Este guia foi elaborado para auxiliar durante o processo de integração com nossas APIs, sendo um cliente ou um parceiro da Omie.Store.
Você encontrará as melhores práticas para garantir uma integração fluída, escalável e evitando erros comuns, facilitando ainda mais sua jornada durante a integração de suas aplicações com a Omie!
Tópicos do Artigo:
Tela para Credenciais
Se você é um parceiro e possui uma solução integrada ao Omie.ERP, sempre disponibilize uma tela em sua aplicação para que o usuário possa preencher ou alterar as credenciais de integração com o Omie ERP: App Key e App Secret.
📣 Lembrete
Por motivos de segurança, o campo destinado ao preenchimento do App Secret deve ter máscara de ocultação, garantindo que o valor digitado não seja exibido em texto puro:
Listagens Incrementais
Um conceito muito importante de boas práticas do consumo de APIs são as listagens incrementais.
Isso significa escolher sempre utilizar métodos de listagem em lote ao invés dos métodos de consulta, além de informar sempre a data/hora da última consulta.
Isso garante que apenas novos registros ou registros atualizados após essa data/hora sejam retornados, tornando a integração muito mais otimizada.
Confira este exemplo:
{
"call": "ListarTarefas",
"app_key": 12345,
"app_secret": "*****",
"param": [
{
"pagina": 1,
"registros_por_pagina": 20,
"data_inicial": "01/01/2025",
"hora_inicial": "00:01:01",
"data_final": "31/01/2025",
"hora_final": "23:59:00"
}
]
}
Paginação dos Resultados
Recomendamos, sempre que aplicável, limitar a consulta em no máximo 500 registros por página para listagens em lote. Este valor pode ser ajustado para dimensionar a resposta conforme o volume esperado de registros.
Por exemplo: para uma API de listagem de Contas a Receber faz sentido buscar por um número maior de cadastros, mas para listar Contas Correntes pode não demandar esse volume.
Mas, não há problema em adotar 500 registros como padrão para todas as APIs.
Tratamento de Erros e Controle de Consumo
Procure implementar mecanismos de retry, backoff e controle de consumo, evitando ultrapassar os limites definidos de rate limit do Omie.
💡Dicas
Para conferir quais os limites de consumo das nossas APIs, consulte este artigo: Limites de Consumo da API do Omie
E para verificar os erros mais comuns e suas soluções, temos outro artigo que vai te ajudar: Tratando os erros de API
Garantia de Documento de Origem
Toda informação registrada na aplicação integrada deve gerar um pedido ou documento de origem no Omie, que será faturado/concluído e só então gerará o financeiro.
Evite incluir lançamentos financeiros diretamente quando houver um documento de origem que deve ser gerado previamente no Omie.
Cadastrar o lançamento de forma antecipada ou paralela pode gerar inconformidades no fluxo operacional, resultando em duplicidade de registros, bloqueio do faturamento do documento fiscal e até mesmo lançamentos contábeis e fiscais indevidos.
💡 Exemplo
Em uma aplicação para oficinas mecânicas, o serviço prestado deve ser registrado como uma Ordem de Serviço para ser faturada no Omie e, dessa forma, gerando automaticamente o a Conta a Receber.
📚 Artigos Relacionados
