Execuções
Como chamar uma integração, interpretar a resposta e acompanhar cada execução. No Partner's Portal, as execuções ficam em Monitoramento > Execuções.
Todas as integrações do iPaaS, qualquer que seja o template, são executadas da mesma forma: com uma chamada POST na Endpoint URL da integração. O que muda de um template para outro é o conteúdo do corpo e da resposta.
Chamando a 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}| Item | Descrição |
|---|---|
{flowId} | O ID da integração. A Endpoint URL completa aparece no Partner's Portal, na etapa Parâmetros e ao final da publicação. |
Authorization | Token gerado com a credencial da integração. Veja Autenticação. |
x-me-correlation-id | Opcional e recomendado. Veja ID de Correlação. |
| Corpo | Depende do template: o documento do ERP (Inbound), {"id": "..."} (Busca de Documentos) ou a operação de busca (Busca de Produtos). |
📘 Nota
Em todos os templates, o corpo da chamada tem limite de 5 MB (acima disso a resposta é
413) e não pode ter chaves JSON repetidas no mesmo objeto (a resposta é400).
📘 Nota
A integração só aceita execuções quando está Ativa, ou em Revisão pendente durante o teste (na Busca de Produtos, também quando Validada). Em qualquer outro status, a chamada é recusada com
422.
Resposta de sucesso
O status de sucesso depende do template:
- Criação de Documentos (Inbound):
202 Accepted. O documento foi recebido, e o resultado final é assíncrono. - Busca de Documentos (Outbound) e Busca de Produtos:
200 OK. A resposta é síncrona, e o resultado já vem no corpo.
Campos da resposta:
| Campo | Presente em | Descrição |
|---|---|---|
correlationId | Todos os templates | O ID de Correlação da execução. |
payload | Busca de Documentos (Outbound) | O documento do ME convertido para o formato do seu ERP. |
mePayload | Busca de Produtos | O resultado da busca no formato de catálogo do ME. |
No template Criação de Documentos (Inbound), o 202 confirma a entrega do documento ao ME. O resultado final é assíncrono e deve ser acompanhado em Monitoramento > Execuções.
ID de Correlação
O ID de Correlação é o identificador de rastreio de uma execução. Envie-o no header x-me-correlation-id com um valor que faça sentido para o seu sistema, por exemplo o identificador que o seu ERP ou middleware já usa nos próprios logs para aquela chamada.
x-me-correlation-id: {seu identificador de rastreio}Por que informar:
- Localizar a execução: em Monitoramento > Execuções, o filtro ID de Correlação encontra a execução pelo mesmo valor que já está nos logs do seu sistema, sem precisar guardar nenhum ID do ME.
- Ligar os dois lados: o mesmo identificador aparece no seu log, na resposta do iPaaS (
correlationId) e no detalhe da execução no Partner's Portal. - Agilizar o suporte: ao abrir um chamado, informe o ID de Correlação. É a forma mais rápida de o time do ME encontrar a execução.
Se você não enviar o header, a plataforma gera um valor e o devolve no campo correlationId da resposta. Nesse caso, guarde esse valor.
❗️ Atenção
O ID de Correlação serve somente para rastreabilidade. Ele não é usado para evitar duplicidade: duas chamadas com o mesmo valor são processadas como duas execuções diferentes. Prefira um valor único por chamada.
ℹ️ Nota
É o mesmo header recomendado para as chamadas feitas diretamente às APIs do ME (veja as boas práticas do Dashboard), mas aqui ele vale para a chamada ao iPaaS. O valor que você envia identifica a execução em Monitoramento > Execuções. Ele não é repassado às chamadas que o iPaaS faz às APIs do ME. Veja Relação com o Dashboard e o Tráfego.
Erros
Quando a execução falha, a resposta usa o formato Problem Details (RFC 7807) com Content-Type: application/problem+json. Exemplo de uma execução da Busca de Documentos sem o campo id no corpo:
{
"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"
}| Campo | Descrição |
|---|---|
status | Código HTTP do erro. |
title / detail | Resumo e descrição do problema. |
failedAtStep | Etapa da execução em que o erro ocorreu. Veja a tabela abaixo. |
correlationId | O ID de Correlação da execução. |
errors | Lista de erros, cada um com field (quando se aplica) e messages. Quando o erro vem da API do ME, por exemplo na validação do documento, as mensagens dela são repassadas aqui. |
errorCode | Código do erro, quando disponível (ex.: SCHEMA_VALIDATION_FAILED). |
Etapas da execução (failedAtStep)
| Etapa | Template | O que acontece nela |
|---|---|---|
INGESTION | Todos | Recebimento e validação do corpo da chamada. |
TRANSFORMATION | Todos | Conversão dos dados com o mapeamento configurado. |
DELIVERY | Inbound | Envio do documento convertido para a API do ME. |
DOCUMENT_PROCESSING | Inbound | Processamento do documento pelo ME (resultado assíncrono). |
DATA_RETRIEVAL | Busca de Documentos | Busca do documento no ME pelo identificador. |
REQUEST_TRANSFORMATION | Busca de Produtos | Montagem da requisição no formato do provedor. |
API_REQUEST | Busca de Produtos | Chamada à API do provedor. |
Códigos HTTP
| Status | Causas mais comuns |
|---|---|
400 Bad Request | O corpo tem chaves JSON repetidas; o parâmetro orderId da Entrega de pedido está ausente ou inválido; ou a API do ME recusou o documento com 400 (as mensagens vêm em errors). |
401 Unauthorized | Token ausente, inválido ou expirado. |
403 Forbidden | O token não pertence à credencial desta integração. |
404 Not Found | A integração não existe ou foi excluída, ou o documento buscado não foi encontrado no ME. |
413 Payload Too Large | O corpo passou do limite de 5 MB. |
422 Unprocessable Entity | A integração não está em um status que permite execução; o corpo não é um objeto JSON ou falta um campo obrigatório, como o id (INGESTION); a conversão falhou com os dados enviados; ou o ME recusou o documento por regra de negócio. |
501 Not Implemented | O tipo de documento configurado ainda não é suportado. |
502 Bad Gateway | A API do ME ou o provedor respondeu com erro inesperado. |
504 Gateway Timeout | A API do ME ou o provedor não respondeu a tempo. |
Na Busca de Produtos, um erro 4xx do provedor é devolvido com o mesmo status do provedor.
Acompanhando as execuções
Todas as execuções das suas integrações ficam registradas no Partner's Portal, em Monitoramento > Execuções. É ali que você confere o resultado de uma chamada, principalmente no template Criação de Documentos (Inbound), cujo resultado final é assíncrono.
Lista de execuções
Cada linha é uma execução:
| Coluna | O que mostra |
|---|---|
| Integração | O nome da integração executada. |
| Tipo do documento | O tipo de documento da integração. |
| Status | O resultado da execução. Veja a tabela abaixo. |
| Data de entrada | Quando a execução começou. |
| Duração | Tempo total da execução. |
| Ação | Ver timeline abre o detalhe da execução. |
A lista é paginada e pode ser atualizada pelo botão de recarregar, ao lado da paginação.
Status de uma execução
| Status | Significado |
|---|---|
| Sucesso | Todas as etapas foram concluídas. |
| Erro | Alguma etapa falhou. A timeline mostra qual. |
| Tempo esgotado | A API do ME ou o provedor não respondeu à chamada a tempo. |
| Em andamento | A execução ainda não terminou. No Inbound, é o status enquanto o ME processa o documento. |
📘 Nota
Tempo esgotado só ocorre quando a API do ME ou o provedor não responde à chamada feita pelo iPaaS. Se o ME nunca devolver o resultado do processamento de um documento Inbound, a execução permanece Em andamento: abra um chamado informando o ID de Correlação.
Filtrando
No topo da lista há três filtros rápidos: Data (período), Status e Tipo do documento. O campo Pesquisar faz uma busca livre.
Em Filtros, é possível combinar critérios:
| Filtro | Uso |
|---|---|
| ID de Correlação | Localiza a execução pelo valor enviado em x-me-correlation-id (ou devolvido em correlationId). É a forma mais direta de achar uma chamada específica. |
| ID da Entidade | Localiza pelo identificador do documento no ME, por exemplo o documento criado por uma execução Inbound. |
| Referência Externa | Localiza pela referência do documento no seu sistema. |
| Status | Sucesso, Erro, Em andamento ou Tempo esgotado. |
| Tipo do documento | O tipo de documento da integração. |
| Data de entrada | Período em que a execução começou. |
| Tipo de Evento | Regra de negócio ou Técnico. |
Os filtros podem ser salvos com um nome e reaproveitados depois, na seção Filtros salvos.
Detalhe da execução (timeline)
Clique em Ver timeline para abrir a execução. O topo mostra:
- o resultado: Execução executada com sucesso, Execução falhou no passo "{etapa}", Execução em andamento ou Execução pendente;
- o Status, a Duração e o ID de Correlação da execução;
- uma linha com as etapas da execução, o status de cada uma e o tempo entre elas.
Abaixo, a lista de Eventos traz cada etapa da execução, na ordem em que aconteceu (por exemplo Ingestion, Transformation, Delivery e Document Processing no Inbound). Cada etapa mostra:
| Informação | Descrição |
|---|---|
| Status e Duração | Resultado e tempo da etapa. |
| Tipo de evento | Regra de negócio (ex.: documento recusado pelo ME) ou Técnico (ex.: falha de comunicação). |
| Severidade | Informação, Aviso, Erro ou Crítico. |
| Código e Erro | Código e mensagem do erro, quando a etapa falha. |
| Erros de validação | Os campos e mensagens de validação, quando houver. |
Algumas etapas mostram também os dados trafegados, para você comparar com o que o seu sistema enviou:
| Etapa | Dados exibidos |
|---|---|
| Ingestion | Os Headers e o Payload recebidos. Headers de identificação, como o token de acesso, não são registrados. |
| Delivery (Inbound) | O Payload enviado à API do ME, já convertido. |
| Document Processing (Inbound) | A Mensagem de retorno do ME e o ID da Entidade do documento criado. |
Clique em uma etapa da lista de Eventos para ver os detalhes dela. No exemplo abaixo, de outra execução da mesma integração, o ME recusou o documento na etapa Document Processing com HTTP 400 e a mensagem retornada pela API do ME (o produto informado não existe no ME), classificada como Regra de negócio:
Encontrando uma chamada específica
- Envie o header
x-me-correlation-idna chamada, ou guarde ocorrelationIddevolvido na resposta. - Em Monitoramento > Execuções, abra Filtros e informe o valor em ID de Correlação.
- Clique em Ver timeline na execução encontrada.
- Se houver erro, veja a etapa que falhou, a mensagem e os erros de validação. Se precisar abrir um chamado, informe o ID de Correlação.
Relação com o Dashboard e o Tráfego
No template Criação de Documentos (Inbound), a etapa Delivery chama as APIs públicas do ME em nome da sua organização, como o seu ERP faria. Por isso essas chamadas também aparecem nas telas gerais de monitoramento do Partner's Portal:
- em Tráfego, como chamadas às APIs do ME (por exemplo,
POST /v1/orders); - no Dashboard, nos indicadores e na lista de falhas das origens Tráfego e Resultado de integração.
Nessas telas, a chamada não traz o valor que você enviou em x-me-correlation-id. O iPaaS usa um identificador interno próprio na chamada à API do ME. Para investigar uma execução do iPaaS, comece sempre por Monitoramento > Execuções, que mostra todas as etapas, inclusive a recusa da API do ME na etapa Document Processing.