Previsualizar el impacto de restringir un catálogo

Compute what would be lost if the commercial combinations of a product were replaced by the proposed ones, and mint the impact_token that confirms THAT exact change.

It is a READ and persists nothing — asking twice over the same catalog returns the same token — but it requires products:write, because the only thing its answer does is authorise a destructive write.
Send configurations as the COMPLETE list of combinations that would remain ACTIVE (an empty list means "retire the allow-list", which returns the product to the cartesian cross), plus variant_ids/presentation_ids enumerating what SURVIVES on each axis — omitting a key means "that axis is untouched", which is not the same as an empty list.
The answer says whether the change needs confirmation at all (requires_confirmation), which crosses stop being sellable, and which negotiated prices would be retired and from which price lists.
The token is a fingerprint of the current catalog AND of the set of prices at stake, not a credential: if either changes before you confirm, the confirmation is rejected and you ask for a fresh preview.
Send it back as impact_token when emptying configurations on PATCH /v1/products/{id}, or when deleting the variant or presentation whose removal would leave the product with no declared combination.

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.

catalog_availability_mode?string

Valor en"open" | "closed"

configurations*array<>

Elementositems <= 1000

presentation_ids?array<>

Elementositems <= 500

variant_ids?array<>

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/configurations/impact-preview", {  method: "POST",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json","Content-Type":"application/json"} },  body: JSON.stringify({  "configurations": [    {      "variant_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",      "presentation_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",      "option_value_ids": null,      "restricts_availability": true    }  ]}),});if (!response.ok) throw new Error(await response.text());if (response.status !== 204) console.log(await response.json());

Ejemplo de respuesta

{
  "data": {
    "object": "catalog_configuration_impact",
    "product_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09",
    "currently_legacy": true,
    "requires_confirmation": true,
    "representable_cross_count": 2,
    "preserved_cross_count": 1,
    "invalidated_cross_count": 1,
    "invalidated_crosses": [
      {
        "variant_id": null,
        "variant_name": null,
        "presentation_id": null,
        "presentation_name": null,
        "label": "Superior · Garrafa de 15 L"
      }
    ],
    "preserved_crosses": [
      {
        "variant_id": null,
        "variant_name": null,
        "presentation_id": null,
        "presentation_name": null,
        "label": "Superior · Garrafa de 5 L"
      }
    ],
    "impact_token": null,
    "retired_price_count": 1,
    "affected_price_list_count": 1,
    "affected_price_list_names": [
      "Tarifa hostelería 2026"
    ]
  }
}

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

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

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

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_param_value",
    "message": "El campo configurations es obligatorio.",
    "param": "configurations",
    "errors": [
      {
        "param": "configurations",
        "code": "parameter_missing",
        "message": "El campo configurations es obligatorio."
      }
    ],
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_param_value",
    "request_id": "req_a7f12b77fbfbbd66470c2c8ea3"
  }
}

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

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

Previsualizar el impacto de restringir un catálogo

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`

Previsualizar el impacto de restringir un catálogo

Authorization

Parámetros de ruta

Headers

Cuerpo de la petición

Cuerpo de la respuesta

200application/json

401application/json

403application/json

404application/json

422application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`