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

# Autenticação na API do PanÐá Zap: Gere e Proteja Tokens

> Como criar uma chave de API do PanÐá Zap em Configurações, enviá-la como token Bearer em cada requisição, armazená-la com segurança e resolver erros 401 Unauthorized.

Toda chamada de API deve incluir um token Bearer no cabeçalho `Authorization`. Não há fluxo OAuth para consumidores da API — você gera um token de longa duração diretamente no painel do PanÐá Zap e o inclui em cada requisição.

## Criando uma Chave de API

<Steps>
  <Step title="Faça login como Administrador">
    Abra o PanÐá Zap e entre com uma conta que tenha privilégios de Administrador.
  </Step>

  <Step title="Vá para Configurações → API">
    Navegue até **Configurações** no menu principal e, em seguida, selecione a aba **API**.
  </Step>

  <Step title="Clique em + Nova API">
    Selecione **+ Nova API** para abrir o formulário de criação de integração.
  </Step>

  <Step title="Nomeie sua integração">
    Dê um nome descritivo que identifique sua finalidade — por exemplo, `Integração CRM` ou `Sincronização E-commerce`. Isso ajuda você a gerenciar várias integrações no futuro.
  </Step>

  <Step title="Selecione uma Sessão">
    Escolha a **Sessão** (canal do WhatsApp) da qual esta integração de API enviará mensagens. Cada integração está vinculada a exatamente um canal. Se precisar enviar de vários canais, crie uma integração de API por canal.
  </Step>

  <Step title="Salve e copie seu token">
    Clique em **Salvar**. Copie o **Bearer Token** exibido imediatamente — ele é mostrado **apenas uma vez**. Anote também o **API ID** mostrado na listagem da integração, pois você precisará dele em toda URL de requisição.
  </Step>
</Steps>

<Warning>
  **Copie seu token agora.** O PanÐá Zap não exibe o Bearer Token novamente depois que você sair desta tela. Se você perdê-lo, precisará rotacionar o token para gerar um novo, o que invalida imediatamente o antigo.
</Warning>

## Usando o Token

Inclua o token Bearer no cabeçalho `Authorization` de toda requisição, e o `{ApiID}` no caminho da URL para rotear a requisição para o canal e o tenant corretos:

```bash theme={null}
curl -X POST https://{BaseUrl}/v2/api/external/{ApiID} \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body": "Hello!", "number": "5511999999999", "externalKey": "key-001"}'
```

Substitua `{BaseUrl}` pelo domínio do seu servidor PanÐá Zap e `{ApiID}` pelo ID da sua listagem de integração.

## Segurança do Token

<Warning>
  **Trate seu token Bearer como uma senha.** Um token concede acesso total à API do tenant que o criou — qualquer pessoa que o possua pode enviar mensagens, ler contatos e gerenciar tickets na sua conta. Não há restrições de escopo.
</Warning>

Siga estas práticas para manter seu token seguro:

* **Nunca faça commit de tokens no controle de versão.** Use variáveis de ambiente ou um gerenciador de segredos para armazená-los.
* **Nunca compartilhe tokens em capturas de tela, mensagens do Slack ou coleções exportadas do Postman** — verifique se o campo *Initial Value* no Postman está sempre vazio (veja [Coleção do Postman](#colecao-do-postman) abaixo).
* **Rotacione quando comprometido.** Vá até **Configurações → API** e clique no ícone de atualização (↺) ao lado da sua integração. O token antigo é invalidado imediatamente — atualize todas as suas integrações antes de rotacionar para evitar interrupções.
* **Armazene em variáveis de ambiente:** referencie seu token como `$PANDAZAP_TOKEN` em scripts e pipelines de CI/CD em vez de fixá-lo no código-fonte.

## Coleção do Postman

Baixe a coleção oficial do Postman diretamente do PanÐá Zap indo em **Configurações → API → Postman**. Após importá-la, configure as variáveis da coleção na aba **Variables**:

* Sempre preencha a coluna **Current Value**, não a **Initial Value** — o Postman inclui os Initial Values quando você exporta ou compartilha uma coleção, o que arrisca expor credenciais.

A coleção usa dois conjuntos de nomes de variáveis dependendo da pasta. Defina ambos os conjuntos com os mesmos valores para que todas as requisições funcionem corretamente:

| Pastas padrão     | Pastas Instagram / Messenger |
| ----------------- | ---------------------------- |
| `{{BaseUrl}}`     | `{{BASE_URL}}`               |
| `{{BearerToken}}` | `{{API_TOKEN}}`              |
| `{{ApiID}}`       | `{{apiId}}`                  |

## Solucionando Erros 401

Se uma requisição retornar uma resposta `401 Unauthorized`, verifique o seguinte:

* O cabeçalho `Authorization` está presente e formatado corretamente — deve conter `Bearer ` (com um espaço) seguido do seu token, sem espaços extras.
* O token não foi rotacionado ou invalidado. Se foi rotacionado recentemente, atualize sua integração para usar o novo token.
* Você está enviando as requisições para o `{BaseUrl}` correto da sua conta PanÐá Zap.

## Gerenciamento de Usuários

Administradores podem criar novos usuários da plataforma de forma programática via API. Isso é útil para provisionar contas de agentes a partir de um sistema externo de RH ou de integração, sem exigir acesso manual ao painel.

```bash theme={null}
curl -X POST https://{BaseUrl}/v2/api/external/{ApiID}/createUser \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "agent@example.com",
    "password": "securePass123",
    "name": "Jane Smith",
    "profile": "user"
  }'
```

| Campo      | Tipo   | Descrição                                                                       |
| ---------- | ------ | ------------------------------------------------------------------------------- |
| `email`    | string | O endereço de e-mail de login do novo usuário. Deve ser único dentro do tenant. |
| `password` | string | Senha inicial da conta. Peça ao usuário para alterá-la no primeiro login.       |
| `name`     | string | Nome de exibição mostrado na plataforma.                                        |
| `profile`  | string | Papel atribuído ao usuário. Use `"user"` para uma conta de agente padrão.       |

Uma resposta bem-sucedida retorna `{"success": true, "data": {...}}` com os detalhes do usuário criado.

## Métricas do Dashboard

Você pode obter contagens de tickets e análises de tempo de resposta para qualquer intervalo de datas usando o endpoint de métricas do dashboard. Isso é útil para construir relatórios personalizados ou sincronizar KPIs com uma ferramenta de BI externa.

```bash theme={null}
curl -X GET "https://{BaseUrl}/v2/api/external/{ApiID}/dash/ticketsAndTimes?startDate=2026-03-01&endDate=2026-03-31" \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"
```

| Parâmetro de consulta | Formato      | Descrição                                   |
| --------------------- | ------------ | ------------------------------------------- |
| `startDate`           | `YYYY-MM-DD` | Início do período do relatório (inclusivo). |
| `endDate`             | `YYYY-MM-DD` | Fim do período do relatório (inclusivo).    |

Uma resposta bem-sucedida retorna `{"success": true, "data": {...}}` contendo o volume de tickets e as métricas de tempo do período especificado.