¿Cómo puedo usar la API de licencias para gestionar licencias de forma programática?

Aprende a usar la API REST de licencias de SecureMailMerge para asignar y desasignar licencias programáticamente usando claves API.

El servidor de licencias proporciona una API REST que te permite asignar y desasignar licencias de forma programática. Esto es útil para revendedores que gestionan múltiples clientes, equipos de TI que automatizan la incorporación, o cualquier persona que integre la gestión de licencias en sus propias herramientas.

Autenticación y URL base

Todas las solicitudes de la API están autenticadas usando una clave API. La clave API es un GUID que debes incluir en el cuerpo de la solicitud (no en un encabezado).

Todos los puntos finales de la API están disponibles en:

https://licensing.solinventum.com/api/manage/{subscriptionType}/{subscriptionID}

Donde:

• subscriptionType es uno de: Paddle, Azure o Manual
• subscriptionID es el GUID de tu suscripción

No necesitas construir esta URL tú mismo. En el servidor de licencias, ve a la página “Asignar Licencias” de tu suscripción y selecciona la pestaña Asignar licencias a través de la API. Mostrará la URL base completa, tu clave API y una carga útil JSON lista para usar para tu suscripción.

Regenerando tu clave API

Si tu clave API se ve comprometida, puedes regenerarla desde la misma página. La clave antigua se invalida de inmediato. Solo el propietario de la suscripción puede regenerar claves API. Siempre usa HTTPS al llamar a la API y mantén tu clave API en secreto: cualquiera con tu clave API puede asignar y desasignar licencias en tu suscripción.

Asignar licencias

Agrega asignaciones de licencias a una o más direcciones de correo electrónico.

PUT /api/manage/{subscriptionType}/{subscriptionID}
Content-Type: application/json

Cuerpo de la solicitud

{
  "apiKey": "4024d0d8-9a7d-4ac3-9e61-efaeb7c278df",
  "emails": ["[email protected]", "[email protected]"]
}

Respuesta

Éxito (200):

{
  "success": true,
  "errors": [],
  "assignmentStats": {
    "availableLicenses": 10,
    "assignedLicenses": 7
  }
}

Licencias insuficientes (402):

Devuelto cuando intentas asignar más licencias de las que están disponibles en tu suscripción.

Solicitud incorrecta (400):

Devuelto por errores de validación como formato de correo electrónico inválido, correos duplicados o campos faltantes.

Reglas de validación

• Debe proporcionarse al menos una dirección de correo electrónico
• Cada correo debe tener un formato válido y no ser más largo de 256 caracteres
• Los correos duplicados dentro de la misma solicitud son rechazados
• No puedes asignar más licencias de las que tu suscripción tiene disponibles

Ejemplos

cURL

curl -X PUT \
  https://licensing.solinventum.com/api/manage/Paddle/ff3d3cf5-5388-40a0-915f-970c1d2d972f \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "4024d0d8-9a7d-4ac3-9e61-efaeb7c278df",
    "emails": ["[email protected]"]
  }'

PowerShell

$body = @{
    apiKey = "4024d0d8-9a7d-4ac3-9e61-efaeb7c278df"
    emails = @("[email protected]")
} | ConvertTo-Json

Invoke-RestMethod `
  -Method Put `
  -Uri "https://licensing.solinventum.com/api/manage/Paddle/ff3d3cf5-5388-40a0-915f-970c1d2d972f" `
  -ContentType "application/json" `
  -Body $body

Desasignar licencias

Elimina las asignaciones de licencias de una o más direcciones de correo electrónico.

DELETE /api/manage/{subscriptionType}/{subscriptionID}
Content-Type: application/json

Cuerpo de la solicitud

{
  "apiKey": "4024d0d8-9a7d-4ac3-9e61-efaeb7c278df",
  "emails": ["[email protected]"]
}

El formato del cuerpo de la solicitud es el mismo que para asignar licencias.

Respuesta

Éxito (200):

{
  "success": true,
  "errors": [],
  "assignmentStats": {
    "availableLicenses": 10,
    "assignedLicenses": 6
  }
}

Solicitud incorrecta (400):

Devuelto si las direcciones de correo electrónico especificadas no están actualmente asignadas a la suscripción.

Ejemplo

curl -X DELETE \
  https://licensing.solinventum.com/api/manage/Paddle/ff3d3cf5-5388-40a0-915f-970c1d2d972f \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "4024d0d8-9a7d-4ac3-9e61-efaeb7c278df",
    "emails": ["[email protected]"]
  }'

Manejo de errores

Siempre verifica el campo success y el array errors en el cuerpo de la respuesta para obtener detalles sobre lo que salió mal.