Aller au contenu
memberfy
FR

Reanalisa a planilha e, com o mapeamento, devolve o resumo

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

Auth
Jeton requis
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; só enquanto a importação está `ANALYZED`. Com `sheet`, `headerRow` (1 a 30), `delimiter` (`,` `;` tab `|`) ou `encoding` (`utf-8`, `windows-1252`, `iso-8859-1`, `utf-16le`, `utf-16be`), devolve a análise de novo. Com `mapping` (e `options`), devolve também `summary`, o resumo do passo 4: linhas, pessoas novas, já membros (recebem grupos, tags e campos vazios), ignoradas por motivo (`NO_EMAIL`, `INVALID_EMAIL`, `DUPLICATE_IN_FILE`, `NO_CONSENT`), `declined` (pediram para não participar, fora de `skipped`), e-mails a enviar e os grupos, tags e campos que serão criados. `unknownOptions` lista, por campo `SELECT` ou `MULTI_SELECT` mapeado, os valores da planilha que ainda não são opções do campo (até 50 por campo): sem virar opção, a célula entra com aviso e sem valor; para virarem opção, acrescente-os ao campo (`PATCH /api/member-fields/{id}`) antes de confirmar. Não grava nada. Com uma coluna `badges` ou `points`, o resumo traz `badges` (`unknown`: nomes que não estão no catálogo, `ignored`, `grants`: quantos badges serão concedidos) e `points` (`rows`, `invalidCount` e `invalid` com até 50 linhas `{ rowNumber, value }`, `alreadyImported`: pessoas que já receberam pontos de uma importação e não recebem de novo, `gamificationOff`: com a gamificação desligada os pontos são ignorados, e `levels`: em que nível as pessoas com pontos vão ficar, `[{ level, name, count }]`, contando que quem chega pela importação ainda não tem atividade da semana). O mapeamento exige exatamente uma coluna `email`; `firstName`, `lastName`, `phone`, `jobTitle`, `tagline`, `consent`, `badges` e `points` aceitam uma coluna cada (duas colunas para o mesmo destino são recusadas); `tags` e `groups` aceitam várias.

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
delimiterfacultatif, | ; | | |
encodingfacultatifstring
mappingfacultatifobject[]
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
optionsfacultatifobject
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
200A análise, com `summary` quando veio o mapeamento.
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.
409A importação já foi 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>/preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CommunityId: $COMMUNITY_ID" \
  -H "Content-Type: application/json" \
  -d '{}'