Empresas e Papéis — Visão Geral
Empresas e Papéis — Visão geral
Um papel (role) agrupa um conjunto de permissões e é atribuído a um ou mais usuários da empresa. As permissões em si — o que cada ação, em cada módulo, permite fazer — formam um catálogo comum da plataforma, consultável separadamente.
Endpoints deste domínio
| Método | Caminho | Descrição |
|---|---|---|
GET | /v1/companies/{id}/users | Lista os usuários de uma empresa |
GET | /v1/companies/{companyId}/roles | Lista os papéis de uma empresa |
PUT | /v1/companies/roles/{roleId} | Atualiza um papel (substituição completa) |
GET | /v1/companies/users/permissions | Lista o catálogo de permissões disponíveis |
POST | /v1/companies/roles | Cria um novo papel |
GET | /v1/companies/{id}/logo-upload-url | Gera uma URL de upload do logotipo da empresa |
GET | /v1/companies/{id}/logo-download-url | Gera uma URL de download do logotipo da empresa |
PATCH | {baseUrlRole}/v2/users/{userId}/agflow-role | Atribui papéis a um usuário |
Particularidade de base de URL: o endpoint de atribuição de papéis a um usuário ( PATCH {baseUrlRole}/v2/users/{userId}/agflow-role) não atende na mesma base de URL dos demais endpoints deste domínio — nem dos demais domínios da API AgFlow. Ele utiliza uma base de URL distinta, dedicada a operações de identidade e papel de usuário. Ao integrar, é necessário configurar a base de URL apropriada para esta operação específica; usar a base padrão da API AgFlow neste endpoint resulta em falha de conexão ou rota inexistente.
Papel × permissões
name, description, type, intern) e por uma lista permissions, no formato [{module, permissions: {<recurso>: [ações]}}]. Cada módulo (por exemplo, card, credit, flow, documents) agrupa recursos, e cada recurso lista as ações permitidas (view, create, update, delete, move, entre outras, variando por recurso). O catálogo completo de módulos, recursos e ações disponíveis pode ser consultado através do endpoint de listagem de permissões.Comportamentos importantes
PUT /v1/companies/roles/{roleId}) é uma substituição completa do objeto — não existe atualização parcial nem leitura prévia das permissões individuais pela API. É necessário reenviar o conjunto completo de dados desejado a cada atualização, mesmo quando apenas um campo está mudando.GET /v1/companies/{companyId}/roles) retorna apenas identificação básica (id, name, description) — nunca o array de permissões. Como não há leitura das permissões vigentes de um papel por esse ou outro endpoint, recomendamos manter esse estado do lado da integração.global é enviado como true.POST /v1/companies/roles), apenas o campo name é obrigatório — os demais campos são opcionais, mas recomendamos sempre enviá-los completos, já que uma atualização futura será uma substituição integral.GET /v1/companies/{id}/users) espera o identificador de organização no caminho — um identificador em um formato diferente do esperado retorna um erro do lado do servidor (502).PATCH {baseUrlRole}/v2/users/{userId}/agflow-role) substitui integralmente a lista de papéis do usuário — não faz mesclagem. Para adicionar um papel sem remover os já atribuídos, é necessário reenviar a lista completa (papéis existentes mais o novo).Modificado em 2026-07-28 20:38:32