API v1

Referencia de la API

Envía mensajes de WhatsApp desde cualquier app. Todos los endpoints usan JSON y una clave de API de Panel → API y webhooks.

Autenticación

Envía tu clave en el header Authorization. Las claves empiezan con nt_live_. Límite: 120 peticiones por minuto por clave.

Authorization: Bearer nt_live_xxxxxxxxxxxxxxxx

Enviar un mensaje

Pone un mensaje en cola. Sale respetando el espaciado de tu número (≥ 2 min) y el límite diario. Se cobra 1 crédito al encolar y se reembolsa si falla.

POST https://notific.app/api/v1/messages
Content-Type: application/json
Idempotency-Key: order-1042-shipped

{
  "from": "num_8f2aXk…",
  "to": "+573001234567",
  "text": "{Hi|Hello} {{name}}! Order #{{order}} shipped 🚚",
  "variables": { "name": "Ana", "order": "1042" },
  "send_at": "2026-11-02T09:00:00",
  "timezone": "America/Bogota"
}

→ 202 Accepted
{ "id": "msg_…", "status": "queued", "scheduled_at": "2026-11-02T14:00:00.000Z", … }

from	ID del número (num_…) que envía el mensaje
to	Destinatario con código de país, ej. +573001234567
text	Hasta 4.000 caracteres. Admite {{variables}} y {spin\|tax}
variables	Objeto opcional con valores para las {{variables}}
send_at	Fecha-hora ISO opcional. Sin offset se interpreta en `timezone`
timezone	Zona IANA opcional del destinatario (por defecto, la de tu cuenta)

Envía un header Idempotency-Key (ej. order-1042-shipped) para reintentar sin duplicar: la misma clave devuelve el mensaje original.

Otros endpoints

GET    https://notific.app/api/v1/messages/:id        → message
GET    https://notific.app/api/v1/messages?status=queued&limit=50
DELETE https://notific.app/api/v1/messages/:id        → cancel a queued message (refunds 1 credit)
GET    https://notific.app/api/v1/numbers             → your numbers and their ids
GET    https://notific.app/api/v1/balance             → { "credits": 1234 }

Webhooks de estado

Configura una URL en Panel → API y webhooks. Enviamos un POST con cada cambio de estado. Verifica la firma: HMAC-SHA256 de `${X-Notific-Timestamp}.${cuerpo}` con tu secreto, en hex, en X-Notific-Signature.

POST https://your-app.com/webhooks/notific
X-Notific-Timestamp: 1792161000
X-Notific-Signature: 5f2c…

{ "event": "message.status",
  "data": { "id": "msg_…", "number_id": "num_…", "to": "+573001234567",
            "status": "delivered", "error": null },
  "timestamp": 1792161000 }

// Node.js
const expected = crypto.createHmac("sha256", secret)
  .update(`${req.headers["x-notific-timestamp"]}.${rawBody}`).digest("hex");

Errores

Los errores devuelven { error: { code, message } } con estado 4xx: 401 unauthorized, 402 insufficient_credits, 403 consent_required, 404 number_not_found, 409 recipient_opted_out, 422 content_blocked (mensaje promocional, con un arreglo `reasons`) e invalid_*, 429 rate_limited.