POST /api/cameras

Cria uma nova câmera e a registra automaticamente no agente de processamento. Se o agente estiver indisponível, a criação falha e nada é salvo no banco de dados.

Autenticação

Scope necessário: cameras:write

Inclua o header Authorization: Bearer <api-key> ou use cookie de sessão.

Requisição

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

Headers

Header	Obrigatório	Descrição
`Authorization`	sim	`Bearer pk_...` (API key) ou cookie de sessão
`Content-Type`	sim	`application/json`

Body

Campo	Tipo	Obrigatório	Padrão	Descrição
`planId`	string	sim	—	ID da assinatura (plano) onde a câmera será registrada
`name`	string	sim	—	Nome da câmera
`location`	string	não	`""`	Localização física
`rtspUrl`	string	não	`""`	URL do stream RTSP
`rtspTransport`	`"tcp"` \| `"udp"`	não	`"tcp"`	Protocolo de transporte RTSP
`enabled`	boolean	não	`true`	Câmera ativa
`roi`	object	não	`null`	Região de interesse (coordenadas do polígono)
`minConfidence`	number	não	`0.5`	Confiança mínima para aceitar reconhecimento (0-1)
`motionDetectionEnabled`	boolean	não	`true`	Ativar detecção de movimento
`motionDetectorType`	`"framediff"` \| `"mog2"`	não	`"framediff"`	Algoritmo de detecção de movimento
`motionThresholdPercent`	number	não	`0.01`	Threshold de detecção de movimento
`motionFramesRequired`	number	não	`1`	Frames consecutivos com movimento necessários
`decodeMode`	`"auto"` \| `"gpu"` \| `"cpu"`	não	`"auto"`	Modo de decodificação de vídeo
`frameIntervalMs`	number	não	`200`	Intervalo entre capturas de frames (ms)
`frameSkip`	number	não	`0`	Número de frames ignorados entre capturas
`crop`	boolean	não	`true`	Se deve recortar a região da placa
`cropResolution`	`"426x240"` \| `"640x360"` \| `"1280x720"`	não	`"640x360"`	Resolução do recorte
`processingMode`	`"blocking"` \| `"queue"` \| `"disk"`	não	`"disk"`	Modo de processamento de frames
`queueSize`	number	não	`100`	Tamanho da fila de processamento
`jpegQuality`	number	não	`100`	Qualidade JPEG (1-100)

Exemplo

curl -X POST "https://api.placaflow.com.br/api/cameras" \
  -H "Authorization: Bearer pk_a1b2c3d4e5f6g7h8i9j0..." \
  -H "Content-Type: application/json" \
  -d '{
    "planId": "980cb867-28f0-4460-ac39-eced786e73f7",
    "name": "Entrada principal",
    "location": "Portão A",
    "rtspUrl": "rtsp://admin:pass@192.168.1.200:554/stream",
    "minConfidence": 0.7
  }'

Resposta 201

{
  "camera": {
    "id": "7012e192-5005-43b6-978c-7e304b3676a6",
    "userId": "c3a1e902-4f5b-4b8a-9c6d-1a2b3c4d5e6f",
    "planId": "980cb867-28f0-4460-ac39-eced786e73f7",
    "createdAt": "2026-03-22T16:00:00.000Z",
    "updatedAt": "2026-03-22T16:00:00.000Z",
    "enabled": true,
    "name": "Entrada principal",
    "location": "Portão A",
    "rtspUrl": "rtsp://admin:pass@192.168.1.200:554/stream",
    "rtspTransport": "tcp",
    "roi": null,
    "minConfidence": 0.7,
    "motionDetectionEnabled": true,
    "motionDetectorType": "framediff",
    "motionThresholdPercent": 0.01,
    "motionFramesRequired": 1,
    "decodeMode": "auto",
    "frameIntervalMs": 200,
    "frameSkip": 0,
    "crop": true,
    "cropResolution": "640x360",
    "processingMode": "disk",
    "queueSize": 100,
    "jpegQuality": 100,
    "snapshotUrl": null,
    "lastSnapshotAt": null
  }
}

Atenção

A câmera é registrada no agente de processamento antes de ser salva no banco. Se o agente estiver indisponível, a API retorna 502 e a câmera não é criada. Se já existir uma câmera com a mesma URL RTSP no agente, retorna 409.

Erros

Código	Descrição
400	Campo `planId` ou `name` ausente, ou dados inválidos
401	Não autenticado ou API key inválida
403	Limite da assinatura atingido ou API key sem scope `cameras:write`
404	Assinatura (planId) não encontrada
409	Câmera duplicada no agente
502	Agente de processamento indisponível