# wa-gateway · Documentación de integración

wa-gateway es la pasarela de WhatsApp Business de la plataforma. Cualquier aplicación puede, sin hablar nunca con Meta ni guardar tokens ni plantillas:

- **enviar** mensajes y plantillas a los clientes de cada cliente suyo,
- **recibir** lo que escriben y el estado de cada envío, como eventos firmados,
- **mostrar** el chat, las plantillas, la configuración y los costes **incrustando pantallas ya hechas**,
- saber **qué clientes tienen el módulo contratado** y con qué límites.

## Por dónde empezar

| Quiero… | Lee |
| --- | --- |
| Enviar mi primer mensaje en 10 minutos | [01 · Inicio rápido](01-inicio-rapido.md) |
| Entender claves, tenants, alcances y roles | [02 · Autenticación y multi-tenant](02-autenticacion-y-multitenant.md) |
| Enviar plantillas, texto, archivos y botones | [03 · Enviar mensajes](03-enviar-mensajes.md) |
| Crear y gestionar plantillas | [04 · Plantillas](04-plantillas.md) |
| Enterarme de lo que llega y de cada entrega | [05 · Recibir eventos](05-recibir-eventos.md) |
| Incrustar el chat y las pantallas en mi app | [06 · UI embebible](06-ui-embebible.md) |
| Gestionar contactos, conversaciones y consentimiento | [07 · Conversaciones y contactos](07-conversaciones-y-contactos.md) |
| Conocer licencias, límites y costes | [08 · Licencias, límites y costes](08-licencias-limites-y-costes.md) |
| Conectar el número de un cliente | [09 · Alta de números y onboarding](09-alta-de-numeros-y-onboarding.md) |
| Probar en local y pasar a producción | [10 · Pruebas y producción](10-pruebas-y-produccion.md) |
| Crear la cuenta de Meta paso a paso y conectar un número que ya uso en el móvil (coexistencia) | [14 · La cuenta de Meta y la coexistencia](14-cuenta-de-meta-y-coexistencia.md) |
| Dar de alta clientes y licencias, y ver su WABA (equipo interno; consola web y API) | [11 · Administración](11-administracion.md) |
| Usar el SDK de TypeScript | [12 · SDK](12-sdk.md) |
| Integrar desde PHP, C#, Java u otro lenguaje | [13 · Otros lenguajes](13-otros-lenguajes.md) |

## Referencia (generada desde el contrato)

- [Referencia interactiva de la API](api/index.html) · también en `GET /docs` del servidor
- [Contrato OpenAPI 3.1](../openapi/openapi.yaml) · importable en Postman, Insomnia, Bruno o un generador de clientes
- [Endpoints](referencia/endpoints.md) · [Eventos](referencia/eventos.md) · [Errores](referencia/errores.md) · [Alcances y roles](referencia/alcances.md)

## Ejemplos ejecutables

En [`ejemplos/`](ejemplos/): envío (Node, Python, curl), receptores de eventos con verificación de firma (Node, Python, Ruby), el endpoint de token de la app anfitriona y un [vector de prueba de firmas](ejemplos/vectores/firma-evento.json) para validar cualquier otra implementación. **Todos se ejecutan contra el sistema real** con `pnpm docs:verify`.

## El modelo en una pantalla

```
Cliente de WhatsApp ─▶ Meta ─▶ wa-gateway ─▶ evento firmado ─▶ vuestra app
                                    ▲              (al menos una vez)
vuestra app ── API key ── POST /v1/messages ──┘
vuestra app ── token de 5 min ── <wa-gateway-embed> ── iframe: chat, plantillas, ajustes, costes
```

- **Tenant** = un cliente final vuestro (con su propia cuenta de WhatsApp, plantillas, conversaciones, licencia y facturación directa con Meta).
- **App** = cada una de vuestras aplicaciones. Una app tiene claves de API y puede estar habilitada o no para cada tenant.
- Todo recurso pertenece a un tenant. Lo de otro tenant **no existe** para vosotros (`404`).
- Los mensajes se envían de forma **asíncrona**: la API responde `202` y el resultado llega por evento.

## Convenciones

- JSON sobre HTTPS, fechas ISO 8601 en UTC, teléfonos con o sin `+` (se normalizan a dígitos con prefijo de país).
- Identificadores con prefijo: `ten_`, `msg_`, `cnv_`, `ctc_`, `tpl_`, `num_`, `agt_`, `med_`, `key_`, `whs_`, `evt_`, `req_`.
- Listados con cursor: `?limit=50&cursor=…` → `{ "data": [...], "next_cursor": "…" | null }`.
- Todas las respuestas llevan `X-Request-Id`; citadlo al pedir soporte.
- Versionado en la ruta (`/v1`). Dentro de una versión solo hay cambios compatibles; las retiradas se anuncian con `Deprecation` y `Sunset` con 6 meses de antelación.