> ## 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.

# O relatório de ronda de um alarme

> O relatório de ronda de um evento: as verificações feitas sob aquele alarme,
prontas para virar a folha que o cliente recebe.

Quando nenhuma verificação foi registrada para o alarme, a resposta é `404` —
não um relatório vazio. Relatório sem verificação seria um documento afirmando
que ninguém olhou, com a aparência de que alguém olhou.

As fotos vêm em endereços assinados e temporários. **Quem guarda o relatório
guarda os bytes, não o link** — é a diferença entre um documento que abre em seis
meses e um que abre hoje.



## OpenAPI

````yaml /api-reference/openapi.json get /api/patrols/sheets/alarm/{alarm_id}
openapi: 3.1.0
info:
  description: >

    API de leitura do Pictor Cloud para integração de parceiro.


    ## Autenticação


    Toda chamada leva a chave no cabeçalho `Authorization`:


    ```

    Authorization: Bearer pct_1a2b3c4d_<segredo>

    ```


    A chave é emitida por um **administrador da conta** no console (Integrações
    →

    Chaves de API) e **aparece uma única vez**, no momento da criação. O
    servidor

    guarda apenas o resumo criptográfico dela: não existe "mostrar de novo". Se

    perder, emita outra e revogue a antiga.


    ## O que a chave enxerga


    A chave carrega o mesmo par permissão/alcance de um usuário:


    | Campo | Valores | Efeito |

    |---|---|---|

    | `role` | `viewer`, `operator`, `admin` | `viewer` basta para tudo que está
    documentado aqui |

    | `scope` | `tenant`, `client`, `video_wall` | recorta o que a chave vê
    dentro da conta |


    Uma chave com `scope=client` só devolve as câmeras (e os eventos, e o

    diagnóstico) daquele cliente. Uma chave nunca atravessa a fronteira da conta
    que

    a emitiu: não existe chave que enxergue duas contas.


    ## Validade


    Toda chave tem prazo — "nunca expira" não é um estado que exista. Quando ela

    vence, as chamadas passam a responder `401`; a cura é emitir outra no
    console.


    ## Cabeçalhos que não se aplicam


    - `X-Tenant-ID`: opcional. Se vier, precisa ser a conta da própria chave;
      divergente responde `403`. A chave decide a conta, o cabeçalho nunca a troca.
    - `X-Membership-ID`: responde `403`. Uma chave não troca de workspace.


    ## Limites


    Há um teto de requisições por chave por minuto. Ao estourar, a resposta é
    `429`

    com `Retry-After`. A emissão de URL de mídia tem teto próprio, bem menor:
    cada

    sessão de vídeo custa CPU no servidor de mídia.


    ## Erros


    | Código | Significado |

    |---|---|

    | `401` | chave ausente, malformada, revogada ou expirada (o motivo não é
    detalhado, de propósito) |

    | `403` | chave válida, sem permissão para o recurso — ou cabeçalho que
    contradiz a chave |

    | `404` | o recurso não existe **ou** não é desta chave (não distinguimos:
    dizer qual seria contar o que existe) |

    | `429` | teto de requisições estourado |
  title: Pictor Cloud — API de parceiro
  version: 1.0.0
servers:
  - description: Pictor Cloud
    url: https://api.pictor.cloud
security: []
paths:
  /api/patrols/sheets/alarm/{alarm_id}:
    get:
      tags:
        - patrols
      summary: O relatório de ronda de um alarme
      description: >-
        O relatório de ronda de um evento: as verificações feitas sob aquele
        alarme,

        prontas para virar a folha que o cliente recebe.


        Quando nenhuma verificação foi registrada para o alarme, a resposta é
        `404` —

        não um relatório vazio. Relatório sem verificação seria um documento
        afirmando

        que ninguém olhou, com a aparência de que alguém olhou.


        As fotos vêm em endereços assinados e temporários. **Quem guarda o
        relatório

        guarda os bytes, não o link** — é a diferença entre um documento que
        abre em seis

        meses e um que abre hoje.
      operationId: get_patrol_sheet_for_alarm_api_patrols_sheets_alarm__alarm_id__get
      parameters:
        - in: path
          name: alarm_id
          required: true
          schema:
            format: uuid
            title: Alarm Id
            type: string
        - in: header
          name: X-Membership-ID
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Membership-Id
        - in: header
          name: X-Tenant-ID
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Tenant-Id
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatrolSheetOut'
          description: Successful Response
        '401':
          description: Chave ausente, invalida, revogada ou expirada.
        '403':
          description: Chave valida, sem permissao para o recurso.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        '429':
          description: Teto de requisicoes desta chave excedido.
      security:
        - HTTPBearer: []
components:
  schemas:
    PatrolSheetOut:
      properties:
        cameras:
          items:
            $ref: '#/components/schemas/SheetCameraOut'
          title: Cameras
          type: array
        checklist:
          default: GPSTEC - RONDA VIRTUAL CFTV
          title: Checklist
          type: string
        emitted_at:
          format: date-time
          title: Emitted At
          type: string
        header:
          $ref: '#/components/schemas/SheetHeaderOut'
        items:
          items:
            $ref: '#/components/schemas/SheetItemOut'
          title: Items
          type: array
        source:
          $ref: '#/components/schemas/SheetSourceOut'
      required:
        - source
        - emitted_at
        - header
        - items
        - cameras
      title: PatrolSheetOut
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    SheetCameraOut:
      properties:
        channel_number:
          anyOf:
            - type: integer
            - type: 'null'
          title: Channel Number
        device_id:
          format: uuid
          title: Device Id
          type: string
        dvr_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          title: Dvr Id
        dvr_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Dvr Name
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
        external_id:
          anyOf:
            - type: string
            - type: 'null'
          title: External Id
        finished_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Finished At
        frames_analyzed:
          default: 0
          title: Frames Analyzed
          type: integer
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        owner:
          anyOf:
            - enum:
                - recorder
                - platform
                - registry
              type: string
            - type: 'null'
          title: Owner
        photo:
          anyOf:
            - $ref: '#/components/schemas/SheetPhotoOut'
            - type: 'null'
        reason_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Reason Code
        reason_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Reason Label
        requested_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Requested At
        situation:
          enum:
            - with_frame
            - no_frame_recorder
            - not_sampled_platform
            - not_sampled_registry
            - pending
            - failed
          title: Situation
          type: string
        situation_label:
          title: Situation Label
          type: string
        verdict:
          anyOf:
            - type: string
            - type: 'null'
          title: Verdict
        verdict_label:
          title: Verdict Label
          type: string
      required:
        - device_id
        - situation
        - situation_label
        - verdict_label
      title: SheetCameraOut
      type: object
    SheetHeaderOut:
      properties:
        cameras_not_sampled:
          title: Cameras Not Sampled
          type: integer
        cameras_pending:
          title: Cameras Pending
          type: integer
        cameras_person:
          title: Cameras Person
          type: integer
        cameras_total:
          title: Cameras Total
          type: integer
        cameras_vehicle:
          title: Cameras Vehicle
          type: integer
        cameras_with_frame:
          title: Cameras With Frame
          type: integer
        cameras_without_frame:
          title: Cameras Without Frame
          type: integer
        duration_seconds:
          anyOf:
            - type: number
            - type: 'null'
          title: Duration Seconds
        executor:
          default: Pictor — verificação automática
          title: Executor
          type: string
        finished_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Finished At
        photos:
          title: Photos
          type: integer
        site:
          anyOf:
            - $ref: '#/components/schemas/SheetSiteOut'
            - type: 'null'
        started_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Started At
        trigger:
          anyOf:
            - $ref: '#/components/schemas/SheetTriggerOut'
            - type: 'null'
      required:
        - cameras_total
        - cameras_with_frame
        - cameras_without_frame
        - cameras_not_sampled
        - cameras_pending
        - cameras_person
        - cameras_vehicle
        - photos
      title: SheetHeaderOut
      type: object
    SheetItemOut:
      properties:
        answer:
          anyOf:
            - type: string
            - type: 'null'
          title: Answer
        comment:
          anyOf:
            - type: string
            - type: 'null'
          title: Comment
        details:
          items:
            type: string
          title: Details
          type: array
        note:
          anyOf:
            - type: string
            - type: 'null'
          title: Note
        number:
          title: Number
          type: integer
        question:
          title: Question
          type: string
        reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Reason
        source:
          title: Source
          type: string
        state:
          enum:
            - answered
            - not_measured
            - phase_2
          title: State
          type: string
      required:
        - number
        - question
        - state
        - source
      title: SheetItemOut
      type: object
    SheetSourceOut:
      properties:
        kind:
          enum:
            - alarm
            - patrol_run
          title: Kind
          type: string
        ref:
          format: uuid
          title: Ref
          type: string
      required:
        - kind
        - ref
      title: SheetSourceOut
      type: object
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
    SheetPhotoOut:
      properties:
        label:
          anyOf:
            - type: string
            - type: 'null'
          title: Label
        score:
          anyOf:
            - type: number
            - type: 'null'
          title: Score
        snapshot_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Snapshot Url
        ts:
          anyOf:
            - type: string
            - type: 'null'
          title: Ts
      title: SheetPhotoOut
      type: object
    SheetSiteOut:
      properties:
        address:
          anyOf:
            - type: string
            - type: 'null'
          title: Address
        external_ref:
          anyOf:
            - type: string
            - type: 'null'
          title: External Ref
        name:
          title: Name
          type: string
        site_id:
          format: uuid
          title: Site Id
          type: string
      required:
        - site_id
        - name
      title: SheetSiteOut
      type: object
    SheetTriggerOut:
      properties:
        account:
          anyOf:
            - type: string
            - type: 'null'
          title: Account
        armed:
          anyOf:
            - type: string
            - type: 'null'
          title: Armed
        code:
          anyOf:
            - type: string
            - type: 'null'
          title: Code
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        provider:
          anyOf:
            - type: string
            - type: 'null'
          title: Provider
        registered_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Registered At
        task_ref:
          anyOf:
            - type: string
            - type: 'null'
          title: Task Ref
      title: SheetTriggerOut
      type: object
  securitySchemes:
    HTTPBearer:
      description: Chave de API da conta, no formato `pct_<prefixo>_<segredo>`.
      scheme: bearer
      type: http

````