Convites

Proprietários e administradores da Organization adicionam colegas de equipe ao Tokeflow Dashboard enviando convites. O convidado recebe um e-mail com um link que carrega um token de convite assinado e de uso único. Os três endpoints desta página alimentam esse fluxo de aterrissagem: a UI do Dashboard primeiro verifica o token para mostrar quem está convidando quem e para qual função, e então o convidado aceita (criando antes uma conta de usuário, caso ainda não tenha uma) ou recusa.

Aceitar um convite concede ao convidado uma associação na organization com a função escolhida por quem convidou — owner, admin, ou viewer. Os papéis e o que cada um pode ver estão descritos em Organizations e Merchants.

Como o fluxo funciona

Sempre verifique antes de renderizar um formulário de aceite: a flag is_new_user no resultado da verificação informa se você deve pedir uma senha ao convidado (conta nova) ou apenas confirmar (conta existente).

O objeto de resultado da verificação

GET /api/v1/invitations/verify retorna este objeto. Apenas valid está sempre presente; os campos descritivos são anuláveis (nullable) e são o que o Dashboard exibe na página de aterrissagem do convite.

Endpoints

GET/api/v1/invitations/verify

Verifica um token de convite e retorna os detalhes necessários para renderizar a página de aterrissagem do convite: quem convidou, para qual organization e papel, quando o convite expira, e se o convidado precisa criar uma conta.

Parâmetros de consulta

Exemplo de requisição

curl -G https://api.tokeflow.com/api/v1/invitations/verify \
  --data-urlencode "token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"

Exemplo de resposta — 200 OK

{
  "valid": true,
  "email": "jane@acme.com",
  "organization_name": "Acme Digital",
  "role": "admin",
  "inviter_name": "Carlos Prado",
  "expires_at": "2026-08-19T12:00:00.000Z",
  "is_new_user": true
}

Exemplo de resposta — 200 OK, token expirado

{
  "valid": false,
  "email": null,
  "organization_name": null,
  "role": null,
  "inviter_name": null,
  "expires_at": null,
  "is_new_user": false
}

POST/api/v1/invitations/accept

Aceita um convite e concede ao convidado uma associação na organization. Quando o convite é para um novo usuário (is_new_user: true no resultado da verificação), inclua password e confirm_password — a conta de usuário é criada com essa senha como parte do aceite.

Campos da requisição

Exemplo de requisição — novo usuário

curl -X POST https://api.tokeflow.com/api/v1/invitations/accept \
  -H "Content-Type: application/json" \
  -d '{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
    "name": "Jane Doe",
    "password": "mySecureP@ss123",
    "confirm_password": "mySecureP@ss123"
  }'

Exemplo de requisição — usuário existente

curl -X POST https://api.tokeflow.com/api/v1/invitations/accept \
  -H "Content-Type: application/json" \
  -d '{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" }'

Resposta — 201 Created

Um aceite bem-sucedido retorna 201 Created com corpo vazio. O convidado agora pode fazer login no Dashboard com seu e-mail e senha.

POST/api/v1/invitations/decline

Recusa um convite. O token é consumido e o convidado não é adicionado à organization; quem convidou sempre pode enviar um novo convite depois.

Campos da requisição

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/invitations/decline \
  -H "Content-Type: application/json" \
  -d '{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" }'

Resposta — 201 Created

Uma recusa bem-sucedida retorna 201 Created com corpo vazio.

Erros

Os casos mais comuns para estes endpoints:

Consulte Erros para o formato geral de erro usado em toda a API.

Relacionados

• Autenticação do Dashboard — faça login depois de aceitar um convite.
• Organizations e Merchants — como organizations, papéis e merchants se encaixam.
• Logs de auditoria — alterações de associação aparecem na trilha de auditoria da organization.