Busca de Documentos (Outbound)

Busque um documento do Mercado Eletrônico pelo identificador e receba-o já no formato do seu ERP.

---

O template Busca de Documentos (Outbound) é uma consulta: em vez de enviar dados ao ME, o seu sistema busca um documento que já existe no ME, informando o identificador dele. O iPaaS busca esse documento, com todas as informações relacionadas (itens, organizações, atributos, anexos etc.), converte para o formato que o seu ERP espera com o mapeamento configurado e devolve o resultado na resposta da chamada. O iPaaS não envia o documento ao seu sistema: quem chama recebe o resultado e decide o que fazer com ele.

📘 Nota

O iPaaS não envia o documento ao seu ERP. Ele devolve o documento convertido para quem fez a chamada, e o seu sistema faz o uso que precisar (gravar no ERP, repassar a outro sistema etc.).

Quando usar

• O seu sistema recebe um aviso de que um documento foi criado ou alterado no ME (por exemplo, por um webhook) e precisa buscar esse documento no formato do ERP.
• Você quer evitar desenvolver consultas às APIs do ME e a conversão dos campos para o formato do ERP.

Tipos de documento suportados

Tipo de documento	Código
Pedido (ordem de compra)	order
Pré-pedido	pre-order
Requisição	request
Cotação	quotation
Contrato	contract
Nota fiscal	invoice
Produto	product
Fornecedor	supplier
Folha de serviço	service-sheet
Documento de folha de serviço	service-sheet-document
Usuário	user
Organização	business-organization

Configurando

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

1. Parâmetros: selecione o ERP, o Tipo de documento e informe um Identificador, que é o ID de um documento desse tipo que já existe no ME. O iPaaS usa esse documento real como exemplo para o mapeamento e para o teste.
2. Estrutura do documento: cole um exemplo do JSON que o seu ERP espera receber. Você pode adicionar comentários // ao final das linhas para explicar o significado dos campos. A IA usa esses comentários para mapear melhor.
3. Dados do Mapeamento: a IA liga os campos do ME (Origem) aos campos do seu ERP (Destino). Revise, confirme as pendentes e ajuste o que for necessário. Veja Mapeamento com IA.
4. Teste: informe um identificador e execute. O portal mostra o JSON gerado, exatamente o que a sua chamada vai receber.
5. Revisar e publicar: confira e clique em Publicar. Copie a Chave e a Secret exibidas.

❗️ Atenção

Se o ME ainda não tiver nenhum documento do tipo escolhido na sua organização, não é possível montar o exemplo. Crie ao menos um documento desse tipo no ME antes de configurar a integração.

Executando

Envie o identificador do documento no campo id do corpo, e não na URL. O id deve ser um texto (entre aspas):

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 documento no ME}"
}

Retorno

A resposta é síncrona: o documento convertido vem no campo payload, na estrutura do exemplo do ERP informado em Estrutura do documento.

200 OK

Por exemplo, uma integração de pedidos cujo exemplo do ERP segue o formato do SAP devolve:

{
  "correlationId": "{valor enviado em x-me-correlation-id}",
  "payload": {
    "PurchaseOrder": {
      "Supplier": "{order.clientSupplierId}",
      "PaymentTerms": "{order.clientPaymentConditionId}",
      "DocumentCurrency": "{order.currency}",
      "CompanyCode": "{code da organização escolhida em order.businessOrganizations}"
    },
    "PurchaseOrderNote": { "PlainLongText": "{order.note}" },
    "PurchaseOrderItem": [
      { "PurchaseOrderItem": "{...}", "OrderQuantity": "{...}", "Material": "{...}" }
    ]
  }
}

Os valores entre chaves indicam de qual campo do documento do ME cada valor veio, conforme o mapeamento publicado.

Campo	Descrição
correlationId	O valor enviado em x-me-correlation-id, ou um valor gerado pela plataforma.
payload	O documento do ME convertido para o formato do seu ERP.

A execução também fica registrada em Monitoramento > Execuções.

Erros comuns

Status	Etapa	Quando acontece
422 Unprocessable Entity	INGESTION	O corpo não é um objeto JSON, ou não tem o campo id como texto preenchido. Mensagem: The 'id' field is required.
404 Not Found	DATA_RETRIEVAL	Não existe documento com esse identificador no ME, para a sua organização. Mensagem: No 'order' record was found for id '{id}'. (com o nome da entidade do tipo de documento).
422 Unprocessable Entity	TRANSFORMATION	A conversão falhou com os dados deste documento.
422 Unprocessable Entity	—	A integração não está em um status que permite execução.
403 Forbidden	—	O token não pertence à credencial desta integração.

Exemplo de resposta para um corpo sem id:

{
  "type": "https://datatracker.ietf.org/doc/html/rfc4918#section-11.2",
  "title": "The request was well-formed but could not be processed.",
  "status": 422,
  "detail": "The 'id' field is required.",
  "failedAtStep": "INGESTION",
  "correlationId": "{correlationId}",
  "errors": [ { "field": "$.id", "messages": ["The 'id' field is required."] } ],
  "errorCode": "SCHEMA_VALIDATION_FAILED"
}

Veja o formato completo dos erros em Execuções.

Limitações

• Não entrega ao ERP. O documento convertido é devolvido na resposta. Gravar no ERP é responsabilidade do sistema que chamou.
• Um documento por chamada, buscado pelo identificador (id). Não há busca por filtros, período ou listas de documentos.
• Somente leitura. A integração não altera nada no ME.
• Um tipo de documento por integração.
• O mapeamento parte de um documento de exemplo. Campos que estavam vazios ou ausentes nesse exemplo podem não ter sido mapeados. Se os seus documentos variam muito, revise o mapeamento com um exemplo mais completo.
• Listas do ME não têm ordem garantida. Para levar um valor de uma lista (por exemplo, o código da organização "EMPRESA") para um campo único do ERP, escolha o item por um campo que o identifique, e não pela posição. Veja Escolhendo um item de uma lista.