Neste documento são demonstradas as formas de utilização dos endpoints de mensagem padronizada do padrão REST/JSON.
Índice |
---|
Âncora | ||||
---|---|---|---|---|
|
POST
Endpoint padrão: /totvseai/standardmessage/v1.
Predicados:
...
/totvseai/standardmessage/v1/transactions
...
?batchType={batchType}&batchUUID={batchUUID}
Onde:
POST /totvseai/standardmessage/v1/transactions?batchType={batchType}
Onde batchType indica o tipo de lote sendo enviado
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 | ||||
---|---|---|---|---|
| ||||
POST /totvseai/standardmessage/v1/transactions // batchType = ?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 | ||||
---|---|---|---|---|
| ||||
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" : "" } } ] } |
...
Será usado o endpoint anterior. Caso não se queira o header, utilizar o endpoint /contents.
Não será possível pelo endpoint /transactions. O endpoint /contents existe para esta finalidade.
Se for informado o batchType, ignorar.
...
language | js |
---|
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/ / { "headerHeader" : { "UUID" : "", "typeType" : "BusinessMessage", "subTypeSubType" : "event|request", "transactionTransaction" : "customerVendor", "versionVersion" : "2.001", "sourceApplicationSourceApplication": "", "productNameProductName" : "", "productVersionProductVersion" : "", "companyIdCompanyId" : "", "branchIdBranchId" : "", "generatedOnGeneratedOn" : "", "deliveryTypeDeliveryType" : "asyncsync", }, "contentContent" : { "atributo1Atributo1" : "", "atributo2Atributo2" : "", ... "atributoNAtributoN" : "" } } |
...
...
DELETE /totvseai/standardmessage/v1/transactions/
Bloco de código | ||
---|---|---|
| ||
DELETE /totvseai/standardmessage/v1/transactions/ { "headerHeader" : { "UUID" : "", "typeType" : "BusinessMessage", "subTypeSubType" : "event|request", "transactionTransaction" : "customerVendor", "versionVersion" : "2.001", "sourceApplicationSourceApplication": "", "productNameProductName" : "", "productVersionProductVersion" : "", "companyIdCompanyId" : "", "branchIdBranchId" : "", "generatedOnGeneratedOn" : "", "deliveryTypeDeliveryType" : "asyncsync", }, "contentContent" : { "atributo1Atributo1" : "", "atributo2Atributo2" : "", ... "atributoNAtributoN" : "" } } |
...
...
...
language | js |
---|
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" : [ { "items" : [ { "header" : { "UUID" : "", "type" : "BusinessMessage", { "subTypeHeader" : "event|request",{ "transactionUUID" : "customerVendor", "versionType" : "2.001BusinessMessage", "sourceApplicationSubType" : "event", "productNameTransaction" : "customerVendor", "productVersionVersion" : "2.001", "generatedOnSourceApplication" : "", "deliveryTypeProductName" : "async", }, "contentProductVersion" : {"", "atributo1GeneratedOn" : "", "atributo2DeliveryType" : "async", }, ... "Content" : { "atributoNAtributo1" : "", } "Atributo2" : }"", { ... "header" : { "AtributoN" : "" "UUID" : "", } }, { "typeHeader" : "BusinessMessage",{ "subTypeUUID" : "event|request", "transactionType" : "customerVendorBusinessMessage", "versionSubType" : "2.001event", "sourceApplicationTransaction" : "customerVendor", "productNameVersion" : "2.001", "productVersionSourceApplication" : "", "generatedOnProductName" : "", "deliveryTypeProductVersion" : "async", } "GeneratedOn" : "", "content "DeliveryType" : "async", }, "Content" : { "atributo1Atributo1" : "", "atributo2Atributo2" : "", ... "atributoNAtributoN" : "" } } ] } |
...
...
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 formatoO JSON equivalente a Response Message será:
Bloco de código | ||
---|---|---|
| ||
{ "headerHeader" : { "UUID" : "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6", "typeType" : "Response", "subTypeSubType" : "event", "transactionTransaction" : "CostCenter", "versionVersion" : "2.000", "sourceApplicationSourceApplication" : "LGX12", "productNameProductName" : "LOGIX", "productVersionProductVersion" : "12.1.15", "generatedOnGeneratedOn" : "2017-11-14T11:47:15-03:00", "deliveryTypeDeliveryType": "async" }, "contentContent" : { "receivedMessageReceivedMessage" : { "UUID" : "<originalMsgUUID>d6bbfa63-ca27-e2ac-0b14-101970f59a5b", "SentBy" : "<sourceApplication>P1299", "eventEvent" : "upsert|delete" }, "processingInformationProcessingInformation" : { "processedOnProcessedOn" : "2017-11-14T11:47:15-03:00", "statusStatus" : "OK|ERROR|WARNING", "detailsDetails" : [ { "codeCode" : "FE001", "messageMessage" : "Mensagem padrão no formato incorreto.", "detailedMessageDetailedMessage" : "", "helpUrl" "HelpUrl": "http://<serverName>tdn.totvs.com" // Opcional }, { "codeCode" : "AE004", "messageMessage" : "", Empresa não configurada para integração.", "detailedMessageDetailedMessage" : "", "HelpUrl": "http://tdn.totvs.com" "helpUrl" : "http://<serverName>" // Opcional } ] }, "returnContentReturnContent" : { "atributo1" : "", "atributo2ListOfInternalID" : "", "listOfInternalID" : [ // Opcional em caso de resposta de requests { "nameName" : "InternalIdNameCostCenter", "originOrigin" : "99|ABC001", "destinationDestination" : "10|1000" }, { "name" : "InternalIdName", "origin" : "", "destination" : "" } ] } } } |
As requisições deste endpoint são exclusivamente síncronas.
O header não é necessário, só o conteúdo.
Bloco de código | ||
---|---|---|
| ||
// Permitir também os filtros por atributo
GET /totvseai/standardmessage/v1/contents/customervendor_1_000?page={page}&pageSize={pageSize}&order={campos}
{
"hasNext" : "true",
"items" : [
{
"atributo1" : "",
"atributo2" : ""
},
{
"atributo1" : "",
"atributo2" : ""
}
]
} |
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.
Para transações que são do tipo request, que necessitem de dados adicionais, os mesmos serão fornecidos como filtros na requisição, seguindo as orientações do Guia de APIs da TOTVS. (colocar esta observação no inicio do documento).
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/{internalID}
{
"atributo1" : "valor1",
"atributo2" : "valor2"
} |
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"
}
|
Bloco de código | ||
---|---|---|
| ||
POST /totvseai/standardmessage/v1/contents/customervendor_1_000/ { "items" : [ { "Name" : "Company", "Origin" : "99", "Destination" : "10" } {] } "atributo1" : "valorA1", "atributo2" : "valorA2" }, { } } |
Entende-se como FALHA quando transmissão e entendimento da mensagem não puderam ser realizados.
Isso pode ocorrer devido aos seguintes motivos:
O status HTTP retornado é 500, e a mensagem de resposta encontra-se no seguinte formato:
Bloco de código | ||
---|---|---|
| ||
{ "atributo1Code" : "valorB1FE001", "atributo2"Message" : "valorB2" Mensagem padrão no }formato incorreto.", ] } |
Bloco de código | ||
---|---|---|
| ||
PUT /totvseai/standardmessage/v1/contents/customervendor_1_000/{internalID} { "atributo1"DetailedMessage" : "valorA1", "atributo2HelpUrl" : "valorA2" } |
Bloco de código | ||
---|---|---|
| ||
DELETE /totvseai/standardmessage/v1/contents/customervendor_1_000/{internalID}
//Não necessita de corpo |
...
http://tdn.totvs.com"
}
|