# Diseño de una API de mensajería REST: recursos, métodos, códigos de estado

> Una API de mensajería REST modela cada envío como un recurso dentro de una colección de mensajes. El cliente hace POST de un mensaje y, como la entrega es asíncrona, el servidor devuelve 202 Accepted con un identificador de mensaje y una URL de estado, y luego notifica el resultado final por webhook. Los métodos HTTP y los códigos de estado siguen la semántica de RFC 9110.

- URL canónica: https://www.broadnet.me/es/reference/rest-messaging-api-design
- Idioma: es
- Última actualización: 2026-07-19
- Editor: BroadNet (https://www.broadnet.me)

Cómo se modela una API de mensajería REST basada en estándares: una colección de mensajes, métodos HTTP y semántica de códigos de estado según RFC 9110, envío síncrono frente a asíncrono (202 Accepted más un callback de estado), negociación de contenido y versionado por URL o por header, con una tabla comparativa REST frente a SMPP.

## El modelo de recurso de mensajes

Una API de mensajería REST trata cada mensaje como un recurso bajo una colección —convencionalmente /messages— direccionable mediante un identificador asignado por el servidor. El verbo, y no un campo del payload, expresa la intención: POST /messages crea y encola un nuevo mensaje saliente; GET /messages/{id} lee su estado actual; GET /messages lista y filtra. Esta es la capa REST que se sitúa por encima de las mismas conexiones de operador que SMPP alcanza a nivel de cable, de modo que el recurso que el cliente hace POST se corresponde, aguas abajo, con un submit_sm sobre una sesión SMPP ligada. Como el identificador lo acuña el servidor y se devuelve en la respuesta (y normalmente se repite en un header Location), el cliente dispone de una referencia estable para sondear o para correlacionar con callbacks de estado posteriores.

*Crear un mensaje en la colección (patrón REST genérico)*

```http
POST /v1/messages HTTP/1.1
Host: api.example
Content-Type: application/json
Authorization: Bearer <token>
Idempotency-Key: 8f14e45f-ea7b-4c0f-9b2a-1d2c3e4f5a6b

{
  "to": "+15551234567",
  "from": "BRANDNAME",
  "text": "Your one-time code is 401 928",
  "callback_url": "https://app.example/webhooks/dlr"
}
```

## Los métodos HTTP y sus garantías

RFC 9110 define dos propiedades que gobiernan cómo pueden tratar una petición un cliente de mensajería y cualquier intermediario. Los métodos seguros (GET, HEAD) no tienen efectos secundarios y son libremente cacheables y reintentables. Los métodos idempotentes (GET, HEAD, PUT, DELETE) pueden repetirse con el mismo efecto neto. POST no es ni seguro ni idempotente, que es justamente el problema para el envío de mensajes: un POST reintentado podría provocar un doble envío. El remedio estándar no es abusar de PUT, sino mantener POST y hacerlo idempotente con un header de petición Idempotency-Key, de modo que una reenvío repetido devuelva el resultado original en lugar de crear un segundo mensaje.

*Métodos HTTP sobre un recurso de mensajes (RFC 9110)*

| Método | En /messages | Seguro | Idempotente |
|---|---|---|---|
| POST | Crear + poner en cola un nuevo mensaje | No | No (hágalo idempotente mediante Idempotency-Key) |
| GET | Leer un mensaje o listar la colección | Sí | Sí |
| HEAD | Verificación de metadatos/existencia | Sí | Sí |
| PUT | Reemplazar un recurso mutable (por ejemplo, una configuración de webhook) | No | Sí |
| PATCH | Actualización parcial de un recurso mutable | No | No |
| DELETE | Cancelar un mensaje que aún está en cola | No | Sí |

## Semántica de los códigos de estado en el envío

El código de estado que devuelve el servidor codifica si el mensaje se aceptó, se completó o se rechazó, y el envío de mensajes es casi siempre asíncrono. RFC 9110 define 202 Accepted precisamente para este caso: la petición se aceptó para su procesamiento pero el procesamiento no ha concluido, y la respuesta debería indicar dónde consultar su evolución. Por tanto, una API de mensajería devuelve 202 para un envío encolado, reservando 201 Created para un recurso completamente materializado y 200 OK para una operación verdaderamente síncrona. Los errores de cliente (payload malformado, destino inválido, remitente desconocido) son 4xx y no deben reintentarse sin cambios; los fallos del servidor o aguas arriba son 5xx y pueden reintentarse con backoff bajo el mismo Idempotency-Key.

*Semántica de los códigos de estado para el envío de mensajes (RFC 9110)*

| Código | Significado | Cuando una API de mensajería lo utiliza |
|---|---|---|
| 202 Accepted | Aceptado, procesamiento incompleto | Envío asíncrono en cola; el estado final se obtiene mediante devolución de llamada |
| 201 Created | Recurso creado | Creación síncrona donde el recurso está completo |
| 200 OK | Solicitud completada | Lectura de estado síncrona u operación verdaderamente inmediata |
| 400 / 422 | Error del cliente / no procesable | Cuerpo con formato incorrecto o campo no válido: no reintentar sin cambios |
| 401 / 403 | No autenticado / prohibido | Credenciales faltantes o insuficientes |
| 409 Conflict | Conflicto de estado | Idempotency-Key reutilizada con una carga útil diferente |
| 429 Too Many Requests | Límite de tasa excedido | Limitar la tasa; respetar Retry-After y aplicar backoff |
| 5xx | Fallo del servidor / aguas arriba | Transitorio: reintentar con backoff bajo la misma clave |

## Entrega síncrona frente a asíncrona

Hay dos latencias distintas en una API de mensajería y confundirlas es un error de diseño. La latencia de la API es cuánto tarda la llamada HTTP en aceptar el mensaje; la latencia de entrega es cuánto tarda la red del operador en entregar el mensaje al terminal y devolver un acuse. Como la segunda no está acotada y escapa al control del remitente, una API bien diseñada acusa recibo de inmediato (202) con un estado aceptado o encolado, y luego entrega el resultado terminal de forma asíncrona: un callback de estado de entrega (el equivalente HTTP de un acuse de entrega de SMPP). Los clientes que necesitan el estado final o bien se suscriben al callback (push) o bien sondean GET /messages/{id} (pull); se prefiere el callback porque evita la carga del sondeo y notifica los cambios de estado en segundos.

*Respuesta 202 Accepted con una referencia de estado*

```http
HTTP/1.1 202 Accepted
Location: /v1/messages/01HZY8Q3M6
Content-Type: application/json

{
  "id": "01HZY8Q3M6",
  "status": "accepted",
  "created_at": "2026-07-19T09:15:22Z",
  "status_url": "/v1/messages/01HZY8Q3M6"
}
```

## Negociación de contenido y versionado

Cliente y servidor acuerdan la representación mediante los headers de negociación de contenido de RFC 9110: la petición lleva Content-Type para el cuerpo que envía y Accept para lo que desea recibir, y el servidor repite el tipo de medio elegido en el Content-Type de la respuesta. La mayoría de las API de mensajería estandarizan application/json y usan application/problem+json para los errores. El versionado de una API tiene dos patrones principales. El versionado por URL (/v1/messages) es explícito, favorable a la caché y trivial de enrutar, a costa de un salto grosero de toda la superficie. El versionado por header o por tipo de medio (Accept: application/vnd.example.v2+json) mantiene las URL estables y permite que un recurso evolucione de forma independiente, a costa de ser invisible en un navegador y más difícil de probar a mano. Sea cual sea la opción, los cambios aditivos (nuevos campos opcionales) nunca deberían exigir un salto de versión; solo lo hacen los cambios que rompen la compatibilidad.

*Enfoques de versionado de una API*

| Enfoque | Ejemplo | Compromiso |
|---|---|---|
| Ruta de URL | /v1/messages | Explícito, almacenable en caché, fácil de enrutar; incrementos de grano grueso |
| Encabezado personalizado | Api-Version: 2026-07-19 | URLs limpias, versión fijada por fecha; invisibles para cachés y navegadores |
| Tipo de medio aceptado | Accept: application/vnd.example.v2+json | Evolución por recurso; más difícil de probar manualmente |
| Parámetro de consulta | /messages?version=2 | Sencillo; complica el almacenamiento en caché y la identidad del recurso |

## REST frente a SMPP: elegir el transporte

La capa HTTP/REST y SMPP son dos transportes hacia la misma red de mensajería, y los remitentes maduros usan ambos. REST es la opción adecuada para la integración de aplicaciones: es sin estado, amigable con los cortafuegos sobre HTTPS ordinario, fácil de asegurar con bearer tokens y sencillo de instrumentar. SMPP es la opción adecuada para un rendimiento sostenido muy alto y el menor coste por mensaje, porque una sesión binaria de larga duración evita el coste de conexión por mensaje y da un control fino de la ventana. La tabla contrasta ambos para que un integrador pueda ajustar el transporte a la carga de trabajo; para los endpoints REST concretos de BroadNet consulte la referencia de la API para desarrolladores, y para el protocolo de cable consulte la introducción a SMPP.

*REST (HTTP) frente a SMPP como transporte de mensajería*

| Propiedad | REST / HTTP | SMPP |
|---|---|---|
| Modelo | Solicitud/respuesta sin estado a través de HTTPS | Sesión binaria de larga duración con estado (bind) |
| Encuadre | JSON sobre HTTP/1.1 o HTTP/2 | PDU binarios (submit_sm, deliver_sm) |
| Confirmación de entrega | Webhook de estado / sondeo GET | recibo deliver_sm en la misma sesión |
| Rendimiento | Bueno; sobrecarga por solicitud | Máximo sostenido; con ventana, baja sobrecarga |
| Auth | Token Bearer / clave API / OAuth 2.0 | system_id + contraseña al vincular |
| Control de flujo | 429 + encabezados Retry-After, RateLimit | Tamaño de ventana + limitación de enquire_link |
| Ideal para | Integración de aplicaciones, webhooks, volumen moderado | Flujos masivos A2P de alto volumen y nivel operador |

## Preguntas frecuentes

### ¿Por qué una API de mensajería REST devuelve 202 en lugar de 200 o 201?

Porque la entrega de mensajes es asíncrona. RFC 9110 define 202 Accepted como «aceptado para su procesamiento, procesamiento no concluido», que describe exactamente un envío encolado. La API acusa recibo de inmediato con un id de mensaje y una referencia de estado, y luego notifica el resultado terminal de la entrega por callback. 201 y 200 implican que la operación ya está completa.

### ¿Cómo debe modelarse un recurso de mensajes?

Como una colección: POST /messages crea y encola un mensaje, GET /messages/{id} lee su estado y GET /messages lista y filtra. El servidor acuña el identificador y lo devuelve (a menudo en un header Location) para que el cliente tenga una referencia estable con la que sondear o correlacionar con los callbacks de estado.

### POST no es idempotente: ¿cómo se evitan los dobles envíos?

Se mantiene POST (expresa correctamente «crear un nuevo mensaje») y se hace idempotente con un header de petición Idempotency-Key. Un reenvío que porte la misma clave devuelve el resultado original en lugar de crear un segundo mensaje. Abusar de PUT para forzar la idempotencia rompe el modelo de recursos REST.

### ¿Cuál es la diferencia entre la latencia de la API y la latencia de entrega?

La latencia de la API es cuánto tarda la llamada HTTP en aceptar el mensaje; la latencia de entrega es cuánto tarda la red del operador en alcanzar el terminal y devolver un acuse. La segunda no está acotada y escapa al control del remitente, por lo que la API acusa rápido (202) y notifica la entrega final de forma asíncrona.

### ¿Debo versionar una API de mensajería en la URL o en un header?

El versionado por URL (/v1/messages) es explícito, favorable a la caché y fácil de enrutar, pero salta toda la superficie de golpe. El versionado por header o por tipo de medio mantiene las URL estables y permite que los recursos evolucionen de forma independiente, pero es invisible para las cachés y más difícil de probar a mano. En ambos casos, los cambios aditivos nunca deberían forzar un salto de versión.

### ¿Cuándo debo usar REST y cuándo SMPP?

Use REST para la integración de aplicaciones: HTTPS sin estado y amigable con cortafuegos, autenticación por bearer token e instrumentación sencilla. Use SMPP para el mayor rendimiento sostenido y el menor coste por mensaje, donde compensa una sesión binaria con ventana y de larga duración. Ambos alcanzan la misma red de mensajería; muchos remitentes ejecutan REST para el tráfico de control y SMPP para los flujos de alto volumen.

## Fuentes

- [IETF RFC 9110 — HTTP Semantics](https://datatracker.ietf.org/doc/html/rfc9110)
- [IETF RFC 9111 — HTTP Caching](https://datatracker.ietf.org/doc/html/rfc9111)

## Relacionado

- [Introducción al protocolo SMPP](https://www.broadnet.me/es/reference/smpp-protocol-overview)
- [Entrega y fiabilidad de webhooks](https://www.broadnet.me/es/reference/webhook-delivery-and-reliability)
- [Idempotencia y limitación de tasa](https://www.broadnet.me/es/reference/idempotency-and-rate-limiting)
- [Errores de API y paginación](https://www.broadnet.me/es/reference/api-errors-and-pagination)
- [Referencia de la API de BroadNet](https://www.broadnet.me/es/developers/api-reference)