Documentación de la API de SMS
Documentación de la API de SMS: guía de uso de la plataforma.
Documentación SMS via API GETINCLOUD-SOP-MANUAL-01-SMS
Versión 1
10/03/2026
Respuesta de Ejemplo (JSON) ........................................¡Error! Marcador no definido.
Respuesta de Ejemplo (JSON) ........................................¡Error! Marcador no definido.
Respuesta de Ejemplo (JSON) ........................................¡Error! Marcador no definido.
Respuesta de Ejemplo (JSON) ........................................¡Error! Marcador no definido.
Respuesta de Ejemplo (JSON) ........................................¡Error! Marcador no definido.
Respuesta de Ejemplo (JSON) ........................................¡Error! Marcador no definido.
Respuesta de Ejemplo (JSON) ........................................¡Error! Marcador no definido.
Respuesta de Ejemplo (JSON 200) .................................¡Error! Marcador no definido.
Respuesta de Ejemplo (JSON - 200 OK) .........................¡Error! Marcador no definido.
Envio De Mensajes Sms
Sms Outbound
Enviar mensaje SMS (Send SMS Message)
POST https://api.getincloud.online/raven/v3/messages
Este punto de acceso le permite enviar un único mensaje SMS de salida.
Al enviar mensajes SMS, el tipo de caracteres utilizados en su mensaje afecta directamente cómo se
codifica, cuántos caracteres caben en cada SMS y cómo se segmentan los mensajes durante la entrega.
Los mensajes que incluyen símbolos especiales, letras acentuadas o caracteres no latinos pueden
cambiar a un formato de codificación diferente, lo cual puede reducir el máximo de caracteres por
segmento e aumentar el costo del mensaje.
Parámetros del cuerpo (Body Params)
• from (string, opcional): Especifica el Código Corto (de 1 a 6 dígitos), Código Largo (de 7 dígitos
en adelante), un código corto alfanumérico (ej. EMPRESA) o un número virtual que se utilizará
para originar y enviar el mensaje SMS. Cualquiera de estos códigos aparecerá en el terminal
como el origen del mensaje de texto.
• to (string, requerido): Determina el número de teléfono de destino para su mensaje. Los
números se especifican en formato E.164 (signo '+' y código de país).
• text (string, requerido): El cuerpo del mensaje de texto que se enviará. La longitud máxima de
un texto de mensaje corto es de 160 caracteres utilizando el alfabeto estándar GSM 03.38. Si
utiliza cualquier carácter que no esté en el alfabeto estándar, el mensaje se codificará en
Unicode y se dividirá en segmentos de un máximo de 70 caracteres cada uno. Por ejemplo, si
incluye un emoji en su mensaje y el mensaje tiene 150 caracteres de longitud, se dividirá en tres
segmentos: el primero con 70 caracteres, el segundo con 70 caracteres y el tercero con solo 10
caracteres. Se le cobrará por segmento, no por mensaje.
• type (string, opcional): Tipo de mensaje que desea enviar. Las opciones soportadas son:
• "MT": Mensaje enviado desde el sistema del proveedor de SMS móvil al teléfono móvil
del usuario final.
• "MO": El mensaje se envía desde el teléfono móvil del usuario final al sistema del
proveedor de SMS.
• requestDR (boolean, opcional): Para notificar el estado de la entrega del mensaje a través de un
callback, el requestDR debe ser true.
• externalId (string, opcional): Un identificador único de su sistema para este mensaje. Este ID se
incluirá en las notificaciones de estado de entrega (DLR).
• callbackUrl (string, opcional): Una URL a la que el sistema enviará notificaciones sobre los
cambios de estado del mensaje.
• scheduledAt (string, opcional): Permite programar el mensaje para ser enviado en un momento
futuro. El formato debe ser una cadena de fecha ISO 8601 (ej. 2023-12-31T23:59:59Z).
• connection (string, opcional): Especifica el identificador de la conexión o ruta específica a través
de la cual se debe enviar el mensaje.
• callbacks (array de objetos, opcional): Una lista de objetos de callback para recibir notificaciones
en múltiples URLs.
• clientId (string, opcional): El identificador único del cliente asociado con la solicitud.
• email (string, opcional): Una dirección de correo electrónico asociada con la transacción o para
propósitos de registro.
Respuestas y Códigos de Estado (Responses)
• 202 Accepted: La solicitud ha sido aceptada exitosamente.
• id (string): Identificador único del mensaje generado por el sistema.
• status (string): Estado actual de la solicitud (ej. "Accepted").
• to (string): El número de destino al que se envió el mensaje.
• created_at (string): Marca de tiempo de la creación del mensaje.
• 400 Bad Request: La solicitud es inválida. Esto puede deberse a parámetros faltantes o formatos
de número incorrectos.
• 401 Unauthorized: Error de autenticación. El token Bearer es inválido, falta o ha expirado.
• 500 Internal Server Error: Error interno del servidor al procesar la solicitud.
Estados Específicos de Mensajería
• SEGMENTS_EXCEEDED: Este estado indica que se ha superado el número de segmentos
permitidos. Esto ocurre cuando el mensaje excede el límite de 160 caracteres por segmento,
por lo tanto, el mensaje no se puede enviar. Para resolver este problema, asegúrese de que sus
mensajes SMS no excedan los 1600 caracteres para evitar alcanzar el límite de segmentos.
Ejemplo de Solicitud (cURL)
Bash
curl --request POST \
--url https://api.getincloud.online/raven/v3/messages \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"from": "87070",
"to": "+580000000005",
"text": "¡Obtén un 20% de DESCUENTO en tu próxima compra!",
"type": "MT",
"externalId": "mi-id-personalizado-123",
"connection": "mi-conexion-01",
"clientId": "cliente_abc_789",
"email": "usuario@ejemplo.com"
}
Codificación y Optimización para SMS Multilingües
(Encoding & Optimization for Multilingual SMS)
Al enviar mensajes SMS —ya sea a través de la Plataforma de Comunicaciones, API o SFTP—
comprender cómo funciona la codificación de caracteres es esencial para gestionar la longitud del
mensaje, la segmentación y el costo. Los mensajes que incluyen caracteres especiales o utilizan
alfabetos extendidos —como letras acentuadas, símbolos o escrituras no latinas— requieren una
codificación adicional, lo que puede reducir la cantidad de caracteres permitidos por segmento. Incluso
un solo carácter no estándar puede activar un cambio en el modo de codificación, provocando que el
mensaje se divida en múltiples segmentos y aumentando los costos de entrega.
Esta sección explica cómo la codificación afecta el tamaño del mensaje, cuándo y por qué ocurren los
cambios de codificación, y proporciona recomendaciones prácticas para ayudarte a redactar textos de
mensajes que minimicen la segmentación y optimicen la eficiencia de la entrega.
Codificación de Caracteres SMS
La tecnología SMS tiene estándares de codificación estrictos que determinan cómo se representan y
transmiten los caracteres. Al redactar mensajes —ya sea a través de la interfaz de usuario de la
plataforma o las API— el conjunto de caracteres que utilices afecta:
• El tipo de codificación (GSM-7 o Unicode).
• El límite de longitud del mensaje.
• El costo por mensaje, ya que los mensajes que superan cierta longitud se dividen en múltiples
segmentos.
Comprender cómo funciona la codificación y qué caracteres activan Unicode te ayuda a mantener los
mensajes dentro de un solo segmento y evitar comportamientos inesperados en la facturación o la
entrega.
Codificación GSM-7
El conjunto de caracteres GSM-7 es un estándar de codificación de 7 bits diseñado para SMS. Cuando
tu mensaje contiene solo caracteres cubiertos por GSM-7 (incluyendo su subconjunto "extendido"), el
sistema utiliza GSM-7.
• Para un mensaje totalmente codificado en GSM-7, la longitud máxima es de 160 caracteres (un
segmento).
• Si el mensaje supera los 160 caracteres (usando GSM-7), el sistema lo divide en múltiples
segmentos (SMS concatenados). En ese caso, cada segmento permite normalmente unos 153
caracteres (porque parte de la carga útil del mensaje se utiliza para los metadatos de
concatenación).
Tabla de símbolos GSM-7
La siguiente tabla enumera los caracteres admitidos por el conjunto de caracteres GSM-7. Estos se
reconocen como caracteres SMS estándar, aunque su visualización en el teléfono móvil del destinatario
puede variar según la compatibilidad del terminal y el soporte de fuentes.
@ Δ S P K 0 i P
p £ _ ! Ä 1 A Q
q $ Φ " k r b R
R C æ - = M Ñ m
2 ¥ Γ # ä 3 C S
s è ∧ ¤ ø 4 D T
t é Ω % Æ 5 E u
e ù Π & , 6 F V
v ì Ψ ' < 7 G W
w ò Σ ( L 8 H X
x Ç Θ ) Ö 9 I Y
y L F Ξ I * : J
@ Δ S P K 0 i P
j z Ø E ö S C +
Å ß . > N Ü n ü
É / ? O § o à
Caracteres de escape GSM-7
Los caracteres enumerados a continuación están incluidos en el conjunto de caracteres GSM-7, pero
requieren una secuencia de escape cuando se usan en un mensaje SMS, lo que significa que cada uno
cuenta como dos caracteres para la longitud total del mensaje:
^, {, }, \, [, ], ~, |, €
Codificación Unicode (UCS-2)
Si el mensaje contiene cualquier carácter no compatible con GSM-7, el sistema cambia la codificación
a Unicode (UCS-2).
• Bajo Unicode, el límite de caracteres por segmento cae a unos 70 caracteres. Es decir, al usar el
conjunto de caracteres Unicode, cada carácter se ve como dos caracteres. Esto disminuye la
cantidad de caracteres que puedes poner en tu SMS de 160 a 70.
• Cuando ocurre la concatenación bajo Unicode, cada segmento subsiguiente puede transportar
típicamente aproximadamente 67 caracteres (debido a la sobrecarga de metadatos).
Por lo tanto, un solo carácter que no sea GSM-7 activa el límite de capacidad inferior y puede
aumentar sustancialmente los segmentos y el costo.
GSM-7 vs Unicode (UCS-2)
La elección entre la codificación GSM-7 y Unicode tiene un impacto directo en la segmentación, entrega
y facturación de los mensajes. La siguiente tabla resume las diferencias clave entre los dos estándares
de codificación:
Máx. Caracteres por
Tipo de Conjunto de
Caracteres Segmento Casos de Uso Comunes
Codificación Caracteres
(SMS Único) (Concatenado)
Alfabeto latín básico, Inglés estándar o
dígitos y marcas de idiomas basados en
Gsm-7 160 153
puntuación latín sin acentos ni
seleccionadas. símbolos especiales.
Mensajes que incluyen
Soporta todos los caracteres no latinos,
Unicode (UCS-2) guiones globales, 70 67 letras acentuadas,
símbolos y emojis. emojis o símbolos
complejos.
En la práctica, la codificación se determina automáticamente por los caracteres utilizados en el
mensaje. Tan pronto como se detecta un carácter que no es GSM-7, el sistema cambia a la codificación
Unicode para todo el mensaje.
Recomendaciones de reemplazo
La siguiente tabla enumera caracteres frecuentemente responsables de cambiar a Unicode o de
consumir unidades adicionales en GSM-7, junto con reemplazos recomendados cuando tu objetivo es
permanecer dentro de un solo segmento.
Carácter Descripción Reemplazo Recomendado Ejemplo
Variaciones de "a"
á, à, â, ä, ã, å a “mañana” → “manana”
acentuada
Variaciones de "e"
é, è, ê, ë e “éxito” → “exito”
acentuada
Variaciones de "i"
í, ì, î, ï i “país” → “pais”
acentuada
Variaciones de "o"
ó, ò, ô, ö, õ o “avión” → “avion”
acentuada
ú, ù, û, ü Variaciones de "u" u “tú” → “tu”
Carácter Descripción Reemplazo Recomendado Ejemplo
acentuada
ñ "ñ" española n “niño” → “nino”
ç Cedilla "c" c “façade” → “facade”
€ Símbolo de Euro EUR “€50” → “EUR 50”
–, — En dash / Em dash - Reemplazar “–” con “-”
Comillas curvas (Smart Reemplazar comillas curvas
‘, ’, “, ” ',"
quotes) por rectas
… Elipsis ... Usar tres puntos
Emojis / Eliminar o usar equivalentes “✔ Confirmed” →
Pictogramas o iconos
símbolos de texto “Confirmed”
El uso de equivalentes simples puede alterar ligeramente el tono o el idioma (especialmente en
español). Debes sopesar la legibilidad frente a la optimización de costo/segmento.
Conclusión
• Si tu mensaje está codificado como GSM-7 y permanece por debajo de ~160 caracteres,
normalmente se envía como un segmento.
• Si supera los ~160 caracteres en GSM-7, se enviará como múltiples segmentos (cada uno de
aproximadamente ~153 caracteres). Es decir, cuando un mensaje GSM-7 supera los 160
caracteres, se añaden metadatos de concatenación para unir las partes. Estos metadatos
consumen 3 caracteres por segmento, reduciendo la capacidad disponible de 160 a 153
caracteres. Por ejemplo, un mensaje GSM-7 de 180 caracteres se enviará como 2 segmentos
(157 + 23 = 180).
• Si el mensaje incluye cualquier carácter que no sea GSM-7, la codificación cambia a Unicode
(UCS-2). En Unicode, cada segmento puede contener 67 caracteres útiles, ya que se reservan 3
caracteres para la información de concatenación. Esto significa que el máximo por segmento
disminuye de 160 a 67 caracteres.
• El impacto en el costo es directo: cada segmento adicional es una unidad facturable.
• Ejemplo: Un mensaje de 140 caracteres que usa solo caracteres GSM-7 se enviará como 1
segmento. Si el mismo mensaje incluye un emoji o cualquier carácter no admitido, la
codificación cambia a Unicode. Debido a que cada segmento Unicode contiene 67 caracteres
útiles, el mensaje de 140 caracteres requerirá 3 segmentos (67 + 67 + 6), triplicando
efectivamente el costo de entrega.
• Para campañas de SMS de alto volumen, incluso pequeños aumentos en los segmentos por
mensaje pueden afectar significativamente el presupuesto.
Al comprender qué caracteres activan la codificación Unicode y seguir las mejores prácticas para la
creación de contenido, puedes optimizar la entrega de SMS, manteniendo la claridad en la
comunicación mientras controlas los costos y garantizas una distribución eficiente de los mensajes.
Enviar mensajes SMS por lote (Send Batch SMS Messages)
POST https://api.getincloud.online/raven/v3/messages/batch
Este punto de acceso (endpoint) le permite enviar múltiples mensajes SMS de salida en una sola
solicitud de lote (batch).
Al enviar mensajes SMS, el tipo de caracteres utilizados en su mensaje afecta directamente cómo se
codifica, cuántos caracteres caben en cada SMS y cómo se segmentan los mensajes durante la entrega.
Los mensajes que incluyen símbolos especiales, letras acentuadas o caracteres no latinos pueden
cambiar a un formato de codificación diferente, lo cual puede reducir el máximo de caracteres por
segmento e aumentar el costo del mensaje.
Parámetros del cuerpo (Body Params)
• messages (array de objetos, requerido): Una lista de objetos de mensaje para enviar. Cada
objeto de mensaje admite los siguientes campos:
• from (string, opcional): Especifica el Código Corto (de 1 a 6 dígitos), Código Largo (de 7
dígitos en adelante), un código corto alfanumérico (ej. EMPRESA) o un número virtual
que se utilizará para originar y enviar el mensaje SMS. Cualquiera de estos códigos
aparecerá en el terminal como el origen del mensaje de texto.
• to (string, requerido): Determina el número de teléfono de destino para su mensaje. Los
números se especifican en formato E.164 (signo '+' y código de país).
• text (string, requerido): El cuerpo del mensaje de texto que se enviará. La longitud
máxima de un texto de mensaje corto es de 160 caracteres utilizando el alfabeto
estándar GSM 03.38. Si utiliza cualquier carácter que no esté en el alfabeto estándar, el
mensaje se codificará en Unicode y se dividirá en segmentos de un máximo de 70
caracteres cada uno. Se le cobrará por segmento, no por mensaje.
• type (string, opcional): Tipo de mensaje que desea enviar. Las opciones soportadas son:
"MT" (Mobile Terminated) o "MO" (Mobile Originated).
• requestDR (boolean, opcional): Para notificar el estado de la entrega del mensaje a
través de un callback, el requestDR debe ser true.
• externalId (string, opcional): Un identificador único de su sistema para este mensaje.
Este ID se incluirá en las notificaciones de estado de entrega (DLR).
• callbackUrl (string, opcional): Una URL a la que el sistema enviará notificaciones sobre
los cambios de estado del mensaje.
• scheduledAt (string, opcional): Permite programar el mensaje para ser enviado en un
momento futuro. El formato debe ser una cadena de fecha ISO 8601 (ej. 2023-12-
31T23:59:59Z).
• connection (string, opcional): Especifica el identificador de la conexión o ruta específica
a través de la cual se debe enviar el mensaje.
• callbacks (array de objetos, opcional): Una lista de objetos de callback para recibir
notificaciones en múltiples URLs.
• clientId (string, opcional): El identificador único del cliente asociado con la solicitud.
• email (string, opcional): Una dirección de correo electrónico asociada con la transacción
o para propósitos de registro.
Estados de respuesta (Response Statuses)
• 202 Accepted: La solicitud de lote ha sido aceptada para su procesamiento.
• batch_id (string): Identificador único para el lote de mensajes.
• status (string): Estado de la solicitud de lote.
• total_messages (integer): Número total de mensajes procesados en el lote.
• 400 Bad Request: La solicitud es inválida debido a errores de formato o parámetros requeridos
faltantes.
• 401 Unauthorized: Error de autenticación. El token Bearer proporcionado es inválido o ha
expirado.
• 413 Payload Too Large: El lote de mensajes excede el límite de tamaño permitido por solicitud.
• 500 Internal Server Error: Se produjo un error inesperado en el servidor.
Ejemplo de Solicitud (cURL)
Bash
curl --request POST \
--url https://api.getincloud.online/raven/v3/messages/batch \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"messages": [
{
"from": "87070",
"to": "+580000000001",
"text": "Hola, este es el primer mensaje del lote.",
"externalId": "batch-item-001"
},
{
"from": "87070",
"to": "+580000000002",
"text": "Hola, este es el segundo mensaje del lote.",
"externalId": "batch-item-002"
}
]
}
'
Información del mensaje SMS (SMS Message Information)
GET https://api.getincloud.online/raven/v3/messages/{id}
Este punto de acceso (endpoint) le permite recuperar información sobre un mensaje SMS de salida
enviado previamente. Es necesario proporcionar el identificador único (id) del mensaje SMS.
Parámetros de la ruta (Path Params)
• id (string, requerido): El identificador único del mensaje SMS que se desea consultar. Este es el
ID que se devuelve en la respuesta tras enviar un mensaje con éxito.
Parámetros de la consulta (Query Params)
(En este endpoint específico de consulta por ID, no se suelen requerir parámetros adicionales en la URL
más allá del identificador en la ruta).
Respuestas y Códigos de Estado (Responses)
• 200 OK: La solicitud fue exitosa y se devuelve la información del mensaje.
• id (string): Identificador único del mensaje.
• from (string): El código o número desde el cual se originó el mensaje.
• to (string): El número de teléfono de destino en formato E.164.
• text (string): El contenido del mensaje enviado.
• status (string): El estado actual del mensaje (ej. Delivered, Sent, Failed, Buffered).
• segments (integer): El número de segmentos en los que se dividió el mensaje para su
entrega.
• externalId (string): El identificador personalizado proporcionado por el cliente en la
solicitud original, si existe.
• clientId (string): El ID del cliente asociado a la transacción.
• created_at (string): Fecha y hora en que se creó el mensaje (formato ISO 8601).
• updated_at (string): Fecha y hora de la última actualización de estado del mensaje.
• error_code (string, opcional): Si el mensaje falló, indica el código de error específico
proporcionado por el operador.
• 401 Unauthorized: Error de autenticación. El token proporcionado no es válido o ha expirado.
• 404 Not Found: No se encontró ningún mensaje con el id proporcionado.
• 500 Internal Server Error: Error interno del servidor al intentar recuperar la información.
Notas Técnicas y Advertencias
• Retención de Datos: Tenga en cuenta que la información del mensaje puede estar sujeta a
políticas de retención. Los mensajes muy antiguos podrían no estar disponibles para su consulta
a través de este endpoint.
• Actualización de Estados: El estado devuelto refleja la última actualización recibida del
operador de red. En algunos casos, puede haber una breve latencia entre la entrega real y la
actualización en el sistema.
Ejemplo de Solicitud (cURL)
Bash
curl --request GET \
--url https://api.getincloud.online/raven/v3/messages/550e8400-e29b-41d4-a716-446655440000 \
--header 'accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY'
Codigos
Listar Códigos de Usuario (List User Codes)
GET https://api.getincloud.online/raven/v3/codes
Este punto de acceso (endpoint) le permite recuperar una lista de todos los códigos (códigos cortos,
números largos o IDs alfanuméricos) asociados con su cuenta.
Parámetros de la consulta (Query Params)
• type (string, opcional): Filtra los códigos por su tipo. Los valores comunes incluyen
SHORT_CODE, LONG_CODE o ALPHANUMERIC.
• status (string, opcional): Filtra los códigos por su estado operativo (ej. ACTIVE, INACTIVE).
• country (string, opcional): Filtra los códigos asociados a un país específico utilizando el código
de país ISO (ej. US, VE, CO).
Encabezados (Headers)
• Authorization (string, requerido): Token de portador para la autenticación. Ejemplo: Bearer
<Tu_Token>.
• accept (string, opcional): application/json.
Respuestas (Responses)
200 OK
La solicitud fue exitosa. Devuelve una lista de códigos asociados al usuario.
Cuerpo de la respuesta (JSON):
• codes (array de objetos): Una lista de códigos disponibles.
• id (string): El identificador único del código en el sistema.
• code (string): El valor real del código (ej. el número 87070).
• type (string): El tipo de código (ej. SHORT_CODE).
• country (string): El país al que pertenece el código.
• status (string): El estado del código.
• capabilities (array de cadenas): Las funciones admitidas por este código (ej. SMS, MMS,
Voice).
401 Unauthorized
Error de autenticación. El token proporcionado es inválido o ha expirado.
Json
{
"error": "Unauthorized"
}
500 Internal Server Error
Ocurrió un error inesperado en el servidor al intentar recuperar la lista de códigos.
Notas Técnicas
Este endpoint es útil para identificar qué remitentes (from) están disponibles para su uso al enviar
mensajes a través de los puntos de acceso de mensajería. Asegúrese de utilizar un código que coincida
con el país de destino de sus destinatarios para garantizar las mejores tasas de entrega.
Ejemplo de Solicitud (cURL)
Bash
curl --request GET \
--url https://api.getincloud.online/raven/v3/codes \
--header 'accept: application/json' \
--header 'Authorization: Bearer <TU_TOKEN>'
Listar Conexiones (List Connections)
GET https://api.getincloud.online/raven/v3/connections
Este punto de acceso (endpoint) le permite recuperar una lista de todas las conexiones (rutas o
proveedores vinculados) disponibles en su cuenta. Estas conexiones representan los canales técnicos
configurados para el envío de mensajes.
Parámetros de la consulta (Query Params)
• status (string, opcional): Filtra las conexiones por su estado actual. Los valores permitidos son
ACTIVE (Activa) o INACTIVE (Inactiva).
• channel (string, opcional): Filtra las conexiones según el canal de comunicación. Ejemplo: sms,
whatsapp, email.
Encabezados (Headers)
• Authorization (string, requerido): Token de portador necesario para autenticar la solicitud.
Formato: Bearer <TU_TOKEN>.
• accept (string, opcional): application/json.
Respuestas (Responses)
200 OK
La solicitud se procesó correctamente y se devuelve la lista de conexiones.
Cuerpo de la respuesta (JSON):
• connections (array de objetos): Una lista que contiene los detalles de cada conexión.
• id (string): El identificador único de la conexión. Este ID puede utilizarse en el parámetro
connection al enviar un mensaje.
• name (string): El nombre descriptivo de la conexión.
• channel (string): El canal de mensajería asociado (ej. sms).
• status (string): El estado operativo de la conexión.
• config (objeto): Información de configuración técnica específica de la conexión.
401 Unauthorized
Fallo en la autenticación debido a un token inválido, inexistente o expirado.
Json
{
"error": "Unauthorized"
}
500 Internal Server Error
Error interno en el servidor al intentar procesar la solicitud de lista de conexiones.
Notas Técnicas
El identificador obtenido en el campo id de este endpoint es el que debe utilizarse en el parámetro
opcional connection de las APIs de envío de mensajes (/messages o /messages/batch). Esto permite
forzar el envío a través de una ruta específica si su cuenta dispone de múltiples proveedores
configurados.
Ejemplo de Solicitud (cURL)
Bash
curl --request GET \
--url https://api.getincloud.online/raven/v3/connections \
--header 'accept: application/json' \
--header 'Authorization: Bearer <TU_TOKEN>'
Recepcion De Mensajes Sms
Sms Inbound
Reenvio
Crear Proceso de Reenvío (Create Forward Process)
POST https://api.getincloud.online/raven/v3/forward-processes
Este punto de acceso (endpoint) le permite crear un nuevo proceso de reenvío. Un proceso de reenvío
define cómo deben manejarse y redirigirse los mensajes entrantes (MO) según criterios específicos,
como palabras clave o números de origen.
Parámetros del cuerpo (Body Params)
• name (string, requerido): Un nombre descriptivo para identificar el proceso de reenvío.
• origin (string, requerido): El código corto, número largo o ID alfanumérico al que llegarán los
mensajes entrantes.
• keyword (string, opcional): La palabra clave específica que activará este proceso de reenvío. Si
se deja en blanco, el proceso puede actuar como un manejador por defecto para el origen.
• targetUrl (string, requerido): La URL del webhook a la que se reenviarán los datos del mensaje
entrante.
• type (string, opcional): El tipo de proceso de reenvío. Los valores comunes incluyen HTTP_POST,
HTTP_GET o EMAIL.
• status (string, opcional): El estado inicial del proceso. Por defecto es ACTIVE.
• externalId (string, opcional): Un identificador único de su sistema para este proceso de reenvío.
• clientId (string, opcional): El identificador único del cliente asociado con este proceso.
• email (string, opcional): Una dirección de correo electrónico para recibir notificaciones
relacionadas con este proceso de reenvío.
• callbackUrl (string, opcional): Una URL adicional para recibir confirmaciones de procesamiento
del reenvío.
Respuestas (Responses)
201 Created
El proceso de reenvío se ha creado con éxito.
Cuerpo de la respuesta (JSON):
• id (string): El identificador único asignado al nuevo proceso de reenvío.
• name (string): El nombre del proceso creado.
• origin (string): El origen configurado.
• keyword (string): La palabra clave asignada.
• status (string): El estado actual del proceso.
• created_at (string): Marca de tiempo de la creación (formato ISO 8601).
400 Bad Request
La solicitud es inválida. Esto puede ocurrir si faltan campos obligatorios o si el origen/palabra clave ya
están en uso por otro proceso.
Json
{
"error": "Keyword already in use for this origin"
}
401 Unauthorized
Fallo en la autenticación. El token Bearer es inválido o no tiene permisos para crear procesos en este
entorno.
500 Internal Server Error
Ocurrió un error inesperado en el servidor durante la creación del proceso.
Notas Técnicas
• Prioridad de Palabras Clave: Si existen múltiples procesos para el mismo origen, el sistema
priorizará la coincidencia exacta de la keyword.
• Seguridad del Webhook: Asegúrese de que su targetUrl esté preparada para recibir peticiones
POST con un cuerpo JSON que contiene los detalles del mensaje entrante (remitente, texto,
marca de tiempo).
Ejemplo de Solicitud (cURL)
Bash
curl --request POST \
--url https://api.getincloud.online/raven/v3/forward-processes \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer <TU_TOKEN>' \
--data '
{
"name": "Reenvío de Promociones",
"origin": "87070",
"keyword": "PROMO",
"targetUrl": "https://mi-servidor.com/webhook/sms-mo",
"type": "HTTP_POST",
"externalId": "ext-proc-001",
"clientId": "client_123"
}
'
Verificar uso de palabra clave (Check Keyword Usage)
POST https://api.getincloud.online/raven/v3/forward-processes/keyword-usage
Este punto de acceso (endpoint) le permite verificar si una palabra clave específica ya está siendo
utilizada por un proceso de reenvío para un origen determinado. Esto es útil para validar la
disponibilidad antes de intentar crear un nuevo proceso de reenvío.
Parámetros del cuerpo (Body Params)
• origin (string, requerido): El código corto, número largo o ID alfanumérico que desea consultar.
• keyword (string, requerido): La palabra clave cuya disponibilidad desea verificar en el origen
especificado.
• clientId (string, opcional): El identificador único del cliente para filtrar la búsqueda dentro de un
contexto de cliente específico.
• externalId (string, opcional): Un identificador externo relacionado con la consulta.
Respuestas (Responses)
200 OK
La consulta se realizó con éxito. La respuesta indica si la palabra clave está en uso.
Cuerpo de la respuesta (JSON):
• isUsed (boolean): Devuelve true si la palabra clave ya está asignada a un proceso de reenvío
para ese origen, o false si está disponible.
• processId (string, opcional): Si isUsed es true, este campo devuelve el ID del proceso de reenvío
que está utilizando actualmente la palabra clave.
• name (string, opcional): El nombre del proceso de reenvío existente, si aplica.
400 Bad Request
La solicitud es inválida. Esto puede ocurrir si faltan los parámetros requeridos origin o keyword.
Json
{
"error": "Missing required parameters: origin, keyword"
}
401 Unauthorized
Error de autenticación. El token proporcionado no es válido, falta o ha expirado.
500 Internal Server Error
Ocurrió un error inesperado en el servidor al intentar verificar el uso de la palabra clave.
Notas Técnicas
• Sensibilidad a mayúsculas/minúsculas: Por lo general, las palabras clave no distinguen entre
mayúsculas y minúsculas en el sistema, pero se recomienda realizar la verificación en el formato
exacto en que planea registrarla.
• Disponibilidad: Una palabra clave se considera "en uso" solo si existe un proceso de reenvío
activo o pausado vinculado a ella.
Ejemplo de Solicitud (cURL)
Bash
curl --request POST \
--url https://api.getincloud.online/raven/v3/forward-processes/keyword-usage \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer <TU_TOKEN>' \
--data '
{
"origin": "87070",
"keyword": "AYUDA",
"clientId": "client_abc_123"
}
'
Actualizar Proceso de Reenvío (Update Forward Process)
PUT https://api.getincloud.online/jacaerys/v1/forwards/{id}
Este punto de acceso permite modificar la configuración de un proceso de reenvío existente. Al
actualizar un proceso de reenvío, puede cambiar los criterios de activación (como palabras clave) o el
destino donde se enviarán los mensajes entrantes.
Parámetros de la Ruta (Path Params)
• id (string, requerido): El identificador único del proceso de reenvío que se desea actualizar.
Parámetros del Cuerpo (Body Params)
• name (string, opcional): El nombre descriptivo del proceso de reenvío.
• origin (string, opcional): El código corto o número largo asociado al proceso.
• keyword (string, opcional): La palabra clave específica que activa el reenvío.
• targetUrl (string, opcional): La URL del servidor (webhook) donde enviará la información del
mensaje entrante.
• type (string, opcional): El tipo de acción o protocolo utilizado para el reenvío (ej. HTTP_POST).
• status (string, opcional): El estado del proceso. Valores permitidos: ACTIVE, INACTIVE, PAUSED.
• externalId (string, opcional): Un identificador único de su propio sistema para este proceso.
• clientId (string, opcional): El identificador único del cliente asociado con la solicitud.
• email (string, opcional): Una dirección de correo electrónico asociada con el proceso para
propósitos de registro o notificación.
• callbackUrl (string, opcional): Una URL adicional para recibir notificaciones de eventos
relacionados con este proceso.
Bloque de Respuestas y Códigos de Estado (Responses)
• 200 OK: La solicitud se completó con éxito.
• id (string): ID del proceso de reenvío.
• status (string): Estado actual tras la actualización.
• updated_at (string): Fecha y hora de la última modificación.
• 400 Bad Request: La solicitud es inválida. Puede deberse a parámetros mal formateados o
campos obligatorios faltantes en la estructura del JSON.
• 401 Unauthorized: No se pudo autenticar la solicitud. El token Bearer o JWT es inválido, falta o
ha expirado.
• 403 Forbidden: El usuario no tiene permisos suficientes para realizar esta acción sobre el recurso
especificado.
• 404 Not Found: El proceso de reenvío con el id proporcionado no existe en el sistema.
• 409 Conflict: Ocurre cuando se intenta actualizar un proceso con una combinación de origin y
keyword que ya está siendo utilizada por otro proceso activo. El sistema no permite duplicidad
en estas reglas.
• 500 Internal Server Error: Ocurrió un error inesperado en el servidor.
Ejemplo de Solicitud (cURL)
Bash
curl --request PUT \
--url https://api.getincloud.online/jacaerys/v1/forwards/550e8400-e29b-41d4-a716-446655440000 \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--data '
{
"name": "Update Promo Forward",
"keyword": "OFERTA",
"status": "ACTIVE",
"clientId": "client_99",
"email": "soporte@empresa.com",
"externalId": "ext-987"
}
'
Nota sobre Codificación y Costos:
Aunque este endpoint es para configuración de reenvío, recuerde que los mensajes que se procesen a
través de este sistema están sujetos a las reglas de codificación GSM-7 y Unicode. Si el reenvío implica
una respuesta automática, el uso de caracteres especiales fuera del estándar GSM-7 reducirá el límite
de caracteres a 70 por segmento, afectando el costo final.
Información del Proceso de Reenvío (Forward Process
Information)
GET https://api.getincloud.online/jacaerys/v1/forwards/{id}
Este punto de acceso (endpoint) permite recuperar los detalles completos y la configuración actual de
un proceso de reenvío específico utilizando su identificador único.
Parámetros de la Ruta (Path Params)
• id (string, requerido): El identificador único del proceso de reenvío que se desea consultar.
Parámetros de Consulta (Query Params)
• (No se especifican parámetros de consulta adicionales para este endpoint).
Encabezados (Headers)
• Authorization (string, requerido): Token de portador necesario para la autenticación. Formato:
Bearer <YOUR_TOKEN>.
• accept (string, opcional): application/json.
Cuerpo de la Respuesta (Response Body)
Cuando la solicitud es exitosa, el objeto JSON de respuesta contiene los siguientes campos:
• id (string): Identificador único del proceso de reenvío.
• name (string): Nombre descriptivo asignado al proceso.
• origin (string): El código corto (shortcode), número largo (longcode) o ID alfanumérico
configurado para recibir los mensajes.
• keyword (string): La palabra clave específica que activa este proceso. Si está vacío, actúa como
capturador general del origen.
• targetUrl (string): La URL del webhook (Callback URL) donde se redirigen los mensajes entrantes
(Mo).
• type (string): El protocolo o tipo de acción definido (ej. HTTP_POST).
• status (string): El estado operativo actual del proceso (ej. ACTIVE, INACTIVE, PAUSED).
• externalId (string): Identificador personalizado proporcionado por el usuario para integración
con sistemas externos.
• clientId (string): Identificador único del cliente al que pertenece el proceso.
• email (string): Dirección de correo electrónico asociada para registros o alertas.
• callbackUrl (string): URL de retorno adicional configurada para el seguimiento de eventos.
• created_at (string): Fecha y hora de creación del proceso en formato ISO 8601.
• updated_at (string): Fecha y hora de la última modificación en formato ISO 8601.
Bloque de Respuestas: Códigos de Estado HTTP
• 200 OK: La solicitud fue exitosa. Se devuelve el objeto JSON con la configuración del proceso.
• 400 Bad Request: La solicitud es inválida o el formato del id es incorrecto.
• 401 Unauthorized: Error de autenticación. El token proporcionado es inválido, ha expirado o no
se incluyó en el encabezado.
• 403 Forbidden: El usuario no tiene permisos para acceder a la información de este proceso de
reenvío específico.
• 404 Not Found: No existe un proceso de reenvío con el id suministrado.
• 500 Internal Server Error: Se produjo un error inesperado en el servidor al procesar la consulta.
Notas Técnicas y Advertencias
• Fidelidad de Datos: La información devuelta representa la configuración en tiempo real del
sistema. Cualquier cambio realizado mediante el método PUT se reflejará inmediatamente en
esta consulta.
• Seguridad: Asegúrese de que las credenciales utilizadas en el encabezado Authorization
correspondan al propietario del proceso o a un administrador con privilegios suficientes.
Ejemplos de Código
Solicitud (cURL)
Bash
curl --request GET \
--url https://api.getincloud.online/jacaerys/v1/forwards/550e8400-e29b-41d4-a716-446655440000 \
--header 'accept: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN'
Respuesta Exitosa (JSON - 200 OK)
Json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Proceso de Reenvío de Soporte",
"origin": "87070",
"keyword": "AYUDA",
"targetUrl": "https://api.tuempresa.com/webhook/sms",
"type": "HTTP_POST",
"status": "ACTIVE",
"externalId": "ext-98765",
"clientId": "client_001",
"email": "tecnico@empresa.com",
"callbackUrl": "https://api.tuempresa.com/log",
"created_at": "2023-10-01T10:00:00Z",
"updated_at": "2023-10-15T14:30:00Z"
}
Respuesta de Error (JSON - 404 Not Found)
Json
{
"error": "Not Found",
"message": "Forward process with the specified ID does not exist."
}
Listar Procesos de Reenvío (List Forward Processes)
GET https://api.getincloud.online/jacaerys/v1/forwards
Este punto de acceso (endpoint) le permite recuperar una lista de todos los procesos de reenvío
configurados en su cuenta. Puede utilizar parámetros de consulta para filtrar los resultados según el
origen, el estado o el cliente.
Parámetros de la Consulta (Query Params)
• origin (string, opcional): Filtra la lista de procesos de reenvío por un código corto, número largo
o ID alfanumérico específico.
• status (string, opcional): Filtra los procesos por su estado operativo. Los valores permitidos son
ACTIVE, INACTIVE o PAUSED.
• clientId (string, opcional): Filtra los procesos asociados a un identificador de cliente específico.
• page (integer, opcional): El número de página para la paginación de los resultados. Por defecto
es 1.
• limit (integer, opcional): El número de registros que se devolverán por página. Por defecto es
10.
Encabezados (Headers)
• Authorization (string, requerido): Token de portador (Bearer token) necesario para la
autenticación de la solicitud. Formato: Bearer <TU_TOKEN>.
• accept (string, opcional): application/json.
Bloque de Respuestas: Códigos de Estado HTTP
• 200 OK: La solicitud fue exitosa. Devuelve un objeto que contiene la lista de procesos de reenvío
y metadatos de paginación.
• items (array de objetos): Lista de procesos de reenvío encontrados. Cada objeto
contiene:
• id (string): Identificador único del proceso.
• name (string): Nombre del proceso.
• origin (string): Código de origen.
• keyword (string): Palabra clave asignada.
• targetUrl (string): URL de reenvío.
• status (string): Estado actual.
• externalId (string): Identificador de sistema externo.
• clientId (string): ID del cliente.
• email (string): Email de contacto.
• created_at (string): Fecha de creación.
• meta (objeto): Información de paginación.
• totalItems (integer): Total de registros encontrados.
• itemCount (integer): Número de registros en la página actual.
• itemsPerPage (integer): Límite de registros por página.
• totalPages (integer): Total de páginas disponibles.
• currentPage (integer): Página actual.
• 400 Bad Request: La solicitud es inválida. Esto puede deberse a parámetros de consulta mal
formateados.
• 401 Unauthorized: No autorizado. El token proporcionado es inválido, falta o ha expirado.
• 403 Forbidden: Prohibido. El usuario no tiene permisos suficientes para listar los procesos de
este entorno.
• 500 Internal Server Error: Error interno del servidor al intentar recuperar la lista de procesos.
Notas Técnicas y Advertencias
• Paginación: Se recomienda encarecidamente utilizar los parámetros page y limit para manejar
grandes volúmenes de datos y evitar latencias en la respuesta.
• Filtros Combinados: Puede combinar múltiples filtros (ej. origin y status) para obtener una lista
más específica de sus procesos de reenvío.
Ejemplo de Solicitud (cURL)
Bash
curl --request GET \
--url 'https://api.getincloud.online/jacaerys/v1/forwards?status=ACTIVE&limit=5' \
--header 'accept: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN'
Procesos
Verificar Disponibilidad de Palabra Clave (Check Keyword
Availability)
POST https://api.getincloud.online/jacaerys/v1/forwards/keyword-validation
Este punto de acceso (endpoint) le permite verificar si una palabra clave específica está disponible para
ser utilizada en un origen determinado antes de intentar crear un proceso de reenvío. A diferencia de
otros métodos de verificación, este se centra en la validación lógica y la disponibilidad en tiempo real
dentro del inventario del cliente.
Parámetros del Cuerpo (Body Params)
• origin (string, requerido): El código corto (short code), número largo (long code) o ID
alfanumérico que desea validar.
• keyword (string, requerido): La palabra clave específica que desea verificar.
• clientId (string, opcional): El identificador único del cliente asociado con la solicitud.
• externalId (string, opcional): Un identificador único de su sistema para esta solicitud de
validación.
• email (string, opcional): Dirección de correo electrónico asociada para propósitos de auditoría
o registro.
• callbackUrl (string, opcional): URL para recibir una respuesta asíncrona si el sistema requiere
una validación extendida.
Bloque de Respuestas: Códigos de Estado HTTP
• 200 OK: La solicitud de validación se procesó correctamente.
• available (boolean): Indica si la palabra clave se puede usar (true) o no (false).
• message (string): Descripción detallada del resultado de la validación.
• 400 Bad Request: La solicitud es inválida. Esto ocurre si faltan parámetros obligatorios como
origin o keyword, o si el formato de los mismos es incorrecto.
• 401 Unauthorized: Error de autenticación. El token Bearer es inválido, falta o ha expirado.
• 403 Forbidden: El usuario no tiene permisos para realizar validaciones en el origen especificado
o el acceso está restringido para su clientId.
• 404 Not Found: El origen especificado no existe o no está asignado a su cuenta.
• 409 Conflict: La palabra clave ya existe y está asignada de forma exclusiva, lo que genera un
conflicto de duplicidad inmediata.
• 500 Internal Server Error: Ocurrió un error inesperado en el servidor durante el proceso de
validación.
Notas Técnicas y Advertencias
• Reglas de Sintaxis: Las palabras clave deben cumplir con las regulaciones locales del país del
origen. Por ejemplo, algunas regiones prohíben palabras clave relacionadas con contenido para
adultos o juegos de azar.
• Fidelidad Textual sobre Codificación: Al igual que en todos los servicios de mensajería, recuerde
que si la palabra clave contiene caracteres especiales (acentos, símbolos no GSM), el
procesamiento del mensaje entrante relacionado podría verse afectado por la codificación
Unicode, aunque esto es más crítico en el envío de mensajes (MT) que en la recepción y
validación de palabras clave.
• Latencia de Registro: Una vez que una palabra clave es validada como disponible, se recomienda
proceder con la creación del proceso de reenvío de inmediato para evitar que otro usuario la
reserve.
Ejemplos de Código
Solicitud (cURL)
Bash
curl --request POST \
--url https://api.getincloud.online/jacaerys/v1/forwards/keyword-validation \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--data '
{
"origin": "87070",
"keyword": "OFERTA",
"clientId": "client_abc_123",
"externalId": "val-9988",
"email": "dev@empresa.com"
}
'
Respuesta de Ejemplo (JSON - 200 OK)
Json
{
"available": true,
"message": "Keyword is available for the specified origin.",
"externalId": "val-9988"
}
Respuesta de Ejemplo (JSON - 409 Conflict)
Json
{
"available": false,
"message": "Keyword is already in use by another process.",
"error_code": "KEYWORD_ALREADY_EXISTS"
}
Pausar Proceso de Reenvío (Pause Forward Process)
PATCH https://api.getincloud.online/jacaerys/v1/forwards/{id}/pause
Este punto de acceso (endpoint) permite suspender temporalmente la ejecución de un proceso de
reenvío específico. Cuando un proceso está pausado, los mensajes entrantes (MO) que coincidan con
los criterios (origen/palabra clave) no serán redirigidos a la targetUrl configurada hasta que el proceso
sea reanudado.
Parámetros de la Ruta (Path Params)
• id (string, requerido): El identificador único del proceso de reenvío que se desea pausar.
Parámetros del Cuerpo (Body Params)
• externalId (string, opcional): Un identificador único de su sistema para rastrear esta solicitud de
cambio de estado.
• clientId (string, opcional): El identificador único del cliente asociado con la solicitud.
• email (string, opcional): Dirección de correo electrónico asociada para propósitos de
notificación o auditoría del cambio de estado.
• callbackUrl (string, opcional): URL para recibir una notificación una vez que el estado del proceso
haya sido actualizado a pausado.
Bloque de Respuestas: Códigos de Estado HTTP
• 200 OK: La solicitud de pausa se procesó con éxito.
• id (string): ID del proceso de reenvío.
• status (string): El nuevo estado del proceso (ej. PAUSED).
• updated_at (string): Fecha y hora de la actualización en formato ISO 8601.
• 400 Bad Request: La solicitud es inválida. Esto puede ocurrir si el id tiene un formato incorrecto
o si el cuerpo de la solicitud contiene errores de sintaxis.
• 401 Unauthorized: Error de autenticación. El token Bearer es inválido, ha expirado o no se
incluyó en la solicitud.
• 403 Forbidden: El usuario no tiene permisos suficientes para modificar el estado de este proceso
de reenvío.
• 404 Not Found: No se encontró ningún proceso de reenvío con el id proporcionado.
• 409 Conflict: El proceso no puede ser pausado porque ya se encuentra en un estado que impide
esta acción (ej. ya está pausado o ha sido eliminado).
• 500 Internal Server Error: Ocurrió un error inesperado en el servidor al intentar pausar el
proceso.
Notas Técnicas y Advertencias
• Impacto en el Tráfico Entrante: Al pausar un proceso, cualquier mensaje entrante que llegue
durante este periodo no será procesado retroactivamente una vez que se reanude. El sistema
simplemente ignorará las coincidencias mientras el estado sea PAUSED.
• Fidelidad Textual: Al igual que con otros cambios de estado, esta acción queda registrada en los
logs de auditoría de la plataforma, asociando el clientId y el externalId si fueron proporcionados.
Ejemplos de Código
Solicitud (cURL)
Bash
curl --request PATCH \
--url https://api.getincloud.online/jacaerys/v1/forwards/550e8400-e29b-41d4-a716-446655440000/pause \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--data '
{
"externalId": "pause-req-001",
"clientId": "client_abc_123",
"email": "admin@empresa.com"
}
'
Respuesta de Ejemplo (JSON - 200 OK)
Json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "PAUSED",
"updated_at": "2023-11-18T10:00:00Z"
}
Respuesta de Ejemplo (JSON - 404 Not Found)
Json
{
"error": "Not Found",
"message": "The forward process with the specified ID was not found."
}
Pausar Procesos de Reenvío del Propietario (Pause Owner
Forward Processes)
PATCH https://api.getincloud.online/jacaerys/v1/forwards/pause-by-owner
Este punto de acceso (endpoint) permite pausar de forma masiva todos los procesos de reenvío que
pertenecen a un propietario específico. Es una herramienta administrativa útil para detener el flujo de
mensajes entrantes (MO) de múltiples reglas de reenvío simultáneamente bajo una misma identidad
de propietario.
Parámetros del Cuerpo (Body Params)
• owner (string, requerido): El identificador o nombre del propietario cuyos procesos de reenvío
se desean pausar.
• externalId (string, opcional): Un identificador único de su sistema para rastrear esta operación
masiva.
• clientId (string, opcional): El identificador único del cliente asociado con la solicitud.
• email (string, opcional): Dirección de correo electrónico asociada para recibir notificaciones
sobre el resultado de la pausa masiva.
• callbackUrl (string, opcional): URL donde el sistema enviará una notificación una vez que todos
los procesos hayan sido actualizados.
Bloque de Respuestas: Códigos de Estado HTTP
• 200 OK: La solicitud se procesó correctamente.
• message (string): Confirmación de que los procesos del propietario han sido pausados.
• count (integer): El número total de procesos de reenvío que fueron afectados por esta
operación.
• 400 Bad Request: La solicitud es inválida. Esto puede ocurrir si falta el parámetro obligatorio
owner o si el formato del JSON es incorrecto.
• 401 Unauthorized: Error de autenticación. El token Bearer es inválido, falta o ha expirado.
• 403 Forbidden: El usuario autenticado no tiene los privilegios necesarios para realizar acciones
masivas o para afectar a este propietario en particular.
• 404 Not Found: No se encontraron procesos de reenvío asociados al owner proporcionado.
• 409 Conflict: La operación entra en conflicto con el estado actual de los procesos (ej. si todos
los procesos ya están pausados o en un estado de error).
• 500 Internal Server Error: Ocurrió un error inesperado en el servidor durante el procesamiento
de la pausa masiva.
Notas Técnicas y Advertencias
• Operación Masiva: Tenga en cuenta que esta acción afecta a todos los procesos vinculados al
propietario. Si solo desea pausar una regla específica, utilice el endpoint de pausa individual por
id.
• Tráfico de Mensajes: Una vez ejecutada la pausa, cualquier mensaje entrante dirigido a los
orígenes de este propietario no será reenviado. No hay procesamiento retroactivo para los
mensajes recibidos durante el periodo de pausa.
• Fidelidad Textual: Al igual que con otros endpoints de la API Jacaerys, el uso de externalId es
altamente recomendado para la conciliación de logs en sistemas externos.
Ejemplos de Código
Solicitud (cURL)
Bash
curl --request PATCH \
--url https://api.getincloud.online/jacaerys/v1/forwards/pause-by-owner \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--data '
{
"owner": "admin_user_01",
"externalId": "bulk-pause-2023",
"clientId": "client_99",
"email": "operaciones@empresa.com"
}
'
Respuesta de Ejemplo (JSON - 200 OK)
Json
{
"message": "All forward processes for the specified owner have been paused.",
"count": 15,
"status": "SUCCESS"
}
Respuesta de Ejemplo (JSON - 404 Not Found)
Json
{
"error": "Not Found",
"message": "No forward processes found for the owner: admin_user_01"
}
Reanudar Proceso de Reenvío (Resume Forward Process)
PATCH https://api.getincloud.online/jacaerys/v1/forwards/{id}/resume
Este punto de acceso (endpoint) permite reactivar un proceso de reenvío que ha sido previamente
pausado. Una vez reanudado, el sistema volverá a procesar los mensajes entrantes (MO) que coincidan
con los criterios de origen y palabra clave, enviándolos a la targetUrl configurada.
Parámetros de la Ruta (Path Params)
• id (string, requerido): El identificador único del proceso de reenvío que se desea reanudar.
Parámetros del Cuerpo (Body Params)
• externalId (string, opcional): Un identificador único de su sistema para rastrear esta solicitud de
cambio de estado.
• clientId (string, opcional): El identificador único del cliente asociado con la solicitud.
• email (string, opcional): Dirección de correo electrónico asociada para propósitos de
notificación o auditoría del cambio de estado.
• callbackUrl (string, opcional): URL para recibir una notificación una vez que el estado del proceso
haya sido actualizado a activo.
Bloque de Respuestas: Códigos de Estado HTTP
• 200 OK: La solicitud de reanudación se procesó con éxito.
• id (string): ID del proceso de reenvío.
• status (string): El nuevo estado del proceso (ej. ACTIVE).
• updated_at (string): Fecha y hora de la actualización en formato ISO 8601.
• 400 Bad Request: La solicitud es inválida. Esto puede ocurrir si el id tiene un formato incorrecto
o si el cuerpo de la solicitud contiene errores de sintaxis.
• 401 Unauthorized: Error de autenticación. El token Bearer es inválido, ha expirado o no se
incluyó en la solicitud.
• 403 Forbidden: El usuario no tiene permisos suficientes para modificar el estado de este proceso
de reenvío.
• 404 Not Found: No se encontró ningún proceso de reenvío con el id proporcionado.
• 409 Conflict: El proceso no puede ser reanudado porque ya se encuentra en un estado que
impide esta acción (ej. ya está activo o ha sido eliminado).
• 500 Internal Server Error: Ocurrió un error inesperado en el servidor al intentar reanudar el
proceso.
Notas Técnicas y Advertencias
• Procesamiento de Mensajes: La reanudación del proceso solo afecta a los mensajes que lleguen
después de que el estado cambie a ACTIVE. Los mensajes que llegaron mientras el proceso
estaba en estado PAUSED no serán procesados ni reenviados retroactivamente.
• Fidelidad Textual: Este cambio de estado se refleja inmediatamente en los logs del sistema. Se
recomienda el uso de externalId para mantener la trazabilidad con sus sistemas internos.
Ejemplos de Código
Solicitud (cURL)
Bash
curl --request PATCH \
--url https://api.getincloud.online/jacaerys/v1/forwards/550e8400-e29b-41d4-a716-446655440000/resume \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--data '
{
"externalId": "resume-req-002",
"clientId": "client_abc_123",
"email": "admin@empresa.com"
}
'
Respuesta de Ejemplo (JSON - 200 OK)
Json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "ACTIVE",
"updated_at": "2023-11-18T11:30:00Z"
}
Respuesta de Ejemplo (JSON - 409 Conflict)
Json
{
"error": "Conflict",
"message": "The forward process is already in ACTIVE status."
}
Desactivar Origen (Disable Origin)
PATCH https://api.getincloud.online/jacaerys/v1/forwards/disable-origin
Este punto de acceso (endpoint) permite desactivar un origen específico (shortcode, longcode o ID
alfanumérico). Al realizar esta acción, todos los procesos de reenvío asociados a dicho origen dejarán
de funcionar, deteniendo efectivamente el procesamiento de cualquier mensaje entrante dirigido a ese
código.
Parámetros del Cuerpo (Body Params)
• origin (string, requerido): El código corto, número largo o identificador alfanumérico que se
desea desactivar.
• externalId (string, opcional): Un identificador único de su sistema para rastrear esta solicitud de
desactivación.
• clientId (string, opcional): El identificador único del cliente asociado con la solicitud.
• email (string, opcional): Dirección de correo electrónico asociada para propósitos de
notificación o auditoría del cambio realizado.
• callbackUrl (string, opcional): URL para recibir una notificación una vez que el origen y sus
procesos asociados hayan sido desactivados.
Bloque de Respuestas: Códigos de Estado HTTP
• 200 OK: La solicitud de desactivación se procesó con éxito.
• message (string): Confirmación de la desactivación del origen.
• affected_processes (integer): El número total de procesos de reenvío que fueron
desactivados junto con el origen.
• 400 Bad Request: La solicitud es inválida. Esto ocurre generalmente si el parámetro origin no se
proporciona o si el cuerpo JSON tiene un formato incorrecto.
• 401 Unauthorized: Error de autenticación. El token Bearer es inválido, ha expirado o no está
presente en la solicitud.
• 403 Forbidden: El usuario no tiene permisos suficientes para desactivar este origen o no
pertenece a la cuenta del cliente.
• 404 Not Found: El origin especificado no existe o no tiene procesos de reenvío asociados que
puedan ser desactivados.
• 409 Conflict: La operación no se puede realizar porque el origen ya se encuentra en un estado
desactivado o existe una tarea de mantenimiento en curso sobre este recurso.
• 500 Internal Server Error: Ocurrió un error inesperado en el servidor al intentar procesar la
desactivación del origen.
Notas Técnicas y Advertencias
• Impacto Crítico: Esta es una acción de alto impacto. Al desactivar el origen, se suspenden todas
las reglas de negocio (palabras clave) vinculadas a ese número. Los mensajes que lleguen al
origen mientras esté desactivado no se reenviarán ni se almacenarán para procesamiento
futuro.
• Reactivación: Para volver a utilizar el origen, es necesario habilitar nuevamente los procesos de
reenvío de forma individual o mediante las herramientas administrativas.
• Fidelidad Textual: Al igual que en otros métodos de la API, se recomienda el uso de externalId
y clientId para asegurar la trazabilidad del log de cambios en entornos multi-cliente.
Ejemplos de Código
Solicitud (cURL)
Bash
curl --request PATCH \
--url https://api.getincloud.online/jacaerys/v1/forwards/disable-origin \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--data '
{
"origin": "87070",
"externalId": "disable-orig-7788",
"clientId": "client_abc_123",
"email": "seguridad@empresa.com"
}
'
Respuesta de Ejemplo (JSON - 200 OK)
Json
{
"message": "The origin and its associated processes have been successfully disabled.",
"affected_processes": 8,
"status": "DISABLED"
}
Respuesta de Ejemplo (JSON - 404 Not Found)
Json
{
"error": "Not Found",
"message": "The specified origin was not found or has no active processes."
}
Listar Palabras Clave del Usuario (List User Keywords)
GET https://api.getincloud.online/jacaerys/v1/forwards/keywords
Este punto de acceso (endpoint) permite recuperar una lista de todas las palabras clave (keywords) que
están asociadas a la cuenta del usuario. Es útil para obtener una visión general de los términos de
activación configurados en los diferentes procesos de reenvío.
Parámetros de la Consulta (Query Params)
• page (integer, opcional): El número de página para la paginación.
• limit (integer, opcional): La cantidad de registros por página que se desea recibir.
• clientId (string, opcional): Filtra las palabras clave asociadas a un identificador de cliente
específico.
• externalId (string, opcional): Filtra los resultados basándose en un identificador de sistema
externo.
Encabezados (Headers)
• Authorization (string, requerido): Token de portador necesario para la autenticación. Formato:
Bearer <YOUR_TOKEN>.
• accept (string, opcional): application/json.
Bloque de Respuestas: Códigos de Estado HTTP
• 200 OK: La solicitud fue exitosa.
• keywords (array de objetos): Una lista de las palabras clave encontradas. Cada objeto
incluye:
• keyword (string): El texto de la palabra clave.
• origin (string): El código corto o número largo al que está vinculada.
• processId (string): El identificador único del proceso de reenvío que utiliza esta
palabra clave.
• meta (objeto): Datos de paginación.
• totalItems (integer): Total de palabras clave encontradas.
• itemCount (integer): Cantidad de elementos en la respuesta actual.
• itemsPerPage (integer): Límite de elementos por página.
• totalPages (integer): Total de páginas disponibles.
• currentPage (integer): Página actual.
• 400 Bad Request: La solicitud es inválida debido a parámetros de consulta mal formateados.
• 401 Unauthorized: Error de autenticación. El token Bearer es inválido, ha expirado o no se
proporcionó.
• 403 Forbidden: El usuario no tiene permisos para acceder a la lista de palabras clave de este
cliente o entorno.
• 404 Not Found: No se encontraron palabras clave bajo los criterios de búsqueda especificados.
• 500 Internal Server Error: Ocurrió un error inesperado en el servidor.
Notas Técnicas y Advertencias
• Unicidad: Recuerde que dentro de un mismo origin, las palabras clave deben ser únicas. Este
listado le permite verificar rápidamente qué términos ya están ocupados.
• Codificación y Sensibilidad: Aunque las palabras clave se almacenan como cadenas de texto, el
sistema suele tratarlas de forma insensible a mayúsculas y minúsculas (case-insensitive). No
obstante, se recomienda mantener la consistencia en el registro.
• Fidelidad Textual sobre Segmentación: Tenga en cuenta que el uso de palabras clave con
caracteres especiales puede influir en la lógica de coincidencia si el terminal del usuario final
envía el mensaje en una codificación distinta (como Unicode en lugar de GSM-7).
Ejemplos de Código
Solicitud (cURL)
Bash
curl --request GET \
--url 'https://api.getincloud.online/jacaerys/v1/forwards/keywords?page=1&limit=10' \
--header 'accept: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN'
Respuesta de Ejemplo (JSON - 200 OK)
Json
{
"keywords": [
{
"keyword": "PROMO",
"origin": "87070",
"processId": "fwd_123456789"
},
{
"keyword": "AYUDA",
"origin": "87070",
"processId": "fwd_987654321"
}
],
"meta": {
"totalItems": 2,
"itemCount": 2,
"itemsPerPage": 10,
"totalPages": 1,
"currentPage": 1
}
}
Listar Procesos de Reenvío por Origen (List Origin Forward
Processes)
GET https://api.getincloud.online/jacaerys/v1/forwards/by-origin/{origin}
Este punto de acceso (endpoint) permite recuperar una lista de todos los procesos de reenvío asociados
a un origen específico (shortcode, longcode o ID alfanumérico). Es útil para visualizar todas las reglas y
palabras clave configuradas para un número de entrada determinado.
Parámetros de la Ruta (Path Params)
• origin (string, requerido): El código corto, número largo o identificador alfanumérico del cual se
desean listar los procesos.
Parámetros de la Consulta (Query Params)
• page (integer, opcional): El número de página para la paginación de los resultados.
• limit (integer, opcional): La cantidad de registros por página que se desea recibir.
• clientId (string, opcional): Filtra los procesos asociados a un identificador de cliente específico.
• externalId (string, opcional): Filtra los resultados basándose en un identificador de sistema
externo.
Encabezados (Headers)
• Authorization (string, requerido): Token de portador (Bearer token) necesario para la
autenticación. Formato: Bearer <TU_TOKEN>.
• accept (string, opcional): application/json.
Bloque de Respuestas: Códigos de Estado HTTP
• 200 OK: La solicitud fue exitosa.
• items (array de objetos): Lista de procesos de reenvío vinculados al origen. Cada objeto
contiene:
• id (string): Identificador único del proceso.
• name (string): Nombre descriptivo del proceso.
• keyword (string): Palabra clave de activación.
• targetUrl (string): URL de destino para el reenvío.
• status (string): Estado actual (ej. ACTIVE, PAUSED).
• externalId (string): Identificador de sistema externo.
• clientId (string): ID del cliente.
• meta (objeto): Datos de paginación.
• totalItems (integer): Total de registros encontrados.
• itemCount (integer): Elementos en la respuesta actual.
• itemsPerPage (integer): Límite de elementos por página.
• totalPages (integer): Total de páginas.
• currentPage (integer): Página actual.
• 400 Bad Request: La solicitud es inválida debido a un formato de origen incorrecto o parámetros
de consulta malformados.
• 401 Unauthorized: Error de autenticación. El token proporcionado es inválido o ha expirado.
• 403 Forbidden: El usuario no tiene permisos para acceder a los procesos de este origen
específico.
• 404 Not Found: No se encontraron procesos de reenvío para el origin proporcionado.
• 500 Internal Server Error: Ocurrió un error inesperado en el servidor.
Notas Técnicas y Advertencias
• Gestión de Orígenes: Este endpoint devuelve únicamente los procesos de reenvío. Si el origen
ha sido desactivado globalmente, los procesos listados aquí podrían aparecer con su estado
individual, pero no ejecutarán el reenvío hasta que el origen sea habilitado.
• Fidelidad Textual sobre Codificación: Al igual que en toda la plataforma, recuerde que el
contenido de los mensajes entrantes que activan estos procesos puede estar sujeto a
variaciones de codificación (GSM-7 o Unicode) dependiendo del operador de origen, lo que debe
ser considerado al procesar la data en su targetUrl.
• Uso de Filtros: El uso de clientId y externalId ayuda a segmentar la búsqueda en entornos donde
un mismo origen es compartido por múltiples departamentos o sub-clientes.
Ejemplos de Código
Solicitud (cURL)
Bash
curl --request GET \
--url 'https://api.getincloud.online/jacaerys/v1/forwards/by-origin/141518?page=1&limit=10' \
--header 'accept: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN'
Respuesta de Ejemplo (JSON - 200 OK)
Json
{
"items": [
{
"id": "fwd_001",
"name": "Campaña Verano",
"keyword": "SOL",
"targetUrl": "https://api.empresa.com/mo",
"status": "ACTIVE",
"externalId": "ext-7788",
"clientId": "client_1"
},
{
"id": "fwd_002",
"name": "Soporte Técnico",
"keyword": "AYUDA",
"targetUrl": "https://api.empresa.com/help",
"status": "PAUSED",
"externalId": "ext-9900",
"clientId": "client_1"
}
],
"meta": {
"totalItems": 2,
"itemCount": 2,
"itemsPerPage": 10,
"totalPages": 1,
"currentPage": 1
}
}
Listar Propietarios de Origen (List Origin Owners)
GET https://api.getincloud.online/jacaerys/v1/forwards/origin-owners/{origin}
Este punto de acceso (endpoint) permite recuperar una lista de todos los propietarios
(usuarios o entidades) que tienen procesos de reenvío configurados para un origen
específico (shortcode, longcode o ID alfanumérico). Es fundamental para la gestión de
permisos y auditoría de quién está utilizando un recurso de entrada compartido.
Parámetros de la Ruta (Path Params)
• origin (string, requerido): El código corto, número largo o identificador alfanumérico
del cual se desean consultar los propietarios.
Parámetros de la Consulta (Query Params)
• clientId (string, opcional): Filtra los propietarios asociados a un identificador de
cliente específico.
• externalId (string, opcional): Filtra los resultados basándose en un identificador de
sistema externo vinculado a la propiedad del origen.
• page (integer, opcional): El número de página para la paginación de los resultados.
• limit (integer, opcional): El número de registros que se devolverán por página.
Encabezados (Headers)
• Authorization (string, requerido): Token de portador (Bearer token) necesario para
la autenticación de la solicitud. Formato: Bearer <TU_TOKEN>.
• accept (string, opcional): application/json.
Bloque de Respuestas: Códigos de Estado HTTP
• 200 OK: La solicitud fue exitosa.
• owners (array de objetos): Lista de propietarios identificados. Cada objeto
contiene:
• ownerId (string): Identificador único del propietario.
• name (string): Nombre o descripción del propietario.
• processesCount (integer): Cantidad de procesos de reenvío que este
propietario tiene activos en el origen.
• clientId (string): ID del cliente asociado.
• meta (objeto): Información de paginación.
• totalItems (integer): Total de propietarios encontrados.
• itemCount (integer): Número de propietarios en la respuesta actual.
• itemsPerPage (integer): Límite de registros por página.
• totalPages (integer): Total de páginas disponibles.
• currentPage (integer): Página actual.
• 400 Bad Request: La solicitud es inválida. Puede deberse a un formato de origen no
soportado o parámetros de consulta incorrectos.
• 401 Unauthorized: Error de autenticación. El token proporcionado es inválido, ha
expirado o no tiene acceso a la API Jacaerys.
• 403 Forbidden: El usuario no tiene permisos suficientes para consultar la propiedad
de este origen.
• 404 Not Found: No se encontró el origen especificado o no tiene propietarios con
procesos asignados.
• 500 Internal Server Error: Ocurrió un error inesperado en el servidor durante la
recuperación de datos.
Notas Técnicas y Advertencias
• Propiedad Compartida: En entornos corporativos, un mismo origen puede tener
múltiples propietarios (departamentos, sucursales, clientes) gestionando palabras
clave distintas. Este endpoint ayuda a identificar colisiones potenciales.
• Fidelidad Textual sobre Codificación: Tenga en cuenta que aunque este endpoint
consulta metadatos de configuración, la lógica de negocio subyacente de los
propietarios está ligada a mensajes entrantes que pueden llegar en GSM-7 o
Unicode, dependiendo de la red del operador.
• Uso de Filtros: Los campos clientId y externalId son opcionales pero se recomiendan
para segmentar la búsqueda cuando se gestionan grandes volúmenes de cuentas
bajo un mismo integrador.
Ejemplos de Código
Solicitud (cURL)
Bash
curl --request GET \
--url 'https://api.getincloud.online/jacaerys/v1/forwards/origin-owners/141518?limit=10' \
--header 'accept: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN'
Respuesta de Ejemplo (JSON - 200 OK)
Json
{
"owners": [
{
"ownerId": "user_admin_01",
"name": "Departamento de Marketing",
"processesCount": 5,
"clientId": "client_9988"
},
{
"ownerId": "user_dev_02",
"name": "Equipo de Desarrollo - Webhooks",
"processesCount": 2,
"clientId": "client_9988"
}
],
"meta": {
"totalItems": 2,
"itemCount": 2,
"itemsPerPage": 10,
"totalPages": 1,
"currentPage": 1
}
}