Invoices

Create an invoice

Create an invoice in draft, or issue it at once with options.issue_directly: true.

  • Send an Idempotency-Key; a duplicate external_id upserts. A 201 is not AEAT acceptance.
  • type: F2, payment or options.register_verifactu make it a one-call checkout (paid simplified invoice).

Signing certificate (NO VERI*FACTU). Only in that mode, a missing or invalid company certificate is rejected before the invoice is issued: 422 verifactu_not_eligible, error.subcode: signing_certificate_unavailable; nothing is consumed, so fix it and repeat the call.

post/companies/{company}/invoices

Request

  • Base URL: https://api.factuarea.com/v1
  • URL: https://api.factuarea.com/v1/companies/{company}/invoices
  • Auth: one of:
    • HTTP bearer
    • API key in header X-API-Key

Path parameters

companystring uuid required

Public identifier (UUID v7) of the company. Get it from GET /v1/me (data.scope[].id).

Headers

Idempotency-Keystring
Example:01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b

Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns 422 idempotency_key_reused; the values of secret fields (password, secret…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the Idempotency guide.

Factuarea-Versionstring date
Example:2026-06-01

Pin the API version (YYYY-MM-DD, Stripe-style date versioning) for this request; omit to use the key's pinned version, or the latest if none. Unsupported version → 400 unsupported_api_version; malformed → 400 parameter_invalid_format. The effective version is echoed in the Factuarea-Version response header. See the Versioning guide.

Request body

type'F1' | 'F2' | 'null' nullable

Invoice type: F1 (complete invoice, the default) or F2 (simplified invoice, the ticket of a terminal). A simplified invoice needs simplified invoices enabled for the company (422 simplified_invoices_disabled) and cannot exceed the absolute cap of 3,000 € VAT included (422 simplified_invoice_not_allowed).

client_idstring uuid

Id of the client (UUID v7). Required with type: F1 (or without type), and the client must have a complete tax ID. Optional with type: F2: without it the invoice is an anonymous ticket; with it, a qualified simplified invoice (the client must belong to your company).

prices_include_taxboolean nullable

When true, the unit_price of every line is the FINAL price with taxes (VAT included) and the system computes the net base to the cent, so the invoice total equals the sum of the amounts you sent. If no distribution of the cents reaches that total the request is rejected with 422 amount_reconciliation_failed and nothing is issued. Catalog lines (product_id) are not accepted in this mode. Defaults to false.

operation_onstring date nullable

Date the operation took place (YYYY-MM-DD) when it differs from the issue date (arts. 6.1.f and 7.1.c of Royal Decree 1619/2012). It cannot be later than issued_on (422 operation_date_after_issue_date) unless the first line that declares a regime_key uses 14 or 15. It is printed on the PDF and reported in the VeriFactu record.

series_idstring uuid nullable
price_list_idstring uuid nullable
reprice_strategy'existing_catalog_lines' | 'future_lines_only' | 'null' nullable
issued_onstring date required
due_onstring date required
notesstring nullable
external_idstring nullable
metadataMetadata nullable

A free map of up to 50 key→value pairs for storing arbitrary structured data (values are strings up to 500 characters). Unlike custom_fields — an ordered list of typed {field, value} pairs with display semantics, present on the six document resources — metadata is an unordered map for opaque integration data; a document may carry both. The master resources (Client, Supplier) have no custom_fields, so their metadata doubles as the custom-fields store.

Reserved keys (read-only). When the system auto-issues an invoice from a payment correlation (Stripe/GoCardless/MONEI), it writes stripe_subscription_id, stripe_invoice_id, billing_reason, period_start and period_end into that invoice metadata automatically. Do not set or overwrite them by hand — the platform owns them and a manual value may be replaced when the correlation runs.

tagsstring[] nullable

Example request

{
  "metadata": {
    "erp_code": "IVA-GEN",
    "ledger_account": "477000"
  }
}

Response

Late retry of an unattended checkout: the external_id already belongs to an invoice issued in your company, so that invoice is returned unchanged — with the Idempotent-Replayed: true header — after completing the VeriFactu alta and the payment if they were missing. Nothing new is created and the invoice number is not consumed again. If the type or the total of the request differ from the issued invoice, the answer is 409 unattended_replay_mismatch instead.

Example response

{
  "data": {
    "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42",
    "object": "invoice",
    "number": "FAC-2026-00042",
    "is_number_assigned": true,
    "type": "F1",
    "series": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02",
      "code": "FAC-2026"
    },
    "client": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
      "name": "Acme Soluciones SL"
    },
    "status": "paid",
    "price_list_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10",
    "price_list_name": "Tarifa profesional 2026",
    "issued_on": "2026-03-15",
    "due_on": "2026-04-14",
    "operation_on": null,
    "subtotal": "1000.00",
    "taxes_total": "210.00",
    "total_vat": "210.00",
    "total_retention": "0.00",
    "total_surcharge": "0.00",
    "total": "1210.00",
    "total_disbursements": "0.00",
    "total_to_pay": "1210.00",
    "currency": "EUR",
    "notes": "Servicios profesionales marzo 2026.",
    "external_id": "ERP-2026-0042",
    "lines": [
      {
        "object": "invoice_line",
        "description": "Consultoría técnica (10 h)",
        "additional_description": "Auditoría inicial e informe de mejoras",
        "product": {
          "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03",
          "name": "Consultoría técnica (hora)"
        },
        "quantity": 10,
        "unit_price": "100.0000",
        "tax_rate": 21,
        "retention_rate": 0,
        "surcharge_rate": 0,
        "discount_percent": 0,
        "subtotal": "1000.00",
        "taxes": "210.00",
        "total": "1210.00",
        "variant": null,
        "presentation": null,
        "item_kind": "service",
        "commercial_unit_code": "HUR",
        "base_unit_code": "HUR",
        "conversion_factor": "1.000000",
        "base_quantity": "10.0000",
        "counted_quantity": null,
        "counted_unit": null,
        "price_list_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10",
        "price_list_name": "Tarifa profesional 2026",
        "price_source": "price_list",
        "price_unit_code": "HUR",
        "configuration": null,
        "options": [],
        "price_semantics": "per_commercial_unit",
        "price_adjustment_total": "0.0000",
        "option_adjustments_absorbed": false,
        "indirect_tax_regime": "iva",
        "aeat_tax_code": "S1",
        "line_type": "NORMAL"
      }
    ],
    "metadata": {
      "order_id": "PO-2026-0042"
    },
    "tags": [
      "consultoria",
      "cliente-vip"
    ],
    "custom_fields": [
      {
        "field": "centro_coste",
        "value": "CC-2026-001"
      },
      {
        "field": "numero_pedido",
        "value": "PO-2026-0042"
      }
    ],
    "operation_regime": "general",
    "exemption_reason": null,
    "legal_mentions": [],
    "exclude_347": false,
    "verifactu_status": "accepted",
    "paid_amount": "1210.00",
    "pending_amount": "0.00",
    "payments": {
      "detail": [
        {
          "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a90",
          "object": "payment",
          "invoice_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42",
          "amount": "1210.00",
          "payment_date": "2026-03-20",
          "payment_method": "bank_transfer",
          "payment_method_text": "Transferencia bancaria",
          "reference": "TRF-2026-0042",
          "notes": null,
          "is_reversed": false,
          "reversed_at": null,
          "reversal_reason": null,
          "reversal_reason_text": null,
          "reversal_note": null,
          "created_at": "2026-03-20T10:30:00Z",
          "updated_at": "2026-03-20T10:30:00Z"
        }
      ],
      "total": "1210.00",
      "pending": "0.00"
    },
    "is_corrective": false,
    "corrective": null,
    "payment": {
      "method": "bank_transfer",
      "reference": "TRF-2026-0042",
      "date": "2026-03-20"
    },
    "public_link": {
      "object": "public_link",
      "url": "https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42",
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42",
      "enabled": true,
      "expires_at": "2026-09-15T23:59:59Z",
      "max_days": 120
    },
    "substituted_by": null,
    "recurring": null,
    "paid_recorded_at": "2026-03-20T10:30:00Z",
    "paid_date": "2026-03-20",
    "issued_at": "2026-03-15T11:45:00Z",
    "sent_at": "2026-03-15T11:47:12Z",
    "sent_via": "email",
    "is_sent": true,
    "voided_at": null,
    "void_reason": null,
    "scheduled_for": null,
    "scheduled_action": null,
    "channel": null,
    "source_store_id": null,
    "origin": "native",
    "created_at": "2026-03-15T11:30:00Z",
    "updated_at": "2026-03-20T10:30:00Z"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.