Convida membros por e-mail
POST/api/members/invite
- Auth
- Requires a token
- Who can call it:
- owner
- admin
- X-CommunityId
X-CommunityIdSend the X-CommunityId of the community the operation happens in.
Owner e admin da comunidade do `X-CommunityId` (obrigatório; o `communityId` no corpo deixou de ser lido e, se vier diferente do header, a resposta é 403). Owner e admin podem dar qualquer papel atribuível, admin inclusive (a mesma regra da promoção). Owner nunca é dado na entrada. Cada e-mail tem o seu resultado em `data.results` (`status`: `invited`, `updated` ou `skipped`, com `reason` e `message` traduzida): um e-mail inválido ou repetido na lista não derruba os outros. `groupIds` e `tags` valem para todos: quem entra fica nos grupos (além dos grupos padrão) e com as tags; quem **já é membro** ganha os grupos e as tags que faltam (nada é tirado; papel e nome não mudam), não recebe e-mail e conta como `updated`. Sem grupos nem tags, quem já é membro volta como `skipped` com `reason: alreadyMember`. E-mail que pediu para não participar da comunidade volta como `skipped` com `reason: optedOut` e nada é enviado. **Nome (um só por pessoa):** mande `people` (`[{ email, name }]`) em vez de, ou junto com, `emails`. Conta nova nasce com o `name`. Conta que já existe só adota o `name` se o nome dela ainda é provisório (vazio ou a parte do e-mail antes do @) e ela não está em nenhuma outra comunidade; senão o `name` vira o nome dela só nesta comunidade (`displayName`), e um nome de verdade nunca é sobrescrito. O `displayName` do perfil fica igual ao nome que aparece, a não ser que venha `displayName`: um nome diferente só nesta comunidade. Cada convidado novo recebe e-mail pela fila (a resposta não espera o envio): conta nova recebe o link de uso único `https://<app da comunidade>/_/auth/set-password?id=&token=`, válido por 7 dias (ver `POST /api/auth/set-password`); quem já tem conta recebe "você foi adicionado(a) à comunidade" com o link de entrada. Nenhuma senha é gerada nem devolvida. Até 500 e-mails por chamada. **Comunidade suspensa pela Memberfy**: 403 com `errors`, `code: COMMUNITY_SUSPENDED` e o motivo (em `message` e em `reason`) para owner, admin, moderador e financeiro; nada é criado nem enviado.
Headers
| Name | Type | Description |
|---|---|---|
X-CommunityIdoptional | string (uuid) | ID da comunidade em que a operação acontece. Obrigatório na maioria dos endpoints com escopo de comunidade. |
Request body application/json
| Name | Type | Description |
|---|---|---|
emailsoptional | object | E-mails sem nome. Obrigatório se não vier `people`. |
peopleoptional | object[] | Convidados com nome. Os e-mails se somam aos de `emails` (até 500 no total). |
people[].emailrequired | string | |
people[].nameoptional | string | Nome da pessoa. · max 100 |
people[].displayNameoptional | string | Nome diferente só nesta comunidade (opcional). · max 100 |
rolerequired | admin | moderator | member | finance | |
groupIdsoptional | string (uuid)[] | Grupos da comunidade para todos os convidados. |
tagsoptional | string[] | Tags para todos os convidados (sem distinguir maiúsculas). |
communityIdoptional | string (uuid) | Ignorado; a comunidade é o `X-CommunityId`. Diferente do header, 403. |
Responses
| Status | Description |
|---|---|
201 | Lista processada, um resultado por e-mail. |
400 | Requisição inválida — falha de validação. |
401 | Token ausente, inválido ou expirado; token de outra comunidade (o `X-CommunityId` ou o `communityId` do corpo não é o do token); token anterior à F-31 F3 ou de uma sessão encerrada (troca de senha, convite aceito). Nesses casos a mensagem pede para entrar de novo (`auth.signInAgain`). |
403 | Autenticado, mas sem permissão para esta operação. |
500 | Erro interno do servidor. |
curl example
curl -X POST "https://api.memberfy.net/api/members/invite" \
-H "Authorization: Bearer $TOKEN" \
-H "X-CommunityId: $COMMUNITY_ID" \
-H "Content-Type: application/json" \
-d '{"role":"admin"}'