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": "<string>",
  "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": "<string>",
    "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: '<string>',
    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' => '<string>',
    '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\": \"<string>\",\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\": \"<string>\",\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\": \"<string>\",\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
  }
}

POST

invoices

validate

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": "<string>",
  "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": "<string>",
    "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: '<string>',
    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' => '<string>',
    '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\": \"<string>\",\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\": \"<string>\",\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\": \"<string>\",\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. On a linked rectificativa (a rectifies.invoice_id) the recipient is inherited from the corrected invoice and may be omitted; when supplied on a substitution it restates the recipient.

Allowed value: "complete"

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.

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

Create a rectifying invoice

List invoices

Introduction

Invoices

Number Series

Tax IDs

Customer portal

Validate an invoice payload

Autorizaciones

Cuerpo

Respuesta