Exemplos ponta a ponta

Um exemplo completo para cada template: da criação da integração até a confirmação do resultado.

---

Os exemplos a seguir mostram o caminho completo de uma integração: configurar, mapear, testar, publicar, executar e conferir o resultado. Os nomes de campos são os de integrações reais configuradas no Partner's Portal e das APIs públicas do ME. Os valores de cada documento aparecem como {...}, porque dependem dos seus dados.

Criação de Documentos (Inbound): pedido de compra vindo do SAP

Cenário: o SAP S/4HANA precisa criar pedidos de compra no ME.

1. Criar e configurar

1. Integrações > Templates > Generic Inbound > Usar Template.
2. Parâmetros: ERP = SAP S/4HANA, Tipo de documento = Order.
3. Estrutura do documento: cole um pedido real exportado pelo SAP, com esta estrutura:

{
  "PurchaseOrder": {
    "PurchaseOrder": "{número do pedido}",
    "Supplier": "{código do fornecedor}",
    "PaymentTerms": "{condição de pagamento}",
    "IncotermsClassification": "{incoterm}",
    "DocumentCurrency": "{moeda}",
    "CreatedByUser": "{usuário}",
    "CompanyCode": "{código da empresa}"
  },
  "PurchaseOrderNote": { "PlainLongText": "{observação}" },
  "PurchaseOrderItem": [
    {
      "PurchaseOrderItem": "{número do item}",
      "OrderQuantity": "{quantidade}",
      "PurchaseOrderItemText": "{descrição do item}",
      "PurchaseOrderQuantityUnit": "{unidade}",
      "Material": "{código do material}"
    }
  ]
}

2. Revisar o mapeamento

O destino é o formato de Create an order. Ligações sugeridas pela IA para este exemplo:

Destino (ME)	Origem (SAP)
clientOrderId	PurchaseOrder.PurchaseOrder
clientSupplierId (obrigatório)	PurchaseOrder.Supplier
clientPaymentConditionId	PurchaseOrder.PaymentTerms
incoTerms	PurchaseOrder.IncotermsClassification
currency	PurchaseOrder.DocumentCurrency
integrationTag (obrigatório)	PurchaseOrder.CreatedByUser
note	PurchaseOrderNote.PlainLongText
items.quantity	OrderQuantity, com conversão para número (percorrendo PurchaseOrderItem)
items.description	PurchaseOrderItemText
items.measurementUnit	PurchaseOrderQuantityUnit
items.clientProductId	Material

Complete os obrigatórios que ficaram sem ligação. Neste exemplo, o quadro indicava 1 obrigatório sem conexão. Em items, o único campo obrigatório da API é items.itemNumber, um número inteiro: ligue-o a PurchaseOrderItem.PurchaseOrderItem, com conversão para número. Se for enviar businessOrganizations, lembre que a API exige code e virtualEntityField em cada organização.

3. Testar e publicar

Na etapa Teste, execute o teste e aguarde Teste concluído com sucesso. Lembre-se: o pedido de teste é criado de verdade no ME. Depois, Revisar e publicar > Publicar, e copie a Chave e a Secret.

4. Executar a partir do ERP

Gere o token com a Chave e a Secret em POST Generate Token:

{ "clientId": "integrationhub-{flowId}", "clientSecret": "{secret}" }

Envie o pedido, com a mesma estrutura do exemplo:

POST https://api.mercadoe.com/integration-hub-api/v1/flows/{flowId}/execute
Authorization: Bearer {accessToken}
Content-Type: application/json
x-me-correlation-id: {seu identificador de rastreio}

Resposta:

{ "correlationId": "{valor enviado em x-me-correlation-id}" }

5. Confirmar o resultado

Em Monitoramento > Execuções, abra Filtros e informe o valor em ID de Correlação. Quando o status mudar de Em andamento para Sucesso, abra a timeline: a etapa Document Processing mostra o ID da Entidade, que é o identificador do pedido criado no ME. Se o status for Erro, a timeline mostra a etapa que falhou e a mensagem da API do ME.

---

Busca de Documentos (Outbound): pedido do ME no formato do SAP

Cenário: quando um pedido é aprovado no ME, o middleware do cliente recebe um webhook e precisa gravar o pedido no SAP S/4HANA.

1. Criar e configurar

1. Integrações > Templates > Generic Outbound > Usar Template.
2. Parâmetros: ERP = SAP S/4HANA, Tipo de documento = Order, Identificador = o ID de um pedido que já existe no ME.
3. Estrutura do documento: cole o JSON que o SAP espera receber. Neste exemplo, a mesma estrutura de pedido do SAP do exemplo anterior (PurchaseOrder, PurchaseOrderNote e PurchaseOrderItem).

2. Revisar o mapeamento

A origem é o pedido do ME, dentro de order. Ligações sugeridas pela IA para este exemplo:

Destino (SAP)	Origem (ME)
PurchaseOrder.Supplier	order.clientSupplierId
PurchaseOrder.PaymentTerms	order.clientPaymentConditionId
PurchaseOrder.DocumentCurrency	order.currency
PurchaseOrderNote.PlainLongText	order.note
PurchaseOrder.CompanyCode	um item da lista order.businessOrganizations (veja abaixo)

CompanyCode é um campo único no SAP, mas vem de uma lista no ME. Nesses casos o quadro pede para você escolher o item (aviso Escolher item), ou já traz a escolha feita pela IA. No fluxo de demonstração, a organização do pedido tem virtualEntityField = MATRIZ, e a IA gerou order.businessOrganizations[virtualEntityField = 'MATRIZ'].code. Confira sempre se o valor escolhido é o que identifica a organização certa na sua configuração do ME. Veja Escolhendo um item de uma lista.

3. Testar e publicar

Na etapa Teste, informe o identificador e confira o JSON gerado. Publique e copie a Chave e a Secret.

4. Executar a partir do middleware

POST https://api.mercadoe.com/integration-hub-api/v1/flows/{flowId}/execute
Authorization: Bearer {accessToken}
Content-Type: application/json
x-me-correlation-id: {seu identificador de rastreio}

{ "id": "{identificador do pedido no ME}" }

Resposta, com o JSON real gerado pelo fluxo de demonstração a partir do pedido criado no exemplo anterior:

{
  "correlationId": "{valor enviado em x-me-correlation-id}",
  "payload": {
    "PurchaseOrder": {
      "PurchaseOrder": "4500000123",
      "Supplier": "3423423",
      "PaymentTerms": "30 DDL",
      "IncotermsClassification": "CIF",
      "DocumentCurrency": "BRL",
      "CompanyCode": "111111",
      "CreatedByUser": "INTEGRACAO"
    },
    "PurchaseOrderNote": { "PlainLongText": "Pedido de demonstração do iPaaS" },
    "PurchaseOrderItem": [
      {
        "PurchaseOrderItem": "10",
        "OrderQuantity": "5",
        "PurchaseOrderItemText": "Parafuso sextavado M10",
        "PurchaseOrderQuantityUnit": "UN",
        "Material": "16814231123123976",
        "NetPriceAmount": "12.5"
      }
    ]
  }
}

O middleware grava o conteúdo de payload no SAP.

---

Busca de Produtos: catálogo de um provedor REST

Cenário: exibir no ME os produtos de um provedor cuja API de busca recebe um corpo JSON próprio.

1. Cadastrar o conector

Em Integrações > Configurações > Conectores > Novo conector:

1. Informações: nome, URL base e Autenticação do provedor. Clique em Testar Autenticação.
2. Recursos: adicione um recurso para cada endpoint do provedor e configure o Mapeamento de requisição de cada um. Por exemplo, para um recurso POST de busca, operação Listar (getAll), cujo provedor espera:

{ "clientDetails": { "clientId": "192533129MEP", "accountNumber": "800014904" }, "searchQuery": "drill" }

Clique em Gerar mapeamento: o searchTerm do ME é ligado a searchQuery, e clientDetails fica como valor fixo. Para o recurso de detalhe, operação Buscar por ID (getById), cujo provedor espera { "productCodes": ["3EB46"], "clientDetails": { ... } }, o productId do ME é ligado a productCodes, e o iPaaS monta a lista automaticamente.

2. Criar a integração

1. Integrações > Templates > Product Search > Usar Template.
2. Parâmetros: selecione o Connector, informe o ME Supplier ID do fornecedor no ME e escolha o Recurso de cada operação.
3. Estrutura do documento: carregue a resposta real do provedor para cada operação.
4. Dados do Mapeamento: ligue os campos da resposta do provedor ao formato de catálogo do ME. A lista de produtos do provedor vai para items, que é uma lista para lista, e o total de resultados vai para totalItems.
5. Teste: execute cada operação obrigatória, informando um Termo de busca (getAll) e um ID do produto (getById). Publique.

3. Resultado

A partir da publicação, as buscas feitas pelo ME consultam o provedor em tempo real. Para conferir o resultado, use a etapa Teste do assistente e acompanhe as buscas em Monitoramento > Execuções.