Introdução

Nessa seção de documentos, você encontrará informações sobre os processos oficiais para realizar integrações com sistemas TOTVS.
Siga os diagramas interativos para acessar aos detalhes de cada etapa.

Macro-processo

Modelos de Integração

API

Integração client-to-server.

Este formato corresponde ao uso das APIs TOTVS por aplicações internas e de terceiros, onde o cliente depende exclusivamente dos dados providos pelo host, que geralmente é um ERP TOTVS. O cliente não necessita de mecanismos de equivalência de chaves (InternalId), pois utilizará aquelas providas pelo host. Neste contexto, a mensagem padronizada atua como um "dicionário de dados" padrão para todas as APIs que realizam as operações e requisições nas entidades mantidas pelo host. .

Não utiliza recursos como controle de fila de mensagens e mecanismos de tradução de conteúdo (de/para).

Fluxos de Construção de Integrações via API

Para permitir uma maior autonomia para quem implementa APIs e suas respectivas especificações, são sugeridos dois fluxos para desenvolvimento de integrações via API. Deste modo, o analista pode escolher o fluxo que deseja seguir, de acordo com sua necessidade. Nos tópicos subsequentes serão explicitados as duas formas a partir de seus respectivos fluxogramas e textos explicativos.

• Fluxo 1

Neste fluxo de desenvolvimento de integrações, a implementação da API/Adapter vem logo após a definição da especificação do OpenAPI e Schema. Em seguida, o analista adapta a documentação e só então solicita a aprovação da integração desenvolvida.

Vantagens

• • • Permite que a API siga para o fluxo de aprovação já com o adapter devidamente alinhado com a especificação OpenAPI, restando apenas o aval do comitê para publicação da integração.
    • Analista irá mais bem preparado para discutir a entidade desenvolvida.

Desvantagens

• • • Possibilidade de retrabalho, já que a implementação virá antes da aprovação da integração pelo comitê.

• Fluxo 2

Já na segunda sugestão do fluxo de desenvolvimento de integrações, o fluxo de aprovação vem logo depois da definição do OpenAPI e Schema, fazendo com que a implementação da API/Adapter seja realizada só após a aprovação da especificação.

Vantagens

• • • Mitiga o risco de retrabalho, por ter aprovado a documentação em comitê antes da implementação.

Desvantagens

• • • As APIs e Mensagens Padronizadas são aprovadas antes da implementação de um POC para garantir a aderência ao negócio.
    • Caso durante o desenvolvimento ou testes for identificada a necessidade de outros campos, será necessário solicitar nova versão e aprovação da mesma ao comitê.

Caso haja necessidade de inclusão de novos campos após a implementação da API, a aprovação do comitê poderá ser solicitada por e-mail a [email protected], informando quais campos serão acrescidos a mensagem original.

Transactions (EAI)

Integração server-to-server.

Neste contexto a mensagem padronizada é, por si só, a forma padrão de comunicação quando se trata de produtos TOTVS nas duas pontas da transmissão de mensagens. A troca de informações abrangidas por esse formato visam, principalmente, a sincronização de dados entre dois ou mais participantes de uma integração e, na maior parte das vezes, requer mecanismos de equivalência de chaves primárias e estrangeiras, como o uso do InternalId.

Utiliza recursos como controle de fila de mensagens e mecanismos de/para.

Análise de negócio e da integração

Apesar de ser uma etapa importante, a definição de uma mensagem (campos trafegados, estrutura, modo de operação) depende de uma boa análise do negócio e da integração como um todo.

Por isso, é vital avaliar bem as opções de integração dentro de um fluxo de negócio completo, para identificar possíveis restrições ou cenários alternativos.

Abaixo elencamos algumas questões que podem ajudar a direcionar a análise de uma integração:

• Quantos sistemas ou aplicativos estarão envolvidos na integração?
• Quais serão consumidores e quais serão produtores de informação?
• Quais as informações (entidades) serão trafegadas?
• Haverá replicação de entidades entre os aplicativos?
• Haverá requisição de informações entre os aplicativos?
• Um aplicativo iniciará algum processo em outro aplicativo?
• A informação trafegada é específica de um aplicativo ou pode ser utilizada futuramente por outros aplicativos?

Embora não seja ainda o momento de decidir questões de nível técnico, já importante ter em conta alguns conceitos e premissas da infraestrutura de integração disponível nos produtos TOTVS.

• O fluxo de integração assíncrono é preferível em relação ao fluxo síncrono, porque reduz o acoplamento entre os aplicativos e permite ampliar o número de participantes da integração.
• A infraestrutura de integração da TOTVS dispõe de vários canais de integração. Atualmente, são suportados:
  • Padrão SOAP com mensagens trafegando em formato XML.
  • Padrão REST com mensagens trafegando em formato JSON.
  • Canal AMQP, com mensagens trafegando em formato JSON.
• Cada canal tem suas características e particularidades. Por exemplo, o canal SOAP é o mais suportado, mas tem um consumo de banda de dados um pouco maior que o canal REST, já que utiliza XML. Sendo assim, ter em mente os prós e contras de cada canal ajuda a definir melhor uma integração.
• Processamentos mais pesados costumam gerar timeout num modelo síncrono. Sendo assim, deve-se tentar antecipar qual será o comportamento dos aplicativos em um cenário de timeout excedido.

Por fim, é importante envolver e manter em contato todas as "pontas" da integração, de forma a evitar que cada equipe desenvolva o seu lado da integração e, no momento da entrega ou da implantação no cliente, se perceba gaps ou falhas de entendimento, que muitas vezes são fatais para o projeto de integração.