Permissões das chaves API
As permissões limitam o que uma integração pode fazer no grupo da chave. Não identificam uma pessoa, não concedem acesso a outro grupo e não substituem a subscrição Rental da organização. As ações humanas abertas através de um launch_url continuam a exigir um utilizador TrakarIA autenticado com permissões adequadas.
Utilize uma chave por sistema e conceda apenas as operações efetivamente realizadas. Assim poderá rodar ou revogar uma integração sem interromper outras e limitar o impacto de uma credencial exposta.
Referência de permissões
Seção intitulada “Referência de permissões”Cada operação pública verifica uma permissão exata. Uma permissão de leitura nunca concede escrita. Em API e integrações, selecionar escrita também seleciona a leitura correspondente quando existe; selecionar extração de anexos também seleciona a leitura de anexos. Trata-se de uma conveniência da interface, não de uma implicação entre permissões API.
| Permissão | O que permite | Operações públicas |
|---|---|---|
vehicles:read | Ler e reconciliar veículos no grupo da chave. | GET /v1/vehicles, GET /v1/vehicles/{vehicle_id} |
vehicles:write | Criar ou sincronizar um veículo pelo ID externo do seu sistema. | PUT /v1/vehicles/by-external/{external_id} |
rentals:read | Ler e reconciliar dossiers Rental e inspeções preparadas. | GET /v1/rentals, GET /v1/rentals/{rental_id}, GET /v1/inspections/{inspection_id} |
rentals:write | Criar, sincronizar, atualizar ou cancelar um dossier Rental. | PUT /v1/rentals/by-external/{external_id}, PATCH /v1/rentals/{rental_id}, POST /v1/rentals/{rental_id}/cancel |
inspections:write | Preparar ou retomar inspeções de entrega/devolução e renovar a ligação temporária. Não permite à API validar a inspeção humana. | POST /v1/rentals/{rental_id}/inspections, POST /v1/inspections/{inspection_id}/launch |
evidence:read | Listar e descarregar provas originais autorizadas, individualmente ou em 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 e descarregar documentos privados fornecidos pelo seu software. | GET /v1/rentals/{rental_id}/attachments, GET /v1/attachments/{attachment_id}/content |
attachments:write | Carregar um documento privado para um dossier Rental. | POST /v1/rentals/{rental_id}/attachments |
attachments:extract | Iniciar a extração faturável de uma carta de condução existente. Os valores extraídos continuam sujeitos a revisão. | POST /v1/attachments/{attachment_id}/extract |
reports:read | Localizar, ler e descarregar relatórios de entrega/comparação e os respetivos 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 | Recuperar eventos do ciclo de vida perdidos durante indisponibilidade dos webhooks. | GET /v1/events |
jobs:read | Consultar o estado e resultado seguro de uma operação assíncrona, incluindo extração documental. | GET /v1/jobs/{job_id} |
GET /v1/capabilities exige uma chave válida e ativa, mas nenhuma permissão operacional adicional. Devolve funcionalidades e limites efetivos, não a lista completa de permissões.
As destinos webhook são geridos separadamente por um administrador autenticado. events:read controla apenas GET /v1/events: não cria um destino, não concede acesso administrativo e não substitui a verificação da assinatura.
Conjuntos comuns
Seção intitulada “Conjuntos comuns”| Necessidade | Mínimo recomendado |
|---|---|
| Verificar ligação e capacidades comerciais | Uma chave válida; nenhuma permissão operacional adicional |
| Sincronizar frota e reservas | vehicles:read, vehicles:write, rentals:read, rentals:write |
| Preparar entrega e devolução | Acrescente inspections:write |
| Consumir fotografias e relatórios finais | Acrescente evidence:read, reports:read |
| Carregar documentos e extrair uma carta | Acrescente attachments:read, attachments:write, attachments:extract, jobs:read |
| Recuperar eventos após indisponibilidade | Acrescente events:read |
| Implementar todo o ciclo Rental | Selecione as permissões usadas nos cenários escolhidos; omita extração ou anexos quando não os utilizar |
O requisito exato aparece como Required permission na referência da API.
Diagnosticar um 403
Seção intitulada “Diagnosticar um 403”Quando falta a permissão necessária, a API devolve 403 com código INSUFFICIENT_SCOPE e indica-a em errors[0].meta.required. Só a acrescente a uma chave substituta se a operação for realmente necessária.
Um 403 também pode significar que o recurso não pertence ao grupo, a organização ou funcionalidade não está disponível, ou o plano não inclui a operação. Conceder todas as permissões não contorna esses controlos. Consulte autenticação e acesso e sincronização e erros.