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
Importante: Os metadados fiscais da empresa (
companyName,address,taxIdevatNumberviaPUT /api/v1/billing/settingsePUT /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 status | Significado Contabilístico | Ação Recomendada do Operador |
|---|---|---|
PAID | O 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_PAID | A 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. |
OVERDUE | A 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 / VOID | A 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)
| Endpoint | Verbo HTTP | Descrição |
|---|---|---|
/api/v1/billing/invoices | GET | Lista faturas paginadas do espaço de trabalho (?page=1&limit=20). |
/api/v1/billing/invoices/:id | GET | Obté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/download | GET | Transmite a fatura fiscal discriminada oficial como anexo application/pdf. |
/api/v1/billing/invoices/:id/pay | POST | Liquida ou volta a tentar cobrar uma fatura pendente/vencida com o método de pagamento ativo do espaço. |
/api/v1/billing/invoices/:id/cancel | POST | Cancela uma fatura aberta por pagar. |
/api/v1/billing/history | GET | Devolve 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)
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)
{
"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)
GET /api/v1/billing/invoices/inv_01933220-5a11-7e00-9c44-887766554433/download HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
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):
POST /api/v1/billing/invoices/inv_01933299-1b22-7c00-8d11-223344556677/pay HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
{
"invoiceId": "inv_01933299-1b22-7c00-8d11-223344556677",
"status": "PAID",
"paidAt": "2026-11-16T10:36:45.000Z",
"amountPaidCents": 17731
}
Documentação Relacionada
-
Configure metadados fiscais da empresa e número de IVA em Definições da Empresa.
-
Adicione ou atualize cartões de crédito, PayPal ou Mobile Money em Métodos de Pagamento.
-
Exporte dados do espaço e registos de conformidade em Exportação de Dados e Relatórios.
