Neste documento são demonstradas as formas de utilização dos endpoints de mensagem padronizada do padrão REST/JSON.
Endpoint /transactionsSubmeter 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 |
---|
|
POST |
Bloco de código |
---|
|
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" : "sync" // Rejeitar toda a requisição e informar que só aceita assíncronoasync"
},
"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 |
---|
|
POST /totvseai/standardmessage/v1/transactions?batchType=simpleBatch
{ businessTransaction&batchUUID=f0b3695c-1efc-49f2-84a7-1eeb59c5a962
{
"Items" : [
{
"header "Header" : {
"UUID" : "",
"typeType" : "BusinessMessage",
"subType" : "event|request",
"transactionSubType" : "customerVendorevent",
"version "Transaction" : "2.001customerVendor",
"sourceApplication": "",
"productNameVersion" : "2.001",
"productVersionSourceApplication" : "",
"generatedOnProductName" : "",
"deliveryTypeProductVersion" : "async",
},
"content "GeneratedOn" : {
"",
"itemsDeliveryType" : [
"async",
},
"Content" : {
"atributo1Atributo1" : "valorA1",
"atributo2Atributo2" : "valorA2",
...
"atributoNAtributoN" : "valorAN"
},
},{
"Header" : {
"atributo1UUID" : "valorB1",
"atributo2" : "valorB2",
...
"Transaction" ...
: "item",
"atributoNVersion" : "valorBN3.001",
}
...
]
}
} |
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???
O batchType poderia ser businessTransaction ou simpleBatch, a principio.
Bloco de código |
---|
|
POST /totvseai/standardmessage/v1/transactions/customervendor_1_000?batchType=simpleBatch|businessTransaction
{
"DeliveryType" : "sync" // Rejeitar toda a requisição e informar que só aceita assíncrono
},
"itemsContent" : [{
{
"atributo1Atributo1" : "valorA1",
"atributo2Atributo2" : "valorA2",
...
"atributoNAtributoN" : "valorAN"
},
{
}
}
"atributo1" : "valorB1",
]
} |
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 |
---|
|
POST /totvseai/standardmessage/v1/transactions/
{
"Header" : {
"atributo2UUID" : "valorB2",
"Type" : ...
"BusinessMessage",
"SubType" : "event",
"Transaction" : "customerVendor",
"atributoNVersion" : "valorBN2.001",
}
"SourceApplication": "",
]
} |
E o UUID? Onde estaria?
Tratar como síncrono ou assíncrono?
Tratar como event ou request
Bloco de código |
---|
|
POST /totvseai/standardmessage/v1/transactions/customervendor_1_000/
{
"atributo1"ProductName" : "",
"atributo2ProductVersion" : "",
...
"atributoNCompanyId" : ""
} |
Se for informado o batchType, ignorar.
Bloco de código |
---|
|
POST /totvseai/standardmessage/v1/transactions/
{
,
"headerBranchId" : {"",
"UUIDGeneratedOn" : "",
"typeDeliveryType" : "BusinessMessagesync",
},
"subTypeContent" : "event|request",
{
"transactionAtributo1" : "customerVendor",
"versionAtributo2" : "2.001",
"sourceApplication": "",
...
"productNameAtributoN" : "",
}
} |
Submeter uma mensagem de eliminação
DELETE /totvseai/standardmessage/v1/transactions/
Bloco de código |
---|
|
DELETE /totvseai/standardmessage/v1/transactions/
{
"Header" : {
"UUID "productVersion" : "",
"generatedOn" : "",
"deliveryTypeType" : "asyncBusinessMessage",
}, "SubType" : "event",
"contentTransaction" : {
"customerVendor",
"atributo1Version" : "2.001",
"atributo2SourceApplication" : "",
"ProductName" ...
: "",
"atributoNProductVersion" : "",
}
} |
Bloco de código |
---|
|
DELETE /totvseai/standardmessage/v1/transactions
{
"headerCompanyId" : {"",
"UUIDBranchId" : "",
"typeGeneratedOn" : "BusinessMessage",
"subTypeDeliveryType" : "event|requestsync",
},
"transactionContent" : "customerVendor",{
"versionAtributo1" : "2.001",
"sourceApplicationAtributo2" : "",
"productName" : "",
...
"productVersionAtributoN" : "",
"generatedOn" : "",
"deliveryType" : "async",
},
"content" : {
}
}
|
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".
Bloco de código |
---|
|
DELETE /totvseai/standardmessage/v1/transactions?batchUUID=f0b3695c-1efc-49f2-84a7-1eeb59c5a962
{
"Items" : [
"atributo1" : "",
{
"atributo2Header" : "",{
...
"atributoNUUID" : "",
}
} |
Bloco de código |
---|
|
DELETE /totvseai/standardmessage/v1/transactions
{
"itemsType" : ["BusinessMessage",
{
"headerSubType" : {
"event",
"UUIDTransaction" : "customerVendor",
"typeVersion" : "BusinessMessage2.001",
"subTypeSourceApplication" : "event|request",
"transactionProductName" : "customerVendor",
"versionProductVersion" : "2.001",
"sourceApplicationGeneratedOn" : "",
"productNameDeliveryType" : "async",
},
"productVersionContent" : "",
{
"generatedOnAtributo1" : "",
"deliveryTypeAtributo2" : "async",
}, ...
"contentAtributoN" : {""
}
"atributo1" : ""},
{
"atributo2Header" : "",
{
...
"UUID" : "",
"atributoNType" : "BusinessMessage"
,
}
"SubType" }: "event",
{
"headerTransaction" : {"customerVendor",
"UUIDVersion" : "2.001",
"typeSourceApplication" : "BusinessMessage",
"subTypeProductName" : "event|request",
"transactionProductVersion" : "customerVendor",
"versionGeneratedOn" : "2.001",
"sourceApplicationDeliveryType" : "async",
"productName" : ""},
"productVersionContent" : "",{
"generatedOnAtributo1" : "",
"deliveryTypeAtributo2" : "async",
},
...
"content" : {
"atributo1"AtributoN" : "",
"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 |
---|
|
{
"Header" : {
"atributoNUUID" : "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
"Type" : "Response",
"SubType" : "event",
}
"Transaction" : }
"CostCenter",
]
}
|
Endpoint /contents
Recuperar um lote de mensagens
O header não é necessário, só o conteúdo.
Bloco de código |
---|
|
GET /totvseai/standardmessage/v1/contents/customervendor_1_000/
{
"Version" : "2.000",
"hasNextSourceApplication" : "trueLGX12",
"itemsProductName" : [
"LOGIX",
{
"ProductVersion" : "12.1.15",
"atributo1GeneratedOn" : "2017-11-14T11:47:15-03:00",
"atributo2DeliveryType" : "async"
},
"Content" : {
"atributo1ReceivedMessage" : "",
{
"atributo2UUID" : ""
d6bbfa63-ca27-e2ac-0b14-101970f59a5b",
"SentBy" : "P1299",
"Event" : "upsert" }
]
} |
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 |
---|
|
GET /totvseai/standardmessage/v1/contents/customervendor_1_000/{internalID}
{
"atributo1" : "valor1",
"atributo2" : "valor2"
} |
Submeter uma entidade
Bloco de código |
---|
|
POST /totvseai/standardmessage/v1/contents/customervendor_1_000/
{
"atributo1" : "valor1",
"atributo2" : "valor2"
}
|
Submeter um lote de entidades
Bloco de código |
---|
|
POST /totvseai/standardmessage/v1/contents/customervendor_1_000/
{
"items" : [
,
"ProcessingInformation" : {
"ProcessedOn" : "2017-11-14T11:47:15-03:00",
"Status" : "ERROR",
"Details" : [
{
"Code" : "FE001",
"Message" : "Mensagem padrão no formato incorreto.",
"DetailedMessage" : "",
"HelpUrl": "http://tdn.totvs.com"
},
{
"Code" : "AE004",
"Message" : "Empresa não configurada para integração.",
"DetailedMessage" : "",
"HelpUrl": "http://tdn.totvs.com"
}
]
},
"ReturnContent" : {
"ListOfInternalID" : [
{
"Name" : "CostCenter",
"Origin" : "99|ABC001",
{
"atributo1Destination" : "valorA1",
10|1000"
},
{
"atributo2" : "valorA2"
"Name" : }"Company",
{
"atributo1Origin" : "valorB199",
"atributo2Destination" : "valorB210"
}
]
}
|
Proposta para eliminar uma entidade
Bloco de código |
---|
|
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 |
---|
|
{
|
Bloco de código |
---|
|
DELETE /totvseai/standardmessage/v1/contents/customervendor_1_000
{
"items" : [
{
"atributo1Code" : "FE001",
"atributo2Message" : ""
},
{
"atributo1Mensagem padrão no formato incorreto.",
"DetailedMessage" : "",
"atributo2HelpUrl" : "http://tdn.totvs.com"
}
]
} |