# Escolha o número de envio

Liste os números conectados à sua empresa, confira a qualidade conhecida e o limite compartilhado do portfólio.

### GET /public/v1/numbers

A chave Bearer limita a consulta à sua empresa. Números desconectados ou removidos não entram na lista. Use o `phone_number_id` escolhido no catálogo de templates e no envio; ele é um identificador da Meta, não o telefone do contato.

cURL · listar números

```bash
curl "https://api.patrociniotech.com/public/v1/numbers?limit=20" \
  -H "Authorization: Bearer SUA_CHAVE"
```

## Paginação

| Parâmetro | Regra |
| --- | --- |
| limit | De 1 a 50. Padrão: 20 números por página. |
| after\_id | Copie next\_after\_id da resposta anterior. Omita na primeira página; não incremente nem interprete o cursor. |
| has\_more / next\_after\_id | Enquanto has\_more for true, consulte a próxima página. next\_after\_id é null quando a lista termina. |

A ordem é lexical por ID. A listagem não congela o cadastro: uma conexão nova que entre antes do cursor será vista em uma nova varredura. Guarde o catálogo localmente e renove periodicamente, em vez de fazer esta consulta antes de cada mensagem.

JSON · resposta ilustrativa

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "phone_number_id": "123456789012345",
        "waba_id": "234567890123456",
        "business_portfolio_id": "345678901234567",
        "label": "Avisos",
        "display_phone_number": "+55 11 90000-0000",
        "verified_name": "Empresa Exemplo",
        "quality": {
          "rating": "GREEN",
          "label": "Alta",
          "source": "meta",
          "checked_at": "2026-11-06T12:00:00Z"
        },
        "messaging_limit": {
          "value": 10000,
          "tier": "TIER_10K",
          "unlimited": false,
          "known": true,
          "label": "10.000",
          "scope": "business_portfolio",
          "window_hours": 24,
          "source": "whatsapp_business_manager_messaging_limit",
          "checked_at": "2026-11-06T12:00:00Z"
        },
        "health": {
          "state": "AVAILABLE",
          "source": "monitoring",
          "checked_at": "2026-11-06T11:55:00Z",
          "reasons": [],
          "stale": false
        },
        "meta_available": true
      }
    ],
    "has_more": false,
    "next_after_id": null,
    "checked_at": "2026-11-06T12:00:01Z"
  }
}
```

## O que cada leitura significa

| Campo | Interpretação |
| --- | --- |
| quality.rating | GREEN, YELLOW, RED, UNKNOWN ou null. UNKNOWN/null não são qualidade baixa; representam ausência de nota ou indisponibilidade. |
| messaging\_limit.value | Destinatários únicos em uma janela móvel de 24 h, compartilhados pelo portfólio. Não é mensagens por minuto, saldo restante ou limite individual de cada número. |
| messaging\_limit.known / unlimited | known=false: não foi possível conhecer o limite. unlimited=true: a Meta informou ilimitado. Nos dois casos value pode ser null; não confunda desconhecido com ilimitado. |
| business\_portfolio\_id | Agrupa números que compartilham a capacidade. Não some o limite desses números. Pode ser null quando a conexão não informa o portfólio. |
| health.state | Última verificação persistida: AVAILABLE, LIMITED, BLOCKED ou UNKNOWN. Não garante que uma nova mensagem será aceita ou entregue. |
| health.reasons | Lista de restrições: code, title, action e entity. 141010 é uma pendência de verificação da empresa; não reduz por si só o limite para 250. Erros de SIP/chamadas são excluídos. |
| health.stale | true quando não há leitura ou ela tem mais de 30 minutos. Confira a hora antes de tomar decisões com o estado persistido. |
| checked\_at | A resposta, a qualidade, o limite e a saúde têm horários próprios. A data da consulta não indica quando a Meta alterou o valor. |

## Falha parcial e atualização

`BLOCKED` informa impedimento de envio: suspenda a campanha e confira os motivos. `LIMITED` exige avaliar `reasons`; não equivale a bloqueio total. Uma pendência de verificação pode coexistir com qualidade GREEN e limite TIER\_10K. Mesmo AVAILABLE não reserva capacidade: acompanhe recusas, entrega e qualidade durante o envio. Para UNKNOWN ou leitura antiga, não conclua que o número está liberado.

Uma falha em um número não apaga os outros. A página retorna HTTP 200 com `meta_available: false` nesse item, qualidade e limite desconhecidos, preservando identidade e a última saúde registrada. Mostre indisponível; não converta esse caso em bloqueado, qualidade baixa ou custo zero.

Qualidade e limite podem usar uma consulta Meta feita há até 120 segundos. O monitoramento de saúde é separado, distribuído em lotes e com novas tentativas espaçadas em falhas. Em fila acumulada ou indisponibilidade, seu horário pode ser mais antigo. Use os horários na interface para deixar isso claro.

> A rota consome a cota compartilhada de 600 requisições por minuto por chave. Ela não oferece reserva de capacidade nem verifica se um destinatário possui WhatsApp. Uma lista vazia é válida; erros de autenticação, paginação e limite continuam usando o envelope de erros da API.

---

Fonte: https://patrociniotech.com/documentacao-api/numeros
Índice para IA: https://patrociniotech.com/documentacao-api/llms.txt