# 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):

| Slug | Nome | Quando aparece |
|------|------|----------------|
| `rma` | Devoluções | Cliente pediu devolução ou troca |
| `logistics` | Logística | Problemas com coleta, transportadora, atraso |
| `orders` | Pedidos | Divergências ou pendências em pedidos |
| `payments` | Pagamentos | Estornos e divergências de repasse |
| `stock` | Estoque | Divergências de inventário |
| `stores` | Lojas | Pendências cadastrais |
| `general` | Geral | Outros casos |

**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.

```mermaid
stateDiagram-v2
    direction LR
    [*] --> new
    new --> analyzing
    analyzing --> waiting: precisa<br/>de retorno
    analyzing --> resolving
    waiting --> resolving: resposta<br/>recebida
    resolving --> resolved
    new --> cancelled
    analyzing --> cancelled
    waiting --> cancelled
    resolving --> cancelled
    resolved --> [*]
    cancelled --> [*]
```

**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:

```jsonc
{
  "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`](/reference/ocorrencias#tag/enums-de-ocorrências/GET/api/seller/occurrences/enums) devolve origem, severidade (com `color`) e status, cada um com `value` + `label` pt-BR.

---

## Listar

<a class="api-route" href="/reference/ocorrencias#tag/ocorrências/GET/api/seller/occurrences"><span class="api-method api-method-get">GET</span><span class="api-path">/api/seller/occurrences</span></a>

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

| Parâmetro | Para quê |
|-----------|----------|
| `matrix` | Slug da matriz (`rma`, `logistics`, ...). |
| `status` | Lista separada por vírgula. |
| `date_from`, `date_to` | Intervalo por data de criação. |
| `page`, `per_page` | Paginação (default `per_page=20`). |

---

## Dashboard

<a class="api-route" href="/reference/ocorrencias#tag/ocorrências/GET/api/seller/occurrences/dashboard"><span class="api-method api-method-get">GET</span><span class="api-path">/api/seller/occurrences/dashboard</span></a>

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

<a class="api-route" href="/reference/ocorrencias#tag/ocorrências/GET/api/seller/occurrences/attention"><span class="api-method api-method-get">GET</span><span class="api-path">/api/seller/occurrences/attention</span></a>

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

<a class="api-route" href="/reference/ocorrencias#tag/ocorrências/GET/api/seller/occurrences/{id}"><span class="api-method api-method-get">GET</span><span class="api-path">/api/seller/occurrences/{id}</span></a>

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

<a class="api-route" href="/reference/ocorrencias#tag/comentários/POST/api/seller/occurrences/{id}/comments"><span class="api-method api-method-post">POST</span><span class="api-path">/api/seller/occurrences/{id}/comments</span></a>

```json
{
  "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.

```mermaid
sequenceDiagram
    autonumber
    participant O as Operador
    participant A as API
    participant I as Integrador
    O->>A: comenta na ocorrência (shared)
    Note over A: comentário do operador criado<br/>(created_at > last_store_read_at)
    I->>A: GET /occurrences/dashboard
    A-->>I: items[...] com has_unread_message=true
    I->>A: GET /occurrences/{id} (abre detalhes)
    Note over A: ocorrência.last_store_read_at = agora
    I->>A: GET /occurrences/dashboard
    A-->>I: items[...] com has_unread_message=false
```

---

## 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

| Status | `message_code` | Quando |
|--------|----------------|--------|
| 401 | `UNAUTHORIZED` | Token ausente, inválido ou expirado. |
| 403 | `FORBIDDEN` | Ocorrência não vinculada à sua loja. |
| 404 | `NOT_FOUND` | ID inexistente. |
| 422 | `VALIDATION_ERROR` | `content` vazio ou maior que 2000 caracteres. |