Como testar uma API OData standard no SAP

Ativei o serviço. Como testo de verdade?

No post anterior de como ativar a API no ambiente, a gente parou no status 200: serviço registrado, nó ICF verde, Gateway respondendo. Só que 200 diz só uma coisa — a API está no ar. Não diz quais campos ela devolve, como filtrar, como navegar do cabeçalho para os itens, nem como criar um registro. É isso que vamos fazer aqui, tela por tela, usando a Sales Order (A2X) como exemplo. Primeiro dentro do próprio SAP, no SAP Gateway Client, e depois no Postman.

Escrevi pensando no funcional que quer validar um serviço standard sem depender do dev. Mas o caminho é o mesmo para qualquer um. Se você ainda não ativou o serviço, comece pelo guia Como ativar uma API OData V2 standard no SAP e volte aqui.

Rápido, só para nivelar. Uma API é a porta por onde dois sistemas trocam dados sem ninguém digitar tela. OData é o padrão que a SAP usa nessas portas. E testar a API é bater nessa porta e conferir o que volta. Tudo aqui é feito sem escrever código.

Parte 1: conhecer a API no Business Accelerator Hub

Antes de mandar a primeira chamada, vale abrir a página da API no Hub e passar pelas abas. É lá que você descobre o que a API faz, como ela autentica e quais campos ela tem. Cinco minutos aqui economizam meia tarde de tentativa e erro depois.

Aba Overview → Attributes: o cenário de comunicação (SAP_COM_0109) e os scope items que entregam a API.

A primeira aba já entrega muita coisa para o funcional: qual cenário de comunicação libera a API e quais scope items ela cobre. Se o processo do cliente não tem aquele scope item ativo, nem adianta seguir.

Authentication Methods: Basic Auth, OAuth 2.0 e X.509. São os modos que a API aceita para te autenticar.

Extensibility: se a API aceita campos de extensão (custom fields), aparece aqui.

Schema View: o modelo de dados. Cada entidade e suas variações (leitura, for create, for update).

API Consumption: snippets por linguagem e os passos para consumir a API no seu código.

A mesma aba em ABAP: como gerar o Service Consumption Model (SRVC) no ADT. Útil para quando o teste virar desenvolvimento.

SAP Help Portal: a estrutura do serviço e a tabela de entities, cada uma com link para os detalhes.

A aba API Reference: o catálogo de operações

Essa é a aba que você mais vai usar enquanto testa. Ela lista todas as operações da API, agrupadas por entidade, com o verbo HTTP colorido na frente: GET para ler, POST para criar, PATCH/PUT para alterar, DELETE para apagar.

Aba API Reference: cada entidade e suas operações, com o verbo colorido.

O que cada operação faz (sem decoreba)

Repare nas cores dos verbos na imagem acima. Cada cor é uma ação diferente, e o nome assusta mais do que o conceito. Pensa num pedido de venda e fica fácil:

O jeito mais fácil de lembrar: GET é o único que não mexe em nada, por isso é o teste mais seguro para começar. POST, PUT, PATCH e DELETE todos alteram dado, e é por isso que eles vão pedir um token de segurança lá na frente. Na mesma fileira você ainda vê MERGE e HEAD: o MERGE é o "primo antigo" do PATCH no OData V2, e o HEAD é um GET que só confere se a porta responde, sem trazer o conteúdo.

O Batch (aquele item Batch Requests no fim da lista) ele serve para mandar várias operações numa chamada só, em vez de uma de cada vez. É o que você usa quando uma depende da outra: criar o cabeçalho do pedido e já gravar os itens juntos, num pacote "tudo ou nada". Se uma parte falha, nada é gravado. Para o funcional, basta saber que ele existe e para que serve.

Abrindo uma leitura (GET): a tabela de opções de query que a API aceita ($filter, $select, $expand, $top...), cada uma com link para a doc.

Guarde essas opções de query, porque são elas que transformam um GET cru numa consulta útil. $top limita a quantidade, $filter restringe por campo, $select escolhe só os campos que interessam e $expand traz os dados relacionados junto (os itens de um pedido, por exemplo). Pensa num balcão: "me traz só os 50 primeiros ($top), só os pedidos do cliente X ($filter) e só os campos data e valor ($select)". É exatamente isso, só que escrito na URL.

Operação POST (criar pedido): parâmetros e corpo de exemplo, prontos para copiar ao selecionar no Example Value.

O mesmo POST com o Schema aberto que vai te dizer as propriedades de cada campo. É daqui que você tira a estrutura do JSON para criar um registro.

Dá para escolher o exemplo por entidade: cabeçalho, item, partner, billing plan...

Leitura por chave: A_SalesOrder('<número>') devolve um pedido só, em vez da lista inteira.

Parte 2: testar no backend com o SAP Gateway Client

Aqui está a forma mais rápida de testar uma API OData dentro do SAP. O Gateway Client (transação /N/IWFND/GW_CLIENT) ou você pode ir pela /N/IWFND/MAINT_SERVICE, procurar pelo serviço e clicar em testar, já roda com o seu usuário logado, então você não precisa montar autenticação nenhuma para começar. É o lugar certo para o primeiro teste.

A Request URI já vem montada com o nome externo do serviço. Método GET e ?$format=xml para começar.

Aquela fileira no topo (GET, POST, PUT, PATCH, MERGE, DELETE, HEAD) são os mesmos verbos da tabela lá de cima, agora em forma de botão. Para testar leitura, deixe marcado o GET. O $format=xml devolve o service document, a "capa" do serviço com a lista de collections. Para ler dados de verdade, troque por $format=json, que é bem mais fácil de ler. Mas antes de digitar a entidade na mão, deixe o sistema listar para você.

Botão Entity Set: o sistema lista as 22 collections do serviço (A_SalesOrder, A_SalesOrderItem...). Escolha uma e a URI se completa sozinha.

Antes de seguir, dois nomes que vão se repetir. Cada item dessa lista (A_SalesOrder, A_SalesOrderItem...) é uma entity: um tipo de registro. A A_SalesOrder é o cabeçalho do pedido (cliente, data, valor total); a A_SalesOrderItem são os itens (produto, quantidade). A lista inteira de uma entity é a collection, ou seja, a "tabela" daquele tipo. Escolhi a A_SalesOrder, troquei para JSON e cliquei em Execute.

Execute → status 200. A resposta traz o array de pedidos em JSON. Repare no Processing Time no topo.

Status 200 e corpo preenchido: a API está entregando dado. Agora o pulo é saber ler essa resposta. Dentro de cada registro existe um bloco __metadata com um campo uri.

Aqui no exemplo abaixo o $top=50 vai trazer os 50 primeiros registros e o $format=json muda o formato da resposta para JSON para facilitar a leitura

O bloco __metadata.uri de cada registro: é a URL exata daquele pedido.

Colando aquela uri (ou a chave) você lê um pedido só e confere campo a campo.

Mais uma leitura, status 200, com o registro pedido. É assim que você valida se o campo X existe e vem preenchido.

Navegação: A_SalesOrder('3')/to_Item devolve os itens daquele cabeçalho. É a associação "andando" pela URL.

Essa navegação é o coração do OData. Em vez de buscar pedido e itens em duas chamadas, você anda da entidade pai para a filha pela própria URL (/to_Item), ou traz tudo de uma vez com $expand=to_Item. Para o funcional, é o que confirma se o relacionamento que ele precisa já vem pronto no standard.

Até aqui, tudo foi leitura. E leitura é livre. O bicho pega quando você tenta gravar.

POST com o body com campos inválidos: status 400(sempre que for códigos 4xx é erro no payload que está enviando), ou seja, quando você for testar criação muito provalvemente se você não tiver os dados de criação 100%, sempre voltará uma mensagem de erro indicando o que está errado, semelhante as BAPIs.

Parte 3: montar e testar a collection no Postman

O Gateway Client é ótimo para o teste rápido dentro do SAP. Mas quando você quer simular o que um sistema externo enxerga, guardar as chamadas, compartilhar com o time ou alternar entre DEV, QA e PRD, o Postman é a ferramenta. E o melhor: você não monta nada do zero. O próprio Hub te dá a collection pronta.

No Postman: workspace → ... → Import.

Importando a collection Sales Order (A2X) baixada do Hub. Pode ser como Postman Collection ou OpenAPI 3.0.

Collection importada: cada entidade vira uma pasta e cada operação já vem como request pronto.

Um aviso de nomes: no Postman, collection quer dizer "pasta de chamadas salvas". Não é a mesma collection do OData (a lista de registros). Mesma palavra, coisas diferentes.

Abrindo o request "Reads all sales order headers" (GET). Não precisei escrever a URL.

A URL usa a variável {{baseUrl}}, que resolve para o caminho do serviço. Embaixo, as query options já documentadas ($top, $filter, $select, $expand...).

Repare que são as mesmas opções que vimos na API Reference e usamos no Gateway Client. OData é OData, muda só a ferramenta. Aqui você marca o $top=50 para não puxar a base inteira e o $format=json para a resposta vir legível.

Authorization da collection = Basic Auth: usuário e senha valem para todas as requests de uma vez.

Configurar a autenticação na collection, e não em cada request, é o atalho que poupa tempo. Toda chamada herda o Basic Auth. Foi exatamente a autenticação que o Hub indicou lá na aba Authentication Methods.

Send → 200 com o JSON na resposta. Mesmo resultado do Gateway Client, agora visto de fora.

Variáveis e ambientes: testar DEV, QA e PRD sem reescrever nada

Essa é a parte que mais ajuda no dia a dia. Em vez de colar a URL do sistema em cada request, você usa uma variável e deixa o ambiente decidir o valor. Trocou o ambiente, trocou o destino, e a request continua igual.

Sem ambiente ainda: Create Environment.

Ambiente DEV com a variável Base_URL apontando para o sistema de desenvolvimento.

Ambiente QAS com a mesma Base_URL, mas apontando para o sistema de QA.

Lista de ambientes: Set active escolhe onde a request vai rodar.

Trocando o ambiente ativo pelo seletor no canto. A request usa {{Base_URL}} e não muda.

Com DEV ativo, {{Base_URL}} resolve para o valor de desenvolvimento.

Mudando o ativo para QAS...

...e o mesmo {{Base_URL}} agora resolve para o valor de QA. A request é idêntica, só o ambiente mudou.

Exportar a collection para levar com você

Por último, vale guardar o que você montou. A collection exportada é um arquivo que você versiona no Git, manda para um colega ou importa em outro workspace.

Collection → ... → More → Export collection.

Export JSON: a collection vira um arquivo, pronto para compartilhar na sua EF ou versionar.

Por que isso importa para o funcional

Testar uma API não é "coisa de dev". Quando você mesmo abre o Gateway Client e dá um GET, descobre na hora se o standard já entrega aquele campo, aquele filtro, aquela navegação. Aí a conversa com o desenvolvedor muda: em vez de abrir um GAP no escuro, você chega dizendo "a API standard cobre isso aqui, falta só aquilo". Menos retrabalho dos dois lados.

Perguntas frequentes

Preciso ativar o serviço antes de testar?

Sim. O teste só funciona se o serviço estiver registrado e com o nó ICF ativo. Esse é o tema do guia Como ativar uma API OData V2 standard no SAP . Com o serviço no ar e o 200 aparecendo, você está pronto para tudo que está neste post.

Qual a diferença entre testar no Gateway Client e no Postman?

O Gateway Client roda dentro do SAP, com o seu usuário já logado: é o teste mais rápido para confirmar que a API responde. O Postman é um cliente externo, então você precisa montar a autenticação e a URL completa. Em compensação, ele guarda as chamadas, alterna entre ambientes e é fácil de compartilhar.

Por que vale a pena usar variáveis e ambientes no Postman?

Porque você testa o mesmo serviço em DEV, QA e PRD sem reescrever a request. A URL de cada sistema fica numa variável (Base_URL) dentro de cada ambiente. Troca o ambiente ativo e pronto, a chamada inteira aponta para o sistema certo. Também evita deixar host e senha "chumbados" na request.

Por que meu POST volta com erro mesmo com o serviço ativo?

Quase sempre é o token CSRF. Leitura (GET) é liberada, mas criar, alterar ou apagar exige primeiro buscar o token com um GET usando o header X-CSRF-Token: Fetch e depois mandá-lo na chamada de gravação. Sem o token, o Gateway recusa com erro (403 ou 400).

Esse fluxo serve para OData V4 também?

O conceito é o mesmo: entender a entidade, ler, filtrar, navegar e gravar. O que muda é o caminho da URL e alguns detalhes de protocolo. As query options ($filter, $select, $expand) seguem valendo, e o Postman funciona igual, bastando trocar a base do serviço.

Conclusão

Testar uma API standard é uma sequência simples quando você separa por ferramenta. No Hub você entende a API: entities, autenticação e opções de query. No Gateway Client você confirma, dentro do SAP, que ela lê, filtra e navega. No Postman você reproduz isso de fora, com a collection pronta, autenticação na collection e ambientes para DEV, QA e PRD.

O detalhe que mais derruba gente é o CSRF na hora de gravar, então guarde esse. Fora isso, o procedimento é o mesmo para qualquer API OData standard, muda só o nome do serviço. Quanto mais natural ficar esse caminho, mais cedo você valida se o standard resolve, e menos tempo perde travado em "será que a API faz isso?".

Referências oficiais

• SAP Business Accelerator Hub — Catálogo de APIs

• SAP Gateway Client (/IWFND/GW_CLIENT) — SAP Help

• Testing an OData Service in the SAP Gateway Client — SAP Help

• Postman Learning Center — Documentação oficial