Importacions de contactes

Previsualitza abans d’escriure

Envia el fitxer a POST /v1/contacts/import/preview i importa’l després amb POST /v1/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/contacts/import/template (contacts:read), conserva les capçaleres i escriu un contacte per fila de dades. El CSV descarregat fa servir UTF-8 amb BOM i comes. Si converteixes la plantilla a XLSX, conserva 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.

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/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.

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/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.

Operacions relacionades