API do ZapToBox.
Sua operação dentro do seu sistema.

01 / PRIMEIROS PASSOS

Da chave à primeira fila.

1. Escolha a conexão no painel. Abra Integrações → API pública. Você precisa ter acesso à conexão e permissão para gerenciar integrações.
2. Crie a chave do seu sistema. Informe um nome, a validade e as permissões. Para este exemplo, selecione queues:read, queues:write e participants:read.
3. Guarde a chave no servidor do cliente. Ela é exibida somente na criação. Use uma variável de ambiente, como ZAPTOBOX_API_KEY. Cada conexão precisa de sua própria chave.
4. Faça a primeira requisição. Os exemplos abaixo usam cURL em um terminal Bash. Substitua IDs e valores pelos retornados na sua conta.

curl 'https://backend.zaptobox.pro/api/v1/public/queues' \
  -H "Authorization: Bearer $ZAPTOBOX_API_KEY"

02 / ACESSO

A chave define o que a integração faz.

Envie Authorization: Bearer SUA_CHAVE em cada operação autenticada. A chave herda os acessos atuais de quem a criou e só funciona na conexão à qual pertence. Suspensão, vencimento do acesso, revogação e mudanças de papel também afetam a integração.

Escolha somente os escopos necessários. Uma chave para consultar filas não precisa poder enviar mensagens. As opções disponíveis aparecem com descrição no painel e na referência OpenAPI.

Uma chave pode durar de 1 a 365 dias e pode ser revogada no painel. Para trocar uma chave, crie a nova, atualize seu sistema e revogue a anterior. Chaves existentes mantêm seus escopos; crie outra para conceder novas operações.

Faça as chamadas no backend do seu sistema. Não coloque a chave no HTML, em aplicativos públicos de navegador ou em repositórios. Esta página não solicita nem armazena sua chave.

03 / FILAS DE ATENDIMENTO

Monte a equipe de vendas pelo seu CRM.

Comece consultando GET /participants. Use os IDs dos participantes que podem receber reservas para preencher members. Adicionar alguém à fila organiza a distribuição; o acesso pago dessa pessoa à conexão precisa existir antes.

curl -X POST 'https://backend.zaptobox.pro/api/v1/public/queues' \
  -H "Authorization: Bearer $ZAPTOBOX_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "name": "Vendas",
    "enabled": true,
    "members": [],
    "mode": "manual",
    "capacity": 10,
    "keywords": ["comprar", "preço"],
    "priority": 1,
    "isDefault": false
  }'

Este exemplo cria a estrutura da fila sem atendentes. Para distribuição automática, informe os IDs reais em members e escolha round_robin (alternância) ou least_busy (menor carga). A capacidade varia de 1 a 200 atendimentos por pessoa. Reservas existentes continuam valendo.

Para consultar e alterar o encaminhamento, a chave também precisa de chats:read e chats:write, respectivamente.

curl -X PATCH 'https://backend.zaptobox.pro/api/v1/public/chats/123/routing' \
  -H "Authorization: Bearer $ZAPTOBOX_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "queueId": "UUID_DA_FILA",
    "priority": 2,
    "vip": true,
    "closeReason": null,
    "version": 0
  }'

Substitua 123, UUID_DA_FILA e version pelos valores consultados. Use queueId: null para remover o encaminhamento. Prioridades vão de 0 a 3; um número maior tem mais prioridade. Encaminhar a conversa não transfere uma reserva existente.

04 / ATENDIMENTO

Acompanhe a conversa e o resultado.

GET /chats retorna as conversas da conexão em páginas. Use after com o último ID recebido para avançar. Tags pessoais continuam visíveis somente para seu criador; a chave age em nome desse usuário. Operações de reserva e atendimento seguem as permissões do painel.

curl -X POST 'https://backend.zaptobox.pro/api/v1/public/messages' \
  -H "Authorization: Bearer $ZAPTOBOX_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: UUID_V4_UNICO_DA_OPERACAO' \
  --data '{"chatId": 123, "text": "Olá! Recebemos sua solicitação."}'

Gere um UUID v4 por envio e mantenha a mesma chave ao repetir a mesma tentativa. O retorno 202 confirma o agendamento. Consulte GET /runs/{runId}, com chats:read, usando o ID retornado para conhecer o resultado. Qualquer reserva humana impede esse envio automático, inclusive uma reserva do criador da chave; acompanhar a execução permite identificar essa situação.

Para executar uma automação existente, use POST /flows/{flowId}/run com chatId e Idempotency-Key. O fluxo segue as capacidades do canal e as permissões do usuário que gerou a chave.

05 / REFERÊNCIA

Explore as operações disponíveis.

A API reúne filas, participantes, conversas, tags, reservas, notas, contatos e campos, lembretes, oportunidades, relatórios, fluxos e integrações. Consulte o contrato de cada operação para os campos, escopos e respostas.

A especificação pode ser importada em ferramentas compatíveis com OpenAPI. Os exemplos desta página continuam disponíveis quando o catálogo não puder ser carregado.

Abra a especificação OpenAPI para consultar o contrato completo.

06 / EVENTOS

Receba as novidades no seu sistema.

1. Em Integrações, cadastre uma URL HTTPS do seu sistema e selecione os eventos que deseja receber.
2. Guarde o segredo de assinatura exibido na criação. Ele é diferente da chave Bearer da API.
3. Valide a assinatura e a data da entrega, registre o identificador do evento e processe cada evento uma única vez.
4. Responda com HTTP 2xx após aceitar a entrega e acompanhe as tentativas pelo histórico do painel.

A assinatura em X-ZapToBox-Signature é o HMAC-SHA256 hexadecimal de timestamp + "." + corpo JSON original, usando o segredo da integração. O timestamp em segundos vem de X-ZapToBox-Timestamp. Valide os bytes originais antes de transformar o JSON e deduplique por X-ZapToBox-Event-Id.

Falhas de rede, HTTP 429 e 5xx recebem novas tentativas, até seis ao todo. Eventos disponíveis incluem mensagens recebidas/enviadas, conclusão ou transferência de automações, conclusão de campanhas e sincronização de CRM. A seleção atual aparece no painel.

07 / RESPOSTAS

Trate o resultado de cada operação.

Operações de dados usam o envelope {"data": …}. Erros usam {"error":{"code":"…","message":"…"}}. Use code no seu tratamento e apresente message para orientar a pessoa.

As rotas de operação têm limite de 120 requisições por minuto por IP. Reserve margem quando vários sistemas compartilham a mesma saída de rede. O uso de Idempotency-Key está previsto nos envios e nas execuções de fluxos; não presuma que a criação de filas será deduplicada automaticamente.