Papeis e Permissoes

Gerencie papeis personalizados e controle granular de permissoes para membros da organizacao.

Listar papeis

Retorna todos os papeis da organizacao (incluindo os padroes e os customizados).

Requisicao

GET /v1/organizations/{orgId}/roles

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

Headers

Header	Valor
`Authorization`	`Bearer {token}`

Exemplo de requisicao

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

Resposta

Status: 200 OK

{
  "content": [
    {
      "id": "role_owner",
      "name": "Owner",
      "description": "Proprietario da organizacao com acesso total",
      "isSystem": true,
      "memberCount": 1,
      "permissions": ["*"]
    },
    {
      "id": "role_admin",
      "name": "Admin",
      "description": "Administrador com acesso amplo",
      "isSystem": true,
      "memberCount": 2,
      "permissions": [
        "DOCUMENTS:READ", "DOCUMENTS:CREATE", "DOCUMENTS:EDIT", "DOCUMENTS:DELETE",
        "ENVELOPES:READ", "ENVELOPES:CREATE", "ENVELOPES:EDIT", "ENVELOPES:DELETE", "ENVELOPES:SEND",
        "TEMPLATES:READ", "TEMPLATES:CREATE", "TEMPLATES:EDIT", "TEMPLATES:DELETE",
        "MEMBERS:READ", "MEMBERS:INVITE", "MEMBERS:REMOVE", "MEMBERS:EDIT_ROLE",
        "SIGNATURES:READ",
        "WEBHOOKS:READ", "WEBHOOKS:CREATE", "WEBHOOKS:EDIT", "WEBHOOKS:DELETE",
        "ORG_SETTINGS:READ", "ORG_SETTINGS:EDIT"
      ]
    },
    {
      "id": "role_member",
      "name": "Member",
      "description": "Membro padrao com acesso limitado",
      "isSystem": true,
      "memberCount": 8,
      "permissions": [
        "DOCUMENTS:READ", "DOCUMENTS:CREATE",
        "ENVELOPES:READ", "ENVELOPES:CREATE", "ENVELOPES:SEND",
        "TEMPLATES:READ",
        "SIGNATURES:READ"
      ]
    },
    {
      "id": "role_custom_001",
      "name": "Revisor",
      "description": "Apenas visualiza documentos e envelopes",
      "isSystem": false,
      "memberCount": 3,
      "permissions": [
        "DOCUMENTS:READ",
        "ENVELOPES:READ",
        "TEMPLATES:READ",
        "SIGNATURES:READ"
      ]
    }
  ]
}

Criar papel customizado

Cria um novo papel com permissoes especificas.

Requisicao

POST /v1/organizations/{orgId}/roles

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

Headers

Header	Valor
`Authorization`	`Bearer {token}`
`Content-Type`	`application/json`

Body

Campo	Tipo	Obrigatorio	Descricao
`name`	string	Sim	Nome do papel
`description`	string	Nao	Descricao do papel
`permissions`	string[]	Sim	Lista de permissoes no formato `RECURSO:ACAO`

Exemplo de requisicao

curl -X POST https://api.tapsign.com.br/v1/organizations/org_abc123/roles \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gerente de Contratos",
    "description": "Gerencia documentos e envelopes, sem acesso a configuracoes",
    "permissions": [
      "DOCUMENTS:READ",
      "DOCUMENTS:CREATE",
      "DOCUMENTS:EDIT",
      "ENVELOPES:READ",
      "ENVELOPES:CREATE",
      "ENVELOPES:EDIT",
      "ENVELOPES:SEND",
      "TEMPLATES:READ",
      "TEMPLATES:CREATE",
      "SIGNATURES:READ"
    ]
  }'

Resposta

Status: 201 Created

{
  "id": "role_custom_002",
  "name": "Gerente de Contratos",
  "description": "Gerencia documentos e envelopes, sem acesso a configuracoes",
  "isSystem": false,
  "memberCount": 0,
  "permissions": [
    "DOCUMENTS:READ",
    "DOCUMENTS:CREATE",
    "DOCUMENTS:EDIT",
    "ENVELOPES:READ",
    "ENVELOPES:CREATE",
    "ENVELOPES:EDIT",
    "ENVELOPES:SEND",
    "TEMPLATES:READ",
    "TEMPLATES:CREATE",
    "SIGNATURES:READ"
  ],
  "createdAt": "2026-03-29T14:30:00Z"
}

Atualizar papel

Atualiza o nome, descricao ou permissoes de um papel customizado.

Requisicao

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

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

Headers

Header	Valor
`Authorization`	`Bearer {token}`
`Content-Type`	`application/json`

Body

Campo	Tipo	Obrigatorio	Descricao
`name`	string	Nao	Novo nome do papel
`description`	string	Nao	Nova descricao
`permissions`	string[]	Nao	Nova lista de permissoes (substitui a anterior)

Exemplo de requisicao

curl -X PUT https://api.tapsign.com.br/v1/organizations/org_abc123/roles/role_custom_002 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": [
      "DOCUMENTS:READ",
      "DOCUMENTS:CREATE",
      "DOCUMENTS:EDIT",
      "DOCUMENTS:DELETE",
      "ENVELOPES:READ",
      "ENVELOPES:CREATE",
      "ENVELOPES:EDIT",
      "ENVELOPES:SEND",
      "TEMPLATES:READ",
      "TEMPLATES:CREATE",
      "TEMPLATES:EDIT",
      "SIGNATURES:READ"
    ]
  }'

Resposta

Status: 200 OK

{
  "id": "role_custom_002",
  "name": "Gerente de Contratos",
  "description": "Gerencia documentos e envelopes, sem acesso a configuracoes",
  "isSystem": false,
  "memberCount": 0,
  "permissions": [
    "DOCUMENTS:READ",
    "DOCUMENTS:CREATE",
    "DOCUMENTS:EDIT",
    "DOCUMENTS:DELETE",
    "ENVELOPES:READ",
    "ENVELOPES:CREATE",
    "ENVELOPES:EDIT",
    "ENVELOPES:SEND",
    "TEMPLATES:READ",
    "TEMPLATES:CREATE",
    "TEMPLATES:EDIT",
    "SIGNATURES:READ"
  ],
  "updatedAt": "2026-03-29T15:00:00Z"
}

Papeis do sistema

Os papeis OWNER, ADMIN e MEMBER sao papeis do sistema (isSystem: true) e nao podem ser editados ou excluidos.

Excluir papel

Remove um papel customizado. Membros com esse papel serao movidos para MEMBER.

Requisicao

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

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

Headers

Header	Valor
`Authorization`	`Bearer {token}`

Exemplo de requisicao

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

Resposta

Status: 204 No Content

Membros reassociados

Ao excluir um papel customizado, todos os membros que possuiam esse papel sao automaticamente movidos para o papel MEMBER.

Listar permissoes disponiveis

Retorna todas as permissoes que podem ser atribuidas a papeis.

Requisicao

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

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

Headers

Header	Valor
`Authorization`	`Bearer {token}`

Exemplo de requisicao

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

Resposta

Status: 200 OK

{
  "resources": [
    {
      "resource": "DOCUMENTS",
      "description": "Documentos enviados para assinatura",
      "actions": ["READ", "CREATE", "EDIT", "DELETE"]
    },
    {
      "resource": "ENVELOPES",
      "description": "Envelopes de assinatura",
      "actions": ["READ", "CREATE", "EDIT", "DELETE", "SEND"]
    },
    {
      "resource": "TEMPLATES",
      "description": "Modelos de documentos reutilizaveis",
      "actions": ["READ", "CREATE", "EDIT", "DELETE"]
    },
    {
      "resource": "MEMBERS",
      "description": "Membros da organizacao",
      "actions": ["READ", "INVITE", "REMOVE", "EDIT_ROLE"]
    },
    {
      "resource": "SIGNATURES",
      "description": "Assinaturas realizadas",
      "actions": ["READ"]
    },
    {
      "resource": "WEBHOOKS",
      "description": "Configuracao de webhooks",
      "actions": ["READ", "CREATE", "EDIT", "DELETE"]
    },
    {
      "resource": "ORG_SETTINGS",
      "description": "Configuracoes da organizacao",
      "actions": ["READ", "EDIT"]
    }
  ]
}

Tabela de permissoes por papel padrao

A tabela abaixo mostra as permissoes atribuidas a cada papel padrao do sistema:

Permissao	OWNER	ADMIN	MEMBER
`DOCUMENTS:READ`	✓	✓	✓
`DOCUMENTS:CREATE`	✓	✓	✓
`DOCUMENTS:EDIT`	✓	✓	-
`DOCUMENTS:DELETE`	✓	✓	-
`ENVELOPES:READ`	✓	✓	✓
`ENVELOPES:CREATE`	✓	✓	✓
`ENVELOPES:EDIT`	✓	✓	-
`ENVELOPES:DELETE`	✓	✓	-
`ENVELOPES:SEND`	✓	✓	✓
`TEMPLATES:READ`	✓	✓	✓
`TEMPLATES:CREATE`	✓	✓	-
`TEMPLATES:EDIT`	✓	✓	-
`TEMPLATES:DELETE`	✓	✓	-
`MEMBERS:READ`	✓	✓	-
`MEMBERS:INVITE`	✓	✓	-
`MEMBERS:REMOVE`	✓	✓	-
`MEMBERS:EDIT_ROLE`	✓	✓	-
`SIGNATURES:READ`	✓	✓	✓
`WEBHOOKS:READ`	✓	✓	-
`WEBHOOKS:CREATE`	✓	✓	-
`WEBHOOKS:EDIT`	✓	✓	-
`WEBHOOKS:DELETE`	✓	✓	-
`ORG_SETTINGS:READ`	✓	✓	-
`ORG_SETTINGS:EDIT`	✓	-	-

Papeis customizados

Use papeis customizados para criar combinacoes especificas de permissoes. Por exemplo, um papel "Revisor" que so pode ler documentos, ou um "Gerente" que pode criar e enviar mas nao excluir.

Erros comuns

Status	Codigo	Descricao
400	`INVALID_PERMISSIONS`	Lista de permissoes contem valores invalidos
400	`SYSTEM_ROLE`	Nao e possivel editar ou excluir papeis do sistema
404	`ROLE_NOT_FOUND`	Papel nao encontrado
409	`ROLE_NAME_EXISTS`	Ja existe um papel com esse nome
403	`FORBIDDEN`	Sem permissao para gerenciar papeis
401	`UNAUTHORIZED`	Token de autenticacao invalido ou ausente

Listar papeis​

Requisicao​

Headers​

Exemplo de requisicao​

Resposta​

Criar papel customizado​

Requisicao​

Headers​

Body​

Exemplo de requisicao​

Resposta​

Atualizar papel​

Requisicao​

Headers​

Body​

Exemplo de requisicao​

Resposta​

Excluir papel​

Requisicao​

Headers​

Exemplo de requisicao​

Resposta​

Listar permissoes disponiveis​

Requisicao​

Headers​

Exemplo de requisicao​

Resposta​

Tabela de permissoes por papel padrao​

Erros comuns​

Listar papeis

Requisicao

Headers

Exemplo de requisicao

Resposta

Criar papel customizado

Requisicao

Headers

Body

Exemplo de requisicao

Resposta

Atualizar papel

Requisicao

Headers

Body

Exemplo de requisicao

Resposta

Excluir papel

Requisicao

Headers

Exemplo de requisicao

Resposta

Listar permissoes disponiveis

Requisicao

Headers

Exemplo de requisicao

Resposta

Tabela de permissoes por papel padrao

Erros comuns