Documentación
Explorar documentación
Idioma
EN ES

Primeros pasos

Pasa de una cuenta nueva de FiscalRail a una factura de prueba terminada y su PDF.
Ver como Markdown

Esta guía recorre el flujo completo más corto de FiscalRail: crear una clave de Test, emitir una factura y generar el PDF terminado. Las operaciones de Test son gratuitas, están aisladas de Live y quedan visiblemente marcadas, por lo que aquí no crearás ningún documento fiscal real.

Crea tu cuenta

Abre el panel e inicia sesión con tu correo electrónico. La configuración inicial solicita los datos de tu negocio y el régimen fiscal. Elígelo con cuidado: determina las reglas de facturación de las cuentas Live y Test y no se puede cambiar después. Elige España para seguir el ejemplo tal como está escrito.

FiscalRail abre la cuenta de Test al terminar la configuración. Permanece en ella durante esta guía.

Crea una clave de API de Test

Abre Developers → API keys, crea una clave y copia el secreto. Los secretos de Test empiezan por ak_test_ y solo se muestran una vez. No guardes la clave en el repositorio y revócala si queda expuesta.

Instala el SDK de Python

Instala el paquete oficial fiscalrail y expón la clave de Test al proceso de tu servidor:

python -m pip install fiscalrail
export FISCALRAIL_API_KEY=ak_test_...

Lee la clave desde tu gestor de secretos y pásala explícitamente a FiscalRail. El cliente mantiene una sesión HTTP reutilizable y envía la clave como token bearer. El SDK nunca lee variables de entorno por su cuenta.

La petición subyacente usa:

Authorization: Bearer ak_test_...

Emite una factura

Una factura necesita al menos una línea. Este ejemplo omite el cliente y genera una factura simplificada de importe reducido. Las cuentas españolas resuelven el tratamiento del IVA a partir de tax y rule; tu integración envía los hechos comerciales en lugar de calcular el impuesto.

import os
from decimal import Decimal

from fiscalrail import FiscalRail
from fiscalrail.tax_regimes.es import vat

client = FiscalRail(os.environ["FISCALRAIL_API_KEY"])
invoice = client.invoices.issue(
    idempotency_key="2f294ef2-9a60-4c7e-a573-5e18fa8348e2",
    lines=[
        {
            "description": "Consulting",
            "quantity": 2,
            "unit_price": Decimal("75.00"),
            "taxes": [vat.general],
        }
    ],
)

Una llamada correcta devuelve un dataclass inmutable Invoice. FiscalRail aplica la serie predeterminada, asigna el siguiente número, resuelve los impuestos y guarda el documento inmutable de forma atómica.

{
  "id": "inv_...",
  "object": "invoice",
  "live": false,
  "account": "acct_...",
  "kind": "invoice",
  "code": "TEST-INV-00001",
  "series": "inv_ser_...",
  "issue_date": "2026-08-11",
  "supply_period": null,
  "preceding_invoice": null,
  "currency": "EUR",
  "supplier": {
    "source": {
      "type": "account",
      "id": "acct_..."
    },
    "name": "Example supplier",
    "tax_id": {
      "country": "ES",
      "type": "es_nif",
      "value": "B02850360"
    },
    "email": "billing@example.com",
    "phone": null,
    "address": {
      "line_1": "Example street 1",
      "line_2": null,
      "city": "Madrid",
      "postal_code": "28001",
      "state": null,
      "country": "ES"
    }
  },
  "customer": null,
  "lines": [
    {
      "index": 1,
      "description": "Consulting",
      "quantity": "2.0",
      "unit_price": "75.00",
      "subtotal": "150.00",
      "taxes": [
        {
          "tax": "vat",
          "rule": "general",
          "effect": "added",
          "treatment": "taxable",
          "description": "IVA 21%",
          "rate": "21%",
          "taxable_base": "150.00"
        }
      ]
    }
  ],
  "tax_totals": [
    {
      "tax": "vat",
      "rule": "general",
      "effect": "added",
      "treatment": "taxable",
      "description": "IVA 21%",
      "rate": "21%",
      "taxable_base": "150.00",
      "amount": "31.50"
    }
  ],
  "totals": {
    "subtotal": "150.00",
    "tax": "31.50",
    "total_with_tax": "181.50",
    "withheld_tax": "0.00",
    "payable": "181.50"
  },
  "created_at": "2026-08-11T09:30:00Z",
  "tax_regime": {
    "key": "es",
    "es": {
      "qr": {
        "content": "https://api.fiscalrail.com/tax-regimes/es/mock-verifications/...",
        "image_url": "https://api.fiscalrail.com/tax-regimes/es/invoice-qrs/..."
      },
      "verifactu": {
        "registrations": [
          {
            "id": "es_inv_reg_...",
            "object": "verifactu_registration",
            "live": false,
            "invoice": "inv_...",
            "kind": "alta",
            "status": "pending",
            "submitted_at": null,
            "csv": null,
            "error": null
          }
        ]
      }
    }
  },
  "amendments": []
}

Copia invoice.id; el ejemplo siguiente lo lee desde INVOICE_ID para que también se pueda ejecutar por separado.

Genera el PDF

La primera petición genera el PDF de forma síncrona. Accept-Language selecciona español o inglés y queda fijado para el PDF de esa factura.

import os

from fiscalrail import FiscalRail

client = FiscalRail(os.environ["FISCALRAIL_API_KEY"])
invoice_pdf = client.invoice_pdfs.render(os.environ["INVOICE_ID"], locale="es")
print(invoice_pdf.url)

El InvoicePdf devuelto incluye una url para el cliente que funciona sin clave de API y caduca a los 30 días. Ábrela para ver la factura de Test terminada, numerada y visiblemente marcada. Trata la URL como un secreto mientras siga activa.

Ya has completado el flujo principal de FiscalRail. Repetir la petición devuelve el documento en caché sin volver a generarlo ni cobrarlo.

Siguientes pasos