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

language	js

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/{transactionID_version}/{internalID}

Onde:

transactionID_version: indica a transação e versão do registro a eliminar;
internalID: identifica o registro que se deseja eliminar.

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

language	js

DELETE /totvseai/standardmessage/v1/transactions/
{
	"Header" : {
    	"UUID" : "",
        "Type

Bloco de código

language	js

DELETE /totvseai/standardmessage/v1/transactions/customerVendor_2_001/10|ABC123
{
	"header" : {
    	"UUID" : "",
        "type" : "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

language	js

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

language	js

{
    "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

language	js

GET /totvseai/standardmessage/v1/contents/customervendor_1_000

{
    "hasNext" :  "true",
    "items" : [
        {
            "atributo1ReceivedMessage" : "",{
            "atributo2UUID" : "d6bbfa63-ca27-e2ac-0b14-101970f59a5b",
        },
    "SentBy"    {: "P1299",
            "atributo1Event" : "upsert"        
        },
        "ProcessingInformation" : {
            "atributo2ProcessedOn" : "2017-11-14T11:47:15-03:00",
        }
    ]
}

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

language	js

GET /totvseai/standardmessage/v1/contents/customervendor_1_000/10|30

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

Submeter uma entidade

POST /totvseai/standardmessage/v1/contents/{transactionID_version}

Onde:

...

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

POST /totvseai/standardmessage/v1/contents/{transactionID_version}

Onde:

...

Bloco de código

language	js

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

{
    "items" : ["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",
        {
            "atributo1Origin" : "valorA199|ABC001",
            "atributo2" : "valorA2"
        "Destination" : "10|1000"
                },
                },{
        {
            "atributo1Name" : "valorB1Company",
                    "atributo2Origin" : "valorB299",
         }
    ]
}

Alterar uma entidade

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

Onde:

...

Bloco de código

language	js

PUT /totvseai/standardmessage/v1/contents/customervendor_1_000/10|30

{

	"atributo1" : "valorA1",
	"atributo2" : "valorA2"

}

Eliminar uma entidade

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

Onde:

...

Bloco de código

language	js

DELETE /totvseai/standardmessage/v1/contents/customervendor_1_000/10|30

//Não necessita de corpo

...

       "Destination" : "10"
                }
            ]
        }
    }
}

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

{
    "Code" : "FE001",
    "Message" : "Mensagem padrão no formato incorreto.",
    "DetailedMessage" : "",
	"HelpUrl": "http://tdn.totvs.com" 
}

Atalhos

Páginas filhas

Versões comparadas

Versão antiga 16

Nova versão Atual

Chave

Âncora
transactions
transactions
Endpoint /transactions

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

Submeter 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

Recuperar um lote de entidades

Recuperar uma entidade

Submeter uma entidade

Submeter um lote de entidades

Alterar uma entidade

Eliminar uma entidade

Entender mensagem de Falha

Atalhos

Páginas filhas

Histórico da Página

Versões comparadas

Versão antiga 16

Nova versão Atual

Chave

ÂncoratransactionstransactionsEndpoint /transactions

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

Submeter 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

Recuperar um lote de entidades

Recuperar uma entidade

Submeter uma entidade

Submeter um lote de entidades

Alterar uma entidade

Eliminar uma entidade

Entender mensagem de Falha

Âncora
transactions
transactions
Endpoint /transactions