# Visión general

> Lo que la API de Vimine ofrece a quien desarrolla para una asociación, y los conceptos que conviene conocer antes de empezar.

URL: https://developers.vimine.network/es/start/overview/

Vimine es la plataforma de gestión de socios para las APS y las entidades italianas del Tercer Sector. Cada
asociación tiene sus socios, sus carnés, su estatuto; con la API, un sitio web o una app **de la asociación, o hecho
para la asociación**, puede usar todo eso sin reconstruir nada.

## Qué puedes hacer

| | Cómo | Con qué credenciales |
|---|---|---|
| **Iniciar sesión con Vimine** — los socios entran en tu sitio con su cuenta | OAuth 2.1 + PKCE, página de inicio de sesión y de consentimiento en vimine.network | un cliente *público* o *nativo* (solo `client_id`) |
| **API de socios** — perfil, carné y veredicto, solicitud de inscripción, estatuto, apps conectadas | `GET /v1/me`, `/v1/me/membership`, … con el token del socio | los permisos que el socio ha concedido |
| **Integraciones de servidor** — los sistemas de la propia asociación consultan el estado de los carnés | `client_credentials` | un cliente *confidencial* (`client_id` + `client_secret`) |
| **Verificación de carnés** — «¿este carné está activo ahora mismo?», también sin conexión | `GET /v1/verify/{card_token}`, claves públicas Ed25519 | ninguna |
| **Perfil público e inscripción** — imagen de la asociación, tipos de carné, estatuto en vigor; formulario de inscripción | `GET /v1/aps/{slug}`, página `enroll` integrable | ninguna |

## Conceptos

- **Asociación y slug.** Cada asociación tiene un *slug* (`https://app.vimine.network/enroll/<slug>`); los
  clientes pertenecen a una asociación y los tokens que emiten solo valen para esa asociación.
- **Cliente.** Una integración registrada desde la consola **Desarrolladores** de la app de Vimine: tiene un tipo
  (sitio web, app nativa, servidor), un entorno (*Test* o *Producción*), URI de redirección, orígenes autorizados y
  los permisos que puede solicitar. Consulta [Registrar un cliente](https://developers.vimine.network/es/start/register-a-client/).
- **Permisos (scopes).** Lo que puede hacer un token: `profile:read`, `membership:read`, `membership:request`, …
  El socio los ve y los concede en la página de consentimiento. La tabla completa está en
  [Permisos, errores y límites](https://developers.vimine.network/es/guides/scopes-and-errors/).
- **Tokens.** El token de acceso del socio dura 10 minutos; el refresh token rota en cada uso y dura 30 días (14 de
  inactividad). El token de un cliente confidencial dura 1 hora. El SDK lo renueva todo por sí solo.
- **`sub`.** El identificador del socio que ves en los tokens y en `/v1/me` (`vms_…`) es **propio de tu
  asociación**: estable en el tiempo, distinto en cada asociación, nunca un id interno.
- **Veredicto.** Lo que cuenta en la entrada: `valid`, `expired`, `statuto_required` (ha vencido el plazo para
  volver a aceptar el estatuto) o `inactive`.
- **Token del carné.** El carné digital es un token firmado (`vmt_…`) que se muestra como código QR, con una ventana
  de validez; rota con cada cambio de estado y, en cualquier caso, cada 90 días.
- **Sandbox.** Una asociación gemela con socios sintéticos en todos los estados, donde los clientes de prueba están
  activos de inmediato. Consulta [Sandbox y clientes de prueba](https://developers.vimine.network/es/guides/sandbox/).

## Dónde está cada cosa

| | |
|---|---|
| Páginas de inicio de sesión, consentimiento y cierre de sesión | `https://app.vimine.network/authorize`, `/oauth/logout` |
| API | `https://api.vimine.network/v1/…` — documento OpenAPI en `/v1/openapi.json`, descubrimiento en `/.well-known/oauth-authorization-server` |
| Claves públicas de los carnés | `https://api.vimine.network/.well-known/vimine-card-keys.json` |
| SDK | `@vimine/sdk` en npm: `@vimine/sdk` (navegador), `@vimine/sdk/react`, `@vimine/sdk/server` |
| Para un asistente de programación | `https://developers.vimine.network/es/llms.txt`: el índice de las páginas en Markdown, con las reglas a seguir; `llms-full.txt` todo en un archivo; cada página en Markdown, `/es/guides/sign-in/` → `/es/guides/sign-in.md` |

## Próximos pasos

1. [Registra un cliente](https://developers.vimine.network/es/start/register-a-client/) desde la consola.
2. [Instala el SDK](https://developers.vimine.network/es/start/install/).
3. Sigue [Iniciar sesión con Vimine](https://developers.vimine.network/es/guides/sign-in/), o [Integraciones de servidor](https://developers.vimine.network/es/guides/server/) si
   trabajas en los sistemas de la propia asociación.