Documentation
Browse documentation
Language
EN ES

Getting started

Go from a new FiscalRail account to a finished test invoice and PDF.
View as Markdown

This guide takes you through FiscalRail's shortest complete workflow: create a Test key, issue an invoice and render the finished PDF. Test operations are free, isolated from Live and visibly marked, so nothing here creates a real fiscal document.

Create your account

Open the dashboard and sign in with your email address. The first-time setup asks for your business details and tax regime. Choose carefully: the tax regime defines the invoicing rules for both the Live account and its Test account and cannot be changed later. Choose Spain to follow the example below as written.

FiscalRail opens the Test account after setup. Stay there for this guide.

Create a Test API key

Open Developers → API keys, create a key and copy its secret. Test secrets begin with ak_test_ and are shown only once. Keep the key out of source control and revoke it if it is exposed.

Install the Python SDK

Install the official fiscalrail package and expose the Test key to your server process:

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

Read the key from your secret manager and pass it to FiscalRail explicitly. The client owns a pooled HTTP session and sends the key as a bearer token. The SDK never reads process environment variables on its own.

The underlying request uses:

Authorization: Bearer ak_test_...

Issue an invoice

An invoice needs at least one line. This example omits the customer, producing a small simplified invoice. Spanish accounts resolve the VAT treatment from tax and rule; your integration sends the commercial facts rather than calculating the tax amount itself.

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],
        }
    ],
)

A successful call returns an immutable Invoice dataclass. FiscalRail applies the account's default series, assigns the next number, resolves its taxes and stores the immutable document atomically.

{
  "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": []
}

Copy invoice.id; the next example reads it from INVOICE_ID so it can also be run independently.

Render the PDF

The first render creates the PDF synchronously. Accept-Language chooses English or Spanish and remains pinned for that invoice PDF.

import os

from fiscalrail import FiscalRail

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

The returned InvoicePdf includes a customer-facing url that works without an API key and expires after 30 days. Open it to see the finished, numbered and visibly marked Test invoice. Treat the URL as a secret while it remains active.

You have now completed the core FiscalRail flow. Repeating the PDF request returns the cached document without rendering or charging again.

Where to go next