Zapini Integrations API

Autenticación

Cada petición se autentica con una clave de integración. Las claves tienen 51 caracteres, comienzan con el prefijo zpk_ y se generan en el panel, en Integraciones → "Integraciones Personalizadas".

Envía la clave en cada petición como Bearer token en la cabecera Authorization. Todas las peticiones y respuestas usan JSON: define Content-Type: application/json al enviar un cuerpo y Accept: application/json siempre.

Ejemplo de petición

curl https://zapini.app/api/v1/kanban/boards \
  -H "Authorization: Bearer zpk_your_51_char_key_here" \
  -H "Accept: application/json"

Alcances

Cada clave lleva una lista explícita de alcances elegida al crearla. Un alcance da acceso a un recurso, dividido en una mitad de lectura y otra de escritura.

Seguridad y límites

Las claves de integración personalizada están diseñadas para entregarse a sistemas de terceros con seguridad. Los siguientes controles aplican a todas las claves:

Errores

Los errores usan códigos de estado HTTP convencionales más un código de error legible por máquina en el cuerpo JSON.

Ejemplo de respuesta — 403 INSUFFICIENT_SCOPE

{
  "success": false,
  "error": "INSUFFICIENT_SCOPE",
  "required_scope": "kanban.write",
  "granted_scopes": ["kanban.read", "chat.read"]
}

Kanban

Gestiona tableros de ventas, columnas y leads — todo lo que ves en el módulo Kanban del panel.

Ejemplo de petición

curl -X POST https://zapini.app/api/v1/kanban/leads \
  -H "Authorization: Bearer zpk_your_51_char_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "column_uuid": "c2b7e9d4-1f3a-4a5b-9c8d-7e6f5a4b3c2d",
    "name": "Jane Doe",
    "phone": "+5511999999999",
    "value": 1500
  }'

Calendario

Crea y gestiona las citas que se muestran en el calendario del panel, incluidas las transiciones de estado.

Ejemplo de petición

curl -X POST https://zapini.app/api/v1/calendar/appointments \
  -H "Authorization: Bearer zpk_your_51_char_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Demo call",
    "start_at": "2026-07-10 14:00",
    "end_at": "2026-07-10 14:30",
    "contact_name": "Jane Doe",
    "contact_number": "+5511999999999"
  }'

Chat

Lee conversaciones y mensajes, y envía texto o medios a través de tu instancia de WhatsApp conectada.

Ejemplo de petición

curl -X POST https://zapini.app/api/v1/chat/send \
  -H "Authorization: Bearer zpk_your_51_char_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "+5511999999999",
    "message": "Hello from my integration!"
  }'

Tickets

Abre y da seguimiento a tickets de soporte de forma programática.

Ejemplo de petición

curl -X POST https://zapini.app/api/v1/tickets \
  -H "Authorization: Bearer zpk_your_51_char_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Customer cannot log in",
    "description": "Password reset e-mail never arrives.",
    "priority": "low",
    "contact_name": "Jane Doe",
    "contact_number": "+5511999999999",
    "tags": ["login", "email"]
  }'

Ejemplo de respuesta — 201

{
  "success": true,
  "data": {
    "uuid": "9d3f2c1a-7b6e-4d5c-8a9b-0c1d2e3f4a5b",
    "code": "TK-8F3K2M1Q",
    "subject": "Customer cannot log in",
    "status": "open",
    "priority": "low",
    "category": null,
    "contact_name": "Jane Doe",
    "contact_number": "+5511999999999",
    "tags": ["login", "email"],
    "due_at": null,
    "created_at": "2026-07-02T12:00:00Z"
  }
}

Base de Datos (Base Inteligente)

Base Inteligente es la base de datos interna del tenant — inmuebles, carta, productos, servicios, profesionales, lo que pida el rubro. Esta API la convierte en un CMS headless: tu sitio lee y escribe exactamente los mismos registros que el cliente administra en el panel de Zapini o en el portal público. Nada se duplica, no hay sincronización que mantener.

Consultando registros

El listado acepta los parámetros de abajo. Los nombres de campo se validan contra el esquema de la colección y los operadores salen de una lista fija — la query string nunca llega cruda a la base.

Ejemplo de petición

# Inmuebles activos hasta R$ 800 mil, del más barato al más caro
curl "https://zapini.app/api/v1/database/collections/imoveis/records?per_page=12&sort=preco&order=asc&filter[ativo]=true&filter[preco][lte]=800000" \
  -H "Authorization: Bearer zpk_your_51_char_key_here"

Ejemplo de respuesta — 200

{
  "success": true,
  "data": [
    {
      "id": "66b3f1c2a4d5e6f708192a3b",
      "titulo": "Apartamento 3 quartos — Icaraí",
      "preco": 780000,
      "quartos": 3,
      "foto_principal": "https://storage.zapini.app/gallery/8/image/....jpg",
      "ativo": true,
      "created_at": "2026-08-01 10:22:41"
    }
  ],
  "meta": { "current_page": 1, "per_page": 12, "total": 37, "last_page": 4 }
}

Creando un registro

curl -X POST https://zapini.app/api/v1/database/collections/imoveis/records \
  -H "Authorization: Bearer zpk_your_51_char_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "titulo": "Cobertura duplex — Santa Rosa",
    "preco": 1250000,
    "quartos": 4,
    "ativo": true
  }'

Consejo: llama a GET /database/collections/{collection} antes de escribir. El esquema devuelve el nombre exacto de cada campo, su tipo y las opciones válidas de los campos enum — eso es lo que evita el 422 al escribir.

TMS — Transporte

Todo el módulo de transporte por HTTP: registrar vehículos y conductores, programar fletes, seguir la entrega factura por factura, registrar incidencias y mantener al día las cuentas por pagar y por cobrar — los mismos datos que ve el operador en el panel.

Módulo y paneles

Flota (vehículos y conductores)

Programación (fletes)

Monitoreo (por factura)

Incidencias

Cuentas por pagar y por cobrar

Listas de valores (altas auxiliares)

Ejemplo de petición

curl -X POST https://zapini.app/api/v1/tms/freights \
  -H "Authorization: Bearer zpk_your_51_char_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "Santos/SP",
    "destination": "Betim/MG",
    "cargo_description": "Bobinas de aco",
    "cargo_weight_kg": 24000,
    "freight_value_brl": 7400.00,
    "vehicle_plate": "ABC1D23",
    "pickup_at": "2026-09-22T08:00:00-03:00",
    "delivery_eta": "2026-09-23T18:00:00-03:00",
    "operational_status": "06",
    "meta": { "nr_carga": "99812", "km": 780, "pedagio": 310.50 }
  }'

Ejemplo de respuesta — 201

{
  "success": true,
  "data": {
    "uuid": "9d3f2c1a-7b6e-4d5c-8a9b-0c1d2e3f4a5b",
    "code": "1482",
    "status": "assigned",
    "operational_status": "06",
    "origin": "Santos/SP",
    "destination": "Betim/MG",
    "driver_name": "Joao da Silva",
    "driver_phone": "+5513999999999",
    "vehicle_plate": "ABC1D23",
    "meta": { "nr_carga": "99812", "km": 780 },
    "created_at": "2026-09-17T12:00:00-03:00"
  }
}

Webhooks (salida)

Una integración personalizada puede registrar una URL de webhook para recibir eventos en tiempo real — por ejemplo message.received y message.sent — entregados como peticiones POST en JSON.

Las claves con database.read también reciben database.record.created, database.record.updated y database.record.deleted cuando cambia un registro de la Base Inteligente — el gancho para revalidar la caché de tu sitio. Estos eventos son del tenant y no llevan instance_uuid.

Las claves con kanban.read también reciben crm.lead.created, crm.lead.updated, crm.lead.moved, crm.lead.won, crm.lead.lost y crm.lead.deleted cada vez que un lead cambia — por cualquier camino: panel, API, formulario de sitio, importación, detección automática o automatización. Son eventos del tenant y no llevan instance_uuid. Movimiento, ganado y perdido tienen evento propio y no se repiten en crm.lead.updated. Eliminar un TABLERO quita sus leads en cascada en la base de datos, sin evento por lead: ese caso emite un único crm.board.deleted con el recuento de lo eliminado.

Cada entrega se firma con HMAC-SHA256. La cabecera X-Zapini-Signature lleva sha256= seguido del HMAC del cuerpo crudo de la petición, calculado con tu secreto de webhook.

Para verificar una entrega, calcula el HMAC sobre el cuerpo crudo de la petición (antes de cualquier parseo) y compáralo con la cabecera usando una comparación de tiempo constante.

Ejemplo de entrega

POST https://your-app.example.com/webhooks/zapini
Content-Type: application/json
X-Zapini-Signature: sha256=5257a869e7ecebeda32affa27f4245b1...

{
  "event": "message.received",
  "timestamp": "2026-07-02T12:00:00Z",
  "data": {
    "conversation_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "message": {
      "direction": "incoming",
      "sender_number": "+5511999999999",
      "content": "Hi! I would like a quote."
    }
  }
}

Verificando la firma (PHP)

$secret    = 'zws_your_webhook_secret';
$payload   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_ZAPINI_SIGNATURE'] ?? '';

$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

// Timing-safe comparison
if (! hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}