API de Integração: chave, permissões e portal de developers
Como liberar o acesso do seu sistema ao Hap - gerar e rotacionar a chave, liberar a escrita no financeiro, e onde fica a documentação técnica no portal de developers.
Quando usar
Use quando precisar executar a rotina de Integrações no ERP.
Antes de começar
- Usuário administrador no Hap (só administrador libera a escrita)
- Uma pessoa ou empresa que vá programar a integração (seu time de TI ou um parceiro)
Para que serve
A API de Integração é o caminho pelo qual um outro sistema conversa com o seu Hap sem ninguém digitar nada. É o que permite, por exemplo, que a sua loja virtual crie o cadastro do produto, que uma ferramenta puxe o saldo de estoque, ou que o seu sistema de conciliação registre os lançamentos do extrato bancário.
Quem programa a integração é o seu time de TI ou um parceiro. O que se faz aqui, dentro do Hap, são três coisas: gerar a chave, decidir o que a chave pode fazer e pegar o endereço que o seu desenvolvedor vai precisar.
Tudo isso fica em Configurações > Integrações > API de Integração.
Gerando a chave
A chave é o que identifica o seu sistema para o Hap. Sem ela, nenhuma requisição entra.
- 1
Abra Configurações > Integrações > API de Integração.
- 2
Clique em Gerar nova chave (rotacionar) e confirme.
- 3
A chave aparece na tela. Copie agora.
Esta é a única vez que a chave aparece. Depois de fechar, não há como recuperá-la - 4
Guarde em local seguro e entregue a quem vai programar a integração.
Depois de criada, a tela mostra quando ela foi gerada e quando foi usada pela última vez. É o jeito mais rápido de saber se a integração está viva.
| Botão | O que faz |
|---|---|
| Gerar nova chave (rotacionar) | Cria uma chave nova e invalida a atual. Use quando a chave vazar ou trocar de fornecedor |
| Revelar chave atual | Mostra de novo a chave em uso, para conferência |
| Revogar | Corta o acesso imediatamente. A integração para de funcionar até você gerar outra |
Liberando a escrita no financeiro
Por padrão, a chave só consulta. Ela lê produtos, pessoas, estoque, notas, vendas e o financeiro, mas não grava nada.
Para que o seu sistema possa registrar lançamentos no financeiro - contas a pagar e a receber, movimentações de extrato e baixas de títulos - alguém precisa liberar explicitamente.
- 1
Na mesma tela, vá até a seção Escrita no financeiro.
- 2
Clique em Liberar escrita e confirme.
- 3
O selo muda de Somente leitura para Escrita liberada.
Com o selo verde, a chave passa a poder registrar lançamentos no financeiro
Bloquear depois é imediato: o botão passa a ser Bloquear escrita, e a API volta a ser apenas de consulta. Nada do que já foi lançado é desfeito.
O endereço que o seu desenvolvedor precisa
No fim da tela, o bloco Como usar traz dois valores com botão de copiar.
| Valor | O que é |
|---|---|
| URL base da API | O endereço do seu Hap. É diferente para cada cliente - nunca reaproveite o de outra empresa |
| Cabeçalho de autenticação | O nome do campo em que a chave viaja a cada requisição |
Copie os dois dali e entregue junto com a chave. É tudo o que o seu desenvolvedor precisa para começar.
O que dá para fazer com a API
| Área | O que dá para fazer |
|---|---|
| Produtos | Consultar o catálogo e criar ou atualizar produtos |
| Pessoas | Consultar e criar ou atualizar clientes, fornecedores e transportadores |
| Estoque | Consultar saldo por produto, empresa e depósito |
| Financeiro | Consultar títulos e saldos. Registrar lançamentos só com a escrita liberada |
| Notas fiscais | Consultar notas de entrada e saída |
| Vendas | Consultar pedidos, contratos e ordens de serviço |
| Compras | Consultar ordens de compra |
| Contratos | Consultar contratos e a cobrança deles |
| Portal do Cliente | Criar convites e receber cadastros de clientes |
O que a API não faz: apagar registros, editar o que já foi lançado no financeiro, ou emitir documento fiscal. Correção continua sendo pelas telas do Hap.
O portal de developers
A documentação técnica - com todos os campos, exemplos prontos e um botão para testar as chamadas - fica em um portal separado, o portal de developers. Ele é só para quem vai programar; não é preciso entrar lá para usar o Hap.
| Recurso | Para que serve |
|---|---|
| Guia de Integração | Explica a autenticação e traz exemplos de uso, em texto corrido |
| Referência da API | Documentação interativa de todos os recursos, campo a campo |
| Tente aqui | Dispara uma chamada de verdade na sua base, direto do navegador, para conferir antes de programar |
Para conseguir acesso, o desenvolvedor faz o cadastro em developers.haptecnologia.com.br com o CNPJ da sua empresa, confirma o e-mail e aguarda a aprovação - conferimos que o CNPJ é de cliente Hap antes de liberar.
Segurança e limites
| Ponto | Por quê |
|---|---|
| A chave é uma credencial | Quem a tiver acessa os dados da empresa. Rotacione ao trocar de fornecedor ou ao desligar alguém que tinha acesso |
| Existe limite de requisições por chave | Passando do limite, as chamadas seguintes são recusadas por alguns instantes e a resposta informa quanto esperar. É proteção contra um laço com defeito derrubar o seu ERP |
| A escrita é reversível e rastreável | Você libera, acompanha o campo de último uso e bloqueia quando quiser |
Problemas comuns
- "Toda chamada responde 401: a chave está incorreta, foi revogada ou foi rotacionada e o seu sistema continua enviando a antiga. Confira o selo na tela; se estiver Revogada, gere outra e atualize no seu sistema."
- "As consultas funcionam, mas gravar responde 403: a escrita no financeiro não foi liberada. Um administrador precisa clicar em Liberar escrita nessa mesma tela."
- "Não encontro o botão Liberar escrita: ele só aparece para usuário administrador do Hap."
- "Perdi a chave: não há como recuperá-la. Gere uma nova em Gerar nova chave (rotacionar) e atualize no seu sistema - a anterior deixa de valer no mesmo instante."
- "O portal de developers não abre a documentação: o cadastro ainda não foi aprovado. Confirme o e-mail e aguarde a liberação; enquanto isso a chave do ERP continua funcionando normalmente."
- "Respostas com 429: seu sistema passou do limite de requisições. A resposta informa quantos segundos esperar - respeite esse tempo em vez de tentar de novo na hora."