API de contactes
Gestiona una sola identitat amb rols acumulables de client, proveïdor i lead. L’API canònica ja cobreix creació i arxivament en lot, cerca per identificadors, verificació censal AEAT, estadístiques, activitat i importacions.
L’API pública ja exposa la superfície completa de contactes. Un contacte conserva la identitat comuna i pot tenir alhora els rols customer, supplier i lead. Així s’eviten identitats duplicades sense barrejar les preferències de venda i compra.
Operacions públiques de contactes
| Necessitat | Operació de contactes |
|---|---|
| Llistar clients o proveïdors | GET /v1/contacts amb el filtre roles |
| Cercar clients o proveïdors | GET /v1/contacts/search amb el filtre roles |
| Cercar per NIF o external ID | POST /v1/contacts/find-by-tax-id o POST /v1/contacts/find-by-external-id |
| Estadístiques de clients o proveïdors | GET /v1/contacts/stats, amb identitats úniques i comptadors per rol |
| Activitat de clients o proveïdors | GET /v1/contacts/{contact}/activities, filtrable per direcció i categoria |
| Descarregar una plantilla d’importació | GET /v1/contacts/import/template |
| Crear diversos registres | POST /v1/contacts/bulk-create, amb dry_run opcional |
| Eliminar diversos registres | POST /v1/contacts/bulk-delete (elimina) o POST /v1/contacts/bulk/archive (arxiva) |
| Verificar una identitat espanyola amb l’AEAT | POST /v1/contacts/census-verification |
| Activar o desactivar proveïdors | PUT /v1/contacts/{contact}/roles/{role}/status o POST /v1/contacts/bulk/status |
/v1/contacts és l’únic recurs públic per a clients, proveïdors i leads fiscals. Les superfícies prèvies al llançament /v1/clients i /v1/suppliers s’han retirat abans que hi hagi integracions externes que en depenguin.
POST /v1/contacts/import accepta fitxers CSV, TXT, XLSX o XLS de fins a 10 MB i com a màxim tres target_roles diferents; fes servir abans l’endpoint de previsualització i espera un 202 quan una importació gran s’encua. L’operació de creació inclou un exemple llest per usar d’una empresa amb rols de client i proveïdor.
Scopes
Les lectures utilitzen contacts:read, les modificacions contacts:write i les baixes —arxivament, eliminació i retirada de rols— contacts:delete. Les mateixes operacions JSON estan disponibles com a eines MCP; la plantilla CSV continua sent una descàrrega REST.