Saltar a contenido

API de integración

La API de Arplyx te permite enviar mensajes de WhatsApp desde tus propios sistemas con un simple POST HTTP. Arplyx se encarga de la cola, los reintentos, el seguimiento de estados y el canal (Meta Official o WhatsApp Direct).

Formas de integrar

Podés llamar la API REST directamente, o usar un atajo:

  • SDKs oficiales para TypeScript/Node (@arplyx/sdk) y Python (arplyx).
  • Servidor MCP para que un agente de IA use Arplyx sin escribir código.
  • Especificación OpenAPI para generar clientes o importar en Postman.

Autenticación

Todas las llamadas se autentican con tu API key en el header x-api-key (sin prefijo Bearer ni nada más):

curl -X POST https://api.arplyx.com/messages \
  -H "x-api-key: ak_live_xxxxxxxx..." \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Si falta el header o la clave es inválida o fue revocada, la API responde 401 con un cuerpo { "error": "..." }.

Cómo obtener tu API key

Las claves se autogestionan desde el portal: Portal → API Keys → Generar API Key. Podés tener hasta 5 claves activas a la vez (útil para separar sistemas: una para tu e-commerce, otra para tu CRM, etc.).

Datos útiles sobre las claves:

  • Tienen el formato ak_live_… (producción). Son largas: 72 caracteres en total.
  • En la tabla se muestran enmascaradas (ak_live_a1b2c3d4…f9e8), y el botón Copiar te da la clave completa cuando la necesites — se guardan cifradas en Arplyx.
  • Se pueden revocar desde la misma pantalla en cualquier momento (por ejemplo si sospechás que se filtró). La revocación es inmediata e irreversible: generá una nueva y actualizá tus sistemas.
  • La misma pantalla te muestra tus cuentas de WhatsApp con su whatsappAccountId listo para copiar.

Note

Las claves generadas antes de junio 2026 no son recuperables (solo existía su hash). Si tenés una de esas y la perdiste, generá una nueva desde el portal y reemplazala en tus sistemas.

Custodiá tu clave

La API key identifica a tu cuenta: cualquiera que la tenga puede enviar mensajes a tu nombre y consumir tu cuota. Guardala en un gestor de secretos o variable de entorno, nunca en el código fuente ni en repositorios.

Antes de enviar

  1. Necesitás al menos una cuenta de WhatsApp vinculada y conectada — por QR (WhatsApp Direct) o con tu app de Meta (Meta Official).
  2. El ID de la cuenta (whatsappAccountId) figura en la tarjeta de cada cuenta en el portal, sección Cuentas. Es obligatorio para whatsapp_direct; para whatsapp_meta solo hace falta si tenés más de una cuenta Meta conectada.
  3. Cada mensaje enviado por API descuenta de la misma cuota mensual de tu plan que los envíos desde el portal. Ver errores, estados y límites.

Alcance de las claves (scoping por cuenta)

Al generar una clave podés limitarla a una sola cuenta de WhatsApp (select "Alcance" en el portal). Pensado para SaaS multi-tenant que operan números de varios clientes finales: si una clave scopeada se filtra, no expone el resto de las cuentas.

Una clave scopeada:

  • Envía solo por esa cuenta: no hace falta pasar whatsappAccountId (se completa solo); pasar otro devuelve 403 key_scope_violation.
  • Lee solo esa cuenta: GET /messages, GET /messages/{id}, GET /whatsapp-accounts, GET /inbound-senders/{phone} y GET /inbound-messages filtran automáticamente por la cuenta del scope.
  • No administra webhooks (403 key_scope_insufficient): la configuración de webhooks afecta a toda la cuenta, así que requiere una clave sin scope.

Modo sandbox

Para desarrollar la integración sin enviar mensajes reales ni gastar cuota, generá una API key sandbox (Portal → API Keys → "Clave sandbox"). Se distinguen por el prefijo ak_test_… y se comportan igual que una clave real, salvo que:

  • Los mensajes no llegan a WhatsApp: el worker simula el ciclo completo en segundos, incluyendo los webhooks de message.status — perfecto para probar tu receptor de eventos de punta a punta.
  • No consumen cuota mensual y no aparecen en tu uso.
  • El resultado se controla con el número destinatario (números mágicos):
Destinatario termina en Ciclo simulado
99 failed con error.code = SANDBOX_SIMULATED_FAILURE
88 sent → delivered → read
cualquier otro sent → delivered
  • Las plantillas se pueden probar en cualquier plan (no hay envío real).
  • Los broadcasts no están disponibles con clave sandbox (403 sandbox_not_supported): una clave de prueba nunca debe poder disparar envíos masivos reales.
  • Los mensajes sandbox se marcan con "sandbox": true en GET /messages y GET /messages/{id}.
  • Las consultas de remitentes entrantes también se simulan: un número que termina en 77 responde hasWritten: true; el resto, false.

Idempotencia

Todos los envíos llevan un externalId: un identificador único tuyo (el ID del pedido, del turno, del evento que dispara el mensaje). Arplyx lo usa para deduplicar:

  • Si repetís un request con el mismo externalId y el mismo payload, la API responde 200 con el mensaje original — no se envía dos veces. Esto hace seguro reintentar ante timeouts o errores de red.
  • Si repetís el externalId con un payload distinto, la API responde 409 conflict y no crea nada.