🔌 Documentación: API

Integración con su CRM/sistemas. Qué es, cómo funciona y cómo se usa — explicado paso a paso.

Solicitar cotización Ver servicio Ver todos los módulos

🔌 API TelHarbor

Integre SMS, WhatsApp y Click-to-dial en sus sistemas. Base: https://api.telharbor.com/v1

💬

SMSEnviar mensajes de texto. Scopes: sms.send, sms.status

🟢

WhatsAppEnviar mensajes por WhatsApp. Scopes: whatsapp.send, whatsapp.status

📞

Click-to-dialOriginar llamadas en la PBX del cliente. Scope: dial.call

Cada API key la habilita TelHarbor con el/los servicios contratados. Solicite su key al equipo de soporte.

🤔 ¿Qué es un API?

API significa Application Programming Interface (Interfaz de Programación de Aplicaciones). En palabras simples: es una puerta de entrada que permite que su sistema (su CRM, su sitio web, su aplicación) le pida cosas a TelHarbor de forma automática, sin que una persona tenga que hacerlo a mano.

🧑‍💻Usted (su sistema)Quiere enviar un SMS o hacer una llamada

→

🧑‍🍳El API (el mesero)Lleva su pedido y le trae la respuesta

→

🏢TelHarbor (la cocina)Hace el trabajo: envía, llama, registra

Es como un mesero en un restaurante: usted no entra a la cocina; le pide al mesero y él le trae lo que necesita. El API es ese intermediario: usted pide (una solicitud) y recibe una respuesta.

La conversación: solicitud y respuesta

Esto aplica igual para todos los servicios de TelHarbor: SMS, WhatsApp y Click-to-dial. Cambia lo que usted pide y lo que recibe, pero el mecanismo (pedir con su llave → recibir respuesta) es el mismo.

🗺️ ¿Cómo funciona el API de TelHarbor?

Su sistema se conecta solo al API de TelHarbor (nunca directo a la red telefónica ni a la central). TelHarbor valida su llave, aplica los límites de seguridad y ejecuta la acción en el servicio correcto.

Seguridad: su sistema nunca se conecta directo a la central telefónica ni a los proveedores. Todo pasa por el API de TelHarbor, que valida y registra cada solicitud.

📞 Flujo del Click-to-dial (paso a paso)

Con una sola solicitud, TelHarbor primero timbra la extensión del agente y, cuando contesta, marca al destino. El agente nunca digita el número: contesta su teléfono y ya está llamando.

Seguridad para call centers: puede ocultar el número del cliente en la pantalla del agente (solo verá el nombre asignado a la llave). El destino ve el CallerID de la ruta saliente de su PBX, no la de su sistema.

🔑 Autenticación, límites y seguridad

Autentique cada petición con su API key en un header:

X-API-Key: <SU_API_KEY> # o bien: Authorization: Bearer <SU_API_KEY>

IP allowlist: opcionalmente su key se restringe a IPs/CIDR autorizados.
Rate limit por minuto y cuota diaria por key.
Todas las llamadas quedan en el registro de uso (auditoría y facturación).
Scopes: la key solo puede usar los servicios que tenga asignados.

Probar conexión GET /ping

curl -H "X-API-Key: <SU_API_KEY>" https://api.telharbor.com/v1/ping

💬 SMS POST /sms/send

curl -X POST https://api.telharbor.com/v1/sms/send \ -H "X-API-Key: <SU_API_KEY>" -H "Content-Type: application/json" \ -d '{"from":"<SU_NUMERO>","to":"+50688887777","text":"Hola desde TelHarbor"}'

🟢 WhatsApp POST /whatsapp/send

curl -X POST https://api.telharbor.com/v1/whatsapp/send \ -H "X-API-Key: <SU_API_KEY>" -H "Content-Type: application/json" \ -d '{"from":"<SU_NUMERO>","to":"+50688887777","text":"Hola desde TelHarbor"}'

Estado de un mensaje GET /messages?id=123

curl -H "X-API-Key: <SU_API_KEY>" "https://api.telharbor.com/v1/messages?id=123"

📞 Click-to-dial POST /dial/call

Timbra la extensión del agente y, al contestar, marca al destino. El cliente nunca se conecta directo a la PBX: TelHarbor la origina de forma segura vía AMI.

Petición

Campo	Requerido	Descripción
`from`	Sí	Extensión del agente en su PBX (ej. `2072`). Es la que suena primero.
`to`	Sí	Número destino (E.164, ej. `+50688887777`) o una extensión interna.
`caller_id`	No	CallerID a mostrar. Si se omite, aplica el nombre configurado en la llave.

curl -X POST https://api.telharbor.com/v1/dial/call \ -H "X-API-Key: <SU_API_KEY>" -H "Content-Type: application/json" \ -d '{"from":"2072","to":"+50688887777"}'

Respuesta

{"ok":true,"message":"Call originated","call":{"from":"2072","to":"+50688887777","action_id":"thapi_req_..."},"request_id":"req_..."}

La PBX a usar queda asociada a su API key por TelHarbor; no se envía en la petición. Una key solo puede originar en su PBX asignada.

⚠️ Errores

Respuestas de error con ok:false y HTTP correspondiente:

HTTP	Significado
`401`	API key ausente o inválida.
`403`	Sin el scope requerido, IP no permitida, o recurso no propio.
`400`	Parámetros inválidos (ej. `from`/`to`).
`429`	Rate limit o cuota diaria excedida.
`502`	Fallo del proveedor / AMI al procesar.