Validate an invoice payload

curl --request POST \
  --url https://api.finseed.es/v1/invoices/validate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "line_items": [
    {
      "description": "Consulting services",
      "quantity": 2,
      "unit_amount": 4150,
      "tax": {
        "type": "vat",
        "rate": 21
      }
    }
  ],
  "type": "complete",
  "external_id": "order-84312",
  "number_series_id": "ns_clx456def789",
  "operation_date": "2025-06-15",
  "recargo_equivalencia": false,
  "footer_notes": "Pago a 30 días."
}
'

import requests

url = "https://api.finseed.es/v1/invoices/validate"

payload = {
    "line_items": [
        {
            "description": "Consulting services",
            "quantity": 2,
            "unit_amount": 4150,
            "tax": {
                "type": "vat",
                "rate": 21
            }
        }
    ],
    "type": "complete",
    "external_id": "order-84312",
    "number_series_id": "ns_clx456def789",
    "operation_date": "2025-06-15",
    "recargo_equivalencia": False,
    "footer_notes": "Pago a 30 días."
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    line_items: [
      {
        description: 'Consulting services',
        quantity: 2,
        unit_amount: 4150,
        tax: {type: 'vat', rate: 21}
      }
    ],
    type: 'complete',
    external_id: 'order-84312',
    number_series_id: 'ns_clx456def789',
    operation_date: '2025-06-15',
    recargo_equivalencia: false,
    footer_notes: 'Pago a 30 días.'
  })
};

fetch('https://api.finseed.es/v1/invoices/validate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.finseed.es/v1/invoices/validate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'line_items' => [
        [
                'description' => 'Consulting services',
                'quantity' => 2,
                'unit_amount' => 4150,
                'tax' => [
                                'type' => 'vat',
                                'rate' => 21
                ]
        ]
    ],
    'type' => 'complete',
    'external_id' => 'order-84312',
    'number_series_id' => 'ns_clx456def789',
    'operation_date' => '2025-06-15',
    'recargo_equivalencia' => false,
    'footer_notes' => 'Pago a 30 días.'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.finseed.es/v1/invoices/validate"

	payload := strings.NewReader("{\n  \"line_items\": [\n    {\n      \"description\": \"Consulting services\",\n      \"quantity\": 2,\n      \"unit_amount\": 4150,\n      \"tax\": {\n        \"type\": \"vat\",\n        \"rate\": 21\n      }\n    }\n  ],\n  \"type\": \"complete\",\n  \"external_id\": \"order-84312\",\n  \"number_series_id\": \"ns_clx456def789\",\n  \"operation_date\": \"2025-06-15\",\n  \"recargo_equivalencia\": false,\n  \"footer_notes\": \"Pago a 30 días.\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.finseed.es/v1/invoices/validate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"line_items\": [\n    {\n      \"description\": \"Consulting services\",\n      \"quantity\": 2,\n      \"unit_amount\": 4150,\n      \"tax\": {\n        \"type\": \"vat\",\n        \"rate\": 21\n      }\n    }\n  ],\n  \"type\": \"complete\",\n  \"external_id\": \"order-84312\",\n  \"number_series_id\": \"ns_clx456def789\",\n  \"operation_date\": \"2025-06-15\",\n  \"recargo_equivalencia\": false,\n  \"footer_notes\": \"Pago a 30 días.\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.finseed.es/v1/invoices/validate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"line_items\": [\n    {\n      \"description\": \"Consulting services\",\n      \"quantity\": 2,\n      \"unit_amount\": 4150,\n      \"tax\": {\n        \"type\": \"vat\",\n        \"rate\": 21\n      }\n    }\n  ],\n  \"type\": \"complete\",\n  \"external_id\": \"order-84312\",\n  \"number_series_id\": \"ns_clx456def789\",\n  \"operation_date\": \"2025-06-15\",\n  \"recargo_equivalencia\": false,\n  \"footer_notes\": \"Pago a 30 días.\"\n}"

response = http.request(request)
puts response.read_body

{
  "valid": true,
  "totals": {
    "subtotal": 8300,
    "tax": 1743,
    "total": 10043
  }
}

Invoices

Validate an invoice payload

Dry-runs an invoice creation payload through the exact validations the create endpoint applies, including the register check the recipient tax id gets when it is a Spanish NIF or an EU VAT number, without persisting anything. Failures return the same errors the create endpoint would; success returns the totals the invoice would carry. A passing validation does not reserve an invoice number and cannot fully guarantee the subsequent creation.

POST

invoices

validate

curl --request POST \
  --url https://api.finseed.es/v1/invoices/validate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "line_items": [
    {
      "description": "Consulting services",
      "quantity": 2,
      "unit_amount": 4150,
      "tax": {
        "type": "vat",
        "rate": 21
      }
    }
  ],
  "type": "complete",
  "external_id": "order-84312",
  "number_series_id": "ns_clx456def789",
  "operation_date": "2025-06-15",
  "recargo_equivalencia": false,
  "footer_notes": "Pago a 30 días."
}
'

import requests

url = "https://api.finseed.es/v1/invoices/validate"

payload = {
    "line_items": [
        {
            "description": "Consulting services",
            "quantity": 2,
            "unit_amount": 4150,
            "tax": {
                "type": "vat",
                "rate": 21
            }
        }
    ],
    "type": "complete",
    "external_id": "order-84312",
    "number_series_id": "ns_clx456def789",
    "operation_date": "2025-06-15",
    "recargo_equivalencia": False,
    "footer_notes": "Pago a 30 días."
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    line_items: [
      {
        description: 'Consulting services',
        quantity: 2,
        unit_amount: 4150,
        tax: {type: 'vat', rate: 21}
      }
    ],
    type: 'complete',
    external_id: 'order-84312',
    number_series_id: 'ns_clx456def789',
    operation_date: '2025-06-15',
    recargo_equivalencia: false,
    footer_notes: 'Pago a 30 días.'
  })
};

fetch('https://api.finseed.es/v1/invoices/validate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.finseed.es/v1/invoices/validate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'line_items' => [
        [
                'description' => 'Consulting services',
                'quantity' => 2,
                'unit_amount' => 4150,
                'tax' => [
                                'type' => 'vat',
                                'rate' => 21
                ]
        ]
    ],
    'type' => 'complete',
    'external_id' => 'order-84312',
    'number_series_id' => 'ns_clx456def789',
    'operation_date' => '2025-06-15',
    'recargo_equivalencia' => false,
    'footer_notes' => 'Pago a 30 días.'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.finseed.es/v1/invoices/validate"

	payload := strings.NewReader("{\n  \"line_items\": [\n    {\n      \"description\": \"Consulting services\",\n      \"quantity\": 2,\n      \"unit_amount\": 4150,\n      \"tax\": {\n        \"type\": \"vat\",\n        \"rate\": 21\n      }\n    }\n  ],\n  \"type\": \"complete\",\n  \"external_id\": \"order-84312\",\n  \"number_series_id\": \"ns_clx456def789\",\n  \"operation_date\": \"2025-06-15\",\n  \"recargo_equivalencia\": false,\n  \"footer_notes\": \"Pago a 30 días.\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.finseed.es/v1/invoices/validate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"line_items\": [\n    {\n      \"description\": \"Consulting services\",\n      \"quantity\": 2,\n      \"unit_amount\": 4150,\n      \"tax\": {\n        \"type\": \"vat\",\n        \"rate\": 21\n      }\n    }\n  ],\n  \"type\": \"complete\",\n  \"external_id\": \"order-84312\",\n  \"number_series_id\": \"ns_clx456def789\",\n  \"operation_date\": \"2025-06-15\",\n  \"recargo_equivalencia\": false,\n  \"footer_notes\": \"Pago a 30 días.\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.finseed.es/v1/invoices/validate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"line_items\": [\n    {\n      \"description\": \"Consulting services\",\n      \"quantity\": 2,\n      \"unit_amount\": 4150,\n      \"tax\": {\n        \"type\": \"vat\",\n        \"rate\": 21\n      }\n    }\n  ],\n  \"type\": \"complete\",\n  \"external_id\": \"order-84312\",\n  \"number_series_id\": \"ns_clx456def789\",\n  \"operation_date\": \"2025-06-15\",\n  \"recargo_equivalencia\": false,\n  \"footer_notes\": \"Pago a 30 días.\"\n}"

response = http.request(request)
puts response.read_body

{
  "valid": true,
  "totals": {
    "subtotal": 8300,
    "tax": 1743,
    "total": 10043
  }
}

Autorizaciones

Authorization

string

header

requerido

API key sent as a bearer token in the Authorization header.

Cuerpo

application/json

The invoice payload to validate.

Option 1
Option 2

The invoice to issue. The invoice number, issue date and totals are assigned server-side; the optional operation_date is the only date the caller sets. Issuance is immediate and the AEAT registration progresses asynchronously (poll verifactu.status). Include a rectifies block to issue a rectificativa instead of an ordinary invoice.

line_items

object[]

requerido

The lines to bill. At least one.

Required array length: 1 - 500 elements

Show child attributes

type

string

requerido

A complete invoice: the recipient is identified and their tax id is validated against the census when it is a Spanish NIF or an EU VAT number. On a linked rectificativa (a rectifies.invoice_id) of a complete original, the recipient is inherited from the corrected invoice and may be omitted; when supplied on a substitution it restates the recipient. On a linked rectificativa type must match the corrected invoice: complete over a simplified original is refused with upgrade_to_complete_not_allowed, and simplified over a complete original with downgrade_to_simplified_not_allowed.

Allowed value: "complete"

external_id

string

Your own reference for this invoice, such as an order id: 1 to 255 characters, no control characters. Unique per environment: a later request carrying the same value is rejected with external_id_already_used no matter how old the original is, which is the guard against duplicates that the 24-hour Idempotency-Key window cannot give. Once used, a value stays taken even after the invoice is voided. Echoed as external_id on the invoice.

Required string length: 1 - 255

Pattern: ^[^\p{Cc}]{1,255}$

Ejemplo:

"order-84312"

number_series_id

string

Number series to issue on (see the Number Series resource). Defaults to the environment default series. For an ordinary invoice this must be a standard series; for a rectificativa (a rectifies block) it must be a rectifying series. Rejected with num_series_not_applicable_for_order_invoice on a linked rectificativa against an order-linked invoice, which always numbers on the rectifying series its integration owns for that kind of correction.

Ejemplo:

"ns_clx456def789"

rectifies

object

Turns this request into a rectificativa (corrective invoice). Reference the original with exactly one of invoice_id (issued through Finseed) or external (issued elsewhere). Omit the whole block to issue an ordinary invoice.

Show child attributes

operation_date

string

Date the underlying operation took place, as a calendar day (YYYY-MM-DD) interpreted in the Europe/Madrid timezone. Must be an existing calendar day between 2025-01-01 and today. When omitted, or when it equals the issue date, the invoice carries the issue date as its operation date. Not supported together with a rectifies block.

Pattern: ^(\d{4})-(\d{2})-(\d{2})$

Ejemplo:

"2025-06-15"

recargo_equivalencia

boolean

Applies the Spanish recargo de equivalencia regime: every VAT line gains its legally paired surcharge (21%→5.2%, 10%→1.4%, 4%→0.5%), computed server-side.

Ejemplo:

false

footer_notes

string

Free-form text printed at the bottom of the invoice PDF.

Maximum string length: 2000

Ejemplo:

"Pago a 30 días."

recipient

object

The identified recipient of a complete invoice.

Show child attributes

Respuesta

The payload is valid, with the totals it would carry.

Successful dry-run of an invoice creation payload.

valid

boolean

requerido

Always true on a 200: the payload passed every validation the create endpoint runs. Failures return the same error responses the create endpoint would.

totals

object

requerido

The exact totals the invoice would carry if created with this payload.

Show child attributes

Introduction

Invoices

Number Series

Tax IDs

Customer portal

Validate an invoice payload

Autorizaciones

Cuerpo

Respuesta