Introdução

Âncora
intro intro

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

Âncora
macro-processo macro-processo

Modelos de Integração

API

Âncora
api 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

Âncora
fluxos-api fluxos-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

  Âncora
  fluxo-1 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.

...

• • • 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

  Âncora
  fluxo-2 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.

...

• • • 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)

Âncora
transactions transactions

Integração server-to-server.

Neste contexto a mensagem padronizada já está estabelecida como o único é, por si só, a forma padrão de comunicação entre os produtos TOTVS e corresponde às integrações que vem sendo construídas ao longo dos anos. 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

...

(Redigir texto analisando as considerações abaixo)

...

• Quem é o dono da mensagem?
• Lote? Timeout?

e da integração

Âncora
analise-negocio analise-negocio

...

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.

...

• 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.