Permissões, erros e limites

Permissões (escopos)

Um cliente pede permissões quando é registrado; o associado as vê na página de consentimento.

Escopo	Quem	O quê
profile:read	associado	GET /v1/me — nome, e-mail, contatos, dados de nascimento, o código fiscal quando existe, e como a pessoa está identificada (codicefiscale_check)
profile:write	associado	PATCH /v1/me — telefone, sexo, e a identificação: data, local e país de nascimento, código fiscal (opcional, pode ser adicionado depois; validado de novo)
membership:read	associado	GET /v1/me/membership, /events, /statuto, /card
membership:request	associado	POST /v1/me/membership — pedido de adesão
statuto:accept	associado	POST /v1/me/membership/statuto/accept
network:manage	associado	o consentimento do associado aos circuitos (em breve)
memberships:read	cliente	GET /v1/memberships/{id}/status
verify:read	cliente	verificação das carteirinhas além da cota anônima
identity:signup	cliente	POST /v1/signup — criar contas em nome dos associados (integrações de servidor)
enroll:write	cliente	POST /v1/enroll — enviar pedidos de adesão, com ou sem código fiscal (guia)
events:read	associado	GET /v1/events, /v1/events/{slug}, /eligibility — incluindo os eventos só para associados (guia)
registrations:read	associado, cliente	GET /v1/me/registrations (associado); GET /v1/events/{slug}/registrations (cliente, sem dados pessoais)
registrations:write	associado, cliente	POST /v1/events/{slug}/registrations e DELETE /v1/me/registrations/{id} (associado); POST …/registrations/guest (cliente)
checkins:write	cliente	POST /v1/checkins — check-ins na entrada a partir de uma carteirinha ou de uma inscrição
webhooks:manage	cliente	em breve

Um cliente público ou nativo só pode pedir permissões de associado; as permissões de “cliente” exigem um cliente confidencial. Quem ainda não é associado só pode conceder as permissões de adesão (profile:*, membership:read, membership:request, statuto:accept).

Erros

As respostas de erro são application/problem+json (RFC 9457):

{
  "type": "https://developers.vimine.network/errors/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "Missing scope: profile:write",
  "request_id": "…"
}

O code é estável: tome as suas decisões com base nele. errors[] acompanha validation_failed e identification_required ({ field, code }). Uma entrada codicefiscale_mismatch — um código fiscal que não confere com os dados de nascimento da pessoa — também traz mismatches, hints e confirmable: quando confirmable é true a pessoa pode confirmar o código e o pedido é repetido com codicefiscale_confirmed: true (veja Associados sem código fiscal). Os endpoints OAuth (/v1/oauth/token, /revoke) respondem no formato OAuth ({ error, error_description }).

code	Significado
missing_token, invalid_token, token_expired	401 — entre de novo (o SDK renova e repete sozinho)
insufficient_scope	403 — falta essa permissão ao token
api_disabled	403 — a associação não ativou a API ou não aceita pedidos
plan_limit	403 — o plano da associação não tem espaço para mais um associado (verifique aps.accepting_requests antes de mostrar o formulário)
not_available	403 — a associação não está recebendo pedidos agora: ainda não aceitou os acordos da plataforma ou não registrou o seu statuto, não está pronta, ou só recebe as pessoas que convidou (o beta privado); detail diz qual é o caso. Em POST /v1/signup: durante o beta, as contas são criadas por convite
not_found	404 — também para os recursos de outras associações
validation_failed	422 — veja errors[] (required, invalid, invalid_codicefiscale, codicefiscale_mismatch com confirmable…)
identification_required	422 em POST /v1/me/membership, 409 em POST /v1/enroll/confirm — a pessoa não está identificada: é preciso um código fiscal, ou data, local e país de nascimento; errors[] indica o que falta
statuto_outdated, statuto_required	422 — indica a versão do statuto em vigor (detail)
rate_limited	429 — espere Retry-After
unavailable	503 — tente de novo daqui a pouco

OAuth: invalid_grant (código ou refresh token inválido, vencido ou reutilizado), invalid_client, invalid_scope, unauthorized_client (cliente aguardando ativação), access_denied (o associado cancelou).

No SDK, tudo isso é um VimineError com o mesmo code.

O beta privado

O Vimine está em beta privado: pessoas e associações entram por convite. Para um cliente, isso quer dizer:

• POST /v1/signup responde 403 not_available e não cria nada, a não ser que o Vimine tenha aberto a adesão pública da sua associação;
• uma associação que só recebe as pessoas que convidou tem aps.invitation_only: true e aps.accepting_requests: false no seu perfil público (association(slug)); POST /v1/enroll e POST /v1/me/membership respondem 403 not_available. Quem tem um convite se associa pelo link que recebe por e-mail;
• os sandboxes continuam abertos: os clientes de teste funcionam como sempre.

Verifique aps.accepting_requests antes de mostrar um formulário de adesão — para o beta como para todo o resto; <vimine-events> e <vimine-enroll> já fazem isso.

Limites

• Por endereço IP: 60 requisições/minuto nos endpoints sensíveis (verificação das carteirinhas, código fiscal, token), 120/minuto no resto; RateLimit-* e Retry-After nas respostas.
• POST /v1/me/membership aceita Idempotency-Key: a mesma chave dentro de 24 horas devolve a mesma resposta (o SDK gera uma por chamada).
• As respostas autenticadas são Cache-Control: no-store.
• Toda resposta traz um request_id: informe-o quando relatar um problema.