Autenticação

Toda rota sob /v1 é autenticada por uma chave de API no header Authorization:

Authorization: Bearer sk_live_...

Não existe outro fator, não existe login por usuário e senha na API e não existe sessão. Quem tem a chave tem a conta.

A chave escolhe o ambiente

A base URL é a mesma para os dois ambientes. O prefixo da chave é quem decide:

• sk_live_ opera em produção e move dinheiro de verdade.
• sk_test_ opera no ambiente de teste.

O formato completo é sk_live_ ou sk_test_ seguido de 43 caracteres alfanuméricos. Qualquer coisa fora disso é recusada com 401 invalid_api_key sem consultar o banco.

Os dois ambientes não se enxergam. Consultar com uma chave de teste um id criado em produção devolve 404, nunca 403: a resposta não confirma que o objeto existe.

Criar, rotacionar e revogar

As três ações acontecem no painel, não pela API. O segredo é mostrado uma única vez, na criação e na rotação; depois disso nem nós conseguimos recuperá-lo.

• Limite: 10 chaves ativas por loja em cada ambiente.
• Chave de produção exige KYC aprovado. Sem isso a criação responde 403 kyc_required. Chave de teste pode ser criada a qualquer momento.
• Rotação: cria a chave nova e agenda a revogação da antiga para daqui a 24 h. Essa janela existe para você trocar a chave em produção sem derrubar nada: publique a nova, confirme que o tráfego migrou, e a antiga morre sozinha.
• Revogação: é imediata e não tem volta. Use quando desconfiar que a chave vazou. Requisição com chave revogada responde 401 revoked_api_key.

Quando a chave é válida e ainda assim recusa

403 seller_not_allowed não é problema de chave, é estado da conta:

• Em produção, a conta precisa estar ativa e com PIX habilitado.
• No ambiente de teste, qualquer estado serve, menos conta encerrada. É o que deixa você integrar enquanto o KYC ainda está em análise.

Onde a chave nunca pode estar

A chave saca dinheiro no seu nome. Ela vive no servidor, em variável de ambiente ou em cofre de segredos, e só.

Nunca embarque a chave em aplicativo, em página web, em repositório ou em log. Uma chave de produção num bundle de front é um saque na conta de quem abrir o DevTools. Se acontecer, revogue antes de consertar o código.

Próximo passo

Com a chave em mãos, vá para Idempotência: o header Idempotency-Key é obrigatório em toda criação de cobrança e de saque.

Referência: Saldo e agregados do seller no mode da API key é a chamada mais barata para confirmar que a sua chave funciona e em qual ambiente ela está.