API e webhooks

Acesso de sistemas externos ao provedor: os tokens que dão acesso à API, os webhooks que avisam outros sistemas quando algo acontece e a documentação da API. A tela tem três abas: Tokens de API, Webhooks e Documentação.

Tokens de API Criar um token Webhooks Criar um webhook A ficha do webhook Documentação

Aba Tokens de API

123456789

Configurações › API e webhooks, aba Tokens de API. A lista nunca mostra o token em si.

1. Abas Tokens de API, Webhooks e Documentação.
2. Novo token abre a criação (veja Criar um token).
3. Cartões: tokens válidos (com o total), usados em 7 dias, que expiram em 30 dias e nunca usados.
4. Abas Todos, Válidos, Expirados e Nunca usados.
5. Busca pelo nome do token e filtro pelo dono.
6. Token: o nome e quando foi criado. O dono é o usuário em nome de quem o token age.
7. Permissões do token (as quatro primeiras; o resto aparece ao passar o mouse).
8. Expira: a data de validade, ou Sem validade. A coluna Último uso, ao lado, mostra quando o token foi usado pela última vez.
9. Menu ⋯ com Revogar.

Revogar corta o acesso na hora de todos os sistemas que usam o token, e não dá para desfazer: para voltar, crie outro token. A situação Dono inativo aparece quando o usuário dono foi desativado; o token para de funcionar junto.

Nota

A tela inteira só aparece para quem tem a permissão de gerenciar tokens de API e webhooks; por padrão, o Administrador.

Criar um token

1234

O diálogo Novo token de API, vazio.

1. Nome (para que serve), por exemplo “Integração ERP”.
2. Validade: 30 dias, 90 dias, 180 dias, 1 ano ou sem validade. A sugestão vem de Recursos do sistema › Configurações › API; o padrão é 1 ano.
3. Permissões do token, agrupadas por módulo. Os atalhos Só leitura (.ver), Todas as minhas e Nenhuma marcam de uma vez.
4. Criar token. Cancelar fecha sem criar.

1. Na aba Tokens de API, clique em Novo token.
2. Dê um nome que diga qual sistema vai usar o token.
3. Escolha a validade e marque só as permissões de que o sistema precisa.
4. Clique em Criar token.
5. Copie o token que aparece no topo da tela, junto com um exemplo de teste rápido, e guarde no sistema que vai usá-lo.

Nota

O token aparece uma vez só, logo depois de criado: ele não é mostrado de novo. O token age em seu nome e só com as permissões marcadas, no máximo as suas.

Aba Webhooks

Webhook é um aviso que o sistema manda para outro sistema na hora em que algo acontece no provedor, como cliente novo, título recebido ou contrato bloqueado.

12345

API e webhooks, aba Webhooks. Na foto, nenhum webhook criado.

1. Novo webhook abre o cadastro (veja Criar um webhook).
2. Cartões: webhooks ativos (e desativados), entregues em 24 horas, que falharam em 24 horas (esgotaram as tentativas) e na fila.
3. Abas Todos, Ativos e Desativados.
4. Busca por nome ou URL.
5. Lista: o webhook com a URL, os eventos assinados, as entregas das últimas 24 horas (entregues, falhas e pendentes), o último sucesso e a situação.

O menu ⋯ de cada webhook tem Abrir, Enviar teste e Excluir. Excluir para o envio dos eventos para aquele destino e cancela as entregas pendentes.

Criar um webhook

1234567

Webhooks › Novo webhook.

1. Aviso: depois de criar, o segredo da assinatura aparece uma vez, para você configurar no sistema que recebe.
2. Nome do webhook.
3. URL de destino: recebe os avisos. Endereços de rede interna não são aceitos.
4. Todos os eventos: tudo o que entra na trilha de auditoria do provedor, inclusive eventos de módulos novos. Embaixo fica a lista para marcar só os eventos de cada tipo de registro.
5. Outro evento: digite um evento que não está na lista (por exemplo, titulo.recebido) e clique em Adicionar.
6. Ativo. Desativado, os eventos novos não são enviados.
7. Criar webhook grava e abre a ficha do webhook com o segredo.

1. Na aba Webhooks, clique em Novo webhook.
2. Dê um nome e cole a URL do sistema que vai receber os avisos.
3. Marque Todos os eventos ou só os eventos que o sistema precisa.
4. Clique em Criar webhook.
5. Copie o segredo da assinatura que aparece no topo da ficha e configure no sistema que recebe. Ele não é mostrado de novo.

A ficha do webhook

A ficha abre pelo nome do webhook na lista. Ela tem:

• no topo, Editar (liga a edição do destino e dos eventos), Enviar teste (manda um evento de teste e mostra o resultado no histórico) e Mais ações, com Trocar segredo e Excluir webhook;
• cartões com as entregas e as falhas em 7 dias, a fila e o tempo médio de resposta;
• o cartão Destino e eventos, com a URL, os eventos assinados, o último sucesso, a última falha e as falhas seguidas;
• o cartão Assinatura (HMAC-SHA256), que mostra só Definido no segredo e os cabeçalhos enviados em cada aviso;
• o histórico de entregas, com filtro por status (pendentes, entregues e falharam) e por data. Clicar numa entrega abre o detalhe, com a opção de reenviar.

Nota

Trocar segredo vale na hora: o segredo antigo para de funcionar, e o sistema que recebe precisa do novo, mostrado uma vez só. Cada evento é enviado até 6 vezes, com espera crescente, e o webhook é desativado depois de 50 entregas falhas seguidas. Os dois números se ajustam em Recursos do sistema › Configurações › Webhooks. As entregas recusadas aparecem em Erros de integração.

Aba Documentação

A referência da API do provedor, para quem vai programar a integração:

• Autenticação: todo pedido leva um token de API no cabeçalho Authorization: Bearer, com um exemplo;
• Erros: o que significam as respostas de erro, como token inválido ou sem permissão;
• Gravações e Idempotency-Key: como repetir um pedido de gravação sem duplicar o registro;
• a lista de todas as chamadas da API que estão no ar, com a permissão de cada uma e exemplos, e uma busca;
• Webhooks de saída: o formato do aviso, os cabeçalhos e como conferir a assinatura.

Telas relacionadas

• Recursos do sistema
• Erros de integração