Amounts & dates

Every monetary, date and time value in the public API follows a small set of fixed conventions. They are the same across every resource, so once you handle them in one place your client works everywhere.

Money

Amounts are always in euros (EUR) — the currency field is present on every document and is "EUR" in v1 (ISO 4217). There is no multi-currency support yet.

Amounts carry two decimal places (cents precision). The canonical representation is a decimal string with exactly two decimals, Stripe-style:

{ "price": "1234.56" }

Let the API compute totals

The total of a document follows one formula across the whole API:

total = subtotal + total_vat + total_surcharge − total_retention

If you need to preview the breakdown before creating a document — for an order summary, a cart, or to reconcile your own figures — call POST /v1/taxes/calculate-totals with the lines and read back the computed subtotal, total_vat, total_surcharge, total_retention and total (amounts in EUR), plus a per-line breakdown in the same order:

{
  "subtotal": 250,
  "total_vat": 52.5,
  "total_surcharge": 0,
  "total_retention": 15,
  "total": 287.5,
  "lines": [
    { "subtotal": 100, "vat_amount": 21, "surcharge_amount": 0, "retention_amount": 0, "total": 121 }
  ]
}

The same per-line tax breakdown applies to every sales document: invoices, quotes, proformas and delivery notes all accept a per-line retention_rate and surcharge_rate (IRPF withholding and equivalence surcharge, 0–100), and their header carries the aggregated total_vat, total_surcharge and total_retention. The same formula holds everywhere. Each line also echoes retention_rate and surcharge_rate back in the response, so you can reconcile the breakdown line by line.

Purchase invoices — per-line tax

A purchase invoice records what a supplier charged you, so each of its lines accepts a few extra fiscal qualifiers that the sales side covers in its own way. On CreatePurchaseInvoiceRequest.lines[] you can set:

The per-line total follows the same shape as the sales side, with retention subtracted and surcharge added:

line total = subtotal + taxes − retention_amount + surcharge_amount

surcharge_rate on a purchase line follows the same legal VAT↔surcharge pairs as a sales line, validated server-side: 21 → 5.2, 10 → 1.4, 4 → 0.5, 0 → 0. The 0 → 0 pair is valid on the purchase side too — an exempt or zero-rated line carries a zero surcharge. An illegal pair is rejected with 422.

exemption_reason qualifies why a line is outside ordinary VAT. It is an enum or null (or absent), which means the line inherits the qualification from the invoice header, or declares none:

A purchase-invoice line carrying both a surcharge and an exemption reason:

{
  "description": "Wholesale goods",
  "quantity": 10,
  "unit_price": "50.00",
  "tax_rate": 21,
  "surcharge_rate": 5.2,
  "retention_rate": 0,
  "vat_deductible": true,
  "exemption_reason": null
}

curl -s -X POST https://api.factuarea.com/v1/purchase_invoices \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "supplier_id": "01931b3e-...s01",
    "received_on": "2026-03-15",
    "lines": [
      { "description": "Exempt service", "quantity": 1, "unit_price": "200.00", "tax_rate": 0, "surcharge_rate": 0, "exemption_reason": "E1" }
    ]
  }' | jq '.data | {subtotal, total_vat, total_surcharge, total_retention, total}'

Dates

Calendar dates (no time component) use YYYY-MM-DD — the ISO-8601 / RFC 3339 full-date form. This covers fields such as issued_on, due_on, paid_on, valid_until, delivery_date, received_on, start_on and end_on:

{
  "issued_on": "2026-03-15",
  "due_on": "2026-04-14",
  "paid_on": "2026-03-20"
}

Send dates in the same format. There is no time and no timezone on a date — it is the calendar day as recorded for the document.

Timestamps

Instant-in-time fields (audit and lifecycle metadata such as created_at, updated_at, signed_at, last_delivery_at) use full ISO-8601 / RFC 3339 date-time strings. Most are emitted in UTC with a Z suffix:

{ "created_at": "2026-05-15T10:34:21Z" }

Some timestamps carry an explicit Europe/Madrid offset instead (+01:00 in winter, +02:00 in summer):

{ "created_at": "2026-04-15T10:31:05+02:00" }

Timezone for quotas

The monthly rate-limit quota resets on day 1 of each calendar month at 00:00 Europe/Madrid (CET/CEST), not UTC. The per-minute quota is a sliding window and the X-RateLimit-Reset header is a UNIX timestamp (seconds since the epoch, timezone-independent). See Rate limits for the full window semantics.

Whenever the API needs a single civil-calendar reference for a business boundary — fiscal periods, the monthly quota reset — that reference is Europe/Madrid.

Quick reference