> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pictor.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Perguntas frequentes

> As dúvidas que aparecem na primeira semana de integração.

## A chave

<AccordionGroup>
  <Accordion title="Uma chave para todos os meus clientes, ou uma por cliente?">
    Uma por conta do Pictor, sempre: a chave nunca atravessa a fronteira da conta
    que a emitiu. Se você atende quarenta condomínios que são quarenta contas,
    são quarenta chaves.

    Dentro de uma conta você pode ir mais fundo: quem administra emite uma chave
    recortada a um cliente, e ela não vê nada dos vizinhos. Vale quando a sua
    arquitetura já separa condomínios, porque o recorte deixa de depender de você
    lembrar do filtro.
  </Accordion>

  <Accordion title="Perdi a chave. Como recupero?">
    Não recupera. O servidor guarda só o resumo criptográfico dela, então nem o
    administrador consegue exibi-la de novo. Peça uma nova e revogue a antiga.
  </Accordion>

  <Accordion title="O que acontece quando a chave vence?">
    As chamadas passam a responder `401`. Para rotacionar sem parada: peça a
    nova, troque no seu lado, e só então peça a revogação da antiga.
  </Accordion>
</AccordionGroup>

## Vídeo

<AccordionGroup>
  <Accordion title="Posso guardar a URL do vídeo em vez do arquivo?">
    Não. Todo endereço de vídeo, foto ou gravação é assinado e vence. Guardar o
    link produz um dossiê que abre hoje e falha em seis meses, e você descobre no
    dia em que alguém precisa dele de verdade.

    Baixe os bytes no mesmo momento em que decide arquivar. Para reabrir depois,
    peça o recurso de novo: a assinatura sai nova.
  </Accordion>

  <Accordion title="Uso `hls_url` ou `whep_url`?">
    `hls_url` é o caminho de partida: playlist comum, qualquer player abre,
    atravessa qualquer rede, alguns segundos de atraso. Use `whep_url` quando o
    operador precisar reagir ao vivo, e tenha o `hls_url` em mão de qualquer
    forma. Ver [Mostrar a câmera ao vivo](/integrar/mostrar-a-camera-ao-vivo).
  </Accordion>

  <Accordion title="Por que o teto de vídeo é doze por minuto, e o geral é seiscentos?">
    Porque as duas chamadas custam coisas diferentes. Uma leitura de inventário é
    uma consulta ao banco; uma emissão de URL de mídia prepara a transmissão da
    câmera, que é um recurso caro.

    Peça no clique, e respeite o `Retry-After` do `429`. Retry imediato custa o
    mesmo que a primeira chamada e não chega mais perto de abrir o vídeo.
  </Accordion>

  <Accordion title="Pedi o vídeo e veio 502. E agora?">
    A rota não devolve `200` com um endereço mudo. O corpo traz um `code` que
    nomeia o sintoma e um `diagnostics_url` que explica a causa. Siga o
    diagnóstico; não faça retry em laço. Ver
    [Por que a câmera não abre](/integrar/por-que-a-camera-nao-abre).
  </Accordion>
</AccordionGroup>

## Cadastro e saúde

<AccordionGroup>
  <Accordion title="O mesmo `device_id` aparece em duas contas. É erro?">
    Não. `device_id` é o identificador do equipamento e é único **dentro da
    conta**, não entre contas — fabricantes repetem padrão de série entre lotes.

    A sua chave primária tem de ser o par (conta, `device_id`), ou o
    `device_uuid`, que é único em qualquer lugar. Ver
    [Casar os dois cadastros](/integrar/casar-o-cadastro).
  </Accordion>

  <Accordion title="Uso `status` ou `transmitting` para dizer que a câmera caiu?">
    `transmitting`. `status` é cadastro: uma câmera `active` aparece assim mesmo
    sem entregar imagem, e esse é o caso mais comum de reclamação de morador.

    E confira `transmitting_witness_fresh` antes de concluir: em `false`, "nenhuma
    sem imagem" significa "sem medição".
  </Accordion>

  <Accordion title="Posso varrer o diagnóstico de todas as câmeras?">
    Não. Com `probe=true` ele contata a câmera de verdade, e quarenta condomínios
    de vinte e cinco câmeras dão mil chamadas por volta.

    O desenho certo tem dois níveis: a frota diz **quem** está sem imagem, numa
    chamada por conta (`?transmitting=no`); o diagnóstico diz **por quê**, e só
    para as que apareceram.
  </Accordion>
</AccordionGroup>

## Contrato

<AccordionGroup>
  <Accordion title="Existe webhook? Vocês me avisam quando algo acontece?">
    Hoje não. Quem pergunta é o seu lado, e as duas rotas que respondem pela conta
    inteira de uma vez (`/api/devices?transmitting=no` e
    `/api/analytics/events?since=…`) mantêm uma integração de dezenas de contas
    muito abaixo do teto.

    Quando o webhook existir, o seu desenho não muda: este laço vira a rede de
    segurança. Integração que só funciona por push perde o que acontece durante
    uma queda de rede, e não tem como saber que perdeu.
  </Accordion>

  <Accordion title="Por que recebo `404` num recurso que eu sei que existe?">
    Porque `404` quer dizer as duas coisas ao mesmo tempo, de propósito: o
    recurso não existe **ou** não é desta chave. Distinguir os dois seria contar
    a quem pergunta o que existe do lado de fora do recorte dele.
  </Accordion>

  <Accordion title="Os cabeçalhos `RateLimit-*` são o teto da minha chave?">
    Não. Eles vêm da borda e contam um orçamento compartilhado por endereço de
    origem: dois sistemas atrás do mesmo IP dividem esse número, e ele não sabe
    nada da sua chave.

    O único que fala da sua chave é o `Retry-After` do `429`. Ver
    [Limites](/limites).
  </Accordion>

  <Accordion title="Posso cadastrar ou editar alguma coisa?">
    Não. É uma API de leitura: não cadastra, não edita, não apaga. Se a sua
    integração precisa escrever, fale com a gente antes de construir em cima da
    suposição.
  </Accordion>
</AccordionGroup>