# ENG-3117 — API de modalidades e registro de contagens

Esta API é consumida pelo aplicativo nativo. O aplicativo fica responsável pela captura e pela experiência de contagem; o servidor é a autoridade para modalidade, interpretação dos códigos, propriedade da tarefa, versão e persistência.

## Modalidades globais

Rotas de gestão, autenticadas e restritas à gestão da Expedição:

- `GET /api/v1/inventory/settings/reading-modes`
- `PUT /api/v1/inventory/settings/reading-modes`

O `GET` devolve `version`, `default_mode`, `family_options`, `family_modes` e `product_modes`. O `PUT` recebe a versão lida e a configuração completa:

```json
{
  "version": 1,
  "default_mode": "quantity",
  "family_modes": [{"id": 12, "mode": "unit"}],
  "product_modes": [{"id": 481, "mode": "quantity"}]
}
```

Os modos são `quantity` (quantidade informada) e `unit` (leituras individuais). A precedência é produto → família → padrão. A atualização incrementa `version`; versão desatualizada retorna `409 inventory_reading_settings_conflict`. Exceções não são removidas automaticamente quando um produto deixa o catálogo.

A configuração é congelada no snapshot do inventário durante `POST /api/v1/inventory/{id}/start`. Alterar as modalidades depois não muda inventários existentes. Snapshots anteriores ao ENG-3117, sem modo congelado, não podem registrar contagens: a API retorna `409 inventory_reading_mode_missing` em vez de inferir uma modalidade.

## Fluxo de tarefa

1. Consultar `GET /api/v1/inventory/available-rounds`.
2. Ler tarefas com `GET /api/v1/inventory/rounds/{round}/tasks?scope=mine`.
3. Assumir uma tarefa aberta com `POST /api/v1/inventory/rounds/{round}/tasks/{task}/claim`, se necessário.
4. Iniciar/ingressar na rodada com `POST /api/v1/inventory/rounds/{round}/enter`.
5. Ler os dados congelados da tarefa em `GET /api/v1/inventory/rounds/{round}/tasks/{task}`. A resposta identifica `product.reading_mode`, unidade, códigos de integração e endereço. A rota não fornece saldo do WMS.
6. Confirmar com `PUT /api/v1/inventory/rounds/{round}/tasks/{task}/count`.

O operador deve ser participante atual da rodada, proprietário da tarefa e ter ingressado explicitamente na rodada. Nenhuma rota grava dados offline. Situação, ingresso individual e capacidades vêm da [consulta operacional de contexto](inventory-operational-api.md), também disponível em `data.context` nas leituras de tarefas.

## Confirmação

Quantidade informada:

```json
{
  "idempotency_key": "8e0397c5-4088-45bd-83e4-9a9f27b9b261",
  "expected_version": 0,
  "address_code": "123",
  "product_code": "78900123",
  "is_zero": false,
  "quantity": "12.50"
}
```

Leitura unitária:

```json
{
  "idempotency_key": "8e0397c5-4088-45bd-83e4-9a9f27b9b261",
  "expected_version": 0,
  "address_code": "{\"type\":\"address\",\"id\":123}",
  "product_code": "{\"type\":\"product\",\"product_id\":481}",
  "is_zero": false,
  "readings": [
    "{\"type\":\"storage_erp\",\"p\":\"P-481\",\"d\":\"01\",\"op\":\"9001\",\"qt\":\"1.50\"}",
    "1234500000000150"
  ]
}
```

- `address_code` aceita o ID da tarefa ou o QR de endereço `{ "type": "address", "id": ... }`; o ID precisa corresponder ao endereço congelado.
- `product_code` é obrigatório para uma contagem positiva e precisa identificar o produto congelado. O contador pode ser omitido somente na ação explícita de zero.
- Em `quantity`, envie uma string decimal, com ponto e até duas casas; o servidor não aceita zero por esse campo, valores negativos, expoentes, vírgula ou precisão maior que duas casas.
- Em `unit`, envie a lista ordenada de códigos em `readings`; o servidor interpreta cada leitura e soma as quantidades. QR `storage_erp` usa `p`, `d` e `qt` (e preserva `op` como evidência). Código numérico de 16 dígitos usa os últimos cinco dígitos como quantidade; para unidade cujo nome congelado seja `Cento`, divide por 100. Código simples usa `integration_packing_quantity`. A leitura precisa identificar o produto da tarefa. A ordem de produção é registrada, mas não restringe a contagem ao WMS.
- Quantidades das etiquetas devem ser positivas. Para registrar zero, envie `is_zero: true` sem `quantity` ou `readings`; o servidor ainda valida o endereço e registra o autor e o instante.
- Não envie `reading_mode`, identidade do operador, saldo esperado, quantidade do ERP ou IDs de escopo. Esses dados não são aceitos como autoridade do cliente.

Resposta de confirmação: `data.version`, `quantity`, `is_zero`, `reading_mode`, `actor_id`, `confirmed_at`, `reason`, `readings` e `replayed`. Quantidades são retornadas como strings decimais.

## Correções, concorrência e auditoria

Uma nova confirmação envia `expected_version: 0`. Para corrigir, envie a versão vigente, um novo `idempotency_key` e `reason` obrigatório. Só o autor da contagem vigente pode corrigi-la. Cada confirmação mantém revisão imutável, identificadores lidos e interpretações, quantidade, modalidade, autor, motivo e instante; a projeção atual é atualizada na mesma transação. Eventos da rodada e do inventário são gravados junto com a contagem.

Repita uma requisição com o mesmo `idempotency_key` e os mesmos dados quando o resultado da rede for desconhecido: a API devolve a revisão já salva com `replayed: true`, sem criar uma nova versão. Na mesma tarefa, reutilizar a chave para dados diferentes retorna `409 inventory_count_command_reused`. Versão concorrente obsoleta retorna `409 inventory_count_version_conflict`.

Erros de validação ou leitura incompatível retornam `422`; tarefa não pertencente ao operador, rodada ainda não iniciada ou falta de ingresso individual retorna `409`; acesso revogado/fora da rodada retorna `403`. O aplicativo não deve tentar gravar localmente em caso de perda de conexão.

### Fechamento e recuperação — ENG-3270

Novas escritas em rodada concluída/desconsiderada de inventário ainda iniciado usam `409 inventory_round_completed` / `inventory_round_discarded`, e não `inventory_round_not_started`. Inventário sem escrita usa `inventory_not_operable`; a consulta de contexto distingue sua situação atual.

Um comando já persistido, com acesso/propriedade/autor ainda autorizados, pode ser recuperado pelo replay original após fechamento. O recibo devolve a revisão daquele comando, enquanto o GET operacional da tarefa própria continua disponível e devolve `task.count` na versão vigente. Não substituir uma revisão mais nova por um recibo antigo. Os GETs e o replay não criam nova revisão/evento. Ver [contrato operacional](inventory-operational-api.md) para capacidades, estados e exemplos.
