# Visão geral

> O que a API do Vimine oferece a quem desenvolve para uma associação, e os conceitos que é bom conhecer antes de começar.

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

O Vimine é a plataforma de gestão de associados para as APS e as organizações do terceiro setor italiano. Cada
associação tem os seus associados, as suas carteirinhas, o seu statuto (o estatuto social); com a API, um site ou um
app **da associação, ou para a associação**, pode usar tudo isso sem reconstruir nada.

## O que você pode fazer

| | Como | Com quais credenciais |
|---|---|---|
| **Entrar com Vimine** — os associados entram no seu site com a conta deles | OAuth 2.1 + PKCE, página de login e de consentimento em vimine.network | um cliente *público* ou *nativo* (só `client_id`) |
| **API do associado** — perfil, carteirinha e veredito, pedido de adesão, statuto, apps conectados | `GET /v1/me`, `/v1/me/membership`, … com o token do associado | as permissões que o associado concedeu |
| **Integrações de servidor** — os sistemas da própria associação leem o status das carteirinhas | `client_credentials` | um cliente *confidencial* (`client_id` + `client_secret`) |
| **Verificação das carteirinhas** — "esta carteirinha está ativa agora?", inclusive off-line | `GET /v1/verify/{card_token}`, chaves públicas Ed25519 | nenhuma |
| **Perfil público e adesão** — identidade visual, tipos de carteirinha, statuto em vigor; formulário de adesão | `GET /v1/aps/{slug}`, página `enroll` incorporável | nenhuma |

## Conceitos

- **Associação e slug.** Cada associação tem um *slug* (`https://app.vimine.network/enroll/<slug>`);
  os clientes pertencem a uma associação e os tokens que emitem valem só para ela.
- **Cliente.** Uma integração registrada no console **Desenvolvedores** do app Vimine: tem um tipo
  (site, app nativo, servidor), um ambiente (*Teste* ou *Produção*), URIs de redirecionamento, origens permitidas e
  as permissões que pode pedir. Veja [Registrar um cliente](https://developers.vimine.network/pt/start/register-a-client/).
- **Permissões (escopos).** O que um token pode fazer: `profile:read`, `membership:read`, `membership:request`, …
  O associado as vê e as concede na página de consentimento. A tabela completa está em
  [Permissões, erros e limites](https://developers.vimine.network/pt/guides/scopes-and-errors/).
- **Tokens.** O access token do associado dura 10 minutos; o refresh token muda a cada uso e dura
  30 dias (14 de inatividade). O token de um cliente confidencial dura 1 hora. O SDK renova tudo sozinho.
- **`sub`.** O identificador do associado que você vê nos tokens e em `/v1/me` (`vms_…`) é **específico da sua
  associação**: estável no tempo, diferente em cada associação, nunca um id interno.
- **Veredito.** O que conta na entrada: `valid`, `expired`, `statuto_required` (a nova aceitação do statuto está
  atrasada) ou `inactive`.
- **Token da carteirinha.** A carteirinha digital é um token assinado (`vmt_…`) mostrado como código QR, com uma janela
  de validade; ele muda a cada mudança de status e, de qualquer forma, a cada 90 dias.
- **Sandbox.** Uma associação gêmea com associados sintéticos em todos os status, onde os clientes de teste ficam
  ativos na hora. Veja [Sandbox e clientes de teste](https://developers.vimine.network/pt/guides/sandbox/).

## Onde ficam as coisas

| | |
|---|---|
| Páginas de login, consentimento e logout | `https://app.vimine.network/authorize`, `/oauth/logout` |
| API | `https://api.vimine.network/v1/…` — documento OpenAPI em `/v1/openapi.json`, descoberta em `/.well-known/oauth-authorization-server` |
| Chaves públicas das carteirinhas | `https://api.vimine.network/.well-known/vimine-card-keys.json` |
| SDK | `@vimine/sdk` no npm: `@vimine/sdk` (navegador), `@vimine/sdk/react`, `@vimine/sdk/server` |
| Para um assistente de programação | `https://developers.vimine.network/pt/llms.txt`: o índice das páginas em Markdown, com as regras a seguir; `llms-full.txt` tudo em um só arquivo; cada página em Markdown, `/pt/guides/sign-in/` → `/pt/guides/sign-in.md` |

## Próximos passos

1. [Registre um cliente](https://developers.vimine.network/pt/start/register-a-client/) no console.
2. [Instale o SDK](https://developers.vimine.network/pt/start/install/).
3. Siga [Entrar com Vimine](https://developers.vimine.network/pt/guides/sign-in/), ou [Integrações de servidor](https://developers.vimine.network/pt/guides/server/) se você
   trabalha nos sistemas da própria associação.