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 fra_test_ y solo se muestran una vez. No guardes la clave en el repositorio y revócala si queda expuesta.

Instala un SDK

Para Python, instala el paquete oficial fiscalrail:

python -m pip install fiscalrail

Para Ruby 3.3 o posterior, añade la gema a tu Gemfile y ejecuta bundle install:

gem "fiscalrail", "~> 0.4.0"

Expón la clave de Test al proceso de tu servidor:

export FISCALRAIL_API_KEY=fra_test_...

Lee la clave desde tu gestor de secretos y pásala explícitamente a FiscalRail en Python o a FiscalRail::Client en Ruby. Ambos clientes reutilizan conexiones HTTP y envían la clave como token bearer. Ninguno lee la clave del entorno por su cuenta.

La petición subyacente usa:

Authorization: Bearer fra_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 una respuesta 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