Importacions de contactes
Previsualitza fitxers de contactes, consulta resultats confirmats per fila i descarrega informes d’errors autoritzats.
Previsualitza abans d’escriure
Envia el fitxer a POST /v1/companies/{company}/contacts/import/preview i importa’l després amb POST /v1/companies/{company}/contacts/import usant un nou Idempotency-Key. Tots dos requereixen contacts:write. HTTP admet CSV, TXT, XLSX i XLS fins a 10 MB; MCP preview_contacts_import i import_contacts admeten CSV base64 fins a 10 MB. Aquesta actualització no afegeix ODS a aquests contractes públics de pujada.
La previsualització conserva les classificacions planificades create, update, add_role, merge_candidate, conflict i invalid. Resol primer els conflictes d’identitat fiscal. Una actualització conserva els camps omesos al fitxer: ometre bank_accounts conserva els comptes i un [] explícit els buida. dry_run=true sempre retorna HTTP 200 sense reservar ni consumir files; import_uuid, el status d’execució i els comptadors són null.
Emplena la plantilla descarregada
Descarrega la plantilla de contactes amb GET /v1/companies/{company}/contacts/import/template (contacts:read), conserva les capçaleres i escriu un contacte per fila de dades. ?format=csv (per defecte) descarrega un CSV UTF-8 amb BOM i només les capçaleres, separades per punt i coma; ?format=xlsx descarrega un llibre amb els fulls Dades, Instruccions, Exemples i Valors permesos. Si converteixes el CSV a XLSX, conserva’n les capçaleres originals. Puja el fitxer emplenat, revisa la correspondència de columnes i previsualitza les files abans d’aplicar la importació.
Una plantilla que només conté capçaleres és vàlida per previsualitzar: HTTP retorna 200, total=0, rows=[] i source_headers en l’ordre original. Les columnes buides es conserven, també quan un full no té files de dades. dry_run=true es comporta igual i no crea un registre d’importació.
Aplicar un fitxer sense files de dades retorna HTTP 422: error.code=business_rule_violation, error.subcode=empty_import i error.param=file. Emplena la plantilla i torna-ho a provar. No es crea un registre d’importació ni s’encua feina. Les eines MCP conserven la mateixa distinció entre previsualitzar i aplicar; aquests codis d’estat corresponen a HTTP.
Tria una estratègia de conflicte
conflict_strategy decideix què fa una fila quan coincideix amb un contacte existent per tax_id o external_id. reject (per defecte) informa d’un conflicte en qualsevol coincidència, tret que la fila només afegeixi un rol que el contacte 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. Un mapatge que anomena una columna que el fitxer no té retorna 422 mapping_header_not_found.
Un percentatge de retenció negatiu a customer_retention_rate o 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.
Consulta la importació acceptada
Es compten registres CSV lògics, inclosos els registres entre cometes amb salts de línia. HTTP executa fins a 199 registres de manera síncrona amb 200; 200 o més s’accepten amb 202 i queued=true. Tots dos camins retornen import_uuid. Les respostes en cua tenen status=queued i comptadors d’execució null; acceptar no significa que totes les files hagin acabat. MCP retorna el mateix payload JSON; 200/202 són codis del transport HTTP.
Usa GET /v1/companies/{company}/contacts/imports/{id}, passant l’import_uuid rebut com a id. Requereix contacts:read i retorna object=contact_import, entity_type=business_contacts, l’estat persistit, comptadors i outcomes. L’empresa prové de la credencial autenticada. Els UUID d’una altra empresa, inexistents o d’un altre mòdul retornen el mateix 404 import_not_found; sense scope de lectura retorna 403 insufficient_scope.
| Camp | Significat |
|---|---|
total_rows / total | Registres d’origen a GET i a les respostes de preview/síncrones. El payload immediat en cua conserva total=0; consulta el total acceptat amb GET. |
added_count | Files aplicades create i add_role confirmades. |
updated_count | Files aplicades update confirmades. |
warnings_count | Avisos que ha produït la importació; no formen part de la suma de la resta de comptadors. |
outcome_kind | changes_applied, nothing_changed, partial o failed. nothing_changed ha acabat sense crear ni actualitzar res: no la presentis com un èxit. També ve a la resposta síncrona de POST /v1/companies/{company}/contacts/import (i import_contacts); és null a la vista prèvia, al dry_run i a les importacions en cua. |
skip_reasons | Files omeses comptades per reason (no_changes, update_not_allowed, merge_review_required…). |
first_diagnostics / outcomes_truncated | Fins a 20 diagnòstics agrupats; outcomes conté com a màxim 500 files i outcomes_truncated indica si se n’han deixat fora més. |
skipped_count / failed_count | Files omeses o rebutjades confirmades. |
unprocessed_count | Registres d’origen sense un resultat confirmat. |
status / failure_reason | Estat persistit real, inclosos els treballs fallits que conserven progrés parcial. |
Una importació terminal pot tenir status=failed encara que failed_count=0: la infraestructura o el manteniment poden tancar un treball amb escriptures confirmades i files pendents. La resposta síncrona usa aquest mateix estat persistit. El seu total conserva els registres d’origen, però rows i les categories inclouen només files confirmades; cadascuna inclou result com a applied, skipped o failed. Les files de previsualització ometen result.
Per exemple, el manteniment va tancar aquesta importació síncrona després d’una fila confirmada. La fila pendent no es presenta com aplicada:
{
"data": {
"rows": [
{
"row": 2,
"action": "create",
"result": "applied",
"target_uuid": "0198f4d1-a492-7e05-9a35-000000000001",
"errors": [],
"warnings": []
}
],
"source_headers": ["name", "tax_id", "roles"],
"total": 2,
"create": 1,
"update": 0,
"add_role": 0,
"merge_candidate": 0,
"conflict": 0,
"invalid": 0,
"dry_run": false,
"queued": false,
"import_uuid": "0198f4d1-a492-7e05-9a35-000000000201",
"added_count": 1,
"skipped_count": 0,
"failed_count": 0,
"unprocessed_count": 1,
"status": "failed",
"failure_reason": "stale_timeout"
}
}Descarrega els diagnòstics originals
GET /v1/companies/{company}/contacts/imports/{id}/errors.csv requereix contacts:read i retorna bytes CSV UTF-8 amb BOM i les capçaleres row_number,field,code,message. Conserva la coordenada d’origen: CSV usa el número de registre lògic amb capçalera=1; els fulls de càlcul usen l’índex físic de fila. Un informe absent retorna 404 import_not_found.
Els informes estan disponibles per a importacions terminals durant la retenció configurada, 90 dies per defecte. L’estat deixa d’anunciar error_report_url quan venç, fins i tot abans de la neteja física. Si falta el CSV o no es pot llegir, els diagnòstics confirmats el reconstrueixen sense escriure un altre fitxer. Les importacions sense diagnòstics de fila no tenen informe d’errors.
En MCP, usa get_contact_import per consultar el progrés i download_contact_import_errors per rebre id, filename, mime_type, hash i file_base64. Tots dos requereixen contacts:read; els bytes descodificats coincideixen amb HTTP i hash és SHA-256. Les descàrregues requereixen autenticació i no generen URL anònimes.
Quota mensual de files
Les noves admissions de contactes comparteixen la quota mensual de files d’importació del pla. Les files aplicades create, update i add_role la consumeixen; les omeses, rebutjades i pendents no. Les reserves concurrents protegeixen la quota abans d’escriure o posar en cua. Les importacions admeses sota l’exempció anterior de contactes la conserven.
Una quota esgotada retorna HTTP 429 import_row_quota_exceeded, amb tipus d’error rate_limit_error, abans d’escriure contactes o posar en cua. Aquesta quota és independent dels bytes pujats i dels límits de peticions HTTP.