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 as permissões dela (veja Permissões da chave).

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.

Permissões da chave

Cada chave nasce com as permissões que você marcar no painel. Elas ficam fixas: para mudar, crie outra chave (a rotação mantém as permissões da chave antiga).

O padrão é Cobranças e Leitura. Saques vem desmarcada: marque só se a integração precisa mesmo sacar pela API, e só numa chave que vive no seu servidor.

Chamar uma rota sem a permissão responde 403 insufficient_scope, e a mensagem diz qual permissão falta. É um erro da chave, não da conta.

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 para escrever (criar cobrança, pedir saque). Só a consulta de cobranças (GET /v1/transactions e GET /v1/transactions/{id}) e a de taxas (GET /v1/rates) continuam funcionando com a conta pendente de KYC, suspensa ou sem PIX, para você confirmar pagamentos. Saldo, saques, extrato e o resto respondem 403. Conta encerrada não consulta nada.
• A resposta traz details.seller_status e details.pix_enabled, para você saber o motivo.
• 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

Uma chave com a permissão Saques movimenta 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á.