Autenticação
Toda chamada leva a sua chave privada no cabeçalho Authorization. As chaves são criadas no painel, em Integrações › API.
Como enviar a chave
Authorization: Bearer gp_live_1a2b3c4d5e6f_0123456789abcdef0123456789abcdef0123456789abcdef- Formato:
gp_live_+ 12 caracteres +_+ 48 caracteres (letrasa-fe números). - A parte
gp_live_+ os 12 primeiros caracteres é o identificador público da chave (aparece no painel). O resto é segredo. - A chave privada inteira aparece uma única vez, na criação. Guardamos só uma versão embaralhada (hash): se perder, gere outra.
- Chave de produção começa com
gp_live_. Para testar sem Pix de verdade, use a chave de testegp_test_(mesmo formato): veja Modo de teste.
Pedido feito por http:// recebe 403 https_obrigatorio e não é redirecionado, porque a chave já teria passado aberta pela internet. Se isso acontecer, troque a chave no painel.
Permissões
Cada chave tem uma ou mais permissões. Chamada sem a permissão daquele endereço recebe 403 sem_permissao.
| Permissão no painel | Libera |
|---|---|
| Criar/consultar transações | /charges |
| Consultar dados da conta e saldo | /balance |
| Criar/consultar saques | /withdrawals |
Chave com permissão de saque tem regras a mais:
- Sempre tem data de validade, de no máximo 365 dias.
- Só cria saque se a conta tiver pelo menos um IP autorizado (senão:
403 ip_obrigatorio). - Pode ser criada com a opção Exigir minha aprovação: o saque fica esperando você aprovar no painel (status
aguardando_sua_aprovacao).
IPs autorizados
Em Integrações › API você pode cadastrar até 20 IPs ou faixas (IPv4 de /16 a /32, IPv6 de /48 a /128). Com a lista preenchida, pedido de outro IP recebe 403 ip_nao_autorizado. Com a lista vazia, qualquer IP é aceito (menos para saques).
Validade, troca e revogação
- Você pode dar uma data de validade à chave (até 5 anos). Depois dela:
401 chave_expirada. - Trocar a chave gera uma nova chave privada com o mesmo identificador; a antiga para na hora.
- Revogar desliga a chave para sempre:
401 nao_autorizado. - Cada conta pode ter até 5 chaves ativas de produção e até 5 de teste.
Quando a chave é recusada
| HTTP | Código | Quando |
|---|---|---|
| 401 | nao_autorizado | Chave errada, revogada ou cabeçalho fora do formato. |
| 401 | chave_expirada | Passou da data de validade. |
| 403 | https_obrigatorio | Pedido chegou por http. |
| 403 | conta_nao_aprovada | Conta ainda em análise. |
| 403 | ip_nao_autorizado | IP fora da lista de IPs autorizados. |
| 403 | sem_permissao | A chave não tem a permissão daquele endereço. |
| 403 | recurso_indisponivel_em_teste | Chave de teste chamando saldo ou saque. |
| 403 | chave_de_teste_na_producao | Chave de teste (gp_test_) no endereço de produção. Ela só vale em /sandbox. |
| 429 | muitas_chaves_invalidas | Muitos pedidos com chave errada da mesma rede em 1 minuto. Espere 1 minuto. |