Boas Práticas para Integração

Para desenvolver uma integração eficaz com nossa API, é crucial considerar algumas premissas importantes. Considerando o uso da API Gateway, uma camada que direciona todas as requisições, estas são prontamente encaminhadas para a infraestrutura do cliente, que assume a responsabilidade pelo processamento completo.

Considerando as limitações fundamentais da API Gateway:

  • Volume de requisições: até 1.000 por minuto (em ambiente de produção) e 20 por minuto (em ambiente de sandobox).
  • Tamanho máximo da requisição: 10MB.
  • Tempo de processamento na infraestrutura do cliente: até 2 minutos.

A seguir, destacamos pontos cruciais aos quais o parceiro integrador deve ficar sempre atento:

  • Para garantir a conformidade, é essencial realizar todas as integrações usando a API Gateway como o padrão de troca de informações. Integrações via Banco de Dados ou o uso direto da antiga API conectada ao SankhyaOm do cliente estão em desacordo com as diretrizes (válido apenas para clientes Sankhya a partir de 01/02/2023).
  • Ao utilizar o serviço para recuperar dados (loadRecords), esteja atento à possibilidade de lentidão. Se encontrar essa situação, revise os campos marcados como "calculados" na entidade, por meio da tela Dicionário de Dados. Expressões personalizadas mal otimizadas podem causar lentidão e, consequentemente, timeouts na API.
  • Incluir ou atualizar registros (salve) também pode causar lentidão na aplicação do cliente ao enviar múltiplos registros por requisição. Isso geralmente ocorre devido a objetos de banco de dados, personalizados, na tabela que representa a entidade utilizada na requisição via API. Recomenda-se reduzir o volume de registros enviados e também revisar esses objetos de banco de dados personalizados para otimizar o desempenho.
  • Como mencionado anteriormente, todo o processamento da requisição ocorre na infraestrutura do cliente. Isso implica que se a infraestrutura do cliente (seja na infraestrutura interna ou em um datacenter externo) não estiver alinhada com as cargas de requisições, a performance pode ser comprometida, levando a timeout na API.
  • O serviço incluirNota é amplamente utilizado na API, mas em certas circunstâncias, pode resultar em timeout. Considere todos os pontos mencionados anteriormente ao analisar isso, e avalie também a quantidade de itens na requisição. Um grande volume de itens pode levar a timeout. Se isso acontecer, é recomendável negociar um número menor de itens (por exemplo, 20 itens, mas avalie caso a caso, pois pode variar) e utilizar o serviço de inclusão/alteração de itens da nota (incluirAlterarItemNota) para adicionar os itens restantes.
  • A obtenção de dados usando serviços sem paginação, como o loadView, pode resultar em timeouts. É crucial estabelecer critérios seguros para evitar grandes volumes de dados, garantindo assim uma integração com desempenho adequado. Para dicas e exemplos sobre como aprimorar a performance ao utilizar o loadView, consulte nosso guia clicando aqui.

Respeitar os limites de taxa de solicitação é essencial para evitar sobrecarga nos servidores da API e do cliente, prevenindo quedas de desempenho e interrupções no serviço. Ignorar esses limites pode resultar em bloqueio de acesso temporário, afetando negativamente a funcionalidade da integração construída pelo parceiro. Ao aderir às regras, o parceiro integrador garante uma experiência mais estável de uso das API's, promovendo a confiabilidade da aplicação e a manutenção de uma boa reputação como parceiro integrador.


Links Úteis