Entendendo e mapeando a API Standard do SAP TM para Criar Ordens de Frete (Freight Orders)

Publicado por Eliel Otavio da Silva em

Bem-vindo a este artigo detalhado sobre a integração com o SAP Transportation Management (TM) usando a API TransportationOrderGenericRequest_In. Sei que muitos já passaram ‘apuros’ com esta integração, então resolvi criar este artigo para ajudar. Um consultor experiente em integrações SAP, especialmente em cenários complexos envolvendo planejamento externo, torres de controle e TMS de terceiros precisa saber disto portanto, elaborei este guia para ajudar profissionais a implementarem criações, atualizações e cancelamentos de Ordens de Frete (Freight Orders – FO) de forma eficiente. Este conteúdo é baseado em documentações oficiais da SAP, como o SAP Help Portal, notas SAP (ex.: 2722559, 2875534, 3420340) e a referência oficial das API.

Esta documentação utiliza o schema XML que tem possibilidade de criar ordens de frete com itens referenciados, conforme a nota 2875534 a partir do S/4HANA 2020 FPS01 esta disponível.  Confira na nota 3420340  se campo atende usado no XML esta em funcionamento pois tem algumas ‘pegadinhas’ como o motorista “driver” que existe no schema mas ao usar no XML não ocorre o erro mas não há efeito ( não é colocado na ordem) porque não esta implementado pela SAP.

Criar uma FO via API é essencial em automações, como integração com middlewares (ex.: SAP CPI ou PI) ou sistemas externos para planejamento outsourced. Aqui, focamos na API TransportationOrderGenericRequest_In, que suporta criação, atualização e cancelamento de FOs, com ênfase em estruturas XML robustas para integrações complexas, incluindo múltiplos stages, itens hierárquicos e referências a documentos base.

Neste artigo, você aprenderá:

  • Onde encontrar a API.
  • Como testar no SAP (via SPROXY).
  • Interpretação detalhada dos campos e estruturas.
  • Dicas para identificar tags obrigatórias e montar XMLs corretos.
  • Boas práticas para testes e Troubleshooting
  • Um exemplo completo de XML para criação, com explicação campo a campo.
  • Exemplos de XML para atualização e cancelamento de FOs.

Vamos começar!

1. Onde Encontrar a API no SAP

A API TransportationOrderGenericRequest_In é um web service SOAP padrão do SAP TM, projetado para cenários de planejamento externo. Ela permite replicar FOs planejadas, incluindo referências a Freight Units (FUs), veículos e etapas de transporte.

Documentações de Referência Validadas:

Pré-requisitos: Certifique-se de que business partners (BPs), produtos, locations e recursos (ex.: veículos) estejam replicados no SAP TM via interfaces dedicadas. O sistema emissor deve estar registrado no SLD (System Landscape Directory) para autenticação.

2. Onde Testar no SAP

A forma mais simples e recomendada para testar é via transação SPROXY no SAP TM. Isso permite simular chamadas inbound sem middlewares.

Passos Detalhados:

  1. Acesse a transação SPROXY:

Clique neste ícone para abrir o serviço específico:

Coloque o código abap do serviço que é /SCMTMS/II_CPX_TOR_GN_RQ_IN e clique para visualizar:

Clique para testar:

Clique para executar :

Clica para editar e colocar seu XML para testar:

Após colocar seu xml, clique em executar:

Se tiver este resultado esta ok e precisa efetuar o commit para ver o resultado:

Para fazer o commit utilize essa opção:

Neste momento basta olhar a ordem de frete criada.

3. Entendendo a Estrutura Principal da API

Na nota 3420340 tem um arquivo anexo que demonstra a macro estrutura e campo a campo e se esta implementada, segue um print sobre a estruturação do xml e posterior detalhamento sobre:

A raiz do XML é <n0:TransportationOrderGenericRequest xmlns:n0=”http://sap.com/xi/SAPGlobal20/Global”>. Ela contém dois blocos principais:

  • MessageHeader: Metadados da mensagem.
  • TransportationOrder: Detalhes da FO propriamente dita.

Validação: Essa estrutura é confirmada pela documentação oficial, com suporte a actionCodes para operações CRUD.

3.1 MessageHeader – Identificação da Mensagem

Este bloco é obrigatório e fornece contexto para rastreabilidade.

Exemplo:

<MessageHeader>

  <ReferenceID>04</ReferenceID>

  <CreationDateTime>2025-10-04T12:00:00.1234567Z</CreationDateTime>

  <SenderBusinessSystemID>QS4800</SenderBusinessSystemID>

  <BusinessScope>

    <TypeCode>3</TypeCode>

    <ID>EXTERNAL_PLANNING</ID>

  </BusinessScope>

</MessageHeader>

Campos Importantes (Validados):

  • ReferenceID: ID único da mensagem para rastreio (obrigatório para logs).
  • CreationDateTime: Data/hora de criação em formato ISO 8601 (obrigatório; use timezone Z para UTC).
  • SenderBusinessSystemID: ID do sistema emissor (deve corresponder ao registrado no SLD/PI/CPI; obrigatório).
  • BusinessScope: Fixo para cenários TM externos.
    • TypeCode: 3 (para escopo de negócios).
    • ID: EXTERNAL_PLANNING (para planejamento outsourced) ou EVENT_ONLY (para eventos de execução).

3.2 TransportationOrder – Estrutura da Ordem de Frete

Este é o bloco principal, com atributos para controle de operação.

Exemplo de Atributos:

XML

<TransportationOrder actionCode=”01″ changeOrdinalNumberValue=”123″ completeTransmissionIndicator=”false”>

Atributos Validados:

  • actionCode: Define a operação (obrigatório).
    • 01: Criar (Create).
    • 02: Atualizar (Change).
    • 03: Cancelar/Excluir (Delete).
  • changeOrdinalNumberValue: Número de versão para controle de concorrência (pode ser qualquer valor em criação; obrigatório em updates para evitar conflitos; deve ser incremental em alterações é recomendado gravar essa ordem para utilizar nas próximas chamadas).
  • completeTransmissionIndicator:
    • false (recomendado na maioria dos cenários reais)

Permite transmissão parcial (delta).

O SAP atualiza somente os campos e estruturas enviados no XML.

Tudo o que não for mencionado permanece inalterado (stages, itens, referências, custos, documentos, etc.).

→ Ideal para atualizações frequentes, integrações complexas com múltiplos sistemas e para evitar sobrescrever acidentalmente dados gerenciados por outros processos.

  • True

Exige transmissão completa (full load).

O SAP interpreta campos/estruturas não enviados como intenção de exclusão/limpeza (seta para vazio ou valor default).

→ Usado principalmente em:

• Criação inicial (quando se deseja garantir estrutura limpa)

• Cancelamento (actionCode=03 – mais seguro)

• Sincronizações completas onde o sistema externo tem a visão total e quer substituir tudo

4. Campos-Chave da Ordem de Frete (Validados e Explicados)

Aqui, detalho campos essenciais, baseados em nota 2722559 (elementos mínimos obrigatórios) e help portal.

4.1 Tipo e Categoria

  • TypeCode: Código do tipo de FO (configurado em customizing SAP TM; ex.: ZABC para custom).
  • CategoryCode: Sempre “TO” para Transportation Order (obrigatório).

4.2 Transportadora (CarrierParty)

  • InternalID: ID interno do BP da transportadora (obrigatório para atribuição).

4.3 Motorista (Driver)

  • Party/InternalID: ID do BP cadastrado como motorista (opcional, mas útil em execuções).

4.4 Stages – Etapas do Transporte

Cada <TransportationStage> define uma perna do transporte. Obrigatório pelo menos um stage.

Campos Essenciais:

  • ID: Identificador único da etapa.
  • OrdinalNumberValue: Sequência (1, 2, 3…; obrigatório para ordenação).
  • ExpectedDepartureDateTime / ExpectedArrivalDateTime: Datas previstas em ISO (obrigatórias).
  • MainLoadingLocation / MainUnloadingLocation:
    • InternalID: ID da location no SAP TM (obrigatório).
  • ItemAssignment: Vincula itens (ex.: veículos ou produtos) ao stage. Pode ter múltiplos <ItemID>.

4.5 TransportationTerms – Modal de Transporte

  • TransportModeCode: Código do modal (obrigatório).
    • 01: Rodoviário.
    • 02: Ferroviário.
    • 03: Aéreo (e outros conforme customizing).

4.6 Documentos de Referência Base (BaseBusinessTransactionDocumentReference)

  • ID: ID do documento base (ex.: FU ou entrega).
  • TypeCode: Tipo (ex.: 1122 para FU; obrigatório se referenciando).

4.7 Item – Detalhes de Recursos

Itens podem ser veículos (AVR/PVR) ou produtos (PRD), com hierarquia.

  • ID: Identificador único do item.
  • CategoryCode: AVR (Active Vehicle Resource), PVR (Passive), PRD (Product).
  • VehicleResource: Para veículos.
    • TransportMeansID: Placa ou ID do veículo.
    • TransportMeansTypeCode: Tipo (ex.: 0001 para caminhão).
  • HierarchyRelationship/ParentItemID: Para itens filhos (ex.: produto vinculado a veículo).
  • BaseBusinessTransactionDocumentReference: Referência ao FU/produto.

Tags Obrigatórias Gerais (de Nota 2722559): MessageHeader completo, TypeCode, CategoryCode, pelo menos um Stage com locations, e actionCode válido.

5. Boas Práticas para Montar XML, Testes e Troubleshooting

  • Interpretar Campos: Use XSD da API no Accelerator Hub para validar tipos e obrigatoriedade.
  • Montar XML Corretamente: Evite namespaces errados; use ferramentas como XMLSpy para validação. Comece com XML mínimo e adicione complexidade.
  • Testes: Inicie em SPROXY com dados mock. Para integrações reais, configure endpoints em SOAMANAGER.
  • Troubleshooting:
    • Erros comuns: Campos obrigatórios ausentes (ex.: CreationDateTime), IDs inválidos (verifique BPs/locations).
    • Monitoramento e logs: SRT_MONI, SLG1 ou CPI (se for o seu caso).

6. Exemplo Completo de XML para Criação (actionCode=”01″)

Aqui está o XML funcional do seu documento, agora documentado campo a campo. Ele cria uma FO com um stage, dois veículos (AVR e PVR), um produto (PRD) vinculado, e referência a FU. Validado o xml abaixo que ele atende aos requisitos mínimos da nota 2722559.

<n0:TransportationOrderGenericRequest xmlns:n0="http://sap.com/xi/SAPGlobal20/Global">
  <!-- MessageHeader: Metadados da mensagem -->
  <MessageHeader>
    <ReferenceID>04</ReferenceID>  <!-- ID único para rastreio -->
    <CreationDateTime>2025-10-04T12:00:00.1234567Z</CreationDateTime>  <!-- Data de criação (ISO, obrigatório) -->
    <SenderBusinessSystemID>QS4800</SenderBusinessSystemID>  <!-- ID do sistema emissor (obrigatório) -->
    <BusinessScope>
      <TypeCode>3</TypeCode>  <!-- Tipo de escopo (fixo: 3) -->
      <ID>EXTERNAL_PLANNING</ID>  <!-- ID de escopo (para planejamento externo) -->
    </BusinessScope>
  </MessageHeader>
  <!-- TransportationOrder: Detalhes da FO -->
  <TransportationOrder actionCode="01" changeOrdinalNumberValue="123" completeTransmissionIndicator="false">
    <!-- actionCode="01": Criação; changeOrdinalNumberValue: Versão; completeTransmissionIndicator=false: Permite parciais -->
    <TypeCode>ZABC</TypeCode>  <!-- Tipo da FO (customizado) -->
    <CategoryCode>TO</CategoryCode>  <!-- Categoria: Transportation Order (obrigatório) -->
    <CarrierParty>
      <InternalID>1500000</InternalID>  <!-- ID da transportadora (BP) -->
    </CarrierParty>

<!--   Vou deixar aqui a estrutura do motorista para o futuro, porém a mesma ainda não funciona conforme a nota 3420340 diz que não foi implementada.
    <Driver>
      <Party>
        <InternalID>60000000</InternalID>  
      </Party>
    </Driver>
-->
    <!-- Stage: Etapa de transporte -->
    <TransportationStage>
      <ID>10</ID>  <!-- ID da etapa -->
      <OrdinalNumberValue>1</OrdinalNumberValue>  <!-- Sequência (obrigatório) -->
      <ExpectedDepartureDateTime>2025-11-14T12:00:00.1234567Z</ExpectedDepartureDateTime>  <!-- Saída prevista -->
      <ExpectedArrivalDateTime>2025-11-14T15:00:00.1234567Z</ExpectedArrivalDateTime>  <!-- Chegada prevista -->
      <MainLoadingStopID>10</MainLoadingStopID>  <!-- ID da parada de carga -->
      <MainLoadingLocation>
        <InternalID>SP_A001</InternalID>  <!-- Location de origem (obrigatório) -->
      </MainLoadingLocation>
      <MainUnloadingStopID>20</MainUnloadingStopID>  <!-- ID da parada de descarga -->
      <MainUnloadingLocation>
        <InternalID>0001100112</InternalID>  <!-- Location de destino (obrigatório) -->
      </MainUnloadingLocation>
      <!-- ItemAssignment: Vincula itens ao stage -->
      <ItemAssignment>
        <ItemID>1000000</ItemID>  <!-- Item veículo AVR -->
        <ItemID>1000020</ItemID>  <!-- Item veículo PVR -->
      </ItemAssignment>
      <ItemAssignment>
        <ItemID>10</ItemID>  <!-- Item produto PRD -->
      </ItemAssignment>
    </TransportationStage>
    <!-- TransportationTerms: Modal -->
    <TransportationTerms>
      <TransportModeCode>01</TransportModeCode>  <!-- 01: Rodoviário -->
    </TransportationTerms>
    <!-- Referência base (ex.: FU) -->
    <BaseBusinessTransactionDocumentReference>
      <ID>0080000323</ID>  <!-- ID do documento base -->
      <TypeCode>1122</TypeCode>  <!-- Tipo: 1122 para FU -->
    </BaseBusinessTransactionDocumentReference>
    <!-- Itens: Recursos e produtos -->
    <Item>
      <ID>1000000</ID>  <!-- ID do item -->
      <CategoryCode>AVR</CategoryCode>  <!-- Active Vehicle Resource -->
      <VehicleResource>
        <ID>BIT-BS</ID> <!-- ID do veículo -->
        <TransportMeansID>ABC-123</TransportMeansID>  <!-- ID do veículo (placa) -->
        <TransportMeansTypeCode>0001</TransportMeansTypeCode>  <!-- Tipo de veículo -->
      </VehicleResource>
    </Item>
    <Item>
      <ID>1000020</ID>  <!-- ID do item -->
      <CategoryCode>PVR</CategoryCode>  <!-- Passive Vehicle Resource -->
      <VehicleResource>
        <TransportMeansID>xxx-123</TransportMeansID>  <!-- ID do veículo passivo -->
        <TransportMeansTypeCode>0001</TransportMeansTypeCode>  <!-- Tipo -->
      </VehicleResource>
    </Item>
    <Item>
      <ID>10</ID>  <!-- ID do item -->
      <CategoryCode>PRD</CategoryCode>  <!-- Product -->
      <HierarchyRelationship>
        <ParentItemID>1000000</ParentItemID>  <!-- Vincula ao veículo pai (hierarquia) -->
      </HierarchyRelationship>
      <BaseBusinessTransactionDocumentReference>
        <ID>4100000426</ID>  <!-- ID do FU/produto -->
        <TypeCode>1122</TypeCode>  <!-- Tipo: FU -->
      </BaseBusinessTransactionDocumentReference>
    </Item>
  </TransportationOrder>
</n0:TransportationOrderGenericRequest>


7. Exemplo de XML para Atualização (actionCode=”02″)
Você pode utilizar o mesmo XML de criação basta colocar o actionCode para “02” que irá efetuar a alteração. Porem resolvi fazer um exemplo diferente para quando não há necessidade de alteração de diversos campos e com referência ao FO.
Exemplo mínimo (atualiza datas de um stage):

<n0:TransportationOrderGenericRequest xmlns:n0="http://sap.com/xi/SAPGlobal20/Global">
  <MessageHeader>
    <!-- ... (mesmo que criação) -->
  <ReferenceID>05</ReferenceID>  <!-- ID único para rastreio -->
    <CreationDateTime>2025-10-04T12:00:00.1234567Z</CreationDateTime>  <!-- Data de criação (ISO, obrigatório) -->
    <SenderBusinessSystemID>QS4800</SenderBusinessSystemID>  <!-- ID do sistema emissor (obrigatório) -->
    <BusinessScope>
      <TypeCode>3</TypeCode>  <!-- Tipo de escopo (fixo: 3) -->
      <ID>EXTERNAL_PLANNING</ID>  <!-- ID de escopo (para planejamento externo) -->
    </BusinessScope>
  </MessageHeader>
  <TransportationOrder actionCode="02" changeOrdinalNumberValue="124" completeTransmissionIndicator="false">
  <CategoryCode>TO</CategoryCode>  <!-- Categoria: Transportation Order (obrigatório) -->

<BaseBusinessTransactionDocumentReference>
<ID>6100000462</ID>  <!-- ID do FO -->
<TypeCode>614</TypeCode> <!-- TIPO: FO -->
</BaseBusinessTransactionDocumentReference>

    <TransportationStage>
      <ID>10</ID>  <!-- Stage a atualizar -->
      <MainLoadingStopID>10</MainLoadingStopID>
<MainUnloadingStopID>20</MainUnloadingStopID>
      <ExpectedDepartureDateTime>2025-11-15T12:00:00.1234567Z</ExpectedDepartureDateTime>  <!-- Nova data de saída -->
      <ExpectedArrivalDateTime>2025-11-15T15:00:00.1234567Z</ExpectedArrivalDateTime>  <!-- Nova chegada -->
    </TransportationStage>
  </TransportationOrder>
</n0:TransportationOrderGenericRequest>

Validação: Incremente changeOrdinalNumberValue para evitar conflitos.

8. Exemplo de XML para Cancelamento (actionCode=”03″)

Para cancelar, use actionCode=”03″ e forneça apenas o ID da FO. Exemplo mínimo:

<n0:TransportationOrderGenericRequest xmlns:n0="http://sap.com/xi/SAPGlobal20/Global">
  <MessageHeader>
    <!-- ... (mesmo que criação) -->
  <ReferenceID>05</ReferenceID>  <!-- ID único para rastreio -->
    <CreationDateTime>2025-10-04T12:00:00.1234567Z</CreationDateTime>  <!-- Data de criação (ISO, obrigatório) -->
    <SenderBusinessSystemID>QS4800</SenderBusinessSystemID>  <!-- ID do sistema emissor (obrigatório) -->
    <BusinessScope>
      <TypeCode>3</TypeCode>  <!-- Tipo de escopo (fixo: 3) -->
      <ID>EXTERNAL_PLANNING</ID>  <!-- ID de escopo (para planejamento externo) -->
    </BusinessScope>
  </MessageHeader>
  <TransportationOrder actionCode="03" changeOrdinalNumberValue="125" completeTransmissionIndicator="true">

<BaseBusinessTransactionDocumentReference>
<ID>6100000462</ID>  <!-- ID do FO -->
<TypeCode>614</TypeCode> <!-- TIPO: FO -->
</BaseBusinessTransactionDocumentReference>


  </TransportationOrder>
</n0:TransportationOrderGenericRequest>

Validação: completeTransmissionIndicator=true é recomendado para deletes totais.

Conclusão

Este guia aprimorado demonstra integrações complexas no SAP TM, com XMLs validados e prontos para uso. Teste em seu ambiente e ajuste IDs conforme seu customizing. Se precisar de mais detalhes ou variações (ex.: múltiplos stages). Fique à vontade para compartilhar comentários ou experiências adicionais relacionadas às integrações do SAP TM Freight Order.

Print Friendly, PDF & Email
Categorias: AbapDicas SAPSAP TM

Eliel Otavio da Silva

Graduado em Ciência da Computação com MBA em Gestão de Projetos. Ampla experiência atuando há mais de 18 anos como Analista de sistemas, Funcional SAP/Gerente de projetos, participando de forma relevante em diversos projetos, otimizando processos e gerando melhorias para os clientes atendidos. Responsável por diversas equipes ao longo da carreira, participando ativamente da implantação de novas funcionalidades, atuando na coordenação das squads. Vivência na análise de sistemas e planejamento de projetos, identificando possíveis soluções tecnológicas, atuando de acordo com as necessidades de cada cliente. Participação ativa na configuração de módulos MM e SD, realizando integrações entre os ERP´s. Realização de diversos cursos relacionados a SAP MM, SD e TM, visando aprimorar meus conhecimentos e me manter atualizado.

Posts relacionados

Dicas SAP

Let’s do something practical using SAP AI (Joule) tocode

How about building a Fiori app using AI to create it for you? So if you liked it, let’s continue.What is the Joule?It is a generative AI used by SAP to interact with SAP applications.Initially Leia mais…

Dicas SAP

Vamos fazer algo na prática utilizando a IA da SAP (Joule) para codificar

Que tal construir um aplicativo fiori utilizando para IA criar para você? Então se gostou vamos continuar. O que é a Joule ? É uma IA generativa usada pela SAP, para interação com as aplicações Leia mais…

Abap

Vamos aprender um pouco sobre o conceito Clean core

O Conceito de “núcleo limpo” no contexto do SAP S/4HANA Cloud ERP, destacando sua importância para as empresas que enfrentam desafios como interrupções na cadeia de suprimentos, mudanças nas preferências dos clientes e conformidade regulatória. Leia mais…