API WAP.lat para tenants

Autenticacion

Enviar `x-api-key: wap_...` en cada request. Cada key pertenece a un tenant y puede limitarse con scopes como `messages:send`, `messages:read`, `media:read`, `instances:read`, `instances:connect`, `instances:write`, `webhooks:read` y `webhooks:write`. El backend vuelve a validar tenant y scope en cada recurso.

curl -H "x-api-key: wap_xxx" https://api.wap.lat/messages

Planes y features

Las capacidades se resuelven desde el plan del tenant y overrides puntuales del tenant. Si una feature no esta habilitada, la API responde 403 con `feature_disabled` y `requiredFeature`.

Mensajes y rich media

POST /messages/text
{ "route": "default", "to": "5493510000000", "text": "Hola" }

Endpoints disponibles: `/messages/image`, `/messages/audio`, `/messages/document`, `/messages/video`, `/messages/sticker`, `/messages/location`, `/messages/contact` y `/messages/poll`.

Los tenants premium administran WebP reutilizables con `/stickers` y los envían con `/stickers/{id}/send`. Los textos outbound pueden editarse con `PATCH /messages/{id}` y los mensajes soportados pueden revocarse con `DELETE /messages/{id}`. Aplican los límites del provider activo.

Para reaccionar a un mensaje persistido use su ID interno de WAP.lat. Enviar otra reaccion la reemplaza; `DELETE` quita la reaccion del numero conectado.

POST /messages/{messageId}/reactions
{ "emoji": "👍" }

DELETE /messages/{messageId}/reactions

Códigos de validación

Genera un código numérico o alfanumérico de 4 a 10 caracteres, o tres palabras unidas por guiones. La llamada elige el teléfono, número emisor, idioma y plantilla; la respuesta devuelve el código para que el integrador lo compruebe.

POST /validation/codes
{ "instanceId": "...", "to": "5493510000000", "type": "numeric", "length": 6, "locale": "es" }

Los planes definen solicitudes mensuales, plantillas y reintentos por teléfono en 24 horas. Cada envío también consume un mensaje saliente. Consulte la documentación completa para administrar plantillas y configuración.

Restauracion de numeros archivados

Eliminar un numero realiza archivado logico. Si el mismo tenant vuelve a crearlo, WAP.lat restaura la instancia y su historial y responde restoredFromArchive: true. Una instancia activa, la propiedad vigente de otro tenant o un bloqueo global siguen rechazando el alta.

Grupos

Requiere feature `groups`. Permite listar grupos, leer metadata, crear grupos, administrar participantes, obtener invite link, salir y enviar texto.

GET /groups?instanceId=...
POST /groups/{groupId}/messages/text

Listas de difusion

Las listas son audiencias propias de WAP.lat, no broadcast lists nativas de WhatsApp. El envio genera mensajes individuales para trazabilidad, retries y opt-out.

POST /broadcast-lists
POST /broadcast-lists/{listId}/recipients
POST /broadcast-lists/{listId}/send-text

Webhooks

Un tenant puede crear varios callbacks hasta el cupo de su plan. Cada endpoint puede asignarse a uno, varios o todos sus numeros; WAP.lat filtra por `payload.instanceId` antes de crear la entrega. Los endpoints reciben HMAC cuando tienen secret.

POST /webhook-endpoints
{ "url": "https://crm.example/webhook", "events": ["message.received"], "instanceIds": ["inst_espana"] }

PATCH /webhook-endpoints/{id}/instances
{ "instanceIds": ["inst_espana", "inst_soporte"] }

Eventos base: `message.received`, `message.sent`, `message.failed`, `media.received`, `qr.updated`, `instance.connected` e `instance.disconnected`.

Eventos ampliados: `message.receipt_update`, `message.reaction`, `poll.results`, `call.received`, `chat.update`, `group.update` y `group.participants_update`.

La entrega es asincronica, con reintentos y resultado HTTP persistido. El panel muestra evento, intentos, respuesta o error; Conversaciones vincula esa evidencia al mensaje correspondiente.

API publica de widget de conexion

Los tenants pueden emitir connection tokens revocables para una instancia WhatsApp. Los tokens tienen capabilities como `status`, `reconnect`, `qr` y `subscribe`, y pueden rotarse desde el panel. El QR es opt-in y no se expone con un scope de solo lectura.

GET /public/instances/{id}/status
POST /public/instances/{id}/reconnect
GET /public/instances/{id}/qr
GET /public/instances/{id}/stream
POST /public/instances/{id}/alert-subscriptions

El `widget.js` embebible y el iframe `/embed/instance/{id}` usan esa API con rate limits, `Cache-Control: no-store`, QR opt-in y alertas por email con double opt-in.

Si una vinculación queda esperando indefinidamente, el tenant puede detener y reanudar la generación con `POST /instances/{id}/qr-renewal/pause` y `/resume`; el estado expone `qrRenewalPaused`.

Política de tráfico y alarmas

Los grupos, newsletters y listas de difusión se bloquean por defecto antes de persistir, descargar media, transcribir o despachar callbacks. La política hereda global → tenant → pool → número y separa entrada de salida.

GET   /traffic-policy
PATCH /traffic-policy
GET   /traffic-policy/instances/{id}/effective
PATCH /traffic-policy/instances/{id}
GET   /traffic-policy/metrics?minutes=1

Los contadores por minuto muestran verde hasta 50 intentos, amarillo de 51 a 100 y rojo desde 101. El superadmin administra los mismos niveles bajo `/admin/traffic-policy`.

Operacion, superadmin y archivo verificable

La consola superadmin nativa administra tenants, planes, features, usuarios, numeros, callbacks, asignaciones, API keys y politicas de archivo. Las reasignaciones limpian asociaciones operativas para evitar cruces entre clientes. CRM expone uso diario entrante/saliente de 30 dias; Sistema acepta rango inclusivo, usa siete dias por defecto y distribuye trafico horario y archivos por tipo.

Operaciones incorpora inventario de IPs directas y proxies, pools compartidos o dedicados, health checks, monitoreo de componentes críticos y un laboratorio controlado para Baileys, WPPConnect y open-wa. Registrar un egreso no provisiona la IP ni promete failover instantáneo entre providers.

La salud de plataforma incluye transcripción de audio, OCR de imágenes y el motor semántico interno. La calibración de sentimiento e intención usa mensajes o conversaciones completas en un flujo privado de revisión Superadmin; no expone conversaciones almacenadas por la API pública. Los runtimes locales Qwen para prompts, imagen y voz son opcionales, nacen apagados y no agregan endpoints tenant públicos.

El ledger liviano conserva permanentemente metadatos de trafico sin texto ni binarios. El detalle elegible se empaqueta en ZIP nativo con manifiesto y SHA-256, se vuelve a leer y verificar antes de purgar, y puede restaurarse de forma transaccional. Los paquetes usan storage local o S3 compatible.

GET   /archive/runs
GET   /archive/runs/{id}/download
GET   /admin/archive/policy?tenantId=...
PATCH /admin/archive/policy
POST  /admin/archive/runs
POST  /admin/archive/runs/{id}/restore

El tenant necesita la feature `messageArchiveAccess`, asignable por plan u override. La configuracion, ejecucion y restauracion quedan reservadas al superadmin. La disponibilidad productiva depende de que la migracion, el storage y la politica esten habilitados; no se publica como activa por defecto.

SDKs y n8n

El repositorio incluye clientes uniformes y sin dependencias obligatorias para Node.js, Python, Laravel/PHP, Go, .NET y Java, mas un nodo n8n inicial. Todos usan la misma API tenant, errores tipados y respetan scopes/features. La sintaxis o compilacion se verifica con `npm.cmd run check:sdks`.

Los artefactos machine-readable de integracion estan versionados en el repositorio como `docs/openapi.yaml` y `docs/postman-wap-lat.json`; la API viva tambien expone `GET /openapi.json` y `GET /llms.txt`.

Estado de cobertura

WAP.lat cubre mensajeria rica, callbacks por numero, conexion remota, grupos basicos, listas internas, SDKs livianos y observabilidad operativa. Algunas capacidades siguen en rollout o roadmap para no prometer mas de lo disponible.