API ZPRO (Postman)

Disponível para o perfil: Administrador

Link do Postman

A API do Z-PRO permite que você integre a plataforma com outros sistemas, como CRMs, ERPs ou plataformas de automação (ex: n8n), para realizar ações de forma programática.

Como Usar a Coleção: Fazendo um "Fork"

No Postman, o termo "fork" tem um significado semelhante ao utilizado em plataformas como o GitHub. Fazer um "fork" de uma coleção significa criar uma cópia pessoal e vinculada da nossa coleção pública. Você poderá usar, testar e modificar esta cópia no seu próprio workspace (espaço de trabalho) sem afetar o original.

Principais Vantagens de Fazer um Fork:

• Independência: Você pode alterar e personalizar a coleção no seu workspace, inserindo suas chaves de autenticação e salvando requisições próprias.

• Sincronização: Você mantém uma referência à coleção original e pode receber notificações sobre nossas atualizações, com a opção de usar a função "pull" para sincronizar as novidades.

• Segurança: Suas chaves de API e testes ficam salvos apenas no seu ambiente privado.

Passo a Passo para Fazer o Fork:

• Acesse nossa coleção pública através do link fornecido.

• Clique na opção "Fork" (geralmente representada por um ícone de ramificação).

• Dê um nome para a sua cópia (label) e escolha em qual workspace você deseja salvá-la.

Como Navegar em um Endpoint no Postman

Ao clicar em uma requisição (endpoint) na sua cópia da coleção, você verá várias abas:

• Overview: A documentação principal, com a descrição do que a rota faz.

• Params: Usado em requisições GET para filtrar os resultados.

• Authorization: Onde a autenticação Bearer Token é configurada.

• Headers: Cabeçalhos da requisição.

• Body: A "carga" de dados que você envia em requisições POST.

Autenticação e Primeiros Passos

Como Gerar seu Token (API Key)

1. No painel Admin, acesse o menu "API".

2. Crie uma nova chave de API para gerar seu token.

Como Usar o Token

Todas as requisições à API devem incluir este token no cabeçalho Authorization, no formato Bearer.

• Exemplo: Authorization: Bearer SEU_TOKEN_AQUI

URL Base

Todas as rotas da API devem ser chamadas a partir da sua URL de back-end.

• Exemplo: https://api.seudominio.com.br/

---

🔒 Autenticação e Segurança

• Isolamento: Todas as rotas são isoladas por Tenant (Empresa). O token garante que apenas dados da empresa autenticada sejam acedidos ou modificados.

• Token: Todas as requisições exigem autenticação via Bearer Token.

• Validação: O sistema valida automaticamente o sessionId e o tenantId em todas as chamadas.

---

📊 Rotas de Listagem (GET)

Utilize estas rotas para consultar informações do sistema.

1. Listar Canais

GET /v2/api/external/:apiId/listChannels Retorna todos os canais de conexão (WhatsApp, Instagram, etc.) do tenant.

2. Listar Sessões

GET /v2/api/external/:apiId/listSessions Lista todas as sessões ativas no sistema.

3. Listar Tickets (Atendimentos)

GET /v2/api/external/:apiId/listTickets Lista os tickets com filtros avançados.

• Query Params: pageNumber, status, searchParam, queuesIds, whatsappIds, selectedUser.

4. Listar Oportunidades (Kanban)

GET /v2/api/external/:apiId/listOpportunities Lista os cartões do funil de oportunidades.

• Query Params: page, limit, status, pipelineId, stageId.

5. Listar Contatos

GET /v2/api/external/:apiId/listContacts

• Query Params: pageNumber, searchParam, walletId, tagId.

6. Listar Usuários (Atendentes)

GET /v2/api/external/:apiId/listUsers Lista todos os utilizadores cadastrados no tenant.

• Query Params: pageNumber, searchParam.

7. Listar Tags (Etiquetas)

GET /v2/api/external/:apiId/listTags

• Query Params: isActive (true/false).

8. Listar Filas

GET /v2/api/external/:apiId/listQueues Lista as filas (departamentos) cadastradas.

9. Verificar Status do Atendente

GET /v2/api/external/:apiId/getUserStatus?userId=ID_DO_USUARIO Verifica em tempo real se um atendente específico está Online ou Offline.

10. Listar Notas Internas

GET /v2/api/external/:apiId/listNotes?ticketId=ID_DO_TICKET Lista todas as notas internas registadas num ticket específico.

11. Buscar Informações Adicionais

GET /v2/api/external/:apiId/getContactExtraInfo?contactId=ID_DO_CONTATO Retorna os campos personalizados (extraInfo) de um contato.

---

✏️ Rotas de Ação e Criação (POST)

Utilize estas rotas para criar registos, atualizar dados ou enviar mensagens complexas.

Gestão de Usuários

• Criar Usuário POST /v2/api/external/:apiId/createUser Body: email, password, name, profile

• Atualizar Usuário POST /v2/api/external/:apiId/updateUser Body: userId, name, email

Mensagens WABA (WhatsApp Oficial)

• Enviar Botões POST /v2/api/external/:apiId/sendButtonWABA Body: number, message, button1, button2, button3, ticketId

• Enviar Lista Interativa POST /v2/api/external/:apiId/sendListWABA Body: number, header, body, footer, button_text, sections, ticketId

Gestão de Contatos

• Atualizar Kanban POST /v2/api/external/:apiId/updateContactKanban Body: contactId, kanban

• Carteirizar Contato (Definir Wallet) POST /v2/api/external/:apiId/updateContactWallet Body: contactId, walletId (ou array de IDs).

• Bloquear/Desbloquear Contato POST /v2/api/external/:apiId/blockContact Body: contactId, blocked (true/false).

• Atualizar Info Adicional POST /v2/api/external/:apiId/updateContactExtraInfo Body: contactId, extraInfo (array).

• Busca Avançada (Ideal para Disparos) POST /v2/api/external/:apiId/contacts/search Busca paginada com filtros avançados, retornando apenas dados essenciais para disparo em massa. Body: tagId (ou array), page, limit, searchParam, walletId, blocked.

Gestão de Tickets

• Alterar Canal do Ticket POST /v2/api/external/:apiId/updateTicketChannel Body: ticketId, whatsappId, channel

• Atualizar Nota Interna POST /v2/api/external/:apiId/updateNote Body: noteId, notes

• Enviar Presence (Digitando...) POST /v2/api/external/:apiId/sendPresence Envia indicadores de estado para o WhatsApp. Body: ticketId, state ("typing", "paused", "recording")

Gestão de Tags (Etiquetas)

• Adicionar Tag (Sem remover as existentes) POST /v2/api/external/:apiId/addTag Body: ticketId, tagId (ou array).

• Remover Tag POST /v2/api/external/:apiId/removeTag Body: ticketId, tagId (ou array).

---

🔐 Tenant API (Exclusivo Superadmin)

Esta rota requer a utilização da chave de API do Superadmin.

• Listar Tenants (Empresas) GET /tenantApiListTenants Lista todos os tenants cadastrados na instalação.

---

🎯 Exemplos de Casos de Uso

1. Disparo em Massa Segmentado Utilize a rota /contacts/search para buscar todos os contatos que possuem uma etiqueta específica (ex: "Lead Quente") e integrar com o N8N para realizar o disparo.

2. Automação de Fluxos

• Utilize /addTag para classificar clientes durante o atendimento automático sem apagar o histórico de tags anteriores.

• Utilize /updateContactWallet para distribuir clientes para a carteira de vendedores específicos automaticamente.

• Utilize /sendPresence para humanizar bots, mostrando o status "Digitando..." antes de enviar a resposta.

3. Integrações Externas Crie usuários automaticamente no Z-PRO (/createUser) quando um novo funcionário for cadastrado no seu sistema de RH ou ERP externo.