Credenciais da API

O que é uma credencial

A credencial é o acesso do seu sistema à API. Cada credencial tem:

Toda credencial ativa acessa todas as rotas da API.

Criar uma credencial

1. No painel, abra Configurações → API.
2. Clique em Nova chave. Abre o painel lateral Criar nova chave de integração.
3. Preencha os campos e clique em Salvar.

A tela Configurações → API lista as credenciais da conta, com a situação, o nome, o começo da chave, o ambiente e o último uso:

Ao clicar em Nova chave, o painel lateral pede a identificação, o webhook e os IPs autorizados:

A chave de Homologação

A chave de Homologação começa com pgp_test_. Toda chamada feita com ela, ou com o token obtido por ela, vai para o ambiente de testes.

Ao salvar a chave, a conta de testes começa a ser preparada. Na lista de Configurações → API, uma etiqueta ao lado do ambiente mostra em que ponto está:

Regras da chave de Homologação:

• Uma por conta. Cada conta pode ter uma chave de Homologação ativa. Para criar outra, revogue a atual. Ela conta no limite de 5 credenciais ativas.
• Editar e revogar valem no ambiente de testes. O nome e os IPs autorizados que você muda no painel passam para o ambiente de testes. Revogar a chave também. A conta de testes não é apagada: a próxima chave de Homologação usa a mesma conta, com os dados de teste que já estavam lá.

O que aparece uma única vez

Depois de salvar, a janela Chave criada com sucesso mostra a chave de API e o token do webhook. O próprio painel avisa:

Esta é a única vez que a chave e o token do webhook serão exibidos. Se perdê-los, será necessário revogar esta chave e criar outra.

A PagPolar guarda só um resumo (hash) da chave. Nem o suporte consegue recuperar a chave depois.

O webhook criado junto

Ao criar a credencial, a PagPolar cria um webhook com a URL e os eventos que você escolheu. Veja o que ele recebe e como alterá-lo em Configurar o webhook.

Restringir por IP

Com IPs autorizados, a API recusa com 403 qualquer requisição que venha de outro IP.

1. Em Configurações → API, abra o menu da credencial (três pontos) e clique em Editar.
2. Em IPs autorizados, informe cada IP de saída do seu servidor.
3. Salve.

O menu da credencial reúne as três ações — histórico de requisições, edição e revogação:

A mudança vale a partir da próxima requisição, inclusive para os tokens já emitidos. Veja A credencial é conferida em toda requisição e como a API descobre o IP em Restrição por IP.

Na edição, só dá para mudar o nome e os IPs autorizados. O ambiente e o webhook não aparecem no formulário de edição.

Expiração

Uma credencial pode ter data de expiração. Depois dessa data, POST /auth/token e as chamadas com os tokens já emitidos respondem 401 com Credencial de API expirada. O formulário do painel não tem campo para essa data.

Revogar uma credencial

Revogue a credencial quando a chave vazar, quando a integração deixar de existir ou quando você perder a chave.

1. Em Configurações → API, abra o menu da credencial (três pontos).
2. Clique em Revogar.
3. Confirme em Revogar esta chave?.

O que acontece:

• A partir da próxima requisição, POST /auth/token e as chamadas com os tokens já emitidos respondem 401 com Credencial de API revogada ou inativa. Veja A credencial é conferida em toda requisição.
• O webhook da credencial é desativado. Os envios que ainda estavam na fila são descartados.
• A revogação não pode ser desfeita. Para voltar a integrar, crie outra credencial.

Limite de 5 credenciais ativas

Cada conta pode ter até 5 credenciais ativas ao mesmo tempo. Ao tentar criar a sexta, o painel mostra:

Limite de 5 credenciais ativas atingido. Revogue uma credencial antes de criar outra.

Credenciais revogadas não contam no limite. Chaves de Produção e de Homologação contam juntas.

Ver o histórico de requisições

1. Em Configurações → API, abra o menu da credencial (três pontos).
2. Clique em Requisições da API. Abre a tela Histórico de requisições.
3. Abra uma requisição para ver os detalhes.

Na lista de credenciais, o ícone Ver histórico abre os envios do webhook da credencial. Veja Entregas e retentativas.

Próximos passos