Resultats d’importació, reintents de tasques i camps nous
La importació de contactes informa de files actualitzades, avisos i del motiu de cada fila omesa; la de tasques es reintenta sense duplicar; les factures exposen origin; pressupostos i proformes exposen operation_regime.
5 d’octubre de 2026
Aquesta versió canvia el contracte de les operacions d’importació i afegeix camps de lectura a factures, pressupostos i proformes. No hi ha cap operació nova: totes les que apareixen a sota ja existien i se n’ha actualitzat la resposta o el comportament. La llista d’operacions és al final de la pàgina.
Seguiment de la importació de contactes
GET /v1/contacts/imports/{id},
POST /v1/contacts/import i
POST /v1/contacts/import/preview
(i les tools MCP get_contact_import, import_contacts i preview_contacts_import)
informen de més coses sobre el que ha fet una importació.
| Camp | Significat |
|---|---|
updated_count | Files que han actualitzat un contacte existent. added_count ja no les inclou: total_rows = added_count + updated_count + skipped_count + failed_count + unprocessed_count. |
warnings_count | Avisos que ha produït la importació. No forma part d’aquesta suma. |
outcome_kind | changes_applied, nothing_changed, partial o failed. completed no vol dir que res canviï: nothing_changed és una importació que ha acabat sense crear ni actualitzar res, així que no la presentis com un èxit. partial té files aplicades i files fallides; failed té files fallides i cap d’aplicada. |
skip_reasons | Files omeses comptades per reason. |
first_diagnostics | Fins a 20 diagnòstics agrupats (code, field, severity, message, count, first_row). |
outcomes_truncated | true quan outcomes conté les 500 primeres files i la importació en té més. |
reason (per fila) | Per què una fila s’ha omès, ha fallat o ha deixat el contacte sense canvis (already_exists, no_changes, merge_review_required, update_not_allowed, identity_conflict, validation_failed…); null quan la fila s’ha aplicat. |
La vista prèvia i la resposta de la importació síncrona afegeixen els mateixos
updated_count, warnings_count, skip_reasons i reason per fila, a més de
l’acció i el comptador skip: files que no canvien res perquè són idèntiques al
contacte existent (no_changes) o apunten a un contacte arxivat
(update_not_allowed). La vista prèvia també informa de les files
merge_candidate (vegeu merge més avall).
La resposta síncrona de POST /v1/contacts/import (i l’eina import_contacts) porta també outcome_kind, amb els mateixos valors que el recurs de seguiment. És null a la vista prèvia, al dry_run i a les importacions en cua (202), i pren valor quan acaba l’execució.
Què fa conflict_strategy
conflict_strategy decideix què passa quan una fila coincideix amb un contacte
existent per tax_id o external_id:
| Valor | Comportament |
|---|---|
reject (per defecte) | Qualsevol coincidència és un conflicte, tret que la fila només afegeixi un rol que el contacte encara no té. |
update | Aplica els camps que porten valor. Una cel·la buida mai esborra un camp. |
merge | No aplica res i marca la fila per a revisió manual: result=skipped, reason=merge_review_required. |
Una importació mai canvia el tax_id ni l’external_id d’un contacte existent i
mai en reactiva un d’arxivat.
Mapatge i columnes
Un mapatge que apunta a una columna que el fitxer no té es rebutja ara amb
422 mapping_header_not_found i param: mapping. Torna a llegir les capçaleres i
envia un mapatge amb claus idèntiques. El codi és al
catàleg d’errors.
L’importador accepta quatre columnes noves: iban i bic (un compte bancari que
s’afegeix als que el contacte ja té: de cobrament per a un client, de pagament per a
un proveïdor), customer_default_price_list_name (nom d’una tarifa existent, en
lloc del seu UUID) i supplier_default_tax_code (codi d’un impost existent, en lloc
del seu UUID).
Un percentatge de retenció negatiu (customer_retention_rate, supplier_retention_rate; la convenció heretada de client, per exemple -15) es desa en positiu (15) i la fila rep l’avís RETENTION_SIGN_NORMALIZED als diagnòstics.
Plantilla d’importació
GET /v1/contacts/import/template
admet ara format=csv|xlsx. csv és el valor per defecte i retorna un fitxer
UTF-8 amb BOM i només les capçaleres, separades per punt i coma. xlsx retorna un
llibre amb els fulls Dades, Instruccions, Exemples i Valors permesos. La resposta és un adjunt
(plantilla-contactos.csv o plantilla-contactos.xlsx, amb Content-Disposition). Continua
requerint contacts:read i no conté dades de l’empresa.
Reintents de la importació de tasques
POST /v1/projects/{project}/tasks/import
i la tool MCP import_project_tasks ja es poden reintentar sense duplicar tasques:
- Repetir la crida amb la mateixa clau i el mateix document retorna l’informe de la primera crida i no crea res.
- Reutilitzar la clau amb un altre document respon
409idempotency_key_reused. - Una clau nova, o cap clau a MCP, crea una còpia nova de les tasques. A MCP
l’argument
idempotency_keyés opcional; per HTTP la capçaleraIdempotency-Keycontinua sent obligatòria.
L’informe afegeix warnings_total, el nombre d’avisos que ha produït la importació, i
warnings_truncated, true quan se n’han deixat fora alguns. A warnings només es
conserven els 200 primers avisos.
Camps de lectura nous
| Recurs | Camp | Significat |
|---|---|---|
| Factura (v1 i MCP) | origin | native per a una factura emesa a Factuarea, historical_import per a una factura històrica registrada per importació: número literal del fitxer, sense comptador de sèrie i sense registre VeriFactu. |
| Pressupost | reference | Número d’origen del document, per exemple el que tenia en un sistema anterior quan es va importar. null si no està definit. |
| Pressupost i proforma | operation_regime | Règim d’operació d’IVA: general, intracomunitaria, importacion_exportacion o isp. |
El reason d’un moviment d’stock admet també initial.