---
title: "Fatura de um cartão em um ciclo, detalhada por categoria"
method: GET
path: "/api/v1/credit-card-bills/invoice"
tags: ["Cartão de crédito"]
---

# Fatura de um cartão em um ciclo, detalhada por categoria

`GET /api/v1/credit-card-bills/invoice`

## Request

- Base URL: `https://snabber.com.br`
- URL: `https://snabber.com.br/api/v1/credit-card-bills/invoice`
- Auth: HTTP bearer

Retorna a fatura de um cartão para um ciclo (identificado pelo mês de vencimento, `cycle_month`), quebrada por categoria — por padrão pela categoria principal, com as subcategorias detalhadas em `subcategories` (já incluídas no `total` da principal); `group_by=category` devolve uma linha por categoria/subcategoria, sem hierarquia. Quando existe a fatura real do Open Finance, `source` é `pluggy_bill` e `total` é o valor que o emissor cobrou (o mesmo "Total da fatura" que aparece no app), com as transações realmente atribuídas àquela fatura pelo banco; sem fatura real (cartão manual, ciclo fora da janela do banco), `source` é `estimated_payment_date` e `total` é a estimativa local somando as transações cuja data de pagamento cai no mês. `total` inclui categorias que são cobrança real mas não contam como gasto pessoal (`ignorable: true`, ex. "Ignorado" e "Pagamento de Cartão de Crédito") — para comparar com gasto pessoal efetivo use `effective_total`, nunca `total` sozinho.

## Query parameters

- `workspace_id` integer
- `account_id` integer
- `account` string
- `cycle_month` string, required
- `group_by` 'category_parent' | 'category'

## Response `200`

Fatura do ciclo

- CreditCardInvoice
  - `account` string
  - `cycle` object
    - `month` string
    - `closing_day` integer, nullable: Dia do mês em que o ciclo fecha, configurado na conta
    - `due_day` integer, nullable: Dia do mês do vencimento, configurado na conta
  - `source` 'pluggy_bill' | 'estimated_payment_date': pluggy_bill = total real do emissor; estimated_payment_date = estimativa local por data de pagamento
  - `bill` CreditCardBill: Fatura real reportada pelo emissor do cartão via Open Finance.
    - `id` string: Identificador da fatura na instituição. Casa com `bill_id` das transações em /v1/transactions — é o vínculo transação↔fatura mais confiável. Opaco: não presuma formato
    - `account_id` integer
    - `account` string
    - `cycle_month` string: Mês de vencimento — a chave que identifica a fatura
    - `closing_month` string: Mês de FECHAMENTO do ciclo ("YYYY-MM"). Casa com `bill_forecast_date` das transações. Distinto de `cycle_month` (vencimento): quando o dia de vencimento é anterior ao de fechamento, o vencimento cai no mês seguinte
    - `due_date` string, date, nullable
    - `closing_date` string, date, nullable: null enquanto a fatura não fechou
    - `is_closed` boolean
    - `total_amount` number, nullable: Valor total cobrado pelo emissor
    - `currency_code` string, nullable
    - `minimum_payment_amount` number, nullable
    - `finance_charges_total` number, nullable: Soma dos encargos/juros reportados
    - `allows_installments` boolean, nullable
    - `payment_status` 'paid' | 'partial' | 'open' | 'due' | 'no_charge' | 'unknown' | 'null', nullable: paid = quitada, partial = paga parcialmente, open = ainda aberta, due = fechada e a vencer, no_charge = sem cobrança, unknown = sem evidência de pagamento
    - `paid_amount` number, nullable
    - `paid_at` string, date, nullable
    - `payment_mode` string, nullable
    - `payment_value_type` string, nullable
  - `categories` CreditCardInvoiceCategory[]
    - `category` string
    - `total` number: Soma das despesas da categoria nessa fatura, positiva
    - `count` integer
    - `ignorable` boolean: true para cobranças reais que não contam como gasto pessoal (Ignorado, Pagamento de Cartão de Crédito, Investimentos, Transferências Entre Contas Próprias, e as subcategorias delas)
    - `subcategories` object[]: Só com group_by=category_parent e quando alguma subcategoria teve gasto: o gasto de cada subcategoria, já incluído em `total`. `total` menos a soma delas é o que foi lançado direto na categoria principal.
      - `category` string
      - `total` number
      - `count` integer
  - `total` number: Total da fatura, incluindo as categorias ignorable
  - `ignored_total` number: Parte do total nas categorias ignorable
  - `effective_total` number: total - ignored_total: o gasto pessoal efetivo da fatura
  - `transaction_count` integer
  - `meta` object
    - `workspace_id` integer

## Other responses

- `400`: Parâmetro inválido ou conta não informada
- `401`: Chave de API ausente, inválida, revogada ou expirada
- `403`: Plano do usuário não tem acesso à API (downgrade para free)
- `404`: Conta não encontrada neste workspace
- `429`: Limite de requisições excedido

---

[API](https://skmtc.dev/snabber/apis/snabber-api.md) · [All operations](https://skmtc.dev/snabber/apis/snabber-api/llms.txt) · [OpenAPI document](https://skmtc.dev/snabber/apis/snabber-api/revisions/bf5841cbd8ce?raw)