> ## Documentation Index
> Fetch the complete documentation index at: https://ajuda.pandazap.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API de Contatos: Crie, Pesquise e Gerencie Clientes

> Use a API de Contatos do PanÐá Zap para criar, atualizar, pesquisar, marcar, bloquear, mesclar e gerenciar toda a sua base de contatos de clientes de forma programática.

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

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/createContact
```

```json theme={null}
{
  "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.

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/showcontact
```

```json theme={null}
{ "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.

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/contacts/search
```

```json theme={null}
{
  "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)

```http theme={null}
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.

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/updateContact
```

Aceita os mesmos campos de [Criar contato](#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.

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/updateContactExtraInfo
```

```json theme={null}
{
  "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.

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/updateContactWallet
```

Atribuir uma única carteira:

```json theme={null}
{ "contactId": 1, "walletId": 5 }
```

Atribuir várias carteiras:

```json theme={null}
{ "contactId": 1, "walletIds": [5, 6] }
```

Remover todas as atribuições de carteira:

```json theme={null}
{ "contactId": 1, "walletIds": [] }
```

<Note>
  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.
</Note>

***

## Bloquear ou desbloquear contato

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

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/blockContact
```

```json theme={null}
{ "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).

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/addTagContact
```

```json theme={null}
{ "contactId": 123, "tagId": 1, "validateNumber": true }
```

***

## Remover tag do contato

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/removeTagContact
```

```json theme={null}
{ "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.

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/mergecontacts
```

```json theme={null}
{
  "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.

<Tip>
  Execute primeiro [Encontrar contatos duplicados](#encontrar-contatos-duplicados) para obter uma lista de candidatos e, em seguida, envie os pares diretamente para este endpoint.
</Tip>

***

## 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.

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/findduplicatecontacts
```

```json theme={null}
{ "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. |