Descripción General
Los administradores de facturación autorizados pueden inspeccionar el historial completo de registros de facturación (GET /api/v1/billing/history), el desglose de partidas (invoice line item type) y los estados de liquidación de pagos en Configuración -> Facturación -> Facturas (/settings/billing/invoices). Impulsado por Billing API (/api/v1/billing/invoices* y GET /api/v1/billing/tax-profile/datev-export), Passinstance genera facturas fiscales en PDF conformes con el IVA para cada renovación de suscripción, ajuste de prorrateo a mitad de ciclo y cargo por complemento modular, y permite la ejecución inmediata del pago o la cancelación de facturas abiertas.
Ciclo de Vida de Generación y Liquidación de Facturas
Importante: Los metadatos de facturación corporativa (
companyName,address,taxIdyvatNumbermediantePUT /api/v1/billing/settingsyPUT /api/v1/billing/tax-profile) se capturan en cada factura en el momento de su finalización. Mantenga actualizados sus datos fiscales en Configuración de la Empresa antes de su fecha de renovación.
Estado de la Factura (invoice status), Ciclo de Vida y Tipos de Partida
Las facturas registran tanto un ciclo de vida administrativo (invoice lifecycle state: DRAFT | OPEN | CLOSED | VOID) como un estado de liquidación de pago (invoice status), mientras que las partidas detalladas utilizan 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 Contable | Acción Recomendada para el Operador |
|---|---|---|
PAID | El pago se capturó y liquidó correctamente mediante el método de pago predeterminado del espacio de trabajo. | Descargue el recibo fiscal oficial en PDF mediante /download para su libro mayor contable. |
PENDING / PARTIALLY_PAID | La factura ha sido finalizada (OPEN) y está pendiente de captura de pago o liquidación de saldo parcial. | Verifique su instrumento de pago predeterminado en Métodos de Pago y ejecute POST /api/v1/billing/invoices/:id/pay. |
OVERDUE | El pago automatizado falló una vez superada la ventana de cobro inicial (por ejemplo, tarjeta vencida o desafío 3DS requerido). | Actualice la tarjeta o el mandato en /settings/billing/payment-method y reintente POST /api/v1/billing/invoices/:id/pay. |
CANCELLED / VOID | La factura fue cancelada (POST /api/v1/billing/invoices/:id/cancel) o anulada antes del cobro. | No se adeuda ningún pago; conserve el registro para fines de auditoría si es necesario. |
Referencia de la API de Gestión de Facturas (Billing API)
| Endpoint | Verbo HTTP | Descripción |
|---|---|---|
/api/v1/billing/invoices | GET | Lista las facturas paginadas del espacio de trabajo (?page=1&limit=20). |
/api/v1/billing/invoices/:id | GET | Recupera el desglose detallado de la factura, incluidas las partidas (invoice line item type), tasas impositivas, notas de IVA e intentos de pago. |
/api/v1/billing/invoices/:id/download | GET | Transmite la factura fiscal detallada oficial como un archivo adjunto application/pdf. |
/api/v1/billing/invoices/:id/pay | POST | Liquida o reintenta el cobro de una factura pendiente o vencida utilizando el método de pago activo del espacio de trabajo. |
/api/v1/billing/invoices/:id/cancel | POST | Cancela una factura abierta impaga. |
/api/v1/billing/history | GET | Devuelve el historial cronológico de eventos de facturación y pago del espacio de trabajo. |
1. Inspección Detallada de Partidas de Factura e IVA (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>
Carga Útil de Respuesta (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. Transmisión de Facturas Fiscales en 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. Reintento de Pago en una Factura Abierta o Vencida (POST /api/v1/billing/invoices/:id/pay)
Actualice su instrumento de pago predeterminado en Configuración -> Facturación -> Método de Pago (/settings/billing/payment-method) y, a continuación, active el cobro (no requiere cuerpo de solicitud):
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
}
Documentación Relacionada
-
Configure los metadatos fiscales corporativos y los números de IVA en Configuración de la Empresa.
-
Añada o actualice tarjetas de crédito, PayPal o Mobile Money en Métodos de Pago.
-
Exporte datos del espacio de trabajo y registros de cumplimiento en Exportación de Datos e Informes.
