Enviar um pedido de adesão para uma pessoa (do lado do servidor)

POST

/v1/enroll

const url = 'https://api.vimine.network/v1/enroll';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"email":"hello@example.com","first_name":"example","last_name":"example","codicefiscale":"example","codicefiscale_confirmed":true,"guardian":{"first_name":"example","last_name":"example","relation":"example","codicefiscale":"example","email":"hello@example.com","phone":"example"},"address":{"kind":"residence","line":"example","postal_code":"example","city":"example","province":"example","country":"IT"},"phone":"example","dob":"2026-04-15","gender":"M","birthplace":"example","birth_country":"example","membership_type":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","locale":"example","accept_statuto":{"version":1,"sha256":"example"},"privacy_notice":{"version":1,"sha256":"example","locale":"example"},"accept_terms":{"version":"example","sha256":"example"},"acknowledge_privacy":{"version":"example","sha256":"example"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.vimine.network/v1/enroll \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "email": "hello@example.com", "first_name": "example", "last_name": "example", "codicefiscale": "example", "codicefiscale_confirmed": true, "guardian": { "first_name": "example", "last_name": "example", "relation": "example", "codicefiscale": "example", "email": "hello@example.com", "phone": "example" }, "address": { "kind": "residence", "line": "example", "postal_code": "example", "city": "example", "province": "example", "country": "IT" }, "phone": "example", "dob": "2026-04-15", "gender": "M", "birthplace": "example", "birth_country": "example", "membership_type": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "locale": "example", "accept_statuto": { "version": 1, "sha256": "example" }, "privacy_notice": { "version": 1, "sha256": "example", "locale": "example" }, "accept_terms": { "version": "example", "sha256": "example" }, "acknowledge_privacy": { "version": "example", "sha256": "example" } }'

Cria a identidade, quando o endereço é novo, e o pedido de adesão (emitido ACTIVE na hora para um tipo gratuito sem etapa de aprovação, senão PENDING até a associação registrar a taxa e/ou aprovar). Um endereço que já tem uma conta Vimine nunca é vinculado em silêncio: o dono dele recebe um link de confirmação e o pedido é criado quando ele o usa. Responde sempre 202. accept_statuto precisa indicar a versão do statuto em vigor (e o sha256, quando publicado). Só tokens de cliente (enroll:write); aceita Idempotency-Key.

Autorizações

BearerToken
enroll:write
ClientBasic

Corpo da requisição^obrigatório

application/json

object

email

obrigatório

string formato: email

first_name

obrigatório

string

<= 50 caracteres

last_name

obrigatório

string

<= 50 caracteres

codicefiscale

Opcional. Uma pessoa é identificada por um código fiscal OU por dob + birthplace + birth_country — nunca por nenhum dos dois (422 required em cada dado que falta). Quando presente, é validado e conferido com os nomes, a data e o local (o país, para quem nasceu no exterior)

string

nullable <= 16 caracteres

codicefiscale_confirmed

A pessoa confirma um código que não confere com os seus dados (422 codicefiscale_mismatch com confirmable: true)

boolean

guardian

Quem exerce o poder familiar sobre um menor de idade (menos de 18 anos pelo dob). OBRIGATÓRIO para um menor quando a associação declarou que coleta este bloco (aps.collects_guardian_data): senão, 422 required em guardian; guardado só quando ela o declarou

object

first_name

obrigatório

string

<= 50 caracteres

last_name

obrigatório

string

<= 50 caracteres

relation

obrigatório

Genitor, tutor… como a associação o registra

string

<= 20 caracteres

codicefiscale

Opcional; recusado quando malformado

string

nullable <= 16 caracteres

email

string formato: email

nullable

phone

string

nullable <= 20 caracteres

address

Residência ou, quando diferente, domicílio. Pedido a todos os associados ou a nenhum: o perfil público diz o que a associação declarou (member_address: none — ignorado, não guardado · optional · required — 422 required em address sem ele)

object

kind

string

padrão: residence

Valores permitidos: residence domicile

line

obrigatório

Rua e número

string

<= 150 caracteres

postal_code

string

nullable <= 12 caracteres

city

obrigatório

string

<= 150 caracteres

province

Só endereços italianos (duas letras); descartado no exterior

string

nullable <= 2 caracteres

country

ISO 3166-1 alpha-2

string

padrão: IT >= 2 caracteres <= 2 caracteres

phone

string

nullable <= 20 caracteres

dob

string formato: date

nullable

gender

Só estatístico: não é conferido

string

nullable

Valores permitidos: M F

birthplace

Comune (nascidos na Itália) ou cidade, texto livre (nascidos no exterior)

string

nullable <= 150 caracteres

birth_country

ISO 3166-1 alpha-2

string

nullable >= 2 caracteres <= 2 caracteres

membership_type

Um dos tipos de carteirinha da associação (omita quando ela tem exatamente um)

string formato: uuid

locale

O idioma da página que a pessoa preencheu (um idioma da plataforma — it, en, …; qualquer outra tag é associada a um dos idiomas da plataforma: en-GB → en, zh-TW → zh-Hant). Ele decide o idioma dos e-mails que vêm depois e se torna a preferência de uma conta NOVA; uma conta existente mantém a sua. Valores não suportados são ignorados

string

nullable

accept_statuto

obrigatório

O statuto em vigor que a pessoa aceitou no seu site (de GET /v1/aps/{slug})

object

version

obrigatório

integer

sha256

string

privacy_notice

O aviso de privacidade da associação que a pessoa leu no seu site (GET /v1/aps/{slug} → privacy_notice). OBRIGATÓRIO quando a associação publica um; 422 privacy_notice_outdated quando não é a versão em vigor

object

version

obrigatório

A versão em vigor do aviso que foi mostrada (GET /v1/aps/{slug} → privacy_notice)

integer

sha256

string

locale

O idioma do aviso que você mostrou (privacy_notice.locale da resposta da qual você o leu). Cada idioma é um documento próprio, com a sua própria versão: indique-o quando você ler o perfil com ?locale=. Padrão: o locale da requisição, depois o idioma da associação

string

accept_terms

As condições de uso da conta (platform_terms) que a pessoa aceitou no seu site — opcional, deve indicar a versão em vigor

object

version

obrigatório

O rótulo da versão em vigor que foi mostrada (GET /v1/legal/{kind})

string

sha256

O hash do seu modelo, quando publicado

string

acknowledge_privacy

O aviso de privacidade da plataforma (platform_privacy) que a pessoa leu — opcional, mesma regra

object

version

obrigatório

O rótulo da versão em vigor que foi mostrada (GET /v1/legal/{kind})

string

sha256

O hash do seu modelo, quando publicado

string

Respostas

202

Aceito

application/json

object

status

obrigatório

string

Valores permitidos: accepted

Exemplo

{
  "status": "accepted"
}

400

Requisição inválida

application/problem+json

object

type

obrigatório

string formato: uri

title

obrigatório

string

status

obrigatório

integer

detail

string

code

obrigatório

string

request_id

string

errors

Array<object>

object

field

string

code

string

message

string

Exemplo^gerado

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "request_id": "example",
  "errors": [
    {
      "field": "example",
      "code": "example",
      "message": "example"
    }
  ]
}

401

Credenciais ausentes ou inválidas

application/problem+json

object

type

obrigatório

string formato: uri

title

obrigatório

string

status

obrigatório

integer

detail

string

code

obrigatório

string

request_id

string

errors

Array<object>

object

field

string

code

string

message

string

Exemplo^gerado

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "request_id": "example",
  "errors": [
    {
      "field": "example",
      "code": "example",
      "message": "example"
    }
  ]
}

403

A associação não aceita pedidos de adesão (api_disabled)

404

Não encontrado

application/problem+json

object

type

obrigatório

string formato: uri

title

obrigatório

string

status

obrigatório

integer

detail

string

code

obrigatório

string

request_id

string

errors

Array<object>

object

field

string

code

string

message

string

Exemplo^gerado

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "request_id": "example",
  "errors": [
    {
      "field": "example",
      "code": "example",
      "message": "example"
    }
  ]
}

422

Falha na validação, tipo de carteirinha desconhecido ou accept_statuto não indica o statuto em vigor

429

Limite de requisições excedido

application/problem+json

object

type

obrigatório

string formato: uri

title

obrigatório

string

status

obrigatório

integer

detail

string

code

obrigatório

string

request_id

string

errors

Array<object>

object

field

string

code

string

message

string

Exemplo^gerado

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "request_id": "example",
  "errors": [
    {
      "field": "example",
      "code": "example",
      "message": "example"
    }
  ]
}

500

Erro interno

application/problem+json

object

type

obrigatório

string formato: uri

title

obrigatório

string

status

obrigatório

integer

detail

string

code

obrigatório

string

request_id

string

errors

Array<object>

object

field

string

code

string

message

string

Exemplo^gerado

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "request_id": "example",
  "errors": [
    {
      "field": "example",
      "code": "example",
      "message": "example"
    }
  ]
}

Enviar um pedido de adesão para uma pessoa (do lado do servidor)

Autorizações

Corpo da requisiçãoobrigatório

Respostas

202

Exemplo

400

Exemplogerado

401

Exemplogerado

403

404

Exemplogerado

422

429

Exemplogerado

500

Exemplogerado

Corpo da requisição^obrigatório

Exemplo^gerado

Exemplo^gerado

Exemplo^gerado

Exemplo^gerado

Exemplo^gerado