Vista previa de la sustitución por cambio de unidad base

Calcula, sin escribir nada, qué ocurre cuando un producto se sustituye por otro nuevo con una unidad base distinta, y genera el impact_token que confirma ESE cambio exacto.

La unidad base de un producto con historial (stock, movimientos, presentaciones, ofertas de proveedor o variantes con stock) no se puede editar en el sitio: su base_unit_change.mode es replacement y la forma de cambiarla es sustituir el producto.
Es una LECTURA —pedirla dos veces sobre el mismo catálogo devuelve el mismo token—, pero exige products:write, porque lo único que hace su respuesta es autorizar una escritura irreversible.
Envía target_base_unit (una de las nueve unidades de medida; una unidad de embalaje como XPK o XBX solo puede ser una presentación), equivalence (cuántas unidades de la base ACTUAL equivalen a UNA unidad de la base NUEVA, p. ej. 0.001 al pasar de kg a g porque 1 g = 0.001 kg; obligatoria entre una unidad de recuento y una de medida, en cualquier sentido; se calcula sola dentro de la misma familia de medida; entre dos familias de medida distintas no existe), un base_price opcional para confirmar, y presentations con una decisión keep o retire por cada presentación del producto antiguo (las que omitas reciben la decisión propuesta).
La respuesta lista en items cada elemento del plan, con su before, su after, su group (review, converted o carried) y sus flags (precision_loss, no_equivalence, fraction); items[].ref es el id público del elemento afectado, y null para el propio producto y para las entradas de tarifa y los componentes de pack, que no tienen id público.
pending_documents lista los documentos de venta sin emitir que seguirán apuntando al producto antiguo.
El token es una huella del plan, no una credencial: si el catálogo, las tarifas o los packs cambian antes de confirmar, la confirmación se rechaza con 422 base_unit_replacement_preview_stale y se pide una vista previa nueva.
Un producto de otra empresa devuelve 404 product_not_found.

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.

target_base_unit*string

Unidad base del producto nuevo. Solo se aceptan las nueve unidades de medida: una unidad de embalaje (XPK, XBX…) solo puede ser la unidad de una presentación.

Valor en"C62" | "KGM" | "GRM" | "LTR" | "MLT" | "MTR" | "MTK" | "HUR" | "DAY"

equivalence?|

Unidades de la base ACTUAL que equivalen a UNA unidad de la base NUEVA (al pasar de kg a g, 1 g = 0.001 kg, así que 0.001; de kg a unidades contadas, 1 unidad = 0.5 kg da 0.5). Es obligatoria entre una unidad contada y una unidad de medida; dentro de la misma familia de medida se calcula y entre dos familias de medida distintas no existe.

Formatodecimal-6

Rangovalue <= 1000000000000

base_price?|

Precio base del producto nuevo por su unidad base. Confírmalo cuando la conversión pierde precisión o no hay equivalencia.

Formatodecimal-2

Rango0 <= value <= 99999999.99

presentations?array<>

Decisión por cada presentación del producto que se sustituye. Las presentaciones que omitas reciben la decisión propuesta.

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/products/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01/base_unit_replacement/preview", {  method: "POST",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json","Content-Type":"application/json"} },  body: JSON.stringify({  "target_base_unit": "C62",  "equivalence": 0.25,  "base_price": 3,  "presentations": [    {      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21",      "decision": "keep"    }  ]}),});if (!response.ok) throw new Error(await response.text());if (response.status !== 204) console.log(await response.json());

Ejemplo de respuesta

{
  "data": {
    "object": "base_unit_replacement_preview",
    "product_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10",
    "from_base_unit": "KGM",
    "to_base_unit": "GRM",
    "equivalence": "0.001000",
    "equivalence_calculated": true,
    "price_confirmation_required": true,
    "items": [
      {
        "kind": "stock",
        "group": "converted",
        "ref": null,
        "name": null,
        "before": {
          "quantity": "5.0000",
          "unit_code": "KGM"
        },
        "after": {
          "quantity": "5000.0000",
          "unit_code": "GRM"
        },
        "flags": [],
        "decision": null,
        "proposed_decision": null
      },
      {
        "kind": "base_price",
        "group": "review",
        "ref": null,
        "name": null,
        "before": {
          "price": "38.00",
          "unit_code": "KGM"
        },
        "after": {
          "price": "0.04",
          "unit_code": "GRM"
        },
        "flags": [
          "precision_loss"
        ],
        "decision": null,
        "proposed_decision": null
      },
      {
        "kind": "presentation",
        "group": "review",
        "ref": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21",
        "name": "Pieza entera",
        "before": {
          "unit_code": "XPK",
          "mode": "fixed",
          "conversion_factor": "7.500000",
          "nominal_base_quantity": "7.5000",
          "price": "285.0000"
        },
        "after": {
          "unit_code": "XPK",
          "mode": "fixed",
          "conversion_factor": "7500.000000",
          "nominal_base_quantity": "7500.0000",
          "price": "285.0000"
        },
        "flags": [],
        "decision": "keep",
        "proposed_decision": "keep"
      }
    ],
    "pending_documents": [
      {
        "type": "quote",
        "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8d01",
        "number": "PRE-2026-0007",
        "status": "draft"
      }
    ],
    "impact_token": "9f2c1e7a4b8d03f56a1c92e8d7b4035f6a8e1c27d9b04f3a5c6e8d1b2a7f9034"
  }
}

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

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "Esta operación requiere el scope 'products:write'. Tu API key solo tiene los scopes: ninguno.",
    "doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
    "request_id": "req_54d11474e8a516d8cef78d336d"
  }
}

{
  "error": {
    "type": "not_found_error",
    "code": "product_not_found",
    "message": "Producto no encontrado.",
    "doc_url": "https://docs.factuarea.com/guides/errors#product_not_found",
    "request_id": "req_6cb2f9a0bca3bbd0994f378441"
  }
}

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_key_reused",
    "message": "Esa `Idempotency-Key` ya se usó con un payload distinto. La clave identifica una operación concreta, así que reutilizarla para otra vaciaría de sentido el replay.",
    "doc_url": "https://docs.factuarea.com/guides/errors#idempotency_key_reused",
    "request_id": "req_f663c95ab6217df04ccecfd1ac"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid_value",
    "message": "La equivalencia debe ser un número positivo con hasta 6 decimales.",
    "param": "equivalence",
    "subcode": "base_unit_replacement_equivalence_invalid",
    "doc_url": "https://docs.factuarea.com/guides/errors#parameter_invalid_value",
    "request_id": "req_d47d2a112832d0000000000000"
  }
}

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

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

Vista previa de la sustitución por cambio de unidad base

Authorization

Parámetros de ruta

Headers

Cuerpo de la petición

Cuerpo de la respuesta

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Vista previa de la sustitución por cambio de unidad base

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`