Pular para o conteúdo principal
A API de CRM do PanÐá Zap permite construir e gerenciar todo o seu fluxo de vendas de forma programática: desde a criação de estruturas de pipeline e o acompanhamento de oportunidades até o agendamento de compromissos e a automação de lembretes. Todas as requisições exigem o cabeçalho Authorization: Bearer {BearerToken}.

Pipelines

Um pipeline é um funil de vendas nomeado que contém etapas ordenadas. Crie quantos pipelines forem necessários para representar diferentes produtos, equipes ou processos de vendas.

Criar pipeline

O pipeline só tem nome: não existe campo de descrição. Depois de criar, monte as etapas com Criar etapa.

Listar pipelines

Exibir pipeline

Atualizar pipeline

Pipeline que não existe na sua empresa responde 404 ERR_PIPELINE_NOT_FOUND.

Excluir pipeline

Só é aceito quando o pipeline não tem etapas, oportunidades nem ações vinculadas; caso contrário, a rota responde 500. Apague as etapas e oportunidades antes. Pipeline que não existe na sua empresa responde 404 ERR_PIPELINE_NOT_FOUND.

Etapas

As etapas são as colunas ordenadas dentro de um pipeline, por exemplo: “Lead”, “Proposta Enviada”, “Negociação” e “Fechado”.

Criar etapa

Só name, pipelineId, order, color, notifyUserId e notifyQueueId são lidos; outros campos são ignorados. O pipelineId precisa ser um pipeline da sua empresa (senão 404 ERR_PIPELINE_NOT_FOUND); notifyUserId e notifyQueueId, um usuário e uma fila da sua empresa (senão 404 ERR_USER_NOT_FOUND ou ERR_QUEUE_NOT_FOUND). O aviso de notifyUserId e notifyQueueId só sai quando alguém da equipe move a oportunidade para a etapa pelo painel: mover pela API, com Atualizar oportunidade, ou criar a oportunidade já na etapa não avisa ninguém.

Listar etapas por pipeline

O parâmetro pipelineId é obrigatório: ele define de qual pipeline as etapas são listadas.

Exibir etapa

Atualizar etapa

Só os campos enviados mudam. Aceita name, order (posição da etapa), color (cor em hexadecimal), pipelineId, notifyUserId e notifyQueueId (usuário e fila avisados quando alguém da equipe move uma oportunidade para a etapa pelo painel; null tira o aviso). Outros campos são ignorados. Erros:
  • pipelineId que não é de um pipeline da sua empresa: 404 ERR_PIPELINE_NOT_FOUND.
  • notifyUserId ou notifyQueueId que não é de um usuário ou de uma fila da sua empresa: 404 ERR_USER_NOT_FOUND ou ERR_QUEUE_NOT_FOUND.
  • Etapa que não existe na sua empresa: 404 ERR_STAGE_NOT_FOUND.

Excluir etapa

Só é aceito quando nenhuma oportunidade ou ação aponta para a etapa; caso contrário, a rota responde 500. Contam também as oportunidades ganhas ou perdidas (que o Kanban do Funil esconde enquanto o filtro Status está em Aberto, o padrão) e as ações desativadas. Mova as oportunidades para outra etapa antes, com Atualizar oportunidade. Etapa que não existe na sua empresa responde 404 ERR_STAGE_NOT_FOUND.

Oportunidades

Uma oportunidade representa um negócio em andamento, vinculado a um contato e a uma etapa dentro de um pipeline.

Criar oportunidade

A rota responde 201 Created com a oportunidade criada, incluindo o contactId do contato vinculado. Se já existir um contato com o número informado, a oportunidade é vinculada a ele. Outros campos do corpo são ignorados.
  • Exige que o token da API tenha um canal vinculado: sem canal, a rota responde 400 ERR_API_REQUIRES_SESSION.
  • Com status win ou lose, a data de fechamento é gravada na hora (ela é diferente da previsão closingForecast).
  • As Ações do Funil configuradas para a etapa passam a valer para a oportunidade, com os dias contados a partir da criação dela.
Diferenças em relação à oportunidade criada pelo painel: a criada pela API não avisa a fila nem o atendente configurados na etapa (Notificar fila ao entrar e Notificar atendente ao entrar), não dispara os webhooks de oportunidade e fica sem criador. Com a Privacidade do Funil ligada, no painel ela aparece para o responsável e para quem vê todas as oportunidades.
Erros (400):

Atualizar oportunidade

Só opportunityId é obrigatório. Envie apenas os campos a alterar: name, value, status, pipelineId, stageId, responsibleId, closingForecast e description.
  • Campo ausente fica como está. Nos demais campos, enviar vazio ou null também deixa como está, exceto description e closingForecast: neles, vazio ou null limpam o valor.
  • Valem as mesmas regras de Criar oportunidade: pipelineId, stageId e responsibleId da sua empresa, value numérico, status open, win ou lose e closingForecast em AAAA-MM-DD, DD/MM/AAAA ou data e hora ISO 8601.
  • A etapa precisa ser do pipeline da oportunidade (ou do pipelineId enviado). Para trocar de pipeline, envie também um stageId desse pipeline.
  • O contato da oportunidade não muda por esta rota.
  • Mudar status para win ou lose grava a data de fechamento (usada no Dashboard do Funil quando Contar por está em Data de fechamento, no relatório Funil por atendente e nas ações Ao marcar como Ganha); voltar para open apaga essa data.
  • Mover a oportunidade de etapa pela API não avisa a fila nem o atendente configurados na etapa e não dispara os webhooks de oportunidade.
  • A Privacidade do Funil não se aplica à API: o token alcança todas as oportunidades da empresa.
Erros:

Listar oportunidades

A resposta traz as oportunidades em data.data, cada uma com os dados do contato (contact), e a paginação em data.pagination.
A Privacidade do Funil (Configurações Gerais) não se aplica à API: a listagem traz as oportunidades de toda a empresa.

Excluir oportunidade

O ID vai no corpo, não na URL. Exige que o token da API tenha um canal vinculado: sem canal, a rota responde 400 ERR_API_REQUIRES_SESSION. A exclusão pela API não dispara o webhook de exclusão de oportunidade.

Agendamentos

Os agendamentos são eventos programados vinculados a um contato e, opcionalmente, a um canal do WhatsApp. Em todas as rotas de agendamento, um {ApiID} da URL que não existe na sua empresa responde 404 ERR_API_CONFIG_NOT_FOUND.

Criar agendamento

Formatos de data aceitos

startAt e endAt aceitam:
  • AAAA-MM-DD, com ou sem hora: 2025-01-15, 2025-01-15T14:30:00 ou 2025-01-15 14:30.
  • Fuso opcional Z, ±HH:mm ou ±HHmm: 2025-01-15T14:30:00-03:00 ou 2025-01-15T17:30:00.000Z.
  • DD/MM/AAAA, com hora opcional HH:mm ou HH:mm:ss: 15/01/2025 ou 15/01/2025 14:30. Com barra é sempre dia/mês/ano.
Sem fuso, a hora vale no fuso horário do servidor: mande o fuso (por exemplo, -03:00) para não depender dele. Só a data vira 00:00 desse dia. Número (timestamp) ou outro formato responde 400.
O atendente responsável é definido pelo userId; sem ele, o agendamento nasce sem atendente vinculado. Outros campos do corpo são ignorados: location, meetingLink e checkInStatus só podem ser definidos em Atualizar agendamento. Os lembretes automáticos (veja Lembretes Agendados) disparam com base no startAt.
Erros:

Listar agendamentos

Os agendamentos vêm em ordem de início (startAt). startFrom e startTo aceitam os mesmos formatos de data de Criar agendamento (com barra é sempre DD/MM/AAAA), e sem fuso vale o fuso horário do servidor. Só a data vale 00:00 desse dia: para incluir o último dia inteiro, mande a hora em startTo (por exemplo, 31/01/2025 23:59:59). Data fora desses formatos responde 400 com ERR_INVALID_FIELD, e o campo field indica startFrom ou startTo. A resposta traz a lista em data e a paginação em pagination (total, page, limit e hasMore).

Exibir agendamento

Atualizar agendamento

Só os campos enviados mudam. Aceita os mesmos campos de Criar agendamento e também checkInStatus, location e meetingLink; outros campos são ignorados. Exemplo:
Erros:
Para remarcar, use startAt (e endAt). Campo com outro nome é descartado sem erro: a chamada responde normalmente, mas o horário não muda. Para confirmar, cancelar ou concluir, altere o status (confirmed, cancelled ou completed).

Excluir agendamento

Para apenas cancelar mantendo o histórico, prefira atualizar o agendamento com "status": "cancelled".

Lembretes Agendados

Os lembretes agendados são regras reutilizáveis que enviam automaticamente uma mensagem do WhatsApp a um contato um determinado número de horas antes do seu compromisso. O lembrete não tem data própria: ele dispara hoursBeforeEvent horas antes de cada agendamento. Em todas as rotas de lembrete, um {ApiID} da URL que não existe na sua empresa responde 404 ERR_API_CONFIG_NOT_FOUND.

Criar lembrete agendado

Sem hoursBeforeEvent ou messageType, a rota responde 400 ERR_MISSING_FIELDS (a resposta traz fields com o que faltou). Valor fora do tipo esperado responde 400 ERR_INVALID_FIELD, com o nome do campo em field. Variáveis de personalização:

Listar lembretes agendados

Retorna todos os lembretes, do mais recente para o mais antigo, sem paginação e sem filtros.

Alternar estado ativo do lembrete agendado

Inverte a flag active: se estava ativo fica inativo, e vice-versa. Nenhum corpo de requisição é necessário. A rota não é idempotente: repetir a chamada desfaz a anterior. Se precisar de um estado específico, consulte o estado atual na listagem antes.

Atualizar lembrete agendado

Aceita os mesmos campos de Criar lembrete agendado: name, description, hoursBeforeEvent, messageType, messageContent, whatsappId e active. Campo com outro nome é descartado sem erro. Erros:
  • whatsappId precisa ser um canal da sua empresa (senão 404 ERR_NO_WAPP_FOUND); null tira o canal.
  • hoursBeforeEvent (número inteiro), messageType (message ou waba_template) e active (true ou false) fora do tipo respondem 400 ERR_INVALID_FIELD, com o nome do campo em field.
  • Lembrete que não existe: 404 ERR_REMINDER_NOT_FOUND.
  • {ApiID} da URL que não existe na sua empresa: 404 ERR_API_CONFIG_NOT_FOUND.

Excluir lembrete agendado


Métricas do Dashboard

Obtenha os indicadores gerais de atendimento de um período: quantidade de atendimentos, demanda ativa e receptiva, tempos médios e novos contatos. As demais rotas de métricas estão na página API de Métricas do Dashboard.
Exemplo de resposta:
Os totais vêm como texto (entre aspas), e o resultado fica dentro de uma lista em data.