Histórico da Página
Índice |
---|
Introdução
Âncora | ||||
---|---|---|---|---|
|
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 | ||||
---|---|---|---|---|
|
draw.io Diagram | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Modelos de Integração
API
Âncora | ||||
---|---|---|---|---|
|
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 | ||||
---|---|---|---|---|
|
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.
editar fluxo de aprovação (adicionar alternativo);
modificar macroprocesso;
...
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.
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ê.
draw.io Diagram | |||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
...
|
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.
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ê.
draw.io Diagram | |||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
...
|
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.
Nota | ||
---|---|---|
| ||
O comitê pode reprovar parcialmente, totalmente ou indicar a utilização de outra mensagem que tenha o mesmo propósito e neste caso, o custo do desenvolvimento será de inteira responsabilidade do proponente da mensagem. Por este motivo, indicamos fortemente o desenvolvimento apenas após a aprovação da mensagem (Fluxo 2). |
Transactions (EAI)
Âncora | ||||
---|---|---|---|---|
|
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.
draw.io Diagram | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Análise de negócio e da integração
Âncora | ||||
---|---|---|---|---|
|
(Redigir texto analisando as considerações abaixo)
...
- Quem é o dono da mensagem?
- Lote? Timeout?
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.
...