Create a purchase invoice

Record an invoice received from a supplier.

Catalog lines accept product_id, variant_id, presentation_id, supplier_offer_id and an optional confirmed_base_quantity.
When supplier_offer_id is provided, the supplier cost, purchase unit and base-unit conversion are frozen in the invoice line snapshot; unit_price may be omitted.
Creating the invoice as pending registers the inbound stock once.
A draft invoice does not affect stock until it is later marked as paid.

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.

source_purchase_invoice_id?|

Formatuuid

is_simplified?boolean

supplier_id?|

Formatuuid

expense_category_id?|

Formatuuid

external_invoice_number*string

Lengthlength <= 255

external_id?|

External business key (integration key from your ERP/CRM), unique per company. Orthogonal to external_invoice_number (the supplier fiscal number): external_id is the resource ID in the integrator system.

Lengthlength <= 100

internal_code?|

Lengthlength <= 255

issued_on*string

Formatdate

received_on?|

Formatdate

due_on?|

Formatdate

status?string

Value in"draft" | "pending"

notes?|

Lengthlength <= 1000

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

internal_notes?|

Lengthlength <= 2000

payment_method?|

Lengthlength <= 30

payment_terms_days?|

Range0 <= value <= 365

bank_account_id?integer|null

expense_account?|

Lengthlength <= 50

tax_period?|

Lengthlength <= 10

tags?array<>|

Itemsitems <= 30

custom_fields?array<>|

Typed custom fields as [{field, value}]. field up to 60 characters (non-empty), value up to 500 characters, up to 50 entries.

Itemsitems <= 50

is_reverse_charge?boolean|null

deductible_percentage?|

Range0 <= value <= 100

operation_class?|

Classifies the origin of the expense for the input VAT of Modelo 303 (boxes [28]-[39]). Closed set; nullable → defaults to corriente.

exclude_347?boolean

Whether to exclude this purchase invoice from the annual Modelo 347 declaration.

lines*array<>

Items1 <= items

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/purchase_invoices", {  method: "POST",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json","Content-Type":"application/json","Idempotency-Key":"erp-2026-public-api-v1-purchase_invoices-create"} },  body: JSON.stringify({  "supplier_id": "456abe0d-79de-44e4-aa62-beedd41a7993",  "external_invoice_number": "HARVEST-PI-EXT-2026-0007",  "internal_code": "GASTO-2026-0007",  "issued_on": "2026-04-15",  "received_on": "2026-04-18",  "due_on": "2026-05-15",  "status": "draft",  "notes": "Factura de suministro electrico abril 2026.",  "internal_notes": "Revisar con contabilidad antes del cierre trimestral.",  "payment_method": "bank_transfer",  "payment_terms_days": 30,  "expense_account": "6280001",  "tax_period": "2026-Q2",  "tags": [    "suministros",    "electricidad",    "recurrente"  ],  "is_reverse_charge": false,  "metadata": {    "cost_center": "operaciones",    "po_number": "PO-4521"  },  "lines": [    {      "description": "Suministro electrico abril 2026",      "quantity": 1,      "unit_price": 450,      "tax_rate": 21    },    {      "description": "Cargo fijo de potencia contratada",      "quantity": 1,      "unit_price": 50,      "tax_rate": 21    }  ]}),});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-3c5d6e7f8a07",
    "object": "purchase_invoice",
    "external_invoice_number": "INV-2026-001-DI",
    "is_simplified": false,
    "external_id": "ERP-COMPRA-2026-0007",
    "internal_code": "GASTO-2026-0007",
    "supplier": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02",
      "name": "Distribuciones Ibéricas, S.L."
    },
    "status": "pending",
    "issued_on": "2026-01-05",
    "received_on": "2026-01-08",
    "due_on": "2026-02-04",
    "subtotal": 350,
    "taxes_total": 73.5,
    "total_vat": 73.5,
    "total_retention": 0,
    "total_surcharge": 0,
    "total": 423.5,
    "currency": "EUR",
    "paid_amount": 0,
    "pending_amount": 423.5,
    "payment_status": "pending",
    "paid_at": null,
    "payment_method": "transferencia",
    "payment_terms_days": 30,
    "bank_account": null,
    "expense_account": "6280001",
    "expense_category_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c01",
    "deductible_percentage": 100,
    "operation_class": "corriente",
    "exclude_347": false,
    "tax_period": "2026-Q1",
    "is_reverse_charge": false,
    "tags": [
      "suministros",
      "oficina"
    ],
    "custom_fields": [
      {
        "field": "centro_coste",
        "value": "CC-OFICINA"
      }
    ],
    "internal_notes": "Revisar con contabilidad antes del cierre trimestral.",
    "attachment": {
      "filename": "factura-material-enero-2026.pdf",
      "mime_type": "application/pdf",
      "size_bytes": 241,
      "download_url": "/v1/purchase_invoices/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a07/file"
    },
    "lines": [
      {
        "object": "purchase_invoice_line",
        "description": "Material oficina pedido Q1",
        "additional_description": "Papel blanco A4, 80 g/m².",
        "quantity": 1,
        "unit_price": 350,
        "tax_rate": 21,
        "retention_rate": 0,
        "surcharge_rate": 0,
        "subtotal": 350,
        "taxes": 73.5,
        "retention_amount": 0,
        "surcharge_amount": 0,
        "vat_deductible": true,
        "total": 423.5,
        "exemption_reason": null,
        "indirect_tax_regime": null,
        "product": null,
        "variant": null,
        "presentation": null,
        "supplier_offer_id": null,
        "item_kind": "good",
        "commercial_unit_code": "H87",
        "base_unit_code": "H87",
        "conversion_factor": "1.000000",
        "base_quantity": "1.0000",
        "price_source": "manual",
        "price_unit_code": "H87",
        "configuration": null,
        "options": [],
        "price_semantics": "per_commercial_unit",
        "price_adjustment_total": "0.0000",
        "option_adjustments_absorbed": false
      }
    ],
    "metadata": {
      "purchase_order": "PO-2026-0007"
    },
    "notes": "Pedido material oficina Q1.",
    "created_at": "2026-01-08T10:00:00Z",
    "updated_at": "2026-01-08T10:00: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_a9d6c7541fc10ad694f45d9457"
  }
}

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

{
  "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_edd505b1d113ba7ec4974c235a"
  }
}

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

{
  "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_253009beeefd0170631bfbdd7b"
  }
}

{
  "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_e0ef97f1ed169122db3a6e459e"
  }
}

Create a purchase 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`