Skip to content
Guia da Central de Ajuda · Faturação e pagamentos
3 min de leituraVerificado 2026-11-16

Faturas e histórico de faturação

Consulte registos mensais/anuais, descarregue faturas PDF oficiais e antecipe itens da próxima renovação.

Neste guia

Visão geral

Os administradores de faturação autorizados podem consultar o histórico completo de faturação (GET /api/v1/billing/history), o detalhe das linhas de fatura (invoice line item type) e os estados de liquidação em Definições -> Faturação -> Faturas (/settings/billing/invoices). Suportado por Billing API (/api/v1/billing/invoices* e GET /api/v1/billing/tax-profile/datev-export), o Passinstance gera faturas fiscais PDF conformes com o IVA para cada renovação de subscrição, ajuste pro-rata intercalar e extra modular, permitindo liquidar de imediato ou cancelar faturas em aberto.

Ciclo de Vida de Emissão e Liquidação de Faturas

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
CICLO DE VIDA DA FATURA, STREAMING PDF E NOVA TENTATIVA
ETAPA 01 CICLO DE FATURAÇÃO / EVENTO PRO-RATA
Renovação de Subscrição, Upgrade de Plano (change) ou Subscrição Add-On
Fixa Entidade Legal, Morada e vatNumber/taxId (PUT/billing/settings)
ETAPA 02 MÁQUINA DE ESTADOS DA FATURA (Billing API)
+[ PAID ] (Cobrança automática concluída) [ PENDING / OPEN ]-+[ OVERDUE ]POST/invoices/:id/pay (Aguarda liquidação) | (Usa Método Padrão)
+[ VOID / CANCELLED ] (Fatura Anulada/Cancelada)
ETAPA 03 OBTENÇÃO DE FATURAS E STREAMING PDF
GET/api/v1/billing/invoices (Histórico Paginado ?page=&limit=)
GET/api/v1/billing/invoices/:id (Linhas, Créditos e Desdobramento de IVA)
GET/api/v1/billing/invoices/:id/download (Stream Binário application/pdf)

Importante: Os metadados fiscais da empresa (companyName, address, taxId e vatNumber via PUT /api/v1/billing/settings e PUT /api/v1/billing/tax-profile) são registados de forma fixa em cada fatura no momento da finalização. Mantenha os dados fiscais atualizados em Definições da Empresa antes da data de renovação.

Estado da Fatura (invoice status), Ciclo de Vida e Tipos de Linha

As faturas registam tanto o ciclo administrativo (invoice lifecycle state: DRAFT | OPEN | CLOSED | VOID) como o estado de pagamento (invoice status), enquanto cada linha utiliza invoice line item type (BASE_SUBSCRIPTION | ADD_ON | ACTIVE_PASSES_INCLUDED | ACTIVE_PASSES_OVERAGE | USAGE_EMAIL | USAGE_SMS | CREDIT_NOTE | ADJUSTMENT | TAX):

invoice statusSignificado ContabilísticoAção Recomendada do Operador
PAIDO pagamento foi cobrado com sucesso no método de pagamento predefinido do espaço.Transfira o recibo fiscal oficial em PDF via /download para a contabilidade.
PENDING / PARTIALLY_PAIDA fatura foi finalizada (OPEN) e aguarda cobrança ou liquidação do saldo restante.Confirme o método predefinido em Métodos de Pagamento e execute POST /api/v1/billing/invoices/:id/pay.
OVERDUEA cobrança automática falhou além da janela inicial (ex.: cartão expirado ou necessidade de 3DS).Atualize o cartão/mandato em /settings/billing/payment-method e tente novamente POST /api/v1/billing/invoices/:id/pay.
CANCELLED / VOIDA fatura foi cancelada (POST /api/v1/billing/invoices/:id/cancel) ou anulada antes da cobrança.Sem montante em dívida; mantenha o registo para integridade da auditoria.

Referência da API de Gestão de Faturas (Billing API)

EndpointVerbo HTTPDescrição
/api/v1/billing/invoicesGETLista faturas paginadas do espaço de trabalho (?page=1&limit=20).
/api/v1/billing/invoices/:idGETObtém o detalhe da fatura incluindo linhas (invoice line item type), taxas de imposto, notas de IVA e tentativas de pagamento.
/api/v1/billing/invoices/:id/downloadGETTransmite a fatura fiscal discriminada oficial como anexo application/pdf.
/api/v1/billing/invoices/:id/payPOSTLiquida ou volta a tentar cobrar uma fatura pendente/vencida com o método de pagamento ativo do espaço.
/api/v1/billing/invoices/:id/cancelPOSTCancela uma fatura aberta por pagar.
/api/v1/billing/historyGETDevolve o histórico cronológico de faturação e eventos de pagamento do espaço.

1. Inspecionar Linhas Detalhadas e IVA da Fatura (GET /api/v1/billing/invoices/:id)

HTTP
GET /api/v1/billing/invoices/inv_01933220-5a11-7e00-9c44-887766554433 HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>

Payload de Resposta (200 OK)

JSON
{
  "id": "inv_01933220-5a11-7e00-9c44-887766554433",
  "invoiceNumber": "PI-2026-004891",
  "status": "PAID",
  "lifecycle": "CLOSED",
  "currency": "EUR",
  "issuedAt": "2026-11-16T09:00:00.000Z",
  "paidAt": "2026-11-16T09:00:04.000Z",
  "customerDetails": {
    "companyName": "Phenix Hospitality GmbH",
    "vatNumber": "DE301928374",
    "address": "Friedrichstrasse 114A, 10117 Berlin, DE"
  },
  "lineItems": [
    {
      "kind": "BASE_SUBSCRIPTION",
      "description": "Growth Plan (2,000 Active Passes) — Monthly",
      "quantity": 1,
      "unitAmountCents": 12000,
      "amountCents": 12000
    },
    {
      "kind": "ADD_ON",
      "description": "Custom Vanity Domain & Branded Email Add-On",
      "quantity": 1,
      "unitAmountCents": 2900,
      "amountCents": 2900
    }
  ],
  "subtotalCents": 14900,
  "taxRatePercent": 19.0,
  "taxCents": 2831,
  "totalCents": 17731
}

2. Transferir Faturas Fiscais PDF (GET /api/v1/billing/invoices/:id/download)

HTTP
GET /api/v1/billing/invoices/inv_01933220-5a11-7e00-9c44-887766554433/download HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
HTTP
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="invoice-PI-2026-004891.pdf"

3. Voltar a Tentar Pagamento de Fatura em Aberto/Vencida (POST /api/v1/billing/invoices/:id/pay)

Atualize o método de pagamento predefinido em Definições -> Faturação -> Método de Pagamento (/settings/billing/payment-method) e acione a cobrança (sem corpo JSON obrigatório):

HTTP
POST /api/v1/billing/invoices/inv_01933299-1b22-7c00-8d11-223344556677/pay HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
JSON
{
  "invoiceId": "inv_01933299-1b22-7c00-8d11-223344556677",
  "status": "PAID",
  "paidAt": "2026-11-16T10:36:45.000Z",
  "amountPaidCents": 17731
}

Documentação Relacionada

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.