# Primeros pasos

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

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

Cada petición la envía como token bearer:

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

### 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"}]
    }]
  }'
```

Una petición correcta devuelve `201 Created` con la factura completa. FiscalRail aplica la serie predeterminada, asigna el siguiente número, resuelve los impuestos y guarda el documento inmutable de forma atómica.

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

Copia el `id` devuelto; la siguiente petición lo usa como `INVOICE_ID`.

## 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.

### cURL

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

La respuesta JSON 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

- Crea un [cliente](/en/docs/api/customers) cuando necesites una factura ordinaria con datos del destinatario.
- Aprende a [corregir una factura emitida](/es/docs/correcting-invoices) sin editar su historial inmutable.
- [Recibe eventos con webhooks](/es/docs/webhooks) en lugar de consultar repetidamente los resultados asíncronos.
- Entiende el [régimen fiscal de España](/es/docs/tax-regimes/spain) y configura [VERI*FACTU](/es/docs/tax-regimes/spain/verifactu) antes de pasar a Live.
- Consulta la [referencia de la API de facturas](/en/docs/api/invoices) cuando necesites todos los campos disponibles.