API de controle de acesso
para integrar o seu sistema.
API REST com autenticação JWT para convites, histórico de acessos, abertura de portas e notificações. Integração com leitores faciais e smart locker pelo Flagy Agent. A mesma API que move o nosso aplicativo.
Três camadas
de integração.
API REST
Aplicativos, portais e sistemas de gestão consultam acessos, criam convites e abrem portas. Respostas em JSON, permissões por perfil de usuário.
Flagy Agent
Ponte segura entre a nuvem e a rede local da portaria. Comunicação só de saída, sem abrir portas no roteador e sem guardar senha dos leitores.
Equipamentos
Leitores faciais Intelbras, Dahua, Hikvision, Control iD e ZKTeco e controladoras de smart locker, por drivers e um protocolo de eventos documentado.
Autenticação
e endpoints.
Base https://control.flagy.com.br/api/v1 (ou o domínio próprio do parceiro). Token de acesso Bearer válido por 1 hora e refresh token rotativo de 30 dias. As permissões seguem o perfil do usuário no painel.
Autenticação
| Método | Rota | O que faz | Acesso |
|---|---|---|---|
| POST | /auth/login | Entra com e-mail e senha (operador) ou CPF/e-mail e senha (pessoa) e devolve os tokens | pública |
| POST | /auth/refresh | Troca o refresh token por um novo par de tokens (rotativo) | pública |
| POST | /auth/identificar | Em quais organizações um CPF tem cadastro (com a marca de cada uma) | pública |
| POST | /auth/pin | Envia o código de acesso pelo WhatsApp | pública |
| POST | /auth/pin/verificar | Confere o código e devolve os tokens | pública |
| GET | /me | Quem está autenticado, a organização e as permissões | token |
| POST | /auth/logout | Encerra a sessão do aparelho | token |
Convites e visitantes
| Método | Rota | O que faz | Acesso |
|---|---|---|---|
| GET | /convites | Convites (pessoa: os seus; operador: todos). Filtro vigentes=1 | token |
| POST | /convites | Cria um convite: tipo, dias, pessoas, áreas e convidados com WhatsApp | token |
| GET | /convites/{id} | Um convite com o link e os convidados (situação de cada um) | token |
| POST | /convites/{id}/cancelar | Cancela o convite e tira os convidados dos leitores | token |
Acessos e portas
| Método | Rota | O que faz | Acesso |
|---|---|---|---|
| GET | /acessos | Histórico de passagens (liberado, negado e motivo), paginado por antes_de | token |
| GET | /dispositivos | Leitores da organização, com situação (online/offline) | dispositivos.ver |
| POST | /dispositivos/{id}/abrir | Abre a porta remotamente (fica no log de auditoria) | dispositivos.abrir |
Notificações
| Método | Rota | O que faz | Acesso |
|---|---|---|---|
| POST | /push | Registra o aparelho para receber notificações (FCM ou Web Push) | token |
| DELETE | /push | Remove o aparelho | token |
| GET | /avisos | Preferências de aviso: entradas, negados, convites, encomendas e canais | token |
| PUT | /avisos | Salva as preferências de aviso | token |
Protocolo entre a nuvem
e a rede da portaria.
O agente se autentica com a organização e um token próprio e conversa só para fora, por HTTPS. A mesma base serve aos leitores faciais e às controladoras de smart locker. Comandos têm validade: um comando que chega atrasado não abre porta.
| Método | Rota /api/agente/v1 | O que faz |
|---|---|---|
| GET | /requisicoes | Comandos pendentes para os leitores da rede local (o agente executa e devolve) |
| POST | /respostas | Resultado dos comandos executados nos leitores |
| POST | /dispositivos | Leitor encontrado na rede (modelo, serial, firmware, IP): cadastra ou religa |
| POST | /eventos/{id} | Passagem lida pelo leitor, com a foto da leitura |
| GET | /lockers/comandos | Smart locker: portas a abrir nas controladoras ligadas ao agente |
| POST | /lockers/{id}/eventos | Smart locker: porta aberta, fechada, sensor de volume, porta forçada, sinal |
| POST | /lockers/{id}/midia | Smart locker: foto ou vídeo da abertura |