Criação de Documentos (Inbound)

Envie documentos do seu ERP no formato dele e deixe o iPaaS criá-los no Mercado Eletrônico.

---

O template Criação de Documentos (Inbound) recebe um documento enviado pelo seu sistema (ERP, middleware ou qualquer aplicação), converte esse documento para o formato da API pública do ME com o mapeamento configurado e cria o documento no ME.

O seu sistema continua enviando o JSON no formato que já produz. Não é preciso adaptá-lo ao contrato das APIs do ME.

Quando usar

• O seu ERP precisa criar pedidos, notas fiscais, contratos, fornecedores, produtos e outros documentos no ME.
• Você quer evitar desenvolver e manter a conversão de campos para o formato do ME.

Tipos de documento suportados

O formato de destino de cada tipo de documento é o da API pública do ME indicada abaixo. Na etapa de mapeamento, esse formato é carregado automaticamente.

Tipo de documento	Operação executada no ME
Produto	POST Create a product
Requisição	POST Create a request
Cotação	POST Create a quotation
Contrato	POST Create a contract
Nota fiscal	POST Create an invoice
Pedido (ordem de compra)	POST Create an order
Entrega de pedido	POST Create an order delivery (exige o parâmetro orderId, veja abaixo)
Contas a pagar	POST Create accounts payable
Contas a receber	POST Create accounts receivable
Fornecedor	POST Create a supplier
Centro de custo	POST Create a cost center
Folha de serviço	POST /v1/service-sheets (API de folhas de serviço do ME)

Configurando

Crie a integração em Integrações > Templates > Generic Inbound > Usar Template e siga as etapas do assistente:

1. Parâmetros: selecione o ERP, ou cadastre um novo, e o Tipo de documento. A Endpoint URL da integração é exibida nesta etapa.
2. Estrutura do documento: cole um exemplo real do JSON que o seu ERP vai enviar. Quanto mais completo o exemplo (todos os campos e ao menos um item em cada lista), melhor o mapeamento.
3. Dados do Mapeamento: a IA liga os campos do seu ERP (Origem) aos campos do ME (Destino). Revise as sugestões, confirme as pendentes e garanta que todos os campos obrigatórios do ME estão ligados. Veja Mapeamento com IA.
4. Teste: o iPaaS executa a integração com o payload de exemplo e aguarda o ME processar o documento.
5. Revisar e publicar: confira o resumo e clique em Publicar. Copie a Chave e a Secret exibidas.

❗️ Atenção

O teste é uma execução real: o documento de exemplo é criado no ME. Use dados de teste ou um ambiente de homologação. Se preferir, use Pular teste, que valida a integração sem executar o teste.

Executando

Envie o documento do seu ERP, na mesma estrutura do exemplo usado no mapeamento, para a Endpoint URL da integração:

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}

O corpo é o JSON do seu ERP. Por exemplo, uma integração de pedidos mapeada a partir de um exemplo do SAP recebe um corpo com esta estrutura:

{
  "PurchaseOrder": {
    "PurchaseOrder": "{número do pedido no ERP}",
    "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}"
    }
  ]
}

O iPaaS converte esse corpo para o formato de Create an order, por exemplo PurchaseOrder.PurchaseOrder → clientOrderId, PurchaseOrder.Supplier → clientSupplierId, PurchaseOrder.PaymentTerms → clientPaymentConditionId, PurchaseOrder.IncotermsClassification → incoTerms, PurchaseOrder.DocumentCurrency → currency, PurchaseOrderNote.PlainLongText → note e os itens de PurchaseOrderItem → items (quantity, description, measurementUnit, clientProductId...), conforme o mapeamento publicado.

• O corpo é um único documento: um objeto JSON com até 5 MB e sem chaves repetidas.
• O header x-me-correlation-id é opcional, mas recomendado. Veja ID de Correlação.

Entrega de pedido: parâmetro orderId

No tipo Entrega de pedido, a entrega é registrada em um pedido já existente. Informe o identificador desse pedido na query string:

POST https://api.mercadoe.com/integration-hub-api/v1/flows/{flowId}/execute?orderId={id do pedido no ME}

Sem o orderId, a execução é recusada com 400 Bad Request na etapa DELIVERY:

{
  "type": "https://datatracker.ietf.org/doc/html/rfc9110#section-15.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "The downstream service returned an unexpected response.",
  "failedAtStep": "DELIVERY",
  "correlationId": "{correlationId}"
}

Retorno

O processamento no ME é assíncrono. A resposta imediata confirma apenas que o iPaaS recebeu, converteu e entregou o documento ao ME:

202 Accepted

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

O correlationId é o valor enviado em x-me-correlation-id. Se o header não for enviado, a plataforma gera um valor e o devolve aqui. Guarde esse valor para localizar a execução depois.

📘 Nota

O 202 Accepted não significa que o documento já foi criado no ME. O resultado final chega depois, quando o ME termina de processar o documento.

Como confirmar que o documento foi criado

1. Acesse Monitoramento > Execuções no Partner's Portal.
2. Em Filtros, filtre por ID de Correlação com o valor devolvido em correlationId.
3. Confira o Status da execução:

Status da execução	Significado
Em andamento	O documento foi entregue ao ME e está sendo processado.
Sucesso	O ME criou o documento.
Erro	A conversão falhou, o ME recusou o documento ou o processamento terminou com erro.
Tempo esgotado	Uma etapa excedeu o tempo limite.

4. Clique em Ver timeline para ver as etapas. Quando o ME conclui o processamento, a etapa DOCUMENT_PROCESSING mostra o resultado, e o ID da Entidade traz o identificador do documento criado no ME. Em caso de erro, a etapa mostra a mensagem devolvida pelo ME.

Veja o passo a passo completo em Acompanhando as execuções.

Erros na resposta imediata

Se o problema for detectado antes ou durante a entrega (payload inválido, falha na conversão, documento recusado pela API do ME, integração não executável etc.), a resposta já traz o erro no formato Problem Details (application/problem+json), com a etapa em que a execução falhou (failedAtStep). Quando o erro vem da API do ME, o status e as mensagens de erro da API são repassados em errors. Veja o formato e todos os códigos em Execuções.

Limitações

• Apenas criação. O template só cria documentos (POST). Atualização (PUT/PATCH), cancelamento e exclusão de documentos ainda não estão disponíveis. Enviar de novo um documento já integrado tenta criá-lo outra vez.
• Um documento por chamada. Não é possível enviar uma lista de documentos em uma única execução.
• Resultado assíncrono. A confirmação de que o documento foi criado não vem na resposta da chamada. Consulte o monitoramento.
• Sem deduplicação. O iPaaS não identifica documentos repetidos. O x-me-correlation-id serve só para rastreabilidade e não impede o envio em duplicidade.
• Um tipo de documento por integração. Para integrar pedidos e notas fiscais, por exemplo, crie uma integração para cada um.
• Formato fixo de entrada. O mapeamento é feito sobre a estrutura do exemplo informado. Se o seu ERP mudar o formato do JSON (campos novos, renomeados ou em outra estrutura), atualize o mapeamento.
• Entrega de pedido exige o orderId na query string.
• O corpo da requisição tem limite de 5 MB e não pode ter chaves JSON duplicadas.