# Getting started

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

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](https://dashboard.fiscalrail.com/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:

```http
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

```bash
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.

```json
{
  "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

```bash
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

- Create a [customer](/en/docs/api/customers) when you need an ordinary invoice with recipient details.
- Learn how to [correct an issued invoice](/en/docs/correcting-invoices) without editing its immutable history.
- [Receive events with webhooks](/en/docs/webhooks) instead of polling for asynchronous outcomes.
- Understand the [Spain tax regime](/en/docs/tax-regimes/spain) and configure [VERI*FACTU](/en/docs/tax-regimes/spain/verifactu) before going Live.
- Use the [Invoice API reference](/en/docs/api/invoices) when you need every available field.