Tarifes

Les tarifes sobreescriuen preus de venda del catàleg dins d'una empresa. Són tenant-scoped, només EUR i usen preus unitaris amb quatre decimals per mantenir precisió en productes mesurats. Pertanyen al mòdul de pla Productes, però usen scopes propis: price_lists:read i price_lists:write.

Cicle de vida i endpoints

Una tarifa neix active; PUT alterna entre active i inactive. Les inactives continuen llegibles per a històric, però no se seleccionen en clients o documents nous. No es pot eliminar una tarifa assignada a clients o esborranys. Les eliminacions de tarifa i ítem són irreversibles.

curl -X POST https://api.factuarea.com/v1/price-lists \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Idempotency-Key: 01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01" \
  -H "Content-Type: application/json" \
  -d '{"name":"Majorista 2026"}'

El nom és únic dins de l'empresa.

Afegir o reemplaçar un preu

POST /v1/price-lists/{priceList}/items fa upsert. Un destí es pot anomenar de tres formes mútuament excloents:

1. configuració comercial emmagatzemada (configuration_id);
2. selecció normalitzada (selection_signature, 64 caràcters hexadecimals);
3. creuament legacy de producte + variant/presentació opcionals.

{
  "product_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a20",
  "configuration_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a21",
  "unit_price": "79.5000",
  "price_unit": "C62"
}

Envia l'id d'un ítem per actualitzar exactament aquell ítem. Reutilitzar el mateix destí amb un altre id es rebutja. price_unit ha de ser compatible amb el destí. El llistat accepta search sobre els noms visibles de producte, variant, presentació, configuració i valors d'opció, a més de status=active|retired.

Precedència de resolució

Per a una selecció nova el resolver aplica aquest ordre estable:

1. tarifa dirigida a la configuració emmagatzemada;
2. tarifa dirigida a la signatura de selecció;
3. tarifa legacy (variant + presentació, variant, presentació, producte, de més a menys específica);
4. preu comercial final propi de la configuració;
5. preu comercial propi de la presentació;
6. preu propi de la variant per unitat base;
7. preu del producte per unitat base.

Tota entrada de tarifa guanya a qualsevol preu propi del catàleg. Els ajustos d'opció només se sumen si la font guanyadora no els ha absorbit ja.

POST /v1/price-lists/resolve

{
  "price_list_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02",
  "product_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a20",
  "configuration_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a21",
  "selection_signature": "b7293f69a30c36b77f6d5ba27f2bc4f1f68e97e447ab8776bf080531d0a1dcee",
  "option_value_ids": ["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a22"]
}

La resposta identifica origen, unit_price, price_unit, unitat base i snapshot de tarifa. També retorna unit_semantics, source_amount, option_adjustment_total i option_adjustments_absorbed, per detectar si els ajustos d'opció s'han absorbit o sumat. Ometre price_list_id recorre els preus propis del catàleg. Una font per unitat base es converteix una vegada amb una presentació fixa; una font per unitat comercial no es converteix mai.

POST /v1/price-lists/resolve-many resol fins a 100 seleccions completes en una petició de només lectura i pot comparar cada resultat amb current_unit_price. Emparella per index, no per l'ordre de la resposta. Un destí invàlid s'atribueix a targets.<n>.

Destins retirats

Quan una eliminació de catàleg confirmada invalida un destí, la seva entrada de tarifa queda retirada, no redirigida en silenci al preu del producte. Conserva import, motiu/data i snapshot del destí, però s'exclou de la resolució, assignacions i estadístiques.

Fes servir .../{item}/reassign per crear una entrada activa nova dirigida a un destí viu; la retirada queda com a històric immutable. .../{item}/purge esborra definitivament aquest històric i exigeix confirm: true, Idempotency-Key i confirmació irreversible als clients que respecten x-irreversible. No es pot purgar una entrada activa o desconeguda.

Contactes, esborranys i repricing

Configura la tarifa de venda del contacte amb PUT /v1/contacts/{contact}/customer-profile i default_price_list_uuid; els documents de venda nous conserven price_list_id. Factures, pressupostos, proformes, albarans i plantilles recurrents retornen id/nom de tarifa i els camps resolts de cada línia.

Canviar la tarifa d'un esborrany amb línies exigeix reprice_strategy:

Els preus manuals, costos d'oferta de proveïdor i snapshots de packs mai es repricien silenciosament. Els documents emesos/històrics són snapshots immutables i no canvien en editar una tarifa.

Errors i MCP

Ramifica per aquests codis, no pel missatge: price_list_not_found, duplicate_price_list_name, inactive_price_list, invalid_price_list_item i price_list_in_use.

El domini MCP Pricing té 13 tools equivalents: list_price_lists, create_price_list, get_price_list, update_price_list, delete_price_list, get_price_list_options, list_price_list_items, upsert_price_list_item, delete_price_list_item, resolve_catalog_price, resolve_many_catalog_prices, reassign_retired_price_list_item i purge_retired_price_list_item. El consentiment OAuth exposa price_lists.read i price_lists.write, de manera que les 13 tools estan disponibles tant mitjançant OAuth com mitjançant API key, subjectes al mòdul Productes del pla.

Consulta Catàleg de productes, Imports i dates i la Referència de l'API.

Conserva els valors resolts de la línia

Conserva price_unit i les quantitats base i comercials resoltes juntament amb el snapshot del catàleg. additional_description afegeix detall llegible sense seleccionar un altre preu. La vista prèvia de recurrents exposa la factura següent resolta sense desar-la; consulta factures recurrents i l’exemple concret de resposta de l’operació.