# Métricas de uso

> Declare métricas no manifesto, registre consumo em lote com outbox resiliente e bloqueie operações quando o limite do plano for atingido.

Apps comercializados na Plataforma podem medir consumo — pedidos emitidos, documentos processados, mensagens enviadas — e a Central de Ativações usa esses números para planos, limites e excedentes.

## 1. Declare as métricas

```json title="central.app.json"
{
  "usageMetrics": [
    {
      "code": "pedidos",
      "name": "Pedidos emitidos",
      "unit": "pedido",
      "description": "Cada pedido enviado ao fornecedor.",
      "defaults": {
        "included": 500,
        "onLimit": "block",
        "overage": { "mode": "unit", "priceMinor": 50 }
      }
    }
  ]
}
```

Até 10 métricas. `GET /core/usage-metrics` publica a lista para a Central pré-preencher os limites do plano.

| `defaults` | Valores |
|---|---|
| `included` | Inteiro ≥ 0 incluído no ciclo |
| `onLimit` | `block` (recusa) ou `auto_addon` |
| `overage.mode` | `unit` ou `block` (com `blockSize`) |
| `overage.priceMinor` | Preço em centavos |

## 2. Registre o consumo

```javascript
const { usage } = require("@oondemand/oon-core-back");

usage.record("pedidos", 1, { tenantId: req.accessContext.tenantId });
```

`record` acumula em memória e envia a cada `OON_USAGE_FLUSH_MS` (padrão 15 s) um lote com ID único. O lote passa pela outbox `oon_usage_outbox` no MongoDB do App: sobrevive a reinício, qualquer réplica reenvia (lease de 30 s, backoff, até 20 tentativas) e a Central conta cada ID uma vez. O encerramento do processo grava o que estiver em memória.

## 3. Bloqueie no limite

```javascript
// Confere antes de uma operação cara
await usage.assertAvailable("pedidos", { tenantId: req.accessContext.tenantId });
```

Recusa com **423 `USAGE_LIMIT_REACHED`** quando o plano bloqueia ao atingir o incluído, somando o estado da Central (cache de 60 s) e o consumo ainda não enviado. Sem resposta da Central, a operação segue.

Em uma rota privada, confira antes e registre depois do sucesso:

```javascript
const { defineRoutes, usage } = require("@oondemand/oon-core-back");

defineRoutes("/pedidos-envio", (router) => {
  router.private.post("/:id/enviar", { permission: "pedidos.write" }, async (req, res) => {
    await usage.assertAvailable("pedidos", { tenantId: req.accessContext.tenantId });
    // ... envia
    usage.record("pedidos", 1, { tenantId: req.accessContext.tenantId });
    res.json({ ok: true });
  });
});
```

`usage.limit(metric)` também existe como middleware Express (confere o limite e registra 1 uso nas respostas 2xx) para composições fora de `router.private`.

## Erros

| Código | Status | Causa |
|---|---:|---|
| `USAGE_METRIC_INVALID` | 422 | Código fora do padrão |
| `USAGE_QUANTITY_INVALID` | 422 | Quantidade não inteira ou < 1 |
| `USAGE_LIMIT_REACHED` | 423 | Limite do ciclo atingido |

No runtime local nada é enviado (`{ recorded: false, reason: "local" }`).

Fonte: https://sdk.oonapps.com/docs/backend/metricas-de-uso