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:

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.

Endpoint /transactions

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 serão apenas 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

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

transactions/

Bloco de código

language	js

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

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

Endpoint /contents

Recuperar um lote de mensagens

GET /totvseai/standardmessage/v1/contents/{transactionID_version}?page={page}&pageSize={pageSize}&order={orderList}&fields={fieldList}&{field1}={value1}&{field2}={value2}&{fieldN}={valueN}

Onde:

page:
pageSize:
order:
fields:
field1...fieldN:

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

Bloco de código

language	js

GET /totvseai/standardmessage/v1/contents/customervendor_1_000

{
    "hasNext" :  "true",
        "itemsSubType" : ["event",
        {
"Transaction" :  "CostCenter",
         "atributo1Version" : "2.000",
        "SourceApplication" :   "atributo2LGX12",
 : ""
      "ProductName" : }"LOGIX",
        {
"ProductVersion" : "12.1.15",
          "atributo1GeneratedOn" : "2017-11-14T11:47:15-03:00",
            "atributo2DeliveryType" : "async"
        },
     ]
}

Recuperar uma entidade

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" : [
        {
"Content" : {
        "ReceivedMessage" : {
            "UUID" : "d6bbfa63-ca27-e2ac-0b14-101970f59a5b",
            "SentBy" : "P1299",
            "Event" : "upsert"        
        },
        "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",
                    "Destination" : "10|1000"
                },
                {
                    "Name" : "Company",
                    "Origin" : "99",
                    "Destination" : "10"
             "atributo1"  : "valorA1",}
            "atributo2" : "valorA2"
        },
        {
            "atributo1" : "valorB1",
            "atributo2" : "valorB2"
        }
    ]
}

Alterar uma entidade

Bloco de código

language	js

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

{

	"atributo1" : "valorA1",
	"atributo2" : "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

...

]
        }
    }
}

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 8

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 uma única mensagem de inclusão/alteração

Submeter uma mensagem de eliminação

Submeter um lote de mensagens de eliminação

Endpoint /contents

Recuperar um lote de mensagens

Entender mensagem de Erro

Recuperar uma entidade

Submeter uma entidade

Submeter um lote de entidades

Alterar uma entidade

Eliminar uma entidade

Eliminar um lote de entidades

Entender mensagem de Falha

Atalhos

Páginas filhas

Histórico da Página

Versões comparadas

Versão antiga 8

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 uma única mensagem de inclusão/alteração

Submeter uma mensagem de eliminação

Submeter um lote de mensagens de eliminação

Endpoint /contents

Recuperar um lote de mensagens

Entender mensagem de Erro

Recuperar uma entidade

Submeter uma entidade

Submeter um lote de entidades

Alterar uma entidade

Eliminar uma entidade

Eliminar um lote de entidades

Entender mensagem de Falha

Âncora
transactions
transactions
Endpoint /transactions