Claves de API

Crea y gestiona claves de API del tenant de Plur-e — los ocho scopes y lo que exige cada uno, los roles de Business Central y CRM, los códigos ERP y su precedencia, caducidad, el límite de 25 y la revocación.

Respuesta rápida

Un administrador del tenant crea claves de API en Developers → APIs → API keys → New API key. Una clave tiene un nombre, una caducidad (30, 90, 180 o 365 días), uno o más de ocho scopes y los roles de Business Central y/o de CRM con los que se ejecuta. La clave se muestra una sola vez, al crearla. Un tenant puede tener 25 claves activas a la vez; una clave activa es la que no está revocada ni caducada.

Crear una clave

Abre Developers → APIs → API keys y pulsa New API key. Necesitas el módulo Developer APIs en tu suscripción y el rol admin del tenant.

Rellena el formulario:

Name — de 1 a 100 caracteres, para reconocer la clave después (por ejemplo, la integración que la usa).
Expires in — 30, 90, 180 o 365 días. Por defecto 90. No existen claves sin caducidad.
Scopes — qué tipo de operación puede hacer la clave. Consulta la tabla de abajo.
Business Central roles y CRM roles — aparecen al elegir scopes de ese grupo. Consulta Roles.
ERP codes used for writes — aparece al elegir bc:write o bc:post. Consulta Códigos ERP.

Pulsa Create. Copia la clave de inmediato: Plur-e la muestra una vez y guarda solo un hash, así que no puede volver a mostrarse. Si la pierdes, crea otra clave y revoca la perdida.

Usa la clave como se indica en Autenticación. La tabla de claves muestra el nombre, scopes, roles, los últimos cuatro caracteres, quién la creó, las fechas de creación y caducidad, el último uso y el estado (Active, Expired o Revoked).

Scopes

Un scope permite un tipo de operación. Algunos scopes exigen que se seleccione otro: el formulario selecciona el requisito por ti.

Scope	Permite	Requiere
`bc:read`	Business Central · Read: listar métodos, ejecutar métodos de lectura, consultar entidades	—
`bc:write`	Business Central · Write: métodos que modifican datos	`bc:read`
`bc:post`	Business Central · Post: métodos que contabilizan documentos (irreversible)	`bc:read`
`crm:read`	Dynamics 365 CRM · Read: entidades, registros, FetchXML y búsqueda	—
`crm:write`	Dynamics 365 CRM · Create and update: crear, actualizar, estado, asignar, asociar y acciones	`crm:read`
`crm:delete`	Dynamics 365 CRM · Delete: eliminar registros, desasociar y acciones de tipo borrado	`crm:read`
`panel:read`	Plur-e panel · Usuarios móviles, dispositivos, roles, módulos y actividad	—
`panel:locations:read`	Plur-e panel · Ubicaciones registradas de usuarios móviles (datos personales)	`panel:read`

Una llamada sin el scope que necesita responde 403 con el error plure_1321, por ejemplo This API key does not have the scope 'crm:delete'. Da a cada integración el menor conjunto de scopes que necesite.

Roles

Los scopes dicen qué tipo de operación; los roles dicen sobre qué entidades y áreas. La API usa los mismos roles MCP que los asistentes de IA. Créalos en Developers → AI & MCP → Roles; consulta Roles MCP para ver cómo funcionan.

Una clave con cualquier scope de Business Central necesita al menos un rol de Business Central.
Una clave con cualquier scope de CRM necesita al menos un rol de CRM, y todos los roles de CRM deben pertenecer a la misma conexión de CRM. Esa es la conexión que usa la clave.
Los roles se asignan a la clave de forma explícita. El rol por defecto del tenant no se añade automáticamente.
Una clave recibe la intersección de sus roles y sus scopes. El scope fija un techo a las acciones que los roles pueden conceder:

Scope	Acción más alta que permite
`bc:read`	Read
`bc:write`	Update
`bc:post`	Post
`crm:read`	Read
`crm:write`	Create y Update
`crm:delete`	Delete

Así, un rol que concede Delete sobre una entidad no sirve de nada a una clave sin crm:delete, y una clave con bc:post sigue sin poder contabilizar en un área cuyo rol no concede Post.

Códigos ERP

Algunos métodos de Business Central actúan en nombre de una persona: un empleado de almacén, un vendedor o una ubicación de venta. Para claves con bc:write o bc:post puedes fijar un valor por defecto de cada uno:

Warehouse employee
Salesperson
Sales location

Cada uno tiene como máximo 50 caracteres. Plur-e no los valida contra Business Central al guardarlos. En cada llamada de escritura, el código usado es, por orden de precedencia:

El valor que pasas de forma explícita en los parameters de la llamada.
El código guardado en la clave.
El valor por defecto del tenant en Developers → AI & MCP → Settings → ERP identity.
Si no hay ninguno, la llamada se rechaza con 422 y el código erp_user_not_mapped.

Límites

Límite	Valor
Claves activas por tenant	25 (crear otra responde `409`, error `plure_1317`)
Opciones de caducidad	30, 90, 180 o 365 días (por defecto 90)
Longitud del nombre	De 1 a 100 caracteres
Longitud del código ERP	50 caracteres
Peticiones por clave	120 por minuto

Revocar una clave

En la tabla de claves, pulsa Revoke y confirma. La revocación es inmediata en el Admin Center y efectiva en la API en un minuto; consulta Autenticación. Revocar una clave ya revocada no hace nada.

Solo los administradores del tenant pueden crear y revocar claves. El personal de soporte puede listarlas, y si intenta crear o revocar recibe el error plure_1319.

Usage log

Developers → APIs → Usage log lista cada petición autenticada por tus claves, la más reciente primero, y se puede filtrar por clave. Cada fila muestra la hora, la clave, la API (bc, crm o panel), la operación, el destino (método, entidad o recurso), el estado, la duración y el código de error. Nunca guarda la clave ni el cuerpo de la petición. Las filas se conservan 90 días.