Desenvolvedores

Integração com o 360º

Uma API HTTP local, autenticada, com fila — é assim que os softwares da suíte (e a sua integração) conversam com o serviço.

Visão geral

Fluxo: apps falam com o 360º por HTTP local; o serviço publica porta e token no service.json

Local-only: o serviço escuta somente em 127.0.0.1, numa porta dinâmica. Não há superfície de rede externa.
Autenticado: toda chamada exige Authorization: Bearer <token>. O token muda a cada inicialização do serviço.
Instância única: um mutex de sistema garante um serviço por máquina.
Fila: trabalhos rodam um por vez (por padrão); um trabalho em execução nunca é interrompido por outro.

1 · Descoberta do serviço

O serviço publica um lockfile ao subir:

%LOCALAPPDATA%\PX3LabApps\service.json
{"port": 51234, "token": "…", "pid": 18044, "started_at": 1754068943.1}

Ler o service.json. Se não existir → o serviço não está de pé.
Validar com um health-check — nunca confie só no arquivo (pode ser de um processo que morreu):

GET http://127.0.0.1:{port}/health
Authorization: Bearer {token}

200 OK → use base_url + token do arquivo. Sem resposta → trate como “serviço fora do ar” e oriente o usuário a abrir o PHOTORF 360º.

O token muda a cada inicialização: releia o lockfile sempre que uma chamada devolver 401.

2 · Enfileirando um trabalho

POST /events
Content-Type: application/json

{
  "token": "<token da Área do Cliente do usuário>",
  "fotos": "Z:/EVENTO/FOTOS",
  "ids":   "Z:/EVENTO/IDS",
  "software": "cloud_photorf",
  "nome_projeto": "Turma 2026",
  "prioridade": 0
}

Resposta: {"job_id": "…"} — o trabalho entrou na fila.

Campo	Obrigatório	Descrição
`token`	sim	credencial do usuário na Área do Cliente (créditos/saldo)
`fotos`	sim	pasta das fotos do evento (visível para a máquina do serviço)
`ids`	não	pasta das fotos de identificação
`software`	não	qual workflow da suíte executa
`cfg`	não	ajustes finos (documentados por software)
`prioridade`	não	maior fura a fila; nunca interrompe o que roda

3 · Acompanhando o progresso

Polling simples (1–2 s é suficiente):

GET /events/{job_id}

O corpo traz status (queued → running → done/failed/cancelled), o progresso por etapa e, ao final, o resumo do resultado. Eventos de console acompanham o snapshot — exiba-os como linha de status para o usuário.

Cancelamento (melhor esforço): POST /events/{job_id}/cancel.

4 · Fila

GET /events — todos os trabalhos + estatísticas.
POST /events/{id}/prioridade {"prioridade": N} — só na fila.
POST /events/{id}/mover {"delta": -1|1} — sobe/desce uma posição.
DELETE /events/concluidos — remove apenas os terminados.

5 · Histórico

GET /historico?limite=200 devolve os trabalhos concluídos (persistem entre reinícios). DELETE /historico zera — ação explícita do operador.

6 · Notificações

Avisos do estúdio entregues à máquina (a bandeja dá o toast na chegada; a lista fica disponível para a sua interface):

GET  /notificacoes            → {"notificacoes": [...], "nao_lidas": N}
POST /notificacoes/{id}/lida

Referência da API

Rota	O que faz
`GET /health`	vivacidade + estatísticas da fila
`GET /status`	estado completo: GPU, pré-carga, fila
`POST /events`	enfileira um trabalho → `{job_id}`
`GET /events`	lista trabalhos + estatísticas
`GET /events/{id}`	snapshot: status, progresso, resultado
`POST /events/{id}/cancel`	cancela (melhor esforço)
`POST /events/{id}/prioridade`	reordena na fila
`POST /events/{id}/mover`	sobe/desce uma posição
`DELETE /events/concluidos`	limpa terminados da fila
`GET /historico`	concluídos (persistente)
`DELETE /historico`	zera o histórico
`GET /notificacoes`	avisos do estúdio + não-lidas
`POST /notificacoes/{id}/lida`	marca um aviso como lido
`POST /shutdown`	encerra o serviço (teardown completo)

Códigos de erro

Código	Quando	Ação recomendada
401	token ausente/errado (ou o serviço reiniciou)	reler o lockfile
404	`job_id` desconhecido nesta instância	consultar `/historico`
409	ação incompatível com o estado do job	recarregar o snapshot
422	corpo inválido no `POST /events`	corrigir o payload

Boas práticas

Nunca mate o processo do serviço; use POST /shutdown ou o menu da bandeja.
Não faça polling agressivo (< 500 ms) — não há informação nova nessa frequência.
Caminhos de pasta devem ser visíveis para a máquina do serviço (atenção a mapeamentos de rede por usuário).
Um trabalho por evento: reenviar a mesma pasta cria OUTRO trabalho.
Projete para enfileirar, não para paralelizar POST /events.