Crea una proforma

Crea una nueva factura proforma en estado `draft`. Las proformas pueden convertirse luego en facturas finales.

Clave única generada por el cliente para garantizar la idempotencia en los reintentos. Te permite reenviar de forma segura la misma petición: la primera respuesta se cachea y se devuelve sin volver a ejecutar la mutación. Es una cadena opaca para el servidor; cualquier valor único de hasta 64 caracteres es válido (UUID v7, UUID v4, ULID, nanoid, etc.). Se recomienda UUID v7 por coherencia con los identificadores de la API. La misma clave reutilizada con un body distinto devuelve 409 idempotency_key_reused.

Longitud1 <= length <= 64

Cuerpo de la petición

application/json

Definiciones de TypeScript

Usa el tipo request body en TypeScript.

client_id*string

Formatouuid

series_id?|

Formatouuid

issued_on*string

Formatodate

valid_until?|

Formatodate

validity_days?|

Rango1 <= value <= 365

notes?|

Longitudlength <= 1000

terms_and_conditions?|

Longitudlength <= 2000

reference?|

Longitudlength <= 255

payment_method?|

Longitudlength <= 100

payment_terms?|

Rango0 <= value <= 365

shipping_cost?|

Rango0 <= value

delivery_terms?|

Longitudlength <= 255

estimated_delivery_date?|

Formatodate

external_id?|

Longitudlength <= 100

currency?|

Valor en"EUR"

metadata?|

Un mapa libre de hasta 50 pares clave→valor para almacenar datos estructurados arbitrarios (los valores son cadenas de hasta 500 caracteres). Esto es DISTINTO de custom_fields: metadata es un mapa clave→valor SIN ORDEN para datos de integración opacos, mientras que custom_fields (en los seis recursos de documento) es una lista ORDENADA de pares tipados {field, value} con semántica de visualización. Un documento puede llevar ambos. Los recursos maestros (Client, Supplier) no tienen custom_fields tipados: usa su metadata como almacén de campos personalizados sin tipar.

Propiedadesproperties <= 50

tags?array<>|

Elementositems <= 30

custom_fields?array<>|

Elementositems <= 50

lines*array<>

Elementos1 <= items

Cuerpo de la respuesta

`application/json`

{
  "data": {
    "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a05",
    "object": "proforma",
    "number": "PRO-2026-00007",
    "series": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e",
      "code": "F-2026"
    },
    "client": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
      "name": "Acme Corporation"
    },
    "status": "draft",
    "issued_on": "2026-01-22",
    "valid_until": "2026-02-21",
    "validity_days": 30,
    "reference": "REF-API-2026-001",
    "converted_to_id": null,
    "converted_invoice_number": "F-2025-003",
    "subtotal": 1500,
    "taxes_total": 315,
    "total_vat": 315,
    "total_retention": 0,
    "total_surcharge": 0,
    "total": 1815,
    "shipping_cost": 15.5,
    "total_with_shipping": 1830.5,
    "currency": "EUR",
    "payment_method": "bank_transfer",
    "payment_terms_days": 30,
    "delivery_terms": "Entrega en 5 dias habiles, portes incluidos",
    "estimated_delivery_date": "2026-06-10",
    "notes": "Proforma pendiente de validación.",
    "terms_and_conditions": "Validez 30 dias. Proforma sin valor fiscal hasta su conversion en factura.",
    "external_id": "ERP-PRO-2026-0007",
    "lines": [
      {
        "object": "proforma_line",
        "description": "Setup inicial",
        "product": {
          "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09",
          "name": "Consultoría hora estándar"
        },
        "quantity": 1,
        "unit_price": 1500,
        "tax_rate": 21,
        "retention_rate": 0,
        "surcharge_rate": 0,
        "discount_percent": 0,
        "subtotal": 1500,
        "taxes": 315,
        "total": 1815
      }
    ],
    "metadata": {
      "erp_code": "IVA-GEN",
      "ledger_account": "477000"
    },
    "tags": [
      "exportacion",
      "pendiente-validar"
    ],
    "custom_fields": [
      {
        "field": "incoterm",
        "value": "EXW"
      }
    ],
    "link_expires_at": "2026-07-01T09:53:23+02:00",
    "link_is_active": true,
    "created_at": "2026-01-22T09:10:00Z",
    "updated_at": "2026-01-22T09:10:00Z"
  }
}

{
  "data": {
    "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a05",
    "object": "proforma",
    "number": "PRO-2026-00007",
    "series": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e",
      "code": "F-2026"
    },
    "client": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
      "name": "Acme Corporation"
    },
    "status": "draft",
    "issued_on": "2026-01-22",
    "valid_until": "2026-02-21",
    "validity_days": 30,
    "reference": "REF-API-2026-001",
    "converted_to_id": null,
    "converted_invoice_number": "F-2025-003",
    "subtotal": 1500,
    "taxes_total": 315,
    "total_vat": 315,
    "total_retention": 0,
    "total_surcharge": 0,
    "total": 1815,
    "shipping_cost": 15.5,
    "total_with_shipping": 1830.5,
    "currency": "EUR",
    "payment_method": "bank_transfer",
    "payment_terms_days": 30,
    "delivery_terms": "Entrega en 5 dias habiles, portes incluidos",
    "estimated_delivery_date": "2026-06-10",
    "notes": "Proforma pendiente de validación.",
    "terms_and_conditions": "Validez 30 dias. Proforma sin valor fiscal hasta su conversion en factura.",
    "external_id": "ERP-PRO-2026-0007",
    "lines": [
      {
        "object": "proforma_line",
        "description": "Setup inicial",
        "product": {
          "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09",
          "name": "Consultoría hora estándar"
        },
        "quantity": 1,
        "unit_price": 1500,
        "tax_rate": 21,
        "retention_rate": 0,
        "surcharge_rate": 0,
        "discount_percent": 0,
        "subtotal": 1500,
        "taxes": 315,
        "total": 1815
      }
    ],
    "metadata": {
      "erp_code": "IVA-GEN",
      "ledger_account": "477000"
    },
    "tags": [
      "exportacion",
      "pendiente-validar"
    ],
    "custom_fields": [
      {
        "field": "incoterm",
        "value": "EXW"
      }
    ],
    "link_expires_at": "2026-07-01T09:53:23+02:00",
    "link_is_active": true,
    "created_at": "2026-01-22T09:10:00Z",
    "updated_at": "2026-01-22T09:10: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"
  }
}

Authorization

Parámetros de cabecera

Cuerpo de la petición

Cuerpo de la respuesta

200application/json

201application/json

401application/json

403application/json

409application/json

422application/json

429application/json

500application/json

Falta la API key

Formato de API key no válido

API key revocada

La API key carece del scope requerido

Se requiere mejorar el plan

El add-on requerido no está activo

Idempotency key reutilizada con un body distinto

Conflicto genérico de recurso

El parámetro no superó la validación

Límite del plan alcanzado (autorización)

Formato de Idempotency-Key no válido

Modelo 303 sin trimestre

Modelo 347 con trimestre

Año fuera de rango

No hay facturas en el periodo

Formato no válido

No hay formateador disponible para la combinación de tipo/formato/año

Imagen de firma demasiado grande (>2MB)

Transición de estado de documento no válida

Factura ya pagada

Presupuesto ya aceptado

Límite de peticiones superado

Demasiados fallos de autenticación (bloqueo temporal)

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`