Zapini Integrations API

Autenticação

Toda requisição é autenticada com uma chave de integração. As chaves têm 51 caracteres, começam com o prefixo zpk_ e são geradas no painel em Integrações → "Integrações Customizadas".

Envie a chave em toda requisição como Bearer token no cabeçalho Authorization. Todas as requisições e respostas usam JSON: defina Content-Type: application/json ao enviar um corpo e Accept: application/json sempre.

Exemplo de requisição

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

Escopos

Cada chave carrega uma lista explícita de escopos escolhida na criação. Um escopo dá acesso a um recurso, dividido em uma metade de leitura e uma de escrita.

Segurança e limites

As chaves de integração customizada foram projetadas para serem entregues a sistemas de terceiros com segurança. Os controles abaixo valem para todas as chaves:

Erros

Os erros usam códigos de status HTTP convencionais mais um código de erro legível por máquina no corpo JSON.

Exemplo de resposta — 403 INSUFFICIENT_SCOPE

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

Kanban

Gerencie quadros de vendas, colunas e leads — tudo o que você vê no módulo Kanban do painel.

Exemplo de requisição

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
  }'

Agenda

Crie e gerencie os agendamentos exibidos na agenda do painel, incluindo transições de status.

Exemplo de requisição

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

Leia conversas e mensagens e envie texto ou mídia pela sua instância de WhatsApp conectada.

Exemplo de requisição

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

Abra e acompanhe tickets de suporte de forma programática.

Exemplo de requisição

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"]
  }'

Exemplo de resposta — 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"
  }
}

Banco de Dados (Base Inteligente)

A Base Inteligente é o banco de dados interno do tenant — imóveis, cardápio, produtos, serviços, profissionais, o que o segmento pedir. Esta API a transforma em um CMS headless: o seu site lê e grava exatamente os mesmos registros que o cliente administra no painel da Zapini ou no portal público. Nada é duplicado, não há sincronização para manter.

Consultando registros

A listagem aceita os parâmetros abaixo. Nomes de campo são validados contra o esquema da coleção e operadores vêm de uma lista fixa — a query string nunca chega crua ao banco.

Exemplo de requisição

# Imóveis ativos até R$ 800 mil, do mais barato ao mais 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"

Exemplo de resposta — 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 }
}

Criando um 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
  }'

Dica: chame GET /database/collections/{collection} antes de gravar. O esquema devolve o nome exato de cada campo, o tipo e as opções válidas dos campos enum — é o que evita 422 na escrita.

TMS — Transporte

O módulo de transporte inteiro por HTTP: cadastrar veículos e motoristas, programar fretes, acompanhar a entrega nota a nota, registrar ocorrências e manter contas a pagar e a receber em dia — os mesmos dados que o operador vê no painel.

Módulo e painéis

Frota (veículos e motoristas)

Programação (fretes)

Monitoramento (por nota fiscal)

Ocorrências (incidentes)

Contas a pagar e a receber

Listas de valores (cadastros auxiliares)

Exemplo de requisição

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 }
  }'

Exemplo de resposta — 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 (saída)

Uma integração customizada pode registrar uma URL de webhook para receber eventos em tempo real — por exemplo message.received e message.sent — entregues como requisições POST em JSON.

Chaves com database.read também recebem database.record.created, database.record.updated e database.record.deleted sempre que um registro da Base Inteligente muda — é o gancho para revalidar o cache do seu site. Esses eventos são do tenant e não carregam instance_uuid.

Chaves com kanban.read também recebem crm.lead.created, crm.lead.updated, crm.lead.moved, crm.lead.won, crm.lead.lost e crm.lead.deleted sempre que um lead muda — por qualquer caminho: painel, API, formulário de site, importação, detecção automática ou automação. São eventos do tenant e não carregam instance_uuid. Movimentação, ganho e perda têm evento próprio e não repetem em crm.lead.updated. Apagar um QUADRO remove os leads dele em cascata no banco, sem evento por lead: esse caso emite um crm.board.deleted único, com a contagem do que foi removido.

Cada entrega é assinada com HMAC-SHA256. O cabeçalho X-Zapini-Signature carrega sha256= seguido do HMAC do corpo bruto da requisição, calculado com o seu segredo de webhook.

Para verificar uma entrega, calcule o HMAC sobre o corpo bruto da requisição (antes de qualquer parse) e compare com o cabeçalho usando comparação em tempo constante.

Exemplo 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 a assinatura (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;
}