API de Totem e Cancelas

Como começar

Integração em três passos

Obtenha as credenciais

A X_API_KEY vem da conta do estabelecimento e o X_APPLICATION_ID é fornecido pelo time de parcerias.

Autentique o equipamento

Na inicialização, o equipamento se identifica pelo MAC e recebe o número do terminal. Veja o fluxo Configuração.

Implemente entrada e saída

Siga os fluxos de totem de entrada e de saída, com ou sem câmera LPR, conforme o equipamento.

Integre com IA

Deixe a IA implementar a integração

Baixe o integracao.md com os fluxos, endpoints, campos e commands desta página, escrito para um agente de código seguir sem inventar nada.

Claude Code

Salve o integracao.md na raiz do projeto do equipamento.
No CLAUDE.md do projeto, adicione a linha @integracao.md.
Peça: "Implemente o Fluxo 1 seguindo o integracao.md".

Integre com o Claude

Codex

Salve o integracao.md na raiz do repositório do equipamento.
Renomeie para AGENTS.md ou cite o arquivo no AGENTS.md existente.
Peça: "Implemente o Fluxo 1 seguindo o integracao.md".

Integre com o Codex

Credenciais necessárias

Duas chaves em todas as requisições

X_API_KEY

Chave do estabelecimento

Enviada no header de toda requisição: identifica o estabelecimento.

Crie uma conta em app.selfparking.com.br
Acesse o menu de configuração da conta

Configurações› Parâmetros› Integrações

X_APPLICATION_ID

ID da aplicação

Enviado no header de toda requisição: identifica a integração/fabricante.

Para obter o X_APPLICATION_ID é preciso entrar em contato com nossa equipe de parcerias.

parceiros@selfparking.com.br

Headers

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

Fluxos de integração

Do boot do equipamento à saída do veículo

Configuração inicial do equipamento

Autenticação pelo MAC, registro quando o equipamento ainda não existe e o loop de consulta de status e comandos.

flowchart TD
    START([Equipamento ligado]):::start
    AUTH["GET /gate/equipment/auth/{macAddress}
1ª chamada - autenticar pelo MAC"]:::req
    START --> AUTH
    AUTH --> OK{"success?"}:::dec

    OK -->|"true
retorna X_API_KEY e terminal"| SAVE["Salvar número do terminal + X_API_KEY
usar em todas as chamadas"]:::act
    OK -->|"false
Equipamento nao encontrado"| ERR["Exibir no display:
Registrar equipamento"]:::err
    ERR --> FORM["Apresentar campo no firmware
para preencher a X_API_KEY"]:::act
    FORM --> REG["POST /gate/equipment
date, description, event,
macAddress, type, version"]:::req
    REG --> REGOK{"success?"}:::dec
    REGOK -->|false| FORM
    REGOK -->|"true
retorna campo terminal"| SAVE

    SAVE --> SET["GET /gate/settings"]:::req
    SET --> SETR["slots, URL QRCode, data/hora,
idioma, msgs ticket, formato, rfidType"]:::resp
    SETR --> SYNC["Sincronizar data/hora
Configurar idioma e formato"]:::act
    SYNC --> POLL["GET /gate/equipment/{terminal}"]:::req
    POLL --> POLLR["emergency, blocked, offlineExit, logs,
type, delay, refresh, cameraLPR,
cameraIP, command"]:::resp
    POLLR --> HASCMD{"Veio
command?"}:::dec

    HASCMD -->|não| WAIT["Aguardar refresh ms"]:::act
    HASCMD -->|sim| EXEC["Executar command
(ver tabela abaixo)"]:::act
    EXEC --> WAIT
    WAIT -.->|"loop a cada refresh ms"| POLL

    classDef start fill:#111827,color:#fff,stroke:#111827,font-weight:bold
    classDef req fill:#eff6ff,stroke:#3b82f6,color:#1e40af
    classDef resp fill:#f5f3ff,stroke:#8b5cf6,color:#4c1d95
    classDef act fill:#f1f5f9,stroke:#94a3b8,color:#334155
    classDef dec fill:#fefce8,stroke:#eab308,color:#713f12
    classDef err fill:#fef2f2,stroke:#ef4444,color:#7f1d1d

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

Totem de entrada (sem LPR)

Mensalistas e credenciados validam o cartão; avulsos recebem o ticket. A impressão segue o paperReceipt.

flowchart TD
    START([Veículo se aproxima]):::start
    TIPO{"Tipo de acesso?"}:::dec
    START --> TIPO

    TIPO -->|"Mensalista / credenciado (RFID)
ou ticket na entrada"| VERIFY["POST /gate/ticket/verify
ticket, isAccessCard, terminal, type"]:::req
    TIPO -->|"Avulso
(entrou no laço)"| TICKET

    VERIFY --> VOK{"success?"}:::dec
    VOK -->|"true - code 2016
Acesso liberado"| TICKET["POST /gate/ticket
ticket, plate?, isAccessCard?, terminal, type"]:::req
    VOK -->|false| BLOCK["Exibir msg no display
Bloquear acesso"]:::err

    TICKET --> TR["Retorna: open, message.display,
message.ticket, ticket, plate,
paperReceipt, qrcode, image.base64"]:::resp
    TR --> OPEN{"open?"}:::dec
    OPEN -->|false| KEEP["Manter cancela fechada
Exibir mensagem"]:::err
    OPEN -->|true| PR{"paperReceipt?"}:::dec

    PR -->|none| GATE["Abrir cancela
(direto, sem ticket)"]:::act
    PR -->|auto| PA["Imprimir ticket automaticamente
nº, placa, QRCode, msg, imagem"]:::act
    PR -->|button| PB["Aguardar usuário apertar botão
e imprimir o ticket"]:::act
    PA --> TAKE["Cliente retira o ticket
da impressora"]:::act
    PB --> TAKE
    TAKE --> GATE2["Abrir cancela"]:::act

    classDef start fill:#111827,color:#fff,stroke:#111827,font-weight:bold
    classDef req fill:#eff6ff,stroke:#3b82f6,color:#1e40af
    classDef resp fill:#f5f3ff,stroke:#8b5cf6,color:#4c1d95
    classDef act fill:#f1f5f9,stroke:#94a3b8,color:#334155
    classDef dec fill:#fefce8,stroke:#eab308,color:#713f12
    classDef err fill:#fef2f2,stroke:#ef4444,color:#7f1d1d

Totem de entrada com câmera LPR

A câmera captura a placa e a API devolve o ticket já associado ao veículo.

Usar este fluxo apenas quando cameraLPR: true em GET /gate/equipment/{terminal}

flowchart TD
    START([Veículo detectado pelo laço]):::start
    CUR["GET /gate/equipment/{terminal}/ticket/current/0/IN
captura foto + leitura da LPR"]:::req
    START --> CUR
    CUR --> CR["Retorna: code, ticket, plate,
paperReceipt, message.display, disableReaders"]:::resp
    CR --> SHOW["Exibir message.display
Guardar ticket e plate"]:::act
    SHOW --> TICKET["POST /gate/ticket
ticket, plate, terminal, type"]:::req
    TICKET --> TR["Retorna: open, message, ticket,
plate, paperReceipt, qrcode, image"]:::resp
    TR --> OPEN{"open?"}:::dec
    OPEN -->|true| GATE["Abrir cancela
Imprimir conforme paperReceipt"]:::act
    OPEN -->|false| BLOCK["Bloquear entrada
Exibir mensagem"]:::err

    classDef start fill:#111827,color:#fff,stroke:#111827,font-weight:bold
    classDef req fill:#eff6ff,stroke:#3b82f6,color:#1e40af
    classDef resp fill:#f5f3ff,stroke:#8b5cf6,color:#4c1d95
    classDef act fill:#f1f5f9,stroke:#94a3b8,color:#334155
    classDef dec fill:#fefce8,stroke:#eab308,color:#713f12
    classDef err fill:#fef2f2,stroke:#ef4444,color:#7f1d1d

Totem de saída (sem LPR)

O ticket é validado; se estiver pago, a cancela abre e a saída é confirmada após a passagem.

flowchart TD
    START([Veículo apresenta ticket]):::start
    VERIFY["POST /gate/ticket/verify
ticket, terminal, type, isAccessCard?"]:::req
    START --> VERIFY
    VERIFY --> VR["Retorna: open, message.display"]:::resp
    VR --> OPEN{"open?"}:::dec
    OPEN -->|false| PEND["Pendente de pagamento
Exibir msg · manter fechada"]:::err
    PEND --> PAY["Usuário paga (caixa/app)
e apresenta ticket de novo"]:::act
    PAY -.-> VERIFY

    OPEN -->|true| GATE["Exibir msg · Abrir cancela"]:::act
    GATE --> PASS["Veículo passa pela cancela"]:::act
    PASS --> CLOSE["POST /gate/ticket/close
ticket, terminal, type, isAccessCard?"]:::req
    CLOSE --> DONE([Saída confirmada]):::start

    classDef start fill:#111827,color:#fff,stroke:#111827,font-weight:bold
    classDef req fill:#eff6ff,stroke:#3b82f6,color:#1e40af
    classDef resp fill:#f5f3ff,stroke:#8b5cf6,color:#4c1d95
    classDef act fill:#f1f5f9,stroke:#94a3b8,color:#334155
    classDef dec fill:#fefce8,stroke:#eab308,color:#713f12
    classDef err fill:#fef2f2,stroke:#ef4444,color:#7f1d1d

Totem de saída com câmera LPR

A placa identifica o ticket; se estiver pago, a cancela abre sem o cliente apresentar nada.

Usar este fluxo apenas quando cameraLPR: true em GET /gate/equipment/{terminal}

flowchart TD
    START([Veículo detectado no laço de saída]):::start
    CUR["GET /gate/equipment/{terminal}/ticket/current/0
captura placa via LPR"]:::req
    START --> CUR
    CUR --> CR["Retorna: open, ticket,
plate, message.display"]:::resp
    CR --> OPEN{"open?"}:::dec
    OPEN -->|false| PEND["Pendente de pagamento
Exibir msg · aguardar pagamento"]:::err
    PEND -.->|"após pagamento"| CUR
    OPEN -->|true| GATE["Abrir cancela"]:::act
    GATE --> PASS["Veículo passa pela cancela"]:::act
    PASS --> CLOSE["POST /gate/ticket/close
ticket, terminal, type"]:::req
    CLOSE --> DONE([Saída confirmada]):::start

    classDef start fill:#111827,color:#fff,stroke:#111827,font-weight:bold
    classDef req fill:#eff6ff,stroke:#3b82f6,color:#1e40af
    classDef resp fill:#f5f3ff,stroke:#8b5cf6,color:#4c1d95
    classDef act fill:#f1f5f9,stroke:#94a3b8,color:#334155
    classDef dec fill:#fefce8,stroke:#eab308,color:#713f12
    classDef err fill:#fef2f2,stroke:#ef4444,color:#7f1d1d

Referência rápida

Endpoints usados nos fluxos

Parâmetros e respostas completos na documentação do Postman.

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 comandos
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

Vai integrar um equipamento?

Fale com o time de parcerias para receber o X_APPLICATION_ID e tirar dúvidas da integração.

parceiros@selfparking.com.br

API de Totem & Cancelas

Integração em três passos

Obtenha as credenciais

Autentique o equipamento

Implemente entrada e saída

Deixe a IA implementar a integração

Claude Code

Codex

Duas chaves em todas as requisições

Chave do estabelecimento

ID da aplicação

Do boot do equipamento à saída do veículo

Configuração inicial do equipamento

Commands possíveis no campo command

Totem de entrada (sem LPR)

Totem de entrada com câmera LPR

Totem de saída (sem LPR)

Totem de saída com câmera LPR

Endpoints usados nos fluxos

Vai integrar um equipamento?

Commands possíveis no campo `command`