Reconhecimentos

Reconhecimentos são registros de placas detectadas pelas câmeras.

Scope necessário: recognitions:read

Listar reconhecimentos

GET /api/recognitions

Retorna reconhecimentos do usuário autenticado, ordenados por data (mais recentes primeiro).

Parâmetros de query:

Parâmetro	Tipo	Obrigatório	Descrição
`plate`	string	não	Filtro por texto contido na placa (case-insensitive)
`cameraId`	string	não	Filtro por UUID da câmera
`from`	ISO 8601	não	Data/hora inicial
`to`	ISO 8601	não	Data/hora final
`limit`	number	não	Resultados por página (1-200, padrão 50)
`lastKey`	string	não	Cursor de paginação (retornado na resposta anterior)

Exemplo:

curl -X GET "https://api.placaflow.com.br/api/recognitions?plate=ABC&from=2026-03-01T00:00:00Z&limit=10" \
  -H "Authorization: Bearer pk_a1b2c3d4..."

Resposta 200:

{
  "recognitions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "userId": "user-uuid",
      "cameraId": "7012e192-5005-43b6-978c-7e304b3676a6",
      "cameraName": "Entrada principal",
      "plate": "ABC1D23",
      "confidence": 0.96,
      "timestamp": "2026-03-22T14:30:00.000Z",
      "photoUrl": "frames/7012e192/photo.jpg",
      "cropUrl": "frames/7012e192/crop.jpg",
      "plateCoordinates": {
        "x": 622,
        "y": 301,
        "width": 429,
        "height": 80
      }
    }
  ],
  "nextKey": "eyJpZCI6Li4u"
}

Atenção

Os campos photoUrl e cropUrl na listagem são chaves S3 internas (não URLs acessíveis). Use o endpoint de detalhe por ID para obter URLs presignadas.

Paginação:

Se nextKey não for null, existem mais resultados. Passe o valor como lastKey na próxima requisição:

curl "https://api.placaflow.com.br/api/recognitions?lastKey=eyJpZCI6Li4u"

Obter por ID

GET /api/recognitions/:id

Retorna um reconhecimento com URLs de imagem presignadas (válidas por 1 hora).

Exemplo:

curl "https://api.placaflow.com.br/api/recognitions/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer pk_a1b2c3d4..."

Resposta 200:

{
  "recognition": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "plate": "ABC1D23",
    "confidence": 0.96,
    "cameraId": "7012e192-...",
    "cameraName": "Entrada principal",
    "timestamp": "2026-03-22T14:30:00.000Z",
    "photoUrl": "https://placaflow.s3.sa-east-1.amazonaws.com/frames/...?X-Amz-Signature=...",
    "cropUrl": "https://placaflow.s3.sa-east-1.amazonaws.com/frames/...?X-Amz-Signature=...",
    "plateCoordinates": { "x": 622, "y": 301, "width": 429, "height": 80 }
  }
}

Campos do reconhecimento

Campo	Tipo	Descrição
`id`	string	UUID único
`userId`	string	UUID do proprietário
`cameraId`	string	UUID da câmera de origem
`cameraName`	string	Nome da câmera
`plate`	string	Texto da placa (uppercase)
`confidence`	number	Confiança 0-1
`timestamp`	string	ISO 8601
`photoUrl`	string?	Frame completo (chave S3 ou URL presignada)
`cropUrl`	string?	Recorte da placa (chave S3 ou URL presignada)
`plateCoordinates`	object?	Bounding box: `{x, y, width, height}` em pixels

Erros

Código	Descrição
401	Não autenticado
404	Reconhecimento não encontrado