Endpoints da API

Base URL: https://api.placaflow.com.br (ou http://localhost:3000 em desenvolvimento)

Autenticação: Authorization: Bearer <api_key> — veja Autenticação.

Reconhecimentos

Listar reconhecimentos

GET /api/recognitions

Parâmetros de query:

Resposta:

{
  "recognitions": [
    {
      "id": "550e8400-e29b...",
      "plate": "ABC1D23",
      "cameraId": "cam-123",
      "cameraName": "Entrada principal",
      "confidence": 0.95,
      "timestamp": "2026-03-20T14:30:00.000Z",
      "photoUrl": "frames/cam-123/photo.jpg",
      "cropUrl": "frames/cam-123/crop.jpg",
      "plateCoordinates": {
        "x": 622,
        "y": 301,
        "width": 429,
        "height": 80
      }
    }
  ],
  "nextKey": "eyJpZCI6..."
}

Obter reconhecimento por ID

GET /api/recognitions/:id

Retorna o reconhecimento com URLs de foto e recorte assinadas (válidas por 1 hora).

Reconhecimento por foto (API LPR)

POST /api/recognize
Content-Type: application/octet-stream
Body: bytes da imagem (JPEG ou PNG, máx 10MB)

Consome 1 crédito. Retorna 402 se não houver créditos suficientes.

Resposta:

{
  "plates": [
    {
      "plate": "ABC1D23",
      "conf": 95.2,
      "charConfs": "0.98;0.95;0.92;0.96;0.94;0.97;0.93",
      "coordinateLeft": 100,
      "coordinateTop": 200,
      "coordinateRight": 300,
      "coordinateBottom": 250,
      "plateType": "car"
    }
  ],
  "processingTimeMs": 45,
  "imageWidth": 1920,
  "imageHeight": 1080,
  "creditsRemaining": 499
}

Créditos

Consultar saldo

GET /api/credits

Resposta:

{
  "credits": 1500
}

Câmeras

Listar câmeras

GET /api/cameras

Criar câmera

POST /api/cameras
Content-Type: application/json

{
  "name": "Entrada principal",
  "location": "Portão A",
  "rtspUrl": "rtsp://user:pass@host:554/stream",
  "enabled": true
}

A câmera é automaticamente registrada no agente de processamento. Retorna 502 se o agente estiver indisponível e 409 se já existir uma câmera com o mesmo identificador.

Atualizar câmera

PUT /api/cameras/:id
Content-Type: application/json

{
  "name": "Novo nome"
}

Excluir câmera

DELETE /api/cameras/:id

Remove a câmera do agente de processamento e cancela a assinatura associada (com crédito proporcional).

Snapshot da câmera

GET /api/cameras/:id/snapshot

Retorna a última captura da câmera em JPEG. Headers X-Frame-Width e X-Frame-Height incluídos quando disponíveis.

Alertas

Listar alertas

GET /api/alertas

Criar alerta

POST /api/alertas
Content-Type: application/json

{
  "name": "Alerta de intruso",
  "plateMatchMode": "any",
  "cameraScope": "all",
  "enabled": true
}

Atualizar / Excluir alerta

PUT /api/alertas/:id
DELETE /api/alertas/:id

Webhooks

Listar webhooks

GET /api/webhooks

Criar webhook

POST /api/webhooks
Content-Type: application/json

{
  "name": "Sistema ERP",
  "url": "https://api.example.com/webhook",
  "events": ["recognition.created", "alert.triggered"],
  "enabled": true
}

Atualizar / Excluir webhook

PUT /api/webhooks/:id
DELETE /api/webhooks/:id

Chaves de API

Listar chaves

GET /api/api-keys

Criar chave

POST /api/api-keys
Content-Type: application/json

{
  "name": "Sistema ERP",
  "scopes": ["recognitions:read", "cameras:read"],
  "enabled": true
}

Retorna plainKey apenas na criação — não será exibida novamente.

Atualizar / Revogar chave

PUT /api/api-keys/:id
DELETE /api/api-keys/:id

Analytics

Dashboard analytics

GET /api/analytics

Retorna dados consolidados dos últimos 30 dias:

{
  "stats": {
    "total30d": 1250,
    "activeCameras": 3,
    "activeApiKeys": 2,
    "successRate": 96.5
  },
  "dailyChart": [...],
  "hourlyChart": [...],
  "topPlates": [...],
  "cameraChart": [...],
  "recent": [...]
}

Códigos de erro