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

# GET /v1/meta/pricing — Preço de Mensagem

> Preço por mensagem publicado do Meta / WhatsApp por mercado, moeda e categoria.

O preço por mensagem publicado do **Meta / WhatsApp Business Platform** para um único mercado + moeda + categoria — o preço de tabela que a Meta cobra por mensagem entregue. É a tabela pública da Meta exposta como dado de referência; **não** é a cobrança real da sua conta.

## Endpoint

`GET https://pilotstatus.com.br/v1/meta/pricing`

<Note>
  Requer qualquer API key válida (`ps_*`) no header `x-api-key`. Chaves com escopo de número ou de tenant funcionam — preço é dado global, não vinculado a um número.
</Note>

## Parâmetros de query

<ParamField query="market" type="string">
  Código do mercado: ISO 3166-1 alpha-2 para países (`BR`, `GB`, `IN`…), `NAM` para América do Norte, ou um bucket regional (`AFR`, `APAC`, `CEEU`, `LATAM`, `MDE`, `WEU`, `GLO`).
</ParamField>

<ParamField query="currency" type="string">
  Código de moeda ISO 4217 (`USD`, `BRL`, `EUR`, `GBP`, `INR`…).
</ParamField>

<ParamField query="category" type="string">
  `marketing`, `utility`, `authentication`, `service` ou `authentication_international`. Obrigatório junto com `market` e `currency`.
</ParamField>

<ParamField query="tiers" type="boolean">
  `true` / `1` → também retorna `volumeTiers` (a Meta cobra menos por mensagem conforme o volume mensal cresce).
</ParamField>

## Modos

| Chamada                                | Retorna                                                                       |
| -------------------------------------- | ----------------------------------------------------------------------------- |
| Sem `market` / `currency` / `category` | **Metadados** — os mercados (código + nome), moedas e categorias disponíveis. |
| `market` + `currency` + `category`     | O **preço flat** dessa combinação.                                            |
| Qualquer parcial                       | `400 MARKET_CURRENCY_CATEGORY_REQUIRED`.                                      |

## Exemplos

<CodeGroup>
  ```bash Preço theme={null}
  curl "https://pilotstatus.com.br/v1/meta/pricing?market=BR&currency=BRL&category=authentication" \
    -H "x-api-key: ps_sua_chave_aqui"
  ```

  ```bash Com volume tiers theme={null}
  curl "https://pilotstatus.com.br/v1/meta/pricing?market=BR&currency=BRL&category=authentication&tiers=1" \
    -H "x-api-key: ps_sua_chave_aqui"
  ```

  ```bash Metadados theme={null}
  curl "https://pilotstatus.com.br/v1/meta/pricing" \
    -H "x-api-key: ps_sua_chave_aqui"
  ```
</CodeGroup>

```json Preço (200) theme={null}
{
  "market": "BR",
  "marketName": "Brazil",
  "currency": "BRL",
  "category": "authentication",
  "pricePerMessage": 0.035
}
```

```json Com volume tiers (200) theme={null}
{
  "market": "BR",
  "marketName": "Brazil",
  "currency": "BRL",
  "category": "authentication",
  "pricePerMessage": 0.035,
  "volumeTiers": [
    { "from": 0,        "to": 500000,  "pricePerMessage": 0.035 },
    { "from": 500001,   "to": 3000000, "pricePerMessage": 0.0333 },
    { "from": 20000001, "to": null,    "pricePerMessage": 0.0263 }
  ]
}
```

```json Metadados (200) theme={null}
{
  "markets": [
    { "code": "BR", "name": "Brazil" },
    { "code": "NAM", "name": "North America" }
  ],
  "currencies": ["AED","ARS","AUD","BRL","CLP","COP","EUR","GBP","IDR","INR","MXN","MYR","PEN","SAR","SGD","USD"],
  "categories": ["marketing","utility","authentication","service","authentication_international"],
  "source": "whatsappbusiness.com"
}
```

## Campos da resposta

<ResponseField name="market" type="string">Código do mercado devolvido.</ResponseField>
<ResponseField name="marketName" type="string">Nome legível do mercado.</ResponseField>
<ResponseField name="currency" type="string">Moeda ISO 4217 devolvida.</ResponseField>
<ResponseField name="category" type="string">A categoria pedida.</ResponseField>

<ResponseField name="pricePerMessage" type="number">
  Preço de tabela por mensagem entregue na moeda pedida. `0` para categorias gratuitas (Service).
</ResponseField>

<ResponseField name="volumeTiers" type="array">
  Só com `tiers=1`. Cada `{ from, to, pricePerMessage }` — o preço cai conforme o volume mensal cresce; `to` é `null` no tier superior ilimitado. Vazio para categorias sem tiering (Marketing / Service).
</ResponseField>

## Categorias de mensagem

| Categoria                      | O que cobre                                                                        |
| ------------------------------ | ---------------------------------------------------------------------------------- |
| `marketing`                    | Promoções, ofertas, sugestões de produto, reengajamento.                           |
| `utility`                      | Atualizações transacionais / disparadas pelo usuário (pedido, pagamento, entrega). |
| `authentication`               | Senhas de uso único (OTP) e verificação de identidade.                             |
| `authentication_international` | Autenticação para certos destinos internacionais (rate própria).                   |
| `service`                      | Respostas dentro da janela de atendimento de 24h — **grátis** (`0`).               |

<Note>
  A Meta só muda preços no 1º dia de cada trimestre (aviso de \~1 mês), então esta tabela é atualizada por schedule. Trate os valores como indicativos e confirme com as tabelas oficiais da Meta para a cobrança exata.
</Note>

## Erros comuns

* `400 MARKET_CURRENCY_CATEGORY_REQUIRED` — envie `market`, `currency` e `category` juntos (ou nenhum, para metadados).
* `400 INVALID_CATEGORY` — o valor de `category` não é uma das cinco categorias válidas.
* `401` — header `x-api-key` ausente ou inválido.
* `404 PRICE_NOT_FOUND` — sem rate publicada para esse mercado + moeda + categoria.