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 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:

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

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