Permisos, errores y límites

Permisos (scopes)

Un cliente solicita los permisos al registrarse; el socio los ve en la página de consentimiento.

Scope	Quién	Qué
profile:read	socio	GET /v1/me — nombre, correo, datos de contacto, datos de nacimiento, el código fiscal cuando lo hay, y cómo está identificada la persona (codicefiscale_check)
profile:write	socio	PATCH /v1/me — teléfono, sexo, y la identificación: fecha, lugar y país de nacimiento, código fiscal (opcional, se puede añadir más tarde; se vuelve a validar)
membership:read	socio	GET /v1/me/membership, /events, /statuto, /card
membership:request	socio	POST /v1/me/membership — solicitud de inscripción
statuto:accept	socio	POST /v1/me/membership/statuto/accept
network:manage	socio	el consentimiento del socio a los circuitos (próximamente)
memberships:read	cliente	GET /v1/memberships/{id}/status
verify:read	cliente	verificación de carnés por encima de la cuota anónima
identity:signup	cliente	POST /v1/signup — crear cuentas en nombre de los socios (integraciones de servidor)
enroll:write	cliente	POST /v1/enroll — enviar solicitudes de inscripción, con o sin código fiscal (guía)
events:read	socio	GET /v1/events, /v1/events/{slug}, /eligibility — incluidos los eventos solo para socios (guía)
registrations:read	socio, cliente	GET /v1/me/registrations (socio); GET /v1/events/{slug}/registrations (cliente, sin datos personales)
registrations:write	socio, cliente	POST /v1/events/{slug}/registrations y DELETE /v1/me/registrations/{id} (socio); POST …/registrations/guest (cliente)
checkins:write	cliente	POST /v1/checkins — check-in en la entrada a partir de un carné o de una inscripción
webhooks:manage	cliente	próximamente

Un cliente público o nativo solo puede solicitar permisos de socio; los permisos de «cliente» requieren un cliente confidencial. Quien todavía no es socio solo puede conceder los permisos de inscripción (profile:*, membership:read, membership:request, statuto:accept).

Errores

Las respuestas de error son 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": "…"
}

code es estable: ramifica tu lógica sobre él. errors[] acompaña a validation_failed y a identification_required ({ field, code }). Una entrada codicefiscale_mismatch — un código fiscal que no coincide con los datos de nacimiento de la persona — lleva además mismatches, hints y confirmable: cuando confirmable es true, la persona puede confirmar el código y la solicitud se repite con codicefiscale_confirmed: true (consulta Socios sin código fiscal). Los endpoints OAuth (/v1/oauth/token, /revoke) responden con el formato OAuth ({ error, error_description }).

code	Significado
missing_token, invalid_token, token_expired	401 — vuelve a iniciar sesión (el SDK renueva y repite por sí solo)
insufficient_scope	403 — al token le falta ese permiso
api_disabled	403 — la asociación no ha activado la API o no acepta solicitudes
plan_limit	403 — el plan de la asociación no tiene sitio para un socio más (comprueba aps.accepting_requests antes de mostrar el formulario)
not_available	403 — la asociación no acepta solicitudes en este momento: todavía no ha aceptado los acuerdos de la plataforma o no ha registrado su estatuto, no está lista, o solo admite a las personas que ha invitado (la beta privada); detail dice cuál de los casos. En POST /v1/signup: durante la beta, las cuentas se crean por invitación
not_found	404 — también para recursos de otras asociaciones
validation_failed	422 — consulta errors[] (required, invalid, invalid_codicefiscale, codicefiscale_mismatch con confirmable…)
identification_required	422 en POST /v1/me/membership, 409 en POST /v1/enroll/confirm — la persona no está identificada: hace falta un código fiscal, o la fecha, el lugar y el país de nacimiento; errors[] indica lo que falta
statuto_outdated, statuto_required	422 — indica la versión del estatuto en vigor (detail)
rate_limited	429 — espera Retry-After
unavailable	503 — vuelve a intentarlo dentro de poco

OAuth: invalid_grant (código o refresh token no válido, caducado o reutilizado), invalid_client, invalid_scope, unauthorized_client (cliente pendiente de activación), access_denied (el socio ha cancelado).

En el SDK todo esto es un VimineError con el mismo code.

La beta privada

Vimine está en beta privada: las personas y las asociaciones entran por invitación. Para un cliente, esto significa:

• POST /v1/signup responde 403 not_available y no crea nada, salvo que Vimine haya abierto la inscripción pública de tu asociación;
• una asociación que solo admite a las personas que ha invitado tiene aps.invitation_only: true y aps.accepting_requests: false en su perfil público (association(slug)); POST /v1/enroll y POST /v1/me/membership responden 403 not_available. Quien tiene una invitación se une desde el enlace que recibe por correo;
• los sandbox siguen abiertos: los clientes de prueba funcionan como siempre.

Comprueba aps.accepting_requests antes de mostrar un formulario de inscripción — tanto para la beta como para todo lo demás; <vimine-events> y <vimine-enroll> ya lo hacen.

Límites

• Por dirección IP: 60 peticiones/minuto en los endpoints sensibles (verificación de carnés, código fiscal, token), 120/minuto en los demás; RateLimit-* y Retry-After en las respuestas.
• POST /v1/me/membership acepta Idempotency-Key: la misma clave en un plazo de 24 horas devuelve la misma respuesta (el SDK genera una por llamada).
• Las respuestas autenticadas son Cache-Control: no-store.
• Cada respuesta lleva un request_id: indícalo cuando informes de un problema.