Permisos de las claves API
Los permisos de una clave API limitan lo que una integración de software puede hacer dentro del grupo de la clave. No identifican a una persona, no conceden acceso a otro grupo ni sustituyen la suscripción Rental de la organización. Las acciones humanas abiertas mediante un launch_url siguen requiriendo un usuario de TrakarIA autenticado y con los permisos adecuados en el grupo.
Utiliza una clave distinta para cada sistema y concede únicamente las operaciones que realiza. Así podrás sustituir o revocar una integración sin interrumpir las demás y limitarás el impacto de una credencial comprometida.
Referencia de permisos
Sección titulada «Referencia de permisos»Cada operación de la API pública comprueba un permiso concreto. Un permiso de lectura nunca concede escritura. En API e integraciones, al seleccionar escritura también se selecciona la lectura correspondiente cuando existe; al seleccionar extracción de adjuntos también se selecciona su lectura. Es una ayuda de la interfaz de creación, no una implicación entre permisos de la API.
| Permiso | Qué permite | Operaciones públicas |
|---|---|---|
vehicles:read | Conciliar y consultar los vehículos del grupo de la clave. | GET /v1/vehicles, GET /v1/vehicles/{vehicle_id} |
vehicles:write | Crear o sincronizar un vehículo mediante el identificador externo del socio. | PUT /v1/vehicles/by-external/{external_id} |
rentals:read | Conciliar y consultar expedientes Rental y sus inspecciones preparadas. | GET /v1/rentals, GET /v1/rentals/{rental_id}, GET /v1/inspections/{inspection_id} |
rentals:write | Crear, sincronizar, modificar o cancelar un expediente Rental. | PUT /v1/rentals/by-external/{external_id}, PATCH /v1/rentals/{rental_id}, POST /v1/rentals/{rental_id}/cancel |
inspections:write | Preparar o reanudar una inspección de salida/devolución y renovar su enlace de apertura temporal. La API no puede validar la inspección humana. | POST /v1/rentals/{rental_id}/inspections, POST /v1/inspections/{inspection_id}/launch |
evidence:read | Enumerar y descargar pruebas originales autorizadas, individualmente o como archivo ZIP. | GET /v1/inspections/{inspection_id}/evidence, GET /v1/evidence/{evidence_id}/content, GET /v1/inspections/{inspection_id}/evidence/archive, GET /v1/rentals/{rental_id}/evidence/archive |
attachments:read | Listar y descargar documentos privados aportados por el socio. | GET /v1/rentals/{rental_id}/attachments, GET /v1/attachments/{attachment_id}/content |
attachments:write | Adjuntar un documento privado a un expediente Rental. | POST /v1/rentals/{rental_id}/attachments |
attachments:extract | Iniciar la extracción facturable de un permiso de conducir ya adjunto. Los valores extraídos siempre requieren revisión. | POST /v1/attachments/{attachment_id}/extract |
reports:read | Descubrir, consultar y descargar informes de salida/comparación y sus PDF. | GET /v1/rentals/{rental_id}/report, GET /v1/rentals/{rental_id}/reports, GET /v1/reports/{report_id}, GET /v1/reports/{report_id}/pdf |
events:read | Conciliar eventos del ciclo de vida perdidos durante una interrupción de webhooks. | GET /v1/events |
jobs:read | Consultar el estado y resultado seguro de una operación asíncrona, incluida la extracción de documentos. | GET /v1/jobs/{job_id} |
GET /v1/capabilities requiere una clave válida y activa, pero ningún permiso de operación adicional. Informa de las funciones y límites efectivos; no es una lista completa de los permisos de la clave.
Los destinos de webhook se gestionan por separado en API e integraciones mediante un administrador de grupo autenticado. events:read controla únicamente GET /v1/events para la conciliación; no crea un destino, no concede acceso a la interfaz de administración ni sustituye la verificación de la firma del webhook.
Conjuntos habituales
Sección titulada «Conjuntos habituales»| Necesidad de integración | Mínimo recomendado |
|---|---|
| Comprobar la conexión y las capacidades comerciales | Una clave válida; ningún permiso de operación adicional |
| Sincronizar flota y reservas | vehicles:read, vehicles:write, rentals:read, rentals:write |
| Preparar inspecciones de salida y devolución | Añadir inspections:write |
| Consumir fotos de inspección e informes finales | Añadir evidence:read, reports:read |
| Adjuntar documentos y extraer un permiso | Añadir attachments:read, attachments:write, attachments:extract, jobs:read |
| Recuperar eventos después de una interrupción de webhooks | Añadir events:read |
| Implementar todo el ciclo de Alquiler | Seleccionar cada permiso utilizado por las operaciones de los escenarios elegidos; eliminar los permisos de extracción o adjuntos cuando no se usen esas funciones |
Estas propuestas corresponden a flujos habituales. El permiso exacto de cada operación aparece como Required permission en la referencia API.
Diagnosticar un 403
Sección titulada «Diagnosticar un 403»Cuando una clave válida carece del permiso necesario, la API devuelve 403 con el código INSUFFICIENT_SCOPE. La respuesta incluye el permiso exacto que falta en errors[0].meta.required. Añádelo a una clave de sustitución solo si la integración necesita realmente esa operación.
Un 403 también puede indicar que el recurso está fuera del grupo de la clave, que la organización o función no está disponible o que el plan comercial no incluye la operación. Conceder todos los permisos no evita esas comprobaciones. Consulta Autenticación y acceso y Sincronización y errores.