Usuarios externos

Identifica a las personas de tu aplicación en UTILIA OS con identify y lístalas: es el primer paso de tickets, facturas, tarjetas y suscripciones.

Actualizado el 8 de octubre de 2026. 3 min de lectura

Incluido en todos los planes. Ver precios

El servicio de usuarios da de alta en UTILIA OS a las personas que usan tu aplicación. Todo lo demás cuelga de ellas: sus tickets de soporte, sus facturas, sus tarjetas guardadas, sus autorizaciones de cobro y sus suscripciones. Por eso identify es casi siempre la primera llamada de una integración. Funciona con la clave de tu aplicación externa, siempre desde tu servidor.

Qué cuelga de un usuario identificado

Recibe de

Tu aplicación
Lo crea o lo actualiza con identify, con su NIF y su dirección si los tienes.

Usuario externo

Una persona de tu aplicación, reconocida por su externalId.

Envía a

CRM
Se vincula a una ficha de cliente: la que indiques con clientId o la que UTILIA OS crea o reutiliza la primera vez que le facturas o le cobras.
Tickets de soporte
Sus tickets y conversaciones con el equipo.
Facturas
Las facturas que emites a su nombre, con sus datos fiscales.
Métodos de pago
Las tarjetas que guarda para pagar.
Suscripciones
Sus cuotas y la autorización que permite cobrarlas solas.

Antes de empezar

Método	Para qué	Scope que exige
`users.identify(datos)`	Crear o actualizar un usuario	`crm:users:write`
`users.list(página, límite)`	Listar los usuarios de tu aplicación	`crm:users:read`

Sin el scope, la respuesta es un 403 con errorCode INSUFFICIENT_SCOPE y un mensaje que no dice cuál falta. Antes que el scope se comprueba el plan: sin el aplicativo Integraciones, la respuesta es un 403 MODULE_NOT_ENABLED.

identify exige scope desde septiembre de 2026

Si tu integración llamaba a identify antes de esa fecha, comprueba que la aplicación tiene concedido crm:users:write: sin él, las altas y actualizaciones de usuarios fallan.

Identificar a un usuario

identify funciona como «crear o actualizar»: si ya existe un usuario con ese externalId en tu aplicación, actualiza los campos que mandes; si no, lo crea. Puedes llamarlo cada vez que alguien inicia sesión en tu aplicación para mantener sus datos al día.

JavaScript	Python	Obligatorio	Qué es
`externalId`	`external_id`	Sí	Identificador de la persona en tu sistema, 255 caracteres como máximo.
`email`	`email`	No	Correo. El SDK comprueba el formato.
`name`	`name`	No	Nombre de la persona o razón social.
`avatarUrl`	`avatar_url`	No	Dirección de su imagen, 2048 caracteres como máximo.
`metadata`	`metadata`	No	Datos libres de clave y valor.
`taxId`	`tax_id`	No	NIF o CIF, 50 caracteres como máximo.
`billingAddress`	`billing_address`	No	Dirección de facturación: `street`, `city`, `postalCode` (`postal_code`) y `country` obligatorios; `province` opcional.
`clientId`	`client_id`	No	Ficha de cliente del CRM a la que vincularlo, si tu aplicación la creó antes.

taxId y billingAddress pasan a la ficha de cliente del CRM y a la de la pasarela de pago: son los datos que salen impresos en el PDF de sus facturas. Mándalos en cuanto los tengas, antes de emitir la primera, para no tener que rectificarla después.

Sin clientId, UTILIA OS crea o reutiliza la ficha de cliente por su cuenta la primera vez que le facturas, le guardas una tarjeta o le creas una suscripción. Con clientId, solo acepta fichas que tu propia aplicación creó (con el servicio de clientes de la API externa) y que no estén vinculadas a un usuario de otra aplicación; en cualquier otro caso responde 404 con errorCode CLIENT_NOT_ACCESSIBLE.

const user = await sdk.users.identify({
  externalId: 'usr-4821',
  email: 'laura.garcia@ejemplo.com',
  name: 'Estudio Marea SL',
  taxId: 'B76543210',
  billingAddress: {
    street: 'Avenida de Canarias 12, planta 3',
    city: 'Las Palmas de Gran Canaria',
    postalCode: '35001',
    country: 'España',
    province: 'Las Palmas',
  },
  metadata: { plan: 'premium' },
});
 
console.log(user.id); // identificador interno en UTILIA OS
console.log(user.clientId); // ficha del cliente en el CRM

La respuesta es el usuario (ExternalUser): id, appId (app_id), externalId, email, name, avatarUrl, metadata, clientId, lastSeenAt (fecha de la última actividad) y, cuando el servidor lo incluye, el número de tickets en _count.tickets (count.tickets en Python).

Listar usuarios

list devuelve los usuarios de tu aplicación por páginas. Por defecto, la página 1 con 20 elementos. La respuesta trae data y pagination (page, limit, total y totalPages).

let page = 1;
let totalPages = 1;
do {
  const result = await sdk.users.list(page, 100);
  for (const user of result.data) {
    console.log(`${user.name} (${user.externalId}): ${user._count?.tickets ?? 0} tickets`);
  }
  totalPages = result.pagination.totalPages;
  page++;
} while (page <= totalPages);

Siguiente paso

Con el usuario identificado, usa su externalId en el resto de servicios:

En esta página