Páginas filhas
  • 3 - Equivalência entre formatos

Versões comparadas

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.
Informações
titleDocumento em construção

O documento abaixo está em elaboração e será complementado ao longo do tempo. A previsão de conclusão é 9/2/2018.

Com o objetivo de auxiliar na migração do formato SOAP/XML para o formato REST/JSON, elaboramos este documento, no qual demonstramos a equivalência de conceitos entre os formatos. Entretanto, algumas tags presentes no formato SOAP/XML não foram migradas para o novo formato, sem um substituto equivalente, por se considerar que estavam estarem em desuso ou não agregavam valorterem uma aplicação muito específica.

Formato SOAP/XMLFormato REST/JSON
Endpoints

http://<servidor>:<porta>/eai2-ws/EAIService?wsdl (DATASUL)

http://<servidor>:<porta>/public/ws/EAIService.wsdl (DATASUL Novo Frame)

http://<servidor>:<porta>/EAISERVICE.apw?wsdl (LOGIX/PROTHEUS)

http://<servidor>:<porta>/EAIService/MEX?wsdl (RM)

  • Operação SOAP padrão para recebimento: receiveMessage

http://<servidor>:<porta>/totvseai/standardmessage/v1/transactions

http://<servidor>:<porta>/totvseai/standardmessage/v1/content

  • Endpoints implementados por todos os ERPs.

Estrutura da mensagem

TOTVSMessage, composta de:

  • MessageInformation e
  • BusinessMessage ou
  • ResponseMessage ou
  • ReceiptMessage

Dois atributos principais:

header
  • Header
  • content
  • Não existe mais mensagem de recibo. O indicativo de que a mensagem foi recebida é o código HTTP 202 (Accepted).

    • Content


    Tags de MessageInformation X atributos de header
    <MessageInformation version="2.000">"
    version
    Version" : "2.000"
    <UUID>d6bbfa63-ca27-e2ac-0b14-101970f59a5b</UUID>"UUID" : "d6bbfa63-ca27-e2ac-0b14-101970f59a5b"
    <Type>BusinessMessage</Type>"
    type
    Type" : "BusinessMessage"
    <Transaction>CostCenter</Transaction>"
    transaction
    Transaction" : "CostCenter"
    <StandardVersion>1.000</StandardVersion>Sem equivalente na mensagem. A versão do padrão será designada na URL do endpoint /totvseai/standardmessage/v1.
    <SourceApplication>P1299</SourceApplication>"
    sourceApplication
    SourceApplication" : "P1299"
    <CompanyId>99</CompanyId>"
    companyId
    CompanyId" : "99"
    <BranchId>01</BranchId>"
    branchId
    BranchId" : "01"
    <UserId>admin<UserID>
    <UserId>admin<UserId>"
    userId
    UserId" : "admin"
    <Enterprise></Enterprise>Não será utilizado no formato REST/JSON
    <BusinessUnit></BusinessUnit>Não será utilizado no formato REST/JSON.
    <CompanySharingMode>C</CompanySharingMode>
    Não será utilizado no formato REST/JSON.
    "CompanySharingMode" : "C"
    <BusinessUnitSharingMode>C</BusinessUnitSharingMode>
    Não será utilizado no formato REST/JSON.
    "BusinessUnitSharingMode" : "C"
    <BranchSharingMode>E</BranchSharingMode>"BranchSharingMode" : "E"
    <BranchSharingMode>C</BranchSharingMode>Não será utilizado no formato REST/JSON.
    <Product name="PROTHEUS" version="12.1.17" />

    "

    productName

    ProductName" : "PROTHEUS"

    "

    productVersion

    ProductVersion" : "12.1.17"

    <GeneratedOn>2017-11-15T12:00:30-02:00</GeneratedOn>"
    generatedOn
    GeneratedOn" : "2017-11-15T12:00:30-02:00"
    <DeliveryType>async</DeliveryType>"
    deliveryType
    DeliveryType" : "async"
    Outras tags e suas equivalências no modelo REST/JSON
    BusinessMessage/BusinessEvent

    Atributo "

    subType

    SubType" do

    header

    Header, com valor igual a "event".

    Ex: "

    subType

    SubType" : "event".

    BusinessMessage/BusinessEvent/EntityUtilizar o atributo "
    transaction
    Transaction" do
    header
  • POST: será equivalente a <Event>upsert</Event>
  • DELETE: será equivalent a <Event>delete</Event>
    Header.
    BusinessMessage/BusinessEvent/Event

    A operação será obtida do método HTTP usado no endpoint:

    Utilizar o atributo "Event" do Header.
    BusinessMessage/BusinessEvent/IdentificationNão será utilizado no formato REST/JSON. Foi substituído pelos
    internalIds
    internal Ids informados no conteúdo da mensagem.
    BusinessMessage/BusinessRequest

    Atributo "

    subType

    SubType" do

    header

    Header com valor igual a "request".

    Ex: "subType" : "request".

    BusinessMessage/BusinessRequest/OperationUsar o atributo "
    transaction" do header.
    Transaction" do Header.
    BusinessMessage/BusinessContentAtributo "Content". Todas as tags do XML correspondentes a BusinessContent devem ser convertidas em atributos JSON, sem qualquer modificação.
    ResponseMessage/ReceivedMessage e tags filhas.

    Atributo "ReceivedMessage"´de Content. Os atributos filhos são equivalências diretas das tags filhas de <ReceivedMessage>.

    "ReceivedMessage" : {
       "UUID" : "d6bbfa63-ca27-e2ac-0b14-101970f59a5b",
       "SentBy" : "P1299",
       "Event" : "upsert"
    }

    ResponseMessage/ProcessingInformation

    Atributo "ProcessingInformation" do Content, quando a mensagem for do tipo "Response". As tags <ProcessedOn> e <Status> tem os atributos equivalentes "ProcessedOn" e "Status".

    "ProcessingInformation" : {
       "ProcessedOn" : "2017-11-14T11:47:15-03:00",
       "Status" : "ERROR",
       "Details" : [{
          "Code" : "FE001",
          "Message" : "Mensagem padrão no formato incorreto.",
          "DetailedMessage" : ""
       },{
          "Code" : "AE004",
          "Message" : "Empresa não configurada para integração.",
          "DetailedMessage" : ""
       }]
    }

    ResponseMessage/ProcessingInformation/ListOfMessagesAtributo "Details" do ProcessingInformation.
    ResponseMessage/ReturnContentAtributo "ReturnContent". Todas as tags XML devem ser convertidas em atributos JSON.
    ReceiptMessage

    A ReceiptMessage seguirá a mesma estrutura do XML, convertendo assim para JSON e atribuindo à propriedade "Content"

    EX:

    Bloco de código
    languagejs
    titleReceiptMessage
    {
      "Header": {
        ...
      },
      "Content": {
        "ReceiptData": {
          "ReceivedOn": "2019-02-11T17:59:10Z"
        },
        "ReceivedMessage": {
          "UUID": "2ea5381f-e317-6d6f-ba3b-9445b4763798",
          "SentBy": "Test"
        }
      }
    }

    Obs.: A propriedade "MessageContent" não deve ser serializada para Json, visando economia no tráfego de rede.


    Padrão de arrays "ListOf___"

    Listas de objetos no padrão "ListOf" como o exemplo abaixo:

    Bloco de código
    languagexml
    firstline1
    titleListOfItems
    linenumberstrue
    collapsetrue
    <BusinessContent>
    	<ListOfItems>
    		<Item>
    			<InternalId>01|010101|11</InternalId>
    			<Code>11</Code>
    			<Name>Sinal</Name>
    			<Value>11836.05</Value>
    		</Item>
    		<Item>
    			<InternalId>01|010101|24</InternalId>
    			<Code>24</Code>
    			<Name>Encargo Financiamento</Name>
    			<Value>12.00</Value>
    		</Item>
    		<Item>
    			<InternalId>01|010101|23</InternalId>
    			<Code>23</Code>
    			<Name>Desconto de Parcela</Name>
    			<Value>12.22</Value>
    		</Item>
    	</ListOfItems>
    </BusinessContent>

    O padrão "ListOf" considera que a tag "ListOf___" é o array e, seguindo o padrão da notação JSon, terá internamente aos colchetes a lista de objetos separados por virgula, conforme exemplo abaixo.

    Bloco de código
    languagejs
    firstline1
    titleListOfItems
    linenumberstrue
    collapsetrue
    {
       "ListOfItems": [
          {
             "InternalId": "01|010101|11",
             "Code": "11",
             "Name": "Sinal",
             "Value": 11836.05
          },
          {
             "InternalId": "01|010101|24",
             "Code": "24",
             "Name": "Encargo Financiamento",
             "Value": 12.00
          },
          {
             "InternalId": "01|010101|23",
             "Code": "23",
             "Name": "Desconto de Parcela",
             "Value": 12.22
          }
       ]
    }