Omnicanal

API Envío Omnicanal (7.0)

Download OpenAPI specification:Download

URL: /contacto.php Terms of Service

INTRODUCCION

API de integración de envío OMNICANAL: una misma campaña puede salir por SMS, RCS, Email, WhatsApp, Voz y Push con una lista ORDENADA de canales. Cada destinatario recibe el mensaje por el primer canal de la lista; si la entrega falla, el sistema lo reintenta automáticamente por el siguiente canal, sin intervención del integrador.

AUTENTICACIÓN

En su cuenta de usuario encontrará el Usuario API y el API Token, ambos son necesarios para realizar las peticiones API REST a las funciones de la API. Las Peticiones, por seguridad deben realizarse en POST y con protocolo HTTPS Seguro.



Para utilizar la Autenticación Básica debe incluir una cabecera en las peticiones del tipo: Authorization: Basic Base64StringAPI donde Base64StringAPI es la codificación en Base64 de la cadena UsuarioAPI:APIToken, puede encontrar su Usuario API y API Token en su cuenta de usuario en Tus Datos -> Configurar Cuenta.



Para generar el string codificado en Base64, simplemente genere el string UsuarioApi:APIToken y codifíquelo en base64 mediante cualquier función base64encode.

A TENER EN CUENTA

Requisitos por canal: Cada canal que incluya en la campaña debe estar disponible en su cuenta:
- SMS: siempre disponible. Indique REMITENTE y MENSAJE (admite variables {{NOMBRE}} y links).
- RCS: requiere un Agente RCS activo (IDAGENTE) y una plantilla RCS creada en el panel (IDPLANTILLA).
- WhatsApp: requiere una cuenta WhatsApp Business conectada, un teléfono (IDTELEFONO) y una plantilla APROBADA por Meta (IDPLANTILLA = nombre de la plantilla).
- Email: requiere un DOMINIO propio VALIDADO en su cuenta (no se envía con dominio por defecto), un ASUNTO (obligatorio) y una plantilla (IDPLANTILLA) o un MENSAJEEMAIL. Opcionalmente NOMBREREMITENTE, el nombre que verá el destinatario junto a la dirección; si no se indica, se muestra la propia dirección.
- Voz: llamada con locución Text-to-Speech. Requiere un número propio ACTIVO como REMITENTE (solicitado en el panel), el MENSAJE a locutar y opcionalmente LENGUAJE (idioma del TTS, p.ej. es) y DETECTARCONTESTADOR.
- Push: aviso a los dispositivos vinculados desde el panel (sección Avisos). El destino es el ALIAS del dispositivo: fijo en el canal (REF) o por destinatario (variable REFPUSH en sus VARIABLES). Sin alias, el canal se salta para ese destinatario — nunca se avisa "a todos los aparatos de la cuenta".

Servicio 2FA/OTP: Si lo que necesita es enviar y validar códigos de un solo uso, use la API específica de 2FA/OTP (misma cascada de canales más generación, validación, webhook de estados y anti-abuso). Las peticiones OTP aparecen en el panel en este mismo listado de campañas, etiquetadas como OTP y con su propio filtro.

Validación en PREPRODUCCIÓN: Antes de pasar a producción, realice llamadas con VALIDARCANALES=SI: el sistema verifica la configuración real de cada canal (plantillas en base de datos, dominio validado, teléfono y plantillas aprobadas en Meta...) y devuelve un error descriptivo (Res -4) si algo no está correctamente configurado. Esta validación añade latencia y tiene un límite de peticiones por minuto: en producción use siempre VALIDARCANALES=NO.


Cascada de reintento: El estado de entrega de cada canal lo notifica el propio operador. Cuando un canal reporta un fallo definitivo de entrega para un destinatario, el sistema reintenta automáticamente por el siguiente canal de la lista que no haya fallado ya para ese destino. Puede seguir el estado de cada destinatario (pendiente, enviado, entregado, leído, reenviado por otro canal, fallido) en el panel, en Envío Omnicanal → Campañas y Estadísticas.


Variables: Las variables de las plantillas ({{NOMBRE}}, {{CODIGO}}...) se envían por destinatario en el array VARIABLES. Los nombres no distinguen mayúsculas de minúsculas.


Respuesta de las peticiones: La mayoría de las funciones disponen de un parámetro denominado 'Resp'. Este parámetro define el formato de la respuesta que se devolverá. Puede ser TXT, JSON o XML. Se recomienda siempre definir este parámetro.

basicAuth

Autenticación HTTP Basic. Use su Usuario API como usuario y su API Token como contraseña (los encuentra en su panel, en Tus Datos → Configurar Cuenta). El header resultante es Authorization: Basic base64(UsuarioAPI:APIToken). La mayoría de las librerías HTTP lo construyen automáticamente (curl -u, requests auth=, basic_auth de Ruby, etc.) sin necesidad de codificar el base64 a mano.

Security Scheme Type: HTTP
HTTP Authorization Scheme: basic

Enviar Omnicanal

/EnviarOmnicanal

Crea y lanza una campaña omnicanal: define la lista ORDENADA de canales (CANALES) y los destinatarios (DESTINATARIOS). Cada destinatario sale por el primer canal; si su entrega falla, el sistema reintenta automáticamente por el siguiente canal de la lista.

ATENCIÓN: use VALIDARCANALES=SI en preproducción para verificar la configuración de los canales antes de enviar.

Authorizations:
basicAuth
query Parameters
Canales
required
Array of strings
Example: Canales=[{"Tipo":"sms","Remitente":"MIEMPRESA","Mensaje":"Hola {{NOMBRE}}, su pedido {{PEDIDO}} esta listo"},{"Tipo":"email","Dominio":"miempresa.com","Asunto":"Su pedido {{PEDIDO}}","MensajeEmail":"Hola {{NOMBRE}}, su pedido esta listo."}]

Array JSON ORDENADO de canales. El orden define la cascada: el primer canal es el principal y el resto son los reintentos. Cada tipo de canal solo puede aparecer una vez. Campos por elemento:
Tipo (obligatorio) - sms | rcs | email | whatsapp | voz | push
sms: Remitente (máx. 11 caracteres alfanuméricos) y Mensaje (obligatorio, admite variables {{NOMBRE}}).
rcs: IdAgente e IdPlantilla (numéricos, de su panel).
whatsapp: IdTelefono (phone_id de Meta) e IdPlantilla (nombre de la plantilla aprobada).
email: Dominio (propio y validado, obligatorio), Asunto (obligatorio, admite variables), Remitente (email del dominio; si se omite se usa envios@dominio) e IdPlantilla (plantilla del panel) o MensajeEmail (cuerpo HTML básico).
voz: Remitente (número propio activo, obligatorio), Mensaje (texto a locutar por TTS, admite variables), Lenguaje (idioma del TTS, por defecto es — español) y DetectarContestador (0|1). El Mensaje admite además los marcadores del asistente de voz: (MP3:fichero) inserta un audio de su biblioteca, (PAUSA:segundos) una pausa y (SPELL:texto) deletrea el texto letra a letra.
push: Titulo y/o Mensaje (admiten variables), Ref (alias FIJO del dispositivo vinculado; si el alias va por destinatario, use la variable REFPUSH en sus VARIABLES), Aplicacion (fuente del aviso, slug corto, por defecto api) y Nivel (critico | alto | normal | bajo). Por ejemplo:


                  [
                    { "Tipo": "whatsapp", "IdTelefono": "572863982585983", "IdPlantilla": "aviso_pedido" },
                    { "Tipo": "sms", "Remitente": "MIEMPRESA", "Mensaje": "Hola {{NOMBRE}}, su pedido {{PEDIDO}} está listo" },
                    { "Tipo": "email", "Dominio": "miempresa.com", "Remitente": "avisos@miempresa.com", "Asunto": "Su pedido {{PEDIDO}}", "MensajeEmail": "Hola {{NOMBRE}}, su pedido está listo." }
]
Destinatarios
required
Array of strings
Example: Destinatarios=[{"Nombre":"Pedro Aicart","Telefono":"34600000001","Email":"pedro@ejemplo.com","Variables":[{"Nombre":"PEDIDO","Valor":"A-1234"}]}]

Array JSON con los destinatarios. Cada elemento admite Nombre (opcional), Telefono (internacional sin +, p.ej. 34600000001), Email y Variables (array [{Nombre,Valor}] u objeto plano). Debe indicar teléfono y/o email según los canales configurados: si todos los canales son de móvil (sms/rcs/whatsapp/voz) el teléfono es obligatorio; si el único canal es email, el email es obligatorio. Con canal push, la variable REFPUSH (alias del dispositivo vinculado de ese destinatario) también es un destino válido por sí solo. Por ejemplo:


                  [
                    {
                        "Nombre": "Pedro Aicart",
                        "Telefono": "34600000001",
                        "Email": "pedro@ejemplo.com",
                        "Variables": [ { "Nombre": "PEDIDO", "Valor": "A-1234" } ]
                    }
]
Fecha
string
Example: Fecha=2026-08-01 10:30

Fecha y hora de envío programado en formato YYYY-MM-DD HH:mm (CET/CEST). Si se omite o está vacía, el envío es inmediato.

Intervaloprohibido
Array of strings
Example: Intervaloprohibido=[{"HoraInicio":"22:00","HoraFin":"09:00","Accion":"1"}]

Intervalo horario en el que NO se debe entregar (array de un objeto con HoraInicio, HoraFin y Accion: 1=posponer, 2=cancelar). 00:00-00:00 = sin restricción.

Referenciausuario
string
Example: Referenciausuario=Campania julio

Referencia libre de la campaña para sus listados (máx. 50 caracteres).

Eliminarduplicados
string
Enum: 0 1
Example: Eliminarduplicados=1

1 (por defecto) elimina destinatarios duplicados (mismo móvil o email) dentro de la campaña. 0 los mantiene.

Validarcanales
string
Enum: "NO" "SI"
Example: Validarcanales=NO

SI = valida la configuración REAL de cada canal antes de crear la campaña (agente y plantilla RCS en su cuenta, dominio email validado y plantilla con HTML, cuenta WhatsApp Business con el teléfono registrado y la plantilla APROBADA en Meta). Pensado para PREPRODUCCIÓN: añade latencia y tiene límite de peticiones por minuto (Res -6 si se supera). En producción use NO.

Resp
string
Enum: "TXT" "JSON" "XML"
Example: Resp=JSON

Tipo de respuesta a mostrar como resultado de la llamada.
JSON - La respuesta la obtendrá en JSON
XML - La respuesta la obtendrá en XML
TXT - La respuesta la obtendrá en formato Texto

Request Body schema:

Los parámetros se envían en el cuerpo de la petición POST, como objeto JSON (Content-Type application/json, RECOMENDADO) o como formulario application/x-www-form-urlencoded. En el formato formulario, los parámetros de tipo array u objeto se envían como string JSON-codificado. Los nombres de los parámetros no distinguen mayúsculas de minúsculas. La descripción detallada de cada parámetro está en la sección de parámetros de esta operación.

Canales
required
Array of any
Destinatarios
required
Array of any
Fecha
string
Intervaloprohibido
Array of any
Referenciausuario
string
Eliminarduplicados
string
Validarcanales
string
Resp
string

Responses

Response Schema:
Array
Res
required
integer <int32>

Respuesta de la función solicitada


>0 idEnvio de la campaña omnicanal creada (correlaciona con las estadísticas del panel).
-1 Error de autenticación.
-2 No hay créditos suficientes (obtendrá Necesarios y Cred).
-3 Error en los datos de la llamada (obtendrá un parámetro Error con la descripción).
-4 Canal mal configurado (obtendrá en Error el canal y el motivo; con VALIDARCANALES=SI la comprobación incluye plantillas, dominio y configuración Meta).
-6 Límite de peticiones por minuto de VALIDARCANALES=SI alcanzado.

Error
string

En caso de Res negativo, descripción del problema.

idEnvio
integer

Identificador de la campaña omnicanal (el mismo que Res cuando es correcto).

Destinatarios
integer

Número de destinatarios procesados.

Alta
integer

Destinatarios válidos dados de alta en la campaña.

Duplicados
integer

Destinatarios descartados por duplicados (con ELIMINARDUPLICADOS=1).

Invalidos
integer

Destinatarios descartados por no tener móvil ni email válidos.

Enviados
integer

Destinatarios encolados en su primer canal (0 si la campaña queda programada).

Fallidos
integer

Destinatarios en los que fallaron TODOS los canales al encolar.

Pendientes
integer

Destinatarios que aún no se han intentado (campaña programada o parada por falta de saldo).

SinSaldo
integer

1 si el envío se detuvo por falta de créditos: los Pendientes quedan en espera y la campaña se reintenta automáticamente cada hora (hasta 7 días) en cuanto haya saldo.

CreditosUsados
number

Créditos cobrados hasta ahora en esta campaña (suma de lo cobrado por cada mensaje encolado; solo se cobra el canal por el que realmente se envía cada intento).

Programado
integer

1 si la campaña quedó programada (FECHA futura); el envío lo lanzará el sistema automáticamente.

Cred
number

Créditos disponibles en la cuenta tras la operación.

Request samples

Content type
{
  • "Canales": "[{\"Tipo\":\"sms\",\"Remitente\":\"MIEMPRESA\",\"Mensaje\":\"Hola {{NOMBRE}}, su pedido {{PEDIDO}} esta listo\"},{\"Tipo\":\"email\",\"Dominio\":\"miempresa.com\",\"Asunto\":\"Su pedido {{PEDIDO}}\",\"MensajeEmail\":\"Hola {{NOMBRE}}, su pedido esta listo.\"}]",
  • "Destinatarios": "[{\"Nombre\":\"Pedro Aicart\",\"Telefono\":\"34600000001\",\"Email\":\"pedro@ejemplo.com\",\"Variables\":[{\"Nombre\":\"PEDIDO\",\"Valor\":\"A-1234\"}]}]",
  • "Fecha": "2026-08-01 10:30",
  • "Intervaloprohibido": "[{\"HoraInicio\":\"22:00\",\"HoraFin\":\"09:00\",\"Accion\":\"1\"}]",
  • "Referenciausuario": "Campania julio",
  • "Eliminarduplicados": "1",
  • "Validarcanales": "NO",
  • "Resp": "JSON"
}

Response samples

Content type
[
  • {
    }
]