Reintentar un escaneo de compra fallido

Inicia el OCR de un escaneo en received o vuelve a encolarlo si está en failed y su error es recuperable.

Requiere expected_version; una versión obsoleta responde 409.
Admite Idempotency-Key.

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

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/retry", {  method: "POST",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json","Content-Type":"application/json","Idempotency-Key":"erp-2026-public-api-v1-purchase_scans-retry"} },  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": 4,
    "source": "api",
    "status": "queued",
    "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": [
      "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": 4,
      "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": false,
    "can_convert": false,
    "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": 4,
      "supplier_id": "019e0000-0000-7000-8000-000000000010",
      "candidates": [],
      "can_create": false,
      "blocked_reason": null
    },
    "conversion_readiness": {
      "can_convert": false,
      "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"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "purchase_scan_source_unavailable",
    "subcode": "source_unavailable",
    "param": "file",
    "message": "El original del escaneo fue purgado o ya no está disponible en el almacenamiento seguro.",
    "doc_url": "https://docs.factuarea.com/errors/purchase_scan_source_unavailable",
    "request_id": "req_scanner_example"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "ocr_company_quota_exceeded",
    "message": "La cuota mensual de lectura de documentos está agotada.",
    "doc_url": "https://docs.factuarea.com/errors/ocr_company_quota_exceeded",
    "request_id": "req_scanner_example"
  }
}

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

{
  "error": {
    "type": "service_unavailable_error",
    "code": "scan_storage_unavailable",
    "message": "El almacenamiento de documentos no está disponible temporalmente.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/errors/scan_storage_unavailable",
    "request_id": "req_scanner_example"
  }
}

Reintentar un escaneo de compra fallido

Authorization

Parámetros de ruta

Headers

Cuerpo de la petición

Cuerpo de la respuesta

202application/json

401application/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`