# API pública

> publicApi() — verificação das carteirinhas, perfil público de uma associação, código fiscal, chaves públicas. Sem credenciais.

URL: https://developers.vimine.network/pt/sdk/public/

```js
import { publicApi } from '@vimine/sdk';
const api = publicApi();                       // ou vimine.public / vimineServer.public
```

Os endpoints que não precisam nem de credenciais nem de login. Podem ser usados de qualquer página, de um leitor, de um
servidor. `publicApi({ apiUrl?, fetch? })` aceita as mesmas opções de rede das outras classes.

| Método | Endpoint | |
|---|---|---|
| `verifyCard(cardToken)` | `GET /v1/verify/{card_token}` | "esta carteirinha está ativa agora?" — só o status e o fim da validade |
| `association(slug, { locale }?)` | `GET /v1/aps/{slug}` | perfil público: identidade visual, tipos de carteirinha com as taxas, statuto em vigor, como admite os associados, se coleta o endereço deles (`member_address`) |
| `validateFiscalCode(input)` | `POST /v1/validate/fiscal-code` | estrutura e caractere de controle; com os dados pessoais, também a coerência deles — e o que o código traz (`birth_date`, `birth_country`). Para uma pessoa nascida no exterior, envie `country` |
| `cardKeys()` | `GET /v1/card-keys` | as chaves públicas (JWKS, Ed25519) que verificam os tokens off-line |
| `confirmEnrollment(token, identification?, address?)` | `POST /v1/enroll/confirm` | consome o token do link "confirme o seu pedido" enviado quando um sistema faz a adesão de uma conta existente; depois de um `409 identification_required` é repetido com `identification`, depois de um `409 address_required` com `address` |
| `events.list(slug, params?)` · `events.get(slug, event, { locale }?)` | `GET /v1/aps/{slug}/events[/{event}]` | os eventos **públicos** de uma associação, com as vagas restantes por tipo ([guia](https://developers.vimine.network/pt/guides/events/)) |
| `confirmRegistration(token)` | `POST /v1/registrations/confirm` | consome o token do link "confirme a sua inscrição" de um convidado: a inscrição, com o `token` do QR quando confirmada |
| `viewRegistration(token)` | `POST /v1/registrations/view` | lê a vaga por trás do link próprio de um convidado (o e-mail que confirma a vaga): o seu status e, enquanto ela estiver confirmada, o `token` do QR; funciona até o fim do evento (desde a 0.3.2) |

```js
const { status, valid_until } = await api.verifyCard('vmt_…');
// { status: 'active', valid_until: '2027-03-31T22:59:59.000Z' } | { status: 'inactive', reason: 'expired' }

const { aps, membership_types, statuto } = await api.association('your-slug');

const check = await api.validateFiscalCode({ code: 'RSSMRA80A01H501U', first_name: 'Mario', last_name: 'Rossi', date: '1980-01-01', place: 'Roma', country: 'IT' });
// { valid: true, error: null, mismatches: [], hints: [], birth_date: '1980-01-01', birth_country: 'IT' }
// | { valid: false, error: 'mismatch', mismatches: ['date'], hints: [], birth_date: '1980-01-01', birth_country: 'IT' }

const { keys } = await api.cardKeys();   // [{ kty: 'OKP', crv: 'Ed25519', x, kid, use: 'sig', alg: 'EdDSA' }]

const { status, already, association } = await api.confirmEnrollment(token);   // do link recebido por e-mail
// { status: 'pending', already: false, association: { name, slug } } — 400 invalid_token quando expirado, 409 statuto_outdated

// 409 identification_required: a conta não está identificada; err.errors indica o que falta. Peça os dados e repita:
await api.confirmEnrollment(token, { dob: '1985-03-10', birthplace: 'Lyon', birth_country: 'FR' });

// 409 address_required: a associação pede um endereço a todos os associados. Peça-o e repita (com a identificação, se já informada):
await api.confirmEnrollment(token, undefined, { line: 'Via Roma 1', postal_code: '20100', city: 'Milano', province: 'MI' });
```

O código fiscal é opcional: `error` é `invalid`, `mismatch` ou `null`, e `hints` traz `names_swapped` quando o
código confere trocando sobrenome e nome. Os dados de nascimento de `identification` e o endereço viajam no
corpo da requisição, nunca no link. Veja [Associados sem código fiscal](https://developers.vimine.network/pt/guides/members-without-cf/).

As chaves mudam raramente: guarde-as em cache e recarregue-as uma vez por dia, ou quando encontrar um `kid` desconhecido.
O resto da verificação off-line está em [Incorporação e verificação das carteirinhas](https://developers.vimine.network/pt/guides/embed-and-verify/).

Esses endpoints têm um limite por IP (60 requisições por minuto na verificação e no código fiscal): para volumes
maiores, use um cliente confidencial com `verify:read`.