# Integração SelfParking · API de Totem e Cancelas (Claude Code)

Especificação para o Claude Code implementar a integração de hardware com a API SelfParking.

## Como usar

1. Salve este arquivo na raiz do projeto do firmware/aplicação do equipamento.
2. No `CLAUDE.md` do projeto, adicione a linha `@integracao.md` para o Claude Code carregar esta especificação em toda sessão. Se o projeto não tiver `CLAUDE.md`, crie um só com essa linha.
3. Peça, por exemplo: "Implemente o Fluxo 1 (configuração inicial do equipamento) seguindo o integracao.md". Depois siga fluxo a fluxo.

## Objetivo

Implementar no firmware/aplicação do equipamento (totem de entrada, totem de saída e cancela, com ou sem câmera LPR) a integração com a API SelfParking, seguindo exatamente os fluxos abaixo.

## Regras para a IA

- Siga os fluxos, endpoints e campos deste documento. **Não invente** endpoints, campos, códigos ou comportamentos que não estejam aqui.
- Quando precisar do formato exato de um payload, tipos, respostas de erro ou headers de um endpoint específico, consulte a documentação completa no Postman: https://documenter.getpostman.com/view/1137906/2sA3e5cSg3. Se a informação não estiver em nenhum dos dois, **pergunte ao desenvolvedor** em vez de supor.
- **Nunca** escreva `X_API_KEY` ou `X_APPLICATION_ID` fixos no código. Leia de configuração/armazenamento seguro do equipamento e peça os valores ao desenvolvedor.
- Persista localmente o `terminal` e a `X_API_KEY` recebidos na autenticação: eles são usados em todas as chamadas seguintes.
- Mantenha o loop de status (`GET /gate/equipment/{terminal}`) rodando durante toda a vida do equipamento, respeitando o intervalo `refresh`.

## Ambiente

| Uso | URL |
|---|---|
| Base | `https://api.selfparking.com.br` |
| Redundância | `https://api2.selfparking.com.br` |

Documentação completa (Postman): https://documenter.getpostman.com/view/1137906/2sA3e5cSg3

## Credenciais

Enviadas no header de toda requisição:

```
X_API_KEY: <chave do estabelecimento>
X_APPLICATION_ID: <id da aplicação>
```

| Header | O que identifica | Como obter |
|---|---|---|
| `X_API_KEY` | O estabelecimento | Criar conta em https://app.selfparking.com.br e acessar Configurações › Parâmetros › Integrações. Também é retornada na autenticação do equipamento (fluxo 1). |
| `X_APPLICATION_ID` | A integração/fabricante | Solicitar ao time de parcerias: parceiros@selfparking.com.br |

> A primeira chamada do equipamento autentica pelo MAC e é ela que retorna a `X_API_KEY`. Confirme no Postman quais headers essa chamada exige antes de implementá-la.

## Fluxo 1 · Configuração inicial do equipamento

Executar ao ligar o equipamento.

1. `GET /gate/equipment/auth/{macAddress}`: primeira chamada, autentica pelo MAC.
   - `success: true`: retorna `X_API_KEY` e `terminal`. Salvar o número do terminal e a `X_API_KEY` e usá-los em todas as chamadas. Ir para o passo 3.
   - `success: false` (equipamento não encontrado): ir para o passo 2.
2. Registro do equipamento:
   1. Exibir no display: "Registrar equipamento".
   2. Apresentar no firmware um campo para preencher a `X_API_KEY`.
   3. `POST /gate/equipment` com `date`, `description`, `event`, `macAddress`, `type`, `version`.
   4. `success: false`: voltar ao campo de preenchimento (2.2).
   5. `success: true`: retorna o campo `terminal`. Salvar o terminal e a `X_API_KEY` e seguir para o passo 3.
3. `GET /gate/settings`: retorna `slots`, URL do QR Code, data/hora, idioma, mensagens do ticket, formato e `rfidType`.
   - Sincronizar data/hora e configurar idioma e formato.
4. Loop de status: `GET /gate/equipment/{terminal}`
   - Retorna `emergency`, `blocked`, `offlineExit`, `logs`, `type`, `delay`, `refresh`, `cameraLPR`, `cameraIP` e `command`.
   - Se veio `command`: executar (ver tabela de commands abaixo).
   - Aguardar `refresh` ms e repetir o passo 4.
   - `cameraLPR: true` indica que os fluxos com LPR (3 e 5) devem ser usados.

### Commands possíveis no campo `command`

| command | commandValue | Ação no equipamento |
|---|---|---|
| `open-gate` | - | Abrir cancela |
| `open-gate` | `ticket` | Abrir cancela com ticket |
| `print` | conteúdo | Imprimir ticket |
| `print\|open-gate` | conteúdo | Imprimir ticket + abrir cancela |
| `reload` | - | Reiniciar aplicação do totem |

## Fluxo 2 · Totem de entrada (sem LPR)

Início: veículo se aproxima. Identificar o tipo de acesso:

- **Mensalista / credenciado (RFID) ou ticket na entrada:**
  1. `POST /gate/ticket/verify` com `ticket`, `isAccessCard`, `terminal`, `type`.
  2. `success: true` (code `2016`, acesso liberado): seguir para `POST /gate/ticket`.
  3. `success: false`: exibir a mensagem no display e bloquear o acesso.
- **Avulso (entrou no laço):** seguir direto para `POST /gate/ticket`.

`POST /gate/ticket` com `ticket`, `plate?`, `isAccessCard?`, `terminal`, `type`.

Retorna: `open`, `message.display`, `message.ticket`, `ticket`, `plate`, `paperReceipt`, `qrcode`, `image.base64`.

- `open: false`: manter a cancela fechada e exibir a mensagem.
- `open: true`: tratar `paperReceipt`:
  - `none`: abrir a cancela direto, sem ticket.
  - `auto`: imprimir o ticket automaticamente (número, placa, QR Code, mensagem, imagem). Quando o cliente retirar o ticket da impressora, abrir a cancela.
  - `button`: aguardar o usuário apertar o botão e imprimir o ticket. Quando o cliente retirar o ticket, abrir a cancela.

## Fluxo 3 · Totem de entrada com câmera LPR

Usar apenas quando `cameraLPR: true` em `GET /gate/equipment/{terminal}`.

1. Veículo detectado pelo laço.
2. `GET /gate/equipment/{terminal}/ticket/current/0/IN`: captura foto e leitura da LPR.
   - Retorna `code`, `ticket`, `plate`, `paperReceipt`, `message.display`, `disableReaders`.
3. Exibir `message.display` e guardar `ticket` e `plate`.
4. `POST /gate/ticket` com `ticket`, `plate`, `terminal`, `type`.
   - Retorna `open`, `message`, `ticket`, `plate`, `paperReceipt`, `qrcode`, `image`.
5. `open: true`: abrir a cancela e imprimir conforme `paperReceipt`.
   `open: false`: bloquear a entrada e exibir a mensagem.

## Fluxo 4 · Totem de saída (sem LPR)

1. Veículo apresenta o ticket.
2. `POST /gate/ticket/verify` com `ticket`, `terminal`, `type`, `isAccessCard?`.
   - Retorna `open`, `message.display`.
3. `open: false` (pendente de pagamento): exibir a mensagem e manter a cancela fechada. O usuário paga (caixa/app) e apresenta o ticket de novo: voltar ao passo 2.
4. `open: true`: exibir a mensagem e abrir a cancela.
5. Quando o veículo passar pela cancela: `POST /gate/ticket/close` com `ticket`, `terminal`, `type`, `isAccessCard?`.
6. Saída confirmada.

## Fluxo 5 · Totem de saída com câmera LPR

Usar apenas quando `cameraLPR: true` em `GET /gate/equipment/{terminal}`.

1. Veículo detectado no laço de saída.
2. `GET /gate/equipment/{terminal}/ticket/current/0`: captura a placa via LPR.
   - Retorna `open`, `ticket`, `plate`, `message.display`.
3. `open: false` (pendente de pagamento): exibir a mensagem e aguardar o pagamento. Após o pagamento, voltar ao passo 2.
4. `open: true`: abrir a cancela.
5. Quando o veículo passar pela cancela: `POST /gate/ticket/close` com `ticket`, `terminal`, `type`.
6. Saída confirmada.

## Referência rápida de endpoints

| Método | Endpoint | Quando usar |
|---|---|---|
| GET | `/gate/equipment/auth/{macAddress}` | Na inicialização, para autenticar o equipamento pelo MAC |
| POST | `/gate/equipment` | Registrar o equipamento quando a autenticação não o encontra |
| GET | `/gate/settings` | Vagas, URL do QR Code, data/hora, idioma, mensagens e formato do ticket |
| GET | `/gate/equipment/{terminal}` | Consulta periódica de status (emergência, bloqueio, LPR) e commands |
| POST | `/gate/ticket/verify` | Validar cartão RFID ou ticket na entrada e na saída |
| POST | `/gate/ticket` | Gerar a entrada do veículo |
| GET | `/gate/equipment/{terminal}/ticket/current/0/IN` | Leitura da LPR no totem de entrada |
| GET | `/gate/equipment/{terminal}/ticket/current/0` | Leitura da LPR no totem de saída |
| POST | `/gate/ticket/close` | Confirmar a saída depois que o veículo passa pela cancela |

## Suporte

- Documentação visual dos fluxos: https://selfparking.com.br/integracoes/documentacao-api-hardware
- Parcerias e `X_APPLICATION_ID`: parceiros@selfparking.com.br