> ## Documentation Index
> Fetch the complete documentation index at: https://www.finseed.es/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> How the Finseed API works: base URL, data conventions, pagination, and errors at a glance.

The Finseed API is a REST API for issuing and reading Verifactu invoices from your own systems. If you can send an HTTPS request, you can use it.

## Base URL

All requests go to:

```
https://api.finseed.es
```

Every endpoint is versioned under a path prefix, starting with `/v1`.

## Authentication

Every request must include an API key, sent as a bearer token in the `Authorization` header. Keys are scoped to one environment, so a test key only ever sees test data and a live key only ever sees live data. See [Authentication](/docs/api-reference/authentication).

## Data conventions

These conventions hold across every endpoint, so you can rely on them without checking each field:

* **JSON only.** Requests and responses use `application/json`.
* **snake\_case fields.** For example `external_customer_id`, `created_at`.
* **Amounts are integer minor units.** A value of `10050` in a EUR invoice means 100.50 EUR. There are no floating-point amounts, so you never lose precision in transit.
* **Currencies are lowercase ISO 4217 codes.** For example `eur`.
* **Timestamps are RFC 3339 in UTC.** For example `2026-06-01T09:30:00Z`.
* **Identifiers are opaque and prefixed.** For example `inv_clx123abc456`. Treat the whole string as a token: do not parse or build it yourself.

## Creating invoices

`POST /v1/invoices` issues an invoice immediately: number assigned, Verifactu record chained, PDF on its way. Registration at the tax agency progresses asynchronously; poll the invoice until `verifactu.status` leaves `pending`. Always send an [Idempotency-Key](/docs/api-reference/idempotency) so retries can never issue a duplicate, and dry-run payloads with `POST /v1/invoices/validate`. See [Create an invoice](/docs/api-reference/creating-invoices).

## Pagination

List endpoints return a single page and a cursor to fetch the next one. Follow the `next_url` in each response until it is `null`. See [Pagination](/docs/api-reference/pagination).

## Downloading invoices

Every invoice has a PDF. Fetch a short-lived link to it with `GET /v1/invoices/{id}/download`, then follow the link to download the file. See [Download an invoice PDF](/docs/api-reference/download-invoice).

## Errors

Any response that is not a `2xx` uses one small JSON envelope with a stable, machine-readable `code` you can branch on:

```json theme={null}
{
  "code": "invalid_request",
  "detail": "The request is not valid. A parameter is missing, malformed, or out of range. See the errors array for the fields that failed.",
  "errors": [
    { "field": "limit", "code": "too_big", "message": "Must be 100 or less." }
  ]
}
```

See [Errors](/docs/api-reference/errors) for the full envelope contract and the catalog of codes.