Overview

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.

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 so retries can never issue a duplicate, and dry-run payloads with POST /v1/invoices/validate. See Create an invoice.

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.

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.

Errors

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

{
  "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 for the full envelope contract and the catalog of codes.

Introduction

Invoices

Number Series

Tax IDs

Customer portal

Base URL

Authentication

Data conventions

Creating invoices

Downloading invoices

Errors

​Base URL

​Authentication

​Data conventions

​Creating invoices

​Pagination

​Downloading invoices

​Errors

Base URL

Authentication

Data conventions

Creating invoices

Pagination

Downloading invoices

Errors