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

# Visão Geral da API Pilot Status

> URL base, autenticação x-api-key, escopos de chave e erros HTTP comuns da API de WhatsApp do Pilot Status.

# Visão Geral da API Pilot Status

O Pilot Status é uma plataforma para envio de mensagens de WhatsApp (transacionais e de marketing/em massa) com controle de templates, versionamento e visibilidade operacional via painel, API e webhooks.

## Base URL

```text theme={null}
https://pilotstatus.com.br/v1
```

## Autenticação

Toda requisição exige uma chave de API enviada no cabeçalho `x-api-key` (ou `x-api-key-id` com o ID da chave). As chaves usam o prefixo `ps_`.

<Warning>
  A API **não** usa tokens `Authorization: Bearer`. Sempre autentique com o cabeçalho `x-api-key: ps_...` (ou `x-api-key-id`).
</Warning>

```bash theme={null}
curl "https://pilotstatus.com.br/v1/messages/msg_abc" \
  -H "x-api-key: ps_your_key_here"
```

<Frame caption="Obtenha (ou regenere) sua chave na página API Keys do painel — uma chave padrão por número.">
  <img src="https://mintcdn.com/iaxp/0E19UdwreN9nHBi1/images/dashboard/api-keys.png?fit=max&auto=format&n=0E19UdwreN9nHBi1&q=85&s=c9ee236ce696155795a1b4c612df0d7d" alt="Página de API Keys do Pilot Status" width="1920" height="896" data-path="images/dashboard/api-keys.png" />
</Frame>

### Escopos de chave

| Escopo                           | Vinculado a           | Pode chamar                                                                                                                                                                                                                          |
| -------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Escopo de número** (padrão)    | Um número de WhatsApp | Todos os endpoints de ação/dados desse número: `POST /v1/messages/send`, status de mensagem, cancelamento, grupos, newsletters, templates, analytics, mídia                                                                          |
| **Escopo de tenant** (singleton) | O tenant (sem número) | Gerenciamento em nível de tenant: `/v1/numbers/*`, `/v1/remote-pairing/*`, `/v1/api-keys`, `/v1/branding`, `/v1/webhooks/*`, `/v1/subscription/extra-numbers`, `/v1/billing/checkout` e `/v1/embed/sessions` (superfície de conexão) |

Consulte [Autenticação da API](/pt-BR/api/authentication) para mais detalhes.

## Conceitos principais

* **Template**: um modelo de mensagem versionado referenciado por `templateId` nos envios via API. Para números **Meta**, os templates são submetidos à Meta para aprovação; para números **não oficiais (Pilot Status web)**, eles são criados localmente sem etapa de aprovação.
* **Message**: uma tentativa de envio criada por `POST /v1/messages/send`.
* **Webhooks**: eventos de entrega (sent/delivered/read/failed) e mensagens recebidas (reply/received/group).
* **Confirmações de leitura**: o status `READ`, o `readAt` e o webhook `message.read` só ocorrem quando o contato destinatário tem as confirmações de leitura do WhatsApp habilitadas.

## Fluxo típico de integração

<Steps>
  <Step title="Criar templates">
    Crie templates no painel (`/templates`).
  </Step>

  <Step title="Conectar o WhatsApp">
    Configure seu número/instância de WhatsApp no painel (`/profile` e `/numbers`).
  </Step>

  <Step title="Criar uma chave de API">
    Crie uma chave de API na página `/api-keys`.
  </Step>

  <Step title="Enviar mensagens">
    Envie mensagens com [`POST /v1/messages/send`](/pt-BR/api/messages/send).
  </Step>

  <Step title="Acompanhar a entrega">
    Consulte o status com [`GET /v1/messages/{messageId}`](/pt-BR/api/messages/status) e/ou consuma eventos via webhooks.
  </Step>
</Steps>

## Erros HTTP comuns

| Status | Significado                                                                          |
| ------ | ------------------------------------------------------------------------------------ |
| `400`  | Payload inválido (ex.: telefone fora do formato E.164, campos obrigatórios ausentes) |
| `401`  | Cabeçalho `x-api-key` / `x-api-key-id` ausente ou inválido                           |
| `403`  | Chave válida, mas operação bloqueada (ex.: escopo de chave incorreto)                |
| `404`  | Recurso não encontrado dentro do escopo da chave                                     |
| `429`  | Limite de taxa excedido                                                              |

## Avisos (WhatsApp / antispam)

<Warning>
  Envios em alto volume e não solicitados podem acionar os mecanismos antispam do WhatsApp (limites de taxa, bloqueios e banimentos). Você é responsável pelo opt-in/consentimento e pela conformidade com as leis aplicáveis e as políticas do WhatsApp.
</Warning>