Antes de enviar
Envíe un SMS o un MMS compatible mediante un número de envío configurado para su cuenta. Esta es una operación en producción que puede contactar con los destinatarios y generar cargos. Envíe únicamente a destinatarios autorizados y solo tráfico aprobado; los números y la referencia del ejemplo siguiente son ficticios.
Su cuenta necesita aprobación para la mensajería saliente y los permisos aplicables al remitente, al país y al tráfico. Las credenciales directas de usuarios personales o consumidores no son aptas para esta API. Las credenciales dedicadas de API aprobadas tienen un proceso de habilitación independiente; los remitentes móviles P2P pueden requerir permisos adicionales de P2P y para Estados Unidos y Canadá. Confirme con MultiTEL la configuración correcta de la cuenta, en lugar de considerar que una credencial de API otorga automáticamente permiso para enviar cualquier tipo de tráfico.
Solicitud de envío
Autentíquese mediante HTTPS con una cuenta de API habilitada desde su dirección IP de origen permitida. Guarde las credenciales en un almacén de secretos del lado del servidor. Utilice POST con campos codificados como formulario, o un objeto JSON cuando no se proporcionen campos de formulario ni de consulta. No incluya credenciales ni el texto del mensaje en una URL.
curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
--data-urlencode 'from=12025550123' \
--data-urlencode 'to=12025550124' \
--data-urlencode 'text=Your requested update is ready.' \
--data-urlencode 'reference=order-update-example' \
https://api.multitel.net/v3/sendsms| Campo | Obligatorio | Significado |
|---|---|---|
| from | Sí | Su número de envío configurado, preferiblemente con todos los dígitos del formato internacional. |
| to | Sí | Un destino, varios destinos separados por comas o un array JSON. Utilice preferiblemente todos los dígitos del formato internacional. Una solicitud de grupo puede rechazarse debido a los límites aplicables de P2P o del país; no se trata de una API de envío masivo sin restricciones. |
| text | Para SMS | Texto del mensaje en UTF-8. Se requiere, como mínimo, texto no vacío o contenido multimedia. Envíe caracteres y saltos de línea reales en lugar de HTML o texto con secuencias de escape porcentuales. Algunas rutas de operador normalizan las cadenas de escape literales. |
| media | Para MMS con solo contenido multimedia | Contenido multimedia codificado en Base64, no una URL ni una ruta de archivo. La disponibilidad de MMS, el formato y el tamaño dependen de la ruta configurada. Confirme con MultiTEL los contenidos multimedia compatibles; este controlador no establece un límite universal de tamaño para el contenido multimedia. |
| reference | Recomendado | Su etiqueta de correlación, que se conserva en los registros y las notificaciones de retorno. Incluya una para facilitar la resolución de problemas. No es una clave de idempotencia. |
| notifyurl | No | Su receptor HTTPS de notificaciones de retorno. El controlador puede enviar mediante POST un resultado inicial después del procesamiento. Debe ser un receptor bajo su control y no debe ser una URL de un servicio interno. |
Para un array JSON, utilice un array real en to; no introduzca una cadena que represente un array JSON dentro de un campo de formulario. Utilice el envío a un único destinatario como prueba inicial de integración. La compatibilidad con grupos y MMS varía según la ruta, por lo que debe confirmar la combinación compatible antes de utilizarlos.
Lea el resultado completo
Solo se muestran algunos campos seleccionados a modo de ejemplo; el coste indicado no es un presupuesto.
{
"status": {
"code": "200",
"msg": ""
},
"response": {
"sms_log_id_ori": 42,
"to": "12025550124",
"from": "12025550123",
"status": "Success",
"message": "Message queued",
"causecode": 0,
"uniqueid": "fixture-message",
"cost": "$0.0120",
"carrier_fee_usd": "0.0020000000",
"chars": 31,
"parts": 1,
"encoding": "GSM-7",
"permsg": "$0.0120",
"pid": "fixture-reference"
}
}Compruebe conjuntamente el estado HTTP, status.code del JSON y status/message de la respuesta. Los códigos de resultado pueden ser cadenas. Conserve sms_log_id_ori y los valores de mensaje y referencia devueltos para que el servicio de asistencia pueda correlacionarlos. Los valores heredados de uniqueid y pid varían según la ruta; no deduzca su formato ni suponga que son tokens de idempotencia del cliente.
Success o Message queued suele indicar la aceptación por parte de la ruta seleccionada, no la recepción en el teléfono de una persona. Un estado de una notificación de retorno inicial como sent no demuestra por sí solo la entrega final.
Segmentos y cargos
Utilice Análisis de longitud de SMS sobre el texto final completo antes de enviarlo. Los precios de los SMS dependen del destino y del servicio de la cuenta; las tarifas aplicables del operador se añaden por segmento. El proceso de envío suma los precios correspondientes a los destinatarios y las tarifas aplicables, y luego multiplica el resultado por el número calculado de segmentos SMS. Para este cálculo, considera una solicitud MMS como un mensaje.
cost y permsg son cadenas con formato monetario en la respuesta heredada. carrier_fee_usd indica el componente correspondiente a la tarifa del operador en USD y ya está incluido en el total de envío calculado; no lo sume una segunda vez. Debe comprobar los precios reales y la disponibilidad de rutas para su cuenta. La solicitud no es una operación que solo consulte el precio.
El código revisado realiza el cargo después de completar correctamente el proceso de envío al operador, pero la aceptación del operador, el almacenamiento local y la facturación no forman una única transacción. Puede producirse un error o agotarse el tiempo de espera después de que se haya aceptado una solicitud en un sistema anterior de la cadena. No se ofrece una clave de idempotencia del cliente: repetir la misma referencia puede provocar otro envío y otro cargo.
Entrega local y resultados mixtos
Los números alojados localmente pueden incorporarse con el estado accepted al flujo de mensajería entrante de MultiTEL sin un envío a un operador externo. Para una solicitud con todos los destinos locales, la respuesta puede incluir accepted, message_id, provider y delivery_status. La aceptación local no garantiza que el destino de reenvío configurado por el destinatario haya funcionado.
Revise local_delivery_results y partial cuando estén presentes. Un destinatario puede mostrar accepted con el valor true aunque el resultado de su reenvío no sea satisfactorio. Una solicitud mixta puede tener destinatarios de operador con el estado accepted y una parte local fallida. No reintente automáticamente el lote completo: concilie primero el resultado de cada destinatario.
En este proceso, la aceptación de una solicitud con todos los destinos locales indica un coste saliente de cero, aunque los destinatarios pueden seguir incurriendo en sus cargos habituales de mensajería entrante. No interprete un coste saliente de cero como una garantía de que no se realizará ningún cargo a ninguna cuenta.
Notificaciones de retorno y correlación
Cuando se proporciona notifyurl, la notificación de retorno inicial contiene una estructura envolvente status y campos de respuesta que incluyen message_id, reference, from, to, status, status_text, error_code, timestamp y accepted. También puede incluir resultados locales. Guarde la información de correlación sin registrar credenciales de API ni contenidos de mensajes innecesarios.
Este controlador no añade un campo de firma a esa notificación de retorno inicial. No utilice una notificación de retorno sin verificar como autorización por sí sola para otra acción. Consulte la configuración de integración y webhooks compatible con su cuenta y concilie los resultados inciertos con los registros del portal o con el servicio de asistencia. No suponga que las notificaciones de retorno llegan una sola vez ni en el orden de entrega final.
Fallos y recuperación segura
Los fallos de validación pueden utilizar el código de API 403. Las denegaciones relacionadas con la aprobación de la cuenta, P2P y las políticas de país también pueden establecer HTTP 403 e incluir un response.code legible por máquina. Los límites de frecuencia pueden utilizar 429 con información para reintentar. Una política no disponible o un fallo de envío o de almacenamiento local pueden utilizar 503 o 500; el comportamiento heredado para saldo insuficiente también puede devolver 500.
Para 429, respete Retry-After y cualquier valor de response.retry_after. En caso de rechazo por cuenta, remitente, país o destinatario, corrija la causa antes de reintentar. Si se agota el tiempo de espera o el resultado del envío no está claro, conserve la hora de la solicitud, la referencia y los identificadores devueltos, revise el portal y contacte con el servicio de asistencia antes de volver a enviar. La ausencia de una entrada en el registro no demuestra por sí sola que ningún operador haya aceptado la solicitud.