Documentação da API REST

API REST para integração com o sistema Alfa Credenciamento. Permite consultar status de eventos e formulários, gerenciar inscritos e realizar outras operações via HTTP.

1. Visão geral

2. Autenticação

2.1 Token por evento (Status e Inscritos)

Os endpoints de Status e Inscritos usam autenticação Bearer com token vinculado ao evento.

Obtenção do token:

1. Acesse o painel do operador
2. Selecione o evento
3. Vá em Integrações > API REST
4. Crie um novo token ou use um existente
5. Copie o token exibido na listagem

Uso nas requisições:

Authorization: Bearer SEU_TOKEN_AQUI

Permissões do token: Cada token pode ter permissões diferentes (index, show, store, update, destroy), configuráveis no momento da criação. Um token sem a permissão store, por exemplo, não poderá criar inscritos.

Validade: O token possui data de expiração opcional. Tokens expirados retornam 401 Unauthorized.

3. Endpoints de Status

Todos os endpoints de status exigem autenticação Bearer e usam o evento associado ao token.

3.1 Status do evento

Verifica se o evento está aberto ou fechado para inscrições.

GET /api/status/evento

Resposta (200 OK):

{
  "evento_id": 2430,
  "nome": "Nome do Evento Exemplo",
  "aberto": true,
  "date_start": "2026-03-10T10:00:00.000000Z",
  "date_end": "2026-04-10T18:00:00.000000Z"
}

3.2 Status do formulário

Verifica se um formulário de inscrição específico está aberto ou fechado.

GET /api/status/formulario/{id}

Parâmetro: id (path) — ID do formulário.

Resposta (200 OK):

{
  "formulario_id": 123,
  "nome": "Inscrição Geral",
  "aberto": false,
  "create_off": true,
  "data_abertura": "2026-03-01T09:00:00.000000Z",
  "data_fechamento": "2026-03-31T23:59:59.000000Z"
}

3.3 Status de vagas da categoria

Verifica se uma categoria atingiu o limite de vagas.

GET /api/status/categoria/{id}

Parâmetro: id (path) — ID da categoria.

Resposta (200 OK):

{
  "categoria_id": 45,
  "nome": "Participante VIP",
  "esgotada": true,
  "limite_inscricoes": 100,
  "total_confirmados": 100,
  "vagas_restantes": 0
}

4. Endpoints de Inscritos

Os endpoints de inscritos exigem autenticação Bearer. Os campos do formulário são dinâmicos por evento — use GET /api/inscrito/campos para obter os IDs exatos.

4.1 Obter campos para criar inscrito

GET /api/inscrito/campos

Retorna os IDs dos campos e um exemplo de body para POST /inscrito.

4.2 Listar inscritos

GET /api/inscrito — Requer permissão: index

Dump legado: devolve todos os inscritos do evento (sem paginação) com o model completo e o bloco facial_photo da frontal (inclui path interno). Prefira a v1 para integrações novas.

Filtro opcional updated_since (mesmo contrato da v1): ISO-8601 UTC com sufixo Z (ex.: 2026-08-20T12:00:00Z), operador >=. Sem o parâmetro, o comportamento permanece o dump completo. Usado pelo QRCredLocal para sync incremental.

Contrato v1 para sync local (ficha + fotos): GET /api/v1/inscrito — Requer permissão: index

O token Bearer já identifica o evento. Paginação: per_page (1–200, default 50) e page. Filtros: facial_status (igualdade em facial_photo_status) e updated_since (sync incremental).

updated_since: ISO-8601 em UTC com sufixo Z (ex.: 2026-08-19T15:31:14Z). Operador >= (inclusivo). Retorna inscritos alterados após o timestamp em qualquer um destes campos: created_at, updated_at, facial_photo_uploaded_at (frontal) ou updated_at de fotos laterais (inscrito_facial_photos).

status: 0 = Pendente, 1 = Liberado, 2 = Recusado. codigo é a chave estável para upsert (QR; se nulo no banco, a API devolve sha1(id)).

nome, email, telefone e cpf são extraídos de dados (ids comuns ou tipo do campo no formulário). O mapa completo do formulário vai em dados.

{
  "data": [{
    "registration_id": 123,
    "event_id": 45,
    "codigo": "abc...sha1...",
    "posicao": 42,
    "status": 1,
    "status_label": "LIBERADO",
    "fora_lista": false,
    "acompanha": null,
    "categoria_id": 10,
    "categoria_nome": "Participante",
    "nome": "João Silva",
    "email": "joao@email.com",
    "telefone": "11999999999",
    "cpf": "000.000.000-00",
    "dados": { "nome": "João Silva", "email": "joao@email.com" },
    "updated_at": "2026-08-18T12:34:56.000000Z",
    "facial_photo": {
      "status": "approved",
      "hash": "abc...",
      "reason": "...",
      "uploaded_at": "...",
      "validated_at": "...",
      "download_url": "https://.../api/v1/inscrito/123/facial-photo"
    },
    "facial_photos": [
      { "pose": "front", "status": "approved", "hash": "...", "download_url": "..." },
      { "id": 9, "pose": "right", "status": "approved", "download_url": ".../facial-photo/9" },
      { "id": 10, "pose": "left", "status": "approved", "download_url": ".../facial-photo/10" }
    ]
  }],
  "meta": { "page": 1, "per_page": 50, "total": 100, "last_page": 2 }
}

Download das fotos (mesmo Bearer): GET /api/v1/inscrito/{id}/facial-photo (frontal) e GET /api/v1/inscrito/{id}/facial-photo/{photo} (laterais). 404 se não existir.

4.3 Criar inscrito

POST /api/inscrito — Requer permissão: store

Corpo: objeto JSON com os campos do formulário. Pode enviar na raiz ({"nome": "João", "email": "joao@email.com"}) ou dentro de dados.

Campos opcionais: voucher, cupom (conforme configuração do evento).

4.4 Exibir inscrito

GET /api/inscrito/{id} — Requer permissão: show

status: 0 = Pendente, 1 = Liberado, 2 = Recusado.

4.5 Atualizar inscrito

PUT /api/inscrito/{id} — Requer permissão: update

Envie apenas os campos que deseja atualizar: categoria, status ou campos do formulário (ex.: nome, email).

4.6 Remover inscrito

DELETE /api/inscrito/{id} — Requer permissão: destroy

Resposta: 204 No Content.

4.7 Download da foto facial do inscrito

GET /api/inscrito/{id}/facial-photo — Requer permissão: show ou index

Retorna o arquivo da foto facial em storage privado. Se não existir foto facial, retorna 404.

Versão v1: GET /api/v1/inscrito/{id}/facial-photo.

4.8 Métricas faciais por evento (v1)

GET /api/v1/inscrito/facial-metrics — Requer permissão: index

Retorna totais de inscritos com/sem foto, distribuição por status facial e tempo médio de validação para acompanhamento operacional.

5. Códigos de resposta e erros

6. Retenção de dados faciais (LGPD)

O expurgo de fotos faciais é executado por rotina agendada com base em FACIAL_PHOTO_RETENTION_DAYS. Após vencimento do prazo, a foto é removida do storage e o registro é marcado como expirado para trilha de auditoria.

Também existe trilha de acesso ao endpoint de download facial com informações de usuário API, evento, inscrito e origem da requisição.

7. Swagger / OpenAPI

A documentação interativa está disponível em:

• Swagger UI: https://www.adm.alfacredenciamento.com.br/docs — Permite testar os endpoints no navegador.
• Especificação OpenAPI (JSON): https://www.adm.alfacredenciamento.com.br/docs/spec — Útil para Postman ou gerar clientes.

Uso no Swagger: Clique em Authorize, cole o token (sem o prefixo Bearer ), autorize e teste os endpoints com Try it out.