Clientes del CRM

Con /external/v1/clients tu aplicación lee y mantiene las fichas de cliente del CRM de UTILIA OS de forma controlada y auditada: para facturar desde fuera, sincronizar el CRM en los dos sentidos o dar soporte con los datos de cada cliente a mano.

Autenticación

Todas las peticiones llevan la clave de API de la aplicación:

X-Api-Key: <api_key_de_la_app>

Además del permiso de la API, el plan de tu organización tiene que incluir el aplicativo CRM; si no, la respuesta es 403 MODULE_NOT_ENABLED. Lo que toca a los grupos de empresas necesita además que el plan incluya Grupos empresariales: la consulta del grupo de un cliente (GET /external/v1/clients/:id/group) y cualquier PATCH /external/v1/clients/:id que lleve parentClientId. Sin eso, esas peticiones responden 403 CAPABILITY_NOT_ENABLED y el resto sigue funcionando, incluido un PATCH sin ese campo.

Permisos de la API (scopes)

Conceder crm:clients:read:fiscal-data o crm:clients:read:notes exige el rol de Super Administrador y un motivo de al menos 20 caracteres, que queda en el registro de auditoría.

Endpoints

source en la desactivación es obligatorio y admite external_app, crm_sync, manual o automation.

Forma de las respuestas:

• Listados: { data, pagination }.
• Cambios (alta, actualización, desactivación, reactivación): { client, changed, recordedAt }.
• Sincronización: { data, nextCursor, hasMore }.

Filtros del listado

GET /external/v1/clients admite page, limit (25 por defecto), status, type y size (listas de valores), industry, country, updatedSince (fecha ISO 8601), sortBy (updatedAt, createdAt o name; por defecto updatedAt) y sortOrder (asc o desc; por defecto desc).

Sincronizar por cambios

GET /external/v1/clients/sync trae solo lo que ha cambiado, de lo más antiguo a lo más reciente, en páginas de hasta 200 clientes (100 por defecto). Sirve igual para contactos y leads, cada uno con su ruta.

Grupos de empresas: matriz y filiales

El CRM permite agrupar empresas de tu organización bajo una empresa matriz, con dos niveles: matriz y filiales, sin más niveles por debajo. La API externa refleja esa jerarquía así:

• parentClientId viaja en todas las respuestas: listados, búsqueda, sincronización y detalle. Cuando el vínculo cambia, el updatedAt de la filial se actualiza y la fila vuelve a salir en GET /external/v1/clients/sync.
• parent { id, name, slug } solo aparece en las respuestas de detalle (GET /external/v1/clients/:id, /by-tax-id, /by-slug y las de cambios).
• GET /external/v1/clients/:id/group devuelve hierarchyRole (PARENT, SUBSIDIARY o STANDALONE), la referencia a la matriz, las filiales con la misma forma que el listado (sin taxId ni notes) y totalSubsidiaries. La clave de API trabaja a nivel de organización, así que lista todas las filiales. No expone datos financieros por filial.
• PATCH /external/v1/clients/:id con parentClientId vincula el cliente como filial de la matriz indicada, o lo desvincula con null. Pedir el vínculo que ya existe no cambia nada (changed: false). Si el plan no incluye Grupos empresariales, la petición responde 403 CAPABILITY_NOT_ENABLED aunque el vínculo pedido sea el vigente: quita parentClientId del cuerpo para seguir actualizando el resto.

La API valida las reglas del grupo:

• La matriz tiene que ser de tipo EMPRESA y no puede ser filial de otro grupo.
• La filial no puede ser PARTICULAR, no puede pertenecer ya a otro grupo (para moverla, desvincúlala y vincúlala de nuevo) ni tener filiales propias.

Vincular o desvincular una filial emite los avisos CLIENT_LINKED_TO_GROUP y CLIENT_UNLINKED_FROM_GROUP, solo con identificadores, y no emite CLIENT_UPDATED. Si necesitas los datos de los clientes afectados, pide su detalle.

Los campos personalizados del CRM no salen por esta API. Puedes leerlos y escribirlos por MCP: lo explica el apartado «Campos personalizados del CRM» de la referencia MCP.

Ejemplos

# Buscar por NIF o CIF
curl -H "X-Api-Key: $KEY" \
  "https://os.utilia.ai/api/external/v1/clients/by-tax-id?taxId=B12345678"
 
# Detalle con datos fiscales y notas
# (requiere crm:clients:read:fiscal-data y crm:clients:read:notes)
curl -H "X-Api-Key: $KEY" \
  "https://os.utilia.ai/api/external/v1/clients/cli-42?include=fiscalData,notes"
 
# Desactivar
curl -X POST \
  -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"reason":"Cliente sin actividad desde 2025","source":"external_app"}' \
  "https://os.utilia.ai/api/external/v1/clients/cli-42/deactivate"

// SDK JavaScript
const page = await sdk.externalClients.list({ limit: 25 });
 
const client = await sdk.externalClients.get('cli-42', {
  include: ['fiscalData', 'notes'],
});
 
const matched = await sdk.externalClients.byTaxId('B12345678');
 
const contacts = await sdk.externalClients.listContacts('cli-42', { limit: 50 });
 
await sdk.externalClients.deactivate('cli-42', {
  reason: 'Cliente sin actividad desde 2025',
  source: 'external_app',
});
 
// Grupo de empresas
const group = await sdk.externalClients.getGroup('cli-matriz');
 
// Vincular una filial (requiere crm:clients:write:hierarchy
// y que el plan incluya Grupos empresariales)
await sdk.externalClients.update('cli-filial', {
  parentClientId: 'cli-matriz',
});
 
// Desvincular del grupo
await sdk.externalClients.update('cli-filial', { parentClientId: null });

# SDK Python
from utilia_sdk import (
    DeactivateClientInput,
    ExternalClientContactsFilters,
    ExternalClientListFilters,
    UpdateClientInput,
    UtiliaSDK,
)
 
async with UtiliaSDK(base_url="https://os.utilia.ai/api", api_key=KEY) as sdk:
    page = await sdk.external_clients.list(ExternalClientListFilters(limit=25))
 
    client = await sdk.external_clients.get(
        "cli-42",
        include=["fiscalData", "notes"],
    )
 
    matched = await sdk.external_clients.by_tax_id("B12345678")
 
    contacts = await sdk.external_clients.list_contacts(
        "cli-42", ExternalClientContactsFilters(limit=50)
    )
 
    await sdk.external_clients.deactivate(
        "cli-42",
        DeactivateClientInput(
            reason="Cliente sin actividad desde 2025",
            source="external_app",
        ),
    )
 
    # Grupo de empresas
    group = await sdk.external_clients.get_group("cli-matriz")
 
    # Vincular una filial (requiere crm:clients:write:hierarchy
    # y que el plan incluya Grupos empresariales)
    await sdk.external_clients.update(
        "cli-filial",
        UpdateClientInput(parent_client_id="cli-matriz"),
    )
 
    # Desvincular del grupo (None explícito)
    await sdk.external_clients.update(
        "cli-filial",
        UpdateClientInput(parent_client_id=None),
    )

getGroup (get_group en Python) y parentClientId en update están en los SDK desde la versión 2.18.0.

Avisos a tu servidor de cliente

Siete eventos, que se envían a todas las aplicaciones suscritas salvo a la que provocó el cambio. No existe CLIENT_DELETED: la API externa nunca elimina, solo desactiva.

Errores propios de estos endpoints

Límites de uso

El límite general es más estricto que el de contactos y leads (600 por hora) porque hay menos clientes y el dato es más sensible. El de by-tax-id lo es todavía más por tratarse del NIF: dificulta recorrer la base de clientes aunque una clave se filtre.

Decisiones de producto

• No hay DELETE desde fuera: solo /deactivate.
• No se exponen el IBAN ni los datos financieros agregados.
• taxId nunca sale en listados ni en la búsqueda libre.

Siguiente paso

Combina este recurso con los endpoints de leads y los endpoints de contactos para cubrir el recorrido lead, contacto, cliente y factura. El catálogo completo de eventos está en Contenido de los avisos.