Crea una factura de compra

Registra una factura recibida de un proveedor.

Las líneas de catálogo admiten product_id, variant_id, presentation_id, supplier_offer_id y un confirmed_base_quantity opcional.
Con supplier_offer_id, el coste, unidad de compra y conversión a unidad base quedan congelados en el snapshot de línea; se puede omitir unit_price.
Crear la factura como pending registra una vez el stock entrante.
Una factura draft no afecta al stock hasta marcarla como pagada.

Clave opaca generada por el cliente (hasta 255 caracteres; se recomienda UUID v7) que hace seguros los reintentos: la primera respuesta se cachea y se reproduce en las repeticiones sin volver a ejecutar la mutación. Reutilizar una clave con un cuerpo distinto devuelve 409 idempotency_key_reused. Consulta la guía de Idempotency.

Longitud1 <= length <= 255

Factuarea-Version?string

Fija la versión de la API (YYYY-MM-DD, versionado por fecha estilo Stripe) para esta petición; omítelo para usar la versión fijada de la clave, o la última si no hay ninguna. Versión no soportada → 400 unsupported_api_version; malformada → 400 parameter_invalid_format. La versión efectiva se refleja en la cabecera de respuesta Factuarea-Version. Consulta la guía de Versioning.

Formatodate

X-Active-Profile?string

Opera en nombre de una empresa hija (API key maestra de gestoría): pasa su id público (UUID v7) y la petición se ejecuta contra los datos de esa hija sin cambiar el scope, el tier ni el environment de la clave (omítelo para usar la propia empresa de la clave). UUID inválido → 400 parameter_invalid_uuid; id desconocido o no propio → 404 profile_not_found. Consulta la guía de Acting on behalf.

Formatouuid

Cuerpo de la petición

application/json

Definiciones de TypeScript

Usa el tipo request body en TypeScript.

source_purchase_invoice_id?|

Formatouuid

is_simplified?boolean

supplier_id?|

Formatouuid

expense_category_id?|

Formatouuid

external_invoice_number*string

Longitudlength <= 255

external_id?|

Clave de negocio externa (clave de integración de tu ERP/CRM), única por empresa. Ortogonal a external_invoice_number (el número fiscal del proveedor): external_id es el ID del recurso en el sistema integrador.

Longitudlength <= 100

internal_code?|

Longitudlength <= 255

issued_on*string

Formatodate

received_on?|

Formatodate

due_on?|

Formatodate

status?string

Valor en"draft" | "pending"

notes?|

Longitudlength <= 1000

metadata?|

Un mapa libre de hasta 50 pares clave→valor para almacenar datos estructurados arbitrarios (los valores son cadenas de hasta 500 caracteres). A diferencia de custom_fields —una lista ordenada de pares tipados {field, value} con semántica de visualización, presente en los seis recursos de documento—, metadata es un mapa sin orden para datos de integración opacos; un documento puede llevar ambos. Los recursos maestros (Client, Supplier) no tienen custom_fields, así que su metadata hace también de almacén de custom-fields.

Claves reservadas (solo lectura). Cuando el sistema autoemite una factura a partir de una correlación de pago (Stripe/GoCardless/MONEI), escribe stripe_subscription_id, stripe_invoice_id, billing_reason, period_start y period_end en la metadata de esa factura automáticamente. No las establezcas ni las sobrescribas a mano —la plataforma es su dueña y un valor manual puede reemplazarse cuando se ejecuta la correlación.

Propiedadesproperties <= 50

internal_notes?|

Longitudlength <= 2000

payment_method?|

Longitudlength <= 30

payment_terms_days?|

Rango0 <= value <= 365

bank_account_id?integer|null

expense_account?|

Longitudlength <= 50

tax_period?|

Longitudlength <= 10

tags?array<>|

Elementositems <= 30

custom_fields?array<>|

Custom fields tipados como [{field, value}]. field hasta 60 caracteres (no vacío), value hasta 500 caracteres, hasta 50 entradas.

Elementositems <= 50

is_reverse_charge?boolean|null

deductible_percentage?|

Rango0 <= value <= 100

operation_class?|

Clasifica el origen del gasto para el IVA soportado del Modelo 303 (casillas [28]-[39]). Conjunto cerrado; nullable → por defecto corriente.

exclude_347?boolean

Si excluir esta factura de compra de la declaración anual del Modelo 347.

lines*array<>

Elementos1 <= items

Cuerpo de la respuesta

`application/json`

Ejemplo de petición

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());

Ejemplo de respuesta

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

Crea una factura de compra

Authorization

Headers

Cuerpo de la petición

Cuerpo de la respuesta

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`