Guardar la revisión de un escaneo de compra

Guarda las correcciones humanas de un escaneo en needs_review: proveedor, cabecera fiscal, líneas y notas, con cada campo marcado como verificado.

Requiere expected_version; una versión obsoleta responde 409 y hay que recargar la versión más reciente.
Devuelve el escaneo actualizado.
Los datos mal formados devuelven 422 antes de comparar la versión.

Headers

Idempotency-Key?string

Clave estable para esta mutación (16–128 caracteres). Reutilízala solo con el mismo payload; después de editar la revisión, inicia una nueva mutación con otra clave.

Longitud16 <= length <= 128

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.

expected_version*integer

Rango1 <= value

fields?

lines?array<||>

Las ediciones parciales conservan los campos y líneas omitidos. Add omite line_id (lo asigna el servidor); update/remove usan el line_id existente.

Elementositems <= 500

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_scans/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01/review", {  method: "PUT",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json","Content-Type":"application/json","Idempotency-Key":"erp-2026-public-api-v1-purchase_scans-review"} },  body: JSON.stringify({  "expected_version": 1}),});if (!response.ok) throw new Error(await response.text());if (response.status !== 204) console.log(await response.json());

Ejemplo de respuesta

{
  "data": {
    "id": "019e0000-0000-7000-8000-000000000042",
    "version": 3,
    "source": "api",
    "status": "needs_review",
    "original_filename": "factura-proveedor.pdf",
    "mime_type": "application/pdf",
    "page_count": 1,
    "received_at": "2026-09-12T10:30:00Z",
    "uploaded_by": {
      "name": "Administración"
    },
    "supplier_id": "019e0000-0000-7000-8000-000000000010",
    "supplier_name": "Suministros Ejemplo SL",
    "document_number": "PROV-2026-0042",
    "issue_date": "2026-09-12",
    "currency": "EUR",
    "total": "121",
    "issue_count": 0,
    "available_actions": [
      "save_review",
      "convert",
      "archive",
      "download_source"
    ],
    "purchase_invoice_id": null,
    "last_error": null,
    "deferred_until": null,
    "deferred_reason": null,
    "file_revision": 1,
    "extraction_revision": 1,
    "bytes": 48231,
    "updated_at": "2026-09-12T10:30:00Z",
    "preview": {
      "url": null,
      "source_url": "/v1/purchase_scans/019e0000-0000-7000-8000-000000000042/source",
      "page_count": 1
    },
    "review": {
      "version": 3,
      "extraction_revision": 1
    },
    "extraction": {
      "supplier_id": {
        "original": "019e0000-0000-7000-8000-000000000010",
        "value": "019e0000-0000-7000-8000-000000000010",
        "confidence": "0.97",
        "confidence_band": "high",
        "issue_codes": [],
        "source": "ocr",
        "evidence": [],
        "extraction_issues": []
      },
      "supplier_name": {
        "original": "suministros ejemplo sl",
        "value": "Suministros Ejemplo SL",
        "confidence": "0.97",
        "confidence_band": "high",
        "issue_codes": [],
        "source": "ocr",
        "evidence": [],
        "extraction_issues": []
      },
      "supplier_tax_id": {
        "original": "b12345674",
        "value": "B12345674",
        "confidence": "0.97",
        "confidence_band": "high",
        "issue_codes": [],
        "source": "ocr",
        "evidence": [],
        "extraction_issues": []
      },
      "is_simplified": {
        "original": "false",
        "value": false,
        "confidence": "0.97",
        "confidence_band": "high",
        "issue_codes": [],
        "source": "ocr",
        "evidence": [],
        "extraction_issues": []
      },
      "document_number": {
        "original": "prov-2026-0042",
        "value": "PROV-2026-0042",
        "confidence": "0.97",
        "confidence_band": "high",
        "issue_codes": [],
        "source": "ocr",
        "evidence": [],
        "extraction_issues": []
      },
      "issue_date": {
        "original": "2026-09-12",
        "value": "2026-09-12",
        "confidence": "0.97",
        "confidence_band": "high",
        "issue_codes": [],
        "source": "ocr",
        "evidence": [],
        "extraction_issues": []
      },
      "reception_date": {
        "original": "2026-09-12",
        "value": "2026-09-12",
        "confidence": "0.97",
        "confidence_band": "high",
        "issue_codes": [],
        "source": "ocr",
        "evidence": [],
        "extraction_issues": []
      },
      "due_date": {
        "original": "2026-10-12",
        "value": "2026-10-12",
        "confidence": "0.97",
        "confidence_band": "high",
        "issue_codes": [],
        "source": "ocr",
        "evidence": [],
        "extraction_issues": []
      },
      "currency": {
        "original": "eur",
        "value": "EUR",
        "confidence": "0.97",
        "confidence_band": "high",
        "issue_codes": [],
        "source": "ocr",
        "evidence": [],
        "extraction_issues": []
      },
      "payment_method": {
        "original": "bank_transfer",
        "value": "bank_transfer",
        "confidence": "0.97",
        "confidence_band": "high",
        "issue_codes": [],
        "source": "ocr",
        "evidence": [],
        "extraction_issues": []
      },
      "expense_category": {
        "original": null,
        "value": null,
        "confidence": null,
        "confidence_band": "unknown",
        "issue_codes": [],
        "source": "ocr",
        "evidence": [],
        "extraction_issues": []
      },
      "operation_class": {
        "original": "corriente",
        "value": "corriente",
        "confidence": "0.97",
        "confidence_band": "high",
        "issue_codes": [],
        "source": "ocr",
        "evidence": [],
        "extraction_issues": []
      },
      "notes": {
        "original": null,
        "value": null,
        "confidence": null,
        "confidence_band": "unknown",
        "issue_codes": [],
        "source": "ocr",
        "evidence": [],
        "extraction_issues": []
      },
      "issuer_tax_id": {
        "original": "b12345674",
        "value": "B12345674",
        "confidence": "0.97",
        "confidence_band": "high",
        "issue_codes": [],
        "source": "ocr",
        "evidence": [],
        "extraction_issues": []
      },
      "recipient_tax_id": {
        "original": "b87654321",
        "value": "B87654321",
        "confidence": "0.97",
        "confidence_band": "high",
        "issue_codes": [],
        "source": "ocr",
        "evidence": [],
        "extraction_issues": []
      },
      "totals": {
        "subtotal": {
          "original": "100",
          "value": "100",
          "confidence": "0.97",
          "confidence_band": "high",
          "issue_codes": [],
          "source": "ocr",
          "evidence": [],
          "extraction_issues": []
        },
        "tax": {
          "original": "21",
          "value": "21",
          "confidence": "0.97",
          "confidence_band": "high",
          "issue_codes": [],
          "source": "ocr",
          "evidence": [],
          "extraction_issues": []
        },
        "retention": {
          "original": "0",
          "value": "0",
          "confidence": "0.97",
          "confidence_band": "high",
          "issue_codes": [],
          "source": "ocr",
          "evidence": [],
          "extraction_issues": []
        },
        "surcharge": {
          "original": "0",
          "value": "0",
          "confidence": "0.97",
          "confidence_band": "high",
          "issue_codes": [],
          "source": "ocr",
          "evidence": [],
          "extraction_issues": []
        },
        "total": {
          "original": "121",
          "value": "121",
          "confidence": "0.97",
          "confidence_band": "high",
          "issue_codes": [],
          "source": "ocr",
          "evidence": [],
          "extraction_issues": []
        }
      },
      "printed_totals": {
        "subtotal": {
          "original": "100",
          "value": "100",
          "confidence": "0.97",
          "confidence_band": "high",
          "issue_codes": [],
          "source": "ocr",
          "evidence": [],
          "extraction_issues": []
        },
        "tax": {
          "original": "21",
          "value": "21",
          "confidence": "0.97",
          "confidence_band": "high",
          "issue_codes": [],
          "source": "ocr",
          "evidence": [],
          "extraction_issues": []
        },
        "retention": {
          "original": "0",
          "value": "0",
          "confidence": "0.97",
          "confidence_band": "high",
          "issue_codes": [],
          "source": "ocr",
          "evidence": [],
          "extraction_issues": []
        },
        "surcharge": {
          "original": "0",
          "value": "0",
          "confidence": "0.97",
          "confidence_band": "high",
          "issue_codes": [],
          "source": "ocr",
          "evidence": [],
          "extraction_issues": []
        },
        "total": {
          "original": "121",
          "value": "121",
          "confidence": "0.97",
          "confidence_band": "high",
          "issue_codes": [],
          "source": "ocr",
          "evidence": [],
          "extraction_issues": []
        }
      },
      "extraction_confirmed": {
        "original": null,
        "value": null,
        "confidence": null,
        "confidence_band": "unknown",
        "issue_codes": [],
        "source": "system",
        "evidence": [],
        "extraction_issues": []
      },
      "totals_confirmed": {
        "original": null,
        "value": null,
        "confidence": null,
        "confidence_band": "unknown",
        "issue_codes": [],
        "source": "system",
        "evidence": [],
        "extraction_issues": []
      }
    },
    "lines": [
      {
        "line_id": "019e0000-0000-7000-8000-000000000043",
        "fields": {
          "description": {
            "original": "material de oficina",
            "value": "Material de oficina",
            "confidence": "0.97",
            "confidence_band": "high",
            "issue_codes": [],
            "source": "ocr",
            "evidence": [],
            "extraction_issues": []
          },
          "additional_description": {
            "original": null,
            "value": null,
            "confidence": null,
            "confidence_band": "unknown",
            "issue_codes": [],
            "source": "ocr",
            "evidence": [],
            "extraction_issues": []
          },
          "quantity": {
            "original": "1",
            "value": "1",
            "confidence": "0.97",
            "confidence_band": "high",
            "issue_codes": [],
            "source": "ocr",
            "evidence": [],
            "extraction_issues": []
          },
          "unit_price": {
            "original": "100",
            "value": "100",
            "confidence": "0.97",
            "confidence_band": "high",
            "issue_codes": [],
            "source": "ocr",
            "evidence": [],
            "extraction_issues": []
          },
          "discount_rate": {
            "original": "0",
            "value": "0",
            "confidence": "0.97",
            "confidence_band": "high",
            "issue_codes": [],
            "source": "ocr",
            "evidence": [],
            "extraction_issues": []
          },
          "tax_rate": {
            "original": "21",
            "value": "21",
            "confidence": "0.97",
            "confidence_band": "high",
            "issue_codes": [],
            "source": "ocr",
            "evidence": [],
            "extraction_issues": []
          },
          "retention_rate": {
            "original": "0",
            "value": "0",
            "confidence": "0.97",
            "confidence_band": "high",
            "issue_codes": [],
            "source": "ocr",
            "evidence": [],
            "extraction_issues": []
          },
          "surcharge_rate": {
            "original": "0",
            "value": "0",
            "confidence": "0.97",
            "confidence_band": "high",
            "issue_codes": [],
            "source": "ocr",
            "evidence": [],
            "extraction_issues": []
          },
          "vat_deductible": {
            "original": "true",
            "value": true,
            "confidence": "0.97",
            "confidence_band": "high",
            "issue_codes": [],
            "source": "ocr",
            "evidence": [],
            "extraction_issues": []
          },
          "indirect_tax_regime": {
            "original": "iva",
            "value": "IVA",
            "confidence": "0.97",
            "confidence_band": "high",
            "issue_codes": [],
            "source": "ocr",
            "evidence": [],
            "extraction_issues": []
          },
          "exemption_reason": {
            "original": null,
            "value": null,
            "confidence": null,
            "confidence_band": "unknown",
            "issue_codes": [],
            "source": "ocr",
            "evidence": [],
            "extraction_issues": []
          },
          "line_subtotal": {
            "original": "100",
            "value": "100",
            "confidence": "0.97",
            "confidence_band": "high",
            "issue_codes": [],
            "source": "ocr",
            "evidence": [],
            "extraction_issues": []
          },
          "tax_amount": {
            "original": "21",
            "value": "21",
            "confidence": "0.97",
            "confidence_band": "high",
            "issue_codes": [],
            "source": "ocr",
            "evidence": [],
            "extraction_issues": []
          },
          "retention_amount": {
            "original": "0",
            "value": "0",
            "confidence": "0.97",
            "confidence_band": "high",
            "issue_codes": [],
            "source": "ocr",
            "evidence": [],
            "extraction_issues": []
          },
          "surcharge_amount": {
            "original": "0",
            "value": "0",
            "confidence": "0.97",
            "confidence_band": "high",
            "issue_codes": [],
            "source": "ocr",
            "evidence": [],
            "extraction_issues": []
          },
          "line_total": {
            "original": "121",
            "value": "121",
            "confidence": "0.97",
            "confidence_band": "high",
            "issue_codes": [],
            "source": "ocr",
            "evidence": [],
            "extraction_issues": []
          }
        }
      }
    ],
    "issues": [],
    "duplicate": null,
    "attempts": [],
    "attempts_total": 0,
    "audit": [],
    "audit_total": 0,
    "linked_purchase_invoice": null,
    "can_save_review": true,
    "can_convert": true,
    "can_link_existing": false,
    "can_override_duplicate": false,
    "can_retry": false,
    "can_replace_source": false,
    "can_archive": true,
    "can_restore": false,
    "can_download_source": true,
    "can_view_purchase_invoice": false,
    "supplier_resolution": {
      "status": "matched",
      "reason_code": null,
      "scan_version": 3,
      "supplier_id": "019e0000-0000-7000-8000-000000000010",
      "candidates": [],
      "can_create": false,
      "blocked_reason": null
    },
    "conversion_readiness": {
      "can_convert": true,
      "requires_supplier_creation": false,
      "blocking_fields": []
    },
    "source_retained": true,
    "review_fields": {
      "document": [
        "supplier_id",
        "supplier_name",
        "supplier_tax_id",
        "is_simplified",
        "document_number",
        "issue_date",
        "reception_date",
        "due_date",
        "currency",
        "payment_method",
        "expense_category",
        "operation_class",
        "notes",
        "issuer_tax_id",
        "recipient_tax_id",
        "totals_confirmed",
        "extraction_confirmed"
      ],
      "read_only": [
        "detected_document_type"
      ],
      "totals": [
        "subtotal",
        "tax",
        "retention",
        "surcharge",
        "total"
      ],
      "line": [
        "description",
        "additional_description",
        "quantity",
        "unit_price",
        "discount_rate",
        "tax_rate",
        "retention_rate",
        "surcharge_rate",
        "vat_deductible",
        "indirect_tax_regime",
        "exemption_reason",
        "line_subtotal",
        "tax_amount",
        "retention_amount",
        "surcharge_amount",
        "line_total"
      ],
      "exemption_reasons": [
        "E1",
        "E2",
        "E3",
        "E4",
        "E5",
        "E6",
        "N1",
        "N2"
      ],
      "operation_classes": [
        "corriente",
        "bien_inversion",
        "importacion",
        "intracomunitaria",
        "isp"
      ]
    },
    "automation": {
      "rejection_code": null
    }
  }
}

Falta la API key

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

Formato de API key no válido

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "La API key no tiene el formato esperado (debe empezar por fact_live_ o fact_test_).",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_api_key",
    "request_id": "req_01HKQS5N9JTQM7HVTQP3FBN5XB"
  }
}

API key revocada

{
  "error": {
    "type": "authentication_error",
    "code": "api_key_revoked",
    "message": "Esta API key ha sido revocada y ya no es válida.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#api_key_revoked",
    "request_id": "req_01HKQS5NA8K7E2V9YDZWMT6RJC"
  }
}

{
  "error": {
    "type": "authorization_error",
    "code": "forbidden_action",
    "message": "No tienes permiso para realizar esta acción.",
    "doc_url": "https://docs.factuarea.com/errors/forbidden_action",
    "request_id": "req_scanner_example",
    "param": "purchase_scan"
  }
}

Recurso no encontrado

{
  "error": {
    "type": "not_found_error",
    "code": "resource_not_found",
    "message": "El recurso solicitado no existe o pertenece a otra empresa.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#resource_not_found",
    "request_id": "req_01HKQS5NEQ6X1R4N9B0C5DWTPG"
  }
}

No se encontró informe de impuestos para el periodo

{
  "error": {
    "type": "not_found_error",
    "code": "tax_report_not_found",
    "message": "No se ha encontrado ninguna declaración generada para el período indicado.",
    "param": "period",
    "doc_url": "https://docs.factuarea.com/guides/errors#tax_report_not_found",
    "request_id": "req_01HKQS5NTAXRNOTFOUNDPERIOD07"
  }
}

Idempotency key reutilizada con un body distinto

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

El recurso ya existe (con subcode)

{
  "error": {
    "type": "conflict_error",
    "code": "resource_already_exists",
    "subcode": "tax_id_already_exists",
    "message": "Ya existe un cliente con ese CIF/NIF.",
    "param": "tax_id",
    "doc_url": "https://docs.factuarea.com/guides/errors#resource_already_exists",
    "request_id": "req_01HKQS5NKW1C6W9T4G5HAIBZVM"
  }
}

Conflicto genérico de recurso

{
  "error": {
    "type": "conflict_error",
    "code": "resource_conflict",
    "message": "El recurso está en un estado que no permite esta operación.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#resource_conflict",
    "request_id": "req_01HKQS5NKW1C6W9T4G5HAIBZVL"
  }
}

El parámetro no superó la validación

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

Formato de Idempotency-Key no válido

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

Límite de peticiones superado

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

Demasiados fallos de autenticación (bloqueo temporal)

{
  "error": {
    "type": "authentication_error",
    "code": "too_many_auth_failures",
    "message": "Has alcanzado el número máximo de intentos de autenticación fallidos. La API key queda bloqueada temporalmente. Reintenta tras el tiempo indicado en `Retry-After`.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#too_many_auth_failures",
    "request_id": "req_01HKQS5NKW1C6W9T4G5H0JBZVM"
  }
}

Too many concurrent uploads in flight

{
  "error": {
    "type": "rate_limit_error",
    "code": "upload_in_flight_budget_exceeded",
    "message": "Tu empresa tiene demasiadas subidas en curso a la vez: este archivo ocupa 10 MB y el margen simultáneo es de 120 MB. Espera a que terminen las subidas en marcha y vuelve a intentarlo dentro de 45 segundos.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#upload_in_flight_budget_exceeded",
    "request_id": "req_01HKQS5NUPLOADINFLIGHT005"
  }
}

Company-wide rate limit exceeded (all keys combined)

{
  "error": {
    "type": "rate_limit_error",
    "code": "company_rate_limit_exceeded",
    "message": "Tu empresa ha superado su límite conjunto de 900 peticiones por minuto, contando a la vez todas sus credenciales. Es un techo de la empresa, así que repartir el tráfico no lo eleva. Reintenta en 12 segundos, o solicita una ampliación de plan si necesitas más capacidad.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#company_rate_limit_exceeded",
    "request_id": "req_01HKQS5NCOMPANYRATELIMIT06"
  }
}

Company-wide monthly quota exhausted (all keys combined)

{
  "error": {
    "type": "rate_limit_error",
    "code": "company_monthly_quota_exceeded",
    "message": "Tu empresa ha agotado su cuota conjunta de 150000 peticiones de este mes, contando a la vez todas sus credenciales. Es un techo de la empresa, así que repartir el tráfico no lo eleva. El contador se reinicia el día 1 del mes siguiente; solicita una ampliación de plan si necesitas más volumen antes.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#company_monthly_quota_exceeded",
    "request_id": "req_01HKQS5NCOMPANYMONTHLY0007"
  }
}

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

Guardar la revisión de un escaneo de compra

Authorization

Parámetros de ruta

Headers

Cuerpo de la petición

Cuerpo de la respuesta

200application/json

401application/json

403application/json

404application/json

409application/json

422application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`