Conectar su sistema de facturación o CRM a la API de socios de Uniqkey

Los socios de Uniqkey pueden leer el uso mensual de licencias de todas sus organizaciones cliente mediante una API REST, de modo que un sistema de facturación, CRM o generación de informes puede obtener las cifras directamente, en lugar de que alguien tenga que exportarlas desde el Portal de socios. En este artículo se explica cómo crear una clave de API en el Portal de socios, cómo funciona la API y qué se puede esperar de los datos.

Quién puede usarla

• La API es para socios de Uniqkey. Las claves de API se crean en el Portal de socios mediante un usuario socio con el rol Admin. Los demás roles no ven la página API keys.
• Una clave pertenece a su cuenta de socio, no al usuario que la creó. Sigue funcionando aunque dicho usuario se marche o sea eliminado.
• Una clave puede ver su propia cuenta de socio y los socios que están por debajo de ella en su jerarquía, por lo que un distribuidor también puede ver a los clientes de sus revendedores. Nunca puede ver socios que estén por encima o al mismo nivel que la suya.
• Su sistema necesita acceso HTTPS saliente a https://partner-api-public.production.uniqkey.eu.
• La API es de solo lectura y devuelve cifras de licencias y nombres de organizaciones. Nunca se incluyen datos de bóvedas, contraseñas, claves ni datos de empleados.

Paso 1: Crear una clave de API

1. Inicie sesión en el Portal de socios como Admin.
2. Abra API keys en el menú.
3. Haga clic en Create API key.
4. Introduzca un Name para la integración que utilizará la clave, por ejemplo Billing sync. El nombre aparece en el registro de auditoría de todo lo que haga la clave, así que debe ser reconocible.
5. Opcionalmente, seleccione una Expiry date. La fecha más próxima que puede seleccionar es mañana. La clave funciona hasta el final de ese día en la zona horaria de su navegador. Deje el campo vacío para crear una clave que no caduque.
6. Haga clic en Create. El cuadro de diálogo Copy your API key now muestra la nueva clave, que comienza por uk_p_.
7. Copie la clave y guárdela en el almacén de secretos de su sistema. La clave solo se muestra una vez. Marque I have stored this API key in a safe place para cerrar el cuadro de diálogo. Después de eso, la clave no podrá volver a mostrarse. Si la pierde, cree una nueva.

Gestión posterior de las claves:

• La página API keys muestra todas las claves, con su nombre, los primeros caracteres de la clave (para poder distinguirlas), cuándo se crearon, cuándo caducan, cuándo se utilizaron por última vez y su estado: Active, Expired o Revoked.
• Para revocar una clave, abra el menú de su fila, seleccione Revoke y confirme. La revocación es permanente y no se puede deshacer. La clave deja de funcionar inmediatamente; en casos excepcionales, puede tardar hasta 1 minuto. Las claves revocadas permanecen en la lista con el estado Revoked.
• Last used se actualiza como máximo cada 5 minutos, por lo que una clave que se esté utilizando puede mostrar una hora de hasta 5 minutos de antigüedad.
• La fecha de caducidad no se puede cambiar después de crear la clave. Cuando una clave esté a punto de caducar, cree una nueva.
• Puede crear varias claves, por ejemplo, una por integración, para poder revocar una sin afectar a las demás. Todas las claves de un socio comparten un mismo límite de solicitudes (consulte «Límites de solicitudes»).
• Para rotar una clave: cree una nueva, actualice su sistema, compruebe que Last used muestre que se está utilizando la nueva clave y, después, revoque la anterior.
• La creación y revocación de una clave se registran en Audit logs del Portal de socios, junto con el nombre de la clave. Cada solicitud correcta de datos de licencias realizada con una clave también se registra allí, mostrando el nombre de la clave como actor. Las entradas aparecen en el registro de auditoría del socio propietario de la clave. Las solicitudes rechazadas y las solicitudes a /v1/me no se registran.

Paso 2: Configurar su sistema

Todas las integraciones necesitan lo mismo:

Obtener los datos una vez al día es una buena configuración predeterminada. Las cifras se actualizan mediante una tarea diaria (consulte «Qué se puede esperar de los datos» más abajo), por lo que consultarlas con mayor frecuencia no aporta nada.

La documentación interactiva de la API está disponible en https://partner-api-public.production.uniqkey.eu/docs. La especificación OpenAPI, que la mayoría de las herramientas pueden utilizar para generar un cliente, está disponible en https://partner-api-public.production.uniqkey.eu/openapi/v1.json.

Prueba rápida con curl

Compruebe que la clave funciona y a qué socio pertenece:

curl -s "https://partner-api-public.production.uniqkey.eu/v1/me" \
  -H "Authorization: Bearer <your key>"

A continuación, obtenga las primeras filas de licencias:

curl -s "https://partner-api-public.production.uniqkey.eu/v1/licenses?limit=5" \
  -H "Authorization: Bearer <your key>"

Una configuración correcta devuelve HTTP 200 con un cuerpo JSON como los de la sección «Respuesta». 401 significa que falta el encabezado Authorization, que no es un token Bearer o que la clave es incorrecta, está revocada o ha caducado.

Referencia de la API

Solicitud

GET /v1/licenses

Una solicitud sin parámetros es válida y devuelve todos los meses de todas las organizaciones que la clave puede ver, comenzando por los más recientes, una página cada vez.

El cursor es opaco. No lo cree, analice ni modifique. Su formato puede cambiar sin previo aviso.

GET /v1/me

No acepta parámetros. Devuelve el socio al que pertenece la clave y el nombre, prefijo y caducidad de la propia clave. Utilícelo para probar una clave. Cuenta para el límite de solicitudes como cualquier otra solicitud.

Respuesta

GET /v1/licenses:

{
  "items": [
    {
      "organizationId": "d5ecd732-4a67-418c-9dea-38a097fba1f6",
      "organizationName": "Example Customer ApS",
      "organizationExternalId": "CRM-10442",
      "partnerId": "3f2a9c1e-7b44-4d0a-9e51-2a6c8f0d1b77",
      "partnerName": "Example Reseller A/S",
      "month": "2026-09",
      "usageLicenseCount": 48,
      "committedLicenseCount": 50,
      "discoveryInstallationCount": 12,
      "discoveryActivatedNow": true
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJEIjoiMjAyNi0wOS0wMSIsIk8iOiJkNWVj..."
}

• Las filas se ordenan primero por mes más reciente y después por organizationId.
• hasMore indica si debe solicitar la página siguiente. Repita mientras hasMore sea verdadero.
• nextCursor es null en la última página.

GET /v1/me:

{
  "partnerId": "3f2a9c1e-7b44-4d0a-9e51-2a6c8f0d1b77",
  "partnerName": "Example Reseller A/S",
  "keyName": "Billing sync",
  "keyPrefix": "uk_p_Xa81kQ2z",
  "expiresAt": "2027-03-31T21:59:59.999Z"
}

expiresAt está en UTC y es null para una clave que no caduca.

Los errores utilizan el formato estándar de detalles del problema (Content-Type: application/problem+json) con un code estable y legible por máquinas:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "The request could not be processed.",
  "code": "bad_request",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

Base el control de errores en code y el estado HTTP. title y detail están destinados a las personas y pueden cambiar.

Formato de las filas

Límites de solicitudes

• Cada socio puede realizar al menos 120 solicitudes por minuto. El límite lo comparten todas las claves del socio, por lo que crear más claves no aumenta la capacidad.
• Cuando se supera el límite, la API devuelve 429 con el código too_many_requests y un encabezado Retry-After con el número de segundos que se debe esperar. Espere al menos ese tiempo antes de volver a intentarlo.
• En el perímetro de red se aplica un límite independiente y superior por dirección IP de origen. Las respuestas normales incluyen encabezados X-RateLimit-* para ese límite. Cuando se supera, también se obtiene 429, pero sin cuerpo JSON, por lo que debe gestionar un 429 mediante su estado y Retry-After, no analizando el cuerpo.

Una sincronización diaria con limit=1000 solo necesita unas pocas solicitudes y se mantiene ampliamente dentro de los límites.

Qué se puede esperar de los datos

• Los recuentos son máximos mensuales. usageLicenseCount y discoveryInstallationCount son los valores más altos de los recuentos diarios registrados durante el mes, no un promedio ni el valor al final del mes. Un usuario que se añade y se elimina de nuevo entre dos recuentos diarios no se detecta.
• Los datos pueden tener un retraso de hasta un día. Las cifras las registra una tarea diaria que se ejecuta poco después de medianoche UTC y cuenta para el día anterior. Un cambio realizado hoy aparecerá después de la siguiente ejecución.
• El mes actual aún puede cambiar. Hasta que termine el mes, un nuevo máximo incrementa la fila del mes actual. El último recuento de un mes se realiza durante la primera hora del día 1 del mes siguiente (UTC), por lo que debe considerar un mes como definitivo a partir de las 02:00 UTC del día 1.
• Cada organización obtiene una fila cada mes, incluidos los meses con uso cero. Las filas comienzan en el mes en que se creó la organización. En casos excepcionales, como una ejecución diaria fallida, puede faltar un mes para una organización. Considere que un mes ausente es desconocido, no cero.
• Las organizaciones de prueba están incluidas. Se devuelven filas para todas las organizaciones de su cuenta de socio, independientemente de si son clientes de pago.
• La ausencia de compromiso y un compromiso de 0 tienen el mismo aspecto. Ambos se devuelven como committedLicenseCount: null.
• discoveryInstallationCount representa instalaciones, no identidades. Cuenta las instalaciones pasivas de la extensión, que es el criterio sobre el que se licencia Discovery. La cifra «Corporate identities» del panel de Discovery cuenta otra cosa y no coincidirá.
• discoveryActivatedNow no es histórico. Refleja la configuración actual y se repite en todos los meses. Utilice discoveryInstallationCount para la facturación.
• Los nombres son actuales. Si se cambia el nombre de una organización o un socio, todos sus meses mostrarán el nombre nuevo. Relacione los datos mediante organizationId, no mediante los nombres.
• Las organizaciones eliminadas conservan su historial. Los meses registrados antes de eliminar una organización se siguen devolviendo. Las filas no indican que la organización se haya eliminado.
• Al mover una organización, se mueve su historial. Solo Uniqkey puede mover una organización a otro socio. Si ocurre, todos sus meses, incluidos los que ya se hayan facturado, la siguen al nuevo socio. Desaparecen de los resultados del socio anterior, salvo que el nuevo socio esté por debajo del anterior.

Notas para integraciones de facturación y CRM

• Conserve su propia copia de los meses facturados. Guarde en su sistema las filas de cada mes cuando facture. Debido a los movimientos y cambios de nombre descritos anteriormente, un mes que vuelva a consultar más adelante puede diferir de lo que facturó.
• Utilice organizationId y month como clave. Cada organización tiene como máximo una fila por mes. Actualice la fila en las sincronizaciones posteriores en lugar de insertar duplicados.
• Vuelva a leer los meses recientes. Una sincronización sencilla y sólida consiste en solicitar el mes anterior en from en cada ejecución y sobrescribir esas filas; después, bloquee un mes en su sistema una vez que se haya facturado.
• Asigne clientes mediante organizationExternalId. En el Portal de socios, abra la organización, edite sus datos e introduzca el número de cliente de su CRM en External ID. También puede establecerlo al crear una organización. Después aparecerá en todas las filas. Uniqkey no comprueba que el valor sea único.
• Utilice una clave por sistema. Una clave independiente para facturación y otra para CRM facilita la lectura del registro de auditoría y permite revocar una sin interrumpir la otra.

Solución de problemas

Cuando se ponga en contacto con soporte, incluya el identificador de su socio (de /v1/me), el nombre de la clave, la URL exacta de la solicitud sin la clave, el estado HTTP y el cuerpo de la respuesta, incluido el traceId.