Create an invoice

Create a sales invoice.

It is created in draft by default; pass options.issue_directly: true to issue it immediately (assigning the correlative number and freezing the document per AEAT), or issue it later.
VeriFactu alta is transmitted to AEAT asynchronously — a 201 does not mean AEAT has accepted the invoice yet, so poll it for the AEAT status.

{
  "client_id": "0190a1b2-c3d4-7e5f-8a90-1b2c3d4e5f60",
  "lines": [{ "description": "Consulting", "quantity": 1, "unit_price": 1000, "tax_rate": 21 }],
  "options": { "issue_directly": true }
}

Limits: at least one line is required; send an Idempotency-Key (≤255 chars, remembered 24 h) for safe retries; a duplicate external_id upserts the existing invoice instead of creating a new one.

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 409 idempotency_key_reused. See the Idempotency guide.

Length1 <= length <= 255

Factuarea-Version?string

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.

Formatdate

X-Active-Profile?string

Operate on behalf of a child company (gestoría master key): pass its public id (UUID v7) and the request runs against that child's data without changing the key's scope, tier or environment (omit to use the key's own company). Invalid UUID → 400 parameter_invalid_uuid; unknown or non-owned id → 404 profile_not_found. See the Acting on behalf guide.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

client_id*string

Formatuuid

series_id*string

Formatuuid

price_list_id?|

Formatuuid

reprice_strategy?|

Value in"existing_catalog_lines" | "future_lines_only" | null

issued_on*string

Formatdate

due_on*string

Formatdate

notes?|

Lengthlength <= 1000

external_id?|

Lengthlength <= 100

metadata?|

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.

Propertiesproperties <= 50

tags?array<>|

Itemsitems <= 30

custom_fields?array<>|

Itemsitems <= 50

lines*array<>

Items1 <= items

options?

Response Body

`application/json`

Request example

const apiKey = process.env.FACTUAREA_API_KEY;if (!apiKey) throw new Error("Set FACTUAREA_API_KEY");const response = await fetch("https://api.factuarea.com/v1/invoices", {  method: "POST",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json","Content-Type":"application/json","Idempotency-Key":"erp-2026-public-api-v1-invoices-create"} },  body: JSON.stringify({  "client_id": "f58fbf7f-333f-499b-affc-c0d396cbd83f",  "series_id": "019e5584-7a72-7038-a8f6-561ed180b699",  "issued_on": "2026-06-01",  "due_on": "2026-07-01",  "notes": "Factura creada via API v1",  "metadata": {    "order_ref": "PO-2026-0042"  },  "lines": [    {      "description": "Servicio de consultoria",      "quantity": 2,      "unit_price": 150,      "tax_rate_id": "019e5584-7a7f-70fd-b9cb-9466c3ee12a8",      "discount_percent": 0    }  ]}),});if (!response.ok) throw new Error(await response.text());if (response.status !== 204) console.log(await response.json());

Response example

{
  "data": {
    "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42",
    "object": "invoice",
    "number": null,
    "is_number_assigned": false,
    "type": "F1",
    "series": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02",
      "code": "FAC-2026"
    },
    "client": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
      "name": "Acme Soluciones SL"
    },
    "status": "draft",
    "price_list_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10",
    "price_list_name": "Tarifa profesional 2026",
    "issued_on": "2026-03-15",
    "due_on": "2026-04-14",
    "subtotal": 1000,
    "taxes_total": 210,
    "total_vat": 210,
    "total_retention": 0,
    "total_surcharge": 0,
    "total": 1210,
    "total_disbursements": 0,
    "total_to_pay": 1210,
    "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,
        "tax_rate": 21,
        "retention_rate": 0,
        "surcharge_rate": 0,
        "discount_percent": 0,
        "subtotal": 1000,
        "taxes": 210,
        "total": 1210,
        "indirect_tax_regime": "iva",
        "variant": null,
        "presentation": null,
        "item_kind": "service",
        "commercial_unit_code": "HUR",
        "base_unit_code": "HUR",
        "conversion_factor": "1.000000",
        "base_quantity": "10.0000",
        "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,
        "regime_key": null,
        "exemption_reason": null,
        "aeat_tax_code": "S1",
        "line_type": "NORMAL",
        "source_invoice_reference": null,
        "source_invoice_ids": null,
        "unit": null,
        "exemption_reason_text": null
      }
    ],
    "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": "not_applicable",
    "paid_amount": 0,
    "pending_amount": 1210,
    "payments": {
      "detail": [],
      "total": 0,
      "pending": 1210
    },
    "is_corrective": false,
    "corrective": null,
    "payment": null,
    "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_at": null,
    "paid_on": null,
    "sent_at": null,
    "voided_at": null,
    "void_reason": null,
    "scheduled_for": null,
    "scheduled_action": null,
    "channel": null,
    "source_store_id": null,
    "created_at": "2026-03-15T11:30:00Z",
    "updated_at": "2026-03-15T11:45:00Z"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "Falta header Authorization o X-API-Key.",
    "doc_url": "https://docs.factuarea.com/guides/errors#missing_api_key",
    "request_id": "req_6404f4f3c8fb061b488677829c"
  }
}

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "Esta operación requiere el scope 'invoices:write'. Tu API key solo tiene los scopes: ninguno.",
    "doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
    "request_id": "req_c813752970820889077e529f3b"
  }
}

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_key_reused",
    "message": "Esa `Idempotency-Key` ya se usó con un payload distinto. La clave identifica una operación concreta, así que reutilizarla para otra vaciaría de sentido el replay.",
    "doc_url": "https://docs.factuarea.com/guides/errors#idempotency_key_reused",
    "request_id": "req_8b869628d192bdc3c3bd7a18dc"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_param_value",
    "message": "El campo client_id es obligatorio.",
    "param": "client_id",
    "errors": [
      {
        "param": "client_id",
        "code": "parameter_missing",
        "message": "El campo client_id es obligatorio."
      }
    ],
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_param_value",
    "request_id": "req_b81bb83c5e121fd832e2ab3668"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Has excedido el límite de requests permitido. Reintenta más tarde.",
    "doc_url": "https://docs.factuarea.com/guides/errors#rate_limit_exceeded",
    "request_id": "req_11787a88162aefa83ad8d2c5ca"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.",
    "doc_url": "https://docs.factuarea.com/guides/errors#internal_error",
    "request_id": "req_d72a5da564028c16ceab8553a7"
  }
}

Create an invoice

Authorization

Headers

Request Body

Response Body

201application/json

401application/json

403application/json

409application/json

422application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`