Zapini Integrations API

Authentication

Every request is authenticated with an integration key. Keys are 51 characters long, start with the zpk_ prefix and are generated in the panel under Integrations → "Custom Integrations".

Send the key on every request as a Bearer token in the Authorization header. All requests and responses use JSON: set Content-Type: application/json when sending a body and Accept: application/json always.

Example request

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

Scopes

Each key carries an explicit list of scopes chosen when it is created. A scope grants access to one resource, split into a read half and a write half.

Security & limits

Custom integration keys are designed to be handed to third-party systems safely. The following controls apply to every key:

Errors

Errors use conventional HTTP status codes plus a machine-readable error code in the JSON body.

Example response — 403 INSUFFICIENT_SCOPE

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

Kanban

Manage sales boards, columns and leads — everything you see in the panel's Kanban module.

Example request

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

Calendar

Create and manage the appointments shown in the panel's calendar, including status transitions.

Example request

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

Read conversations and messages, and send text or media through your connected WhatsApp instance.

Example request

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

Open and track support tickets programmatically.

Example request

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

Example response — 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"
  }
}

Database (Base Inteligente)

Base Inteligente is the tenant's internal database — properties, menu items, products, services, staff, whatever the vertical calls for. This API turns it into a headless CMS: your website reads and writes exactly the same records the client administers in the Zapini panel or the public portal. Nothing is duplicated, there is no sync to keep.

Querying records

The listing endpoint accepts the parameters below. Field names are validated against the collection schema and operators come from a fixed allowlist — the query string never reaches the database raw.

Example request

# Active listings up to R$ 800k, cheapest first
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"

Example response — 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 }
}

Creating a record

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

Tip: call GET /database/collections/{collection} before writing. The schema returns each field's exact name, its type and the valid options of enum fields — that is what keeps writes from failing with 422.

TMS — Transport

The whole transport module over HTTP: register vehicles and drivers, plan freights, track deliveries note by note, log incidents and keep payables and receivables in sync — the same data the operator sees in the panel.

Module & dashboards

Fleet (vehicles & drivers)

Freights (planning)

Monitoring (per invoice)

Occurrences (incidents)

Payables & receivables

Value lists (auxiliary registers)

Example request

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

Example response — 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 (outbound)

A custom integration may register a webhook URL to receive real-time events — for example message.received and message.sent — delivered as JSON POST requests.

Keys holding database.read also receive database.record.created, database.record.updated and database.record.deleted whenever a Base Inteligente record changes — the hook to revalidate your site cache. These events are tenant-level and carry no instance_uuid.

Keys with kanban.read also receive crm.lead.created, crm.lead.updated, crm.lead.moved, crm.lead.won, crm.lead.lost and crm.lead.deleted whenever a lead changes — through any path: panel, API, web form, import, auto-detection or automation. These are tenant events and carry no instance_uuid. Moves, wins and losses have their own event and are not repeated as crm.lead.updated. Deleting a BOARD removes its leads by database cascade, with no per-lead event: that case emits a single crm.board.deleted carrying the counts of what was removed.

Every delivery is signed with HMAC-SHA256. The X-Zapini-Signature header carries sha256= followed by the HMAC of the raw request body, computed with your webhook secret.

To verify a delivery, compute the HMAC over the raw request body (before any parsing) and compare it against the header using a timing-safe comparison.

Example delivery

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."
    }
  }
}

Verifying the signature (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;
}