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.

Endpoint /transactions

Submeter mensagens em lote

POST /totvseai/standardmessage/v1/transactions?batchType={batchType}

Onde batchType indica o tipo de lote sendo enviado

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. Se houver transações distintas num simpleBatch, deve ser gerado erro;
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.

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	// 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

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

...

Será usado o endpoint anterior. Caso não se queira o header, utilizar o endpoint /contents.

Submeter uma mensagem, sem header

Não será possível pelo endpoint /transactions. O endpoint /contents existe para esta finalidade.

Submeter uma mensagem, com header

Se for informado o batchType, ignorar.

...

language	js

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/

/

{
    "headerHeader" : {
        "UUID" : "",
        "typeType" : "BusinessMessage",
        "subTypeSubType" : "event|request",
        "transactionTransaction" : "customerVendor",
        "versionVersion" : "2.001",
        "sourceApplicationSourceApplication": "",
        "productNameProductName" : "",
        "productVersionProductVersion" : "",
        "companyIdCompanyId" : "",
        "branchIdBranchId" : "",
        "generatedOnGeneratedOn" : "",
        "deliveryTypeDeliveryType" : "asyncsync",
    },
    "contentContent" : {
        "atributo1Atributo1" : "",
        "atributo2Atributo2" : "",
        ...
        "atributoNAtributoN" : ""
    }
}

...

Submeter uma mensagem

...

de eliminação

DELETE /totvseai/standardmessage/v1/transactions/

Bloco de código

language	js

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" : ""
    }
}

...

Submeter um lote de mensagens

...

de eliminação

...

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

language	js

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" : ""
            }
        }
    ]
}

...

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 formatoO JSON equivalente a Response Message será:

Bloco de código

language	js

{
    "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" : ""
                }
            ]
        }
    }
}

Endpoint /contents

As requisições deste endpoint são exclusivamente síncronas.

Recuperar um lote de mensagens

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

Bloco de código

language	js

// 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" : ""
        }
    ]
}

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.

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

language	js

// 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"
}

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

language	js

POST /totvseai/standardmessage/v1/contents/updateContractParcel_2_001/

{
    "atributo1" : "valor1",
    "atributo2" : "valor2"
}

Submeter um lote de entidades

Bloco de código

language	js

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

{
    "items" : [

                {
                    "Name" : "Company",
                    "Origin" : "99",
                    "Destination" : "10"
                }
            {]
        }
    "atributo1" : "valorA1",
            "atributo2" : "valorA2"
        },
        {
        }
}

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

{
    "atributo1Code" : "valorB1FE001",
            "atributo2"Message" : "valorB2"
Mensagem padrão no      }formato incorreto.",
    ]
}

Alterar uma entidade

Bloco de código

language	js

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

{

	"atributo1"DetailedMessage" : "valorA1",
	"atributo2HelpUrl" : "valorA2"

}

Eliminar uma entidade

Bloco de código

language	js

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

//Não necessita de corpo

Eliminar um lote de entidades

...

http://tdn.totvs.com" 
}

Páginas filhas

Versões comparadas

Versão antiga 7

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

Submeter

Submeter uma mensagem, sem header

Submeter uma mensagem, com header

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

Submeter uma mensagem

de eliminação

Submeter um lote de mensagens

de eliminação

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

Entender mensagem de Falha

Alterar uma entidade

Eliminar uma entidade

Eliminar um lote de entidades

Páginas filhas

Histórico da Página

Versões comparadas

Versão antiga 7

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

Submeter

Submeter uma mensagem, sem header

Submeter uma mensagem, com header

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

Submeter uma mensagem

de eliminação

Submeter um lote de mensagens

de eliminação

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

Entender mensagem de Falha

Alterar uma entidade

Eliminar uma entidade

Eliminar um lote de entidades

Âncora
transactions
transactions
Endpoint /transactions