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.
Nuevos endpoints26
| Endpoint | Descripción |
|---|---|
GET/v1/contacts | Listar contactos |
POST/v1/contacts | Crear un contacto |
GET/v1/contacts/options | Listar opciones de filtros de contactos |
GET/v1/contacts/stats | Obtener estadísticas de contactos |
GET/v1/contacts/search | Buscar contactos |
POST/v1/contacts/find-by-tax-id | Buscar un contacto por identificador fiscal |
POST/v1/contacts/find-by-external-id | Buscar un contacto por ID externo |
POST/v1/contacts/census-verification | Verificar un contacto contra el censo de la AEAT |
POST/v1/contacts/import/preview | Previsualizar una importación de contactos |
POST/v1/contacts/import | Importar contactos |
GET/v1/contacts/import/template | Descargar la plantilla de importación de contactos |
POST/v1/contacts/bulk/archive | Archivar contactos en lote |
POST/v1/contacts/bulk-delete | Eliminar contactos en lote |
POST/v1/contacts/bulk-create | Crear contactos en lote |
POST/v1/contacts/bulk/status | Cambiar el estado de roles de contactos en lote |
POST/v1/contacts/{contact}/roles/{role} | Asignar un rol de contacto |
PUT/v1/contacts/{contact}/roles/{role}/status | Cambiar el estado de un rol de contacto |
DEL/v1/contacts/{contact}/roles/{role} | Eliminar un rol de contacto |
PUT/v1/contacts/{contact}/customer-profile | Actualizar un perfil de cliente |
PUT/v1/contacts/{contact}/supplier-profile | Actualizar un perfil de proveedor |
PUT/v1/contacts/{contact}/bank-accounts | Sustituir las cuentas bancarias de un contacto |
PUT/v1/contacts/{contact}/restore | Restaurar un contacto archivado |
GET/v1/contacts/{contact}/activities | Listar la actividad del contacto |
GET/v1/contacts/{contact} | Obtener un contacto |
PUT/v1/contacts/{contact} | Actualizar un contacto |
DEL/v1/contacts/{contact} | Eliminar un contacto |