Papéis e Permissões

O acesso de um membro dentro da organização vem do seu papel (OWNER, ADMIN, MEMBER ou VIEWER) somado aos ajustes individuais de permissão, descritos em Permissões individuais do membro.

Na API, essas permissões são conferidas nas rotas protegidas por permissão de organização, como as de organização, membros, convites, papéis, pastas, contatos e relatórios.

---

Catálogo de permissões

As permissões seguem o formato RECURSO:AÇÃO.

Recurso	Ações
DOCUMENTS	CREATE, READ, EDIT, DELETE, SEND
TEMPLATES	CREATE, READ, EDIT, DELETE
MEMBERS	INVITE, REMOVE, EDIT_ROLE, READ
ORG	EDIT_SETTINGS
REPORTS	READ
INTEGRATIONS	MANAGE
FOLDERS	CREATE, READ, EDIT, DELETE
CONTACTS	CREATE, READ, EDIT, DELETE

Cada permissão também tem um id numérico, usado nos papéis customizados. Consulte os IDs em Listar permissões disponíveis e não fixe esses valores no seu código.

---

Permissões por papel padrão

Permissão	OWNER	ADMIN	MEMBER	VIEWER
DOCUMENTS:CREATE	✓	✓	✓	-
DOCUMENTS:READ	✓	✓	✓	✓
DOCUMENTS:EDIT	✓	✓	✓	-
DOCUMENTS:DELETE	✓	✓	-	-
DOCUMENTS:SEND	✓	✓	✓	-
TEMPLATES:CREATE	✓	✓	✓	-
TEMPLATES:READ	✓	✓	✓	✓
TEMPLATES:EDIT	✓	✓	✓	-
TEMPLATES:DELETE	✓	✓	-	-
MEMBERS:INVITE	✓	✓	-	-
MEMBERS:REMOVE	✓	✓	-	-
MEMBERS:EDIT_ROLE	✓	✓	-	-
MEMBERS:READ	✓	✓	✓	✓
ORG:EDIT_SETTINGS	✓	✓	-	-
REPORTS:READ	✓	✓	-	-
INTEGRATIONS:MANAGE	✓	✓	-	-
FOLDERS:CREATE	✓	✓	-	-
FOLDERS:READ	✓	✓	✓	✓
FOLDERS:EDIT	✓	✓	-	-
FOLDERS:DELETE	✓	✓	-	-
CONTACTS:CREATE	✓	✓	-	-
CONTACTS:READ	✓	✓	✓	✓
CONTACTS:EDIT	✓	✓	-	-
CONTACTS:DELETE	✓	✓	-	-

OWNER

O proprietário passa em qualquer checagem de permissão da organização, independentemente de ajustes individuais.

---

Papéis customizados

Uma organização pode cadastrar papéis customizados, cada um com nome, papel base e uma lista de permissões.

Papéis customizados e membros

Hoje não existe rota para atribuir um papel customizado a um membro: o papel do membro aceita apenas ADMIN, MEMBER ou VIEWER. Para dar a um membro um conjunto específico de permissões, use o papel padrão mais os ajustes individuais. Por isso, criar, alterar ou excluir um papel customizado não muda o acesso de nenhum membro.

Listar papéis customizados

Permissão necessária: MEMBERS:READ

GET /v1/organizations/{orgId}/roles

URL completa: https://api.tapsign.com.br/v1/organizations/{orgId}/roles

curl -X GET https://api.tapsign.com.br/v1/organizations/42/roles \
  -H "Authorization: Bearer {token}"

Status: 200 OK

Exemplo resumido:

{
  "roles": [
    {
      "id": 3,
      "name": "Revisor",
      "baseRole": "VIEWER",
      "permissions": [
        { "id": 2, "resource": "DOCUMENTS", "action": "READ" },
        { "id": 7, "resource": "TEMPLATES", "action": "READ" }
      ],
      "createdAt": "2026-09-12T14:30:00Z"
    }
  ],
  "availablePermissions": [
    { "id": 1, "resource": "DOCUMENTS", "action": "CREATE" },
    { "id": 2, "resource": "DOCUMENTS", "action": "READ" }
  ],
  "defaultRolePermissions": {
    "MEMBER": [
      "CONTACTS:READ", "DOCUMENTS:CREATE", "DOCUMENTS:EDIT", "DOCUMENTS:READ", "DOCUMENTS:SEND",
      "FOLDERS:READ", "MEMBERS:READ", "TEMPLATES:CREATE", "TEMPLATES:EDIT", "TEMPLATES:READ"
    ],
    "VIEWER": [
      "CONTACTS:READ", "DOCUMENTS:READ", "FOLDERS:READ", "MEMBERS:READ", "TEMPLATES:READ"
    ]
  }
}

Campo	Tipo	Descrição
roles	array	Papéis customizados da organização, em ordem alfabética de nome
roles[].id	integer	ID do papel. É o {roleId} das rotas abaixo.
roles[].name	string	Nome do papel
roles[].baseRole	string	Papel base: OWNER, ADMIN, MEMBER ou VIEWER
roles[].permissions	array	Permissões do papel, cada uma com id, resource e action
roles[].createdAt	string	Data de criação (ISO 8601, UTC)
availablePermissions	array	Catálogo completo de permissões (id, resource, action)
defaultRolePermissions	object	Uma chave por papel padrão (OWNER, ADMIN, MEMBER, VIEWER) com as permissões padrão em ordem alfabética. O exemplo acima mostra só duas chaves.

Criar papel customizado

Permissão necessária: MEMBERS:EDIT_ROLE

POST /v1/organizations/{orgId}/roles

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome do papel
baseRole	string	Sim	Papel base: OWNER, ADMIN, MEMBER ou VIEWER
permissionIds	integer[]	Não	IDs das permissões do catálogo

curl -X POST https://api.tapsign.com.br/v1/organizations/42/roles \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Revisor",
    "baseRole": "VIEWER",
    "permissionIds": [2, 7]
  }'

Status: 201 Created

{
  "id": 3,
  "name": "Revisor",
  "baseRole": "VIEWER",
  "permissions": [
    { "id": 2, "resource": "DOCUMENTS", "action": "READ" },
    { "id": 7, "resource": "TEMPLATES", "action": "READ" }
  ],
  "createdAt": "2026-09-12T14:30:00Z"
}

Atualizar papel customizado

Permissão necessária: MEMBERS:EDIT_ROLE

PUT /v1/organizations/{orgId}/roles/{roleId}

Envie só o que quiser alterar. O baseRole não é alterado por esta rota.

Campo	Tipo	Obrigatório	Descrição
name	string	Não	Novo nome
permissionIds	integer[]	Não	Nova lista de IDs de permissões. Substitui a lista anterior.

curl -X PUT https://api.tapsign.com.br/v1/organizations/42/roles/3 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "permissionIds": [2, 7, 13]
  }'

Status: 200 OK, com o papel atualizado no mesmo formato da criação.

Excluir papel customizado

Permissão necessária: MEMBERS:EDIT_ROLE

DELETE /v1/organizations/{orgId}/roles/{roleId}

curl -X DELETE https://api.tapsign.com.br/v1/organizations/42/roles/3 \
  -H "Authorization: Bearer {token}"

Status: 204 No Content

---

Listar permissões disponíveis

Retorna o catálogo completo de permissões com seus IDs.

Permissão necessária: MEMBERS:READ

GET /v1/organizations/{orgId}/roles/permissions

URL completa: https://api.tapsign.com.br/v1/organizations/{orgId}/roles/permissions

curl -X GET https://api.tapsign.com.br/v1/organizations/42/roles/permissions \
  -H "Authorization: Bearer {token}"

Status: 200 OK

[
  { "id": 1, "resource": "DOCUMENTS", "action": "CREATE" },
  { "id": 2, "resource": "DOCUMENTS", "action": "READ" },
  { "id": 13, "resource": "MEMBERS", "action": "READ" }
]

---

Erros comuns

Código	Quando acontece
400	Campo obrigatório ausente ou inválido (o detalhe vem em fields)
401	Token ausente, inválido ou chave de API desativada
403	O usuário não é membro ativo da organização ou não tem a permissão exigida pela rota
404	Papel customizado não encontrado nesta organização

O formato do corpo de erro está em Status de Erros.