Substituir factures simplificades per factura completa

Agrupa N factures simplificades (F2) sota una única factura completa substitutiva (F3) amb les dades completes del destinatari.

Marca els originals com a substituïts.
Signing certificate (NO VERI*FACTU). Només en aquest mode, un certificat d'empresa absent o no vàlid es rebutja abans de emetre la factura: 422 verifactu_not_eligible, error.subcode: signing_certificate_unavailable; no es consumeix res, així que corregeix-lo i repeteix la crida.

Authorization

AuthorizationBearer <token>

La teva API key com a token Bearer: fact_live_… en producció, fact_test_… en sandbox. Consulta la guia d'autenticació.

A: header

Paràmetres de ruta

company*string

Identificador públic (UUID v7) de l'empresa. Obtén-lo de GET /v1/me (data.scope[].id).

Formatuuid

Clau opaca generada pel client (fins a 255 caràcters; es recomana UUID v7) que permet reintents segurs: la primera resposta s'emmagatzema i es reprodueix en les repeticions sense tornar a executar la mutació. Reutilitzar una clau amb un cos diferent retorna 422 idempotency_key_reused; els valors dels camps secrets (password, secret…) compten com a part del cos, així que reintentar amb un secret corregit sota la mateixa clau és una petició diferent, mai la repetició de la resposta anterior. Consulta la guia d'idempotència. Obligatòria en aquesta operació: repetir-la produeix un efecte irreversible (un correu enviat, un fitxer generat, una crida a un tercer o un càrrec), per la qual cosa una petició sense aquesta capçalera es rebutja amb 422 idempotency_key_required abans d'executar lògica de negoci.

Longitud1 <= length <= 255

Factuarea-Version?string

Fixa la versió de l'API (YYYY-MM-DD, versionat per data estil Stripe) per a aquesta petició; omet-lo per usar la versió fixada de la clau, o l'última si no n'hi ha cap. Versió no suportada → 400 unsupported_api_version; mal formada → 400 parameter_invalid_format. La versió efectiva es reflecteix a la capçalera de resposta Factuarea-Version. Consulta la guia de Versioning.

Formatdate

Cos de la petició

application/json

Definicions de TypeScript

Usa el tipus request body a TypeScript.

client_id*string

Formatuuid

simplified_invoice_ids*array<>

Elements1 <= items

notes?|

Longitudlength <= 2000

pdf_template_id?|

UUID opcional i anul·lable de la plantilla de l'empresa per a la factura substitutiva. Omet-lo per heretar el valor per defecte; un UUID sol·licita una selecció manual compatible. Només té efecte quan la presentació amb revisions està activada per a l'empresa; en cas contrari s'ignora.

Formatuuid

expected_selection_version?string

No s'accepta en aquesta operació: es rebutja amb 422 quan la presentació amb revisions està activada per a l'empresa i s'ignora en cas contrari.

Cos de la resposta

`application/json`

Exemple de petició

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/companies/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01/invoices/substitute-simplified", {  method: "POST",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json","Content-Type":"application/json","Idempotency-Key":"erp-2026-public-api-v1-invoices-substitute_simplified"} },  body: JSON.stringify({  "client_id": "f58fbf7f-333f-499b-affc-c0d396cbd83f",  "simplified_invoice_ids": [    "feb47de0-d6ed-40de-a4d4-8825182f5a6d"  ],  "notes": "Sustitución de facturas simplificadas por factura completa."}),});if (!response.ok) throw new Error(await response.text());if (response.status !== 204) console.log(await response.json());

Exemple de resposta

{
  "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",
        "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",
        "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,
        "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,
        "pack_group": null,
        "id": "019e0000-0000-7000-8000-000000000001",
        "business_references": null,
        "delivery_notes_references": [],
        "sequence_number": 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": "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": null,
    "sent_via": null,
    "is_sent": false,
    "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",
    "business_references": null,
    "invoicing_period": null,
    "legal_literals": [],
    "administrative_snapshot": null,
    "administrative_override": null,
    "administrative_centres": null,
    "administrative_version": 1,
    "administrative_revision_id": null,
    "structured_source_snapshots": [],
    "payment_terms": null,
    "payment_terms_version": 0,
    "payment_terms_source": "none",
    "payment_terms_currency": "EUR",
    "payment_terms_captured_at": null,
    "payment_terms_frozen_at": null,
    "pdf_output_state": {
      "state": null,
      "presentation_id": null,
      "artifact_id": null,
      "format": null,
      "variant": null,
      "unavailable_reason": null,
      "error": null,
      "retry_after": null,
      "download_url": null
    },
    "presentation": null
  }
}

S'ha enviat la capçalera X-Active-Profile retirada

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_unknown",
    "subcode": "retired_active_profile_header",
    "message": "La cabecera 'X-Active-Profile' fue retirada de la API v1: la empresa efectiva se indica en el segmento de empresa de la ruta.",
    "param": "X-Active-Profile",
    "doc_url": "https://docs.factuarea.com/guides/errors#parameter_unknown",
    "request_id": "req_01J8Y3M2Q40000000000000001"
  }
}

Capçalera Factuarea-Version malformada

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid_format",
    "message": "El header 'Factuarea-Version' debe tener formato YYYY-MM-DD.",
    "param": "Factuarea-Version",
    "doc_url": "https://docs.factuarea.com/guides/errors#parameter_invalid_format",
    "request_id": "req_01J8Y3M2Q40000000000000002"
  }
}

Factuarea-Version no admesa

{
  "error": {
    "type": "invalid_request_error",
    "code": "unsupported_api_version",
    "message": "La versión de API '2020-01-01' no está soportada.",
    "param": "Factuarea-Version",
    "doc_url": "https://docs.factuarea.com/guides/errors#unsupported_api_version",
    "request_id": "req_01J8Y3M2Q40000000000000003"
  }
}

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

S’ha assolit el límit anual de documents

{
  "error": {
    "type": "payment_required_error",
    "code": "plan_limit_exceeded",
    "message": "Has alcanzado el límite anual de documentos de tu plan (7/7). El periodo termina el 2027-03-14; amplía el plan para seguir creando documentos ahora.",
    "param": null,
    "details": {
      "resource": "documents_year",
      "current": 7,
      "limit": 7,
      "period_end": "2027-03-14T23:59:59+01:00"
    },
    "doc_url": "https://docs.factuarea.com/guides/errors#plan_limit_exceeded",
    "request_id": "req_01HKQS5NDOCUMENTQUOTA01"
  }
}

No hi ha cap mètode de pagament registrat

{
  "error": {
    "type": "payment_required_error",
    "code": "payment_method_required",
    "message": "La cuenta no tiene un método de pago configurado para cobrar el NIF adicional: configúralo y vuelve a intentarlo.",
    "param": null,
    "details": {
      "payment_setup_url": "https://billing.stripe.com/p/session/live_YWNjdF8xS2ZHM0RLb0h4RXBGV3lY"
    },
    "doc_url": "https://docs.factuarea.com/guides/errors#payment_method_required",
    "request_id": "req_01HKQS5NPAYMENTMETHODREQ01"
  }
}

S'ha rebutjat el càrrec immediat

{
  "error": {
    "type": "payment_required_error",
    "code": "additional_nif_charge_failed",
    "subcode": "additional_nif_charge_failed",
    "message": "No se pudo cobrar el NIF adicional de la cuenta. Detalle: card_declined.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#additional_nif_charge_failed",
    "request_id": "req_01HKQS5NADDNIFCHARGEFAIL02"
  }
}

Aquesta operació requereix millorar el pla

{
  "error": {
    "type": "payment_required_error",
    "code": "addon_required",
    "subcode": "webhooks_addon_required",
    "message": "Tu plan actual no permite crear endpoints de webhook. Contrata un plan que incluya webhooks.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#addon_required",
    "request_id": "req_01HKQS5NADDONREQUIREDWHK03"
  }
}

Quota d'emmagatzematge de l'empresa exhaurida

{
  "error": {
    "type": "payment_required_error",
    "code": "storage_quota_exceeded",
    "message": "Has alcanzado el uso máximo de tu cuenta. Escríbenos a soporte.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#storage_quota_exceeded",
    "request_id": "req_01HKQS5NSTORAGEQUOTAEXC04"
  }
}

POST /v1/companies/{company}/invoices/substitute-simplified · 403 insufficient_scope

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

Empresa desactivada

{
  "error": {
    "type": "authorization_error",
    "code": "company_inactive",
    "message": "Esta empresa está desactivada. Actívala para operar.",
    "param": "company",
    "doc_url": "https://docs.factuarea.com/guides/errors#company_inactive",
    "request_id": "req_01J8Y3M2Q40000000000000005"
  }
}

POST /v1/companies/{company}/invoices/substitute-simplified · 404 invoice_not_found

{
  "error": {
    "type": "not_found_error",
    "code": "invoice_not_found",
    "message": "Factura no encontrada.",
    "param": "invoice_uuid",
    "subcode": "invoice_not_found",
    "doc_url": "https://docs.factuarea.com/guides/errors#invoice_not_found",
    "request_id": "req_4b4c3802ddbc77532bfe0b59c9"
  }
}

Empresa no trobada o fora de l'abast de l'API key

{
  "error": {
    "type": "not_found_error",
    "code": "profile_not_found",
    "message": "La empresa indicada no existe o no está en el ámbito de tu credencial.",
    "param": "company",
    "doc_url": "https://docs.factuarea.com/guides/errors#profile_not_found",
    "request_id": "req_01J8Y3M2Q40000000000000004"
  }
}

La presentació del document ha canviat

{
  "error": {
    "type": "conflict_error",
    "code": "pdf_presentation_conflict",
    "message": "La presentación documental ha cambiado. Actualiza los datos antes de volver a guardar.",
    "param": "expected_version",
    "doc_url": "https://docs.factuarea.com/guides/errors#pdf_presentation_conflict",
    "request_id": "req_01J8Y3M2Q4CF0000000000PPC1"
  }
}

El context de presentació revisat ha canviat

{
  "error": {
    "type": "conflict_error",
    "code": "pdf_presentation_context_changed",
    "message": "El contexto de presentación ha cambiado. Actualiza la vista previa antes de continuar.",
    "param": "expected_preview_context_fingerprint",
    "doc_url": "https://docs.factuarea.com/guides/errors#pdf_presentation_context_changed",
    "request_id": "req_01J8Y3M2Q4CF0000000000PCC1"
  }
}

Les dades legals de la factura han canviat

{
  "error": {
    "type": "conflict_error",
    "code": "pdf_legal_source_changed",
    "message": "Los datos jurídicos de la factura han cambiado. Crea una revisión antes de entregar esta presentación.",
    "param": "presentation_id",
    "doc_url": "https://docs.factuarea.com/guides/errors#pdf_legal_source_changed",
    "request_id": "req_01J8Y3M2Q4CF0000000000PLS1"
  }
}

Reserva concurrent d'identificadors (reintentable)

{
  "error": {
    "type": "conflict_error",
    "code": "resource_conflict",
    "message": "Hay otra operación reservando identificadores sobre 'series' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.",
    "doc_url": "https://docs.factuarea.com/guides/errors#resource_conflict",
    "request_id": "req_01J8Y3M2Q4CF0000000000IDR1"
  }
}

POST /v1/companies/{company}/invoices/substitute-simplified · 422 invalid_param_value

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

POST /v1/companies/{company}/invoices/substitute-simplified · 422 verifactu_not_eligible (signing_certificate_unavailable, param certificate)

{
  "error": {
    "type": "invalid_request_error",
    "code": "verifactu_not_eligible",
    "message": "No se puede emitir: tu empresa está en modo NO VERI*FACTU y no tiene un certificado electrónico vigente para firmar el registro de facturación. Sube uno en Ajustes → Certificado digital y vuelve a emitir la factura.",
    "param": "certificate",
    "subcode": "signing_certificate_unavailable",
    "doc_url": "https://docs.factuarea.com/guides/errors#verifactu_not_eligible",
    "request_id": "req_a296d965719d18a090bc52ee61"
  }
}

POST /v1/companies/{company}/invoices/substitute-simplified · 422 verifactu_not_eligible (signing_certificate_unavailable, param representation)

{
  "error": {
    "type": "invalid_request_error",
    "code": "verifactu_not_eligible",
    "message": "No se puede emitir: tu empresa está en modo NO VERI*FACTU y el registro de facturación debe firmarse con el certificado de Factuarea, pero la representación que lo habilita no está activa. Regístrala en Ajustes → VeriFactu o cambia el modo de remisión a certificado propio y vuelve a emitir la factura.",
    "param": "representation",
    "subcode": "signing_certificate_unavailable",
    "doc_url": "https://docs.factuarea.com/guides/errors#verifactu_not_eligible",
    "request_id": "req_1d6a7d8670b33c4267e30f3e1c"
  }
}

POST /v1/companies/{company}/invoices/substitute-simplified · 422 verifactu_not_eligible (signing_certificate_unavailable, param system_certificate)

{
  "error": {
    "type": "invalid_request_error",
    "code": "verifactu_not_eligible",
    "message": "No se puede emitir: el certificado de Factuarea con el que se firma el registro de facturación de tu empresa no está disponible en este momento. Inténtalo de nuevo en unos minutos; si persiste, contacta con soporte.",
    "param": "system_certificate",
    "subcode": "signing_certificate_unavailable",
    "doc_url": "https://docs.factuarea.com/guides/errors#verifactu_not_eligible",
    "request_id": "req_500848b88455135e22a07ad310"
  }
}

Idempotency key reutilitzada amb un payload diferent

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_key_reused",
    "message": "La Idempotency-Key 'order-2026-0001' ya se usó con un payload distinto.",
    "param": "Idempotency-Key",
    "doc_url": "https://docs.factuarea.com/guides/errors#idempotency_key_reused",
    "request_id": "req_01J8Y3M2Q40000000000000007"
  }
}

Format d'Idempotency-Key no vàlid

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_param_format",
    "message": "La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.",
    "param": "Idempotency-Key",
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_param_format",
    "request_id": "req_01J8Y3M2Q40000000000000008"
  }
}

Falta la Idempotency-Key en una escriptura amb efecte extern

{
  "error": {
    "type": "invalid_request_error",
    "code": "idempotency_key_required",
    "message": "La operación «public-api.v1.invoices.send» exige la cabecera Idempotency-Key desde el 2026-10-01. Envía una clave única por operación (un UUID sirve) y, si reintenta, repite exactamente la misma clave para que la operación no se ejecute dos veces.",
    "param": "Idempotency-Key",
    "doc_url": "https://docs.factuarea.com/guides/errors#idempotency_key_required",
    "request_id": "req_01J8Y3M2Q40000000000000009"
  }
}

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

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

{
  "error": {
    "type": "service_unavailable_error",
    "code": "pdf_engine_unreachable",
    "message": "El motor de generación PDF no está disponible en este momento. Inténtalo de nuevo en unos instantes.",
    "doc_url": "https://docs.factuarea.com/guides/errors#pdf_engine_unreachable",
    "request_id": "req_b05d7f31c8e2946a1f73d0b5e8"
  }
}

Substituir factures simplificades per factura completa

Authorization

Paràmetres de ruta

Headers

Cos de la petició

Cos de la resposta

201application/json

400application/json

401application/json

402application/json

403application/json

404application/json

409application/json

422application/json

429application/json

500application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`