Una sola API REST para enviar SMS, correos y mensajes de WhatsApp, acortar links,
programar campañas y repartir saldo entre subclientes. Todas las respuestas son JSON.
Inicia sesión para que tus credenciales se carguen automáticamente
en los ejemplos y en la consola de pruebas.
URL basehttps://plataforma.connectus.la
AutenticaciónHeader Authorization: Basic
Formatoapplication/json
CodificaciónUTF-8
Autenticación
Cada request lleva el header Authorization con el ID de tu cuenta y tu
API key unidos por dos puntos y codificados en Base64:
http header
Authorization: Basic SURfREVfQ1VFTlRBOkFQSV9LRVk=
El ID de cuenta y la API key se obtienen en la plataforma, en
Admin → Empresa y cuenta. La key es única por usuario y por cuenta, y todo lo que
hagas con ella queda registrado a nombre de ese usuario.
Trata la API key como una contraseña: nunca la publiques en código de frontend, repositorios o apps móviles.
Si no envías el header, la respuesta es 401 con {"error":"You must submit an API key"}.
Si la key no existe o fue rotada, la respuesta es 401 con {"error":"Invalid or expired API key"}.
Regenerar la key desde Admin → Empresa y cuenta invalida la anterior de inmediato.
Errores
Los errores devuelven un objeto con la clave error (string o arreglo de strings).
Algunos endpoints de WhatsApp agregan code y details para automatizar el manejo.
Código
Significado
200 / 201 / 202
Operación aceptada. 202 indica procesamiento en background.
204
Operación aceptada, sin contenido en la respuesta.
400
Falta un parámetro obligatorio o su formato es inválido.
401
Header Authorization ausente o credenciales inválidas.
403
El producto no está habilitado para la cuenta, o el usuario no tiene el rol requerido.
404
El recurso no existe o pertenece a otra cuenta.
409
Conflicto de estado (por ejemplo, un número de WhatsApp ya conectado).
412
Precondición de negocio no cumplida: saldo insuficiente, número inválido, contenido rechazado.
422
El payload es válido pero los datos no pasan la validación.
502 / 504
Error o timeout del proveedor externo (carrier, SMTP, Meta). Reintentable.
Ojo con los envíos de email y links cortos: algunos rechazos de negocio llegan con
200 y la clave error en el cuerpo. Valida siempre la presencia del
identificador (id, id_sms, short_link) antes de dar el envío por bueno.
General
Verificación de credenciales y datos de la cuenta.
POST/api_v3/testAPI key
Probar credenciales
Devuelve 200 si el header Authorization es válido. Úsalo como health check de tu integración.
Respuestas
200OK
{
"message": "test"
}
401Sin credenciales
{
"error": "You must submit an API key"
}
401Credenciales inválidas
{
"error": "Invalid or expired API key"
}
GET/api_v3/accountAPI key
Datos de la cuenta
Devuelve el registro completo de la cuenta asociada a la API key, incluidos los feature flags de cada producto.
Los flags sms, email_enabled, whatsapp_qr y meta_whatsapp indican qué productos puede usar la cuenta. Si un producto está apagado, sus endpoints responden 403.
Envío individual, OTP, consulta de saldo y reportes de mensajería SMS.
POST/api_v3/sms/send_individualEjecuta de verdadAPI key
Enviar SMS
Envía un SMS a un destinatario. Descuenta saldo del país de destino.
Si no se envía src_number se usa el número marcado como predeterminado de la cuenta. Si no se envía id_delivery, el mensaje se agrupa en el delivery mensual automático de tipo API.
Body
Campo
Tipo
Descripción
dst_number*
string
Número destino en formato internacional, sin + ni espacios.
sms_content*
string
Texto del mensaje.
src_number
integer
Número remitente. Debe pertenecer a la cuenta.
(opcional)
id_delivery
string
id_unique de un delivery existente con id_product = 1 y deliver_at futuro.
(opcional)
id_client
string
id_unique de un subcliente: descuenta de su saldo en vez del saldo libre.
(opcional)
El contenido pasa por el validador anti-scam de la cuenta; si lo rechaza responde 412 con el motivo.
Guarda el id_sms: es el identificador que se usa para consultar el estado.
En cuentas postpago no se valida saldo: el envío sale igual y se factura después.
Los rechazos de id_delivery (no existe, id_product distinto de 1, fecha pasada) salen con 200 y la clave error, no con 4xx: valida la presencia de id_sms.
Respuestas
200Enviado
{
"id_sms": "8f39eacf5c904bf590c1956f52543026"
}
422Falta un campo
{
"error": "Destination number not found"
}
412Sin saldo / número inválido
{
"error": "Your balance for Chile is too low"
}
412Remitente ajeno a la cuenta
{
"error": "The source number is not included in the registered account numbers"
}
403SMS no habilitado
{
"error": "SMS no está habilitado para esta cuenta. Usá el modo de prueba."
}
POST/api_v3/sms/send_otpEjecuta de verdadAPI key
Enviar SMS OTP
Ruta dedicada a códigos de un solo uso: entrega priorizada y sin validación anti-scam.
Requiere que la cuenta tenga habilitado el permiso de envío OTP.
Body
Campo
Tipo
Descripción
dst_number*
string
Número destino en formato internacional.
sms_content*
string
Texto del mensaje, normalmente el código.
src_number
string
Número remitente. Por defecto el primero de la cuenta.
(opcional)
save_content
string
Con valor hash se guarda el contenido como SHA-256 en vez de texto plano.
(opcional)
Usa save_content=hash cuando el OTP no deba quedar legible en los reportes.
A diferencia de send_individual, no valida ni descuenta saldo: el OTP sale aunque la cuenta esté en cero y su consumo no aparece en GET /api_v3/sms/balance.
Estado de entrega de un SMS a partir del id devuelto por el envío.
Parámetros de ruta
Campo
Tipo
Descripción
id*
string
id_sms devuelto por el envío.
Estados frecuentes: NEW, ESME_ROK (aceptado por el carrier), DELIVRD (entregado), UNDELIV (no entregado), EXPIRED, REJECTD, ESME_RINVDSTADR (número inválido).
Requiere que la cuenta esté validada; si no, responde 401 aunque las credenciales sean correctas.
Hoy el estado se consulta sólo por polling. La URL de estado de SMS de Admin → Empresa y cuenta no dispara notificaciones automáticas por cambio de estado: ver el webhook de salida Estado de SMS para el detalle.
Respuestas
200OK
{
"status": "DELIVRD"
}
401Cuenta no validada
{
"error": "Account is not active"
}
404No existe
{
"error": "Not found"
}
GET/api_v3/sms/date_reportAPI key
Reporte por fechas
Lista los SMS salientes de la cuenta en un rango de fechas (máximo 7 días).
Query string
Campo
Tipo
Descripción
begin_date*
date
Fecha inicial YYYY-MM-DD.
end_date*
date
Fecha final YYYY-MM-DD.
El identificador de cada SMS viene en id_sms (el mismo valor que devuelve el envío), no en id_unique.
El rango incluye los dos extremos: end_date entra completo, hasta las 23:59:59.
{
"error": "Delivery with ID b2ef511e53a341bd983c870a71093b6b not found"
}
Email
Envío transaccional de correos, OTP por email y consulta de saldo.
POST/api_v3/email/send_singleEjecuta de verdadAPI key
Enviar email
Encola un correo individual usando un remitente verificado de la cuenta.
El src_email debe existir en la cuenta y estar verificado. Si el destinatario está desuscrito de ese remitente, el envío se registra como FAILED y no se entrega.
Body
Campo
Tipo
Descripción
src_email*
string
Remitente verificado de la cuenta.
dst_email*
string
Destinatario.
subject*
string
Asunto.
email_content*
string
Cuerpo del correo. Acepta HTML.
sender
string
Nombre visible del remitente.
(opcional)
id_client
string
id_unique de un subcliente: descuenta de su saldo.
(opcional)
id_delivery
string
id_unique de un delivery con id_product = 2 y deliver_at futuro.
(opcional)
Este endpoint responde 200 con la clave error en los rechazos de negocio: valida siempre la presencia de id en la respuesta.
Rechazos posibles con 200: Empty source emails, Source email not available (1) y (2), Your balance is insufficient, The free balance is insufficient, Client does not exist, Client has no email balance, The destination email is unsubscribed…, los tres de id_delivery y Error could not be generated.
Los remitentes se dan de alta y verifican en Email → Configuración.
Respuestas
200Encolado
{
"id": "3e794ad2835e40a7a0fb817884f61fc7"
}
200Remitente no disponible
{
"error": "Source email not available (1)"
}
200Sin saldo
{
"error": "Your balance is insufficient"
}
403Email no habilitado
{
"error": "Email no está habilitado para esta cuenta. Usá el modo de prueba."
}
POST/api_v3/email/send_otp_emailEjecuta de verdadAPI key
Enviar email OTP
Envío inmediato vía SMTP de Connectus, pensado para códigos de verificación.
A diferencia de send_single, no encola: entrega al SMTP en la misma request y devuelve el estado real del proveedor.
Body
Campo
Tipo
Descripción
src_email*
string
Remitente verificado de la cuenta.
dst_email*
string
Destinatario.
subject*
string
Asunto.
email_content*
string
Cuerpo del correo. Acepta HTML.
sender
string
Nombre visible del remitente.
(opcional)
Requiere que la cuenta esté en estado Activa para usar el SMTP de Connectus.
Igual que send_single, los rechazos de negocio salen con 200 y la clave error (Empty source emails, Source email not available (1) y (2), saldo insuficiente, destinatario desuscrito): valida siempre la presencia de id.
Respuestas
200Entregado al SMTP
{
"id": "3e794ad2835e40a7a0fb817884f61fc7"
}
200Remitente no disponible
{
"error": "Source email not available (1)"
}
200Sin saldo
{
"error": "Your balance is insufficient"
}
422Rechazado por el proveedor
{
"error": "El correo no fue enviado porque el dominio remitente no tiene DKIM configurado",
"status": "MISSING_DKIM",
"id": "3e794ad2835e40a7a0fb817884f61fc7"
}
GET/api_v3/email/balanceAPI key
Saldo de emails
Saldo total de correos disponibles en la cuenta.
Respuestas
200OK
{
"balance": 48200
}
GET/api_v3/email/:idAPI key
Estado de un email
Estado de un correo a partir del id devuelto por el envío.
Parámetros de ruta
Campo
Tipo
Descripción
id*
string
id devuelto por el envío.
Estados frecuentes: NEW, SENT_TO_SMTP, PENDING, DELIVRD (entregado), OPENED, FAILED, MISSING_DKIM.
Para correos enviados por el SMTP de Connectus el estado se refresca contra el proveedor en el momento de la consulta.
Respuestas
200OK
{
"status": "DELIVRD"
}
404No existe
{
"error": "Not found"
}
Links cortos
Acortador de URLs con conteo de clics, integrable en campañas de SMS y email.
POST/api_v3/short_linkEjecuta de verdadAPI key
Crear link corto
Acorta una URL. Requiere que la cuenta tenga la función habilitada.
Body
Campo
Tipo
Descripción
link*
string
URL completa a acortar.
Respuestas
200Creado
{
"short_link": "https://cnct.us/3f7ac1"
}
200No habilitado
{
"error": "Account short_link not enabled"
}
200Parámetros incorrectos
{
"error": "Wrong parameters"
}
GET/api_v3/short_link/:idAPI key
Eventos de un link
Devuelve el link original y la lista de clics registrados.
Parámetros de ruta
Campo
Tipo
Descripción
id*
string
Identificador corto (lo que va después de cnct.us/).
Estados posibles: NEW (encolado), SENT (entregado al proveedor), NOT_SENT y ERROR. Este canal no reporta entrega al destinatario: no existe un estado DELIVERED.
La ruta acepta GET y POST indistintamente; los parámetros van igual en query string o en el body.
Cuando el mensaje no existe responde 200, no 404: valida la clave status.
Respuestas
200OK
{
"status": "SENT"
}
200No encontrado
{
"error": "Message not found"
}
GET/api_v3/whatsapp/messagesAPI key
Conversación
Últimos 10 mensajes intercambiados entre dos números.
Query string
Campo
Tipo
Descripción
src_number*
string
Número QR de la cuenta.
dst_number*
string
Número del contacto.
La ruta acepta GET y POST indistintamente.
Consulta en vivo al proveedor del número QR, así que es más lenta que el resto de los endpoints.
Canal oficial de WhatsApp: integración nativa con Meta (Tech Provider directo).
GET/api_v3/meta/whatsapp/go_live_statusAPI key
Estado go-live
Checklist de salida a producción más el health check en vivo del número.
Cada item de checks trae code, status y message. Los códigos son connected_number, account_mode, quality_rating, token_health, webhook_health, smoke_test y approved_templates.
{
"error": "Meta onboarding session not found",
"code": "meta_session_not_found"
}
Estadísticas
Agregados de consumo de la plataforma.
GET/api_v3/stats/messages_summaryAPI key
Resumen de mensajes
Totales de SMS y email por año, mes y modalidad de pago.
Métrica agregada de toda la plataforma, no de tu cuenta. Para el consumo propio usa /api_v3/sms/date_report o los reportes del panel.
El rango de años está fijo en el código (2024 y 2025): no acepta parámetros de fecha y no devuelve años posteriores hasta que se actualice el controlador.
Connectus postea a la URL configurada en Admin → Empresa y cuenta el estado de un SMS.
El payload tiene sólo esas dos claves y el estado va en español: PROGRAMADO, EN_COLA, ENVIADO_A_CARRIER, ESPERANDO_RESPUESTA, ENTREGADO, NO_ENTREGABLE o NUMERO_INVALIDO. No incluye src_number ni dst_number.
Hoy no se dispara solo por cada cambio de estado: el camino automático está roto y los envíos que sí salen vienen de procesos batch. Confirmá con soporte antes de basar tu integración en este webhook; mientras tanto, consultá el estado con GET /api_v3/sms/:id.
Responde 200 lo antes posible. Para probar durante el desarrollo puedes usar webhook.site.