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

# Listar atendimentos

> Os atendimentos com documentos gerados, com o status da assinatura, em ordem de atualização.

**Escopo do app:** `documents:read`. Pelo OAuth, vale o perfil da pessoa.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/appointments
openapi: 3.1.0
info:
  title: API da Westhetics
  version: 1.0.0
  description: >-
    A API pública da Westhetics: pacientes, anamneses, contratos e assinaturas
    da clínica, com eventos por webhook. Autentique com a chave do app
    (`Authorization: Bearer wx_…`), criada pela gestora em Integrações, ou com o
    token OAuth da pessoa. Respostas em JSON, mensagens em pt-BR. Guias em
    https://docs.westhetics.io.
  contact:
    name: Westhetics
    url: https://docs.westhetics.io
    email: suporte@westhetics.com.br
servers:
  - url: https://api.westhetics.io
    description: Produção
security:
  - apiKey: []
  - oauth2: []
tags:
  - name: Conta
    description: Quem chama e a clínica.
  - name: Pacientes
    description: O cadastro da paciente.
  - name: Anamneses
    description: Enviar, acompanhar e ler a anamnese.
  - name: Catálogo
    description: Procedimentos, prestadores e modelos.
  - name: Contratos e assinaturas
    description: Gerar o contrato e os termos e enviar para assinatura.
  - name: Eventos
    description: O que aconteceu na clínica, por consulta ou por webhook.
  - name: Webhooks
    description: Os endereços que recebem os eventos do app.
paths:
  /v1/appointments:
    get:
      tags:
        - Contratos e assinaturas
      summary: Listar atendimentos
      description: >-
        Os atendimentos com documentos gerados, com o status da assinatura, em
        ordem de atualização.


        **Escopo do app:** `documents:read`. Pelo OAuth, vale o perfil da
        pessoa.
      operationId: listAppointments
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            default: 25
            description: Itens por página, de 1 a 100.
            type: integer
            minimum: 1
            maximum: 100
          description: Itens por página, de 1 a 100.
        - name: cursor
          in: query
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 400
            description: O `nextCursor` da página anterior.
          description: O `nextCursor` da página anterior.
        - name: patientId
          in: query
          required: false
          schema:
            type: string
            format: uuid
            pattern: >-
              ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        - name: state
          in: query
          required: false
          schema:
            type: string
            enum:
              - generated
              - sent
              - canceled
        - name: updatedSince
          in: query
          required: false
          schema:
            type: string
            format: date-time
            pattern: >-
              ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
            description: >-
              Só o que mudou a partir deste instante (ISO 8601): o jeito de
              sincronizar.
          description: >-
            Só o que mudou a partir deste instante (ISO 8601): o jeito de
            sincronizar.
      responses:
        '200':
          description: Sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Appointment'
                  meta:
                    $ref: '#/components/schemas/PageMeta'
                required:
                  - data
                  - meta
              example:
                data:
                  - id: 3c9d1e2f-4a5b-4c7d-8e9f-0a1b2c3d4e5f
                    parentAppointmentId: null
                    type: procedure
                    state: sent
                    patientId: f47ac10b-58cc-4372-a567-0e02b2c3d479
                    anamnesisId: 5e1d2c3b-4a59-4687-b6a5-948372615049
                    practitioner:
                      id: 7c1d9e2f-3a4b-4c5d-8e6f-7a8b9c0d1e2f
                      name: Ana Oliveira
                    procedures:
                      - id: b8e2c4d6-1f3a-4b5c-8d7e-9f0a1b2c3d4e
                        name: Preenchimento labial
                        type: single
                        amountCents: 190000
                    totalAmountCents: 190000
                    paymentTerms: PIX, débito ou crédito em até 10× sem juros.
                    imageConsent: 'yes'
                    isModelPatient: false
                    procedureDate: '2026-10-20'
                    procedureTime: '14:30'
                    generation: 1
                    generatedAt: '2026-10-15T14:30:00Z'
                    documents:
                      - id: d4e5f6a7-b8c9-4123-8ef4-567890123456
                        appointmentId: 3c9d1e2f-4a5b-4c7d-8e9f-0a1b2c3d4e5f
                        patientId: f47ac10b-58cc-4372-a567-0e02b2c3d479
                        templateId: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
                        name: Contrato de prestação de serviços
                        category: service_contract
                        versionLabel: '5'
                        status: awaiting_patient
                        contentHash: >-
                          a3f9c1e7d2b84f6a9e0c1d2b3a4f5e6d7c8b9a0f1e2d3c4b5a6978877665544
                        pageCount: 4
                        hasFile: true
                        isRestricted: false
                        signedFileHash: null
                        generatedAt: '2026-10-15T14:30:00Z'
                        patientSignedAt: null
                        signedAt: null
                        expiredAt: null
                        canceledAt: null
                        updatedAt: '2026-10-15T14:30:00Z'
                    signature:
                      status: awaiting_patient
                      request:
                        id: 6f7e8d9c-0b1a-4f2e-9d3c-4b5a69788796
                        protocolNumber: WX-4472-BM
                        channels: whatsapp
                        provider: autentique
                        sentAt: '2026-10-15T14:30:00Z'
                        linkExpiresAt: '2026-10-22T14:30:00Z'
                        linkOpenedAt: null
                        resendCount: 0
                        canceledAt: null
                        cancellationReason: null
                    createdAt: '2026-10-15T14:30:00Z'
                    updatedAt: '2026-10-15T14:30:00Z'
                meta:
                  limit: 25
                  nextCursor: null
        '400':
          description: O corpo não é JSON, ou falta o que a rota precisa.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Sem chave, chave que não confere, revogada ou token vencido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: O app não tem o escopo, ou a pessoa não pode pelo perfil.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Dado que não passa na regra; `fields` traz a mensagem de cada campo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Passou de 100 chamadas por minuto; veja `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Appointment:
      type: object
      properties:
        id:
          type: string
        parentAppointmentId:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            O atendimento original quando este é um adicional: os documentos
            acrescentados depois do envio, com envio próprio.
        type:
          type: string
          enum:
            - procedure
            - standalone
        state:
          type: string
          enum:
            - generated
            - sent
            - canceled
        patientId:
          type: string
        anamnesisId:
          anyOf:
            - type: string
            - type: 'null'
        practitioner:
          anyOf:
            - type: object
              properties:
                id:
                  type: string
                name:
                  type: string
              required:
                - id
                - name
              additionalProperties: false
            - type: 'null'
        procedures:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              type:
                type: string
              amountCents:
                anyOf:
                  - type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  - type: 'null'
            required:
              - id
              - name
              - type
              - amountCents
            additionalProperties: false
        totalAmountCents:
          anyOf:
            - type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
        paymentTerms:
          anyOf:
            - type: string
            - type: 'null'
        imageConsent:
          anyOf:
            - type: string
              enum:
                - 'yes'
                - 'no'
            - type: 'null'
        isModelPatient:
          type: boolean
        procedureDate:
          anyOf:
            - type: string
              description: Data no formato aaaa-mm-dd.
            - type: 'null'
        procedureTime:
          anyOf:
            - type: string
            - type: 'null'
        generation:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        generatedAt:
          anyOf:
            - type: string
              description: Data e hora ISO 8601, em UTC.
            - type: 'null'
        documents:
          type: array
          items:
            $ref: '#/components/schemas/Document'
        signature:
          anyOf:
            - $ref: '#/components/schemas/Signature'
            - type: 'null'
        createdAt:
          type: string
          description: Data e hora ISO 8601, em UTC.
        updatedAt:
          type: string
          description: Data e hora ISO 8601, em UTC.
      required:
        - id
        - parentAppointmentId
        - type
        - state
        - patientId
        - anamnesisId
        - practitioner
        - procedures
        - totalAmountCents
        - paymentTerms
        - imageConsent
        - isModelPatient
        - procedureDate
        - procedureTime
        - generation
        - generatedAt
        - documents
        - signature
        - createdAt
        - updatedAt
      additionalProperties: false
      description: 'O atendimento: os procedimentos, o valor, os documentos e a assinatura.'
    PageMeta:
      type: object
      properties:
        limit:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        nextCursor:
          anyOf:
            - type: string
            - type: 'null'
          description: Passe em `cursor` para a próxima página; nulo no fim.
      required:
        - limit
        - nextCursor
      additionalProperties: false
      description: A página de uma lista por cursor.
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - bad_request
                - unauthenticated
                - forbidden
                - not_found
                - conflict
                - validation_failed
                - rate_limited
                - unavailable
                - internal_error
            message:
              type: string
              description: A causa e o caminho, em pt-BR.
            fields:
              description: 'No 422: a mensagem de cada campo.'
              type: object
              propertyNames:
                type: string
              additionalProperties:
                type: string
            requestId:
              type: string
          required:
            - code
            - message
            - requestId
          additionalProperties: false
      required:
        - error
      additionalProperties: false
      description: O envelope de erro.
    Document:
      type: object
      properties:
        id:
          type: string
        appointmentId:
          type: string
        patientId:
          type: string
        templateId:
          type: string
        name:
          type: string
        category:
          type: string
        versionLabel:
          type: string
        status:
          type: string
          enum:
            - generated
            - awaiting_patient
            - awaiting_clinic_signature
            - signed
            - not_signed
            - expired
            - canceled
        contentHash:
          anyOf:
            - type: string
            - type: 'null'
        pageCount:
          anyOf:
            - type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
        hasFile:
          type: boolean
        isRestricted:
          type: boolean
          description: >-
            O documento da anamnese traz as respostas: só quem lê a anamnese
            baixa (o app, com `anamneses:answers`).
        signedFileHash:
          anyOf:
            - type: string
            - type: 'null'
        generatedAt:
          anyOf:
            - type: string
              description: Data e hora ISO 8601, em UTC.
            - type: 'null'
        patientSignedAt:
          anyOf:
            - type: string
              description: Data e hora ISO 8601, em UTC.
            - type: 'null'
        signedAt:
          anyOf:
            - type: string
              description: Data e hora ISO 8601, em UTC.
            - type: 'null'
        expiredAt:
          anyOf:
            - type: string
              description: Data e hora ISO 8601, em UTC.
            - type: 'null'
        canceledAt:
          anyOf:
            - type: string
              description: Data e hora ISO 8601, em UTC.
            - type: 'null'
        updatedAt:
          type: string
          description: Data e hora ISO 8601, em UTC.
      required:
        - id
        - appointmentId
        - patientId
        - templateId
        - name
        - category
        - versionLabel
        - status
        - contentHash
        - pageCount
        - hasFile
        - isRestricted
        - signedFileHash
        - generatedAt
        - patientSignedAt
        - signedAt
        - expiredAt
        - canceledAt
        - updatedAt
      additionalProperties: false
      description: Um documento gerado (contrato, termo, anamnese).
    Signature:
      type: object
      properties:
        status:
          type: string
          enum:
            - generated
            - awaiting_patient
            - awaiting_clinic_signature
            - signed
            - not_signed
            - expired
            - canceled
        request:
          anyOf:
            - type: object
              properties:
                id:
                  type: string
                protocolNumber:
                  type: string
                channels:
                  type: string
                  enum:
                    - whatsapp
                    - email
                    - both
                provider:
                  type: string
                  enum:
                    - autentique
                    - westhetics
                sentAt:
                  type: string
                  description: Data e hora ISO 8601, em UTC.
                linkExpiresAt:
                  type: string
                  description: Data e hora ISO 8601, em UTC.
                linkOpenedAt:
                  anyOf:
                    - type: string
                      description: Data e hora ISO 8601, em UTC.
                    - type: 'null'
                resendCount:
                  type: integer
                  minimum: -9007199254740991
                  maximum: 9007199254740991
                canceledAt:
                  anyOf:
                    - type: string
                      description: Data e hora ISO 8601, em UTC.
                    - type: 'null'
                cancellationReason:
                  anyOf:
                    - type: string
                    - type: 'null'
              required:
                - id
                - protocolNumber
                - channels
                - provider
                - sentAt
                - linkExpiresAt
                - linkOpenedAt
                - resendCount
                - canceledAt
                - cancellationReason
              additionalProperties: false
            - type: 'null'
      required:
        - status
        - request
      additionalProperties: false
      description: O status da assinatura do atendimento e o último envio.
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: wx_<64 hex>
      description: >-
        A chave do app de integração, criada em Integrações. Escopos:
        `patients:read` (Listar, buscar e ler pacientes; os eventos patient.*.);
        `patients:write` (Criar e editar pacientes. Inclui ler.);
        `anamneses:read` (Listar e ler anamneses, sem as respostas; os eventos
        anamnesis.*.); `anamneses:write` (Enviar, reenviar e cancelar anamnese.
        Inclui ler.); `anamneses:answers` (Ler as respostas da anamnese
        preenchida. É dado de saúde.); `documents:read` (Atendimentos,
        documentos, status da assinatura e o PDF; os eventos appointment.* e
        signature_request.*.); `documents:write` (Gerar contrato e termos e
        enviar para assinatura, reenviar e cancelar. Inclui ler.);
        `catalog:read` (Procedimentos, prestadores e modelos de documento da
        clínica.); `webhooks:write` (Criar, alterar e remover os webhooks do
        próprio app pela API.)
    oauth2:
      type: oauth2
      description: >-
        Token OAuth 2.1 da pessoa (código com PKCE), emitido a um aplicativo
        conectado. Vale o perfil da pessoa na clínica da conexão, por 12 horas.
      flows:
        authorizationCode:
          authorizationUrl: https://zosqwpksgewzphikvgfz.supabase.co/auth/v1/oauth/authorize
          tokenUrl: https://zosqwpksgewzphikvgfz.supabase.co/auth/v1/oauth/token
          refreshUrl: https://zosqwpksgewzphikvgfz.supabase.co/auth/v1/oauth/token
          scopes:
            openid: Identidade.
            email: O e-mail.
            profile: O nome.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.