openapi: 3.1.0
info:
  title: Instituto Cestari Public & Agent API
  description: Especificação oficial da API do Instituto Cestari (Piracaia - SP). Permite que agentes autônomos de IA e desenvolvedores consultem serviços médicos, especialidades em saúde mental, corpo clínico, dados de contato e orientações para agendamento de consultas.
  version: 1.0.0
  x-api-version: 1.0.0
  x-deprecation-policy:
    status: active
    versioningScheme: URI Path (/v1/, /api/v1/) and Api-Version HTTP Header
    noticePeriodDays: 180
    rfcStandards:
      - RFC 8594 Sunset Header
      - RFC 8594 Deprecation Header
    standardHeaders:
      - Api-Version
      - RateLimit-Limit
      - RateLimit-Remaining
      - RateLimit-Reset
      - RateLimit-Policy
      - X-RateLimit-Limit
      - X-RateLimit-Remaining
      - X-RateLimit-Reset
      - Deprecation
      - Sunset
    policyUrl: "https://institutocestari.com.br/docs#deprecation-policy"
    description: Breaking changes or deprecated endpoints will be announced at least 180 days in advance via RFC 8594 Deprecation and Sunset HTTP headers.
  contact:
    name: Instituto Cestari Suporte Técnico & Desenvolvedores
    email: Institutocestari@outlook.com
    url: https://institutocestari.com.br/contato
  license:
    name: Proprietary
    url: https://institutocestari.com.br
servers:
  - url: https://institutocestari.com.br
    description: Servidor Oficial de Produção
  - url: https://institutocestari.com.br/api/v1
    description: Servidor Oficial API v1 (/api/v1)
  - url: https://institutocestari.com.br/v1
    description: Servidor Oficial API v1 (/v1)
paths:
  /v1/health:
    get:
      summary: Verificação de Saúde da API (Healthcheck v1)
      operationId: getHealthV1
      tags:
        - Sistema v1
      description: Retorna o status operacional da API e dos serviços do Instituto Cestari.
      parameters:
        - $ref: "#/components/parameters/ApiVersionHeader"
        - $ref: "#/components/parameters/HealthVerboseQuery"
      responses:
        200:
          description: API operacional
          headers:
            Api-Version:
              $ref: "#/components/headers/ApiVersion"
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
            RateLimit-Policy:
              $ref: "#/components/headers/RateLimitPolicy"
            X-RateLimit-Limit:
              $ref: "#/components/headers/XRateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/XRateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/XRateLimitReset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
  /v1/info:
    get:
      summary: Informações Institucionais do Instituto Cestari (v1)
      operationId: getInfoV1
      tags:
        - Institucional v1
      description: Retorna dados cadastrais, propósito, endereço físico, horário de funcionamento e canais de atendimento.
      parameters:
        - $ref: "#/components/parameters/ApiVersionHeader"
        - $ref: "#/components/parameters/InfoSectionQuery"
      responses:
        200:
          description: Informações institucionais retornadas com sucesso
          headers:
            Api-Version:
              $ref: "#/components/headers/ApiVersion"
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
            RateLimit-Policy:
              $ref: "#/components/headers/RateLimitPolicy"
            X-RateLimit-Limit:
              $ref: "#/components/headers/XRateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/XRateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/XRateLimitReset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InfoResponse"
  /v1/services:
    get:
      summary: Lista de Especialidades e Procedimentos de Medicina Avançada (v1)
      operationId: getServicesV1
      tags:
        - Serviços v1
      description: Retorna o catálogo completo de tratamentos médicos, psiquiátricos, psicológicos e diagnósticos de alta complexidade (Escetamina, Polissonografia, Farmacogenética, Paliperidona).
      parameters:
        - $ref: "#/components/parameters/ApiVersionHeader"
        - $ref: "#/components/parameters/ServicesCategoryQuery"
      responses:
        200:
          description: Lista de serviços retornada com sucesso
          headers:
            Api-Version:
              $ref: "#/components/headers/ApiVersion"
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
            RateLimit-Policy:
              $ref: "#/components/headers/RateLimitPolicy"
            X-RateLimit-Limit:
              $ref: "#/components/headers/XRateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/XRateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/XRateLimitReset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServicesResponse"
  /v1/corpo-clinico:
    get:
      summary: Corpo Clínico e Equipe Multidisciplinar (v1)
      operationId: getCorpoClinicoV1
      tags:
        - Equipe v1
      description: Lista os médicos psiquiatras, clínicos, psicólogos e neuropsicólogos com seus respectivos registros profissionais (CRM, RQE, CRP) e biografias clínicas.
      parameters:
        - $ref: "#/components/parameters/ApiVersionHeader"
        - $ref: "#/components/parameters/CorpoClinicoSpecialtyQuery"
      responses:
        200:
          description: Equipe clínica retornada com sucesso
          headers:
            Api-Version:
              $ref: "#/components/headers/ApiVersion"
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
            RateLimit-Policy:
              $ref: "#/components/headers/RateLimitPolicy"
            X-RateLimit-Limit:
              $ref: "#/components/headers/XRateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/XRateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/XRateLimitReset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CorpoClinicoResponse"
  /v1/contact:
    get:
      summary: Canais Oficiais de Contato e Agendamento (v1)
      operationId: getContactInfoV1
      tags:
        - Contato v1
      description: Fornece números de WhatsApp oficiais, link direto de atendimento, telefone fixo, e-mail e endereço físico completo.
      parameters:
        - $ref: "#/components/parameters/ApiVersionHeader"
        - $ref: "#/components/parameters/ContactChannelQuery"
      responses:
        200:
          description: Canais de contato retornados com sucesso
          headers:
            Api-Version:
              $ref: "#/components/headers/ApiVersion"
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
            RateLimit-Policy:
              $ref: "#/components/headers/RateLimitPolicy"
            X-RateLimit-Limit:
              $ref: "#/components/headers/XRateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/XRateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/XRateLimitReset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactResponse"
    post:
      summary: Enviar Solicitação de Contato ou Agendamento (v1)
      operationId: submitContactInquiryV1
      tags:
        - Contato v1
      description: Recebe dados de triagem inicial e gera o link formatado para finalização imediata no WhatsApp oficial do Instituto Cestari.
      parameters:
        - $ref: "#/components/parameters/ApiVersionHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContactInquiryRequest"
      responses:
        200:
          description: Solicitação processada com sucesso
          headers:
            Api-Version:
              $ref: "#/components/headers/ApiVersion"
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
            RateLimit-Policy:
              $ref: "#/components/headers/RateLimitPolicy"
            X-RateLimit-Limit:
              $ref: "#/components/headers/XRateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/XRateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/XRateLimitReset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactInquiryResponse"
        400:
          description: Requisição inválida ou campos obrigatórios ausentes
          headers:
            Api-Version:
              $ref: "#/components/headers/ApiVersion"
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/health:
    get:
      summary: Verificação de Saúde da API (Healthcheck v1)
      operationId: getHealthApiV1
      tags:
        - Sistema v1
      description: Retorna o status operacional da API e dos serviços do Instituto Cestari.
      parameters:
        - $ref: "#/components/parameters/ApiVersionHeader"
        - $ref: "#/components/parameters/HealthVerboseQuery"
      responses:
        200:
          description: API operacional
          headers:
            Api-Version:
              $ref: "#/components/headers/ApiVersion"
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
            RateLimit-Policy:
              $ref: "#/components/headers/RateLimitPolicy"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
  /api/v1/info:
    get:
      summary: Informações Institucionais do Instituto Cestari (v1)
      operationId: getInfoApiV1
      tags:
        - Institucional v1
      description: Retorna dados cadastrais, propósito, endereço físico, horário de funcionamento e canais de atendimento.
      parameters:
        - $ref: "#/components/parameters/ApiVersionHeader"
        - $ref: "#/components/parameters/InfoSectionQuery"
      responses:
        200:
          description: Informações institucionais retornadas com sucesso
          headers:
            Api-Version:
              $ref: "#/components/headers/ApiVersion"
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InfoResponse"
  /api/v1/services:
    get:
      summary: Lista de Especialidades e Procedimentos de Medicina Avançada (v1)
      operationId: getServicesApiV1
      tags:
        - Serviços v1
      description: Retorna o catálogo completo de tratamentos médicos, psiquiátricos, psicológicos e diagnósticos de alta complexidade.
      parameters:
        - $ref: "#/components/parameters/ApiVersionHeader"
        - $ref: "#/components/parameters/ServicesCategoryQuery"
      responses:
        200:
          description: Lista de serviços retornada com sucesso
          headers:
            Api-Version:
              $ref: "#/components/headers/ApiVersion"
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServicesResponse"
  /api/v1/corpo-clinico:
    get:
      summary: Corpo Clínico e Equipe Multidisciplinar (v1)
      operationId: getCorpoClinicoApiV1
      tags:
        - Equipe v1
      description: Lista os médicos psiquiatras, clínicos, psicólogos e neuropsicólogos com seus respectivos registros profissionais e biografias clínicas.
      parameters:
        - $ref: "#/components/parameters/ApiVersionHeader"
        - $ref: "#/components/parameters/CorpoClinicoSpecialtyQuery"
      responses:
        200:
          description: Equipe clínica retornada com sucesso
          headers:
            Api-Version:
              $ref: "#/components/headers/ApiVersion"
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CorpoClinicoResponse"
  /api/v1/contact:
    get:
      summary: Canais Oficiais de Contato e Agendamento (v1)
      operationId: getContactInfoApiV1
      tags:
        - Contato v1
      description: Fornece números de WhatsApp oficiais, link direto de atendimento, telefone fixo, e-mail e endereço físico completo.
      parameters:
        - $ref: "#/components/parameters/ApiVersionHeader"
        - $ref: "#/components/parameters/ContactChannelQuery"
      responses:
        200:
          description: Canais de contato retornados com sucesso
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactResponse"
    post:
      summary: Enviar Solicitação de Contato ou Agendamento (v1)
      operationId: submitContactInquiryApiV1
      tags:
        - Contato v1
      description: Recebe dados de triagem inicial e gera o link formatado para finalização imediata no WhatsApp oficial do Instituto Cestari.
      parameters:
        - $ref: "#/components/parameters/ApiVersionHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContactInquiryRequest"
      responses:
        200:
          description: Solicitação processada com sucesso
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactInquiryResponse"
        400:
          description: Requisição inválida ou campos obrigatórios ausentes
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/health:
    get:
      summary: Verificação de Saúde da API (Healthcheck)
      operationId: getHealth
      tags:
        - Sistema
      description: Retorna o status operacional da API e dos serviços do Instituto Cestari.
      parameters:
        - $ref: "#/components/parameters/ApiVersionHeader"
        - $ref: "#/components/parameters/HealthVerboseQuery"
      responses:
        200:
          description: API operacional
          headers:
            Api-Version:
              $ref: "#/components/headers/ApiVersion"
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
  /api/info:
    get:
      summary: Informações Institucionais do Instituto Cestari
      operationId: getInfo
      tags:
        - Institucional
      description: Retorna dados cadastrais, propósito, endereço físico, horário de funcionamento e canais de atendimento.
      parameters:
        - $ref: "#/components/parameters/ApiVersionHeader"
        - $ref: "#/components/parameters/InfoSectionQuery"
      responses:
        200:
          description: Informações institucionais retornadas com sucesso
          headers:
            Api-Version:
              $ref: "#/components/headers/ApiVersion"
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InfoResponse"
  /api/services:
    get:
      summary: Lista de Especialidades e Procedimentos de Medicina Avançada
      operationId: getServices
      tags:
        - Serviços
      description: Retorna o catálogo completo de tratamentos médicos, psiquiátricos, psicológicos e diagnósticos de alta complexidade (Escetamina, Polissonografia, Farmacogenética, Paliperidona).
      parameters:
        - $ref: "#/components/parameters/ApiVersionHeader"
        - $ref: "#/components/parameters/ServicesCategoryQuery"
      responses:
        200:
          description: Lista de serviços retornada com sucesso
          headers:
            Api-Version:
              $ref: "#/components/headers/ApiVersion"
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServicesResponse"
  /api/corpo-clinico:
    get:
      summary: Corpo Clínico e Equipe Multidisciplinar
      operationId: getCorpoClinico
      tags:
        - Equipe
      description: Lista os médicos psiquiatras, clínicos, psicólogos e neuropsicólogos com seus respectivos registros profissionais (CRM, RQE, CRP) e biografias clínicas.
      parameters:
        - $ref: "#/components/parameters/ApiVersionHeader"
        - $ref: "#/components/parameters/CorpoClinicoSpecialtyQuery"
      responses:
        200:
          description: Equipe clínica retornada com sucesso
          headers:
            Api-Version:
              $ref: "#/components/headers/ApiVersion"
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CorpoClinicoResponse"
  /api/contact:
    get:
      summary: Canais Oficiais de Contato e Agendamento
      operationId: getContactInfo
      tags:
        - Contato
      description: Fornece números de WhatsApp oficiais, link direto de atendimento, telefone fixo, e-mail e endereço físico completo.
      parameters:
        - $ref: "#/components/parameters/ApiVersionHeader"
        - $ref: "#/components/parameters/ContactChannelQuery"
      responses:
        200:
          description: Canais de contato retornados com sucesso
          headers:
            Api-Version:
              $ref: "#/components/headers/ApiVersion"
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactResponse"
    post:
      summary: Enviar Solicitação de Contato ou Agendamento
      operationId: submitContactInquiry
      tags:
        - Contato
      description: Recebe dados de triagem inicial e gera o link formatado para finalização imediata no WhatsApp oficial do Instituto Cestari.
      parameters:
        - $ref: "#/components/parameters/ApiVersionHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContactInquiryRequest"
      responses:
        200:
          description: Solicitação processada com sucesso
          headers:
            Api-Version:
              $ref: "#/components/headers/ApiVersion"
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactInquiryResponse"
        400:
          description: Requisição inválida ou campos obrigatórios ausentes
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
components:
  parameters:
    ApiVersionHeader:
      name: Api-Version
      in: header
      required: false
      description: "Versão semântica da API solicitada pelo cliente ou agente (ex: '1.0.0' ou '1'). Padrão: 1.0.0"
      schema:
        type: string
        default: 1.0.0
        example: 1.0.0
    HealthVerboseQuery:
      name: verbose
      in: query
      required: false
      description: Se verdadeiro, inclui detalhes estendidos de status e latência.
      schema:
        type: boolean
        default: false
    InfoSectionQuery:
      name: section
      in: query
      required: false
      description: "Filtrar por seção de interesse: 'all', 'contact', 'address' ou 'hours'."
      schema:
        type: string
        enum:
          - all
          - contact
          - address
          - hours
        default: all
    ServicesCategoryQuery:
      name: category
      in: query
      required: false
      description: Filtrar serviços médicos pela categoria clínica.
      schema:
        type: string
        enum:
          - all
          - psiquiatria
          - psicologia
          - medicina_avancada
          - diagnosticos
        default: all
    CorpoClinicoSpecialtyQuery:
      name: specialty
      in: query
      required: false
      description: Filtrar integrantes do corpo clínico por especialidade profissional.
      schema:
        type: string
        enum:
          - all
          - psiquiatria
          - psicologia
          - neuropsicologia
        default: all
    ContactChannelQuery:
      name: channel
      in: query
      required: false
      description: Filtrar canais de atendimento desejados.
      schema:
        type: string
        enum:
          - all
          - whatsapp
          - phone
          - email
        default: all
  headers:
    ApiVersion:
      description: Versão semântica oficial da API em execução.
      schema:
        type: string
        example: 1.0.0
    RateLimitLimit:
      description: Número máximo de requisições permitidas por janela.
      schema:
        type: integer
        example: 120
    RateLimitRemaining:
      description: Número de requisições restantes na janela atual.
      schema:
        type: integer
        example: 119
    RateLimitReset:
      description: Segundos restantes até a renovação da janela de taxa.
      schema:
        type: integer
        example: 60
    RateLimitPolicy:
      description: Política de taxa aplicável no formato quota;w=segundos.
      schema:
        type: string
        example: 120;w=60
    XRateLimitLimit:
      description: "Header legado de compatibilidade: limite de requisições."
      schema:
        type: integer
        example: 120
    XRateLimitRemaining:
      description: "Header legado de compatibilidade: requisições restantes."
      schema:
        type: integer
        example: 119
    XRateLimitReset:
      description: "Header legado de compatibilidade: segundos até o reset."
      schema:
        type: integer
        example: 60
    Deprecation:
      description: Data RFC 8594 anunciando depreciação do endpoint quando aplicável.
      schema:
        type: string
        example: "@1798761600"
    Sunset:
      description: Data RFC 8594 de desativação definitiva do endpoint quando aplicável.
      schema:
        type: string
        example: Wed, 30 Jun 2027 23:59:59 GMT
    RetryAfter:
      description: Segundos que o cliente deve aguardar antes de tentar novamente (HTTP 429).
      schema:
        type: integer
        example: 60
  schemas:
    ErrorResponse:
      type: object
      description: Formato estruturado de erro da API
      required:
        - error
      properties:
        error:
          type: object
          description: Objeto detalhado do erro
          required:
            - code
            - message
            - hint
          properties:
            code:
              type: string
              example: API_ENDPOINT_NOT_FOUND
              description: Código de erro padronizado para consumo programático
            message:
              type: string
              example: O endpoint da API solicitado não foi encontrado.
              description: Descrição amigável em português sobre a causa do erro
            hint:
              type: string
              example: Consulte /openapi.json ou a documentação em /docs para endpoints válidos.
              description: Dica prática de resolução orientada a agentes e desenvolvedores
    HealthResponse:
      type: object
      description: Status operacional do serviço e timestamp
      required:
        - status
        - service
        - version
        - timestamp
      properties:
        status:
          type: string
          example: ok
          description: Indicador de disponibilidade operacional ('ok')
        service:
          type: string
          example: Instituto Cestari Public API
          description: Nome oficial do serviço de API
        version:
          type: string
          example: 1.0.0
          description: Versão semântica da API em execução
        timestamp:
          type: string
          format: date-time
          example: 2026-09-22T17:45:00.000Z
          description: Data e hora no formato ISO-8601 UTC do momento da consulta
    Address:
      type: object
      description: Endereço geográfico padronizado da clínica
      required:
        - street
        - neighborhood
        - city
        - state
        - postalCode
        - country
      properties:
        street:
          type: string
          example: Rua José Sequeira Bueno, 195
          description: Logradouro, número e complemento
        neighborhood:
          type: string
          example: Jd. Vista Alegre
          description: Bairro
        city:
          type: string
          example: Piracaia
          description: Cidade
        state:
          type: string
          example: SP
          description: Sigla da Unidade Federativa (UF)
        postalCode:
          type: string
          example: 12970-000
          description: Código de Endereçamento Postal (CEP)
        country:
          type: string
          example: Brasil
          description: Nome do país
    InfoResponse:
      type: object
      description: Informações institucionais completas do Instituto Cestari
      required:
        - name
        - legalName
        - description
        - address
        - phone
        - email
        - hours
        - modalities
      properties:
        name:
          type: string
          example: Instituto Cestari
          description: Nome fantasia da clínica médica
        legalName:
          type: string
          example: Instituto Cestari Medicina Avançada
          description: "Razão social oficial (CNPJ: 20.291.441/0001-05)"
        description:
          type: string
          example: Centro de excelência médica e saúde mental em Piracaia - SP. Especialidades em psiquiatria, psicologia, clínica médica e medicina avançada.
          description: Resumo institucional e escopo das atividades clínicas
        address:
          $ref: "#/components/schemas/Address"
        phone:
          type: string
          example: +55 11 99661-0911
          description: Telefone e WhatsApp para contato e triagem
        email:
          type: string
          format: email
          example: Institutocestari@outlook.com
          description: E-mail de contato da instituição
        hours:
          type: string
          example: "Segunda a Sexta-feira: 08:00 às 19:00"
          description: Horário de funcionamento ambulatorial
        modalities:
          type: array
          description: Lista de modalidades de atendimento disponíveis aos pacientes
          items:
            type: string
            example: Presencial em Piracaia - SP
            description: Descrição textual da modalidade clínica
          example:
            - Presencial em Piracaia - SP
            - Telemedicina para todo o Brasil
    ServiceItem:
      type: object
      description: Item individual do catálogo de serviços e especialidades
      required:
        - id
        - category
        - name
        - description
        - url
      properties:
        id:
          type: string
          example: infusao-escetamina
          description: Identificador único (slug) do procedimento para consultas e URLs
        category:
          type: string
          example: Medicina Avançada
          description: "Categoria clínica do serviço (ex: Medicina Avançada, Especialidades)"
        name:
          type: string
          example: Infusão de Escetamina
          description: Nome oficial do tratamento ou procedimento médico
        description:
          type: string
          example: Protocolo ambulatorial monitorado para depressão resistente a tratamentos convencionais.
          description: Resumo clínico detalhando indicações e objetivos terapêuticos
        url:
          type: string
          format: uri
          example: https://institutocestari.com.br/saude-mental/infusao-escetamina
          description: URL canônica da página dedicada com detalhes aprofundados
    ServicesResponse:
      type: object
      description: Catálogo completo de especialidades e procedimentos de medicina avançada
      required:
        - services
      properties:
        services:
          type: array
          description: Coleção de procedimentos clínicos e exames diagnósticos
          items:
            $ref: "#/components/schemas/ServiceItem"
    CorpoClinicoMember:
      type: object
      description: Perfil profissional de membro da equipe clínica
      required:
        - name
        - role
        - registry
        - bio
      properties:
        name:
          type: string
          example: Dr. Laerte Ferreirinha Cestari
          description: Nome completo do profissional de saúde
        role:
          type: string
          example: Médico Psiquiatra
          description: Cargo ou especialidade principal
        registry:
          type: string
          example: CRM-SP 163.272 / RQE 97.612
          description: Número de registro no conselho profissional correspondente (CRM/RQE ou CRP)
        bio:
          type: string
          example: Mais de 10 anos de experiência em saúde mental, especialista em psiquiatria clínica e avaliações periciais.
          description: Breve histórico de formação e atuação clínica
    CorpoClinicoResponse:
      type: object
      description: Corpo clínico multidisciplinar atuante no Instituto Cestari
      required:
        - team
      properties:
        team:
          type: array
          description: Lista de médicos e psicólogos credenciados
          items:
            $ref: "#/components/schemas/CorpoClinicoMember"
    ContactResponse:
      type: object
      description: Canais oficiais de contato e agendamento
      required:
        - primaryWhatsApp
        - whatsappUrl
        - telephone
        - email
        - address
        - bookingInstructions
      properties:
        primaryWhatsApp:
          type: string
          example: +55 11 99661-0911
          description: Número oficial do WhatsApp para atendimento em formato internacional
        whatsappUrl:
          type: string
          format: uri
          example: https://wa.me/5511996610911
          description: Link direto para início imediato da conversa no WhatsApp
        telephone:
          type: string
          example: +55 11 99661-0911
          description: Telefone para contato telefônico direto
        email:
          type: string
          format: email
          example: Institutocestari@outlook.com
          description: E-mail de atendimento
        address:
          type: string
          example: Rua José Sequeira Bueno, 195 - Jd. Vista Alegre, Piracaia - SP
          description: Endereço físico formatado da clínica
        bookingInstructions:
          type: string
          example: Envie mensagem no WhatsApp informando nome e se deseja atendimento presencial em Piracaia ou Telemedicina.
          description: Instruções passo a passo para pacientes e agentes realizarem o agendamento
    ContactInquiryRequest:
      type: object
      description: Dados para solicitação de agendamento ou informações
      required:
        - name
        - contactMethod
      properties:
        name:
          type: string
          example: Maria Silva
          description: Nome completo do paciente ou interessado
        contactMethod:
          type: string
          example: +55 11 99999-9999
          description: Número de telefone ou WhatsApp para retorno
        serviceOfInterest:
          type: string
          example: Infusão de Escetamina
          description: Nome do procedimento ou especialidade clínica desejada
        modality:
          type: string
          enum:
            - presencial
            - online
            - indiferente
          default: presencial
          description: "Modalidade de preferência do atendimento: 'presencial' em Piracaia ou 'online' por telemedicina"
        message:
          type: string
          example: Gostaria de agendar uma avaliação para tratamento de depressão.
          description: Mensagem descritiva com o motivo do contato ou dúvidas prévias
    ContactInquiryResponse:
      type: object
      description: Confirmação do envio da solicitação e link de direcionamento
      required:
        - success
        - message
        - whatsappRedirectUrl
      properties:
        success:
          type: boolean
          example: true
          description: Booleano confirmando o recebimento da solicitação
        message:
          type: string
          example: Solicitação registrada com sucesso.
          description: Mensagem informativa sobre o próximo passo
        whatsappRedirectUrl:
          type: string
          format: uri
          example: https://wa.me/5511996610911?text=Ol%C3%A1%2C%20gostaria%20de%20informa%C3%A7%C3%B5es
          description: URL com mensagem pré-formatada pronta para envio no WhatsApp