Tema
Tokens de API e webhooks
Esta parte é para quem liga o sistema da sua empresa ao portal. Exemplo: um ERP que cria cobranças sozinho.
Não usa integração? Pode pular esta página.
Para quem programa
As chamadas da API (endereços, campos e respostas) estão na Referência da API.
Clique no seu nome, no fim do menu. No grupo Desenvolvimento, escolha:
- Tokens de API;
- Webhooks.
Passo a passo
Veja Como criar um usuário de API e Como reenviar o aviso de pagamento (webhook).
Quem vê
Aparece para quem tem a permissão de integração por API.
Tokens de API (Usuários de API)
Chave da conta (Account Token)
No alto da tela fica a chave da sua conta.
- O olho mostra ou esconde a chave.
- O botão copia a chave.
Guarde a chave em segredo
Quem tem a chave e um usuário de API mexe na sua conta. Nunca mande a chave por e-mail aberto ou em grupo de mensagens.
Usuários de API
O usuário de API é a identidade que o seu sistema usa para entrar. A lista mostra Nome, E-mail (identificador) e Documento.
| Botão | Faz |
|---|---|
| Baixar credenciais | Baixa um arquivo com os dados de acesso. |
| Editar | Muda nome, e-mail, documento e telefone. |
| Apagar | Tira o acesso. Confirme em Remover. |
Criar um usuário de API
Passo a passo com fotos e vídeo
- Clique em Novo usuário API.
- Escreva o Nome. Exemplo: Integração ERP.
- Escreva o E-mail (identificador).
- Escreva o CPF/CNPJ.
- Clique em Criar usuário API.
O quadro Como funciona explica o acesso: o seu sistema faz um POST para /account/get-token, enviando o email do usuário de API e o token da conta.
Webhooks
O webhook é um aviso automático que o portal manda para o seu sistema. Exemplo: quando uma cobrança é paga.
Onde fica o endereço
Cada cobrança leva o seu endereço. O seu sistema manda o campo webhook ao criar a cobrança pela API. O portal não tem campo para o endereço.
A tela Webhooks
Em cima ficam os números Entregues, Com falha e Total.
Para achar um aviso:
- Em Pesquisar, escreva a URL ou o código da cobrança.
- Se quiser, escolha o Resultado: Entregues ou Com falha.
- Se quiser, escolha a Data início e a Data fim.
- Clique em Filtrar.
O botão Limpar mostra todos os avisos de novo.
| Coluna | O que mostra |
|---|---|
| Aviso | O que aconteceu, o número e o valor. |
| Cobrança | O código da cobrança. Clique para abrir. |
| URL de destino | Para onde foi enviado. |
| Resultado | Entregue ou Falhou, com o código que o seu sistema respondeu. |
| Data/hora | Quando foi enviado. |
Entregue quer dizer que o seu sistema respondeu com um código 2xx (por exemplo, 200).
Clique em uma linha. Abre Detalhes do Webhook, com:
- Payload Enviado (JSON): o que o portal mandou. O botão Copiar copia;
- Resposta do Servidor: o que o seu sistema respondeu.
Reenviar o aviso de pagamento
O seu sistema não recebeu o aviso de uma cobrança paga? Mande o aviso de novo pelo portal.
Passo a passo com imagens e vídeo: Como reenviar o aviso de pagamento.
Quando aparece o botão
O botão Reenviar aparece só quando:
- a cobrança está Paga;
- a cobrança tem boleto (Boleto ou BolePix);
- a cobrança foi criada com um endereço de webhook.
Cobrança só com Pix não tem o botão.
Como reenviar
- No menu, clique em Cobranças.
- Clique na cobrança paga.
- Desça até o quadro Webhook de notificação.
- Confira o endereço. O botão copia o endereço.
- Clique em Reenviar, no canto do quadro.
- Espere o desenho girando parar.
O resultado
Abre a janela Resultado da Notificação.
| Aparece | Quer dizer |
|---|---|
| Sucesso! | O seu sistema recebeu o aviso. |
| Ocorreu um erro | O seu sistema não aceitou o aviso. |
| Status HTTP | O código que o seu sistema respondeu. Exemplo: 200. |
| Resposta da API | O texto que o seu sistema respondeu. |
Clique em Fechar para sair.
O aviso reenviado é o mesmo do pagamento: valor pago, data e dados da cobrança.
Conferir depois
Todo reenvio fica guardado na tela Webhooks, com o resultado. Veja A tela Webhooks.
Deu errado?
| Problema | O que fazer |
|---|---|
| Não tem o botão Reenviar | Veja se a cobrança está Paga e tem boleto. |
| Não tem o quadro Webhook de notificação | A cobrança foi criada sem endereço de webhook. |
| Ocorreu um erro | Peça para quem cuida do seu sistema ver o Status HTTP. |
| Erro de novo | O endereço pode estar fora do ar. Tente mais tarde. |
Avise o seu sistema
O seu sistema pode receber o mesmo pagamento duas vezes. Ele deve conferir o código da cobrança antes de dar baixa.