O eGestor disponibiliza uma API REST que permite integrar o sistema a lojas virtuais, aplicativos e outras plataformas, dando acesso a módulos como produtos, contatos, vendas, financeiro, boletos, Pix e nota fiscal eletrônica. Na prática, é o recurso que permite automatizar tarefas que, de outra forma, você precisaria fazer manualmente dentro do sistema.
Neste guia atualizado, você vai entender o que é a API do eGestor, como funciona a autenticação, quais recursos estão disponíveis, quais são os limites de uso e como dar os primeiros passos para integrar seu sistema.
O que é a API do eGestor?
A API (Interface de Programação de Aplicações) do eGestor é uma interface REST que permite a outros sistemas se comunicarem com a conta do usuário de forma programática, sem precisar acessar a tela do sistema. Se você já sabe o que é uma API de forma geral, a do eGestor segue o mesmo princípio: um conjunto de endpoints que respondem a requisições HTTP e devolvem ou recebem dados em formato JSON.
Com ela, é possível:
- Consultar e cadastrar contatos (clientes, fornecedores e transportadores);
- Criar, atualizar e consultar produtos, categorias e ajustes de estoque;
- Registrar vendas e ordens de serviço com os dados de cliente e itens envolvidos;
- Lançar recebimentos e pagamentos no financeiro;
- Emitir e consultar boletos e cobranças via Pix;
- Consultar a situação de notas fiscais (NF-e e NFS-e) e baixar o XML de documentos autorizados;
- Receber notificações automáticas por webhook sempre que sua integração criar, alterar ou excluir um registro.
É esse conjunto de recursos que viabiliza, por exemplo, a integração de sistemas entre o eGestor e uma loja virtual, um aplicativo de delivery ou um sistema de PDV (ponto de venda) próprio.
Como funciona a autenticação na API?
A API do eGestor usa o protocolo OAuth2 para autenticação. O fluxo funciona em duas etapas:
- Você gera um personal_token dentro do próprio sistema, no menu Configurações, na aba API. Esse token é um JWT que já contém informações da empresa (subdomínio) e do usuário;
- Esse personal_token é trocado por um access_token por meio de uma requisição POST para
https://api.egestor.com.br/api/oauth/access_token, informando o parâmetrogrant_type=personal.
A resposta traz o access_token (válido por 900 segundos), o token_type (Bearer) e um refresh_token para renovar o acesso sem pedir o personal_token novamente. A partir daí, toda requisição aos demais endpoints precisa enviar o header Authorization: Bearer [access_token].
Além disso, vale lembrar que o eGestor não possui ambiente de homologação (sandbox): cada conta é isolada das demais (multi-tenant). Por isso, quem está desenvolvendo uma integração deve criar uma conta de testes separada antes de apontar a aplicação para a conta de produção do cliente.
Métodos de requisição
As requisições seguem os métodos HTTP padrão:
| Método | Função |
|---|---|
| GET | Retorna informações de um ou mais registros |
| POST | Cria um novo registro, como uma venda ou um cadastro de contato |
| PUT | Atualiza um registro existente ou altera sua situação (por exemplo, marcar uma conta a receber como paga) |
| DELETE | Remove um registro do sistema |
Todas as requisições devem usar HTTPS, e as ações de listagem retornam 50 registros por página, sem opção de alterar esse limite.
Recursos disponíveis na API
A API dá acesso a praticamente todos os módulos do eGestor. Os principais grupos de endpoints são:
- Empresa: dados cadastrais da conta;
- Contatos: clientes, fornecedores e transportadores;
- Categorias e produtos: cadastro de itens e ajuste de estoque;
- Serviços: cadastro de serviços prestados;
- Disponíveis: contas caixa configuradas na empresa;
- Formas de pagamento, plano de contas e grupo de tributos: configurações usadas no financeiro e nas vendas;
- Recebimentos e pagamentos: lançamentos do financeiro;
- Compras, vendas e devoluções: movimentações comerciais, incluindo vendas feitas no PDV e ordens de serviço;
- Boletos: emissão e consulta de boletos bancários;
- Pix: geração e consulta de cobranças via Pix;
- NFS-e: emissão e consulta de notas fiscais de serviço;
- NF-e: consulta da situação de notas fiscais e download do XML de documentos autorizados;
- Relatórios: extração de dados consolidados do sistema;
- Disco virtual: upload e download de arquivos vinculados a outros registros;
- Usuários: gestão dos usuários da conta;
- Webhooks: configuração de notificações automáticas.
No módulo de NF-e, por exemplo, a API retorna a situação de cada nota (criada, enviada, autorizada, rejeitada, cancelada, entre outras). Se o seu sistema recebe uma nota com situação de rejeição, vale consultar o guia de rejeições da nota fiscal para entender o código retornado e como corrigi-lo antes de reenviar.
Webhooks: automação em tempo real
Além de consultar dados sob demanda, é possível cadastrar webhooks para os módulos de produtos, contatos, vendas, usuários e financeiro. Sempre que criar, atualizar ou excluir um registro desses módulos, o eGestor envia uma requisição para a URL cadastrada. Essa requisição contém o formato do módulo, a ação realizada e um securityToken próprio, utilizado para validar a autenticidade do envio.
Dois pontos importantes para quem for implementar:
- O timeout de resposta ao webhook é de 3 segundos, com até 5 tentativas em caso de falha. Por isso, o recomendado é apenas registrar o recebimento e processar os dados depois, usando uma fila (queue);
- É possível optar por receber o payload como JSON, marcando o parâmetro correspondente no cadastro do webhook.
Limites de requisição e códigos de resposta
A API permite até 60 requisições por minuto por aplicação e usuário. Esse limite pode ser acompanhado nos headers X-RateLimit-Limit e X-RateLimit-Remaining, enviados em todas as respostas. Ao ultrapassar o limite, a API retorna o código 429, e é preciso aguardar alguns segundos antes de tentar novamente.
| Código | Significado |
|---|---|
| 200 | Requisição executada com sucesso |
| 400 | Erro de validação ou campo inexistente |
| 401 | Dados de acesso inválidos |
| 404 | Registro não encontrado |
| 405 | Método não implementado para o endpoint |
| 410 | Registro já foi apagado do sistema ou não se encontra mais disponível |
| 422 | Dado informado fora do escopo definido para o campo |
| 429 | Número máximo de requisições atingido (aguarde alguns segundos e tente novamente) |
Biblioteca PHP e primeiros passos
Para quem desenvolve em PHP, o eGestor mantém uma biblioteca (SDK) oficial no GitHub, que facilita a integração sem precisar montar as requisições manualmente. A documentação completa dos endpoints, com exemplos de requisição e resposta, fica disponível em egestor.docs.apiary.io.
Para começar uma integração, o caminho é:
- Criar (ou usar) uma conta no eGestor;
- Acessar Configurações > API e gerar o personal_token;
- Trocar o personal_token por um access_token, conforme descrito acima;
- Fazer as primeiras chamadas de teste, como
GET /empresa, para validar a autenticação; - Cadastrar os webhooks necessários, se a integração precisar reagir a mudanças em tempo real.
Vantagens de integrar via API
Empresas que dependem de mais de um sistema no dia a dia (loja virtual, PDV, aplicativo de delivery, sistema fiscal de terceiros) ganham quando esses sistemas conversam entre si automaticamente. Entre os principais benefícios de uma gestão integrada via API estão:
- Redução de retrabalho, já que os dados não precisam ser digitados duas vezes em sistemas diferentes;
- Menos erros de digitação e de sincronização entre estoque, financeiro e vendas;
- Atualização de dados em tempo real entre as plataformas conectadas;
- Possibilidade de automatizar processos como emissão de nota fiscal, geração de boleto e baixa de estoque assim que uma venda é concluída.
Casos de uso comuns
Na prática, a API do eGestor costuma ser usada para:
- Integração com e-commerce: sincronizar pedidos da loja virtual com o financeiro e o estoque do eGestor automaticamente;
- Sistemas de PDV próprios: registrar vendas feitas no ponto de venda diretamente na conta do eGestor;
- Aplicativos de terceiros: consultar situação de notas fiscais, boletos e Pix sem precisar acessar o sistema manualmente;
- Automação fiscal: disparar a emissão de NF-e ou NFS-e a partir de outro sistema e acompanhar a situação da nota até a autorização.
Conclusão
A API do eGestor é o caminho para quem precisa que o sistema converse com outras plataformas, seja uma loja virtual, um PDV próprio ou um aplicativo de gestão fiscal. Com autenticação via OAuth2, endpoints para praticamente todos os módulos do sistema e suporte a webhooks, é possível automatizar boa parte do fluxo de vendas, financeiro e emissão de notas sem intervenção manual.
Antes de começar a desenvolver, vale revisar a documentação completa, testar em uma conta separada e planejar o uso dos webhooks para reduzir o número de requisições. Em caso de dúvidas específicas sobre a integração, você pode acionar o suporte pelo e-mail suporte@zipline.com.br.
Perguntas frequentes sobre a API do eGestor
A API do eGestor é gratuita?
O acesso à API está disponível para contas do eGestor, sem cobrança adicional pelo uso da integração em si. Cobranças específicas, como as de emissão de boleto, seguem as mesmas regras aplicadas ao uso do sistema pela interface normal.
Preciso saber programar para usar a API?
Sim. A API é voltada a desenvolvedores ou a empresas que tenham uma equipe técnica capaz de construir a integração, seja usando a biblioteca PHP oficial, seja fazendo as requisições HTTP diretamente em outra linguagem.
Existe um ambiente de testes (sandbox)?
Não. O eGestor não possui sandbox, e cada conta é isolada das demais. A recomendação é criar uma conta de testes separada para o desenvolvimento e só depois apontar a integração para a conta de produção.
Quantas requisições posso fazer por minuto?
O limite é de 60 requisições por minuto por aplicação e usuário. Ao ultrapassar esse número, a API retorna o código 429 e é preciso aguardar alguns segundos antes de tentar novamente.
É possível emitir nota fiscal pela API?
A API permite consultar a situação de NF-e e NFS-e já emitidas e baixar o XML de documentos autorizados. Para o fluxo completo de emissão fiscal, vale combinar a integração com um emissor dedicado, como o NFe+.
Como sei se um registro foi alterado sem precisar consultar a API o tempo todo?
Cadastrando um webhook para o módulo desejado (produtos, contatos, vendas, usuários ou financeiro). Assim, o eGestor avisa automaticamente seu sistema sempre que houver uma criação, alteração ou exclusão, sem necessidade de ficar consultando a API em intervalos fixos.
0 comentários