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.

Every request sends it as a bearer token:

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.

curl https://api.fiscalrail.com/v1/invoices \
  --request POST \
  --header "Authorization: Bearer ak_test_..." \
  --header "Idempotency-Key: 2f294ef2-9a60-4c7e-a573-5e18fa8348e2" \
  --header "Content-Type: application/json" \
  --data '{
    "lines": [{
      "description": "Consulting",
      "quantity": "2",
      "unit_price": "75.00",
      "taxes": [{"tax": "vat", "rule": "general"}]
    }]
  }'

A successful request returns 201 Created with the complete invoice. 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 the returned id; the next request uses it as INVOICE_ID.

Render the PDF

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

curl "https://api.fiscalrail.com/v1/invoices/$INVOICE_ID/pdf" \
  --request POST \
  --header "Authorization: Bearer ak_test_..." \
  --header "Accept-Language: en"

The JSON response 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