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

# API keys

> Crie uma API key do Fire, vincule-a a um vendor e escolha os scopes que cada endpoint exige.

Toda chamada aos endpoints `/api/v1/*` é autenticada com uma API key enviada no header `x-api-key`. Esta página explica como criá-la, o que significa **vendor scope** (o motivo da maioria dos `403`) e qual **scope** cada endpoint precisa.

Para o fluxo de login, os demais headers e a verificação de assinatura de webhooks, consulte [Autenticação](https://docs.fire.rest/pt/authentication.md).

## Criar uma key

As keys são criadas no dashboard do Fire, em **Developers → API Management** (`/developers/firepos-api-management`). A página lista suas keys existentes (nome, vendor, prefixo, scopes, status, data de criação e de expiração). Antes de começar, escolha a **conta e o vendor** desejados no seletor do dashboard (no topo), depois selecione **Create API Key** e preencha o formulário:

**1. Confira a conta e o vendor**

O formulário mostra a **Account** e o **Vendor** aos quais a key ficará vinculada. Eles vêm da sua seleção no dashboard e não são alterados no formulário. Com **All vendors** selecionado, a key fica **sem vínculo de vendor** — veja [Vendor scope](#vendor-scope).

**2. Nome e descrição**

**Name** é obrigatório (por exemplo, `XMART Production`). **Description** é opcional: escreva para que a key é usada, assim você consegue distingui-las depois.

**3. Escolha os scopes**

Selecione pelo menos um scope. Conceda apenas o que sua integração chama — veja [Scopes](#scopes).

**4. Defina uma expiração (opcional)**

Escolha uma data, ou deixe vazio para uma key que nunca expira.

Selecione **Create API Key**, copie a key (ela começa com `pk_live_`) e guarde-a com segurança. Envie-a em cada requisição:

```http theme={null}
x-api-key: <your_api_key>
```

> [!NOTE]
>
> `x-api-key` é o header recomendado. O Fire também aceita a mesma key como `Authorization: Bearer pk_live_...` (alias legacy, que a tela do dashboard ainda menciona). Se você enviar ambos, `x-api-key` é usado.

> [!NOTE]
>
> Fale com a equipe da sua conta no Fire se você não vir **API Management** em **Developers** no seu dashboard.

## Gerenciar keys

* **Editar scopes:** você pode alterar os scopes de uma key sem mudar o segredo dela.
* **Nome, descrição e expiração** não podem ser editados depois que a key é criada.
* **Revogar:** uma key revogada para de funcionar e não pode mais ser editada.
* **Rotação:** não há rotação integrada. Para rotacionar, crie uma key nova com os mesmos scopes, troque sua integração para ela e depois revogue a antiga.

## Vendor scope

Uma key **vendor-scoped** é vinculada a uma conta **e** a um vendor (uma marca ou conceito dentro dessa conta). O Fire deriva ambos da própria key — você nunca envia `accountId` nem `vendorId` como parâmetros — e só retorna ou aceita dados que pertencem a esse vínculo.

A maioria dos endpoints `/api/v1/fire/external/*` e os webhooks de entrada (`webhooks:*`) **exigem** uma key vendor-scoped. Uma key sem vendor é rejeitada:

```json 403 — key not vendor-scoped theme={null}
{
  "success": false,
  "error": "FORBIDDEN",
  "message": "API key must be vendor-scoped (account + vendor binding) to access this endpoint"
}
```

Para obter uma key vendor-scoped, **selecione um vendor** no dashboard antes de criá-la. Dados de outra conta ou de outro vendor também retornam `403`, então o mais limpo é uma key por vendor.

## Scopes

Um scope dá acesso a uma família de endpoints. Uma key sem o scope exigido é rejeitada com `403` e uma mensagem indicando o scope que falta.

> [!NOTE]
>
> Ao lado de alguns scopes o dashboard mostra `requires account` ou `requires vendor`. Esse rótulo só é verificado quando você salva a key. **Cada endpoint exige o seu próprio vínculo quando você o chama**, e nem sempre coincide com o rótulo — a página do endpoint indica o que ele precisa. Na dúvida, crie a key com um vendor selecionado.

| Rótulo no dashboard | Scope | Endpoints |
| - | - | - |
| Orders Write | `orders:write` | [Atualizar pedido](https://docs.fire.rest/pt/api-reference/update-order.md), [Confirmar pagamento](https://docs.fire.rest/pt/api-reference/confirm-payment.md), [Vendas perdidas](https://docs.fire.rest/pt/api-reference/lost-sales.md) |
| Orders Read | `orders:read` | [Listar pedidos](https://docs.fire.rest/pt/api-reference/list-orders.md), [Listar pedidos da loja](https://docs.fire.rest/pt/api-reference/list-store-orders.md), [Obter pedido](https://docs.fire.rest/pt/api-reference/get-order.md), [Elegibilidade de cancelamento](https://docs.fire.rest/pt/api-reference/cancellation-eligibility.md), [Impressão fiscal](https://docs.fire.rest/pt/api-reference/fiscal-print.md), [Motivos de recusa de pagamento](https://docs.fire.rest/pt/api-reference/payment-decline-reasons.md) |
| Printing Read | `printing:read` | [Imprimir fechamento do dia](https://docs.fire.rest/pt/api-reference/print-day-close.md), [Imprimir documento do pedido](https://docs.fire.rest/pt/api-reference/print-order-document.md) |
| Store Read | `store:read` | [Listar lojas](https://docs.fire.rest/pt/api-reference/list-stores.md), [Obter loja](https://docs.fire.rest/pt/api-reference/get-store.md), [Listar terminais da loja](https://docs.fire.rest/pt/api-reference/list-store-terminals.md) — exigem uma key **vendor-scoped** |
| Menu Read | `menu:read` | [Listar menus](https://docs.fire.rest/pt/api-reference/list-menus.md), [Obter menu](https://docs.fire.rest/pt/api-reference/get-menu.md) |
| Cash Management Read | `cash-management:read` | [Dinheiro esperado](https://docs.fire.rest/pt/api-reference/cash-expected.md), [Conciliações de caixa](https://docs.fire.rest/pt/api-reference/cash-reconciliations.md) (leitura) |
| Cash Management Write | `cash-management:write` | [Conciliações de caixa](https://docs.fire.rest/pt/api-reference/cash-reconciliations.md), [Conciliações de caixa (v2)](https://docs.fire.rest/pt/api-reference/cash-reconciliations-v2.md) |
| Webhooks Fiscal Callback | `webhooks:fiscal` | [Callback fiscal](https://docs.fire.rest/pt/api-reference/fiscal-callback.md) — o callback exige uma key **vendor-scoped** |
| Webhooks KDS Order Status | `webhooks:kds` | [Status do pedido KDS](https://docs.fire.rest/pt/api-reference/kds-order-status.md) — exige uma key **vendor-scoped** |
| Webhooks Aggregator Order Status | `webhooks:aggregator` | [Status do pedido do agregador](https://docs.fire.rest/pt/api-reference/aggregator-order-status.md) |
| Webhooks PlugNotas | `webhooks:plugnotas` | Callback do provedor fiscal brasileiro. |
| Channels Read | `channels:read` | [Configuração de canais](https://docs.fire.rest/pt/api-reference/channels-config.md) |
| Payment Methods Read | `payment-methods:read` | [Configuração de métodos de pagamento](https://docs.fire.rest/pt/api-reference/payment-methods-config-v2.md) |
| Kiosks Write | `kiosks:write` | Abrir e fechar sessões de inicialização de quiosques. |
| Component Health | `component-health:write` | [Saúde dos componentes](https://docs.fire.rest/pt/api-reference/component-health.md) |
| Fiscal Gateway (numbering) | `fiscal:write` | [Numeração de documentos fiscais](https://docs.fire.rest/pt/api-reference/fiscal-documents-v2.md) |
| Document Types | `document-types:read` | [Tipos de documento fiscal](https://docs.fire.rest/pt/api-reference/fiscal-document-types.md) |

> [!NOTE]
>
> Cada página de endpoint indica o scope exato no seu parâmetro `x-api-key`. Se esta tabela e uma página de endpoint divergirem, vale a página do endpoint.

## Erros comuns

| Status | Causa | Solução |
| - | - | - |
| `401` | `x-api-key` ausente ou inválida | Envie a key no header `x-api-key`. |
| `403` — scope ausente | A key não tem o scope que o endpoint exige | Use uma key que inclua esse scope. Você pode adicionar scopes a uma key existente. |
| `403` — não vendor-scoped | A key não tem vínculo de vendor | Crie uma key nova com um vendor selecionado no dashboard. |


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