API de contactos
Gestiona una sola identidad con roles acumulables de cliente, proveedor y lead. La API canónica ya cubre creación y archivado en lote, búsqueda por identificadores, verificación censal AEAT, estadísticas, actividad e importaciones.
La API pública ya expone la superficie completa de contactos. Un contacto conserva la identidad común y puede tener a la vez los roles customer, supplier y lead. Así se evitan identidades duplicadas sin mezclar las preferencias de venta y compra.
Operaciones públicas de contactos
| Necesidad | Operación de contactos |
|---|---|
| Listar clientes o proveedores | GET /v1/contacts con el filtro roles |
| Buscar clientes o proveedores | GET /v1/contacts/search con el filtro roles |
| Buscar por NIF o external ID | POST /v1/contacts/find-by-tax-id o POST /v1/contacts/find-by-external-id |
| Estadísticas de clientes o proveedores | GET /v1/contacts/stats, con identidades únicas y contadores por rol |
| Actividad de clientes o proveedores | GET /v1/contacts/{contact}/activities, filtrable por dirección y categoría |
| Descargar una plantilla de importación | GET /v1/contacts/import/template |
| Crear varios registros | POST /v1/contacts/bulk-create, con dry_run opcional |
| Eliminar varios registros | POST /v1/contacts/bulk-delete (elimina) o POST /v1/contacts/bulk/archive (archiva) |
| Verificar una identidad española con la AEAT | POST /v1/contacts/census-verification |
| Activar o desactivar proveedores | PUT /v1/contacts/{contact}/roles/{role}/status o POST /v1/contacts/bulk/status |
/v1/contacts es el único recurso público para clientes, proveedores y leads fiscales. Las superficies previas al lanzamiento /v1/clients y /v1/suppliers se han retirado antes de que existan integraciones externas dependientes de ellas.
POST /v1/contacts/import acepta archivos CSV, TXT, XLSX o XLS de hasta 10 MB y como máximo tres target_roles distintos; usa antes el endpoint de previsualización y espera un 202 cuando una importación grande se encola. La operación de creación incluye un ejemplo listo para usar de una empresa con roles de cliente y proveedor.
Scopes
Las lecturas usan contacts:read, las modificaciones contacts:write y las bajas —archivado, eliminación y retirada de roles— contacts:delete. Las mismas operaciones JSON están disponibles como herramientas MCP; la plantilla CSV sigue siendo una descarga REST.