Aller au contenu
memberfy
FR

Confirma e enfileira a importação

POST/api/members/imports/{id}/start

Auth
Jeton requis
Qui peut l’appeler:
moderator
Clé d’API:
members:write
X-CommunityId
X-CommunityId Envoyez le X-CommunityId de la communauté où l’opération a lieu.
Les descriptions des endpoints viennent directement de la spécification de l’API et sont en portugais pour l’instant. L’interface autour est traduite.

Owner e admin. Recebe o mesmo corpo do preview, com `mapping` e `options` obrigatórios: `role` só `member` ou `moderator`; `origin` obrigatória (até 150 caracteres, texto simples, sem link; vai no e-mail, escapada); com coluna `consent`, `consentValues` não vazio; sem ela, `consentDeclaration: true`. O clique é a confirmação: grupos e tags que faltam (da coluna Grupos/Tags) e os campos `newField` são criados no processamento, sem outra etapa. Responde **202** antes de qualquer e-mail: o processamento é assíncrono (fila, lotes de 200 linhas, retomável). Cada pessoa nova recebe o convite da importação (conta nova: link de definir senha, 7 dias; conta existente: "você foi adicionado(a)"), com a origem e o link "Agradeço o convite, mas não quero participar"; quem já era membro não recebe. Os envios não contam na cota de campanhas. Ao terminar, quem importou recebe um e-mail com o resumo. Acompanhe em `GET /api/members/imports/{id}`. **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. Suspensa durante o processamento, a importação para no próximo lote: vira `INTERRUPTED`, as linhas restantes não criam perfil, nenhum convite a mais sai e quem importou recebe o resumo dizendo que foi interrompida pela suspensão.

Paramètres

NomEmplacementTypeDescription
idobligatoirepathstring (uuid)

En-têtes

NomTypeDescription
X-CommunityIdfacultatifstring (uuid)ID da comunidade em que a operação acontece. Obrigatório na maioria dos endpoints com escopo de comunidade.

Corps de la requête application/json

NomTypeDescription
sheetfacultatifstring
headerRowfacultatifinteger≥ 1, ≤ 30
delimiterfacultatifstring
encodingfacultatifstring
mappingobligatoireobject[]
mapping[].columnobligatoireintegerO `index` da coluna, como veio na análise.
mapping[].targetobligatoireignore | email | firstName | lastName | phone | jobTitle | tagline | tags | groups | groupsExpireAt | consent | smsConsent | whatsappConsent | field | newField | badges | pointsDestino da coluna. `smsConsent` é o consentimento de SMS de serviço da linha: só conta com `smsConsentAttestation: true` (a responsabilidade pela declaração é da comunidade) e vale também para quem já é membro (2026-10-28), exceto quem saiu do canal ou retirou o consentimento (aviso `CONSENT_WITHDRAWN`); "não", vazio ou sem a coluna, nada é gravado. O telefone da linha, com a atestação, já pode receber SMS e WhatsApp enquanto for o telefone do perfil (2026-10-28), mas fica não verificado: códigos de acesso só vão para número confirmado pela própria pessoa. `whatsappConsent` (2026-10-27) é o mesmo para o WhatsApp, com `whatsappConsentValues` e `whatsappConsentAttestation` próprios. Em quem já é membro, o `phone` da linha substitui o do perfil (não verificado), exceto um número verificado diferente (aviso `PHONE_KEPT_VERIFIED`) ou o perfil de owner numa importação de admin. `jobTitle` é o Cargo do perfil (até 100 caracteres) e `tagline` a Biografia (até 200); o que passar é cortado e a linha entra com o aviso `TOO_LONG`. Em quem já é membro, os dois só preenchem o que está vazio. `groupsExpireAt` (uma coluna por importação) é o "Válido até" dos grupos que a linha dá à pessoa (os da coluna Grupos e os da importação), inclusive os que ela já tinha: data `dd/mm/aaaa` (`mm/dd/aaaa` em en-US) ou `aaaa-mm-dd`, válida o dia inteiro no fuso da comunidade. Data inválida ou que já passou: a linha entra com o aviso `INVALID_VALUE` e os grupos ficam permanentes. `badges` (uma coluna) concede os badges do catálogo da comunidade, nomes separados por `;` (sem diferenciar maiúsculas e acentos), com a origem `import`: quem já tem o badge fica como está; nome que não está no catálogo aparece em `summary.badges.unknown` e precisa ser criado no catálogo (`POST /api/badges`) ou ignorado em `ignoreNames` antes do start (senão 400 `badgesUnknown`). `points` (uma coluna) são os pontos iniciais, inteiro de 1 a 100.000 (`1.500` e `250.0` também valem): vazio ou 0 não faz nada, outro valor entra com o aviso `INVALID_POINTS` e sem pontos; viram um ajuste com o motivo "Importação" só com a gamificação ligada e nunca duas vezes para a mesma pessoa (aviso `POINTS_ALREADY_IMPORTED`). Badges e pontos da importação não mandam e-mail nem sino e não disparam "Recebeu badge", "Subiu de nível" nem "Atingiu N pontos"; o webhook `badge.awarded` sai com `source: import`.
mapping[].ignoreNamesfacultatifstring[]Com `badges`: nomes da coluna que não estão no catálogo e devem ser ignorados.
mapping[].fieldKeyfacultatifstringCom `field`: a `key` de um campo customizado existente. Num campo `MULTI_SELECT`, a célula lista as opções separadas por `;` ou `,` ("Linux; Cloud"), pelo rótulo ou pelo `value`, sem diferenciar maiúsculas nem acentos.
mapping[].newFieldfacultatifobjectCom `newField`: o campo criado na hora, sempre opcional. `SELECT` ganha como opções os valores distintos da coluna; `MULTI_SELECT`, os itens distintos das células (de 2 a 50; fora disso o campo nasce `TEXT`).
mapping[].newField.labelfacultatifstringmax 120
mapping[].newField.typefacultatifTEXT | NUMBER | DATE | SELECT | BOOLEAN | MULTI_SELECT
optionsobligatoireobject
options.rolefacultatifmember | moderator
options.groupIdsfacultatifstring (uuid)[]
options.tagsfacultatifstring[]
options.originfacultatifstringDe onde veio a lista. Obrigatória no start; texto simples, sem link; vai no e-mail. · max 150
options.consentValuesfacultatifstring[]Com uma coluna `consent`: os valores que contam como sim.
options.consentDeclarationfacultatifbooleanSem coluna `consent`: a declaração aceita (obrigatória no start).
options.smsConsentValuesfacultatifstring[]Com uma coluna `smsConsent`: os valores que contam como sim. Padrão: sim, s, yes, y, true, 1, x, si, sí, ja.
options.smsConsentAttestationfacultatifbooleanA comunidade atesta que coletou o consentimento de SMS de quem tem sim na coluna. A data do start fica gravada (`smsConsentAttestedAt` da importação) em cada consentimento, com origem `import`. Sem a atestação, nenhum sim conta.
options.whatsappConsentValuesfacultatifstring[]Com uma coluna `whatsappConsent`: os valores que contam como sim (mesmo padrão do SMS).
options.whatsappConsentAttestationfacultatifbooleanA comunidade atesta que coletou o consentimento de WhatsApp de quem tem sim na coluna (`whatsappConsentAttestedAt` da importação, origem `import`). Só para quem a importação cria.

Réponses

StatutDescription
202Enfileirada.
400Requisição inválida — falha de validação.
401Token ausente, inválido ou expirado; token de outra comunidade (o `X-CommunityId` ou o `communityId` do corpo não é o do token); token antigo ou de uma sessão encerrada (troca de senha, convite aceito). Nesses casos a mensagem pede para entrar de novo (`auth.signInAgain`).
403Autenticado, mas sem permissão para esta operação.
404Recurso não encontrado.
409Já confirmada ou abandonada.
429Outra planilha está sendo lida nesta comunidade (uma por vez) ou no servidor. Tente de novo em instantes (`reason: busy`).

Exemple curl

curl -X POST "https://api.memberfy.net/api/members/imports/<id>/start" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CommunityId: $COMMUNITY_ID" \
  -H "Content-Type: application/json" \
  -d '{"mapping":[{}],"options":{}}'