Contactes unificats

Disponibilitat i identitat

Fes servir /v1/contacts per a les integracions noves. Un contacte pot ser client i proveïdor sense duplicar la seva identitat fiscal. L’accés continua limitat per l’empresa autenticada i els scopes contacts:* de la clau; els rols no substitueixen els permisos d’usuari.

Un contacte té una identitat fiscal i un UUID opac a id. Els seus roles acumulables són customer, supplier i lead, cadascun amb estat active o inactive. El lead fiscal exigeix NIF vàlid o identificació fiscal alternativa; la captació prefiscal i les oportunitats CRM són funcionalitats futures independents. Assigna customer al contacte existent en convertir-lo en client, sense duplicar-lo. Els rols no concedeixen permisos d’usuari.

Crear un contacte client o proveïdor

Fes servir name, kind i un array explícit roles. Les escriptures reben noms de rol; les lectures retornen objectes de rol amb estat i dates. Reutilitza el mateix id per a tots els seus rols.

curl -X POST https://api.factuarea.com/v1/contacts \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Distribuciones Ejemplo SL","kind":"company","tax_id":"B12345674","roles":["customer","supplier"]}'

Consulta i filtres

Fes servir GET /v1/contacts amb search per nom, NIF, email, telèfon/mòbil o referència externa. Fes servir roles, role_match, role_status, kind, country_code, province, city, tags, has_email, has_phone i dates d’alta per als filtres estructurats. La paginació utilitza limit i starting_after; consulta has_more abans de continuar.

Consulta GET /v1/contacts/options per obtenir els valors disponibles. field=country retorna el catàleg de països; country_code, province, city i tag retornen valors presents als contactes d’aquella empresa. Els països utilitzen codis ISO alpha-2. Província i ciutat filtren per coincidència exacta. Les etiquetes es normalitzen i pertanyen a cada empresa.

Escriptura sense perdre configuració

Crea amb POST /v1/contacts, incloent-hi un array explícit de rols (pot estar buit). Actualitza la identitat comuna separadament de les transicions de rol, els perfils de client/proveïdor i els comptes bancaris. Conserva tots dos perfils als contactes duals. La tarifa predeterminada és a customer_profile.default_price_list_uuid; els valors de compra pertanyen al perfil de proveïdor. Fes servir UUID, mai IDs numèrics interns.

Arxivar no elimina l’historial fiscal. Desactivar conserva les associacions documentals i impedeix seleccionar aquell rol per a operacions noves. No pots retirar un rol amb referències; desactiva’l. Respecta els requisits de scope i idempotència de cada operació a la referència API.

Documents, recurrents i automatitzacions

Factures de venda, pressupostos, albarans i proformes resolen la identitat de client. Factures de compra, ofertes/productes del proveïdor i contractes resolen la identitat de proveïdor. Conserva les associacions històriques en desactivar rols. Les programacions recurrents són independents de les factures emeses: no són ingressos facturats, i les factures generades han de continuar vinculades al contacte canònic. Les programacions existents i les associacions documentals històriques conserven el vincle durant la migració.

L’API pública exposa únicament /v1/contacts per a les identitats de tercers. Desa l’UUID que retorna aquesta API i conserva els snapshots documentals històrics. Subscriu-te explícitament als esdeveniments de contactes i deduplica els lliuraments per la identitat de l’esdeveniment.

SDKs, CLI i tools

L’SDK exposa el recurs contacts; la CLI, les ordres contacts. MCP exposa les mateixes operacions amb scopes contacts:read, contacts:write o contacts:delete. Comprova que la versió instal·lada els inclou abans de migrar. L’assistent conversacional consulta contactes canònics i obre la seva UI per escriure; no inventa un pipeline CRM.

Gestionar rols, perfils, arxivat i eliminació

Assigna rols amb POST /v1/contacts/{contact}/roles/{role}. Canvia’n l’estat amb PUT /v1/contacts/{contact}/roles/{role}/status; inclou role i status al body. Retira només rols sense referències amb DELETE /v1/contacts/{contact}/roles/{role}.

Actualitza la identitat comuna amb PUT /v1/contacts/{contact}. Modifica valors predeterminats mitjançant /customer-profile o /supplier-profile, i comptes bancaris mitjançant /bank-accounts; són operacions PUT. Els rols inactius i els contactes arxivats conserven l’historial.

POST /v1/contacts/{contact}/archive arxiva el contacte i PUT /v1/contacts/{contact}/restore el desarxiva; arxivar està sempre permès, fins i tot si el contacte té factures, contractes o ofertes de proveïdor. DELETE /v1/contacts/{contact} és una altra operació: un esborrat lògic que retira el contacte de totes les superfícies de lectura i no es pot desfer des de l’API, mentre els seus documents es mantenen intactes. Fes servir l’is_archived retornat per oferir l’acció correcta; arxivat i estat del rol són estats diferents. Llista els arxivats amb GET /v1/contacts?is_archived=1.

Identificadors als documents

El contracte documental conserva els camps direccionals client_id i supplier_id. Envia l’id del contacte canònic amb rol customer o supplier actiu, respectivament. No reanomenis aquests camps a contact_id. El servidor resol la projecció direccional dins de l’empresa autenticada.

Importació

Fes servir la previsualització d’importació per revisar rols, conflictes d’identitat i mapeigs abans d’importar. Fes servir POST /v1/contacts/census-verification per verificar un parell espanyol de nom i NIF sense crear cap contacte.