API de Contatos: Crie, Pesquise e Gerencie Clientes

Os contatos são a base de toda conversa no PanÐá Zap. Use os endpoints abaixo para manter seu banco de dados de contatos sincronizado com o seu CRM, marcar e segmentar contatos, gerenciar carteiras de contas e resolver registros duplicados. Todas as requisições exigem o cabeçalho Authorization: Bearer {BearerToken}.

Criar contato

POST https://{BaseUrl}/v2/api/external/{ApiID}/createContact

{
  "name": "Maria Silva",
  "number": "5511999999999",
  "email": "maria@example.com",
  "firstName": "Maria",
  "lastName": "Silva",
  "businessName": "Acme Corp",
  "birthdayDate": "15/06/1990",
  "externalKey": "crm-contact-4521",
  "validateNumber": true
}

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome completo de exibição.
`number`	string	Sim	Número de telefone no formato E.164.
`email`	string	Não	Endereço de e-mail do contato.
`firstName`	string	Não	Primeiro nome (usado na personalização de mensagens).
`lastName`	string	Não	Sobrenome.
`businessName`	string	Não	Nome da empresa ou organização.
`birthdayDate`	string	Não	Data de nascimento no formato `DD/MM/YYYY`.
`externalKey`	string	Não	Identificador único do seu sistema externo.
`validateNumber`	boolean	Não	Valida o número no WhatsApp antes de salvar.

Exibir contato por número

Obtenha um único registro de contato pelo número de telefone.

POST https://{BaseUrl}/v2/api/external/{ApiID}/showcontact

{ "number": "5511999999999", "validateNumber": true }

Pesquisar contatos

Pesquise sua lista de contatos usando uma consulta de texto livre ou filtre por tags, carteira ou status de bloqueio.

POST https://{BaseUrl}/v2/api/external/{ApiID}/contacts/search

{
  "searchParam": "Maria",
  "page": 1,
  "limit": 40,
  "tagId": 5
}

Campo	Tipo	Descrição
`searchParam`	string	Fragmento de nome, número ou e-mail a ser pesquisado.
`page`	integer	Número da página (padrão: `1`).
`limit`	integer	Resultados por página (padrão: `40`).
`tagId`	integer	Filtra contatos por um único ID de tag.
`tagIds`	integer[]	Filtra contatos que correspondam a qualquer um dos IDs de tag fornecidos.
`walletId`	integer	Filtra contatos atribuídos a uma carteira de conta específica.
`blocked`	boolean	Filtra por status de bloqueio (`true` ou `false`).

Listar contatos (paginado)

GET https://{BaseUrl}/v2/api/external/{ApiID}/listContacts?pageNumber=1&searchParam=Maria&tagId=5

Query param	Descrição
`pageNumber`	Página a retornar (padrão: `1`).
`searchParam`	Busca por texto livre em nome, número e e-mail.
`tagId`	Filtra por ID de tag.

Atualizar contato

Atualiza um registro de contato existente. Identifique o contato incluindo o number no corpo da requisição. Todos os outros campos são opcionais — apenas os campos que você incluir serão atualizados.

POST https://{BaseUrl}/v2/api/external/{ApiID}/updateContact

Aceita os mesmos campos de Criar contato, além de:

Campo	Tipo	Descrição
`number`	string	Obrigatório. Identifica o contato a ser atualizado.
`kanban`	integer	Associa o contato a um ID de card do Kanban.

Atualizar campos personalizados (extraInfo)

Armazene pares chave-valor arbitrários em um contato para guardar dados de CRM, números de contrato, segmentos, ou qualquer outra informação estruturada.

POST https://{BaseUrl}/v2/api/external/{ApiID}/updateContactExtraInfo

{
  "contactId": 1,
  "extraInfo": [
    { "name": "Contract Number", "value": "CTR-2024-001" },
    { "name": "Segment", "value": "Enterprise" }
  ]
}

Campo	Tipo	Descrição
`contactId`	integer	Obrigatório. ID do contato a ser atualizado.
`extraInfo`	object[]	Obrigatório. Array de pares `{ name, value }` a serem definidos.

Atribuir contato a uma carteira

Uma carteira é uma atribuição de gerente de conta ou responsável. Enviar esta requisição substitui completamente as atribuições de carteira atuais do contato.

POST https://{BaseUrl}/v2/api/external/{ApiID}/updateContactWallet

Atribuir uma única carteira:

{ "contactId": 1, "walletId": 5 }

Atribuir várias carteiras:

{ "contactId": 1, "walletIds": [5, 6] }

Remover todas as atribuições de carteira:

{ "contactId": 1, "walletIds": [] }

A lista walletIds substitui todas as atribuições de carteira existentes para o contato. Para remover uma única carteira sem afetar as demais, primeiro recupere as carteiras atuais e envie de volta a lista sem a que você deseja remover.

Bloquear ou desbloquear contato

Bloquear um contato impede que mensagens recebidas desse número abram novos tickets.

POST https://{BaseUrl}/v2/api/external/{ApiID}/blockContact

{ "contactId": 1, "blocked": true }

Defina "blocked": false para desbloquear.

Adicionar tag ao contato

Aplique uma tag diretamente a um contato (sem exigir um ticket aberto).

POST https://{BaseUrl}/v2/api/external/{ApiID}/addTagContact

{ "contactId": 123, "tagId": 1, "validateNumber": true }

Remover tag do contato

POST https://{BaseUrl}/v2/api/external/{ApiID}/removeTagContact

{ "number": "5511999999999", "tagIds": [1, 2], "validateNumber": true }

Passe vários IDs em tagIds para remover várias tags em uma única chamada.

Mesclar contatos duplicados

Consolide registros de contato duplicados. O registro primaryId é mantido e o registro duplicateId é mesclado nele. Você pode enviar até 150 pares por requisição.

POST https://{BaseUrl}/v2/api/external/{ApiID}/mergecontacts

{
  "pairs": [
    { "primaryId": 123, "duplicateId": 456 },
    { "primaryNumber": "5511999999999", "duplicateNumber": "551199999999" }
  ]
}

Você pode identificar contatos por ID (primaryId / duplicateId) ou por número de telefone (primaryNumber / duplicateNumber). Os dois estilos podem ser combinados na mesma requisição.

Execute primeiro Encontrar contatos duplicados para obter uma lista de candidatos e, em seguida, envie os pares diretamente para este endpoint.

Encontrar contatos duplicados

Escaneie seu banco de dados de contatos em busca de possíveis duplicatas e retorne uma lista de pares candidatos para revisão.

POST https://{BaseUrl}/v2/api/external/{ApiID}/findduplicatecontacts

{ "limit": 500, "matchKinds": ["nine_digit_variant", "cross_collision"] }

Campo	Tipo	Descrição
`limit`	integer	Número máximo de pares duplicados a retornar.
`matchKinds`	string[]	Estratégias de detecção a usar. `nine_digit_variant` identifica números que diferem apenas pelo prefixo do 9º dígito brasileiro; `cross_collision` identifica números correspondentes entre DDDs diferentes.

Primeiros Passos

Mensagens

Tickets e Contatos

Campanhas e CRM

Webhooks e Eventos

API de Contatos: Crie, Pesquise e Gerencie Clientes

Criar contato

Exibir contato por número

Pesquisar contatos

Listar contatos (paginado)

Atualizar contato

Atualizar campos personalizados (extraInfo)

Atribuir contato a uma carteira

Bloquear ou desbloquear contato

Adicionar tag ao contato

Remover tag do contato

Mesclar contatos duplicados

Encontrar contatos duplicados

​Criar contato

​Exibir contato por número

​Pesquisar contatos

​Listar contatos (paginado)

​Atualizar contato

​Atualizar campos personalizados (extraInfo)

​Atribuir contato a uma carteira

​Bloquear ou desbloquear contato

​Adicionar tag ao contato

​Remover tag do contato

​Mesclar contatos duplicados

​Encontrar contatos duplicados

Criar contato

Exibir contato por número

Pesquisar contatos

Listar contatos (paginado)

Atualizar contato

Atualizar campos personalizados (extraInfo)

Atribuir contato a uma carteira

Bloquear ou desbloquear contato

Adicionar tag ao contato

Remover tag do contato

Mesclar contatos duplicados

Encontrar contatos duplicados