Dashboard de monitoramento
Visão Geral
O Dashboard é a página inicial do Partner's Portal. Ele reúne, em uma única tela, os indicadores de saúde das suas integrações com o ME e a lista das falhas recentes, para que você identifique e investigue problemas sem precisar navegar por várias telas.
Com o Dashboard você consegue responder rapidamente:
- Quantas chamadas e integrações o seu sistema executou no período e qual foi a taxa de sucesso;
- Se a situação melhorou ou piorou em relação ao período anterior;
- Quais chamadas às APIs falharam, quais integrações foram recusadas e quais notificações de webhook não chegaram ao seu endpoint;
- Onde abrir o detalhe completo de cada falha (telas de Tráfego e Eventos).
ℹ️ Nota
O Dashboard é uma ferramenta de monitoramento e diagnóstico. Os números são calculados a partir dos logs da plataforma e não devem ser usados como fonte transacional ou de conciliação. Para isso, consulte as próprias APIs ou mantenha um log no seu sistema.
Origens monitoradas
Tudo o que aparece no Dashboard vem de três origens de atividade:
| Origem | Exibida como | O que representa | Quando é considerada falha |
|---|---|---|---|
| Tráfego de API | Tráfego | Cada chamada que o seu sistema faz às APIs públicas do ME (por exemplo, POST /v1/orders). | Quando a API responde com status HTTP fora da faixa 2xx (inclui 4xx e 5xx). |
| Resultado de integração | Resultado de integração / Int. Result | O resultado do processamento assíncrono de uma integração, o mesmo conteúdo do evento de webhook integration.result. | Quando o statusCode do resultado indica que o documento não foi processado com sucesso. |
| Entrega de webhook | Webhook / Esgotadas | A entrega da notificação integration.result ao endpoint que você cadastrou no Partner's Portal. | Quando todas as tentativas de reenvio se esgotam sem sucesso (status Exhausted). Veja a lógica de retentativas. |
❗️ Atenção
Uma falha de Webhook não significa que a operação falhou no ME. Ela indica que a notificação não chegou ou não foi aceita pelo seu endpoint. O resultado da operação em si aparece na origem Resultado de integração.
Período e atualização
No topo da página ficam o filtro de período (padrão: Últimas 24 horas) e o botão Recarregar. O período escolhido vale para todos os blocos do Dashboard: indicadores, gráficos e lista de falhas.
| Período | Intervalo considerado |
|---|---|
| Últimas 24 horas | As últimas 24 horas corridas até o momento atual. |
| Últimos 7 dias | Do início do dia, 7 dias atrás, até o momento atual. |
| Últimos 30 dias | Do início do dia, 30 dias atrás, até o momento atual. |
| Período específico | Intervalo de datas escolhido por você. |
Os dados não são atualizados automaticamente. Use Recarregar para buscar novamente os indicadores e a lista com o período atual.
Indicadores (KPIs)
A primeira linha do Dashboard mostra quatro indicadores. Cada um tem um ícone de informação (ⓘ) com a explicação da métrica.
| Indicador | O que mede |
|---|---|
| Total de execuções | Total de execuções registradas no período, somando tráfego de API e resultados de integração. |
| Taxa de sucesso | Execuções com sucesso divididas pelo total de execuções (tráfego de API + integrações) no período, exibida em percentual com uma casa decimal. |
| Total de falhas | Execuções que falharam no período, separadas por origem: Tráfego e Resultado de integração. |
| Esgotadas | Notificações de webhook que esgotaram todas as tentativas de reenvio sem sucesso no período. |
Comparativo com o período anterior
Os indicadores Total de execuções e Taxa de sucesso mostram a variação em relação ao período anterior (vs. período anterior). O período anterior é a janela de mesma duração imediatamente antes do período selecionado. Por exemplo, com Últimas 24 horas selecionado, a comparação é feita com as 24 horas anteriores.
- Total de execuções: variação em percentual (
%). - Taxa de sucesso: variação em pontos percentuais (
pp). Uma queda de98.0%para95.5%aparece como-2.5pp. - Quando não há dados no período anterior, a variação aparece como —.
Gráficos
Tráfego da API — Distribuição de status
Mostra, ao longo do período, quantas chamadas às APIs do ME terminaram em 2xx, 4xx e 5xx. Use-o para identificar picos de erro e correlacioná-los com mudanças no seu sistema (deploys, cargas em lote, credenciais expiradas etc.).
- Todos: exibe as três faixas de status.
- Somente erros: oculta a faixa
2xxpara destacar4xxe5xx. Esse filtro muda apenas a visualização do gráfico; os indicadores não mudam.
A granularidade do eixo de tempo é escolhida automaticamente conforme o tamanho do período:
| Tamanho do período | Agrupamento |
|---|---|
| Até 48 horas | Por hora |
| Até 60 dias | Por dia |
| Até 365 dias | Por semana |
| Acima de 365 dias | Por mês |
Resultados de integração
Gráfico de rosca com a distribuição dos resultados de integração no período, em três fatias: Entregues, Falharam e Esgotadas.
Quando não há dados no período, os gráficos exibem a mensagem Sem dados no período selecionado.
Falhas — detalhamento
Abaixo dos gráficos fica a lista das falhas do período. Ela mostra somente registros com resultado Falhou ou Esgotado: chamadas e integrações bem-sucedidas não aparecem aqui.
Filtros por origem
| Filtro | O que lista |
|---|---|
| Todos | Falhas de todas as origens. |
| Tráfego | Chamadas às APIs que retornaram status fora de 2xx. |
| Resultado de integração | Integrações que não foram processadas com sucesso. |
| Somente esgotados | Notificações de webhook que esgotaram as tentativas de entrega. |
O filtro por origem afeta apenas a lista. O contador acima da lista mostra o total de resultados; quando aparece com + (por exemplo, N+ resultados), o valor é um limite inferior e o total real pode ser maior.
Colunas
| Coluna | Descrição |
|---|---|
| Data de Entrega | Data e hora em que a atividade ocorreu. |
| Origem | Tráfego, Int. Result ou Webhook. |
| Integração / Chave | Recurso envolvido (por exemplo, orders, contracts) e o Correlation ID da atividade. |
| Erro | Mensagem de erro extraída da resposta da API ou do resultado da integração. |
| Status de Entrega / Tentativa | Resultado (Falhou ou Esgotado) e, para webhooks, o número da tentativa. |
| Ação | Botão Detalhes, que abre o painel de detalhe da atividade. |
A lista é paginada, com 25, 50 ou 100 registros por página.
Detalhe da atividade
Ao clicar em Detalhes, um painel lateral exibe:
| Campo | Descrição |
|---|---|
| Resultado | Falhou ou Esgotado. Para webhooks esgotados, informa quantas tentativas foram feitas e que o evento não será reenviado automaticamente. |
| Código de status | Status HTTP retornado pela API (tráfego), pelo processamento (resultado de integração) ou pelo seu endpoint (webhook). |
| Tentativa | Número da tentativa de entrega (webhooks). |
| Origem | Origem da atividade. |
| Correlation ID | Identificador que liga a atividade à requisição original. Use-o para buscar a chamada em Tráfego e ao abrir chamados de suporte. |
| Event ID | Identificador do evento de webhook (resultado de integração e webhook). |
| ID do documento de origem | Identificador do registro de log que originou a atividade. |
| Mensagem de erro | Mensagem completa do erro. |
O painel também oferece um atalho para a tela de monitoramento correspondente:
- Abrir em Tráfego: para falhas de Tráfego. Abre a tela de Tráfego, onde você vê a requisição e a resposta completas (headers, corpo e tempo de resposta).
- Abrir em Eventos: para Resultado de integração e Webhook. Abre a tela de Eventos já filtrada pelo
Event IDe pela data da atividade, com o payload do evento e o histórico de tentativas de entrega.
Como investigar uma falha
- Selecione o período em que o problema ocorreu e observe os indicadores Taxa de sucesso e Total de falhas, e o gráfico de tráfego, para entender quando a falha começou e qual origem foi afetada.
- Na lista Falhas — detalhamento, filtre pela origem e abra o Detalhes do registro.
- Siga o caminho conforme a origem:
| Origem | Causa provável | O que fazer |
|---|---|---|
Tráfego com 400/422 | Payload fora do contrato da API (campo obrigatório ausente, tipo ou tamanho inválido). | Abra em Tráfego, leia o corpo da resposta, corrija o payload conforme a API Reference e reenvie. |
Tráfego com 401/403 | Credencial inválida, expirada ou sem permissão para o recurso. | Revise a API Key e o token. Veja Credenciais. |
Tráfego com 429 | Limite de requisições atingido. | Reduza a taxa de chamadas e respeite os headers ratelimit-*. Veja Rate Limit. |
Tráfego com 5xx | Instabilidade do lado do ME. | Tente novamente com backoff. Se persistir, abra um chamado informando o Correlation ID. |
| Resultado de integração | A requisição foi aceita, mas o documento não foi processado (regra de negócio, cadastro ausente etc.). | Leia a Mensagem de erro, corrija o dado na origem e reenvie o documento. |
| Webhook esgotado | Seu endpoint não respondeu 2xx em até 10 segundos durante todas as retentativas. | Verifique a disponibilidade do endpoint e as credenciais cadastradas no Partner's Portal. Veja Webhooks. |
Boas práticas
- Envie um identificador próprio no header
X-ME-CORRELATION-ID(por exemplo, o número do pedido no seu ERP). Assim a coluna Integração / Chave e as telas de Tráfego e Eventos mostram uma referência que o seu time reconhece. - Responda aos webhooks rapidamente com
2xxe processe a lógica de negócio de forma assíncrona, para evitar notificações esgotadas. - Acompanhe o comparativo com o período anterior depois de cada mudança no seu sistema: uma queda na Taxa de sucesso logo após um deploy costuma apontar a causa.
- Informe o Correlation ID ao abrir chamados de suporte com o ME.
Perguntas frequentes
Por que erros 4xx contam como falha se o problema está no meu payload? O Dashboard mede a saúde da integração do ponto de vista do seu sistema: uma chamada que não gerou o resultado esperado é uma falha, independentemente da causa. O código de status e a mensagem de erro ajudam a separar erros do seu lado (4xx) de erros do lado do ME (5xx).
Por que não vejo as chamadas bem-sucedidas na lista? A lista Falhas — detalhamento é exclusiva para falhas. Para consultar todas as chamadas, incluindo as bem-sucedidas, use a tela de Tráfego.
O filtro "Somente erros" do gráfico muda os indicadores? Não. Ele só oculta a faixa 2xx do gráfico de tráfego.