Saltar para o conteúdo principal
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.

​
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.
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.
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:
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.
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:
403 — key not vendor-scoped
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.
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.
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