> ## 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 Tickets: Crie, Atualize e Consulte Conversas

> Crie, atualize, liste e pesquise tickets de suporte no PanÐá Zap para sincronizar seus dados de conversas e atendimento com sistemas externos.

Toda conversa no PanÐá Zap é representada como um ticket. Use os endpoints abaixo para abrir tickets de forma programática, sincronizar seu status com sistemas externos, marcá-los com tags e roteá-los, anexar notas e fechá-los — tudo sem precisar acessar o painel.

Todas as requisições exigem o cabeçalho `Authorization: Bearer {BearerToken}`.

***

## Criar ticket

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

Abre um novo ticket e, se não existir um ticket aberto ou pendente para o contato, também cria o contato.

```json theme={null}
{
  "body": "Initial message content.",
  "number": "5511999999999",
  "externalKey": "create-ticket-001",
  "userId": 3,
  "status": "pending",
  "validateNumber": true
}
```

| Campo            | Tipo    | Obrigatório | Descrição                                             |
| ---------------- | ------- | ----------- | ----------------------------------------------------- |
| `body`           | string  | Sim         | Primeira mensagem enviada ao contato.                 |
| `number`         | string  | Sim\*       | Número de telefone do contato no formato E.164.       |
| `externalKey`    | string  | Não         | Identificador único do seu sistema para deduplicação. |
| `userId`         | integer | Não         | ID do agente ao qual o ticket será atribuído.         |
| `status`         | string  | Não         | Status inicial: `open` ou `pending`.                  |
| `validateNumber` | boolean | Não         | Valida o número no WhatsApp antes de enviar.          |
| `queueId`        | integer | Não         | Fila à qual o ticket será atribuído.                  |
| `chatFlowId`     | integer | Não         | Fluxo de chat a ser acionado na criação do ticket.    |
| `kanbanId`       | integer | Não         | Card do kanban a ser associado.                       |
| `reasonId`       | integer | Não         | Motivo/categoria do ticket.                           |
| `value`          | number  | Não         | Valor monetário associado ao ticket.                  |

<Note>
  Para o **canal de e-mail**, omita `number` e envie `email` e `channelId` (o ID de um canal de webmail) em vez disso.
</Note>

***

## Listar tickets

```http theme={null}
GET https://{BaseUrl}/v2/api/external/{ApiID}/listTickets?pageNumber=1&status=open
```

Retorna uma lista paginada de tickets filtrada pelos parâmetros fornecidos.

| Query param   | Descrição                                                  |
| ------------- | ---------------------------------------------------------- |
| `pageNumber`  | Página a retornar (padrão: `1`).                           |
| `status`      | Filtra por status: `open`, `pending` ou `closed`.          |
| `searchParam` | Busca por texto livre nos campos do ticket.                |
| `queuesIds`   | Lista de IDs de filas separados por vírgula para filtrar.  |
| `whatsappIds` | Lista de IDs de canais separados por vírgula para filtrar. |

***

## Exibir ticket por número

Retorna o ticket aberto ou pendente mais recente para o número de contato informado.

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

```json theme={null}
{ "number": "5511999999999" }
```

***

## Exibir todos os tickets de um número

Retorna todos os tickets — independentemente do status — associados ao número de contato informado.

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

```json theme={null}
{ "number": "5511999999999" }
```

***

## Exibir ticket por ID

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

```json theme={null}
{ "ticketId": 1262 }
```

***

## Atualizar informações do ticket

Atualize o status, o agente atribuído, a fila, o fluxo de chat, ou ative/desative integrações de automação em um ticket.

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

```json theme={null}
{
  "ticketId": 1262,
  "userId": 1,
  "status": "open",
  "queueId": null,
  "chatFlowId": null,
  "typebotStatus": false,
  "chatgptStatus": false,
  "n8nStatus": false
}
```

| Campo           | Tipo            | Descrição                                                      |
| --------------- | --------------- | -------------------------------------------------------------- |
| `ticketId`      | integer         | **Obrigatório.** Ticket a ser atualizado.                      |
| `userId`        | integer         | Reatribui a um agente diferente.                               |
| `status`        | string          | Novo status: `open`, `pending` ou `closed`.                    |
| `queueId`       | integer \| null | Fila para a qual mover o ticket, ou `null` para desatribuir.   |
| `chatFlowId`    | integer \| null | Fluxo de chat a anexar, ou `null` para desanexar.              |
| `typebotStatus` | boolean         | Ativa ou desativa a integração com o Typebot para este ticket. |
| `chatgptStatus` | boolean         | Ativa ou desativa a integração com o ChatGPT para este ticket. |
| `n8nStatus`     | boolean         | Ativa ou desativa a integração com o n8n para este ticket.     |

***

## Atualizar fila do ticket

Move um ticket para uma fila diferente sem alterar nenhum outro campo.

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

```json theme={null}
{ "ticketId": 4, "queueId": 1 }
```

***

## Adicionar tag ao ticket

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

Adicionar uma única tag:

```json theme={null}
{ "ticketId": 4, "tagId": 1 }
```

Adicionar várias tags de uma vez:

```json theme={null}
{ "ticketId": 4, "tagIds": [1, 2, 3] }
```

***

## Remover tag do ticket

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

```json theme={null}
{ "ticketId": 4, "tagId": 1 }
```

***

## Obter todas as mensagens de um ticket

Obtenha o histórico completo de mensagens de um determinado ticket.

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

```json theme={null}
{ "ticket": "1262" }
```

***

## Pesquisar mensagens dentro de um ticket

```http theme={null}
GET https://{BaseUrl}/v2/api/external/{ApiID}/searchMessages?ticketId=1262&searchParam=invoice&page=1&limit=20
```

| Query param   | Descrição                                                 |
| ------------- | --------------------------------------------------------- |
| `ticketId`    | **Obrigatório.** Ticket no qual pesquisar.                |
| `searchParam` | **Obrigatório.** Palavra-chave ou frase a ser pesquisada. |
| `page`        | Número da página (padrão: `1`).                           |
| `limit`       | Resultados por página (padrão: `20`).                     |

***

## Criar nota interna

Notas internas são visíveis apenas para os agentes e nunca são enviadas ao contato.

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

```json theme={null}
{
  "notes": "Customer confirmed budget availability.",
  "ticketId": 1262,
  "userId": 1,
  "idFront": "note-front-001"
}
```

| Campo      | Tipo    | Descrição                                                              |
| ---------- | ------- | ---------------------------------------------------------------------- |
| `notes`    | string  | **Obrigatório.** Conteúdo da nota.                                     |
| `ticketId` | integer | **Obrigatório.** Ticket ao qual a nota será anexada.                   |
| `userId`   | integer | Agente que está criando a nota.                                        |
| `idFront`  | string  | Chave de idempotência do lado do cliente para evitar notas duplicadas. |

***

## Pausa de ticket

Use a pausa para interromper temporariamente um ticket — por exemplo, enquanto aguarda a resposta de um cliente ou a conclusão de um processo interno.

**Iniciar pausa:**

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/ticket/pause/start/{ticketId}
```

```json theme={null}
{ "pauseReason": "Waiting for customer" }
```

**Encerrar pausa:**

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/ticket/pause/end/{ticketId}
```

Nenhum corpo de requisição é necessário para encerrar uma pausa.

***

## Enviar avaliação de satisfação

Dispare uma pesquisa de satisfação para o contato associado a um ticket.

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

```json theme={null}
{
  "ticketId": 1262,
  "externalKey": "eval-001",
  "force": false
}
```

| Campo         | Tipo    | Descrição                                                                                        |
| ------------- | ------- | ------------------------------------------------------------------------------------------------ |
| `ticketId`    | integer | **Obrigatório.** Ticket para o qual enviar a avaliação.                                          |
| `externalKey` | string  | Chave única para deduplicação.                                                                   |
| `force`       | boolean | Defina como `true` para reenviar mesmo que uma avaliação já tenha sido enviada para este ticket. |