A API do OneFlow permite que o seu sistema se comunique diretamente com o OneFlow, enviando e consultando informações como documentos fiscais, lançamentos contábeis, folha de pagamento e obrigações. Ela é usada por escritórios e empresas que querem conectar sistemas próprios ao OneFlow e automatizar rotinas.
Antes de começar, vale conhecer alguns pontos importantes: a integração é baseada em tokens, o consumo é feito por empresa e nem tudo o que existe no sistema está disponível via API. Reunimos aqui as respostas para as dúvidas mais frequentes, dos pré-requisitos aos erros mais comuns, para ajudar você a configurar e usar a integração com mais segurança.
Para saber como obter os acessos e começar a usar, consulte o artigo Autenticação para utilização de APIs do OneFlow. Para ver tudo o que está disponível, acesse a documentação técnica no Swagger do OneFlow.
Tópicos do Artigo
Primeiros passos
Antes de integrar, é importante entender o que é necessário para usar a API e como ela funciona no dia a dia. Nesta seção você encontra as respostas para as dúvidas iniciais mais comuns.
1) O que preciso para usar a API?
1) O que preciso para usar a API?
Ter um usuário cadastrado no aplicativo do escritório (OneFlow) e também permissão do usuário para acessar a empresa que será integrada. Não é necessário ter perfil de administrador.
Ter os tokens de acesso do escritório e da empresa.
Se a empresa também usa o ERP Omie, o usuário também precisa ter acesso ao ERP dela.
2) Posso integrar várias empresas de uma só vez (em lote)?
2) Posso integrar várias empresas de uma só vez (em lote)?
Não. O consumo da API é feito por empresa, com o token de cada uma. Para atender várias empresas, envie as requisições separadamente, cada uma com o token da respectiva empresa.
3) Existe ambiente de testes (sandbox)?
3) Existe ambiente de testes (sandbox)?
Não. Como alternativa, utilize uma empresa fictícia no ambiente oficial para validar o fluxo antes de usar com dados reais.
Tokens e autenticação
O acesso à API do OneFlow é feito por meio de tokens, que identificam o escritório e a empresa em cada requisição. Aqui você entende como eles funcionam, quanto tempo duram e como mantê-los atualizados e seguros.
1) Existe limite de requisições ou custo?
1) Existe limite de requisições ou custo?
Não. O uso da API do OneFlow não tem custo adicional, e os limites de consumo da API do ERP Omie não se aplicam a ela, pois são APIs independentes.
2) Como funciona a autenticação?
2) Como funciona a autenticação?
A integração é baseada em tokens: um do escritório (OneFlow) e um da empresa. Cada empresa deve usar o seu próprio token, vinculado ao app_hash dela. Não utilize o token de uma empresa para acessar outra.
3) Onde obtenho os tokens?
3) Onde obtenho os tokens?
Os tokens são obtidos por chamadas à API. Depois de fazer login no portal do OneFlow ou do Omie, obtenha o token do usuário de integração. Com ele, liste os aplicativos para identificar o app_hash do escritório e gerar o token do escritório (OneFlow). Em seguida, liste as empresas para obter o app_hash de cada uma e gerar o token da empresa.
💡Dica!
O passo a passo completo, com os endereços de cada chamada, está no artigo:
4) Os tokens expiram?
4) Os tokens expiram?
Sim. Os tokens têm validade limitada de 24h. Para não precisar fazer login novamente, utilize o refresh token, que atualiza o token automaticamente.
5) Preciso fazer login no portal para renovar o token?
5) Preciso fazer login no portal para renovar o token?
Não, desde que você tenha o par token e refresh token da empresa. Com ele, a renovação é feita sem acessar o portal. Se o par não estiver mais válido, será necessário gerar os tokens novamente.
6) Como manter meus tokens seguros?
6) Como manter meus tokens seguros?
Não compartilhe os tokens por e-mail ou mensagem e guarde-os em um lugar seguro. Se suspeitar que algum token foi exposto, gere novos tokens.
Erros comuns
Ao integrar com a API, é normal encontrar alguns erros no caminho. Nesta seção reunimos os mais frequentes, com o que costuma causá-los e o que verificar. Cada caso precisa ser analisado, pois o mesmo código pode ter causas e validações diferentes.
1) Recebi o erro 401 na API do OneFlow. O que significa?
1) Recebi o erro 401 na API do OneFlow. O que significa?
Em geral, indica um problema na identificação da requisição, como token ausente, incorreto ou pertencente a outra empresa. Confira se o token enviado é o da empresa correta e se está sendo enviado conforme a documentação orienta.
2) Recebi o erro 403 na API do OneFlow. O que fazer?
2) Recebi o erro 403 na API do OneFlow. O que fazer?
Esse erro costuma estar ligado ao token. Siga esta ordem:
Confirme se o usuário está cadastrado no escritório (OneFlow) e na empresa.
Estando correto, verifique se os tokens estão corretos e se não expiraram.
Renove os tokens com o refresh token e tente novamente.
3) Recebi o erro 404 na API do OneFlow. O que fazer?
3) Recebi o erro 404 na API do OneFlow. O que fazer?
Esse erro geralmente ocorre quando a empresa também usa o ERP Omie e o usuário não tem acesso a ele. Nesse caso, o usuário precisa:
Estar cadastrado no aplicativo do escritório (OneFlow);
Ter o usuário cadastrado na empresa (OneFlow);
Estar convidado no aplicativo e ter acesso ao ERP Omie dessa empresa.
Se algum desses acessos estiver faltando, o erro pode ocorrer. Estando tudo certo, confira também os dados enviados na requisição.
4) Recebi outro erro ou uma mensagem de “erro de integração”. O que fazer?
4) Recebi outro erro ou uma mensagem de “erro de integração”. O que fazer?
Confira se os dados enviados seguem o que está descrito no Swagger. Se o erro continuar, abra um atendimento com o suporte informando:
Data e horário da tentativa;
Empresa em que o erro ocorreu;
Qual endpoint estava utilizando e procedimento que estava tentando realizar;
O código e a mensagem do erro.
O que é possível fazer via API
A API do OneFlow cobre uma grande parte das rotinas do sistema, mas nem tudo está disponível. Aqui você encontra dúvidas comuns sobre o que pode ser feito pela integração e o que ainda precisa ser feito diretamente no sistema.
1) Como saber se uma ação está disponível na API?
1) Como saber se uma ação está disponível na API?
Consulte o Swagger do OneFlow. Tudo o que está documentado lá pode ser feito via API. O que não aparece não está disponível e deve ser feito diretamente no sistema.
2) Não encontro a opção de exclusão de lançamento no Swagger. Como excluo um lançamento contábil?
2) Não encontro a opção de exclusão de lançamento no Swagger. Como excluo um lançamento contábil?
As exclusões existem, mas aparecem no Swagger como requisições do tipo POST, e não DELETE. Para excluir um lançamento contábil, é preciso informar o ID dele, que é gerado pelo sistema na inclusão. Para obtê-lo, faça uma consulta dos lançamentos e utilize o ID retornado.
3) Posso cadastrar uma empresa nova pela API?
3) Posso cadastrar uma empresa nova pela API?
Sim. A criação de empresas está disponível. Consulte os detalhes no Swagger.
4) Posso obter DRE, Balanço e DFC pela API?
4) Posso obter DRE, Balanço e DFC pela API?
Não diretamente. O balancete e o razão podem ser consultados via API, com o mesmo conteúdo apresentado nas telas do sistema. DRE, Balanço e DFC estão disponíveis como anexos das obrigações, sendo assim, só poderão ser gerados via API se as obrigações desses demonstrativos tiverem sido finalizadas na competência Contábil.
5) Posso enviar outros documentos além de NFS-e e NF-e?
5) Posso enviar outros documentos além de NFS-e e NF-e?
Hoje a integração contempla NFS-e e NF-e, que são os layouts mais utilizados. Se você precisa de outro tipo de documento, registre a solicitação no suporte, detalhando qual é.
6) O CNPJ deve ser enviado com ou sem máscara?
6) O CNPJ deve ser enviado com ou sem máscara?
Você pode enviar das duas formas. O OneFlow remove a máscara automaticamente.
7) É possível emitir nota fiscal ou faturar uma Ordem de Serviço via API?
7) É possível emitir nota fiscal ou faturar uma Ordem de Serviço via API?
Não. Atualmente, não é possível emitir notas fiscais de serviço (NFS-e) ou faturar uma Ordem de Serviço (OS) via API no OneFlow.
É possível importar o XML de uma NFS-e emitida pelo padrão nacional ou pelo layout da prefeitura, além de incluir manualmente uma NFS-e no sistema. No entanto, a emissão da nota fiscal e o faturamento da Ordem de Serviço via API não estão disponíveis.
8) O que ainda precisa ser feito diretamente no sistema?
8) O que ainda precisa ser feito diretamente no sistema?
Atualmente, não é possível realizar via API:
Admissão e demissão de colaboradores e criação de rubricas da folha;
Envio ou renovação de certificado digital (por critério de segurança);
Alteração dos cards padrão do sistema.
9) Posso solicitar uma nova funcionalidade?
9) Posso solicitar uma nova funcionalidade?
Sim. Caso precise de um endpoint que ainda não esteja disponível na documentação Swagger da API OneFlow, você pode solicitar uma nova funcionalidade para que a equipe avalie a possibilidade de implementação.
Para isso, informe o CNPJ do escritório, o CNPJ da empresa, descreva a funcionalidade ou os dados que deseja consultar ou integrar e convide o usuário suporte@oneflow.com.br no OneFlow para que possamos avaliar a solicitação.
Notificações (webhook)
Muitas integrações precisam saber quando algo muda no OneFlow. Nesta seção explicamos como acompanhar alterações hoje.
1) O OneFlow avisa a minha aplicação quando algo é alterado?
1) O OneFlow avisa a minha aplicação quando algo é alterado?
Hoje não há webhook ou callback disponível de forma geral. Para acompanhar alterações, consulte periodicamente as listagens disponíveis no Swagger.
Segurança e dados
A segurança das informações é prioridade no OneFlow. Aqui você encontra como os dados são protegidos, onde ficam hospedados e como exportá-los.
1) Os dados estão protegidos?
1) Os dados estão protegidos?
Sim. Toda a comunicação é feita via SSL. O OneFlow faz parte da infraestrutura da Omie, alinhada às práticas da LGPD e com ISO 27001 implantada. Mais detalhes na Central de Segurança.
2) Onde os dados ficam hospedados?
2) Onde os dados ficam hospedados?
Na AWS, Amazon Web Services.
3) De quem são os dados?
3) De quem são os dados?
Do cliente. Nos termos da LGPD, o OneFlow atua como operador dos dados e o cliente como controlador. Solicitações relacionadas aos direitos do titular devem partir do controlador, e o suporte pode apoiar no que for necessário.
4) Como exporto os meus dados?
4) Como exporto os meus dados?
A exportação pode ser realizada manualmente ou via API (conforme endpoints disponíveis) e feita por competência fechada. Você pode baixar relatórios, como DRE e balancetes, livros fiscais, arquivos de obrigações acessórias, como SPEDs, e guias de impostos.
📚 Artigos Relacionados
