Histórico da Página
| Índice |
|---|
Objetivo
Documentar a estrutura, funcionamento e práticas relacionadas à mensagem padronizada TOTVS utilizando REST como padrão de comunicação e JSON como formato de mensagem.
| Informações | ||
|---|---|---|
| ||
Este documento leva em consideração que o leitor tenha um conhecimento prévio da mensagem padronizada TOTVS utilizando XML e SOAP. Caso algum termo não esteja suficientemente descrito aqui, recomenda-se consultar o documento Padrão para criação de mensagem padronizada, disponível no portal de Integrações TOTVS. |
Estrutura
Semelhante ao que se tem na mensagem padronizada, baseada em SOAP e XML, a estrutura é composta dos seguintes elementos:
...
Graficamente, a estrutura pode ser descrita conforme abaixo:
Funcionamento
A dinâmica envolvendo o envio e recebimento de mensagens não se altera com a nova proposta. O que muda, de fato, são o formato da mensagem e a interface.
...
A geração das mensagens continua a cargo dos adapters, que entregam para a Engine do EAI a estrutura de dados necessária para gerar a mensagem no padrão TOTVS. Da mesma, forma o recebimento das mensagens continua sendo intermediado pelo Engine de EAI, que determinará qual o adapter responsável por processar a mensagem recebida.
Definições
Mensagem
A mensagem padronizada, utilizando JSON como formato, será composta dos seguintes elementos:
...
| Informações | ||
|---|---|---|
| ||
A tag Identification, subordinada à tag BusinessEvent, não será contemplada no formato REST/JSON. Essa tag foi sendo substituída ao longo do tempo pelos Internal IDs do corpo das mensagens. Ao migrar um adapter para utilizar o novo formato, qualquer processamento baseado na tag Identification deve ser revisto. |
Alguns Exemplos de Mensagem
Uma mensagem da transação CostCenter, na versão 2.000, seria expressa da seguinte forma, usando o formato JSON:
...
- É válido somente para mensagens assíncronas. Caso uma das mensagens presentes no lote tenha o atributo DeliveryType igual a "sync", todo o lote deve ser rejeitado.
- Pode conter mensagens de uma mesma transação e versão, ou mensagens de transações/versões distintas.
- Um lote pode ser tratado como um simples agrupador de mensagens sem relação entre si, ou um lote transacional, onde as mensagens são interdependentes, representando uma única transação de negócio. Veja a descrição do parâmetro batchType, do predicado /transactions na seção a seguir, para mais informações.
- Geração e envio do UUID pela origem é obrigatória. Veja a descrição do parâmetro batchUUID, do predicado /transactions na seção a seguir, para mais informações.
Interface
As mensagens padronizadas em formato JSON serão recebidas por um endpoint padrão, conforme descrito abaixo:
...
| Informações |
|---|
Salvo quando explicitamente indicado no documento, deve-se considerar que os endpoints disponibilizam os recursos previstos no Guia de Implementação de APIs para paginação, ordenação e filtro de dados. |
Predicado /transactions
| Painel | ||
|---|---|---|
| ||
| http://<servidor>[:<porta>]/totvseai/standardmessage/v1/transactions?batchType={batchType}?batchUUID={batchUUID} |
...
- POST: para receber mensagens de requisição (request), ou mensagem de inclusão/alteração (event). Corresponde às mensagens XML contendo a tag BusinessRequest, ou tag BusinessEvent com Event igual a "upsert".
- DELETE: para mensagens de eliminação (delete). Corresponde às mensagens XML contendo a tag BusinessEvent, com Event igual a "delete".
Exemplos de utilização
Exemplos de utilização deste predicado podem ser encontrados nos links a seguir:
- Submeter mensagem de inclusão/alteração em lote;
- Submeter uma mensagem de inclusão/alteração;
- Submeter uma mensagem de eliminação;
- Submeter um lote de mensagens de eliminação.
Predicado /contents
| Painel | ||
|---|---|---|
| ||
| http://<servidor>[:<porta>]/totvseai/standardmessage/v1/contents/{transactionID_version}/{internalID}. |
...
| Informações | ||
|---|---|---|
| ||
| O formato de mensagem utilizado nas requisições para o endpoint /contents é mais simples, já que não requer as informações de cabeçalho utilizadas para realizar o controle da mensagem (rastreamento, fila, etc). A proposta é apenas utilizar-se do modelo de mensagem padronizada para trafegar informações entre as partes. Na prática, o modelo de dados que será trafegado nas requisições corresponde apenas ao atributo content do modelo completo, usado pelo endpoint /transactions. |
Exemplos de utilização
Exemplos de utilização deste predicado podem ser vistos nos link a seguir:
- Recuperar uma lista de entidades;
- Recuperar uma entidade;
- Submeter uma entidade;
- Alterar uma entidade;
- Eliminar uma entidade.
Coexistência com o formato XML
No período de migração das implementações em XML para JSON, será necessário que os formatos convivam simultaneamente e sejam interoperáveis. Assim que todos os ERPs forem capazes de trabalhar com a nova proposta, o formato XML e os endpoints SOAP poderão ser desativados.
...
Para apoiar na migração de adapters do formato XML para o formato JSON, foi desenvolvido o documento Equivalência entre formatos, o qual possui orientações importantes para este processo.
Elaboração da mensagem padronizada
O desenho de uma transação, no formato REST/JSON, deve utilizar o formato Swagger/OpenAPI, em substituição ao formato XML Schema, utilizado na implementação SOAP/XML. Para mais informações sobre como implementar um documento Swagger, consulte a especificação própria do padrão.
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas