Substituir un producte canviant la seva unitat base

Substitueix un producte per un de NOU amb una unitat base diferent i respon 201 amb el producte nou, el replaces del qual apunta a l'antic.

L'estoc, les presentacions que conservis, les variants, les ofertes de proveïdor, les entrades de tarifa i els components de pack es converteixen i passen al producte nou; l'antic es desactiva, conserva tot el seu historial, el seu replaced_by apunta al nou i mai no es pot reactivar.
És IRREVERSIBLE: no hi ha operació inversa, així que Idempotency-Key és obligatòria i reintentar amb la mateixa clau retorna la mateixa resposta sense crear un segon producte.
El cos és el de la vista prèvia més l'impact_token obligatori d'una vista prèvia vigent amb la mateixa petició.
No consumeix quota del pla: el producte antic deixa de comptar i l'ús net és zero.
Quan la conversió perd precisió o no hi ha equivalència, cal confirmar base_price (422 base_unit_replacement_price_confirmation_required).
Rebuigs: 422 business_rule_violation amb subcodi product_already_replaced, base_unit_replacement_conversion_unavailable o base_unit_replacement_blocked_by_packs; 422 parameter_invalid_value amb subcodi base_unit_replacement_same_unit (el destí ja és la unitat base del producte), base_unit_replacement_equivalence_invalid, base_unit_replacement_price_confirmation_required, base_unit_replacement_preview_stale o base_unit_replacement_decision_invalid.
L'esdeveniment product.replaced es publica amb el producte nou com a objecte.
Un producte d'una altra empresa retorna 404 product_not_found.

Clau opaca generada pel client (fins a 255 caràcters; es recomana UUID v7) que permet reintents segurs: la primera resposta s'emmagatzema i es reprodueix en les repeticions sense tornar a executar la mutació. Reutilitzar una clau amb un cos diferent retorna 409 idempotency_key_reused. Consulta la guia d'idempotència. Obligatòria en aquesta operació: repetir-la produeix un efecte irreversible (un correu enviat, un fitxer generat, una crida a un tercer o un càrrec), per la qual cosa una petició sense aquesta capçalera es rebutja amb 422 idempotency_key_required abans d'executar lògica de negoci.

Longitud1 <= length <= 255

Factuarea-Version?string

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

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

equivalence?|

Rangvalue <= 1000000000000

base_price?|

Rang0 <= value <= 99999999.99

presentations?array<>

Elementsitems <= 500

impact_token*string

Coincidència^[0-9a-fA-F]+$

Longitud64 <= length <= 64

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

Exemple de resposta

{
  "data": {
    "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c01",
    "object": "product",
    "name": "Jamón ibérico al corte",
    "sku": "JAMON-IBERICO-G",
    "price": "0.04",
    "currency": "EUR",
    "tax_rate": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f",
      "rate": 21
    },
    "stock": "5000.0000",
    "item_kind": "product",
    "base_unit": "GRM",
    "gross_weight_kg": null,
    "manage_stock": true,
    "gallery": [],
    "video": null,
    "is_active": true,
    "description": "Jamón ibérico cortado a mano, vendido por gramos.",
    "tags": [],
    "low_stock_threshold": null,
    "presentation_count": 1,
    "variant_count": 0,
    "supplier_offer_count": 0,
    "option_group_count": 0,
    "configuration_count": 0,
    "catalog_availability_mode": "open",
    "preferred_supplier_offer_id": null,
    "presentations": [
      {
        "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b31",
        "object": "product_presentation",
        "product_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c01",
        "name": "Pieza entera",
        "mode": "fixed",
        "unit": "XPK",
        "conversion_factor": "7500.000000",
        "nominal_base_quantity": "7500.0000",
        "barcode": null,
        "commercial_price_override": "285.0000",
        "gross_weight_kg": null,
        "specifications": {},
        "active": true
      }
    ],
    "variants": [],
    "supplier_offers": [],
    "option_groups": [],
    "configurations": [],
    "is_low_stock": false,
    "is_in_stock": true,
    "specifications": {},
    "metadata": {},
    "external_id": null,
    "created_at": "2026-10-15T09:30:00Z",
    "updated_at": "2026-10-15T09:30:00Z",
    "base_unit_change": {
      "mode": "direct",
      "blockers": []
    },
    "replaces": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10",
      "name": "Jamón ibérico al corte",
      "base_unit": "KGM",
      "replaced_at": "2026-10-15T09:30:00Z",
      "equivalence": "0.001000",
      "stock_transferred": "5000.0000"
    },
    "replaced_by": null
  }
}

{
  "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 vista previa ya no corresponde al estado actual del producto o a esta petición, así que no se ha cambiado nada. Vuelve a solicitar la vista previa y confirma de nuevo.",
    "param": "impact_token",
    "subcode": "base_unit_replacement_preview_stale",
    "doc_url": "https://docs.factuarea.com/guides/errors#parameter_invalid_value",
    "request_id": "req_909185bad8ac80000000000000"
  }
}

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

Substituir un producte canviant la seva 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`

Substituir un producte canviant la seva unitat base

Authorization

Paràmetres de ruta

Headers

Cos de la petició

Cos de la resposta

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