Consumo de Prosas

Lista os movimentos de consumo de Prosas. Filtros: ?start_date=&end_date=&category=&source=&contact_id=&page=1&limit=50&currency=brl (e, com `include=meta_lines`, &delivery_status=&meta_page=&meta_limit=). Sem datas, a janela é dos últimos 30 dias. Na página 1 o envelope traz `meta_costs`, o custo Meta estimado do período na moeda de `currency` (`brl` ou `usd`, padrão `brl`). Com `?include=meta_lines` o envelope ganha `meta_lines`: cada envio com custo Meta registrado (template ou resposta de conversa), em grão de linha, com paginação própria (`meta_page`, padrão 1; `meta_limit`, padrão 50, teto 100) — independente de `page`/`limit` — e ordem da cobrança mais recente para a mais antiga (linha `void`, sem data de cobrança, fica no fim). Com `include=meta_lines`, `category` aceita, além do vocabulário de Prosas, as categorias Meta (`marketing`, `utility`, `authentication`, `authentication-international`, `service`, `unknown`); `prospection` e `human` são só de Prosas e devolvem `meta_lines` vazio. Sem `include`, `category` aceita só o vocabulário de Prosas.

• `prosas` e `cost_brl` são ASSINADOS: uma linha negativa é o estorno de uma cobrança anterior. Some os valores como vêm — filtrar o negativo superestima o custo.
• Em `meta_costs`, `messages` (em `totals`, `by_category` e `by_day`) e `costs.sent` contam LINHAS DE CUSTO do período, inclusive as `not_applicable` e `void` — não são o número de envios.
• `coverage` diz quais cobranças estão desligadas na empresa. Com `campaign_billing_enabled: false` não existe linha de campanha; com `messages_billing_enabled: false` não existe linha nenhuma. Leia esse bloco antes de concluir que um período não teve consumo.
• Sem `start_date`, a janela recua 30 dias a partir de `end_date` (ou de agora). A tabela inteira nunca é varrida numa só chamada.
• `limit` vai até 100 e a ordenação é por data decrescente. O rate limit é de 60 requisições por minuto por chave: use `pagination.next_page` para retomar a paginação de onde parou depois de um 429.
• `contact` vem `null` quando o débito não tem lead — prospecção, enriquecimento, contato excluído, ou linha anterior à atribuição por lead.
• `meta_costs` é do PERÍODO, não da página: vem só na página 1 (sem `page` ou `page=1`); nas demais páginas vem `null`, para não ser contado de novo a cada página.
• Período de `meta_costs`: data sem hora (`AAAA-MM-DD`) é lida no fuso da empresa — `start_date` desde 00:00 local e `end_date` até o fim do dia local; data com hora (ISO 8601 completo) é usada como veio, com `end_date` exclusivo. `meta_costs.period` traz o intervalo efetivo em UTC. As linhas de Prosas mantêm a leitura atual das datas, então os dois recortes podem diferir nas bordas do dia.
• `meta_costs` é custo Meta ESTIMADO pela tarifa base da Meta (em R$, US$ × PTAX de venda do dia), de natureza diferente das Prosas: nunca some os dois. Cada linha de custo entra pela data de cobrança — recorte diferente do relatório de campanhas, que conta a mensagem pelo horário de envio.
• `costs.amount` fica `null` enquanto houver linha `pending` na moeda (a PTAX do dia sai por volta das 13h de Brasília, em dias úteis); `costs.known_amount` é sempre o parcial já conhecido.
• Se o resumo de custo Meta não puder ser lido, a resposta continua 200 com `meta_costs: null` e `degraded: ["meta_costs"]`; as linhas de Prosas e `coverage` não são afetadas.
• `meta_lines` só aparece com `?include=meta_lines`. É dinheiro de natureza DIFERENTE de `data`: `meta_lines[].cost` é tarifa Meta estimada, `data[].cost_brl` é crédito interno de Prosa — nunca some os dois. Sem `?include=meta_lines` a resposta é idêntica à de hoje.
• `meta_lines` tem paginação PRÓPRIA (`meta_page`, `meta_limit`, teto 100), independente de `page`/`limit` das linhas de Prosa, e do mesmo período de `meta_costs`.
• `meta_lines[].status` é o status na moeda pedida — em R$ a linha pode seguir `pending` até a PTAX do dia ser publicada, com o valor em US$ já resolvido. `meta_lines[].cost` fica `null` quando esse status não carrega valor monetário (pending, free, not_billed, void, not_applicable). `meta_lines[].contact` vem `null` em custo órfão (sem mensagem associada) — a linha ainda traz `template_name`.
• `category` em `meta_lines` aceita as categorias Meta (marketing, utility, authentication, authentication-international, service, unknown); `prospection` e `human` são só de Prosas e devolvem `meta_lines.data: []`.
• `meta_lines[].origin` é `campaign` (envio de campanha), `template` (template fora de campanha, como a régua — reconhecido pelo nome, pelo tipo da mensagem ou pela categoria marketing/utility/authentication) ou `conversation` (resposta de conversa, sem template — normalmente grátis na janela de 24 h).
• `meta_lines[].delivery_status` é a situação do envio: `sent` (enviado, sem confirmação de entrega), `delivered` (entregue), `read` (lido) ou `failed` (falhou — a Meta não cobra); `null` em custo órfão. Outro valor de status, raro, sai como está e não é filtrável. Para filtrar use `delivery_status=` com um ou mais valores separados por vírgula — "entregue" é `delivery_status=delivered,read`, porque lido também foi entregue. Sem `include=meta_lines` o parâmetro é ignorado.
• Se a leitura de `meta_lines` falhar, a resposta continua 200 com `meta_lines: null` e `degraded` ganha `"meta_lines"`; os demais blocos não são afetados.

{
  "success": true,
  "data": [
    {
      "id": "<uuid>",
      "date": "2026-09-02T14:33:10.221Z",
      "category": "marketing",
      "prosas": 40,
      "cost_brl": 0.4,
      "source": "campaign",
      "contact_id": "<uuid>",
      "contact": {
        "id": "<uuid>",
        "name": "João Silva",
        "identifier": "5548999990000"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 240,
    "total_pages": 5,
    "next_page": 2
  },
  "coverage": {
    "messages_billing_enabled": true,
    "campaign_billing_enabled": false,
    "note": "Envios de campanha não consomem Prosas nesta empresa: nenhuma linha com origem de campanha aparece neste relatório. As demais origens estão cobertas."
  },
  "meta_costs": {
    "currency": "BRL",
    "estimated": true,
    "timezone": "America/Sao_Paulo",
    "period": {
      "start": "2026-09-01T03:00:00.000Z",
      "end": "2026-09-16T03:00:00.000Z"
    },
    "totals": {
      "messages": 1200,
      "costs": {
        "amount": null,
        "known_amount": 312.48,
        "coverage": 0.9917,
        "sent": 1200,
        "resolved": 980,
        "free": 190,
        "not_billed": 0,
        "void": 3,
        "not_applicable": 17,
        "historical": 0,
        "pending": 10,
        "status": "partial",
        "basis": [
          "usd_rate_x_ptax_venda"
        ]
      }
    },
    "by_category": [
      {
        "category": "marketing",
        "pricing_window": null,
        "messages": 900,
        "costs": {
          "amount": null,
          "known_amount": 300.12,
          "coverage": 0.9889,
          "sent": 900,
          "resolved": 890,
          "free": 0,
          "not_billed": 0,
          "void": 0,
          "not_applicable": 0,
          "historical": 0,
          "pending": 10,
          "status": "partial",
          "basis": [
            "usd_rate_x_ptax_venda"
          ]
        }
      }
    ],
    "by_day": [
      {
        "date": "2026-09-01",
        "messages": 80,
        "costs": {
          "amount": 20.5,
          "known_amount": 20.5,
          "coverage": 1,
          "sent": 80,
          "resolved": 64,
          "free": 16,
          "not_billed": 0,
          "void": 0,
          "not_applicable": 0,
          "historical": 0,
          "pending": 0,
          "status": "complete",
          "basis": [
            "usd_rate_x_ptax_venda"
          ]
        }
      }
    ],
    "note": "Custo Meta estimado pela tarifa base da Meta (R$ = US$ × PTAX de venda do dia); não é recibo e não se soma às Prosas. `amount` fica nulo enquanto houver linha pendente de precificação — use `known_amount` para o parcial. O recorte é pela data de cobrança da linha de custo, diferente do relatório de campanhas, que usa o horário de envio da mensagem."
  },
  "meta_lines": {
    "data": [
      {
        "id": "<uuid>",
        "date": "2026-09-10T12:00:00.000Z",
        "category": "marketing",
        "pricing_window": null,
        "template_name": "promo_setembro",
        "origin": "campaign",
        "delivery_status": "read",
        "status": "resolved",
        "cost": 0.33,
        "currency": "BRL",
        "estimated": true,
        "contact_id": "<uuid>",
        "contact": {
          "id": "<uuid>",
          "name": "João Silva",
          "identifier": "5548999990000"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 8158,
      "total_pages": 164,
      "next_page": 2
    }
  }
}

curl -s -H "Authorization: Bearer <sua-key>" https://www.prosalab.com/api/v1/prosas/consumption