Neste documento são demonstradas as formas de utilização dos endpoints de mensagem padronizada do padrão REST/JSON.

Índice

Âncora
transactions
transactions
Endpoint /transactions

Submeter mensagens de inclusão/alteração em lote

POST

Definições gerais

Endpoint padrão: /totvseai/standardmessage/v1.

Predicados:

...

/totvseai/standardmessage/v1/transactions

...

?batchType={batchType}&batchUUID={batchUUID}

Onde:

batchType indica o tipo de lote sendo enviado. Os valores possíveis são:
- simpleBatch: Este é o tipo default, quando o parâmetro não for informado, e indica que as transações podem ser processadas individualmente. Eventuais erros não comprometem as demais;
- businessTransaction: indica que as transações dentro do lote devem ser processadas de forma atômica: ou processa tudo ou não aceita nenhuma. O lote pode conter mensagens de uma mesma transação e versão.
batchUUID: UUID gerado pela origem que será a referencia do lote. Esta informação é obrigatória quando for lote, mesmo o batchType sendo implícito.

Requisições em lote serão apenas assíncronas

Endpoint /transactions

Submeter mensagens em lote - transações diversas

Query parameter batchType indica o tipo de lote sendo enviado.

businessTransaction: indica que as transações dentro do lote devem ser processadas de forma atômica: ou processa tudo ou não aceita nenhuma.
simpleBatch: indica que as transações podem ser processadas individualmente. Eventuais erros não comprometem as demais. Este é o tipo default, quando o parâmetro não for informado. Se houver transações distintas num simpleBatch, deve ser gerado erro.

Requisições em lote serão apenas assíncronas, quando passarem pela Engine do EAI. Do contrário, pode acontecer timeout, prejudicando a integração. Por este motivo, se houver uma mensagem como modo de envio (deliveryType) igual a "sync", todo o lote deve ser rejeitado.

Bloco de código

language	js
title	Lote de mensagens - simpleBatch

Bloco de código

language	js

POST /totvseai/standardmessage/v1/transactions?batchUUID=f0b3695c-1efc-49f2-84a7-1eeb59c5a962	// batchType=businessTransaction = simpleBatch é implícito

{
    "itemsItems" : [
		{
            "headerHeader" : {
                "UUID" : "",
                "typeType" : "BusinessMessage",
                "subTypeSubType" : "event|request",
                "transactionTransaction" : "customerVendor",
                "versionVersion" : "2.001",
                "sourceApplicationSourceApplication": "",
                "productNameProductName" : "",
                "productVersionProductVersion" : "",
                "generatedOnGeneratedOn" : "",
                "deliveryTypeDeliveryType" : "async",
            },
            "contentContent" : {
                "atributo1Atributo1" : "",
                "atributo2Atributo2" : "",
                ...
                "atributoNAtributoN" : ""
            }
        },{
            "headerHeader" : {
                "UUID" : "",
                ...
                "transactionTransaction" : "itemcustomerVendor",
                "versionVersion" : "32.001",
                ...
                "deliveryTypeDeliveryType" : "syncasync" // Rejeitar toda a requisição e informar que só aceita assíncrono
            },
            "contentContent" : {
                "atributo1Atributo1" : "",
                "atributo2Atributo2" : "",
                ...
                "atributoNAtributoN" : ""
            }
        }
    ]
}

Submeter mensagens em lote - mesma transação

Esta proposta apresenta uma situação relevante: Um único UUID de mensagem será usado para cada uma das mensagens presentes em "content"???

Neste modelo, seria aceito o batchType businessTransaction ou seria somente simpleBatch???

Bloco de código

language	js
title	Lote de mensagens - businessTransaction

Bloco de código

language	js

POST /totvseai/standardmessage/v1/transactions?batchType=simpleBatch

{
businessTransaction&batchUUID=f0b3695c-1efc-49f2-84a7-1eeb59c5a962

{
    "headerItems" : [
		{
            "UUIDHeader" : "",{
        "type        "UUID" : "BusinessMessage",
        "subType        "Type" : "event|requestBusinessMessage",
        "transaction" : "customerVendor",
        "versionSubType" : "2.001event",
        "sourceApplication"        "Transaction" : "customerVendor",
        "productName        "Version" : "2.001",
         "productVersion       "SourceApplication": "",
                "ProductName" : "",
                "ProductVersion" : "",
                "GeneratedOn" : "",
                "DeliveryType" : "async",
            },
            "Content" : {
                "Atributo1" : "",
                "Atributo2" : "",
                ...
                "AtributoN" : ""
            }
        },{
            "Header" : {
                "UUID" : "",
                ...
                "Transaction" : "item",
                "Version" : "3.001",
                ...
                "DeliveryType" : "sync" // Rejeitar toda a requisição e informar que só aceita assíncrono
            },
            "Content" : {
                "Atributo1" : "",
                "Atributo2" : "",
                ...
                "AtributoN" : ""
            }
        }
    ]
}

Submeter uma única mensagem de inclusão/alteração

POST /totvseai/standardmessage/v1/transactions

Os parâmetros batchType e batchUUID não são relevantes para esta situação. Logo, se forem informados, devem ser ignorados.

Bloco de código

language	js

POST /totvseai/standardmessage/v1/transactions/

{
    "Header" : {
        "generatedOn" : "",
        "deliveryTypeUUID" : "async",
    },
    "contentType" : {
        "items" : ["BusinessMessage",
            {
                "atributo1"SubType" : "valorA1",
      event",
          "atributo2Transaction" : "valorA2customerVendor",
        "Version"        ...: "2.001",
        "SourceApplication": "",
        "atributoNProductName" : "valorAN",
        "ProductVersion" :   }"",
        "CompanyId" : "",
  {
      "BranchId" : "",
         "atributo1GeneratedOn" : "valorB1",
                "atributo2DeliveryType" : "valorB2sync",
    },
    "Content" : {
      ...
  "Atributo1" : "",
            "atributoNAtributo2" : "valorBN",
        ...
    }
    "AtributoN" :   ]""
    }
}

Submeter mensagens em lote - mesma transação e versão

Neste modelo, que preve a passagem pelo engine do EAI, não temos os UUIDs das mensagens. Como rastreá-las???

...

}
}

Submeter uma mensagem de eliminação

DELETE /totvseai/standardmessage/v1/transactions/

Bloco de código

language	js

POSTDELETE /totvseai/standardmessage/v1/transactions/customervendor_1_000?batchType=simpleBatch|businessTransaction


{
	"Header" : {
    	"itemsUUID" : ["",
        {
"Type" : "BusinessMessage",
          "atributo1SubType" : "valorA1event",
        "Transaction" : "customerVendor",
        "atributo2Version" : "valorA22.001",
        "SourceApplication": "",
      ...
  "ProductName" : "",
        "atributoNProductVersion" : "valorAN",
        } "CompanyId" : "",
        {
"BranchId"    : "",
        "atributo1GeneratedOn" : "valorB1",
            "atributo2DeliveryType" : "valorB2sync",
    },
    "Content" : {
       ...
    "Atributo1" : "",
         "atributoNAtributo2" : "valorBN",
        }...
    ]
}

Submeter uma mensagem, sem header

E o UUID? Onde estaria?

Tratar como síncrono ou assíncrono?

Tratar como event ou request.

Bloco de código

language	js

POST /totvseai/standardmessage/v1/transactions/customervendor_1_000/

{
     "atributo1AtributoN" : "",
    "atributo2" : "",
    ...
    "atributoN" : ""
}

Submeter uma mensagem, com header

}
}

Submeter um lote de mensagens de eliminação

DELETE /totvseai/standardmessage/v1/transactions?batchType={batchType}?batchUUID={batchUUID}

A eliminação em lote utiliza o mesmo endpoint, variando apenas o corpo, onde as mensagens a eliminar estarão dentro de um array JSON. Somente mensagens assíncronas serão aceitas.

O endpoint aceita os parâmetros batchType e batchUUID, e o comportamento será o mesmo descrito para quando um lote de mensagens é submetido. Se o parâmetro batchType for omitido, deve-se assumir o valor "simpleBatch"Se for informado o batchType, ignorar.

Bloco de código

language	js

POSTDELETE /totvseai/standardmessage/v1/transactions/?batchUUID=f0b3695c-1efc-49f2-84a7-1eeb59c5a962

{
    "headerItems" : {[
        "UUID" : "",
{
            "typeHeader" : "BusinessMessage",
{
                "subTypeUUID" : "event|request",
        "transaction" : "customerVendor",
        "versionType" : "2.001BusinessMessage",
        "sourceApplication": "",
        "productNameSubType" : "event",
        "productVersion        "Transaction" : "customerVendor",
                "generatedOnVersion" : "2.001",
        "deliveryType" : "async",
    },
    "contentSourceApplication" : {"",
        "atributo1" : "",
        "atributo2ProductName" : "",
        ...
        "atributoNProductVersion" : "",
    }
}

Eliminar uma mensagem, com header

Bloco de código

language	js

DELETE /totvseai/standardmessage/v1/transactions

{
    "header" : {
        "UUIDGeneratedOn" : "",
        "type" : "BusinessMessage",
        "subTypeDeliveryType" : "event|requestasync",
        "transaction"   : "customerVendor"},
            "versionContent" : "2.001",{
        "sourceApplication": "",
        "productNameAtributo1" : "",
        "productVersion        "Atributo2" : "",
           "generatedOn" : "",
   ...
     "deliveryType" : "async",
     },
    "contentAtributoN" : {""
        "atributo1" : "",
  }
      "atributo2" : ""},
        ...
{
            "atributoNHeader" : ""{
    }
}

Eliminar um lote de mensagens, com headers

Bloco de código

language	js

DELETE /totvseai/standardmessage/v1/transactions

{
            "itemsUUID" : ["",
         {       "Type" : "BusinessMessage",
                "headerSubType" : {"event",
                "UUIDTransaction" : "customerVendor",
                "typeVersion" : "BusinessMessage2.001",
                "subTypeSourceApplication" : "event|request",
                "transactionProductName" : "customerVendor",
                "versionProductVersion" : "2.001",
                "sourceApplicationGeneratedOn" : "",
                "productNameDeliveryType" : "async",
            },
            "productVersionContent" : "",{
                "generatedOnAtributo1" : "",
                "deliveryTypeAtributo2" : "async",
            },
            "content" : {...
                "atributo1AtributoN" : "",
                "atributo2" : "",
   }
        }
    ]
}

Entender mensagem de Erro

Entende-se como ERRO quando transmissão e entendimento da mensagem foram realizados com sucesso, porém alguma regra de negócio no ERP receptor não foi cumprida.

O status HTTP retornado é 200, e a mensagem de resposta encontra-se no seguinte formato:

Bloco de código

language	js

{ ...
    "Header" :   {
        "atributoNUUID" : "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
        "Type" : "Response",
  }
      "SubType" : }"event",
        {
"Transaction" :  "CostCenter",
         "headerVersion" : {
      "2.000",
          "UUIDSourceApplication" : "LGX12",
        "ProductName" : "LOGIX",
        "typeProductVersion" : "BusinessMessage12.1.15",
                "subType"GeneratedOn" : "event|request2017-11-14T11:47:15-03:00",
                "transaction" "DeliveryType": "customerVendor"async"
    },
    "Content" :   {
        "versionReceivedMessage" : "2.001",{
                "sourceApplicationUUID" : "d6bbfa63-ca27-e2ac-0b14-101970f59a5b",
                "productNameSentBy" : "P1299",
                "productVersionEvent" : "upsert",
        
        },
     "generatedOn"  : "ProcessingInformation",
  : {
             "deliveryTypeProcessedOn" : "async2017-11-14T11:47:15-03:00",
            }"Status" : "ERROR",
            "contentDetails" : {[
                "atributo1" : "",
{
                    "atributo2Code" : "FE001",
                ...
       "Message" :        "atributoN" : """Mensagem padrão no formato incorreto.",
            }
        }
"DetailedMessage"    ]
}

Endpoint /contents

Recuperar um lote de mensagens

O header não é necessário, só o conteúdo.

Bloco de código

language	js

GET /totvseai/standardmessage/v1/contents/customervendor_1_000/

{
    "hasNext" :  "true": "",
					"HelpUrl": "http://tdn.totvs.com" 
                },
    "items"   : [
        {
                    "atributo1" : "",
Code" : "AE004",
                    "atributo2Message" : ""
Empresa não configurada      }para integração.",
        {
            "atributo1DetailedMessage" : "",
					"HelpUrl": "http://tdn.totvs.com" 
              "atributo2" : ""}
         }
   ]
        ]
}

Recuperar uma entidade, informando o internalID

O termo entidade está sendo usado no lugar de mensagem, porque neste endpoint (e nos demais) não haverá os controles que são feitos no endpoint /transactions. Uma mensagem implica em um remetente, um destinatário e um conteúdo. Neste caso, temos explicito apenas o conteúdo, correspondente a uma entidade no destino, que é identificada pelo internalID.

Importante: ao utilizar InternalID (da maneira convencional) estamos assumindo a existência de um de-para.

Bloco de código

language	js

GET /totvseai/standardmessage/v1/contents/customervendor_1_000/{internalID}

{
,
        "ReturnContent" : {            
            "atributo1ListOfInternalID" : "valor1",[
    "atributo2" : "valor2"
}

Submeter uma entidade

Bloco de código

language	js

POST /totvseai/standardmessage/v1/contents/customervendor_1_000/

{
    "atributo1            {
                    "Name" : "valor1CostCenter",
      "atributo2" : "valor2"
}

Submeter um lote de entidades

Bloco de código

language	js

POST /totvseai/standardmessage/v1/contents/customervendor_1_000/

{
              "itemsOrigin" : ["99|ABC001",
        {
            "atributo1Destination" : "valorA1",
10|1000"
                },
             "atributo2"  : "valorA2"{
                    "Name" :  }"Company",
        {
            "atributo1Origin" : "valorB199",
            "atributo2        "Destination" : "valorB210"
                }
     ]
}

Proposta para eliminar uma entidade

Bloco de código

language	js

DELETE /totvseai/standardmessage/v1/contents/customervendor_1_000/{internalID}

{       ]
    "atributo1" : "",
  }
  "atributo2" : ""}
}

Proposta para eliminar um lote de entidades

Os internalID devem estar nos elementos do array "items"???

Entender mensagem de Falha

Entende-se como FALHA quando transmissão e entendimento da mensagem não puderam ser realizados.

Isso pode ocorrer devido aos seguintes motivos:

Configuração do EAI está incorreta ou incompleta
Estrutura da mensagem recebida está incorreta ou incompleta

O status HTTP retornado é 500, e a mensagem de resposta encontra-se no seguinte formato:

Bloco de código

language	js

Bloco de código

language	js

DELETE /totvseai/standardmessage/v1/contents/customervendor_1_000

{
	"items" : [
		{
		    "atributo1Code" : "FE001",
		    "atributo2Message" : ""
		},
		{
			"atributo1Mensagem padrão no formato incorreto.",
    "DetailedMessage" : "",
			"atributo2HelpUrl" : "http://tdn.totvs.com" 
		}
	]
}

Atalhos

Páginas filhas

Versões comparadas

Versão antiga 4

Nova versão Atual

Chave

Âncora
transactions
transactions
Endpoint /transactions

Submeter mensagens de inclusão/alteração em lote

Definições gerais

Endpoint /transactions

Submeter mensagens em lote - transações diversas

Submeter mensagens em lote - mesma transação

Submeter uma única mensagem de inclusão/alteração

Submeter mensagens em lote - mesma transação e versão

Submeter uma mensagem de eliminação

Submeter uma mensagem, sem header

Submeter uma mensagem, com header

Submeter um lote de mensagens de eliminação

Eliminar uma mensagem, com header

Eliminar um lote de mensagens, com headers

Entender mensagem de Erro

Endpoint /contents

Recuperar um lote de mensagens

Recuperar uma entidade, informando o internalID

Submeter uma entidade

Submeter um lote de entidades

Proposta para eliminar uma entidade

Proposta para eliminar um lote de entidades

Entender mensagem de Falha

Atalhos

Páginas filhas

Histórico da Página

Versões comparadas

Versão antiga 4

Nova versão Atual

Chave

ÂncoratransactionstransactionsEndpoint /transactions

Submeter mensagens de inclusão/alteração em lote

Definições gerais

Endpoint /transactions

Submeter mensagens em lote - transações diversas

Submeter mensagens em lote - mesma transação

Submeter uma única mensagem de inclusão/alteração

Submeter mensagens em lote - mesma transação e versão

Submeter uma mensagem de eliminação

Submeter uma mensagem, sem header

Submeter uma mensagem, com header

Submeter um lote de mensagens de eliminação

Eliminar uma mensagem, com header

Eliminar um lote de mensagens, com headers

Entender mensagem de Erro

Endpoint /contents

Recuperar um lote de mensagens

Recuperar uma entidade, informando o internalID

Submeter uma entidade

Submeter um lote de entidades

Proposta para eliminar uma entidade

Proposta para eliminar um lote de entidades

Entender mensagem de Falha

Âncora
transactions
transactions
Endpoint /transactions