Skip to main content
Toda chamada leva a chave no header:
Toda chamada vai para:
Todo endpoint desta versão vive sob /v1. A URL completa de uma criação de cobrança é https://api.usevext.com/v1/charges.

​
A chave aparece uma única vez

A chave é criada em Desenvolvedores no painel, e o valor em claro aparece uma única vez, na criação. Guardamos apenas um hash SHA-256. Nem o suporte consegue recuperá-la, e é esse o ponto: um dump do nosso banco não permite cobrar em nome de ninguém. Perdeu, gere outra e revogue a anterior.
Guarde a chave no servidor, nunca no JavaScript que chega ao navegador. Qualquer pessoa que abra as ferramentas de desenvolvedor da página consegue lê-la de lá, e a chave dá acesso às suas cobranças, aos seus estornos e ao seu saldo.

​
Ambientes

Chaves de teste usam o prefixo sk_test_; as de produção, sk_live_. A diferença é visível a olho nu de propósito — uma chave de teste colada em produção precisa ser reconhecível antes de alguém passar a tarde investigando por que nada acontece.

​
Escopos

Cada chave carrega escopos. Dê a cada integração só o que ela usa: uma chave de relatório que vazou não deveria conseguir criar cobrança nem estornar.

​
401 e 403 respondem coisas diferentes

Chamar um endpoint fora do escopo devolve 403, e não 401: a chave está certa, faltou permissão. Devolver 401 diria “sua chave está errada” a quem tem a chave certa, e a pessoa iria procurar o problema no lugar errado. 401 — o problema é a chave. Quatro códigos, distinguidos na message e nunca no status: A revogada é distinguida da inexistente na mensagem porque quem integra precisa saber que a chave existiu e foi desligada — e quem está adivinhando tokens não aprende nada com isso, já que o status é o mesmo nos quatro casos. 403 — o problema é o escopo. O details diz exatamente o que faltou:
insufficient_scope
Nenhum dos dois se resolve repetindo a chamada. Corrija a chave, ou gere outra com o escopo certo.

​
Veja também

Erros

O catálogo completo e o que fazer em cada família.

Webhooks

O segredo de assinatura é outro, e por endpoint.
Ficou algo de fora? Escreva para suporte@usevext.com. Se o assunto for uma chamada específica, informe o horário dela; se for uma entrega de webhook, informe o X-Vext-Delivery — é por ele que localizamos a tentativa, a resposta do seu servidor e o horário.