Factuarea API
Pro-forma invoices

Update a proforma

Update a draft proforma. Once converted, the proforma becomes immutable.

PUT
/proformas/{proforma}

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

proforma*string

Header Parameters

Idempotency-Key?string

Unique key generated by the client to ensure idempotency on retries. It lets you safely resend the same request: the first response is cached and returned without re-executing the mutation. It is an opaque string to the server; any unique value of up to 64 characters is valid (UUID v7, UUID v4, ULID, nanoid, etc.). UUID v7 is recommended for consistency with the API identifiers. The same key reused with a different body returns 409 idempotency_key_reused.

Length1 <= length <= 64

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

import { Factuarea } from "@factuarea/sdk";const factuarea = new Factuarea({ apiKey: process.env.FACTUAREA_API_KEY! });const result = await factuarea.proformas.update("01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01", {    // request body — see the schema below  });
{
  "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"
  }
}
GET

List proforma statuses

Returns the closed catalog of proforma statuses with their public `value`, localized `label`, and UI `color`. Use it to populate filters or status pickers instead of hard-coding values.

POST

Bulk delete delivery notes

Delete several delivery notes in a single request. The body takes an `ids` array of `uuid`s. Returns a `bulk_delete_result` with the count of deleted notes and a `failed` list (`id` + Spanish `reason`) for those that could not be deleted (e.g. signed or invoiced). Supports `Idempotency-Key` for safe retries.