Crea una factura de compra

Clau única generada pel client per garantir la idempotència en els reintents. Et permet reenviar de manera segura la mateixa petició: la primera resposta es cacheja i es retorna sense tornar a executar la mutació. És una cadena opaca per al servidor; qualsevol valor únic de fins a 64 caràcters és vàlid (UUID v7, UUID v4, ULID, nanoid, etc.). Es recomana UUID v7 per coherència amb els identificadors de l'API. La mateixa clau reutilitzada amb un body diferent retorna 409 idempotency_key_reused.

Longitud1 <= length <= 64

Cos de la petició

application/json

Definicions de TypeScript

Usa el tipus request body a TypeScript.

supplier_id*string

Formatuuid

expense_category_id?|

Formatuuid

external_invoice_number*string

Longitudlength <= 255

external_id?|

Clau de negoci externa (clau d'integració ERP/CRM, change external-id-documents). Ortogonal a external_invoice_number (el número fiscal del proveïdor): external_id és l'ID del recurs en el sistema de l'integrador, únic per empresa.

Longitudlength <= 100

internal_code?|

Longitudlength <= 255

issued_on*string

Formatdate

received_on?|

Formatdate

due_on?|

Formatdate

status?string

Estat inicial opcional (BR-PUR-001). Model de 4 estats: allowlist de CREACIÓ draft|pending (received/pending_payment es van fusionar en pending). paid|cancelled són transicions del cicle de vida (mark_paid/change_status), NO estats de creació. Si s'omet, el domini aplica el valor per defecte draft.

Valor a"draft" | "pending"

notes?|

Longitudlength <= 1000

metadata?|

Un mapa lliure de fins a 50 parells clau→valor per emmagatzemar dades estructurades arbitràries (els valors són cadenes de fins a 500 caràcters). Això és DIFERENT de custom_fields: metadata és un mapa clau→valor SENSE ORDRE per a dades d'integració opaques, mentre que custom_fields (en els sis recursos de document) és una llista ORDENADA de parells tipats {field, value} amb semàntica de visualització. Un document pot portar tots dos. Els recursos mestres (Client, Supplier) no tenen custom_fields tipats: fes servir el seu metadata com a magatzem de camps personalitzats sense tipar.

Propietatsproperties <= 50

internal_notes?|

Camps estesos. Només la FORMA bàsica; l'allowlist de payment_method, el format de tax_period i la cardinalitat de tags es validen al VO/Aggregate.

Longitudlength <= 2000

payment_method?|

Longitudlength <= 30

payment_terms_days?|

Rang0 <= value <= 365

bank_account_id?integer|null

expense_account?|

Longitudlength <= 50

tax_period?|

Longitudlength <= 10

is_reverse_charge?boolean|null

deductible_percentage?|

Rang0 <= value <= 100

operation_class?|

operation_class (BR-PUR-018 / BR-TXR-030) SÍ que és escrivible via API v1 en compres: l'integrador classifica l'origen de la seva despesa a efectes de l'IVA suportat del Model 303 (caselles [28]-[39]). Conjunt tancat; nullable → default corriente.

Valor a"corriente" | "bien_inversion" | "importacion" | "intracomunitaria"

exclude_347?boolean

exclude_347 (BR-TXR-024) SÍ que és escrivible via API v1 en compres: l'integrador classifica les seves pròpies despeses. En vendes (Invoice) el flag és de només lectura en v1 i només es muta des de la SPA interna (vegeu InvoiceV1Resource). Asimetria deliberada per superfície.

tags?array<>|

Elementsitems <= 30

custom_fields?array<>|

custom_fields tipats [{field,value}] (§10) — VO Shared CustomFields. field ≤60 no buit, value ≤500, ≤50 entrades.

Elementsitems <= 50

lines*array<>

Elements1 <= items

Cos de la resposta

`application/json`

{
  "data": {
    "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a07",
    "object": "purchase_invoice",
    "external_invoice_number": "INV-2026-001-DI",
    "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": "paid",
    "issued_on": "2026-01-05",
    "received_on": "2026-04-18",
    "due_on": "2026-02-04",
    "subtotal": 350,
    "taxes_total": 73.5,
    "total_retention": 0,
    "total": 423.5,
    "currency": "EUR",
    "paid_amount": 423.5,
    "pending_amount": 0,
    "payment_status": "paid",
    "paid_at": "2026-01-10",
    "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-Q2",
    "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-suministros-abril-2026.pdf",
      "mime_type": "application/pdf",
      "size_bytes": 241,
      "download_url": "/v1/purchase_invoices/019e822c-555a-709d-99d7-2cfeac9fc920/file"
    },
    "lines": [
      {
        "object": "purchase_invoice_line",
        "description": "Material oficina comanda Q1",
        "quantity": 1,
        "unit_price": 350,
        "tax_rate": 21,
        "retention_rate": 0,
        "subtotal": 350,
        "taxes": 73.5,
        "retention_amount": 0,
        "vat_deductible": true,
        "total": 423.5
      }
    ],
    "metadata": {
      "erp_code": "IVA-GEN",
      "ledger_account": "477000"
    },
    "notes": "Pedido material oficina Q1.",
    "created_at": "2026-01-08T10:00:00Z",
    "updated_at": "2026-01-10T12:00:00Z"
  }
}

{
  "data": {
    "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a07",
    "object": "purchase_invoice",
    "external_invoice_number": "INV-2026-001-DI",
    "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": "paid",
    "issued_on": "2026-01-05",
    "received_on": "2026-04-18",
    "due_on": "2026-02-04",
    "subtotal": 350,
    "taxes_total": 73.5,
    "total_retention": 0,
    "total": 423.5,
    "currency": "EUR",
    "paid_amount": 423.5,
    "pending_amount": 0,
    "payment_status": "paid",
    "paid_at": "2026-01-10",
    "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-Q2",
    "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-suministros-abril-2026.pdf",
      "mime_type": "application/pdf",
      "size_bytes": 241,
      "download_url": "/v1/purchase_invoices/019e822c-555a-709d-99d7-2cfeac9fc920/file"
    },
    "lines": [
      {
        "object": "purchase_invoice_line",
        "description": "Material oficina comanda Q1",
        "quantity": 1,
        "unit_price": 350,
        "tax_rate": 21,
        "retention_rate": 0,
        "subtotal": 350,
        "taxes": 73.5,
        "retention_amount": 0,
        "vat_deductible": true,
        "total": 423.5
      }
    ],
    "metadata": {
      "erp_code": "IVA-GEN",
      "ledger_account": "477000"
    },
    "notes": "Pedido material oficina Q1.",
    "created_at": "2026-01-08T10:00:00Z",
    "updated_at": "2026-01-10T12:00:00Z"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "No se ha proporcionado una API key válida en el header Authorization.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#missing_api_key",
    "request_id": "req_01HKQS5N8VR7QXJ9K3T6BWPMZA"
  }
}

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "Esta API key no tiene el scope requerido para esta operación.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
    "request_id": "req_01HKQS5NBC3P8M1KX4V7SLNHQD"
  }
}

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_key_reused",
    "message": "La cabecera `Idempotency-Key` ya se usó con un body distinto. Usa una clave nueva o reenvía exactamente el mismo body.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#idempotency_key_reused",
    "request_id": "req_01HKQS5NHT9A4U7R2E3F8GZWTJ"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "El campo `name` es obligatorio y no puede estar vacío.",
    "param": "name",
    "doc_url": "https://docs.factuarea.com/guides/errors#parameter_invalid",
    "request_id": "req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Has excedido el rate limit de 60 peticiones por minuto. Reintenta tras 30 segundos.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#rate_limit_exceeded",
    "request_id": "req_01HKQS5NKW1C6W9T4G5H0JBZVL"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Ha ocurrido un error inesperado. Si persiste, contacta con soporte adjuntando el request_id.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#internal_error",
    "request_id": "req_01HKQS5NLX2D7X0U5H6J1KCAWM"
  }
}

Crea una factura de compra

Authorization

Paràmetres de capçalera

Cos de la petició

Cos de la resposta

200application/json

201application/json

401application/json

403application/json

409application/json

422application/json

429application/json

500application/json

Falta l'API key

Format d'API key no vàlid

API key revocada

L'API key no té el scope requerit

Cal millorar el pla

L'add-on requerit no està actiu

Idempotency key reutilitzada amb un body diferent

Conflicte genèric de recurs

El paràmetre no ha superat la validació

Límit del pla assolit (autorització)

Format d'Idempotency-Key no vàlid

Modelo 303 sense trimestre

Modelo 347 amb trimestre

Any fora de rang

No hi ha factures en el període

Format no vàlid

No hi ha formatador disponible per a la combinació de tipus/format/any

Imatge de signatura massa gran (>2MB)

Transició d'estat de document no vàlida

Factura ja pagada

Pressupost ja acceptat

Límit de peticions superat

Massa errors d'autenticació (bloqueig temporal)

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`