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

# Requisições à API pela CLI

> Envie uma requisição autenticada à API e escolha como a CLI imprime a resposta.

Instale o pré-lançamento de desenvolvimento publicado da CLI com Node.js 22 ou
posterior:

```bash theme={null}
npm install -g @polymorfa/cli@0.1.0-dev.0
polymorfa --version
```

Este pré-lançamento inclui os comandos abaixo. Mantenha as credenciais em
variáveis de ambiente, em um gerenciador de segredos ou em um perfil de
autenticação da CLI.

Use `polymorfa api` para enviar uma requisição pela CLI com a credencial
escolhida. Passe um caminho relativo que comece com `/` e escolha `messaging` ou
`platform` como a superfície da credencial:

```bash theme={null}
polymorfa api /platform/customers --surface platform
```

O comando usa GET, a menos que você defina `-X/--method`. Forneça uma
credencial à CLI por meio de `POLYMORFA_API_KEY` ou de um perfil de autenticação
configurado. Mantenha as chaves da equipe em um ambiente confiável. A API
continua aplicando as permissões e o acesso a projetos dessa credencial.

## Verifique a configuração da CLI

Execute `polymorfa doctor` antes de investigar um problema em uma requisição à
API. Ele verifica a versão do Node.js, a configuração de perfis, o acesso ao
keyring, a conectividade com a API e a autenticação da chave de API de servidor:

```bash theme={null}
polymorfa doctor --json
```

O comando sai com `0` quando todas as verificações obrigatórias são concluídas.
Ele sai com `1` se uma verificação falhar ou se a validação da credencial for
ignorada. Uma credencial ausente ou várias variáveis de ambiente de credencial
fazem a verificação falhar. Um token de projeto ou de cliente é informado como
presente, mas o `doctor` não consegue validá-lo remotamente e sai com `1`; isso
não determina se esse token pode acessar um comando específico. Use uma única
chave de API de servidor para verificar a autenticação. Uma resposta `401`
falha; uma resposta `403` gera um aviso de que a chave foi autenticada, mas a
listagem de projetos foi negada. `--profile <name>` seleciona esse perfil em vez
das credenciais do ambiente. A saída não inclui os valores das credenciais.

## Complete comandos no seu shell

Depois de instalar a CLI, carregue o script de autocompletar do seu shell:

```bash theme={null}
source <(polymorfa completion bash)
```

No Zsh, inicialize o autocompletar antes de carregar o script:

```zsh theme={null}
autoload -Uz compinit && compinit
source <(polymorfa completion zsh)
```

No Fish:

```fish theme={null}
polymorfa completion fish | source
```

Pressione Tab depois de `polymorfa` para completar comandos, ou depois de um
comando para completar as flags dele. O script também sugere as opções fixas de
flag quando um comando as define. Ele usa informações da CLI instalada e não
consulta perfis, IDs de projeto, credenciais nem outros valores de argumento.
Você pode adicionar o comando de carregamento ao arquivo de inicialização do
seu shell para as próximas sessões.

## Inicie um projeto Node

Execute `init` em um diretório onde você queira um projeto inicial em Node.js e
TypeScript:

```bash theme={null}
polymorfa init
```

O comando grava `package.json`, `src/index.ts`, `.env.example` e um README. Ele
recusa a execução, antes de gravar qualquer coisa, se já existir um arquivo
inicial ou um diretório `src`. Nenhuma credencial nem vínculo com projeto é
criado. O pacote fixa a versão de desenvolvimento exata publicada do SDK. Execute
`npm install` e `npm run typecheck` no diretório do projeto inicial e depois
defina `POLYMORFA_API_KEY` no seu shell ou gerenciador de segredos antes de
`npm start`.

Use `polymorfa link` separadamente quando quiser que os comandos da CLI usem um
projeto.

## Inspecione sessões

Use uma chave de API da equipe com `sessions:read` para inspecionar os metadados
das sessões:

```bash theme={null}
polymorfa session list
polymorfa session list --project PROJECT_ID --json
polymorfa session view SESSION_ID
polymorfa session status SESSION_ID --json
```

`session list` retorna todas as sessões da equipe, a menos que você passe um ID
de projeto. Use um ID de sessão dessa lista em `view` ou `status`. Esses dois
comandos recusam `--project` porque o ID da sessão identifica uma única sessão
em toda a equipe. `status` mostra o status armazenado e o motivo; ele não testa
a conexão em tempo real.

## Descubra as sessões do projeto pelo MCP local

Execute `polymorfa mcp tools` para listar as ferramentas do MCP local.

Instale o servidor MCP local no seu cliente de agente com
`polymorfa mcp install codex` ou `polymorfa mcp install claude`. Forneça à CLI
uma chave de API da equipe com `sessions:read`. A ferramenta somente leitura
`polymorfa_session_list` exige um UUID de projeto explícito e retorna o ID, o
nome, o status armazenado e o indicador de modo de teste de cada sessão. Ela não
retorna números de telefone, credenciais nem dados de mensagens, e não testa uma
conexão em tempo real. Tokens de projeto e tokens de cliente da Messaging não
podem usar essa ferramenta.

O servidor MCP local também expõe ferramentas para iniciar, consultar o status
e parar o listener. O [servidor MCP hospedado](/pt-br/integrations/mcp-server) é
uma conexão separada.

## Encontre documentação

Pesquise na documentação publicada:

```bash theme={null}
polymorfa docs search "rate limits"
```

O comando imprime os títulos, caminhos e links das páginas correspondentes. Ele
pesquisa o índice da documentação publicada e precisa de acesso à rede, mas não
usa as suas credenciais da Polymorfa. Adicione `--json` para receber os mesmos
resultados como um array JSON.

Abra uma página pelo caminho mostrado nos resultados:

```bash theme={null}
polymorfa docs open api/rate-limits
```

Use `--print` para obter a URL sem abrir um navegador. Um segmento final curto
do caminho só funciona quando identifica uma única página; use o caminho
completo quando várias páginas tiverem o mesmo nome.

## Encaminhe eventos para um handler local

`polymorfa listen` transmite os eventos do projeto e encaminha os corpos exatos
de evento disponíveis para um handler. Use uma chave da equipe ou uma credencial
de projeto com `events:listen`. Defina `POLYMORFA_API_KEY` ou
`POLYMORFA_PROJECT_TOKEN`, ou selecione um perfil de autenticação.

Passe o endereço do handler e grave em um arquivo privado o segredo local de
assinatura, gerado a cada execução:

```bash theme={null}
polymorfa listen --project PROJECT_ID \
  --forward-to https://127.0.0.1:3000/webhooks \
  --forward-secret-out ./local-forwarding.secret \
  -H 'X-Local-Mode: test' --skip-verify --json
```

O encaminhamento exige os bytes exatos da carga. Para eventos de um número,
ative o armazenamento hospedado de mensagens desse número; os corpos das
mensagens não são retidos por padrão. Se o corpo não estiver disponível, o
listener informa `event_unavailable` e interrompe o encaminhamento com
`forwarding_failed`, em vez de enviar metadados no lugar dele. Consulte
[disponibilidade da carga do evento](/api/event-streams#read-an-event) para ver
as outras condições que podem deixar um corpo indisponível.

Verifique a assinatura local antes de processar um corpo encaminhado. Em um
handler TypeScript que usa o [pré-lançamento de desenvolvimento do SDK](/pt-br/sdks/overview),
passe os bytes da requisição sem parsing, o cabeçalho `Polymorfa-Local-Signature`
e o segredo da execução para `webhooks.verifyLocal`:

```ts theme={null}
import { readFile } from "node:fs/promises";
import { webhooks } from "@polymorfa/sdk";

async function verifyForwardedEvent(request: Request) {
  const rawBody = new Uint8Array(await request.arrayBuffer());
  const signature = request.headers.get("Polymorfa-Local-Signature") ?? "";
  const secret = (await readFile("./local-forwarding.secret", "utf8")).trim();
  return webhooks.verifyLocal({ body: rawBody, signature, secret });
}
```

`verifyLocal` rejeita uma assinatura inválida ou um carimbo de data e hora com
mais de 300 segundos de diferença do relógio do handler. Rejeite a requisição
quando a verificação falhar. Não faça o parsing nem serialize o corpo de novo
antes da verificação. O segredo local de assinatura é separado do segredo do
seu webhook de produção.

`-H` adiciona um cabeçalho personalizado às requisições encaminhadas. Repita a
opção para adicionar mais cabeçalhos. Ela não substitui os cabeçalhos de
autenticação, de enquadramento do corpo nem de assinatura da Polymorfa. A CLI
não repete os valores de cabeçalho recusados. Cabeçalhos personalizados não
atravessam um redirecionamento que muda a origem. Mantenha valores secretos
fora dos argumentos de comando.

`--skip-verify` aceita um certificado autoassinado somente para um destino de
encaminhamento HTTPS em loopback. Ele não altera a verificação de TLS da API da
Polymorfa nem de destinos de encaminhamento públicos. Omita a opção quando o seu
handler tiver um certificado confiável. `--json` imprime registros JSONL para as
transições do listener, incluindo os eventos recebidos; os heartbeats do
servidor não geram registros de saída. O encaminhamento em JSON ou em um
terminal não interativo exige `--forward-secret-out`.

## Leia todas as páginas

Para um endpoint que retorna `page.nextCursor`, adicione `--paginate`. A CLI
envia cada cursor de volta no parâmetro de consulta `cursor`. Ela para se a API
indicar mais páginas sem um cursor, repetir um cursor ou ultrapassar
`--max-pages` (100 por padrão).

```bash theme={null}
polymorfa api /platform/customers --surface platform --paginate
```

A saída para humanos imprime cada página assim que ela chega. `--json` imprime
um único documento com `data` definido como um array dos corpos das páginas. O
`metadata` dele contém o status e o ID da requisição da resposta final, quando
existirem, além da contagem de páginas. Use `--include` para uma saída para
humanos que inclua os metadados de cada resposta. Para reunir esses resultados
de página em um único array, combine-o com `--slurp`:

```bash theme={null}
polymorfa api /platform/customers --surface platform --paginate --slurp --include
```

`--paginate` aceita apenas requisições GET. Deixe o parâmetro de consulta
`cursor` fora do caminho quando a CLI gerenciar a paginação.

## Filtre ou formate uma resposta

`--jq` executa uma expressão jq em cada página. Ele imprime strings sem aspas e
preserva espaços e quebras de linha dentro dos valores de string:

```bash theme={null}
polymorfa api /platform/customers --surface platform --paginate \
  --jq '.data[].id'
```

Use `--slurp` para passar à expressão um único array com os corpos das páginas:

```bash theme={null}
polymorfa api /platform/customers --surface platform --paginate --slurp \
  --jq 'map(.data | length) | add'
```

`--template` aceita caminhos, `range`, `if` e literais de string. Strings entre
aspas podem conter `}}` sem fechar a ação:

```bash theme={null}
polymorfa api /platform/customers --surface platform \
  --template '{{range .data}}{{.id}}{{"\\n"}}{{end}}'
```

`--jq`, `--template` e `--json` são mutuamente exclusivos. `--include` não pode
ser combinado com nenhum dos dois filtros. `--slurp` exige `--paginate`.

## Leia as análises do WhatsApp

Ative as Análises no Console e depois use uma credencial confiável com
`sessions:read`. Selecione um projeto e, se quiser, o UUID do registro de um
número:

```bash theme={null}
polymorfa analytics get --project "$PROJECT_ID" \
  --session-id "$NUMBER_ID" \
  --since 2026-09-01T00:00:00Z --until 2026-10-01T00:00:00Z --json
```

Omita `--session-id` para ler todos os números do projeto. Uma credencial da
organização pode omitir `--project` para ler a equipe. Uma credencial de projeto
fica restrita ao próprio projeto. `--since` e `--until` aceitam datas com fuso
horário explícito; o intervalo máximo é de 366 dias e o padrão são os 30 dias
anteriores.

A tabela mostra atividade, taxas de leitura e de resposta, tempo de resposta e
problemas de conexão. `--json` retorna a resposta completa da API, incluindo
comparações por tipo e tamanho de mensagem, participação por código de chamada
e por dispositivo, respostas pelo celular, atividade dos clientes e o retrato
atual da fila de respostas. Preserve as taxas anuláveis e os indicadores de
cobertura. A saída para humanos inclui as taxas de atendimento de chamadas, as
chamadas recebidas perdidas, os tempos até o atendimento e as taxas de
retorno, mesmo quando não há telemetria de mensagens. O JSON inclui a cobertura
do tempo das chamadas, os detalhamentos de qualidade e de erros e as séries
diárias de chamadas por número. Com as análises desativadas, nenhum agregado do
negócio é retornado.

Consulte [Análises do WhatsApp](/pt-br/console/analytics) para ver as definições das
medições.

## Exporte métricas de análises

Use a build a partir do código-fonte da CLI para gravar um snapshot compatível
com coletores:

```bash theme={null}
polymorfa analytics metrics --project "$PROJECT_ID" \
  --window-hours 24 --format openmetrics > analytics.om
```

Adicione `--session-id` para selecionar o UUID do registro de um número ou
`--segments` para detalhamentos por metadados. `--json` envolve o texto das
métricas e os metadados HTTP em uma resposta JSON. A saída padrão é o texto das
métricas. As versões publicadas da CLI podem ser anteriores a este comando.

Estes valores são gauges de janelas sobrepostas, não contadores monotônicos.
Consulte a [configuração de coletores](/pt-br/console/analytics-collectors) para ver
a autenticação, as definições das métricas e a configuração do OpenTelemetry.

### Intervalos observados do celular

As respostas de análises incluem, em `accountActivity`, as somas de duração da
atividade do celular, as contagens de intervalos concluídos, as somas e
contagens dos períodos sem atividade e as médias correspondentes. As linhas das
séries incluem somas e contagens para comparações ponderadas. As séries de
atividade usam intervalos por hora para períodos de até 48 horas e intervalos
diários em UTC para períodos mais longos. Essas observações não medem se o
celular está ligado nem o tempo online/offline verificado. Leia as
[definições dos intervalos](/pt-br/console/analytics#atividade-do-celular-da-polymorfa-e-dos-clientes)
antes de interpretá-las. A saída JSON preserva as médias ausentes como `null`.

## Limites de gastos e ordem de cobrança

Use uma chave da organização com `billing:read` para leituras ou
`billing:manage` para gravações. As gravações exigem Pay-As-You-Go. Credenciais
de projeto e de cliente não acessam esses controles.

```bash theme={null}
polymorfa api /platform/billing/limits --surface platform
polymorfa api /platform/billing/priorities --surface platform
```

Use a revisão da resposta ao alterar um limite ou uma prioridade. Para a ordem
de projetos ou de números, envie a lista completa, da maior prioridade para a
menor, e a revisão da equipe inteira para `PUT /platform/billing/priorities`.
Uma ordem desatualizada ou incompleta falha sem alterações parciais. Consulte
[reorder priorities](/api-reference/platform/billing/reorder-billing-priorities)
e [set a limit](/api-reference/platform/billing/set-billing-limit) para ver os
corpos das requisições.

### Controles financeiros por recurso

Use a credencial da organização com `billing:read` ou `billing:manage` e um UUID
de projeto, cliente ou número. Leia um único recurso antes de salvar para obter
`expectedBudgetRevision` e `expectedPriorityRevision`:

```bash theme={null}
polymorfa api '/platform/billing/controls/customer/CUSTOMER_UUID' --surface platform
polymorfa api '/platform/billing/controls/customer/CUSTOMER_UUID' --surface platform -X PUT --input controls.json
```

`controls.json` contém `limitCredits`, `priority`, `expectedBudgetRevision` e
`expectedPriorityRevision`. Um valor desatualizado retorna um conflito sem
alterar nenhuma das configurações. `limitCredits: null` remove o limite. A
criação de um QuickLink real aceita `billingControls` na entrada JSON; ela exige
uma credencial financeira da equipe e Pay-As-You-Go. Links de teste e
suplementares recusam controles financeiros iniciais.

### Ranking de prioridades com financiamento misto

Leia as prioridades de um projeto com `GET /platform/billing/priorities?projectId=PROJECT_UUID`.
Reordene os clientes e os números reais do projeto juntos com `PUT /platform/billing/priorities`:

```json theme={null}
{
  "scope": "resource",
  "projectId": "22222222-2222-4222-8222-222222222222",
  "resources": [
    { "scope": "number", "resourceId": "33333333-3333-4333-8333-333333333333" },
    { "scope": "customer", "resourceId": "44444444-4444-4444-8444-444444444444" }
  ],
  "expectedRevision": 5
}
```

Inclua todos os clientes ativos e números reais do projeto escolhido. Use a
revisão da leitura; alterações simultâneas retornam 409. Dentro do projeto, uma
prioridade de número mais alta passa à frente da prioridade de cliente. A
prioridade do projeto e todos os limites de gastos continuam valendo. Use o
método de requisição bruta do cliente publicado para essas chamadas.

## Capacidades de grupo armazenadas

As versões da CLI que contêm `group capabilities` leem as configurações de grupo
armazenadas com:

```bash theme={null}
polymorfa group capabilities 9007199254740993 --session support --json
```

Use uma credencial de servidor com `groups:read`. O número vinculado precisa ser
membro atual do grupo e a equipe precisa ter acesso ao beta de capacidades do
número. Uma configuração desconhecida continua desconhecida; o comando não abre
o chat nem busca a configuração dele. Consulte
[Capacidades do número](/pt-br/guides/numbers/number-capabilities).

Gerencie as chaves da organização e os tokens de projeto no [Console](/pt-br/console/api-keys).
A CLI não oferece comandos para criar, listar ou revogar essas credenciais. As
operações com tokens de cliente continuam disponíveis pela API pública.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.