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 /totvseai/standardmessage/v1/transactions?batchType={batchType}&batchUUID={batchUUID}
Onde:
Definições gerais
Endpoint padrão: /totvseai/standardmessage/v1.
Predicados:
- /transactions: para receber mensagens através do engine de EAI.
- /contents: para receber e recuperar mensagens de forma direta, sem passar pelo engine do EAI. Usado quando apenas o conteúdo trafegado é relevante.
...
Submeter mensagens em lote
POST /totvseai/standardmessage/v1/transactions?batchType={batchType}
...
- 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 Requisições em lote serão apenas assíncronas. 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 - batchType = simpleBatch |
---|
|
POST /totvseai/standardmessage/v1/transactions?batchUUID=f0b3695c-1efc-49f2-84a7-1eeb59c5a962 // batchType = simpleBatch é implícito
{
"itemsItems" : [
{
"headerHeader" : {
"UUID" : "",
"typeType" : "BusinessMessage",
"subTypeSubType" : "event",
"transactionTransaction" : "customerVendor",
"versionVersion" : "2.001",
"sourceApplicationSourceApplication": "",
"productNameProductName" : "",
"productVersionProductVersion" : "",
"generatedOnGeneratedOn" : "",
"deliveryTypeDeliveryType" : "async",
},
"contentContent" : {
"atributo1Atributo1" : "",
"atributo2Atributo2" : "",
...
"atributoNAtributoN" : ""
}
},{
"headerHeader" : {
"UUID" : "",
...
"transactionTransaction" : "customerVendor",
"versionVersion" : "2.001",
...
"deliveryTypeDeliveryType" : "async"
},
"contentContent" : {
"atributo1Atributo1" : "",
"atributo2Atributo2" : "",
...
"atributoNAtributoN" : ""
}
}
]
} |
Bloco de código |
---|
language | js |
---|
title | Lote de mensagens - batchType = businessTransaction |
---|
|
POST /totvseai/standardmessage/v1/transactions?batchType=businessTransaction&batchUUID=f0b3695c-1efc-49f2-84a7-1eeb59c5a962
{
"itemsItems" : [
{
"headerHeader" : {
"UUID" : "",
"typeType" : "BusinessMessage",
"subTypeSubType" : "event",
"transactionTransaction" : "customerVendor",
"versionVersion" : "2.001",
"sourceApplicationSourceApplication": "",
"productNameProductName" : "",
"productVersionProductVersion" : "",
"generatedOnGeneratedOn" : "",
"deliveryTypeDeliveryType" : "async",
},
"contentContent" : {
"atributo1Atributo1" : "",
"atributo2Atributo2" : "",
...
"atributoNAtributoN" : ""
}
},{
"headerHeader" : {
"UUID" : "",
...
"transactionTransaction" : "item",
"versionVersion" : "3.001",
...
"deliveryTypeDeliveryType" : "sync" // Rejeitar toda a requisição e informar que só aceita assíncrono
},
"contentContent" : {
"atributo1Atributo1" : "",
"atributo2Atributo2" : "",
...
"atributoNAtributoN" : ""
}
}
]
} |
Submeter uma única mensagem de inclusão/alteração
POST /totvseai/standardmessage/v1/transactions
O parâmetro Os parâmetros batchType e batchUUID não é relevante são relevantes para esta situação. Logo, se for informadoforem informados, deve devem ser ignoradoignorados.
Bloco de código |
---|
|
POST /totvseai/standardmessage/v1/transactions/
{
"headerHeader" : {
"UUID" : "",
"typeType" : "BusinessMessage",
"subTypeSubType" : "event",
"transactionTransaction" : "customerVendor",
"versionVersion" : "2.001",
"sourceApplicationSourceApplication": "",
"productNameProductName" : "",
"productVersionProductVersion" : "",
"companyIdCompanyId" : "",
"branchIdBranchId" : "",
"generatedOnGeneratedOn" : "",
"deliveryTypeDeliveryType" : "sync",
},
"contentContent" : {
"atributo1Atributo1" : "",
"atributo2Atributo2" : "",
...
"atributoNAtributoN" : ""
}
} |
...
Submeter uma mensagem de eliminação
DELETE /totvseai/standardmessage/v1/transactions/transacions
Justificando a presença de corpo na requisição de DELETE, é necessário identificar se a transação é síncrona ou não. Sem o corpo, todas as informações teriam que ser colocadas na URL da requisição.
Bloco de código |
---|
Bloco de código |
---|
|
DELETE /totvseai/standardmessage/v1/transactions/
{
"headerHeader" : {
"UUID" : "",
"typeType" : "BusinessMessage",
"subTypeSubType" : "event",
"transactionTransaction" : "customerVendor",
"versionVersion" : "2.001",
"sourceApplicationSourceApplication": "",
"productNameProductName" : "",
"productVersionProductVersion" : "",
"companyIdCompanyId" : "",
"branchIdBranchId" : "",
"generatedOnGeneratedOn" : "",
"deliveryTypeDeliveryType" : "sync",
},
"contentContent" : {
"atributo1Atributo1" : "",
"atributo2Atributo2" : "",
...
"atributoNAtributoN" : ""
}
}
|
...
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 o parâmetro 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, terá deve-se assumir o valor "simpleBatch".
Bloco de código |
---|
|
DELETE /totvseai/standardmessage/v1/transactions?batchUUID=f0b3695c-1efc-49f2-84a7-1eeb59c5a962
{
"itemsItems" : [
{
"headerHeader" : {
"UUID" : "",
"typeType" : "BusinessMessage",
"subTypeSubType" : "event",
"transactionTransaction" : "customerVendor",
"versionVersion" : "2.001",
"sourceApplicationSourceApplication": "",
"productNameProductName" : "",
"productVersionProductVersion" : "",
"generatedOnGeneratedOn" : "",
"deliveryTypeDeliveryType" : "async",
},
"contentContent" : {
"atributo1Atributo1" : "",
"atributo2Atributo2" : "",
...
"atributoNAtributoN" : ""
}
},
{
"headerHeader" : {
"UUID" : "",
"typeType" : "BusinessMessage",
"subTypeSubType" : "event",
"transactionTransaction" : "customerVendor",
"versionVersion" : "2.001",
"sourceApplicationSourceApplication": "",
"productNameProductName" : "",
"productVersionProductVersion" : "",
"generatedOnGeneratedOn" : "",
"deliveryTypeDeliveryType" : "async",
},
"contentContent" : {
"atributo1Atributo1" : "",
"atributo2Atributo2" : "",
...
"atributoNAtributoN" : ""
}
}
]
}
|
...
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" : {
"UUID" : "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
"Type" : "Response",
"SubType" : "event",
"Transaction" : "CostCenter",
"Version" : "2.000",
"SourceApplication" : "LGX12",
"ProductName" : "LOGIX",
"ProductVersion" : "12.1.15",
"GeneratedOn" : "2017-11-14T11:47:15-03:00",
"DeliveryType": "async"
},
"Content" : { |
Informações |
---|
O termo entidade está sendo usado no lugar de mensagem, porque neste endpoint 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 seu internalID. |
Recuperar um lote de entidades
GET /totvseai/standardmessage/v1/contents/{transactionID_version}?
page={page}&
pageSize={pageSize}&
order={orderList}&
fields={fieldList}&
{field1}={value1}&{field2}={value2}&{fieldN}={valueN}
Onde:
- transactionID_version: indica a transação e versão para a qual se quer recuperar os itens. Parâmetro obrigatório.
- page: Indica a página a recuperar. Valor padrão: 1.
- pageSize: Indica a quantidade de itens por página: Valor padrão: 10.
- order: Contém a lista de campos, separados por vírgula, que devem ser considerados para ordenar a lista de itens. Quando a ordenação for decrescente, o sinal "-" deve preceder o nome do campo. Valor padrão: ordenação definida pelo backend.
Ex: order=-description,code. - fields: Contem a lista de campos, separados por vírgula, que deve constar no retorno. Valor padrão: todos os campos.
Ex: field=code,description. - field1...fieldN: Indica o filtro que deve ser aplicado para selecionar os itens do retorno. Valor padrão: sem filtro.
Ex: code=10&description=Teste.
Bloco de código |
---|
|
GET /totvseai/standardmessage/v1/contents/customervendor_1_000
{
"hasNext" : "true",
"items" : [
"ReceivedMessage" : {
"atributo1UUID" : "d6bbfa63-ca27-e2ac-0b14-101970f59a5b",
"atributo2SentBy" : "P1299",
"Event" : "upsert"
},
"ProcessingInformation" : {
"atributo1ProcessedOn" : "2017-11-14T11:47:15-03:00",
"atributo2Status" : "ERROR",
}
]
} |
Recuperar uma entidade
GET /totvseai/standardmessage/v1/contents/{transactionID_version}/{internalID}?
fields={fieldList}&
{field1}={value1}&{fieldN}={valueN}
Onde:
- transactionID_version: parâmetro obrigatório, que identifica a transação e versão da entidade desejada.
- internalID: parâmetro obrigatório contendo o internalID da entidade desejada.
- fields: parâmetro opcional, contendo a lista de campos que devem constar no retorno. Valor padrão: todos os campos.
- field1...fieldN: conjunto de parâmetros opcionais, necessários para transações do tipo request. Os parâmetros podem variar conforme a transação e versão.
Bloco de código |
---|
|
// Todas as possibilidades de filtro e ordenação do Guia são aplicáveis.
GET /totvseai/standardmessage/v1/contents/customervendor_1_000/10|30
{
"atributo1" : "valor1",
"atributo2" : "valor2"
} |
Submeter uma entidade
Para transações do tipo event, representa a criação de um registro.
Para transações do tipo request, representa a execução de um processamento.
Bloco de código |
---|
|
POST /totvseai/standardmessage/v1/contents/updateContractParcel_2_001/
{
"atributo1" : "valor1",
"atributo2" : "valor2"
}
|
Submeter um lote de entidades
Bloco de código |
---|
|
POST /totvseai/standardmessage/v1/contents/customervendor_1_000/
{
"items" : ["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",
"Destination" : "10|1000"
},
{
{
"atributo1Name" : "valorA1",
"Company",
"atributo2Origin" : "valorA299",
},
"Destination" : {"10"
"atributo1" : "valorB1",
}
"atributo2" : "valorB2"]
}
]
}
|
Alterar uma entidade
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 |
---|
|
{
"Code |
Bloco de código |
---|
|
PUT /totvseai/standardmessage/v1/contents/customervendor_1_000/{internalID}
{
"atributo1" : "valorA1FE001",
"atributo2 "Message" : "valorA2"
} |
Eliminar uma entidade
Bloco de código |
---|
|
DELETE /totvseai/standardmessage/v1/contents/customervendor_1_000/{internalID}
//Não necessita de corpo |
...
Mensagem padrão no formato incorreto.",
"DetailedMessage" : "",
"HelpUrl": "http://tdn.totvs.com"
}
|