Catálogo de eventos - Pictor Cloud API

Esta é a lista completa dos eventos que o Pictor envia para o seu endereço. Cada tipo tem nome estável em recurso.acao — o nome não muda. Quando o conteúdo de um evento mudar de forma incompatível, ele vira um tipo novo ou ganha uma version nova; o que já existe continua chegando igual.

A mesma lista está em GET /api/webhooks/event-types, com os campos de cada tipo. Se você gera código a partir do contrato, leia de lá — a página e a rota saem da mesma fonte.

Como ler a coluna de estado

Estado	O que significa
Emitido hoje	Já existe quem produza este fato. Assine e você recebe.
Reservado — ainda sem emissor	O nome está reservado e o formato está fechado, mas ninguém produz o fato ainda. Você pode assinar agora: no dia em que o emissor nascer, o seu receptor já está pronto e nada precisa mudar do seu lado.

A entrega é pelo menos uma vez. O mesmo evento pode chegar mais de uma vez — numa reentrega depois de um erro, ou quando a sua resposta demora e nós tentamos de novo. Use o cabeçalho Pictor-Event-Id para descartar o repetido: ele é o mesmo em todas as tentativas do mesmo evento.

Ronda

`patrol.completed`

Uma varredura de ronda terminou e a folha está completa. Emitido hoje · versão do conteúdo: 1

Dispara no fim da VARREDURA, não no fim da corrida da agenda: a corrida encerra por relógio e pode fechar com verificação ainda pendente. O evento aponta a varredura; a folha inteira sai da API de relatórios de ronda, com a sua chave.

Campo de `data`	Tipo	O que é
`alarm_id`	`uuid`	O alarme que agrupa a varredura.
`completed_at`	`string`	Quando a varredura fechou, ISO-8601 com fuso.

`patrol.digest_ready`

O resumo do dia agrupando as varreduras foi montado. Reservado — ainda sem emissor · versão do conteúdo: 1

Campo de `data`	Tipo	O que é
`local_date`	`string`	O dia local resumido (AAAA-MM-DD).
`patrols_total`	`integer`	Varreduras no dia.

IA e verificação

`verification.completed`

A verificação por IA terminou, com veredito qualquer. Emitido hoje · versão do conteúdo: 1

Sai SEMPRE que a verificação termina, inclusive quando ela não viu nada (label = none). É este o tipo que responde “a ronda rodou”.

Campo de `data`	Tipo	O que é
`device_id`	`uuid`	Câmera que produziu o quadro.
`external_id`	`string \| null`	Identificador da câmera no seu cadastro.
`label`	`string \| null`	O veredito: person, vehicle, none, uncertain.
`score`	`number \| null`	Confiança de 0 a 1.
`detected_at`	`string`	Quando aconteceu, ISO-8601 com fuso.

`verification.person_detected`

Uma pessoa foi detectada na cena. Emitido hoje · versão do conteúdo: 1

O evento não carrega imagem. Busque o quadro pela API com a sua chave.

Campo de `data`	Tipo	O que é
`device_id`	`uuid`	Câmera que produziu o quadro.
`external_id`	`string \| null`	Identificador da câmera no seu cadastro.
`score`	`number \| null`	Confiança de 0 a 1.
`detected_at`	`string`	Quando aconteceu, ISO-8601 com fuso.

`verification.vehicle_detected`

Um veículo foi detectado na cena. Emitido hoje · versão do conteúdo: 1

O evento não carrega imagem nem placa.

Campo de `data`	Tipo	O que é
`device_id`	`uuid`	Câmera que produziu o quadro.
`external_id`	`string \| null`	Identificador da câmera no seu cadastro.
`label`	`string \| null`	car, truck, motorcycle, …
`score`	`number \| null`	Confiança de 0 a 1.
`detected_at`	`string`	Quando aconteceu, ISO-8601 com fuso.

`verification.obstruction_suspected`

A cena parece obstruída (lente tapada, mira mexida). Reservado — ainda sem emissor · versão do conteúdo: 1

Campo de `data`	Tipo	O que é
`device_id`	`uuid`	Câmera avaliada.
`detected_at`	`string`	Quando aconteceu, ISO-8601 com fuso.

Equipamento

`device.offline`

A câmera parou de responder. Emitido hoje · versão do conteúdo: 1

A sonda é TCP na porta de vídeo e cobre câmera com endereço próprio. Câmera de nuvem P2P não tem endereço fixo e fica de fora — ausente é honesto, ‘offline’ seria mentira.

Campo de `data`	Tipo	O que é
`device_id`	`uuid`	A câmera.
`external_id`	`string \| null`	Identificador dela no seu cadastro.
`previous_status`	`string`	O estado de onde ela saiu.
`changed_at`	`string`	Quando a transição foi aplicada, ISO-8601.

`device.online`

A câmera voltou a responder. Emitido hoje · versão do conteúdo: 1

Campo de `data`	Tipo	O que é
`device_id`	`uuid`	A câmera.
`external_id`	`string \| null`	Identificador dela no seu cadastro.
`previous_status`	`string`	O estado de onde ela saiu.
`changed_at`	`string`	Quando a transição foi aplicada, ISO-8601.

`device.no_frame`

A câmera responde no endereço, mas não entrega quadro. Reservado — ainda sem emissor · versão do conteúdo: 1

Este é o evento que fecha o laço de manutenção: recebido, o seu sistema abre a ordem de serviço sozinho.

Campo de `data`	Tipo	O que é
`device_id`	`uuid`	A câmera.
`external_id`	`string \| null`	Identificador dela no seu cadastro.
`last_frame_at`	`string \| null`	Último quadro observado, ISO-8601.

`device.recorder_offline`

O gravador (appliance ou DVR) parou de reportar. Reservado — ainda sem emissor · versão do conteúdo: 1

Campo de `data`	Tipo	O que é
`appliance_id`	`uuid`	O gravador.
`observed_at`	`string \| null`	Último reporte recebido, ISO-8601.

`device.recorder_online`

O gravador voltou a reportar. Reservado — ainda sem emissor · versão do conteúdo: 1

Campo de `data`	Tipo	O que é
`appliance_id`	`uuid`	O gravador.
`observed_at`	`string \| null`	Reporte que restabeleceu, ISO-8601.

`device.retention_below_contract`

A retenção de gravação caiu abaixo do contratado. Reservado — ainda sem emissor · versão do conteúdo: 1

Campo de `data`	Tipo	O que é
`device_id`	`uuid`	A câmera ou o gravador.
`days_observed`	`integer`	Dias de gravação encontrados.
`days_contracted`	`integer`	Dias que o contrato prevê.

Alarme

`alarm.received`

Um alarme entrou pelo canal de eventos. Emitido hoje · versão do conteúdo: 1

Sai só na PRIMEIRA vez. Retransmissão do mesmo disparo é dedupada antes de virar evento — se ela também emitisse, o seu sistema abriria duas ocorrências para o mesmo alarme.

Campo de `data`	Tipo	O que é
`alarm_id`	`uuid`	O alarme. É o mesmo id que a API devolve.
`provider`	`string`	Por qual canal ele entrou.
`received_at`	`string`	Quando chegou, ISO-8601 com fuso.

`alarm.verified`

A IA CONFIRMOU o alarme — viu alguma coisa na cena. Emitido hoje · versão do conteúdo: 1

Só quando a IA confirma. A verificação que terminou sem ver nada sai como verification.completed e NÃO como este tipo — assine os dois se precisa saber que a varredura rodou.

Campo de `data`	Tipo	O que é
`alarm_id`	`uuid \| null`	O alarme verificado.
`device_id`	`uuid`	Câmera que produziu o quadro.
`external_id`	`string \| null`	Identificador da câmera no seu cadastro.
`label`	`string`	O veredito: person, vehicle, uncertain.
`score`	`number \| null`	Confiança de 0 a 1.
`verified_at`	`string`	Quando o veredito saiu, ISO-8601.

Entrega de relatório

`report.delivered`

O relatório saiu para a lista de destinatários. Emitido hoje · versão do conteúdo: 1

‘Entregue’ aqui é ‘o transporte aceitou’. Não é prova de que a pessoa recebeu — para isso existe report.opened.

Campo de `data`	Tipo	O que é
`local_date`	`string`	O dia local resumido (AAAA-MM-DD).
`delivered_at`	`string`	Quando o transporte aceitou, ISO-8601.

`report.opened`

Alguém abriu o relatório pelo link assinado. Emitido hoje · versão do conteúdo: 1

Sai UMA vez por relatório, na primeira abertura — recarregar a página não gera outro. É prova PARCIAL de entrega: a ausência do evento não prova que não chegou, porque quem lê o e-mail e não clica no link não gera evento nenhum. Não monte SLA de entrega em cima da ausência dele.

Campo de `data`	Tipo	O que é
`alarm_id`	`uuid`	A varredura aberta.
`opened_at`	`string`	Quando foi aberto, ISO-8601 com fuso.

Serviço

`webhook.test`

Evento de teste, disparado por você no console. Emitido hoje · versão do conteúdo: 1

Vai só para o endpoint em que você pediu, e nunca para os outros. É o único tipo que não descreve um fato do vídeo.

Campo de `data`	Tipo	O que é
`message`	`string`	Texto fixo que identifica o teste.
`requested_by`	`string`	Quem pediu o disparo.

O que nenhum evento carrega

Nenhum tipo desta lista traz imagem, rosto, placa, nome, e-mail ou telefone. O evento aponta para o recurso (device_id, alarm_id, um link assinado com prazo) e você busca o conteúdo pela API, com a sua chave — assim o acesso fica registrado do seu lado e do nosso, e o corpo do webhook não vira um depósito de dado pessoal no seu servidor de recepção.

A janela de repetição

Cada entrega leva um carimbo de tempo assinado. Recuse o que chegar com mais de 300 segundos de diferença do seu relógio: é assim que uma entrega capturada hoje deixa de valer amanhã.

​Como ler a coluna de estado

​Ronda

​patrol.completed

​patrol.digest_ready

​IA e verificação

​verification.completed

​verification.person_detected

​verification.vehicle_detected

​verification.obstruction_suspected

​Equipamento

​device.offline

​device.online

​device.no_frame

​device.recorder_offline

​device.recorder_online

​device.retention_below_contract

​Alarme

​alarm.received

​alarm.verified

​Entrega de relatório

​report.delivered

​report.opened

​Serviço

​webhook.test

​O que nenhum evento carrega

​A janela de repetição

Como ler a coluna de estado

Ronda

`patrol.completed`

`patrol.digest_ready`

IA e verificação

`verification.completed`

`verification.person_detected`

`verification.vehicle_detected`

`verification.obstruction_suspected`

Equipamento

`device.offline`

`device.online`

`device.no_frame`

`device.recorder_offline`

`device.recorder_online`

`device.retention_below_contract`

Alarme

`alarm.received`

`alarm.verified`

Entrega de relatório

`report.delivered`

`report.opened`

Serviço

`webhook.test`

O que nenhum evento carrega

A janela de repetição