Guia de Ocorrências

Ocorrências são casos abertos pela plataforma que envolvem a sua loja: uma devolução em análise, um problema de coleta, uma pendência cadastral. Aqui você lista, consulta detalhes e troca comentários com o time interno.

Conceitos

Matriz (categoria da ocorrência):

Etapa: sequência típica abaixo. Quem move a ocorrência de uma etapa para outra é sempre o operador da plataforma — você não vai encontrar uma rota para avançar ou voltar etapa, e isso é intencional: a ocorrência é um caso conduzido pelo time interno. Seu papel aqui é acompanhar e responder pelos comentários; a etapa anda conforme o operador trata o caso.

Severidade:low, medium, high, critical.

Status:open, resolved, cancelled, auto_closed (escondido por padrão nas listagens).

Origem:manual, system, scheduled.

O objeto que GET /{id} devolve, de relance — cada campo apontando para o conceito acima:

{
  "id": "01K8PB0KMM…",       // ID da ocorrência
  "title": "Devolução…",      // resumo do caso
  "severity": "high",         // ← Severidade
  "severity_label": "Alta",   // versão pt-BR p/ exibir (vale p/ todo *_label)
  "status": "open",           // ← Status
  "origin": "system",         // ← Origem
  "matrix": {…},              // ← Matriz (categoria)
  "step": {…},                // ← Etapa — quem move é a plataforma
  "assigned_to": {…},         // operador responsável (ou null)
  "is_overdue": false,        // passou do due_at
  "relations": [{…}],         // entidades vinculadas (pedido, loja, item)
  "comments": [{…}]           // só os shared (ver seção Comentários)
}

Para não hardcodar essas listas, a rota GET /api/seller/occurrences/enums devolve origem, severidade (com color) e status, cada um com value + label pt-BR.

Listar

GET/api/seller/occurrences

Retorna apenas ocorrências visíveis à sua loja. Filtros suportados:

Dashboard

GET/api/seller/occurrences/dashboard

Resumo pronto para a home:

• open_count: total em aberto.
• requires_action: ocorrências esperando resposta sua.
• last_updated_at: data da última atualização.
• items: as 10 mais relevantes (ordenadas por severidade), cada uma com o flag has_unread_message.

Cards de atenção

GET/api/seller/occurrences/attention

Agrupa as ocorrências abertas por matriz. Cada card traz title, count, accent (cor) e href (link da listagem filtrada). Aceita limit (1..10, default 4).

Detalhes

GET/api/seller/occurrences/{id}

Retorna a ocorrência completa: dados, entidades vinculadas (pedido, loja, item) e comentários.

Abrir uma ocorrência marca ela como lida e zera o aviso de "não lidas". Não chame em loop só para checar mudanças; use a listagem ou o dashboard.

Comentários

• Você só vê comentários shared. O time interno também troca anotações privadas durante a análise, mas essas ficam fora da sua visão de propósito — você recebe apenas o que foi marcado para compartilhar com a loja, então não precisa filtrar nada: tudo que chega até você já é para ser lido.
• is_system=true indica evento automático (mudança de etapa, fechamento). Exiba como timeline, não como mensagem.
• author_type: store (sua loja), operator (time interno) ou system.

Responder

POST/api/seller/occurrences/{id}/comments

{
  "content": "Segue foto do produto recebido com avaria na lateral."
}

content é obrigatório, até 2000 caracteres. Sempre criado como shared.

Flag has_unread_message

Fica true quando existe comentário shared do operador mais recente que a sua última leitura (last_store_read_at). O flag aparece nos itens do dashboard (GET /occurrences/dashboard) — a listagem comum não o devolve. Para zerar, abra a ocorrência.

Visibilidade

Você só vê uma ocorrência se ela estiver marcada como visível à loja e sua loja estiver vinculada a ela. Qualquer outro caso retorna 403.

A listagem já aplica esse filtro automaticamente, então tudo que aparece na lista pode ser aberto em detalhes.

Erros