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.
Nous endpoints26
| Endpoint | Descripció |
|---|---|
GET/v1/contacts | Llistar contactes |
POST/v1/contacts | Crear un contacte |
GET/v1/contacts/options | Llistar opcions dels filtres de contactes |
GET/v1/contacts/stats | Obtenir estadístiques de contactes |
GET/v1/contacts/search | Cercar contactes |
POST/v1/contacts/find-by-tax-id | Cercar un contacte per identificador fiscal |
POST/v1/contacts/find-by-external-id | Cercar un contacte per ID extern |
POST/v1/contacts/census-verification | Verificar un contacte contra el cens de l’AEAT |
POST/v1/contacts/import/preview | Previsualitzar una importació de contactes |
POST/v1/contacts/import | Importar contactes |
GET/v1/contacts/import/template | Descarregar la plantilla d’importació de contactes |
POST/v1/contacts/bulk/archive | Arxivar contactes en lot |
POST/v1/contacts/bulk-delete | Eliminar contactes en lot |
POST/v1/contacts/bulk-create | Crear contactes en lot |
POST/v1/contacts/bulk/status | Canviar l’estat dels rols de contactes en lot |
POST/v1/contacts/{contact}/roles/{role} | Assignar un rol de contacte |
PUT/v1/contacts/{contact}/roles/{role}/status | Canviar l’estat d’un rol de contacte |
DEL/v1/contacts/{contact}/roles/{role} | Eliminar un rol de contacte |
PUT/v1/contacts/{contact}/customer-profile | Actualitzar un perfil de client |
PUT/v1/contacts/{contact}/supplier-profile | Actualitzar un perfil de proveïdor |
PUT/v1/contacts/{contact}/bank-accounts | Substituir els comptes bancaris d’un contacte |
PUT/v1/contacts/{contact}/restore | Restaurar un contacte arxivat |
GET/v1/contacts/{contact}/activities | Llistar l’activitat del contacte |
GET/v1/contacts/{contact} | Obtenir un contacte |
PUT/v1/contacts/{contact} | Actualitzar un contacte |
DEL/v1/contacts/{contact} | Eliminar un contacte |