Gerenciar Membros

Rotas para listar, convidar, remover e alterar o papel e as permissões dos membros de uma organização. Todas exigem que o usuário autenticado seja membro ativo da organização e tenha a permissão indicada em cada rota. O proprietário (OWNER) passa em todas as checagens. A tabela de permissões por papel está em Papéis e Permissões.

Listar membros

Retorna os membros ativos da organização, com paginação.

Permissão necessária: MEMBERS:READ

Requisição

GET /v1/organizations/{orgId}/members

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

Headers

Header	Valor
`Authorization`	`Bearer {token}`

Parâmetros de rota

Parâmetro	Tipo	Obrigatório	Descrição
`orgId`	integer	Sim	ID da organização

Query parameters

Parâmetro	Tipo	Obrigatório	Descrição
`page`	integer	Não	Número da página, começando em `0`. Padrão: `0`
`size`	integer	Não	Itens por página. Padrão: `20`. Valores acima de `200` são reduzidos para `200`

Exemplo de requisição

curl -X GET "https://api.tapsign.com.br/v1/organizations/42/members?page=0&size=20" \
  -H "Authorization: Bearer {token}"

Resposta

Status: 200 OK

{
  "content": [
    {
      "id": 7,
      "userId": 1001,
      "userName": "Joao Silva",
      "userEmail": "[email protected]",
      "userImgUrl": null,
      "role": "OWNER",
      "active": true,
      "joinedAt": "2026-09-01T10:00:00Z"
    },
    {
      "id": 8,
      "userId": 1002,
      "userName": "Maria Santos",
      "userEmail": "[email protected]",
      "userImgUrl": null,
      "role": "MEMBER",
      "active": true,
      "joinedAt": "2026-09-12T14:30:00Z"
    }
  ],
  "totalElements": 2,
  "totalPages": 1,
  "size": 20,
  "number": 0
}

A resposta segue o formato de página do Spring. Os campos principais de paginação são totalElements, totalPages, size e number (página atual).

Campos do membro

Campo	Tipo	Descrição
`id`	integer	ID do membro na organização. É o `{memberId}` das rotas abaixo (não é o `userId`).
`userId`	integer	ID do usuário
`userName`	string	Nome do usuário
`userEmail`	string	E-mail do usuário
`userImgUrl`	string \| null	URL da foto do usuário
`role`	string	Papel: `OWNER`, `ADMIN`, `MEMBER` ou `VIEWER`
`active`	boolean	Se o membro está ativo
`joinedAt`	string	Data de ingresso na organização (ISO 8601, UTC)

Convidar membro

Cria um convite e envia um e-mail para a pessoa ingressar na organização. O convite vale por 7 dias.

Permissão necessária: MEMBERS:INVITE

Requisição

POST /v1/organizations/{orgId}/members/invite

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

Headers

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

Parâmetros de rota

Parâmetro	Tipo	Obrigatório	Descrição
`orgId`	integer	Sim	ID da organização

Body

Campo	Tipo	Obrigatório	Descrição
`email`	string	Sim	E-mail do convidado
`role`	string	Sim	Papel que o convidado terá: `ADMIN`, `MEMBER` ou `VIEWER`

Exemplo de requisição

curl -X POST https://api.tapsign.com.br/v1/organizations/42/members/invite \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "role": "MEMBER"
  }'

Resposta

Status: 201 Created

{
  "id": 15,
  "email": "[email protected]",
  "role": "MEMBER",
  "token": "3f6c2a1e-8b7d-4c1a-9e2f-5d4b3a2c1b0a",
  "status": "PENDING",
  "organizationName": "Empresa Exemplo LTDA",
  "inviterName": "Joao Silva",
  "expiresAt": "2026-09-19T14:30:00Z",
  "createdAt": "2026-09-12T14:30:00Z"
}

O token identifica o convite nas rotas de aceitar, recusar, cancelar e reenviar. Os campos do convite estão descritos em Convites.

Regras do convite

Não é possível convidar com o papel OWNER (retorna 400).
Se já existe um convite com status PENDING para o mesmo e-mail na organização, a API retorna 409.
Se a organização atingiu o limite de membros ativos (maxMembers), a API retorna 409.

Remover membro

Remove o membro da organização. O registro é desativado (active: false) e o membro deixa de ter acesso às rotas da organização.

Permissão necessária: MEMBERS:REMOVE

Requisição

DELETE /v1/organizations/{orgId}/members/{memberId}

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

Headers

Header	Valor
`Authorization`	`Bearer {token}`

Parâmetros de rota

Parâmetro	Tipo	Obrigatório	Descrição
`orgId`	integer	Sim	ID da organização
`memberId`	integer	Sim	ID do membro (campo `id` da listagem)

Exemplo de requisição

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

Resposta

Status: 204 No Content

Proprietário

O proprietário da organização (OWNER) não pode ser removido. A tentativa retorna 400.

Alterar papel do membro

Atualiza o papel de um membro na organização.

Permissão necessária: MEMBERS:EDIT_ROLE

Requisição

PUT /v1/organizations/{orgId}/members/{memberId}/role

URL completa: https://api.tapsign.com.br/v1/organizations/{orgId}/members/{memberId}/role

Headers

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

Parâmetros de rota

Parâmetro	Tipo	Obrigatório	Descrição
`orgId`	integer	Sim	ID da organização
`memberId`	integer	Sim	ID do membro

Body

Campo	Tipo	Obrigatório	Descrição
`role`	string	Sim	Novo papel: `ADMIN`, `MEMBER` ou `VIEWER`

Exemplo de requisição

curl -X PUT https://api.tapsign.com.br/v1/organizations/42/members/8/role \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "ADMIN"
  }'

Resposta

Status: 200 OK

{
  "id": 8,
  "userId": 1002,
  "userName": "Maria Santos",
  "userEmail": "[email protected]",
  "userImgUrl": null,
  "role": "ADMIN",
  "active": true,
  "joinedAt": "2026-09-12T14:30:00Z"
}

Papel OWNER

O papel do proprietário não pode ser alterado, e o papel OWNER não pode ser atribuído a outro membro. As duas tentativas retornam 400.

Permissões individuais do membro

Além do papel, cada membro pode ter permissões concedidas ou retiradas individualmente.

Consultar permissões efetivas

Permissão necessária: MEMBERS:READ

GET /v1/organizations/{orgId}/members/{memberId}/permissions

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

Status: 200 OK

{
  "memberId": 8,
  "permissions": [
    "DOCUMENTS:CREATE",
    "DOCUMENTS:READ",
    "MEMBERS:INVITE",
    "MEMBERS:READ",
    "TEMPLATES:READ"
  ]
}

permissions traz as permissões efetivas (papel mais ajustes) no formato RECURSO:AÇÃO. A ordem dos itens não é garantida.

Definir permissões

Permissão necessária: MEMBERS:EDIT_ROLE

PUT /v1/organizations/{orgId}/members/{memberId}/permissions

Campo	Tipo	Obrigatório	Descrição
`permissions`	string[]	Sim	Lista completa das permissões que o membro deve ter, no formato `RECURSO:AÇÃO`

curl -X PUT https://api.tapsign.com.br/v1/organizations/42/members/8/permissions \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": ["DOCUMENTS:CREATE", "DOCUMENTS:READ", "MEMBERS:INVITE", "MEMBERS:READ", "TEMPLATES:READ"]
  }'

Status: 200 OK, com o mesmo formato da consulta (memberId e permissions efetivas).

Como funciona

A API compara a lista enviada com as permissões padrão do papel do membro e guarda só as diferenças (concessões e retiradas). Enviar exatamente as permissões do papel remove todos os ajustes. Valores que não existem no catálogo de permissões são ignorados.

Papéis disponíveis

Papel	Descrição
`OWNER`	Proprietário. Criado junto com a organização e passa em todas as checagens de permissão. Não pode ser convidado, atribuído, removido nem ter o papel alterado.
`ADMIN`	Administrador. Por padrão tem todas as permissões do catálogo.
`MEMBER`	Membro. Por padrão cria, edita e envia documentos e modelos, e tem leitura de membros, pastas e contatos.
`VIEWER`	Leitor. Por padrão só tem leitura de documentos, modelos, membros, pastas e contatos.

Detalhes em Papéis e Permissões.

Erros comuns

Código	Quando acontece
`400`	Campo ausente ou inválido (o detalhe vem em `fields`), papel `OWNER` no convite ou na alteração, ou tentativa de remover ou alterar o papel do proprietário
`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`	Membro não encontrado nesta organização
`409`	Já existe convite pendente para o e-mail, ou a organização atingiu o limite de membros

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

Listar membros​

Requisição​

Headers​

Parâmetros de rota​

Query parameters​

Exemplo de requisição​

Resposta​

Campos do membro​

Convidar membro​

Requisição​

Headers​

Parâmetros de rota​

Body​

Exemplo de requisição​

Resposta​

Remover membro​

Requisição​

Headers​

Parâmetros de rota​

Exemplo de requisição​

Resposta​

Alterar papel do membro​

Requisição​

Headers​

Parâmetros de rota​

Body​

Exemplo de requisição​

Resposta​

Permissões individuais do membro​

Consultar permissões efetivas​

Definir permissões​

Papéis disponíveis​

Erros comuns​

Listar membros

Requisição

Headers

Parâmetros de rota

Query parameters

Exemplo de requisição

Resposta

Campos do membro

Convidar membro

Requisição

Headers

Parâmetros de rota

Body

Exemplo de requisição

Resposta

Remover membro

Requisição

Headers

Parâmetros de rota

Exemplo de requisição

Resposta

Alterar papel do membro

Requisição

Headers

Parâmetros de rota

Body

Exemplo de requisição

Resposta

Permissões individuais do membro

Consultar permissões efetivas

Definir permissões

Papéis disponíveis

Erros comuns