Equipamentos

Gerencia os dispositivos físicos de reconhecimento — Totens (tablet dedicado), Câmeras Intelbras (DVR/NVR com reconhecimento facial via nuvem) e a integração com catracas de acesso (apenas provisionamento, não configurável via API).

:::info
Suporte por tipo

Tipo	Provisionamento via API	Observação
Totem (reconhecimento facial no app)	✅ Completo	Gera QR Code de pareamento. O totem escaneia o QR e se conecta automaticamente.
DVR/NVR Intelbras (CFTV IP via nuvem)	✅ Completo	Requer teste de conexão bem-sucedido antes de criar/atualizar.
Catraca de acesso	❌ Não exposto	Requer app integrador próprio. Apenas leitura, sync, regeneração de token e mapeamento são acessíveis.
:::

Endpoints

Método	Rota	Scope	Descrição
GET	`/v1/equipments`	`equipment:read`	Listar equipamentos da unidade
POST	`/v1/equipments`	`equipment:write`	Criar equipamento (totem ou DVR/NVR Intelbras)
GET	`/v1/equipments/:id`	`equipment:read`	Detalhar equipamento
PUT	`/v1/equipments/:id`	`equipment:write`	Atualizar equipamento
DELETE	`/v1/equipments/:id`	`equipment:write`	Excluir equipamento (desfaz vínculos)
POST	`/v1/equipments/intelbras/test-connection`	`equipment:write`	Testar conexão com DVR/NVR Intelbras
GET	`/v1/equipments/:id/mappings/search`	`equipment:read`	Buscar pessoas sincronizadas com a catraca
GET	`/v1/equipments/:id/sync-status`	`equipment:read`	Status de sincronização (catraca)
POST	`/v1/equipments/:id/sync-users`	`equipment:write`	Disparar sincronização (catraca)
POST	`/v1/equipments/:id/access-sync`	`equipment:write`	Reenviar permissões de acesso (catraca)
GET	`/v1/equipments/:id/push-queue`	`equipment:read`	Fila de comandos pendentes (catraca)
POST	`/v1/equipments/:id/regenerate-token`	`equipment:write`	Regenerar token de webhook (catraca)

GET /v1/equipments

Lista os equipamentos da unidade.

Parâmetros (query)

Param	Tipo	Default	Descrição
`search`	string	—	Busca por nome, ID do dispositivo ou número de série.
`type`	`GDREDU_TOTEM` \| `CONTROLID_DEVICE` \| `INTELBRAS_P2P`	—	Filtra por tipo.
`page`	number	`1`
`limit`	number	`20`	Max 100.

Exemplo

curl "https://api.gdredu.com/v1/equipments?type=INTELBRAS_P2P&search=bloco" \
  -H "Authorization: Bearer gdredu_live_..." \
  -H "x-branch-id: 770e8400-e29b-41d4-a716-446655440000"

Resposta (200)

{
  "data": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "name": "Câmera Bloco A",
      "type": "INTELBRAS_P2P",
      "recognitionType": "BOTH",
      "deviceId": null,
      "serialNumber": "ABCD1234567890",
      "version": null,
      "model": null,
      "branchId": "770e8400-e29b-41d4-a716-446655440000",
      "lastConnection": "2026-06-20T15:30:00.000Z",
      "lastSync": "2026-06-20T15:35:00.000Z",
      "recognitionAddPresenceAuto": false,
      "controlIdBaseId": 1,
      "p2pClientId": "intelbras-p2p-uuid",
      "username": "admin",
      "remotePortIntelbras": 37777,
      "devTypeIntelbras": "iM7",
      "detailTypeIntelbras": "Face Recognition Camera",
      "swVersionIntelbras": "1.0.0",
      "hwVersionIntelbras": "1.0",
      "createdAt": "2026-06-01T10:00:00.000Z",
      "updatedAt": "2026-06-20T15:35:00.000Z",
      "online": true,
      "_count": { "presences": 15234 }
    }
  ],
  "pagination": {
    "page": 1, "limit": 20, "total": 8, "totalPages": 1, "hasNext": false, "hasPrev": false
  }
}

Campo	Descrição
`type`	`GDREDU_TOTEM` (tablet), `INTELBRAS_P2P` (câmera) ou `CONTROLID_DEVICE` (catraca).
`recognitionType`	Lado do reconhecimento: `ENTRY` (entrada), `EXIT` (saída) ou `BOTH`.
`online`	`true` se o dispositivo conectou nos últimos 5 minutos.
`lastConnection`	Última vez que o dispositivo fez heartbeat / poll.
`lastSync`	Última sincronização de dados (presenças, mapeamentos).

POST /v1/equipments

Cria um novo equipamento. O tipo determina os campos obrigatórios.

Body (Totem)

{
  "type": "GDREDU_TOTEM",
  "name": "Totem Recepção",
  "recognitionAddPresenceAuto": true,
  "recognitionType": "BOTH"
}

Body (DVR/NVR Intelbras)

{
  "type": "INTELBRAS_P2P",
  "name": "Câmera Bloco A",
  "recognitionType": "BOTH",
  "recognitionAddPresenceAuto": true,
  "intelbras": {
    "serial": "ABCD1234567890",
    "username": "admin",
    "password": "senha-do-dispositivo",
    "remotePort": 37777
  }
}

Campo	Tipo	Obrigatório	Descrição
`type`	enum	sim	`GDREDU_TOTEM` ou `INTELBRAS_P2P`.
`name`	string	sim	Nome descritivo (até 200 caracteres).
`recognitionType`	enum	não	`ENTRY`, `EXIT` ou `BOTH` (default).
`recognitionAddPresenceAuto`	boolean	não	Se `true`, marca o aluno como presente em todas as aulas do dia ao passar no equipamento.
`intelbras.serial`	string	sim*	Número de série do DVR/NVR Intelbras.
`intelbras.username`	string	sim*	Usuário admin do dispositivo.
`intelbras.password`	string	sim*	Senha do dispositivo.
`intelbras.remotePort`	number	não	Porta remota (default `37777`).

* Obrigatório apenas para INTELBRAS_P2P.

Fluxo

Totem: o equipamento é criado e um QR Code (campo pairingToken) é retornado. O totem físico escaneia o QR e se conecta.
Intelbras: o sistema testa a conexão antes de criar. Se falhar, retorna 502 com os detalhes do erro. Se sucesso, o equipamento é criado e a sincronização com a nuvem Intelbras começa em até 1 minuto.

Resposta (201)

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "name": "Câmera Bloco A",
  "type": "INTELBRAS_P2P",
  "recognitionType": "BOTH",
  "deviceId": null,
  "serialNumber": "ABCD1234567890",
  "username": "admin",
  "remotePortIntelbras": 37777,
  "branchId": "770e8400-e29b-41d4-a716-446655440000",
  "lastConnection": null,
  "lastSync": null,
  "recognitionAddPresenceAuto": true,
  "controlIdBaseId": 1,
  "createdAt": "2026-06-20T16:00:00.000Z",
  "updatedAt": "2026-06-20T16:00:00.000Z",
  "online": false
}

Para Totem, a resposta inclui também:

{
  "pairingToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...."
}

Use esse token para gerar o QR Code no seu app (codificando-o como imagem QR) — o totem escaneia o QR e completa o pareamento.

Erros

Status	Code	Quando
400	`VALIDATION_ERROR`	Campos obrigatórios faltando ou inválidos
409	`CONFLICT`	Já existe equipamento com o mesmo número de série Intelbras
502	`INTERNAL_ERROR`	Falha ao testar conexão Intelbras (credenciais inválidas, dispositivo offline)

GET /v1/equipments/:id

Detalha um equipamento. Retorna os mesmos campos da listagem, mais tokens sensíveis (accessToken, webhookToken).

Exemplo

curl "https://api.gdredu.com/v1/equipments/660e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer gdredu_live_..." \
  -H "x-branch-id: 770e8400-e29b-41d4-a716-446655440000"

Resposta (200)

Mesma forma do POST. Para catracas, inclui:

{
  "accessToken": "...",
  "webhookToken": "...",
  "controlIdMonitorConfigured": true,
  "controlIdPushConfigured": true
}

Status	Code	Quando
404	`NOT_FOUND`	Equipamento não encontrado na unidade

PUT /v1/equipments/:id

Atualiza um equipamento.

Body (Totem ou Intelbras)

{
  "name": "Câmera Bloco A (renomeada)",
  "recognitionType": "ENTRY",
  "recognitionAddPresenceAuto": true,
  "intelbras": {
    "username": "newadmin",
    "password": "nova-senha"
  }
}

Campo	Tipo	Descrição
`name`	string	Novo nome.
`recognitionType`	enum	`ENTRY`, `EXIT` ou `BOTH`.
`recognitionAddPresenceAuto`	boolean	Atualiza flag de presença automática.
`controlIdBaseId`	number	Apenas para catracas: ID base usado para gerar IDs internos. Aceita 1 (padrão, IDs a partir de 1) ou 110 (IDs a partir de 110).
`intelbras.serial`	string	Novo número de série. Se diferente do atual, dispara verificação de duplicata.
`intelbras.username`	string	Novo usuário.
`intelbras.password`	string	Nova senha. Atualizar a senha desconecta e reconecta o túnel P2P.
`intelbras.remotePort`	number	Nova porta remota.

Comportamento

Se qualquer credencial Intelbras mudar (username, password, serial ou remotePort), o túnel P2P atual é encerrado e a sincronização é refeita em até 1 minuto.
Atualizar password exige teste de conexão prévio via /v1/equipments/intelbras/test-connection com o equipmentId (caso contrário a alteração é aceita mas o túnel pode falhar).

Erros

Status	Code	Quando
400	`VALIDATION_ERROR`	Dados inválidos
404	`NOT_FOUND`	Equipamento não encontrado
409	`CONFLICT`	Outro equipamento já usa o novo número de série Intelbras

DELETE /v1/equipments/:id

Exclui o equipamento e desvincula todas as presenças, mapeamentos e comandos pendentes associados.

Resposta

204 No Content em caso de sucesso.

:::warning
Presenças não são apagadas — apenas perdem a referência ao equipamento (equipmentId torna-se null). Use isso se quiser manter histórico de detecções.
:::

Status	Code	Quando
404	`NOT_FOUND`	Equipamento não encontrado

POST /v1/equipments/intelbras/test-connection

Testa a conexão com uma DVR/NVR Intelbras antes de criar ou atualizar. Use no wizard de configuração para validar credenciais em tempo real.

Body

{
  "serial": "ABCD1234567890",
  "username": "admin",
  "password": "senha-do-dispositivo",
  "remotePort": 37777,
  "equipmentId": "660e8400-e29b-41d4-a716-446655440000"
}

Campo	Tipo	Obrigatório	Descrição
`serial`	string	sim	Número de série.
`username`	string	sim	Usuário.
`password`	string	sim	Senha.
`remotePort`	number	não	Porta (default `37777`).
`equipmentId`	uuid	não	Em atualização, ID do equipamento atual (para ignorar na verificação de duplicata).

Resposta (200)

{
  "success": true,
  "message": "Conexão estabelecida com sucesso.",
  "deviceInfo": {
    "serial": "ABCD1234567890",
    "devType": "iM7",
    "detailType": "Face Recognition Camera",
    "swVersion": "1.0.0",
    "hwVersion": "1.0"
  }
}

Em caso de falha:

{
  "success": false,
  "message": "Falha na autenticação: usuário ou senha inválidos.",
  "deviceInfo": null
}

Erros

Status	Code	Quando
400	`VALIDATION_ERROR`	Campos obrigatórios faltando
404	`NOT_FOUND`	`equipmentId` informado não existe na unidade
409	`CONFLICT`	Outro equipamento já usa este número de série
502	`INTERNAL_ERROR`	Falha na comunicação com a nuvem Intelbras

GET /v1/equipments/:id/mappings/search

Busca pessoas (alunos ou usuários) com vinculação conhecida à catraca, retornando o status de sincronização. Disponível apenas para CONTROLID_DEVICE.

Parâmetros (query)

Param	Tipo	Default	Descrição
`q`	string	—	Termo de busca (mínimo 2 caracteres).
`take`	number	`10`	Max 25.
`onlySynced`	`true`	`false`	Apenas pessoas com foto sincronizada.
`onlyRegistered`	`true`	`false`	Apenas pessoas com vínculo (mesmo sem foto).

Exemplo

curl "https://api.gdredu.com/v1/equipments/660e8400-.../mappings/search?q=joao&onlySynced=true" \
  -H "Authorization: Bearer gdredu_live_..." \
  -H "x-branch-id: 770e8400-..."

Resposta (200)

{
  "results": [
    {
      "kind": "student",
      "id": "880e8400-e29b-41d4-a716-446655440000",
      "name": "João da Silva",
      "email": "[email protected]",
      "avatarUrl": "https://cdn.gdredu.com/photos/students/880e.../foto1.jpg?<sas>",
      "synced": true,
      "registered": true,
      "controlIdUserId": 12,
      "syncedAt": "2026-06-20T14:30:00.000Z",
      "lastSyncError": null
    },
    {
      "kind": "user",
      "id": "990e8400-e29b-41d4-a716-446655440000",
      "name": "Maria Professora",
      "email": "[email protected]",
      "avatarUrl": null,
      "synced": false,
      "registered": true,
      "controlIdUserId": 25,
      "syncedAt": null,
      "lastSyncError": "Qualidade da foto abaixo do mínimo (score 0.42)"
    }
  ],
  "hasMore": false
}

Campo	Descrição
`kind`	`student` ou `user`.
`synced`	`true` se a foto da pessoa já foi sincronizada com a catraca.
`registered`	`true` se há um vínculo criado (mesmo sem foto sincronizada).
`controlIdUserId`	ID interno atribuído pela catraca para esta pessoa.
`lastSyncError`	Mensagem de erro do último sync (se houver).

GET /v1/equipments/:id/sync-status

Retorna o status consolidado de sincronização da catraca (totais, comandos pendentes, contadores, erros recentes).

Resposta (200)

{
  "totalMappings": 1500,
  "syncedMappings": 1487,
  "pendingMappings": 8,
  "errorMappings": 5,
  "commandCounts": {
    "pending": 3,
    "sent": 12,
    "confirmed": 1240,
    "failed": 7
  },
  "photoStats": {
    "totalRejected": 14,
    "permanentlyFailed": 2,
    "recentErrors": [
      {
        "controlIdUserId": 12,
        "studentId": "880e8400-...",
        "userId": null,
        "name": "João da Silva",
        "error": "Qualidade da foto abaixo do mínimo",
        "rejectCount": 3
      }
    ]
  },
  "lastSync": "2026-06-20T15:35:00.000Z"
}

POST /v1/equipments/:id/sync-users

Dispara a sincronização completa de todos os alunos e usuários com a catraca. Útil após mudanças em massa (cadastros, fotos) ou ao diagnosticar inconsistências.

Resposta (200)

{
  "commandsCreated": 1532,
  "usersToSync": 1500,
  "usersToRemove": 8,
  "errors": []
}

A sincronização é processada em background. Use o GET /sync-status para acompanhar o progresso.

POST /v1/equipments/:id/access-sync

Reenvia as permissões de acesso para todos os usuários cadastrados na catraca. Use após mudanças nos vínculos ou em reconfiguração do equipamento.

Resposta (200)

{
  "commandsCreated": 11,
  "usersAffected": 1500
}

GET /v1/equipments/:id/push-queue

Lista os comandos pendentes/enviados/erro na fila de push da catraca, para diagnóstico.

Parâmetros (query)

Param	Tipo	Default	Descrição
`status`	string	—	Filtra por status: `PENDING`, `SENT`, `CONFIRMED`, `FAILED`, `RETRYING`, `IGNORED`.
`limit`	number	`20`	Max 100.
`offset`	number	`0`

Resposta (200)

{
  "data": [
    {
      "id": "...",
      "equipmentId": "660e8400-...",
      "verb": "POST",
      "endpoint": "create_or_modify_objects",
      "body": "{\"object\":\"users\",\"values\":[...]}",
      "status": "PENDING",
      "priority": 10,
      "attempts": 0,
      "sentAt": null,
      "confirmedAt": null,
      "nextAttemptAt": "2026-06-20T16:05:00.000Z"
    }
  ],
  "total": 3
}

POST /v1/equipments/:id/regenerate-token

Gera um novo webhook token para a catraca. O token anterior é invalidado — o dispositivo precisará ser reconfigurado com o novo token.

Resposta (200)

{
  "webhookToken": "novo-uuid-token"
}

Status	Code	Quando
404	`NOT_FOUND`	Equipamento não é uma catraca

Conceitos importantes

QR Code de pareamento (Totem)

Ao criar um totem, a resposta inclui o campo pairingToken. Para finalizar o pareamento, exiba esse token como QR Code na tela do operador. O totem físico escaneia o QR, decodifica o token e se conecta automaticamente à plataforma.

Teste de conexão (Intelbras)

Câmeras Intelbras só são criadas se o teste de conexão passar. Use POST /v1/equipments/intelbras/test-connection antes de criar para feedback em tempo real no wizard.

Presença automática

Quando recognitionAddPresenceAuto = true, ao passar no equipamento, o aluno é marcado como presente em todas as aulas do dia (não só na aula atual). Útil para totens de entrada que cobrem múltiplas turmas.

Tolerância a falhas

Se uma foto de aluno for rejeitada pela câmera (qualidade baixa, rosto não detectado), a tentativa é repetida em até 3 vezes. Após isso, o vínculo é marcado como permanentlyFailed no sync-status e precisa ser atualizado pelo painel.