Vista prèvia de la substitució per canvi d'unitat base

Calcula, sense escriure res, què passa quan un producte se substitueix per un altre de nou amb una unitat base diferent, i genera l'impact_token que confirma AQUEST canvi exacte.

La unitat base d'un producte amb historial (estoc, moviments, presentacions, ofertes de proveïdor o variants amb estoc) no es pot editar al lloc: el seu base_unit_change.mode és replacement i la manera de canviar-la és substituir el producte.
És una LECTURA —demanar-la dues vegades sobre el mateix catàleg retorna el mateix token—, però exigeix products:write, perquè l'única cosa que fa la seva resposta és autoritzar una escriptura irreversible.
Envia target_base_unit (una de les nou unitats de mesura; una unitat d'embalatge com XPK o XBX només pot ser una presentació), equivalence (quantes unitats de la base ACTUAL equivalen a UNA unitat de la base NOVA, p. ex. 0.001 en passar de kg a g perquè 1 g = 0.001 kg; obligatòria entre una unitat de recompte i una de mesura, en qualsevol sentit; es calcula sola dins de la mateixa família de mesura; entre dues famílies de mesura diferents no existeix), un base_price opcional per confirmar, i presentations amb una decisió keep o retire per cada presentació del producte antic (les que ometis reben la decisió proposada).
La resposta llista a items cada element del pla, amb el seu before, el seu after, el seu group (review, converted o carried) i els seus flags (precision_loss, no_equivalence, fraction); items[].ref és l'id públic de l'element afectat, i null per al producte mateix i per a les entrades de tarifa i els components de pack, que no tenen id públic.
pending_documents llista els documents de venda sense emetre que continuaran apuntant al producte antic.
El token és una empremta del pla, no una credencial: si el catàleg, les tarifes o els packs canvien abans de confirmar, la confirmació es rebutja amb 422 base_unit_replacement_preview_stale i es demana una vista prèvia nova.
Un producte d'una altra empresa retorna 404 product_not_found.

Fixa la versió de l'API (YYYY-MM-DD, versionat per data estil Stripe) per a aquesta petició; omet-lo per usar la versió fixada de la clau, o l'última si no n'hi ha cap. Versió no suportada → 400 unsupported_api_version; mal formada → 400 parameter_invalid_format. La versió efectiva es reflecteix a la capçalera de resposta Factuarea-Version. Consulta la guia de Versioning.

Formatdate

X-Active-Profile?string

Opera en nom d'una empresa filla (API key mestra de gestoria): passa el seu id públic (UUID v7) i la petició s'executa contra les dades d'aquella filla sense canviar l'scope, el tier ni l'environment de la clau (omet-lo per usar la pròpia empresa de la clau). UUID no vàlid → 400 parameter_invalid_uuid; id desconegut o no propi → 404 profile_not_found. Consulta la guia d'Acting on behalf.

Formatuuid

Cos de la petició

application/json

Definicions de TypeScript

Usa el tipus request body a TypeScript.

target_base_unit*string

Unitat base del producte nou. Només s'accepten les nou unitats de mesura: una unitat d'embalatge (XPK, XBX…) només pot ser la unitat d'una presentació.

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

equivalence?|

Unitats de la base ACTUAL que equivalen a UNA unitat de la base NOVA (en passar de kg a g, 1 g = 0.001 kg, així que 0.001; de kg a unitats comptades, 1 unitat = 0.5 kg dóna 0.5). És obligatòria entre una unitat comptada i una unitat de mesura; dins de la mateixa família de mesura es calcula i entre dues famílies de mesura diferents no n'hi ha.

Formatdecimal-6

Rangvalue <= 1000000000000

base_price?|

Preu base del producte nou per la seva unitat base. Confirma'l quan la conversió perd precisió o no hi ha equivalència.

Formatdecimal-2

Rang0 <= value <= 99999999.99

presentations?array<>

Decisió per cada presentació del producte que se substitueix. Les presentacions que ometis reben la decisió proposada.

Elementsitems <= 500

Cos de la resposta

`application/json`

Exemple de petició

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());

Exemple de resposta

{
  "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 prèvia de la substitució per canvi d'unitat base

Authorization

Paràmetres de ruta

Headers

Cos de la petició

Cos de la resposta

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Vista prèvia de la substitució per canvi d'unitat base

Authorization

Paràmetres de ruta

Headers

Cos de la petició

Cos de la resposta

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`