Lista as faturas do cliente

GET /portal/invoices

Escopo do token: invoices:read. Recurso: Faturas.

Visão do cliente (sem dados internos). As cobranças não são incluídas. external_id e end_customer_ref trazem as faturas dos contratos dos servidores com essa referência (a atual de cada servidor, removidos inclusive).

Exemplo de requisição

Os exemplos leem o token da variável de ambiente HALVER_API_TOKEN (um token sc_live_… criado em Desenvolvedores › Tokens de API). Nunca escreva o token no código.

curl "https://dash.halver.com.br/api/v1/portal/invoices?limit=50" \
  -H "Authorization: Bearer $HALVER_API_TOKEN"

package main

import (
  "fmt"
  "io"
  "net/http"
  "os"
  "time"
)

func main() {
  req, err := http.NewRequest(http.MethodGet, "https://dash.halver.com.br/api/v1/portal/invoices?limit=50", nil)
  if err != nil {
    panic(err)
  }
  req.Header.Set("Authorization", "Bearer "+os.Getenv("HALVER_API_TOKEN"))
  client := &http.Client{Timeout: 30 * time.Second}
  resp, err := client.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()
  out, err := io.ReadAll(resp.Body)
  if err != nil {
    panic(err)
  }
  fmt.Println(resp.Status)
  fmt.Println(string(out))
}

import os

import requests

resp = requests.get(
    "https://dash.halver.com.br/api/v1/portal/invoices?limit=50",
    headers={
        "Authorization": f"Bearer {os.environ['HALVER_API_TOKEN']}",
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Parâmetros

Parâmetros de consulta

status string
courtesy: fatura de conta interna (cortesia), com 100% de desconto “Uso interno”; no_charge: descontos cobriram o valor todo. Nas duas não há nada a pagar: nunca vão ao gateway, à NFS-e nem à inadimplência. Um de: open, paid, overdue, cancelled, refunded, courtesy, no_charge.
q string
Texto de busca (case-insensitive, contém).
contract_id string (uuid)
external_id string
Id do pedido no sistema do revendedor, o external_id do servidor. Formato: ^[A-Za-z0-9._:-]{1,128}$.
end_customer_ref string
Id do cliente final no sistema do revendedor, o end_customer_ref do servidor. Formato: ^[A-Za-z0-9._:-]{1,128}$.
due_from string (date)
Vencimento a partir de (YYYY-MM-DD, inclusive).
due_to string (date)
Vencimento até (YYYY-MM-DD, inclusive).
competence string
Mês de competência (YYYY-MM). Formato: ^\d{4}-(0[1-9]|1[0-2])$.
limit integer
Tamanho da página (padrão 50, máximo 200). De 1 a 200. Padrão: 50.
offset integer
Deslocamento da página. Mínimo 0. Padrão: 0.

Respostas

200

Página de faturas.

Campos da resposta

data array de object obrigatório
- amount_cents integer (int64) obrigatório
- amount_due_cents integer (int64) obrigatório
  Valor para pagar hoje (com multa e juros quando em atraso); 0 se a fatura não está em aberto.
- cancelled_at string (date-time) obrigatório pode ser nulo
- card_action qualquer pode ser nulo
  Pagamento com cartão esperando o cliente confirmar (3D Secure); nulo quando não há.
  - amount_cents integer (int64) obrigatório
  - charge_id string (uuid) obrigatório
- charges array de object
  Presente apenas no detalhe e quando há cobranças acionáveis (exclui canceladas e recusadas).
  - action_required boolean
    Pagamento com cartão esperando o cliente confirmar (3D Secure pedido pelo banco).
  - amount_cents integer (int64) obrigatório
  - automatic boolean
    Debitada por Pix Automático no vencimento (não há o que pagar manualmente).
  - bank_slip_url string obrigatório
    PDF do boleto. No link público, só enquanto a fatura e o boleto estão em aberto.
  - boleto_line string
    Linha digitável do boleto (vazia quando o provedor não a informa). No link público, só com o boleto em aberto.
  - confirmation_business_days integer
    Boleto pago é confirmado em até N dias úteis (1 na Stripe, 3 no Asaas); 0 nas demais formas.
  - due_date string (date) obrigatório
  - expires_at string (date-time) pode ser nulo
    Até quando o Pix ou o boleto pode ser pago; nulo quando continua pagável depois do vencimento.
  - id string (uuid) obrigatório
  - method string obrigatório
    Forma de pagamento. Um de: pix, boleto, credit_card.
  - paid_at string (date-time) obrigatório pode ser nulo
  - status string obrigatório
    Um de: pending, confirmed, received, overdue, refunding, refunded, chargeback, cancelled, failed.
- competence string (date) obrigatório
  Primeiro dia do mês de competência (YYYY-MM-01).
- contract_id string (uuid) obrigatório pode ser nulo
- description string obrigatório
- discount_cents integer (int64) obrigatório
- due_date string (date) obrigatório
- gateway string obrigatório
  Como a fatura é recebida. manual = Pix direto na conta da empresa, baixado por conciliação ou manualmente. stripe e asaas significam “cobrada num gateway” e aceitam Pix, boleto e cartão: cada cobrança nova sai pelo provedor configurado para a forma (PIX_PROVIDER, BOLETO_PROVIDER, CARD_PROVIDER; veja GET /public/card-config), a cobrança já emitida termina no provedor que a emitiu e um cartão salvo é sempre cobrado no provedor que o salvou. Contratos novos nascem com o provedor configurado (Stripe quando ela está configurada). Um de: asaas, stripe, nupay, manual.
- gross_amount_cents integer (int64) obrigatório
  Valor cheio (bruto); amount_cents é o que se paga.
- id string (uuid) obrigatório
- late_terms object obrigatório
  Multa e juros por atraso, combinados no contrato, em pontos-base (200 = 2,00%). A multa incide uma vez; os juros são ao mês, pro rata die. Zero = sem multa/juros. Pix e boleto do Asaas levam os termos; cobranças emitidas após o vencimento e o Pix direto já incluem o que acumulou.
  - fee_bps integer obrigatório
    Multa (% do valor), em pontos-base. De 0 a 1000.
  - interest_bps integer obrigatório
    Juros ao mês, em pontos-base. De 0 a 1000.
  - policy string
    Como os termos se aplicam, definido pelo sistema (ignorado nas requisições). standard: multa e juros desde o dia seguinte ao vencimento, o Asaas soma em Pix e boleto. cloud (contratos de servidores e IPs elásticos): sem multa nem juros até o 15º dia após o vencimento (dia útil); depois, juros desde o dia seguinte ao vencimento e multa só em Pix e boleto (nunca no cartão), calculados pela plataforma; o Asaas não soma nada. Um de: standard, cloud.
- lines array de object
  Linhas de cobrança e de desconto (só no detalhe).
  - amount_cents integer (int64) obrigatório
  - description string obrigatório
  - discount_source string
    contract - desconto da equipe; coupon - cupom; internal - uso interno (conta interna); minimum - saldo abaixo do mínimo de cobrança (R$ 5,00) dispensado. Um de: contract, coupon, internal, minimum.
  - kind string obrigatório
    Um de: charge, discount.
  - quantity integer obrigatório
- number string obrigatório
- paid_amount_cents integer (int64) obrigatório
- paid_at string (date-time) obrigatório pode ser nulo
- payment_issue string obrigatório
  Aviso ao cliente quando a última tentativa no cartão falhou; vazio caso contrário.
- payment_method string obrigatório
  Forma de pagamento. Um de: pix, boleto, credit_card.
- payment_method_id string (uuid) obrigatório pode ser nulo
- payment_url string
  Link público de pagamento, para compartilhar com quem vai pagar (só no detalhe).
- period_end string (date) obrigatório pode ser nulo
- period_start string (date) obrigatório pode ser nulo
- refunded_amount_cents integer (int64) obrigatório
  Devolvido ao cliente até agora (estorno parcial ou total).
- refunded_at string (date-time) obrigatório pode ser nulo
- service_invoice object
  Nota fiscal da fatura como o cliente a vê.
  - cancelled boolean obrigatório
  - issued_at string (date-time) obrigatório pode ser nulo
  - number string obrigatório
  - pdf_url string obrigatório
  - xml_url string obrigatório
- status string obrigatório
  courtesy: fatura de conta interna (cortesia), com 100% de desconto “Uso interno”; no_charge: descontos cobriram o valor todo. Nas duas não há nada a pagar: nunca vão ao gateway, à NFS-e nem à inadimplência. Um de: open, paid, overdue, cancelled, refunded, courtesy, no_charge.
- subscription_id string (uuid) pode ser nulo
  Recorrência que gerou a fatura (nula em faturas avulsas).
meta object obrigatório
- limit integer obrigatório
- offset integer obrigatório
- total integer (int64) obrigatório

{
  "data": [
    {
      "amount_cents": 89900,
      "amount_due_cents": 89900,
      "cancelled_at": null,
      "card_action": {
        "amount_cents": 89900,
        "charge_id": "f4910b35-92e2-4ae6-ab35-ab53c9c4a131"
      },
      "charges": [
        {
          "action_required": false,
          "amount_cents": 89900,
          "automatic": false,
          "bank_slip_url": "",
          "boleto_line": "",
          "confirmation_business_days": 0,
          "due_date": "2026-10-20",
          "expires_at": null,
          "id": "f4910b35-92e2-4ae6-ab35-ab53c9c4a131",
          "method": "pix",
          "paid_at": null,
          "status": "pending"
        }
      ],
      "competence": "2026-10-20",
      "contract_id": "751e7c9a-fae2-4027-9be3-5728dfce8982",
      "description": "Servidor de produção",
      "discount_cents": 89900,
      "due_date": "2026-10-20",
      "gateway": "asaas",
      "gross_amount_cents": 89900,
      "id": "38eb1f33-5f76-44d9-a2dd-bd2fbcc16b7e",
      "late_terms": {
        "fee_bps": 0,
        "interest_bps": 0,
        "policy": "standard"
      },
      "lines": [
        {
          "amount_cents": 89900,
          "description": "Servidor de produção",
          "discount_source": "contract",
          "kind": "charge",
          "quantity": 1
        }
      ],
      "number": "FAT-0000123",
      "paid_amount_cents": 89900,
      "paid_at": null,
      "payment_issue": "",
      "payment_method": "pix",
      "payment_method_id": "b3588322-3d69-442f-8bfb-a261636228e6",
      "payment_url": "",
      "period_end": null,
      "period_start": null,
      "refunded_amount_cents": 89900,
      "refunded_at": null,
      "service_invoice": {
        "cancelled": false,
        "issued_at": null,
        "number": "FAT-0000123",
        "pdf_url": "",
        "xml_url": ""
      },
      "status": "open",
      "subscription_id": "5aa44abf-128c-4582-924c-c5d63f42c78e"
    }
  ],
  "meta": {
    "limit": 50,
    "offset": 0,
    "total": 1
  }
}

Erros

Todo erro vem como application/problem+json (RFC 9457), com um code estável, a mensagem em português em detail, o motivo de cada campo em errors (nos erros de validação) e o request_id, que você informa ao suporte. Veja a lista completa de códigos.

Status	Quando	Códigos
400	Requisição inválida (JSON malformado, campo desconhecido, parâmetro inválido ou falha de validação).	`validation_failed`
401	Não autenticado (token ausente, inválido ou expirado; credenciais inválidas).	`auth.unauthorized`
403	Autenticado, mas sem permissão para a área ou a operação.	`api_token.insufficient_scope`

{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "detail": "o token não tem o escopo invoices:read; crie um token com esse escopo em Desenvolvedores › Tokens de API",
  "code": "api_token.insufficient_scope",
  "request_id": "6f1c0b2a9e4d7c3b5a8f0e1d"
}