openapi: 3.1.0
info:
  title: Takeat — API Externa V1.0
  version: 1.0.0
  description: |
    Nova API externa da Takeat. Chaves `tk_live_` e `tk_test_` criadas no
    AI Builders são trocadas por access tokens curtos e refresh tokens rotativos em
    `/oauth/token`. Os endpoints de dados ficam sob `/v1` e aceitam no header
    `Authorization: Bearer {token}` tanto um access token OAuth quanto a sessão
    autenticada do próprio restaurante. Tokens OAuth exigem o escopo documentado;
    sessões de restaurante ficam limitadas ao `restaurant_id` assinado no token.
    Chaves `tk_` não são aceitas diretamente nas rotas de dados.
    Respostas de erro incluem `X-Error-Id`, um identificador de correlação
    acessível por CORS para informar ao suporte. Os envelopes V1 e OAuth
    permanecem inalterados; não envie credenciais em relatos de erro.
servers:
  - url: https://public-api.takeat.app
    description: Produção

tags:
  - name: Salão e mesas
    description: Mesas, métricas, reservas, chamados e consulta de caixas para integrações.
  - name: Relatórios · Pagamentos
    x-displayName: Pagamentos
    description: Relatórios de leitura de Pagamentos.
  - name: Relatórios · Clientes
    x-displayName: Clientes
    description: Relatórios de leitura de Clientes.
  - name: Relatórios · Produtos
    x-displayName: Produtos
    description: Relatórios de leitura de Produtos.
  - name: Relatórios · KDS
    x-displayName: KDS
    description: Relatórios de leitura de KDS.
  - name: Takeat Store
    description: Avaliações do próprio app identificado pela conexão OAuth.
  - name: Restaurante
    description: Status da conta e funcionalidades disponíveis para tutoriais.
  - name: Autenticação
    description: Emissão, renovação e revogação de tokens.
  - name: Marcas
    description: Marcas do restaurante e identificação comercial.
  - name: Cardápio
    description: Cardápio publicado por canal de venda.
  - name: Pedidos
    description: Sessões de comanda, contas, pedidos e pagamentos.
  - name: Catálogo
    description: Produtos, complementos e métodos de pagamento.
  - name: Complementos
    description: Consulta e edição de complementos, preços, fiscal e disponibilidade.
  - name: Avaliações
    description: Avaliações de clientes, notas e comentários do restaurante.
  - name: Clientes
    description: Buyers vinculados ao restaurante, compras e informações do Clube.
  - name: Clube de Fidelidade
    description: Clientes do Clube de Fidelidade.
  - name: Estoque
    description: Insumos e produtos intermediários ativos.
  - name: Financeiro
    description: Lançamentos, contas a pagar e receber e totais financeiros.
  - name: Fiscal
    description: Consulta de NF-e recebidas.

  - name: Garçom · Perfil
    x-displayName: Perfil
    description: Identidade da autorização pessoal.
  - name: Garçom · Cardápio
    x-displayName: Cardápio
    description: Cardápio publicado e marcas ativas.
  - name: Garçom · Mesas
    x-displayName: Mesas
    description: Identificação e situação das mesas.
  - name: Garçom · Comandas
    x-displayName: Comandas
    description: Comandas presenciais ativas com dados reduzidos.
  - name: Garçom · Pedidos
    x-displayName: Pedidos
    description: Itens dos pedidos presenciais ativos.

security:
  - bearerAuth: []

x-tagGroups: &ref_0
  - name: Restaurante
    icon: store
    description: Dados e gestão das lojas e endpoints compartilhados de tokens.
    tags:
      - Autenticação
      - Takeat Store
      - Restaurante
      - Marcas
      - Cardápio
      - Pedidos
      - Salão e mesas
      - Catálogo
      - Complementos
      - Avaliações
      - Clientes
      - Clube de Fidelidade
      - Estoque
      - Financeiro
      - Fiscal
  - name: Relatórios
    icon: chart-no-axes-combined
    description: Indicadores e análises de pagamentos, clientes, produtos e KDS para integrações de restaurantes.
    tags:
      - Relatórios · Pagamentos
      - Relatórios · Clientes
      - Relatórios · Produtos
      - Relatórios · KDS
  - name: Garçom
    icon: hand-platter
    description: Consultas limitadas ao atendimento, com autorização OAuth pessoal e PKCE.
    tags:
      - Garçom · Perfil
      - Garçom · Cardápio
      - Garçom · Mesas
      - Garçom · Comandas
      - Garçom · Pedidos
x-takeat-reference-groups: *ref_0

paths:
  /v1/reports/payments/summary:
    get:
      operationId: getReportPaymentsSummary
      tags:
        - Relatórios · Pagamentos
      summary: Resumo de pagamentos
      description: >-
        Consulte a série de pagamentos por dia ou por mês usando granularity. A opção filtered permite recortar o período por marca, canal e forma de pagamento. Informe as datas ou os meses correspondentes à escolha. Exige reports:payments:read e restaurante autorizado; preserva o corpo e os cálculos da variante selecionada. Veja exemplos no guia de relatórios.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:payments:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - name: granularity
          in: query
          required: false
          description: >-
            Granularidade: daily = diária; monthly = mensal; filtered = período com filtros de pagamentos.
            Padrão: diária.
          schema:
            type: string
            enum:
              - daily
              - monthly
              - filtered
            default: daily
        - name: start_date
          in: query
          required: false
          description: >-
            Início do período (YYYY-MM-DD). No KDS também aceita ISO com timezone. Obrigatório quando
            granularity=daily ou filtered; ignorado no modo mensal.
          schema:
            type: string
          example: '2026-11-01'
        - name: end_date
          in: query
          required: false
          description: >-
            Fim do período (YYYY-MM-DD). KDS inclui o dia civil de Brasília; com ISO, o instante final é
            exclusivo. KDS: máximo 92 dias. Obrigatório quando granularity=daily ou filtered; ignorado no modo
            mensal.
          schema:
            type: string
          example: '2026-11-07'
        - name: start_month
          in: query
          required: false
          description: Primeiro mês (YYYY-MM). Obrigatório quando granularity=monthly; ignorado nos outros modos.
          schema:
            type: string
          example: 2026-11
        - name: end_month
          in: query
          required: false
          description: Último mês (YYYY-MM). Obrigatório quando granularity=monthly; ignorado nos outros modos.
          schema:
            type: string
          example: 2026-11
        - $ref: '#/components/parameters/ReportFill'
        - $ref: '#/components/parameters/ReportBrandId'
        - $ref: '#/components/parameters/ReportChannelGroup'
        - $ref: '#/components/parameters/ReportChannel'
        - $ref: '#/components/parameters/ReportPaymentMethodId'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/payments/methods:
    get:
      operationId: getReportPaymentsMethods
      tags:
        - Relatórios · Pagamentos
      summary: Pagamentos por forma
      description: >-
        Consulte a série de pagamentos por dia ou por mês usando granularity. A opção filtered permite recortar o período por marca, canal e forma de pagamento. Informe as datas ou os meses correspondentes à escolha. Exige reports:payments:read e restaurante autorizado; preserva o corpo e os cálculos da variante selecionada. Veja exemplos no guia de relatórios.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:payments:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - name: granularity
          in: query
          required: false
          description: >-
            Granularidade: daily = diária; monthly = mensal; filtered = período com filtros de pagamentos.
            Padrão: diária.
          schema:
            type: string
            enum:
              - daily
              - monthly
              - filtered
            default: daily
        - name: start_date
          in: query
          required: false
          description: >-
            Início do período (YYYY-MM-DD). No KDS também aceita ISO com timezone. Obrigatório quando
            granularity=daily ou filtered; ignorado no modo mensal.
          schema:
            type: string
          example: '2026-11-01'
        - name: end_date
          in: query
          required: false
          description: >-
            Fim do período (YYYY-MM-DD). KDS inclui o dia civil de Brasília; com ISO, o instante final é
            exclusivo. KDS: máximo 92 dias. Obrigatório quando granularity=daily ou filtered; ignorado no modo
            mensal.
          schema:
            type: string
          example: '2026-11-07'
        - name: start_month
          in: query
          required: false
          description: Primeiro mês (YYYY-MM). Obrigatório quando granularity=monthly; ignorado nos outros modos.
          schema:
            type: string
          example: 2026-11
        - name: end_month
          in: query
          required: false
          description: Último mês (YYYY-MM). Obrigatório quando granularity=monthly; ignorado nos outros modos.
          schema:
            type: string
          example: 2026-11
        - $ref: '#/components/parameters/ReportBrandId'
        - $ref: '#/components/parameters/ReportChannelGroup'
        - $ref: '#/components/parameters/ReportChannel'
        - $ref: '#/components/parameters/ReportPaymentMethodId'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/payments/channels:
    get:
      operationId: getReportPaymentsChannels
      tags:
        - Relatórios · Pagamentos
      summary: Pagamentos por canal
      description: >-
        Consulte a série de pagamentos por dia ou por mês usando granularity. A opção filtered permite recortar o período por marca, canal e forma de pagamento. Informe as datas ou os meses correspondentes à escolha. Exige reports:payments:read e restaurante autorizado; preserva o corpo e os cálculos da variante selecionada. Veja exemplos no guia de relatórios.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:payments:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - name: granularity
          in: query
          required: false
          description: >-
            Granularidade: daily = diária; monthly = mensal; filtered = período com filtros de pagamentos.
            Padrão: diária.
          schema:
            type: string
            enum:
              - daily
              - monthly
              - filtered
            default: daily
        - name: start_date
          in: query
          required: false
          description: >-
            Início do período (YYYY-MM-DD). No KDS também aceita ISO com timezone. Obrigatório quando
            granularity=daily ou filtered; ignorado no modo mensal.
          schema:
            type: string
          example: '2026-11-01'
        - name: end_date
          in: query
          required: false
          description: >-
            Fim do período (YYYY-MM-DD). KDS inclui o dia civil de Brasília; com ISO, o instante final é
            exclusivo. KDS: máximo 92 dias. Obrigatório quando granularity=daily ou filtered; ignorado no modo
            mensal.
          schema:
            type: string
          example: '2026-11-07'
        - name: start_month
          in: query
          required: false
          description: Primeiro mês (YYYY-MM). Obrigatório quando granularity=monthly; ignorado nos outros modos.
          schema:
            type: string
          example: 2026-11
        - name: end_month
          in: query
          required: false
          description: Último mês (YYYY-MM). Obrigatório quando granularity=monthly; ignorado nos outros modos.
          schema:
            type: string
          example: 2026-11
        - $ref: '#/components/parameters/ReportBrandId'
        - $ref: '#/components/parameters/ReportChannelGroup'
        - $ref: '#/components/parameters/ReportChannel'
        - $ref: '#/components/parameters/ReportPaymentMethodId'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/customers/summary:
    get:
      operationId: getReportCustomersSummary
      tags:
        - Relatórios · Clientes
      summary: Resumo de clientes
      description: >-
        Consulte a série de clientes por dia ou por mês usando granularity. Informe as datas ou os meses correspondentes à escolha. Exige reports:customers:read e restaurante autorizado; preserva o corpo e os cálculos da variante selecionada. Veja exemplos no guia de relatórios.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:customers:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - name: granularity
          in: query
          required: false
          description: 'Granularidade: daily = diária; monthly = mensal. Padrão: diária.'
          schema:
            type: string
            enum:
              - daily
              - monthly
            default: daily
        - name: start_date
          in: query
          required: false
          description: >-
            Início do período (YYYY-MM-DD). No KDS também aceita ISO com timezone. Obrigatório quando
            granularity=daily; ignorado no modo mensal.
          schema:
            type: string
          example: '2026-11-01'
        - name: end_date
          in: query
          required: false
          description: >-
            Fim do período (YYYY-MM-DD). KDS inclui o dia civil de Brasília; com ISO, o instante final é
            exclusivo. KDS: máximo 92 dias. Obrigatório quando granularity=daily; ignorado no modo mensal.
          schema:
            type: string
          example: '2026-11-07'
        - name: start_month
          in: query
          required: false
          description: Primeiro mês (YYYY-MM). Obrigatório quando granularity=monthly; ignorado nos outros modos.
          schema:
            type: string
          example: 2026-11
        - name: end_month
          in: query
          required: false
          description: Último mês (YYYY-MM). Obrigatório quando granularity=monthly; ignorado nos outros modos.
          schema:
            type: string
          example: 2026-11
        - $ref: '#/components/parameters/ReportChannel'
        - $ref: '#/components/parameters/ReportFill'
        - $ref: '#/components/parameters/ReportPhoneBreakdown'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/customers/retention:
    get:
      operationId: getReportCustomersRetention
      tags:
        - Relatórios · Clientes
      summary: Retenção de clientes
      description: >-
        Consulte a série de clientes por dia ou por mês usando granularity. Informe as datas ou os meses correspondentes à escolha. Exige reports:customers:read e restaurante autorizado; preserva o corpo e os cálculos da variante selecionada. Veja exemplos no guia de relatórios.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:customers:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - name: granularity
          in: query
          required: false
          description: 'Granularidade: daily = diária; monthly = mensal. Padrão: diária.'
          schema:
            type: string
            enum:
              - daily
              - monthly
            default: daily
        - name: start_date
          in: query
          required: false
          description: >-
            Início do período (YYYY-MM-DD). No KDS também aceita ISO com timezone. Obrigatório quando
            granularity=daily; ignorado no modo mensal.
          schema:
            type: string
          example: '2026-11-01'
        - name: end_date
          in: query
          required: false
          description: >-
            Fim do período (YYYY-MM-DD). KDS inclui o dia civil de Brasília; com ISO, o instante final é
            exclusivo. KDS: máximo 92 dias. Obrigatório quando granularity=daily; ignorado no modo mensal.
          schema:
            type: string
          example: '2026-11-07'
        - name: start_month
          in: query
          required: false
          description: Primeiro mês (YYYY-MM). Obrigatório quando granularity=monthly; ignorado nos outros modos.
          schema:
            type: string
          example: 2026-11
        - name: end_month
          in: query
          required: false
          description: Último mês (YYYY-MM). Obrigatório quando granularity=monthly; ignorado nos outros modos.
          schema:
            type: string
          example: 2026-11
        - $ref: '#/components/parameters/ReportChannel'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/customers/visit-retention:
    get:
      operationId: getReportCustomersVisitRetention
      tags:
        - Relatórios · Clientes
      summary: Retenção por frequência de visitas
      description: >-
        Consulte a série de clientes por dia ou por mês usando granularity. Informe as datas ou os meses correspondentes à escolha. Exige reports:customers:read e restaurante autorizado; preserva o corpo e os cálculos da variante selecionada. Veja exemplos no guia de relatórios.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:customers:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - name: granularity
          in: query
          required: false
          description: 'Granularidade: daily = diária; monthly = mensal. Padrão: diária.'
          schema:
            type: string
            enum:
              - daily
              - monthly
            default: daily
        - name: start_date
          in: query
          required: false
          description: >-
            Início do período (YYYY-MM-DD). No KDS também aceita ISO com timezone. Obrigatório quando
            granularity=daily; ignorado no modo mensal.
          schema:
            type: string
          example: '2026-11-01'
        - name: end_date
          in: query
          required: false
          description: >-
            Fim do período (YYYY-MM-DD). KDS inclui o dia civil de Brasília; com ISO, o instante final é
            exclusivo. KDS: máximo 92 dias. Obrigatório quando granularity=daily; ignorado no modo mensal.
          schema:
            type: string
          example: '2026-11-07'
        - name: start_month
          in: query
          required: false
          description: Primeiro mês (YYYY-MM). Obrigatório quando granularity=monthly; ignorado nos outros modos.
          schema:
            type: string
          example: 2026-11
        - name: end_month
          in: query
          required: false
          description: Último mês (YYYY-MM). Obrigatório quando granularity=monthly; ignorado nos outros modos.
          schema:
            type: string
          example: 2026-11
        - $ref: '#/components/parameters/ReportChannel'
        - $ref: '#/components/parameters/ReportPhoneBreakdown'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/products/summary:
    get:
      operationId: getReportProductsSummary
      tags:
        - Relatórios · Produtos
      summary: Resumo de vendas de produtos
      description: >-
        Consulte a série de vendas de produtos por dia ou por mês usando granularity. Informe as datas ou os meses correspondentes à escolha. Exige reports:products:read e restaurante autorizado; preserva o corpo e os cálculos da variante selecionada. Veja exemplos no guia de relatórios.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:products:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - name: granularity
          in: query
          required: false
          description: 'Granularidade: daily = diária; monthly = mensal. Padrão: diária.'
          schema:
            type: string
            enum:
              - daily
              - monthly
            default: daily
        - name: start_date
          in: query
          required: false
          description: >-
            Início do período (YYYY-MM-DD). No KDS também aceita ISO com timezone. Obrigatório quando
            granularity=daily; ignorado no modo mensal.
          schema:
            type: string
          example: '2026-11-01'
        - name: end_date
          in: query
          required: false
          description: >-
            Fim do período (YYYY-MM-DD). KDS inclui o dia civil de Brasília; com ISO, o instante final é
            exclusivo. KDS: máximo 92 dias. Obrigatório quando granularity=daily; ignorado no modo mensal.
          schema:
            type: string
          example: '2026-11-07'
        - name: start_month
          in: query
          required: false
          description: Primeiro mês (YYYY-MM). Obrigatório quando granularity=monthly; ignorado nos outros modos.
          schema:
            type: string
          example: 2026-11
        - name: end_month
          in: query
          required: false
          description: Último mês (YYYY-MM). Obrigatório quando granularity=monthly; ignorado nos outros modos.
          schema:
            type: string
          example: 2026-11
        - $ref: '#/components/parameters/ReportFill'
        - $ref: '#/components/parameters/ReportCompare'
        - $ref: '#/components/parameters/ReportIncludeToday'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/tables:
    get:
      operationId: listSalonTables
      tags:
        - Salão e mesas
      summary: Consultar mesas
      description: >-
        Exige tables:read e access token de integração do restaurante. Consulte o guia de salão para limites,
        qualidade do histórico e consultas de reservas existentes.
      security:
        - salonIntegration: []
      x-required-scopes:
        - tables:read
      parameters:
        - $ref: '#/components/parameters/SalonRestaurantId'
      responses:
        '200':
          description: Resultado da operação.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SalonTablesResponse'
        '400':
          description: Payload, período ou cursor inválido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Token ausente, inválido, expirado ou revogado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo, perfil ou restaurante não autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Recurso não encontrado no restaurante autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: Projeção excedeu o limite de segurança.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/tables/history:
    get:
      operationId: listSalonHistory
      tags:
        - Salão e mesas
      summary: Histórico consolidado de mesas
      description: >-
        Exige table-sessions:read e access token de integração do restaurante. Consulte o guia de salão para
        limites, qualidade do histórico e consultas de reservas existentes.
      security:
        - salonIntegration: []
      x-required-scopes:
        - table-sessions:read
      parameters:
        - $ref: '#/components/parameters/SalonRestaurantId'
        - $ref: '#/components/parameters/SalonStart'
        - $ref: '#/components/parameters/SalonEnd'
        - $ref: '#/components/parameters/SalonLimit'
        - $ref: '#/components/parameters/SalonCursor'
        - name: table_id
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
          description: Filtro de mesa; se a URL já contiver uma mesa, os seletores devem coincidir.
        - name: table_type
          in: query
          schema:
            type: string
            enum:
              - table
              - lounge
              - balcony
          description: Tipo físico da mesa. O histórico de balcão aceita apenas balcony.
      responses:
        '200':
          description: Resultado da operação.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SalonHistoryPage'
        '400':
          description: Payload, período ou cursor inválido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Token ausente, inválido, expirado ou revogado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo, perfil ou restaurante não autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Recurso não encontrado no restaurante autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: Projeção excedeu o limite de segurança.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/tables/{tableId}/history:
    get:
      operationId: listSalonTableHistory
      tags:
        - Salão e mesas
      summary: Histórico de uma mesa
      description: >-
        Exige table-sessions:read e access token de integração do restaurante. Consulte o guia de salão para
        limites, qualidade do histórico e consultas de reservas existentes.
      security:
        - salonIntegration: []
      x-required-scopes:
        - table-sessions:read
      parameters:
        - $ref: '#/components/parameters/SalonRestaurantId'
        - $ref: '#/components/parameters/SalonTableId'
        - $ref: '#/components/parameters/SalonStart'
        - $ref: '#/components/parameters/SalonEnd'
        - $ref: '#/components/parameters/SalonLimit'
        - $ref: '#/components/parameters/SalonCursor'
        - name: table_id
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
          description: Filtro de mesa; se a URL já contiver uma mesa, os seletores devem coincidir.
        - name: table_type
          in: query
          schema:
            type: string
            enum:
              - table
              - lounge
              - balcony
          description: Tipo físico da mesa. O histórico de balcão aceita apenas balcony.
      responses:
        '200':
          description: Resultado da operação.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SalonHistoryPage'
        '400':
          description: Payload, período ou cursor inválido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Token ausente, inválido, expirado ou revogado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo, perfil ou restaurante não autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Recurso não encontrado no restaurante autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: Projeção excedeu o limite de segurança.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/table-assistance:
    get:
      operationId: listSalonAssistance
      tags:
        - Salão e mesas
      summary: Consultar chamados de mesas
      description: >-
        Exige table-assistance:read e access token de integração do restaurante. Consulte o guia de salão para
        limites, qualidade do histórico e consultas de reservas existentes.
      security:
        - salonIntegration: []
      x-required-scopes:
        - table-assistance:read
      parameters:
        - $ref: '#/components/parameters/SalonRestaurantId'
        - $ref: '#/components/parameters/SalonStart'
        - $ref: '#/components/parameters/SalonEnd'
        - $ref: '#/components/parameters/SalonLimit'
        - $ref: '#/components/parameters/SalonCursor'
        - name: table_id
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
          description: Filtro de mesa; se a URL já contiver uma mesa, os seletores devem coincidir.
        - name: status
          in: query
          schema:
            type: string
            enum:
              - pending
              - attended
      responses:
        '200':
          description: Resultado da operação.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SalonAssistancePage'
        '400':
          description: Payload, período ou cursor inválido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Token ausente, inválido, expirado ou revogado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo, perfil ou restaurante não autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Recurso não encontrado no restaurante autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: Projeção excedeu o limite de segurança.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/cash-register:
    get:
      operationId: listSalonCashRegisters
      tags:
        - Salão e mesas
      summary: Consultar caixas em aberto
      description: >-
        Exige cash-register:read e access token de integração do restaurante. Consulte o guia de salão para
        limites, qualidade do histórico e consultas de reservas existentes.
      security:
        - salonIntegration: []
      x-required-scopes:
        - cash-register:read
      parameters:
        - $ref: '#/components/parameters/SalonRestaurantId'
        - name: cashier_id
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
      responses:
        '200':
          description: Resultado da operação.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SalonCashResponse'
        '400':
          description: Payload, período ou cursor inválido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Token ausente, inválido, expirado ou revogado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo, perfil ou restaurante não autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Recurso não encontrado no restaurante autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: Projeção excedeu o limite de segurança.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/counter-mode/history:
    get:
      operationId: listSalonCounterHistory
      tags:
        - Salão e mesas
      summary: Histórico de balcão
      description: >-
        Exige table-sessions:read e access token de integração do restaurante. Consulte o guia de salão para
        limites, qualidade do histórico e consultas de reservas existentes.
      security:
        - salonIntegration: []
      x-required-scopes:
        - table-sessions:read
      parameters:
        - $ref: '#/components/parameters/SalonRestaurantId'
        - $ref: '#/components/parameters/SalonStart'
        - $ref: '#/components/parameters/SalonEnd'
        - $ref: '#/components/parameters/SalonLimit'
        - $ref: '#/components/parameters/SalonCursor'
        - name: table_id
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
          description: Filtro de mesa; se a URL já contiver uma mesa, os seletores devem coincidir.
        - name: table_type
          in: query
          schema:
            type: string
            enum:
              - table
              - lounge
              - balcony
          description: Tipo físico da mesa. O histórico de balcão aceita apenas balcony.
      responses:
        '200':
          description: Resultado da operação.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SalonHistoryPage'
        '400':
          description: Payload, período ou cursor inválido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Token ausente, inválido, expirado ou revogado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo, perfil ou restaurante não autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Recurso não encontrado no restaurante autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: Projeção excedeu o limite de segurança.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/tables/{tableId}/reservations:
    get:
      operationId: listSalonReservations
      tags:
        - Salão e mesas
      summary: Consultar reservas da mesa
      description: >-
        Exige reservations:read e access token de integração do restaurante. Consulte o guia de salão para
        limites, qualidade do histórico e consultas de reservas existentes.
      security:
        - salonIntegration: []
      x-required-scopes:
        - reservations:read
      parameters:
        - $ref: '#/components/parameters/SalonRestaurantId'
        - $ref: '#/components/parameters/SalonTableId'
        - $ref: '#/components/parameters/SalonStart'
        - $ref: '#/components/parameters/SalonEnd'
        - $ref: '#/components/parameters/SalonLimit'
        - $ref: '#/components/parameters/SalonCursor'
        - name: table_id
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
          description: Filtro de mesa; se a URL já contiver uma mesa, os seletores devem coincidir.
        - name: status
          in: query
          schema:
            type: string
            enum:
              - pending_payment
              - confirmed
              - checked_in
              - finished
              - cancelled
              - no_show
              - expired
      responses:
        '200':
          description: Resultado da operação.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SalonReservationPage'
        '400':
          description: Payload, período ou cursor inválido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Token ausente, inválido, expirado ou revogado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo, perfil ou restaurante não autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Recurso não encontrado no restaurante autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: Projeção excedeu o limite de segurança.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/reservations/{reservationId}:
    get:
      operationId: getSalonReservation
      tags:
        - Salão e mesas
      summary: Consultar reserva
      description: >-
        Exige reservations:read e access token de integração do restaurante. Consulte o guia de salão para
        limites, qualidade do histórico e consultas de reservas existentes.
      security:
        - salonIntegration: []
      x-required-scopes:
        - reservations:read
      parameters:
        - $ref: '#/components/parameters/SalonRestaurantId'
        - $ref: '#/components/parameters/SalonReservationId'
      responses:
        '200':
          description: Resultado da operação.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SalonReservation'
        '400':
          description: Payload, período ou cursor inválido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Token ausente, inválido, expirado ou revogado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo, perfil ou restaurante não autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Recurso não encontrado no restaurante autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: Projeção excedeu o limite de segurança.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/tables/metrics:
    get:
      operationId: getSalonMetrics
      tags:
        - Salão e mesas
      summary: Consultar métricas por mesa
      description: >-
        Exige reports:tables:read e access token de integração do restaurante. Consulte o guia de salão para
        limites, qualidade do histórico e consultas de reservas existentes.
      security:
        - salonIntegration: []
      x-required-scopes:
        - reports:tables:read
      parameters:
        - $ref: '#/components/parameters/SalonRestaurantId'
        - $ref: '#/components/parameters/SalonStart'
        - $ref: '#/components/parameters/SalonEnd'
        - name: table_id
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
          description: Filtro de mesa; se a URL já contiver uma mesa, os seletores devem coincidir.
      responses:
        '200':
          description: Resultado da operação.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SalonMetricsResponse'
        '400':
          description: Payload, período ou cursor inválido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Token ausente, inválido, expirado ou revogado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo, perfil ou restaurante não autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Recurso não encontrado no restaurante autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: Projeção excedeu o limite de segurança.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/tables/events:
    get:
      operationId: streamSalonEvents
      tags:
        - Salão e mesas
      summary: Acompanhar atualizações do salão por SSE
      description: >-
        Exige tables:read e access token de integração do restaurante. Consulte o guia de salão para limites,
        qualidade do histórico e consultas de reservas existentes.
      security:
        - salonIntegration: []
      x-required-scopes:
        - tables:read
      parameters:
        - $ref: '#/components/parameters/SalonRestaurantId'
      responses:
        '200':
          description: >-
            Snapshot tables.snapshot, invalidações autorizadas e heartbeat. Sem replay; recarregue após
            reconectar.
          content:
            text/event-stream:
              schema:
                type: string
        '400':
          description: Payload, período ou cursor inválido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Token ausente, inválido, expirado ou revogado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo, perfil ou restaurante não autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Recurso não encontrado no restaurante autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: Projeção excedeu o limite de segurança.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: Dependência não configurada ou indisponível.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Limite de conexões SSE por instância, restaurante ou cliente excedido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/reports/payments/transactions:
    get:
      operationId: getReportPaymentsTransactions
      tags:
        - Relatórios · Pagamentos
      summary: Transações de pagamento
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:payments:read e restaurante autorizado.
        Filtros, valores e paginação mantêm o contrato do serviço de relatórios. Não concede permissões novas a
        tokens existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:payments:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportStartDate'
        - $ref: '#/components/parameters/ReportEndDate'
        - $ref: '#/components/parameters/ReportPaymentMethod'
        - $ref: '#/components/parameters/ReportCursor'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/payments/sessions:
    get:
      operationId: getReportPaymentsSessions
      tags:
        - Relatórios · Pagamentos
      summary: Atendimentos com pagamentos
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:payments:read e restaurante autorizado.
        Filtros, valores e paginação mantêm o contrato do serviço de relatórios. Não concede permissões novas a
        tokens existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:payments:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportAno'
        - $ref: '#/components/parameters/ReportMes'
        - $ref: '#/components/parameters/ReportCursor'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/customers/activity/customers:
    get:
      operationId: getReportCustomersActivityCustomers
      tags:
        - Relatórios · Clientes
      summary: Clientes por atividade
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:customers:read e restaurante autorizado.
        Filtros, valores e paginação mantêm o contrato do serviço de relatórios. Não concede permissões novas a
        tokens existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:customers:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportStartDate'
        - $ref: '#/components/parameters/ReportEndDate'
        - $ref: '#/components/parameters/ReportSegment'
        - $ref: '#/components/parameters/ReportChannel'
        - $ref: '#/components/parameters/ReportOrigin'
        - $ref: '#/components/parameters/ReportVisits'
        - $ref: '#/components/parameters/ReportMode'
        - $ref: '#/components/parameters/ReportHasPhone'
        - $ref: '#/components/parameters/ReportCursor'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/customers/visit-funnel:
    get:
      operationId: getReportCustomersVisitFunnel
      tags:
        - Relatórios · Clientes
      summary: Funil de visitas
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:customers:read e restaurante autorizado.
        Filtros, valores e paginação mantêm o contrato do serviço de relatórios. Não concede permissões novas a
        tokens existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:customers:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportStartDate'
        - $ref: '#/components/parameters/ReportEndDate'
        - $ref: '#/components/parameters/ReportCohortStartDateOptional'
        - $ref: '#/components/parameters/ReportCohortEndDateOptional'
        - $ref: '#/components/parameters/ReportMinStage'
        - $ref: '#/components/parameters/ReportCursor'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/customers/visit-retention/customers:
    get:
      operationId: getReportCustomersVisitRetentionCustomers
      tags:
        - Relatórios · Clientes
      summary: Clientes por etapa de visitas
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:customers:read e restaurante autorizado.
        Filtros, valores e paginação mantêm o contrato do serviço de relatórios. Não concede permissões novas a
        tokens existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:customers:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportCohortStartDate'
        - $ref: '#/components/parameters/ReportCohortEndDate'
        - $ref: '#/components/parameters/ReportStage'
        - $ref: '#/components/parameters/ReportMode'
        - $ref: '#/components/parameters/ReportOrigin'
        - $ref: '#/components/parameters/ReportChannel'
        - $ref: '#/components/parameters/ReportHasPhone'
        - $ref: '#/components/parameters/ReportCursor'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/products/realtime/today:
    get:
      operationId: getReportProductsRealtimeToday
      tags:
        - Relatórios · Produtos
      summary: Vendas de hoje
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:products:read e restaurante autorizado.
        Filtros, valores e paginação mantêm o contrato do serviço de relatórios. Não concede permissões novas a
        tokens existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:products:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/products/realtime/today/orders:
    get:
      operationId: getReportProductsRealtimeTodayOrders
      tags:
        - Relatórios · Produtos
      summary: Pedidos de hoje
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:products:read e restaurante autorizado.
        Filtros, valores e paginação mantêm o contrato do serviço de relatórios. Não concede permissões novas a
        tokens existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:products:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/products/abc:
    get:
      operationId: getReportProductsAbc
      tags:
        - Relatórios · Produtos
      summary: Curva ABC de produtos
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:products:read e restaurante autorizado.
        Filtros, valores e paginação mantêm o contrato do serviço de relatórios. Não concede permissões novas a
        tokens existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:products:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportStartDate'
        - $ref: '#/components/parameters/ReportEndDate'
        - $ref: '#/components/parameters/ReportView'
        - $ref: '#/components/parameters/ReportChannel'
        - $ref: '#/components/parameters/ReportCategoryId'
        - $ref: '#/components/parameters/ReportIncludeToday'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/products/bcg:
    get:
      operationId: getReportProductsBcg
      tags:
        - Relatórios · Produtos
      summary: Matriz BCG de produtos
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:products:read e restaurante autorizado.
        Filtros, valores e paginação mantêm o contrato do serviço de relatórios. Não concede permissões novas a
        tokens existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:products:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportStartDate'
        - $ref: '#/components/parameters/ReportEndDate'
        - $ref: '#/components/parameters/ReportView'
        - $ref: '#/components/parameters/ReportChannel'
        - $ref: '#/components/parameters/ReportCategoryId'
        - $ref: '#/components/parameters/ReportIncludeToday'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/products/insights:
    get:
      operationId: getReportProductsInsights
      tags:
        - Relatórios · Produtos
      summary: Análises de vendas
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:products:read e restaurante autorizado.
        Filtros, valores e paginação mantêm o contrato do serviço de relatórios. Não concede permissões novas a
        tokens existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:products:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportStartDate'
        - $ref: '#/components/parameters/ReportEndDate'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/products/catalog/images:
    get:
      operationId: getReportProductsCatalogImages
      tags:
        - Relatórios · Produtos
      summary: Imagens do catálogo
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:products:read e restaurante autorizado.
        Filtros, valores e paginação mantêm o contrato do serviço de relatórios. Não concede permissões novas a
        tokens existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:products:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/products/daily/categories:
    get:
      operationId: getReportProductsDailyCategories
      tags:
        - Relatórios · Produtos
      summary: Vendas por categoria e dia
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:products:read e restaurante autorizado.
        Filtros, valores e paginação mantêm o contrato do serviço de relatórios. Não concede permissões novas a
        tokens existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:products:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportStartDate'
        - $ref: '#/components/parameters/ReportEndDate'
        - $ref: '#/components/parameters/ReportIncludeToday'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/products/monthly/products:
    get:
      operationId: getReportProductsMonthlyProducts
      tags:
        - Relatórios · Produtos
      summary: Vendas de produtos no mês
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:products:read e restaurante autorizado.
        Filtros, valores e paginação mantêm o contrato do serviço de relatórios. Não concede permissões novas a
        tokens existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:products:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportMonth'
        - $ref: '#/components/parameters/ReportChannel'
        - $ref: '#/components/parameters/ReportCategoryId'
        - $ref: '#/components/parameters/ReportIncludeToday'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/products/monthly/categories:
    get:
      operationId: getReportProductsMonthlyCategories
      tags:
        - Relatórios · Produtos
      summary: Vendas por categoria no mês
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:products:read e restaurante autorizado.
        Filtros, valores e paginação mantêm o contrato do serviço de relatórios. Não concede permissões novas a
        tokens existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:products:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportMonth'
        - $ref: '#/components/parameters/ReportIncludeToday'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/products/monthly/complements:
    get:
      operationId: getReportProductsMonthlyComplements
      tags:
        - Relatórios · Produtos
      summary: Vendas de complementos no mês
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:products:read e restaurante autorizado.
        Filtros, valores e paginação mantêm o contrato do serviço de relatórios. Não concede permissões novas a
        tokens existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:products:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportMonth'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/products/monthly/channels:
    get:
      operationId: getReportProductsMonthlyChannels
      tags:
        - Relatórios · Produtos
      summary: Vendas por canal no mês
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:products:read e restaurante autorizado.
        Filtros, valores e paginação mantêm o contrato do serviço de relatórios. Não concede permissões novas a
        tokens existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:products:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportMonth'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/products/monthly/hierarchy:
    get:
      operationId: getReportProductsMonthlyHierarchy
      tags:
        - Relatórios · Produtos
      summary: Categorias, produtos e complementos do mês
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:products:read e restaurante autorizado.
        Filtros, valores e paginação mantêm o contrato do serviço de relatórios. Não concede permissões novas a
        tokens existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:products:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportMonth'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/products/period/products:
    get:
      operationId: getReportProductsPeriodProducts
      tags:
        - Relatórios · Produtos
      summary: Vendas de produtos no período
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:products:read e restaurante autorizado.
        Filtros, valores e paginação mantêm o contrato do serviço de relatórios. Não concede permissões novas a
        tokens existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:products:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportStartDate'
        - $ref: '#/components/parameters/ReportEndDate'
        - $ref: '#/components/parameters/ReportChannel'
        - $ref: '#/components/parameters/ReportCategoryId'
        - $ref: '#/components/parameters/ReportIncludeToday'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/products/period/categories:
    get:
      operationId: getReportProductsPeriodCategories
      tags:
        - Relatórios · Produtos
      summary: Vendas por categoria no período
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:products:read e restaurante autorizado.
        Filtros, valores e paginação mantêm o contrato do serviço de relatórios. Não concede permissões novas a
        tokens existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:products:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportStartDate'
        - $ref: '#/components/parameters/ReportEndDate'
        - $ref: '#/components/parameters/ReportIncludeToday'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/products/period/complements:
    get:
      operationId: getReportProductsPeriodComplements
      tags:
        - Relatórios · Produtos
      summary: Vendas de complementos no período
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:products:read e restaurante autorizado.
        Filtros, valores e paginação mantêm o contrato do serviço de relatórios. Não concede permissões novas a
        tokens existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:products:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportStartDate'
        - $ref: '#/components/parameters/ReportEndDate'
        - $ref: '#/components/parameters/ReportChannel'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/products/period/order-attach:
    get:
      operationId: getReportProductsPeriodOrderAttach
      tags:
        - Relatórios · Produtos
      summary: Participação de produtos nos pedidos
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:products:read e restaurante autorizado.
        Filtros, valores e paginação mantêm o contrato do serviço de relatórios. Não concede permissões novas a
        tokens existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:products:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportStartDate'
        - $ref: '#/components/parameters/ReportEndDate'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/products/period/complement-attach:
    get:
      operationId: getReportProductsPeriodComplementAttach
      tags:
        - Relatórios · Produtos
      summary: Participação de complementos nas vendas
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:products:read e restaurante autorizado.
        Filtros, valores e paginação mantêm o contrato do serviço de relatórios. Não concede permissões novas a
        tokens existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:products:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportStartDate'
        - $ref: '#/components/parameters/ReportEndDate'
        - $ref: '#/components/parameters/ReportProductId'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/products/period/cancellations:
    get:
      operationId: getReportProductsPeriodCancellations
      tags:
        - Relatórios · Produtos
      summary: Cancelamentos no período
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:products:read e restaurante autorizado.
        Filtros, valores e paginação mantêm o contrato do serviço de relatórios. Não concede permissões novas a
        tokens existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:products:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportStartDate'
        - $ref: '#/components/parameters/ReportEndDate'
        - $ref: '#/components/parameters/ReportGroupBy'
        - $ref: '#/components/parameters/ReportFilterBy'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/products/period/product-sales:
    get:
      operationId: getReportProductsPeriodProductSales
      tags:
        - Relatórios · Produtos
      summary: Detalhamento de vendas de um produto
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:products:read e restaurante autorizado.
        Filtros, valores e paginação mantêm o contrato do serviço de relatórios. Não concede permissões novas a
        tokens existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:products:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportStartDate'
        - $ref: '#/components/parameters/ReportEndDate'
        - $ref: '#/components/parameters/ReportProductId'
        - $ref: '#/components/parameters/ReportCursor'
      responses:
        '200':
          $ref: '#/components/responses/Report200Passthrough'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/kds/overview:
    get:
      operationId: getReportKdsOverview
      tags:
        - Relatórios · KDS
      summary: Visão geral do KDS
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:kds:read e restaurante autorizado. Cache de
        cinco minutos; leituras por réplica quando configurada. Não concede permissões novas a tokens
        existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:kds:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportStartDate'
        - $ref: '#/components/parameters/ReportEndDate'
        - $ref: '#/components/parameters/ReportKdsIds'
        - $ref: '#/components/parameters/ReportChannels'
        - $ref: '#/components/parameters/ReportChannelGroups'
        - $ref: '#/components/parameters/ReportCompare'
      responses:
        '200':
          $ref: '#/components/responses/Report200Kds'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/kds/heatmap:
    get:
      operationId: getReportKdsHeatmap
      tags:
        - Relatórios · KDS
      summary: Mapa de calor do preparo
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:kds:read e restaurante autorizado. Cache de
        cinco minutos; leituras por réplica quando configurada. Não concede permissões novas a tokens
        existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:kds:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportStartDate'
        - $ref: '#/components/parameters/ReportEndDate'
        - $ref: '#/components/parameters/ReportKdsIds'
        - $ref: '#/components/parameters/ReportChannels'
        - $ref: '#/components/parameters/ReportChannelGroups'
      responses:
        '200':
          $ref: '#/components/responses/Report200Kds'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/kds/stations:
    get:
      operationId: getReportKdsStations
      tags:
        - Relatórios · KDS
      summary: Tempo de preparo por estação
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:kds:read e restaurante autorizado. Cache de
        cinco minutos; leituras por réplica quando configurada. Não concede permissões novas a tokens
        existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:kds:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportStartDate'
        - $ref: '#/components/parameters/ReportEndDate'
        - $ref: '#/components/parameters/ReportKdsIds'
        - $ref: '#/components/parameters/ReportChannels'
        - $ref: '#/components/parameters/ReportChannelGroups'
        - $ref: '#/components/parameters/ReportCompare'
      responses:
        '200':
          $ref: '#/components/responses/Report200Kds'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/kds/products:
    get:
      operationId: getReportKdsProducts
      tags:
        - Relatórios · KDS
      summary: Tempo de preparo e cumprimento de metas por produto
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:kds:read e restaurante autorizado. Cache de
        cinco minutos; leituras por réplica quando configurada. Não concede permissões novas a tokens
        existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:kds:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportStartDate'
        - $ref: '#/components/parameters/ReportEndDate'
        - $ref: '#/components/parameters/ReportKdsIds'
        - $ref: '#/components/parameters/ReportChannels'
        - $ref: '#/components/parameters/ReportChannelGroups'
        - $ref: '#/components/parameters/ReportLimit'
        - $ref: '#/components/parameters/ReportCompare'
      responses:
        '200':
          $ref: '#/components/responses/Report200Kds'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/kds/detractors:
    get:
      operationId: getReportKdsDetractors
      tags:
        - Relatórios · KDS
      summary: Itens com preparo mais demorado
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:kds:read e restaurante autorizado. Cache de
        cinco minutos; leituras por réplica quando configurada. Não concede permissões novas a tokens
        existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:kds:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportStartDate'
        - $ref: '#/components/parameters/ReportEndDate'
        - $ref: '#/components/parameters/ReportKdsIds'
        - $ref: '#/components/parameters/ReportChannels'
        - $ref: '#/components/parameters/ReportChannelGroups'
        - $ref: '#/components/parameters/ReportLimit'
        - $ref: '#/components/parameters/ReportMinSample'
        - $ref: '#/components/parameters/ReportCompare'
      responses:
        '200':
          $ref: '#/components/responses/Report200Kds'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/kds/product-channels:
    get:
      operationId: getReportKdsProductChannels
      tags:
        - Relatórios · KDS
      summary: Tempo de um produto por canal
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:kds:read e restaurante autorizado. Cache de
        cinco minutos; leituras por réplica quando configurada. Não concede permissões novas a tokens
        existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:kds:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportStartDate'
        - $ref: '#/components/parameters/ReportEndDate'
        - $ref: '#/components/parameters/ReportKdsIds'
        - $ref: '#/components/parameters/ReportChannels'
        - $ref: '#/components/parameters/ReportChannelGroups'
        - $ref: '#/components/parameters/ReportLimit'
        - $ref: '#/components/parameters/ReportGapPct'
        - $ref: '#/components/parameters/ReportGapMin'
        - $ref: '#/components/parameters/ReportMinOrders'
      responses:
        '200':
          $ref: '#/components/responses/Report200Kds'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/kds/channels:
    get:
      operationId: getReportKdsChannels
      tags:
        - Relatórios · KDS
      summary: Tempo de preparo por canal
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:kds:read e restaurante autorizado. Cache de
        cinco minutos; leituras por réplica quando configurada. Não concede permissões novas a tokens
        existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:kds:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportStartDate'
        - $ref: '#/components/parameters/ReportEndDate'
        - $ref: '#/components/parameters/ReportKdsIds'
        - $ref: '#/components/parameters/ReportChannels'
        - $ref: '#/components/parameters/ReportChannelGroups'
        - $ref: '#/components/parameters/ReportCompare'
      responses:
        '200':
          $ref: '#/components/responses/Report200Kds'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/kds/consistency:
    get:
      operationId: getReportKdsConsistency
      tags:
        - Relatórios · KDS
      summary: Regularidade do tempo de preparo
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:kds:read e restaurante autorizado. Cache de
        cinco minutos; leituras por réplica quando configurada. Não concede permissões novas a tokens
        existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:kds:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportStartDate'
        - $ref: '#/components/parameters/ReportEndDate'
        - $ref: '#/components/parameters/ReportKdsIds'
        - $ref: '#/components/parameters/ReportChannels'
        - $ref: '#/components/parameters/ReportChannelGroups'
      responses:
        '200':
          $ref: '#/components/responses/Report200Kds'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/kds/waiters:
    get:
      operationId: getReportKdsWaiters
      tags:
        - Relatórios · KDS
      summary: Tempo de preparo por garçom
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:kds:read e restaurante autorizado. Cache de
        cinco minutos; leituras por réplica quando configurada. Não concede permissões novas a tokens
        existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:kds:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportStartDate'
        - $ref: '#/components/parameters/ReportEndDate'
        - $ref: '#/components/parameters/ReportKdsIds'
        - $ref: '#/components/parameters/ReportChannels'
        - $ref: '#/components/parameters/ReportChannelGroups'
      responses:
        '200':
          $ref: '#/components/responses/Report200Kds'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/reports/kds/slowest:
    get:
      operationId: getReportKdsSlowest
      tags:
        - Relatórios · KDS
      summary: Pedidos com preparo mais demorado
      description: >-
        Consulta de leitura equivalente à manager-api. Exige reports:kds:read e restaurante autorizado. Cache de
        cinco minutos; leituras por réplica quando configurada. Não concede permissões novas a tokens
        existentes.
      security:
        - reportsIntegration: []
      x-required-scopes:
        - reports:kds:read
      parameters:
        - $ref: '#/components/parameters/ReportRestaurantId'
        - $ref: '#/components/parameters/ReportStartDate'
        - $ref: '#/components/parameters/ReportEndDate'
        - $ref: '#/components/parameters/ReportKdsIds'
        - $ref: '#/components/parameters/ReportChannels'
        - $ref: '#/components/parameters/ReportChannelGroups'
        - $ref: '#/components/parameters/ReportLimit'
      responses:
        '200':
          $ref: '#/components/responses/Report200Kds'
        '400':
          $ref: '#/components/responses/Report400'
        '401':
          $ref: '#/components/responses/Report401'
        '403':
          $ref: '#/components/responses/Report403'
        '404':
          $ref: '#/components/responses/Report404'
        '502':
          $ref: '#/components/responses/Report502'
        '503':
          $ref: '#/components/responses/Report503'
  /v1/store/reviews:
    get:
      tags: [Takeat Store]
      operationId: listConnectedStoreReviewsV1
      summary: Consultar avaliações do app conectado
      description: |
        O client_id do token e sua instalação identificam o app; não aceita ID
        de outro aplicativo. Exige OAuth PKCE de restaurante com instalação
        ativa, não expirada e app visível. Exige store:reviews:read.
        Sem restaurant_id, lista todas as avaliações do app. Com o filtro,
        lista e resumo incluem somente uma loja autorizada na conexão e nos
        vínculos atuais da rede. Retorna 10 avaliações por página, da mais
        recente para a mais antiga. IDs de contas e e-mails não são publicados.
        Avaliações excluídas logicamente não aparecem em data, ownReview,
        totais ou médias.
      x-required-scope: store:reviews:read
      security:
        - storeOAuth: []
      parameters:
        - $ref: '#/components/parameters/StoreReviewRestaurantId'
        - name: page
          in: query
          schema: { type: integer, minimum: 1, maximum: 1000, default: 1 }
      responses:
        '200':
          description: Avaliações do app, filtradas por restaurante quando solicitado.
          headers:
            Cache-Control:
              schema: { type: string, const: no-store }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ConnectedStoreReviewsPage' }
        '400':
          description: Query inválida ou parâmetro desconhecido.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
        '401':
          description: Access token ausente, inválido ou expirado.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
        '403':
          description: Conexão inválida, revogada ou expirada; loja não autorizada; perfil ou credencial incompatível.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
    post:
      tags: [Takeat Store]
      operationId: saveConnectedStoreReviewV1
      summary: Criar ou atualizar avaliação do app conectado
      description: |
        O token identifica o app e as lojas autorizadas. Cria ou atualiza uma
        única avaliação por aplicativo e restaurante, retornando 200 nos dois
        casos. Se ela foi excluída logicamente, restaura o mesmo registro com
        a nova nota e comentário. Sem restaurant_id, infere a loja se o token autoriza somente uma;
        com várias lojas, o seletor é obrigatório. A nota e o comentário devem
        ser escolhidos pelo usuário antes do envio. O autor é o usuário do
        consentimento ou o dono registrado da rede, com acesso ativo verificado.
        Conexões sem esse usuário precisam passar novamente pelo consentimento.
        App e instalação são verificados e bloqueados na transação de gravação.
        Exige store:reviews:write e não aceita IDs de autor ou app no corpo.
      x-required-scope: store:reviews:write
      security:
        - storeOAuth: []
      parameters:
        - $ref: '#/components/parameters/StoreReviewRestaurantId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [rating, comment]
              properties:
                rating: { type: integer, minimum: 1, maximum: 5 }
                comment:
                  type: string
                  minLength: 3
                  maxLength: 1500
                  description: Texto simples; espaços nas extremidades são removidos antes de validar.
            example: { rating: 5, comment: Ajudou a organizar o dia a dia do restaurante. }
      responses:
        '200':
          description: Avaliação criada ou atualizada.
          headers:
            Cache-Control:
              schema: { type: string, const: no-store }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/StoreAppReview' }
        '400':
          description: Corpo inválido, query inválida ou seletor obrigatório ausente.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
        '401':
          description: Access token ausente, inválido ou expirado.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
        '403':
          description: Conexão ou responsável sem acesso ativo; restaurante não autorizado.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
  /v1/store/reviews/{reviewId}:
    delete:
      tags: [Takeat Store]
      operationId: deleteConnectedStoreReviewV1
      summary: Excluir avaliação do próprio restaurante
      description: |
        Exige uma conexão OAuth de restaurante ativa. O client_id do token
        identifica o app e o restaurante selecionado deve ser autorizado na
        conexão e nos vínculos atuais da rede. Só exclui uma avaliação de
        autoria desse restaurante nesse aplicativo; o usuário individual que
        escreveu a avaliação não precisa ser o mesmo responsável atual.
        Registra deleted_at e updated_at, preservando a linha e seu conteúdo.
        A avaliação deixa de aparecer nas consultas, totais, médias e ownReview
        da API e da Store. Um novo POST restaura o mesmo registro.
        Avaliações inexistentes, já excluídas ou de outro app/restaurante
        retornam o mesmo 404. Exige store:reviews:write.
      x-required-scope: store:reviews:write
      security:
        - storeOAuth: []
      parameters:
        - name: reviewId
          in: path
          required: true
          description: ID da avaliação retornado na consulta ou no envio.
          schema: { type: string, format: uuid }
        - $ref: '#/components/parameters/StoreReviewRestaurantId'
      responses:
        '204':
          description: Avaliação excluída logicamente; sem corpo de resposta.
        '400':
          description: ID ou query inválidos; restaurante obrigatório em conexão com várias lojas.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
        '401':
          description: Access token ausente, inválido ou expirado.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
        '403':
          description: Conexão inativa, perfil incompatível ou restaurante não autorizado.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
        '404':
          description: Avaliação inexistente, já excluída ou pertencente a outro app/restaurante.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
  /v1/restaurants/features:
    get:
      tags: [Restaurante]
      operationId: getRestaurantFeaturesV1
      summary: Consultar status e funcionalidades do restaurante
      description: >-
        Exige OAuth restaurants:read ou sessão do próprio restaurante.
        Lê o primário sem cache. is_active é a ativação da conta, não abertura da loja.
        features contém 26 capacidades exportáveis agrupadas por produto;
        available_features fica vazio para contas inativas. Não verifica provedores,
        expiração de testes ou permissões individuais, nem concede acesso a outras rotas.
        A seleção é limitada à autorização atual; não modifica configurações.
      x-required-scope: restaurants:read
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
      responses:
        '200':
          description: Status da conta e catálogo completo de funcionalidades.
          headers:
            Cache-Control:
              schema: { type: string, const: no-store }
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestaurantFeaturesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Restaurante inexistente ou excluído (restaurant_not_found).
          content:
            application/json:
              schema:
                type: object
                required: [statusCode, message, key]
                properties:
                  statusCode: { type: integer, const: 404 }
                  message: { type: string }
                  key: { type: string, const: restaurant_not_found }


  /v1/ratings:
    get:
      tags: [Avaliações]
      operationId: getRatingsV1
      summary: Listar avaliações do restaurante
      description: >-
        OAuth exige ratings:read; aceita sessão autenticada do próprio restaurante.
        Retorna todas as origens por padrão, inclusive Clube. O filtro channel é literal e opcional;
        use channel=clube nesta mesma rota para avaliações atuais do Clube integradas ao Takeat.
        O histórico antigo do banco próprio do api-clube não é incluído.
        Datas YYYY-MM-DD obrigatórias, inclusivas em UTC, máximo de 92 dias.
        Ordenação por created_at e id decrescentes. Resumo sobre todo o período e filtros,
        independente da página. Pode conter nome e telefone do cliente, quando disponíveis.
        Preserve os filtros ao aplicar pagination.next. A leitura pode refletir atraso da réplica.
      x-required-scope: ratings:read
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
        - $ref: '#/components/parameters/RatingsStartDate'
        - $ref: '#/components/parameters/RatingsEndDate'
        - $ref: '#/components/parameters/RatingsPage'
        - $ref: '#/components/parameters/RatingsPerPage'
        - name: channel
          in: query
          description: Origem literal armazenada, como takeat ou clube. Omitir inclui todas as origens.
          schema: { type: string, minLength: 1, maxLength: 255 }
      responses:
        '200':
          description: Página de avaliações e resumo de todas as correspondências.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RatingsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /v1/restaurants:
    get:
      tags: [Autenticação]
      operationId: listAuthorizedRestaurants
      summary: Listar lojas acessíveis pela credencial
      description: >-
        Aceita somente access token de integração. Retorna IDs e nomes públicos da
        concessão atual, intersectada com os vínculos ativos de multilojas. Não aceita
        chave bruta ou sessão humana. Não exige novo escopo. Concessões universais
        devem escolher um tenant e não podem enumerar todas as lojas.
      responses:
        '200':
          description: Lojas autorizadas atualmente
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: false
                  required: [id, fantasy_name]
                  properties:
                    id: { description: "ID da loja (string numérica); use como restaurant_id nas demais rotas.", type: string, example: '81' }
                    fantasy_name: { description: "Nome fantasia da loja.", type: string, example: Centro }
        '401': { description: Credencial inválida ou não aceita }
        '403': { description: A concessão não pode listar lojas }
  /v1/inventory/inputs/bulk:
    put:
      tags:
        - Estoque
      summary: Editar insumos em lote
      operationId: updateManagedInputsBulk
      description: >-
        OAuth exige inputs:write; aceita também sessão de restaurante. Edição parcial. Unidade muda
        somente sem saldo nem vínculos. Cadastros mestres e multiloja são protegidos. Custos alteram
        valorização, sem mudar quantidades. Aceita um objeto ou array de 1 a 100 alterações, cada uma
        com id. Retorna um array na ordem enviada. IDs duplicados são rejeitados. Qualquer falha
        desfaz todo o lote. Fichas aceitam até 2000 ingredientes somados; cada proprietário preserva
        sua verificação expected_updated_at.
      security:
        - bearerAuth: []
      x-required-scope: inputs:write
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
      responses:
        '200':
          description: Operação concluída.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ManagedInventoryStock'
        '400':
          description: Payload inválido, duplicidade ou ciclo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Credencial inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ou restaurante não permitido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Cadastro ausente, cancelado ou de outro restaurante.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Conflito de atualização, cadastro gerenciado ou unidade em uso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/InventoryInputBatchEdit'
                - type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    $ref: '#/components/schemas/InventoryInputBatchEdit'
  /v1/inventory/intermediaries/bulk:
    put:
      tags:
        - Estoque
      summary: Editar intermediários em lote
      operationId: updateManagedIntermediariesBulk
      description: >-
        OAuth exige intermediaries:write; aceita também sessão de restaurante. Edição parcial. Unidade
        muda somente sem saldo nem vínculos. Cadastros mestres e multiloja são protegidos. Custos
        alteram valorização, sem mudar quantidades. Aceita um objeto ou array de 1 a 100 alterações,
        cada uma com id. Retorna um array na ordem enviada. IDs duplicados são rejeitados. Qualquer
        falha desfaz todo o lote. Fichas aceitam até 2000 ingredientes somados; cada proprietário
        preserva sua verificação expected_updated_at.
      security:
        - bearerAuth: []
      x-required-scope: intermediaries:write
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
      responses:
        '200':
          description: Operação concluída.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ManagedInventoryStock'
        '400':
          description: Payload inválido, duplicidade ou ciclo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Credencial inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ou restaurante não permitido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Cadastro ausente, cancelado ou de outro restaurante.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Conflito de atualização, cadastro gerenciado ou unidade em uso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/InventoryIntermediaryBatchEdit'
                - type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    $ref: '#/components/schemas/InventoryIntermediaryBatchEdit'
  /v1/inventory/intermediaries/technical-sheets/bulk:
    put:
      tags:
        - Estoque
      summary: Substituir fichas de intermediários em lote
      operationId: replaceIntermediaryTechnicalSheetsBulk
      description: >-
        OAuth exige intermediaries:write; aceita também sessão de restaurante. Substitui toda a
        composição atomicamente. Arrays vazios removem ingredientes editáveis. Preserva insumo mestre,
        saldos e preços de venda; recalcula custos dependentes. Não executa produção nem conversão de
        unidade. Recipe omitido limpa o preparo. Aceita um objeto ou array de 1 a 100 alterações, cada
        uma com id. Retorna um array na ordem enviada. IDs duplicados são rejeitados. Qualquer falha
        desfaz todo o lote. Fichas aceitam até 2000 ingredientes somados; cada proprietário preserva
        sua verificação expected_updated_at.
      security:
        - bearerAuth: []
      x-required-scope: intermediaries:write
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
      responses:
        '200':
          description: Operação concluída.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InventoryTechnicalSheet'
        '400':
          description: Payload inválido, duplicidade ou ciclo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Credencial inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ou restaurante não permitido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Cadastro ausente, cancelado ou de outro restaurante.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Conflito de atualização, cadastro gerenciado ou unidade em uso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/InventoryIntermediarySheetBatchEdit'
                - type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    $ref: '#/components/schemas/InventoryIntermediarySheetBatchEdit'
  /v1/products/technical-sheets/bulk:
    put:
      tags:
        - Estoque
      summary: Substituir fichas de produtos em lote
      operationId: replaceProductTechnicalSheetsBulk
      description: >-
        OAuth exige products:write; aceita também sessão de restaurante. Substitui toda a composição
        atomicamente. Arrays vazios removem ingredientes editáveis. Preserva saldos e preços de venda
        e apresenta o custo da ficha atualizado. Produtos preservam o insumo mestre. Não aceita yield
        nem recipe; não executa produção ou movimentação quantitativa. Aceita um objeto ou array de 1
        a 100 alterações, cada uma com id. Retorna um array na ordem enviada. IDs duplicados são
        rejeitados. Qualquer falha desfaz todo o lote. Fichas aceitam até 2000 ingredientes somados;
        cada proprietário preserva sua verificação expected_updated_at.
      security:
        - bearerAuth: []
      x-required-scope: products:write
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
      responses:
        '200':
          description: Operação concluída.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InventoryTechnicalSheet'
        '400':
          description: Payload inválido, duplicidade ou ciclo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Credencial inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ou restaurante não permitido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Cadastro ausente, cancelado ou de outro restaurante.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Conflito de atualização, cadastro gerenciado ou unidade em uso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/InventoryTechnicalSheetBatchEdit'
                - type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    $ref: '#/components/schemas/InventoryTechnicalSheetBatchEdit'
  /v1/complements/technical-sheets/bulk:
    put:
      tags:
        - Estoque
      summary: Substituir fichas de complementos em lote
      operationId: replaceComplementTechnicalSheetsBulk
      description: >-
        OAuth exige complements:write; aceita também sessão de restaurante. Substitui toda a
        composição atomicamente. Arrays vazios removem ingredientes editáveis. Preserva saldos e
        preços de venda e apresenta o custo da ficha atualizado. Produtos preservam o insumo mestre.
        Não aceita yield nem recipe; não executa produção ou movimentação quantitativa. Aceita um
        objeto ou array de 1 a 100 alterações, cada uma com id. Retorna um array na ordem enviada. IDs
        duplicados são rejeitados. Qualquer falha desfaz todo o lote. Fichas aceitam até 2000
        ingredientes somados; cada proprietário preserva sua verificação expected_updated_at.
      security:
        - bearerAuth: []
      x-required-scope: complements:write
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
      responses:
        '200':
          description: Operação concluída.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InventoryTechnicalSheet'
        '400':
          description: Payload inválido, duplicidade ou ciclo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Credencial inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ou restaurante não permitido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Cadastro ausente, cancelado ou de outro restaurante.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Conflito de atualização, cadastro gerenciado ou unidade em uso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/InventoryTechnicalSheetBatchEdit'
                - type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    $ref: '#/components/schemas/InventoryTechnicalSheetBatchEdit'
  /v1/inventory/inputs:
    get:
      tags:
        - Estoque
      summary: Listar cadastro de insumos
      operationId: listManagedInputs
      description: >-
        OAuth exige inputs:read; aceita também sessão de restaurante. Inclui IDs, saldos e
        indicadores de gestão.
      security:
        - bearerAuth: []
      x-required-scope: inputs:read
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
          description: >-
            Página fixa de 100, ordenada por nome e ID. Offset inválido/negativo segue o fallback
            legado para zero.
      responses:
        '200':
          description: Operação concluída.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedInventoryPage'
        '400':
          description: Payload inválido, duplicidade ou ciclo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Credencial inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ou restaurante não permitido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Cadastro ausente, cancelado ou de outro restaurante.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Conflito de atualização, cadastro gerenciado ou unidade em uso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
    post:
      tags:
        - Estoque
      summary: Criar cadastro de insumos
      operationId: createManagedInput
      description: >-
        OAuth exige inputs:write; aceita também sessão de restaurante. Cria com saldo zero; não produz
        nem consome ingredientes. Aceita um objeto ou um array de 1 a 100 cadastros. Objeto retorna
        objeto; array retorna array na ordem enviada. O lote inteiro é atômico. Lotes de intermediários
        aceitam até 2000 ingredientes somados.
      security:
        - bearerAuth: []
      x-required-scope: inputs:write
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
      responses:
        '201':
          description: Operação concluída.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ManagedInventoryStock'
                  - type: array
                    items:
                      $ref: '#/components/schemas/ManagedInventoryStock'
        '400':
          description: Payload inválido, duplicidade ou ciclo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Credencial inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ou restaurante não permitido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Cadastro ausente, cancelado ou de outro restaurante.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Conflito de atualização, cadastro gerenciado ou unidade em uso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/InventoryInputCreate'
                - type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    $ref: '#/components/schemas/InventoryInputCreate'
  /v2/inventory/inputs:
    get:
      tags:
        - Estoque
      summary: Listar cadastro de insumos (V2 paginada)
      operationId: listManagedInputsPaginatedV2
      description: >-
        OAuth exige inputs:read; aceita também sessão de restaurante. Inclui IDs, saldos e indicadores de
        gestão.

        Retorna data e pagination; siga pagination.next mantendo os filtros. A V1 permanece disponível com seu
        contrato anterior.
      security:
        - bearerAuth: []
      x-required-scope: inputs:read
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
          description: >-
            Página fixa de 100, ordenada por nome e ID. Offset inválido/negativo segue o fallback legado para
            zero.
      responses:
        '200':
          description: Operação concluída.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedInventoryPageV2'
        '400':
          description: Payload inválido, duplicidade ou ciclo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Credencial inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ou restaurante não permitido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Cadastro ausente, cancelado ou de outro restaurante.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Conflito de atualização, cadastro gerenciado ou unidade em uso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'

  /v1/inventory/inputs/{id}:
    get:
      tags:
        - Estoque
      summary: Consultar cadastro de insumos
      operationId: getManagedInput
      description: OAuth exige inputs:read; aceita também sessão de restaurante. Leitura no primário.
      security:
        - bearerAuth: []
      x-required-scope: inputs:read
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
        - name: id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
      responses:
        '200':
          description: Operação concluída.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedInventoryStock'
        '400':
          description: Payload inválido, duplicidade ou ciclo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Credencial inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ou restaurante não permitido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Cadastro ausente, cancelado ou de outro restaurante.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Conflito de atualização, cadastro gerenciado ou unidade em uso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
    put:
      tags:
        - Estoque
      summary: Editar cadastro de insumos
      operationId: updateManagedInput
      description: >-
        OAuth exige inputs:write; aceita também sessão de restaurante. Edição parcial. Unidade muda
        somente sem saldo nem vínculos. Cadastros mestres e multiloja são protegidos. Custos alteram
        valorização, sem mudar quantidades.
      security:
        - bearerAuth: []
      x-required-scope: inputs:write
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
        - name: id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
      responses:
        '200':
          description: Operação concluída.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedInventoryStock'
        '400':
          description: Payload inválido, duplicidade ou ciclo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Credencial inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ou restaurante não permitido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Cadastro ausente, cancelado ou de outro restaurante.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Conflito de atualização, cadastro gerenciado ou unidade em uso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventoryInputUpdate'
  /v1/inventory/inputs/cost-centers/bulk:
    put:
      tags:
        - Estoque
      summary: Trocar centro de custo de insumos em lote
      operationId: setInputCostCentersBulk
      description: |
        Troca somente o centro de custo de 1 a 100 insumos distintos, aplicados inteiros
        ou nada. Aceita insumos master e replicados pela multilojas; o cadastro da rede
        retorna 409. Exige `inputs:write`.
      security:
        - bearerAuth: []
      x-required-scope: inputs:write
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InputCostCenterBatch'
      responses:
        '200':
          description: Insumos na ordem enviada.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required: [items]
                properties:
                  items:
                    description: "Insumos atualizados, na ordem enviada, com o cadastro completo após a troca do centro de custo."
                    type: array
                    items:
                      $ref: '#/components/schemas/ManagedInventoryStock'
        '400':
          description: Corpo inválido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Credencial inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ou loja não permitidos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Insumo ou centro de custo inexistente na loja (`inventory_cost_center_not_found`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Cadastro da rede (`inventory_managed_record`) ou edição concorrente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/inventory/inputs/{id}/cost-center:
    put:
      tags:
        - Estoque
      summary: Trocar centro de custo de um insumo
      operationId: setInputCostCenter
      description: |
        Troca somente o centro de custo; `null` remove. Aceita insumos master e
        replicados pela multilojas (`is_multistore_child`); o cadastro da rede
        (`is_multistore`) retorna 409. Exige `inputs:write`.
      security:
        - bearerAuth: []
      x-required-scope: inputs:write
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
        - name: id
          in: path
          required: true
          schema: { type: integer, minimum: 1, maximum: 2147483647 }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InputCostCenter'
      responses:
        '200':
          description: Insumo atualizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedInventoryStock'
        '400':
          description: Corpo inválido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Credencial inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ou loja não permitidos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Insumo ou centro de custo inexistente na loja.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Cadastro da rede ou edição concorrente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/inventory/intermediaries:
    get:
      tags:
        - Estoque
      summary: Listar cadastro de intermediários
      operationId: listManagedIntermediaries
      description: >-
        OAuth exige intermediaries:read; aceita também sessão de restaurante. Inclui IDs, saldos e
        indicadores de gestão.
      security:
        - bearerAuth: []
      x-required-scope: intermediaries:read
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
          description: >-
            Página fixa de 100, ordenada por nome e ID. Offset inválido/negativo segue o fallback
            legado para zero.
      responses:
        '200':
          description: Operação concluída.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedInventoryPage'
        '400':
          description: Payload inválido, duplicidade ou ciclo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Credencial inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ou restaurante não permitido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Cadastro ausente, cancelado ou de outro restaurante.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Conflito de atualização, cadastro gerenciado ou unidade em uso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
    post:
      tags:
        - Estoque
      summary: Criar cadastro de intermediários
      operationId: createManagedIntermediary
      description: >-
        OAuth exige intermediaries:write; aceita também sessão de restaurante. Cria com saldo zero; não
        produz nem consome ingredientes. Aceita um objeto ou um array de 1 a 100 cadastros. Objeto
        retorna objeto; array retorna array na ordem enviada. O lote inteiro é atômico. Lotes de
        intermediários aceitam até 2000 ingredientes somados.
      security:
        - bearerAuth: []
      x-required-scope: intermediaries:write
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
      responses:
        '201':
          description: Operação concluída.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ManagedInventoryStock'
                  - type: array
                    items:
                      $ref: '#/components/schemas/ManagedInventoryStock'
        '400':
          description: Payload inválido, duplicidade ou ciclo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Credencial inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ou restaurante não permitido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Cadastro ausente, cancelado ou de outro restaurante.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Conflito de atualização, cadastro gerenciado ou unidade em uso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/InventoryIntermediaryCreate'
                - type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    $ref: '#/components/schemas/InventoryIntermediaryCreate'
  /v2/inventory/intermediaries:
    get:
      tags:
        - Estoque
      summary: Listar cadastro de intermediários (V2 paginada)
      operationId: listManagedIntermediariesPaginatedV2
      description: >-
        OAuth exige intermediaries:read; aceita também sessão de restaurante. Inclui IDs, saldos e indicadores
        de gestão.

        Retorna data e pagination; siga pagination.next mantendo os filtros. A V1 permanece disponível com seu
        contrato anterior.
      security:
        - bearerAuth: []
      x-required-scope: intermediaries:read
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
          description: >-
            Página fixa de 100, ordenada por nome e ID. Offset inválido/negativo segue o fallback legado para
            zero.
      responses:
        '200':
          description: Operação concluída.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedInventoryPageV2'
        '400':
          description: Payload inválido, duplicidade ou ciclo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Credencial inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ou restaurante não permitido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Cadastro ausente, cancelado ou de outro restaurante.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Conflito de atualização, cadastro gerenciado ou unidade em uso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'

  /v1/inventory/intermediaries/{id}:
    get:
      tags:
        - Estoque
      summary: Consultar cadastro de intermediários
      operationId: getManagedIntermediary
      description: OAuth exige intermediaries:read; aceita também sessão de restaurante. Leitura no primário.
      security:
        - bearerAuth: []
      x-required-scope: intermediaries:read
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
        - name: id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
      responses:
        '200':
          description: Operação concluída.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedInventoryStock'
        '400':
          description: Payload inválido, duplicidade ou ciclo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Credencial inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ou restaurante não permitido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Cadastro ausente, cancelado ou de outro restaurante.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Conflito de atualização, cadastro gerenciado ou unidade em uso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
    put:
      tags:
        - Estoque
      summary: Editar cadastro de intermediários
      operationId: updateManagedIntermediary
      description: >-
        OAuth exige intermediaries:write; aceita também sessão de restaurante. Edição parcial.
        Unidade muda somente sem saldo nem vínculos. Cadastros mestres e multiloja são protegidos.
        Custos alteram valorização, sem mudar quantidades.
      security:
        - bearerAuth: []
      x-required-scope: intermediaries:write
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
        - name: id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
      responses:
        '200':
          description: Operação concluída.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedInventoryStock'
        '400':
          description: Payload inválido, duplicidade ou ciclo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Credencial inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ou restaurante não permitido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Cadastro ausente, cancelado ou de outro restaurante.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Conflito de atualização, cadastro gerenciado ou unidade em uso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventoryIntermediaryUpdate'
  /v1/inventory/intermediaries/{id}/technical-sheet:
    get:
      tags:
        - Estoque
      summary: Consultar ficha de intermediários
      operationId: getIntermediaryTechnicalSheet
      description: >-
        OAuth exige intermediaries:read; aceita também sessão de restaurante. Quantidades por lote
        para intermediários e por unidade vendida para produtos/complementos. Insumo mestre é
        separado.
      security:
        - bearerAuth: []
      x-required-scope: intermediaries:read
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
        - name: id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
      responses:
        '200':
          description: Operação concluída.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryTechnicalSheet'
        '400':
          description: Payload inválido, duplicidade ou ciclo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Credencial inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ou restaurante não permitido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Cadastro ausente, cancelado ou de outro restaurante.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Conflito de atualização, cadastro gerenciado ou unidade em uso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
    put:
      tags:
        - Estoque
      summary: Substituir ficha de intermediários
      operationId: replaceIntermediaryTechnicalSheet
      description: >-
        OAuth exige intermediaries:write; aceita também sessão de restaurante. Substitui toda a
        composição atomicamente. Arrays vazios removem ingredientes editáveis. Preserva insumo
        mestre, saldos e preços de venda; recalcula custos dependentes. Não executa produção nem
        conversão de unidade. Recipe omitido limpa o preparo.
      security:
        - bearerAuth: []
      x-required-scope: intermediaries:write
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
        - name: id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
      responses:
        '200':
          description: Operação concluída.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryTechnicalSheet'
        '400':
          description: Payload inválido, duplicidade ou ciclo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Credencial inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ou restaurante não permitido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Cadastro ausente, cancelado ou de outro restaurante.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Conflito de atualização, cadastro gerenciado ou unidade em uso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventoryIntermediarySheetUpdate'
  /v1/products/{id}/technical-sheet:
    get:
      tags:
        - Estoque
      summary: Consultar ficha de produtos
      operationId: getProductTechnicalSheet
      description: >-
        OAuth exige products:read; aceita também sessão de restaurante. Quantidades por lote para
        intermediários e por unidade vendida para produtos/complementos. Insumo mestre é separado.
      security:
        - bearerAuth: []
      x-required-scope: products:read
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
        - name: id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
      responses:
        '200':
          description: Operação concluída.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryTechnicalSheet'
        '400':
          description: Payload inválido, duplicidade ou ciclo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Credencial inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ou restaurante não permitido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Cadastro ausente, cancelado ou de outro restaurante.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Conflito de atualização, cadastro gerenciado ou unidade em uso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
    put:
      tags:
        - Estoque
      summary: Substituir ficha de produtos
      operationId: replaceProductTechnicalSheet
      description: >-
        OAuth exige products:write; aceita também sessão de restaurante. Substitui toda a composição
        atomicamente. Arrays vazios removem ingredientes editáveis. Preserva saldos e preços de
        venda e apresenta o custo da ficha atualizado. Produtos preservam o insumo mestre.
        Não aceita yield nem recipe; não executa produção ou movimentação quantitativa.
      security:
        - bearerAuth: []
      x-required-scope: products:write
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
        - name: id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
      responses:
        '200':
          description: Operação concluída.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryTechnicalSheet'
        '400':
          description: Payload inválido, duplicidade ou ciclo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Credencial inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ou restaurante não permitido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Cadastro ausente, cancelado ou de outro restaurante.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Conflito de atualização, cadastro gerenciado ou unidade em uso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventoryTechnicalSheetUpdate'
  /v1/complements/{id}/technical-sheet:
    get:
      tags:
        - Estoque
      summary: Consultar ficha de complementos
      operationId: getComplementTechnicalSheet
      description: >-
        OAuth exige complements:read; aceita também sessão de restaurante. Quantidades por lote para
        intermediários e por unidade vendida para produtos/complementos. Insumo mestre é separado.
      security:
        - bearerAuth: []
      x-required-scope: complements:read
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
        - name: id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
      responses:
        '200':
          description: Operação concluída.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryTechnicalSheet'
        '400':
          description: Payload inválido, duplicidade ou ciclo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Credencial inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ou restaurante não permitido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Cadastro ausente, cancelado ou de outro restaurante.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Conflito de atualização, cadastro gerenciado ou unidade em uso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
    put:
      tags:
        - Estoque
      summary: Substituir ficha de complementos
      operationId: replaceComplementTechnicalSheet
      description: >-
        OAuth exige complements:write; aceita também sessão de restaurante. Substitui toda a composição
        atomicamente. Arrays vazios removem ingredientes editáveis. Preserva saldos e preços de
        venda e apresenta o custo da ficha atualizado. Produtos preservam o insumo mestre.
        Não aceita yield nem recipe; não executa produção ou movimentação quantitativa.
      security:
        - bearerAuth: []
      x-required-scope: complements:write
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
        - name: id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
      responses:
        '200':
          description: Operação concluída.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryTechnicalSheet'
        '400':
          description: Payload inválido, duplicidade ou ciclo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Credencial inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ou restaurante não permitido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Cadastro ausente, cancelado ou de outro restaurante.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Conflito de atualização, cadastro gerenciado ou unidade em uso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventoryTechnicalSheetUpdate'

  /oauth/resume:
    post:
      tags: [Autenticação]
      summary: Retomar uma instalação elegível
      description: |
        Sessão humana de restaurante. Emite um novo código PKCE para instalação
        válida com permissões inalteradas, mesmo quando famílias anteriores foram
        revogadas. Não reativa instalação revogada/expirada nem estende sua validade.
        MCP, multilojas e menus centrais exigem consentimento específico.
        Após resposta ambígua, não repetir automaticamente a emissão.
      operationId: resumeOAuthAuthorization
      security:
        - RestaurantOwnerSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [client_id, redirect_uri, code_challenge, code_challenge_method]
              properties:
                client_id:
                  type: string
                redirect_uri:
                  type: string
                  format: uri
                code_challenge:
                  type: string
                code_challenge_method:
                  type: string
                  enum: [S256]
                state:
                  type: string
      responses:
        "201":
          description: Código novo de uso único; trocar com o verifier original do app.
          headers:
            Cache-Control:
              schema:
                type: string
              example: no-store
          content:
            application/json:
              schema:
                type: object
                required: [code, redirect_uri, expires_in]
                properties:
                  code:
                    description: "Código de autorização de uso único; troque em POST /oauth/token com o code_verifier original."
                    type: string
                  redirect_uri:
                    description: "Callback registrado do app, igual ao enviado na requisição, para onde redirecionar com code e state."
                    type: string
                    format: uri
                  expires_in:
                    description: "Validade do código em segundos (padrão 300)."
                    type: integer
                  state:
                    description: "Valor state enviado pelo app, devolvido sem alteração; ausente se não foi enviado."
                    type: string
        "400":
          description: App ou callback inválido.
        "401":
          description: Sessão humana inválida; autenticar novamente preservando a tentativa.
        "403":
          description: Retomada não permitida; atualizar estado e apresentar consentimento quando elegível.
        "409":
          description: Permissões alteradas; recarregar e exigir aprovação explícita.

  /oauth/cancel:
    post:
      tags: [Autenticação]
      summary: Cancelar uma tentativa de autorização
      description: |
        Exclusivo do fluxo interativo com sessão humana de restaurante. Valida app,
        parceiro, perfil, acesso à conta e callback registrado. Não cria, consome ou
        revoga códigos, instalações ou tokens. Não recebe refresh token do app.
        O contrato legado POST /oauth/consent com decision=deny continua revogando
        autorização existente e não deve ser usado para simples cancelamento.
      operationId: cancelOAuthAttempt
      security:
        - RestaurantOwnerSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [client_id, redirect_uri]
              properties:
                client_id:
                  type: string
                redirect_uri:
                  type: string
                  format: uri
                state:
                  type: string
      responses:
        "200":
          description: Tentativa cancelada; autorização existente preservada.
          headers:
            Cache-Control:
              schema:
                type: string
              example: no-store
          content:
            application/json:
              schema:
                type: object
                required: [redirect_uri, error]
                properties:
                  redirect_uri:
                    description: "Callback registrado do app, para onde redirecionar o usuário com error e state."
                    type: string
                    format: uri
                  error:
                    description: "Código OAuth do cancelamento; sempre access_denied."
                    type: string
                    enum: [access_denied]
                  state:
                    description: "Valor state enviado pelo app, devolvido sem alteração; ausente se não foi enviado."
                    type: string
        "400":
          description: App indisponível ou callback não cadastrado.
        "401":
          description: Sessão humana ausente, inválida ou expirada.
        "403":
          description: Conta sem acesso ou perfil incompatível.
        "503":
          description: Autenticação temporariamente indisponível; preserve a sessão do app.

  /oauth/token:
    post:
      tags: [Autenticação]
      summary: Emitir ou renovar tokens
      description: |
        Suporta duas formas de iniciar uma sessão:

        - API key: envie a chave completa `tk_live_...` ou `tk_test_...` como
          `api_key` com `grant_type=api_key`. Não informe `client_id` ou
          `client_secret`.
        - App instalável: envie o código recebido no callback, o client ID
          público, a redirect URI exata e o `code_verifier` com
          `grant_type=authorization_code`. O app não possui client secret.

        O parâmetro `scope` restringe o token a um subconjunto dos escopos da
        chave no grant `api_key`. A resposta contém um access token curto e um
        refresh token rotativo. Para renovar uma sessão de API key, envie
        somente o refresh token atual. Para um app instalável, envie o refresh
        token atual e seu `client_id`. Sempre substitua o refresh token pelo
        novo valor da resposta.

        Alterar as permissões de um app instalável (adição ou remoção de escopos)
        revoga todas as autorizações e tokens existentes, mantendo o client ID.
        Códigos e refresh tokens anteriores retornam `invalid_grant`; os access
        tokens anteriores deixam de acessar os recursos. Cada restaurante deve
        repetir o consentimento com PKCE para obter tokens com as permissões atuais.
      operationId: exchangeApiKey
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              oneOf:
                - $ref: "#/components/schemas/ApiKeyGrantRequest"
                - $ref: "#/components/schemas/ApiKeyRefreshRequest"
                - $ref: "#/components/schemas/AuthorizationCodeGrantRequest"
                - $ref: "#/components/schemas/OAuthClientRefreshRequest"
            examples:
              apiKey:
                summary: Primeira troca com API key
                value:
                  grant_type: api_key
                  api_key: tk_live_...
                  scope: menu:read products:read
              authorizationCode:
                summary: Código de um app instalado com PKCE
                value:
                  grant_type: authorization_code
                  client_id: tk_app_...
                  code: tk_code_...
                  redirect_uri: https://app.example.com/oauth/callback
                  code_verifier: verifier-base64url
      responses:
        "200":
          description: Access e refresh tokens emitidos com sucesso.
          headers:
            Cache-Control:
              schema:
                type: string
              example: no-store
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenResponse"
        "400":
          description: Grant ou escopo inválido. invalid_grant de apps orienta nova autorização; não repita a credencial antiga.
          headers:
            X-OAuth-Recovery:
              description: Presente em invalid_grant de authorization_code e refresh_token de apps. Falhas transitórias não recebem esta orientação.
              schema:
                type: string
                enum: [reauthorize]
            X-Error-Id:
              description: Identificador de correlação para suporte.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthError"
        "401":
          description: Chave ausente, inválida, expirada ou revogada.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthError"

  /oauth/revoke:
    post:
      tags: [Autenticação]
      summary: Revogar um access token
      description: |
        Revoga antecipadamente um access ou refresh token. A operação é
        idempotente. Apps públicos `tk_app_...` enviam `client_id` e não possuem
        client secret. Para encerrar todas as sessões de uma API key, revogue a
        chave no AI Builders.
      operationId: revokeAccessToken
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/RevokeTokenRequest"
      responses:
        "200":
          description: Solicitação processada, inclusive para token desconhecido ou já revogado.
        "400":
          description: Client ID ausente ou formulário inválido.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthError"

  /v1/menu:
    get:
      tags: [Cardápio]
      summary: Consultar cardápio publicado
      description: |
        Retorna as seções vendidas ao cliente, seus produtos e, opcionalmente,
        os grupos de complementos. Com OAuth, exige o escopo `menu:read`; a
        sessão do restaurante também é aceita sem escopos de integração.

        O contrato remove registros excluídos, categorias de embalagem e
        espelhos internos do iFood. Preços, disponibilidade e apresentação são
        agrupados em objetos. `pricing.resolved.base` aplica a prioridade dos
        preços do canal; `pricing.resolved.minimum` soma as escolhas obrigatórias.
        Disponibilidade avalia canal, horários, esgotamento e escolhas válidas.
        Não retorna objeto de restaurante nem aliases do contrato anterior.
        Não substitui validação de checkout, abertura da loja ou capacidade de entrega.
      operationId: getMenu
      parameters:
        - $ref: "#/components/parameters/RestaurantId"
        - name: channel
          in: query
          description: Canal que define disponibilidade e preço efetivo.
          schema:
            type: string
            enum: [in_store, delivery]
            default: in_store
        - name: only_available
          in: query
          description: Quando true, remove itens inelegíveis, esgotados, grupos inutilizáveis e seções vazias. False preserva-os com availability.resolved.reason.
          schema:
            type: boolean
            default: true
        - name: category_id
          in: query
          description: Restringe a resposta a uma categoria.
          schema:
            type: integer
            minimum: 1
        - name: search
          in: query
          description: Busca por nome e descrição, sem diferenciar acentos ou caixa.
          schema:
            type: string
            maxLength: 120
        - name: brand_id
          in: query
          description: Restringe às categorias da marca, sempre dentro do restaurante autorizado.
          schema:
            type: integer
            minimum: 1
        - name: scheduled_at
          in: query
          description: Instante ISO 8601 com Z ou offset explícito; exige channel=delivery. Avalia horários e permissão de agendamento do produto. Sem este parâmetro, usa o instante atual e o canal imediato.
          schema:
            type: string
            format: date-time
            example: "2026-08-28T19:00:00-03:00"
        - name: include_complements
          in: query
          description: Inclui grupos e opções. False omite a propriedade, mas mantém os mesmos cálculos de preço e disponibilidade.
          schema:
            type: boolean
            default: true
        - name: include_fiscal_info
          in: query
          description: Inclui fiscal em cada produto, sem alias fiscal_info nem metadados internos.
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: Cardápio resolvido para o restaurante e canal.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MenuResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /v1/table-sessions:
    get:
      tags: [Pedidos]
      summary: Listar sessões de comanda
      description: |
        Retorna comandas abertas e fechadas com contas, pedidos, pagamentos e
        dados fiscais. O intervalo máximo é de três dias e as datas são UTC.
        Com OAuth, exige o escopo `table-sessions:read`; a sessão do
        restaurante também é aceita sem escopos de integração.

        A resposta preserva o contrato publicado: chaves `snake_case`, valores
        monetários como strings com escala e relações aninhadas.
        `status_timings` sempre está presente e agrupa os horários persistidos
        do ciclo do pedido. Etapas ainda não atingidas retornam `null`; a API
        não infere transições ausentes nem calcula durações.
        `bills[].buyer.delivery_address` é o destino selecionado pela sessão por
        `buyer_delivery_address_id`, nunca um endereço arbitrário do cadastro do comprador.
        Retorna null para sessões sem entrega, retirada, destino ausente ou de outro
        restaurante; um comprador ausente também permanece null.
        `motoboy_id` filtra pelo entregador atribuído à sessão, dentro do mesmo
        restaurante, mantendo todos os pedidos aninhados. Pode ser combinado com
        `brand_id`; as datas continuam obrigatórias. IDs sem correspondência ou
        de outro restaurante retornam lista vazia.
        `motoboy_id` e `motoboy` sempre estão presentes. O objeto contém apenas
        `id`, `name` e `phone`, com contatos anuláveis. Ambos retornam null para
        vínculos ausentes ou contraditórios, inclusive de outro restaurante.
        Atribuições históricas permanecem disponíveis para entregadores arquivados.
        `intended_payments` sempre está presente e concentra `payment_method`,
        `change_for`, `is_prepaid` e `ifood_paid`, mesmo antes de existir um pagamento.
        A forma é uma intenção; no checkout nativo, `change_for` representa
        "troco para", não troco já devolvido.
        `payments` continua contendo somente os pagamentos registrados.
        `session_number` é a sequência anulável da comanda no restaurante,
        distinta do ID interno e de `attendance_password`.
        Os filtros discount_obs, coupon_id, coupon_code, coupon_title e coupon_type
        podem ser combinados com os filtros existentes (AND). Os critérios de cupom
        devem corresponder ao mesmo uso não cancelado, com vínculo válido à loja
        ou a um cupom global. Textos são aparados; % e _ são literais. Não filtra
        os itens da resposta: a comanda completa e todos os cupons válidos são mantidos.
        A filtragem ocorre antes da paginação; reutilize o cursor com os mesmos filtros.
      operationId: getTableSessionsV1
      parameters:
        - name: buyer_id
          in: query
          required: false
          description: ID exato de buyers.id vinculado a uma conta da comanda; não é client_id do Clube. Com buyer_phone, ambos devem corresponder ao mesmo comprador.
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
        - name: buyer_phone
          in: query
          required: false
          description: Telefone completo (55 + DDD + número), somente dígitos. Normaliza a formatação dos telefones cadastrados e encontra todos os compradores com esse telefone, dentro do restaurante. Sem busca parcial; mantém a comanda completa.
          schema:
            type: string
            pattern: '^55[0-9]{10,11}$'
            example: '5527999990000'
        - name: discount_obs
          in: query
          required: false
          description: Trecho literal da observação de desconto; busca sem diferenciar maiúsculas.
          schema:
            type: string
            minLength: 1
            maxLength: 255
        - name: coupon_id
          in: query
          required: false
          description: ID exato do cupom utilizado.
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
        - name: coupon_code
          in: query
          required: false
          description: Código atual exato do cupom, diferenciando maiúsculas.
          schema:
            type: string
            minLength: 1
            maxLength: 255
        - name: coupon_title
          in: query
          required: false
          description: Trecho literal do título atual do cupom; busca sem diferenciar maiúsculas.
          schema:
            type: string
            minLength: 1
            maxLength: 255
        - name: coupon_type
          in: query
          required: false
          description: Tipo registrado no uso não cancelado do cupom.
          schema:
            type: string
            enum: [percentage, absolute, free-shipping]
        - $ref: "#/components/parameters/RestaurantId"
        - $ref: "#/components/parameters/BrandId"
        - name: motoboy_id
          in: query
          required: false
          description: ID do entregador atribuído à sessão no restaurante consultado.
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
        - name: start_date
          in: query
          required: true
          description: Data/hora inicial em UTC.
          schema:
            type: string
            format: date-time
        - name: end_date
          in: query
          required: true
          description: Data/hora final em UTC. Aceita até três dias inteiros mais uma fração; quatro dias são rejeitados. Intervalo invertido retorna lista vazia.
          schema:
            type: string
            format: date-time
      responses:
        "200":
          description: Lista de sessões de comanda.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/TableSessionV1"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /v2/table-sessions:
    get:
      tags:
        - Pedidos
      summary: Listar sessões de comanda (V2 paginada)
      description: >-
        Comandas, contas, pedidos, pagamentos e dados fiscais em páginas ordenadas por ID. Datas UTC, sem limite
        de dias na V2. limit: padrão 50, máximo 100; cursor vinculado à loja e aos filtros. Continue com
        pagination.next até has_more=false. Cada sessão inclui o objeto intended_payments
        (payment_method, change_for, is_prepaid, ifood_paid), separado de payments.
        No checkout nativo, change_for significa troco para, não o troco devolvido.
        A V1 mantém seu envelope anterior.
        Os filtros discount_obs, coupon_id, coupon_code, coupon_title e coupon_type
        podem ser combinados com os filtros existentes (AND). Os critérios de cupom
        devem corresponder ao mesmo uso não cancelado, com vínculo válido à loja
        ou a um cupom global. Textos são aparados; % e _ são literais. Não filtra
        os itens da resposta: a comanda completa e todos os cupons válidos são mantidos.
        A filtragem ocorre antes da paginação; reutilize o cursor com os mesmos filtros.
      operationId: getTableSessionsV1PaginatedV2
      parameters:
        - name: buyer_id
          in: query
          required: false
          description: ID exato de buyers.id vinculado a uma conta da comanda; não é client_id do Clube. Com buyer_phone, ambos devem corresponder ao mesmo comprador.
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
        - name: buyer_phone
          in: query
          required: false
          description: Telefone completo (55 + DDD + número), somente dígitos. Normaliza a formatação dos telefones cadastrados e encontra todos os compradores com esse telefone, dentro do restaurante. Sem busca parcial; mantém a comanda completa.
          schema:
            type: string
            pattern: '^55[0-9]{10,11}$'
            example: '5527999990000'
        - name: discount_obs
          in: query
          required: false
          description: Trecho literal da observação de desconto; busca sem diferenciar maiúsculas.
          schema:
            type: string
            minLength: 1
            maxLength: 255
        - name: coupon_id
          in: query
          required: false
          description: ID exato do cupom utilizado.
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
        - name: coupon_code
          in: query
          required: false
          description: Código atual exato do cupom, diferenciando maiúsculas.
          schema:
            type: string
            minLength: 1
            maxLength: 255
        - name: coupon_title
          in: query
          required: false
          description: Trecho literal do título atual do cupom; busca sem diferenciar maiúsculas.
          schema:
            type: string
            minLength: 1
            maxLength: 255
        - name: coupon_type
          in: query
          required: false
          description: Tipo registrado no uso não cancelado do cupom.
          schema:
            type: string
            enum: [percentage, absolute, free-shipping]
        - $ref: '#/components/parameters/RestaurantId'
        - $ref: '#/components/parameters/BrandId'
        - name: motoboy_id
          in: query
          required: false
          description: ID do entregador atribuído à sessão no restaurante consultado.
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
        - name: start_date
          in: query
          required: true
          description: Data/hora inicial em UTC.
          schema:
            type: string
            format: date-time
        - name: end_date
          in: query
          required: true
          description: Data/hora final em UTC, sem limite de dias. Intervalo invertido retorna uma página vazia.
          schema:
            type: string
            format: date-time
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: cursor
          in: query
          description: Cursor retornado em pagination.next.cursor; mantenha a loja e os filtros originais.
          schema:
            type: string
            maxLength: 500
      responses:
        '200':
          description: Lista de sessões de comanda.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableSessionsPage'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /v1/table-sessions/{sessionId}:
    get:
      tags: [Pedidos]
      summary: Consultar uma sessão de comanda
      operationId: getTableSessionV1
      description: |
        Retorna uma sessão aberta ou fechada, com o mesmo objeto e relações da
        listagem: pedidos, contas, pagamentos, troco, previsão de recebimento,
        códigos de complementos, dados fiscais, status_timings e motoboy.
        Não exige intervalo de datas. O ID interno é combinado com o restaurante
        autorizado e, quando informado, brand_id. Sessões ausentes, de outra loja
        ou fora da marca selecionada retornam o mesmo 404 table_session_not_found.
        Exige table-sessions:read com OAuth ou uma sessão verificada do restaurante.
      parameters:
        - $ref: "#/components/parameters/RestaurantId"
        - $ref: "#/components/parameters/BrandId"
        - name: sessionId
          in: path
          required: true
          description: ID interno da sessão, não session_number nem attendance_password.
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
      responses:
        "200":
          description: Uma sessão completa de comanda.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TableSessionV1"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Sessão não encontrada no restaurante e marca autorizados (table_session_not_found).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"

  /v1/payment-methods:
    get:
      tags: [Catálogo]
      summary: Listar métodos de pagamento
      description: |
        Retorna os métodos habilitados para o restaurante. Com OAuth, exige o
        escopo `payment-methods:read`; a sessão do restaurante também é aceita.
      operationId: getPaymentMethodsV1
      parameters:
        - $ref: "#/components/parameters/RestaurantId"
      responses:
        "200":
          description: Lista de métodos de pagamento.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "./openapi.yaml#/components/schemas/PaymentMethodItem"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /v1/files:
    post:
      tags: [Catálogo]
      summary: Enviar uma imagem de produto do cardápio
      operationId: uploadProductImageV1
      description: |
        Requer products:write ou sessão de restaurante. Apenas um campo multipart file,
        JPEG/PNG/WebP de até 10 MiB e 25 megapixels. Conteúdo real é validado;
        animações são rejeitadas. Produz WebP de até 1600px e miniatura de até 400px,
        sem metadados. Upload não altera produtos. Use o id como image_id em criações
        ou edições no mesmo restaurante. Não permite arquivos genéricos nem exclusão.
      parameters:
        - $ref: "#/components/parameters/RestaurantId"
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              additionalProperties: false
              required: [file]
              properties:
                file: { type: string, format: binary }
      responses:
        "201":
          description: Imagem persistida para uso nos produtos deste restaurante.
          content:
            application/json:
              schema:
                type: object
                required: [id, name, path, url, thumbnail_url, content_type, size]
                properties:
                  id: { description: "ID do arquivo de imagem criado; envie como image_id ao criar ou editar um produto.", type: integer, minimum: 1 }
                  name: { description: "Nome do arquivo original enviado (sem caminho, sem caracteres de controle, até 255 caracteres); padrão \"Imagem de produto.webp\".", type: string }
                  path: { description: "Caminho relativo da imagem no armazenamento (product-images/r<restaurant_id>/<uuid>.webp).", type: string }
                  url: { description: "URL pública da imagem convertida para WebP (máx. 1600×1600 px, qualidade 80).", type: string, format: uri }
                  thumbnail_url: { description: "URL pública da miniatura WebP (máx. 400×400 px).", type: string, format: uri }
                  content_type: { description: "Tipo MIME do arquivo armazenado; sempre image/webp, qualquer que seja o formato enviado (JPEG, PNG ou WebP).", type: string, const: image/webp }
                  size: { description: "Tamanho em bytes da imagem WebP armazenada (após conversão), não do arquivo enviado.", type: integer, minimum: 1 }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "413":
          description: Imagem excede 10 MiB.
        "503":
          description: image_upload_unavailable ou image_upload_failed; nenhum produto alterado.

  /v1/integrations/ifood/merchants:
    get:
      tags: [Catálogo]
      summary: Listar lojas iFood do restaurante
      operationId: listIfoodMerchantsV1
      description: Requer products:read ou sessão do restaurante. Lista somente vínculos iFood não cancelados do restaurante autorizado; não expõe tokens. Use ifood_restaurant_id no caminho da consulta de itens; ifood_merchant_id é o identificador externo.
      x-required-scope: products:read
      parameters:
        - $ref: "#/components/parameters/RestaurantId"
      responses:
        "200":
          description: Lojas iFood vinculadas.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required: [ifood_restaurant_id, ifood_merchant_id, name, active]
                  properties:
                    ifood_restaurant_id: { description: "ID do vínculo da loja iFood com o restaurante na Takeat; use como {id} em .../merchants/{id}/products e em ifood_targets[].ifood_restaurant_id.", type: integer }
                    ifood_merchant_id: { description: "ID da loja (merchant) no iFood, em formato UUID.", type: string }
                    name: { description: "Nome da loja iFood registrado no vínculo; null quando não informado.", type: [string, "null"] }
                    active: { description: "Se o vínculo com essa loja iFood está ativo. Vínculos cancelados não são listados.", type: boolean }
              examples:
                LojasIfoodVinculadas:
                  $ref: "#/components/examples/LojasIfoodVinculadas"
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }

  /v1/integrations/ifood/merchants/{id}/products:
    get:
      tags: [Catálogo]
      summary: Consultar itens do catálogo iFood
      operationId: listIfoodCatalogProductsV1
      description: Requer products:read ou sessão do restaurante. Consulta o catálogo DEFAULT da loja autorizada no iFood para escolher ifood_item_id. O parâmetro id recebe o ifood_restaurant_id numérico da consulta de lojas. Usa o token compartilhado e pode renová-lo quando expirado. Não publica códigos.
      x-required-scope: products:read
      parameters:
        - $ref: "#/components/parameters/RestaurantId"
        - name: id
          in: path
          required: true
          schema: { type: integer, minimum: 1 }
      responses:
        "200":
          description: Itens do catálogo DEFAULT.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required: [ifood_item_id, name, external_code]
                  properties:
                    ifood_item_id: { description: "ID do item no catálogo iFood da loja (UUID); use em ifood_targets[].ifood_item_id.", type: string }
                    name: { description: "Nome do item no catálogo iFood (nome do item, ou do produto associado); string vazia se o iFood não informar.", type: string }
                    external_code: { description: "Código externo (código PDV) atualmente gravado no item iFood, no contexto DEFAULT; null quando o item não tem código.", type: [string, "null"] }
              examples:
                ItensIfoodCatalogo:
                  $ref: "#/components/examples/ItensIfoodCatalogo"
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { description: Loja ou catálogo não encontrado no contexto autorizado. }
        "502": { description: Falha ou resposta inválida do iFood. }
        "503": { description: Token ou configuração de renovação indisponível. }

  /v1/products:
    get:
      tags: [Catálogo]
      summary: Listar produtos por categoria
      description: |
        Retorna categorias e produtos no formato compatível com o API Legado,
        incluindo `pdv_codes` e o objeto adicional `fiscal` em cada produto.
        Com OAuth, exige o escopo `products:read`; a
        sessão do restaurante também é aceita.
      operationId: getProductsV1
      parameters:
        - $ref: "#/components/parameters/RestaurantId"
        - $ref: "#/components/parameters/BrandId"
      responses:
        "200":
          description: Categorias com seus produtos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ProductCategory"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
    post:
      tags: [Catálogo]
      summary: Criar produto
      description: |
        Cria um produto em uma categoria não removida do restaurante. Com OAuth,
        exige `products:write`; a sessão do restaurante também é aceita. Não
        existe exclusão de produtos nesta API.
        Uma categoria indisponível pode receber produtos, mas não aparece no menu
        com only_available=true. Envie preços como números, não strings.
        Veja a [referência de campos](/externo/v1/campos-do-produto) para padrões
        de criação e efeitos sobre preços, disponibilidade e esgotamento.
      operationId: createProductV1
      parameters:
        - $ref: "#/components/parameters/RestaurantId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateProductRequest"
      responses:
        "201":
          description: Produto criado.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ManagedProduct"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Categoria não encontrada no restaurante autorizado.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ApiError" }

  /v1/products/{productId}:
    get:
      tags: [Catálogo]
      summary: Consultar produto
      description: Requer products:read. Retorna um produto ativo do restaurante autorizado e sua versão updated_at.
      operationId: getProductV1
      parameters:
        - $ref: "#/components/parameters/ProductId"
        - $ref: "#/components/parameters/RestaurantId"
      responses:
        "200":
          description: Produto encontrado.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ManagedProduct" }
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Produto não encontrado no restaurante autorizado.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ApiError" }
    put:
      tags: [Catálogo]
      summary: Editar produto
      description: |
        Atualização parcial: campos ausentes permanecem intactos. Com OAuth,
        exige `products:write`; a sessão do restaurante também é aceita.
        null limpa descrição e preços opcionais; zero define preço zero.
        Alterar o preço base não encerra uma promoção existente.
        Consulte a [referência de campos](/externo/v1/campos-do-produto).
        replicate_ifood=false por padrão. true exige ifood:catalog:write e destinos explícitos;
        a publicação ocorre após a confirmação da gravação local. Falha remota não desfaz a gravação local e retorna 207.
      x-conditional-scopes:
        replicate_ifood=true: [ifood:catalog:write]
      operationId: updateProductV1
      parameters:
        - $ref: "#/components/parameters/ProductId"
        - $ref: "#/components/parameters/RestaurantId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateProductRequest"
            examples:
              EdicaoLocalPdv:
                $ref: "#/components/examples/EdicaoLocalPdv"
              PublicacaoProdutoIfood:
                $ref: "#/components/examples/PublicacaoProdutoIfood"
              RepeticaoPublicacaoIfood:
                $ref: "#/components/examples/RepeticaoPublicacaoIfood"
      responses:
        "207":
          description: Gravação local concluída; uma ou mais publicações incompletas. Examine ifood_replication.results por produto. Os dados locais foram preservados.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ManagedProduct"
              examples:
                ProdutoComPublicacaoParcial:
                  $ref: "#/components/examples/ProdutoComPublicacaoParcial"
        "200":
          description: Produto atualizado.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ManagedProduct"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Produto ou categoria não encontrados no restaurante autorizado.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ApiError" }

        "409":
          description: product_update_conflict ou product_pdv_code_conflict. Nenhuma alteração local aplicada. Consulte e revise novamente.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ApiError" }

  /v1/products/bulk:
    post:
      tags: [Catálogo]
      summary: Criar de 1 a 100 produtos atomicamente
      operationId: createProductsV1
      description: Requer products:write ou sessão de restaurante. Lote serializável; qualquer erro impede todas as criações. Imagens devem pertencer ao restaurante.
      parameters:
        - $ref: "#/components/parameters/RestaurantId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              maxItems: 100
              items: { $ref: "#/components/schemas/CreateProductRequest" }
      responses:
        "201":
          description: Produtos criados na ordem da requisição.
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/ManagedProduct" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404":
          description: Categoria ou imagem não encontrada; lote não aplicado.
        "409":
          description: Conflito na transação; lote não aplicado.
    put:
      tags: [Catálogo]
      summary: Editar vários produtos atomicamente
      description: |
        Requer products:write ou sessão de restaurante. Corpo é um array de
        1–100 edições parciais. IDs repetidos causam 400 duplicate_product_ids.
        Qualquer falha local impede todas as alterações locais e chamadas remotas. Zero é permitido nos preços.
        expected_updated_at permite impedir a aplicação de uma revisão obsoleta.
        Os campos têm os mesmos efeitos da edição individual; consulte a
        [referência de campos](/externo/v1/campos-do-produto).
        replicate_ifood=false por padrão. true exige ifood:catalog:write e destinos explícitos;
        a publicação ocorre após a confirmação da gravação local. Falha remota não desfaz a gravação local e retorna 207.
      x-conditional-scopes:
        replicate_ifood=true: [ifood:catalog:write]
      operationId: updateProductsV1
      parameters:
        - $ref: "#/components/parameters/RestaurantId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              maxItems: 100
              items:
                type: object
                allOf:
                  - $ref: "#/components/schemas/UpdateProductFields"
                  - type: object
                    properties:
                      id: { type: integer, minimum: 1 }
                    required: [id]
                unevaluatedProperties: false
            example:
              - { id: 42, price: 0 }
              - { id: 43, delivery_price: 0 }
            examples:
              LoteMistoPdv:
                $ref: "#/components/examples/LoteMistoPdv"
      responses:
        "207":
          description: Gravação local concluída; uma ou mais publicações incompletas. Examine ifood_replication.results por produto. Os dados locais foram preservados.
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/ManagedProduct" }
              examples:
                LoteComPublicacaoParcial:
                  $ref: "#/components/examples/LoteComPublicacaoParcial"
        "200":
          description: Produtos atualizados na ordem da requisição.
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/ManagedProduct" }
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Produto ou categoria não encontrados. Lote não aplicado.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ApiError" }
        "409":
          description: product_update_conflict — nenhum produto atualizado.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ApiError" }

  /v1/products/{productId}/availability:
    patch:
      tags: [Catálogo]
      summary: Alterar disponibilidade por canal
      description: |
        Altera `available` (presencial) e/ou `available_in_delivery`
        (delivery). Ao menos um campo é obrigatório. Com OAuth, exige
        `products:write`; a sessão do restaurante também é aceita.
        Os canais são independentes. Para marcar ou reverter esgotamento,
        envie sold_off no PUT individual ou em lote, não nesta rota.
      operationId: updateProductAvailabilityV1
      parameters:
        - $ref: "#/components/parameters/ProductId"
        - $ref: "#/components/parameters/RestaurantId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateProductAvailabilityRequest"
      responses:
        "200":
          description: Disponibilidade atualizada.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ManagedProduct"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Produto não encontrado no restaurante autorizado.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ApiError" }

  /v1/complements/{complementId}:
    get:
      tags:
        - Complementos
      summary: Consultar complemento
      description: >-
        Requer complements:read ou sessão de restaurante. Tenant validado pelo restaurante autorizado.
        Consulte /externo/v1/gerenciar-complementos.
      operationId: getComplementV1
      parameters:
        - $ref: '#/components/parameters/ComplementId'
        - $ref: '#/components/parameters/RestaurantId'
      responses:
        '200':
          description: Complemento encontrado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedComplement'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Complemento não encontrado no restaurante autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
    put:
      tags:
        - Complementos
      summary: Editar complemento
      description: >-
        Requer complements:write ou sessão de restaurante. Tenant validado pelo restaurante
        autorizado. Consulte /externo/v1/gerenciar-complementos. Edição parcial; campos omitidos são
        preservados. expected_updated_at detecta revisões obsoletas; conflitos retornam 409. Bulk
        aplica 1–100 itens atomicamente na ordem recebida.
      operationId: updateComplementV1
      parameters:
        - $ref: '#/components/parameters/ComplementId'
        - $ref: '#/components/parameters/RestaurantId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateComplementRequest'
      responses:
        '200':
          description: Complemento atualizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedComplement'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Complemento não encontrado no restaurante autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: >-
            complement_update_conflict: revisão obsoleta ou conflito concorrente; nenhuma alteração
            aplicada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/complements/bulk:
    put:
      tags:
        - Complementos
      summary: Editar vários complementos atomicamente
      description: >-
        Requer complements:write ou sessão de restaurante. Tenant validado pelo restaurante
        autorizado. Consulte /externo/v1/gerenciar-complementos. Edição parcial; campos omitidos são
        preservados. expected_updated_at detecta revisões obsoletas; conflitos retornam 409. Bulk
        aplica 1–100 itens atomicamente na ordem recebida.
      operationId: updateComplementsV1
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              maxItems: 100
              items:
                type: object
                allOf:
                  - $ref: '#/components/schemas/UpdateComplementFields'
                  - type: object
                    properties:
                      id:
                        type: integer
                        minimum: 1
                    required:
                      - id
                unevaluatedProperties: false
            example:
              - id: 42
                price: 0
              - id: 43
                delivery_price: 0
      responses:
        '200':
          description: Complementos atualizados na ordem da requisição.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ManagedComplement'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Complemento não encontrado no restaurante autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: >-
            complement_update_conflict: revisão obsoleta ou conflito concorrente; nenhuma alteração
            aplicada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/complements/{complementId}/availability:
    patch:
      tags:
        - Complementos
      summary: Alterar disponibilidade por canal
      description: >-
        Requer complements:write ou sessão de restaurante. Tenant validado pelo restaurante
        autorizado. Consulte /externo/v1/gerenciar-complementos. Edição parcial; campos omitidos são
        preservados. expected_updated_at detecta revisões obsoletas; conflitos retornam 409. Bulk
        aplica 1–100 itens atomicamente na ordem recebida.
      operationId: updateComplementAvailabilityV1
      parameters:
        - $ref: '#/components/parameters/ComplementId'
        - $ref: '#/components/parameters/RestaurantId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateComplementAvailabilityRequest'
      responses:
        '200':
          description: Disponibilidade atualizada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedComplement'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Complemento não encontrado no restaurante autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: >-
            complement_update_conflict: revisão obsoleta ou conflito concorrente; nenhuma alteração
            aplicada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'

  /v1/product-categories:
    get:
      tags:
        - "Catálogo"
      summary: "Listar categorias de produtos"
      operationId: "listProductCategoriesV1"
      description: |
        Retorna as categorias de produtos não removidas do restaurante,
        ordenadas por `custom_order` e depois por `id`. Com OAuth, exige o
        escopo `products:read`; a sessão autenticada do restaurante também é
        aceita.
        Escopo products:read ou sessão autenticada de restaurante. Isolamento pelo restaurante autorizado. Disponibilidades de cada canal são independentes; omissões preservam campos. Marca deve pertencer ao restaurante e não pode ser trocada na edição. Não expõe exclusão, imagens, horários ou configurações de integração.
      parameters:
        -
          $ref: "#/components/parameters/RestaurantId"
      responses:
        200:
          description: "Operação concluída."
          content:
            application/json:
              schema:
                type: "array"
                items:
                  $ref: "#/components/schemas/ManagedProductCategory"
        400:
          description: "Campos inválidos ou marca fora do restaurante (invalid_product_category)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Credencial ausente ou inválida."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        403:
          description: "Escopo insuficiente ou restaurante não autorizado."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        404:
          description: "Categoria inexistente, excluída ou de outro restaurante (product_category_not_found)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        409:
          description: "Revisão obsoleta, edição concorrente ou categoria gerenciada por integração/multiloja (product_category_conflict)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
    post:
      tags:
        - "Catálogo"
      summary: "Criar categoria de produtos"
      operationId: "createProductCategoryV1"
      description: |
        Cria uma categoria para uma marca não removida do restaurante autorizado. Com
        OAuth, exige `products:write`; a sessão autenticada do restaurante
        também é aceita. Os campos de disponibilidade e ordenação omitidos
        usam os defaults do cadastro. O nome é normalizado removendo espaços
        nas extremidades.
        Escopo products:write ou sessão autenticada de restaurante. Isolamento pelo restaurante autorizado. Disponibilidades de cada canal são independentes; omissões preservam campos. Marca deve pertencer ao restaurante e não pode ser trocada na edição. Não expõe exclusão, imagens, horários ou configurações de integração.
      parameters:
        -
          $ref: "#/components/parameters/RestaurantId"
      responses:
        201:
          description: "Operação concluída."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ManagedProductCategory"
        400:
          description: "Campos inválidos ou marca fora do restaurante (invalid_product_category)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Credencial ausente ou inválida."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        403:
          description: "Escopo insuficiente ou restaurante não autorizado."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        404:
          description: "Categoria inexistente, excluída ou de outro restaurante (product_category_not_found)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        409:
          description: "Revisão obsoleta, edição concorrente ou categoria gerenciada por integração/multiloja (product_category_conflict)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateProductCategoryRequest"
  /v1/product-categories/{categoryId}:
    get:
      tags:
        - "Catálogo"
      summary: "Consultar categoria de produtos"
      operationId: "getProductCategoryV1"
      description: |
        Retorna uma categoria de produtos não removida do restaurante
        autorizado. Com OAuth, exige `products:read`; a sessão autenticada do
        restaurante também é aceita.
        Escopo products:read ou sessão autenticada de restaurante. Isolamento pelo restaurante autorizado. Disponibilidades de cada canal são independentes; omissões preservam campos. Marca deve pertencer ao restaurante e não pode ser trocada na edição. Não expõe exclusão, imagens, horários ou configurações de integração.
      parameters:
        -
          $ref: "#/components/parameters/RestaurantId"
        -
          name: "categoryId"
          in: "path"
          required: true
          schema:
            type: "integer"
            minimum: 1
            maximum: 2147483647
      responses:
        200:
          description: "Operação concluída."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ManagedProductCategory"
        400:
          description: "Campos inválidos ou marca fora do restaurante (invalid_product_category)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Credencial ausente ou inválida."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        403:
          description: "Escopo insuficiente ou restaurante não autorizado."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        404:
          description: "Categoria inexistente, excluída ou de outro restaurante (product_category_not_found)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        409:
          description: "Revisão obsoleta, edição concorrente ou categoria gerenciada por integração/multiloja (product_category_conflict)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
    put:
      tags:
        - "Catálogo"
      summary: "Editar parcialmente categoria de produtos"
      operationId: "updateProductCategoryV1"
      description: |
        Atualização parcial: campos omitidos permanecem intactos. Com OAuth,
        exige `products:write`; a sessão autenticada do restaurante também é
        aceita. `brand_id` não pode ser alterado. Envie `updated_at` da última
        consulta como `expected_updated_at` para rejeitar uma revisão obsoleta.
        O nome é normalizado removendo espaços nas extremidades.
        Escopo products:write ou sessão autenticada de restaurante. Isolamento pelo restaurante autorizado. Disponibilidades de cada canal são independentes; omissões preservam campos. Marca deve pertencer ao restaurante e não pode ser trocada na edição. Não expõe exclusão, imagens, horários ou configurações de integração.
      parameters:
        -
          $ref: "#/components/parameters/RestaurantId"
        -
          name: "categoryId"
          in: "path"
          required: true
          schema:
            type: "integer"
            minimum: 1
            maximum: 2147483647
      responses:
        200:
          description: "Operação concluída."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ManagedProductCategory"
        400:
          description: "Campos inválidos ou marca fora do restaurante (invalid_product_category)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Credencial ausente ou inválida."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        403:
          description: "Escopo insuficiente ou restaurante não autorizado."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        404:
          description: "Categoria inexistente, excluída ou de outro restaurante (product_category_not_found)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        409:
          description: "Revisão obsoleta, edição concorrente ou categoria gerenciada por integração/multiloja (product_category_conflict)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateProductCategoryRequest"

  /v1/complement-categories:
    get:
      tags: [Complementos]
      summary: Listar categorias de complementos
      operationId: listComplementCategoriesV1
      description: "Escopo complements:read, ou sessão autenticada do restaurante. Vínculos são compartilhados; todas as referências são validadas no restaurante e marca."
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
      responses:
        '200':
          description: Operação concluída.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ManagedComplementCategory'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      tags: [Complementos]
      summary: Criar categoria de complementos
      operationId: createComplementCategoryV1
      description: "Escopo complements:write, ou sessão autenticada do restaurante. Vínculos são compartilhados; todas as referências são validadas no restaurante e marca."
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateComplementCategoryRequest'
      responses:
        '409':
          description: Conflito de versão ou transação; nenhuma alteração aplicada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '201':
          description: Operação concluída.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedComplementCategory'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v1/complement-categories/{categoryId}:
    put:
      tags: [Complementos]
      summary: Atualizar categoria de complementos
      operationId: updateComplementCategoryV1
      description: "Escopo complements:write, ou sessão autenticada do restaurante. Vínculos são compartilhados; todas as referências são validadas no restaurante e marca."
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
        - in: path
          name: categoryId
          required: true
          schema: { type: integer, minimum: 1, maximum: 2147483647 }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateComplementCategoryRequest'
      responses:
        '409':
          description: Conflito de versão ou transação; nenhuma alteração aplicada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '200':
          description: Operação concluída.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedComplementCategory'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v1/complements:
    post:
      tags: [Complementos]
      summary: Criar complemento
      operationId: createComplementV1
      description: "Escopo complements:write, ou sessão autenticada do restaurante. Vínculos são compartilhados; todas as referências são validadas no restaurante e marca."
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateComplementRequest'
      responses:
        '409':
          description: Conflito de versão ou transação; nenhuma alteração aplicada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '201':
          description: Operação concluída.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedComplement'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    get:
      tags: [Catálogo]
      summary: Listar complementos por categoria
      description: |
        Retorna categorias de complementos e seus itens no formato compatível
        com o API Legado. Com OAuth, exige o escopo `complements:read`; a
        sessão do restaurante também é aceita.
      operationId: getComplementsV1
      parameters:
        - $ref: "#/components/parameters/RestaurantId"
        - $ref: "#/components/parameters/BrandId"
      responses:
        "200":
          description: Categorias com seus complementos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "./openapi.yaml#/components/schemas/ComplementCategory"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /v1/clients:
    get:
      tags: [Clientes]
      operationId: getClientsV1
      summary: Listar clientes vinculados ao restaurante
      x-required-scope: clients:read
      security:
        - bearerAuth: []
      description: |
        Exige `clients:read` no access token OAuth ou sessão autenticada do restaurante.
        Lista buyers vinculados, inclusive importados e sem compras. O ID público é buyers.id,
        preservado após cadastro no Clube. Pessoas existentes somente no Clube não entram.
        Telefones brasileiros são normalizados com DDI 55, sem inferir DDD ou nono dígito.
        O filtro de cadastro ativo na loja é aplicado antes de contar e paginar. Ordenação por ID crescente.
        Compras são sessões finished/completed ou deliveries delivered/finished, mesmo abertos,
        excluindo pedidos cancelados. Total gasto soma somente cestas atribuídas ao buyer,
        com fallback para o buyer da conta individual, sem frete, taxas ou pagamentos separados.
        Não consulta números intermediários de marketplace. Não altera cadastros ou saldos.
        Sem Clube configurado ou sem loja ativa no Clube, retorna os clientes da Takeat com registered_in_clube false, clube, cashback e cashback_expires_at null.
        Indisponibilidade, timeout ou resposta inválida do Clube falha integralmente com 502 clube_unavailable.
        A rota GET /v1/clube/clients mantém seu contrato independente.
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
        - name: page
          in: query
          schema: { type: integer, minimum: 1, default: 1 }
        - name: per_page
          in: query
          schema: { type: integer, minimum: 1, maximum: 200, default: 100 }
        - name: registered_in_clube
          in: query
          description: Cadastro ativo no Clube da loja. Aceita somente true ou false; ausência não filtra.
          schema: { type: boolean }
      responses:
        '200':
          description: Página de buyers; página excedente preserva totais e retorna clients vazio. Base vazia tem total_pages zero.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestaurantClientsPage'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          description: Clube indisponível, configuração inconsistente ou cadastro ambíguo. Nenhuma resposta parcial.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example: { statusCode: 502, key: clube_unavailable, message: Não foi possível consultar os dados do Clube. }

  /v1/clube/clients:
    get:
      tags: [Clube de Fidelidade]
      summary: Listar clientes do Clube de Fidelidade
      description: |
        Retorna uma página de clientes do Clube. Com OAuth, exige o escopo
        `clube:read`; a sessão do restaurante também é aceita. O restaurante
        precisa ter o Clube configurado.
      operationId: getClubeClientsV1
      parameters:
        - $ref: "#/components/parameters/RestaurantId"
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: per_page
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 100
      responses:
        "200":
          description: Página de clientes do Clube.
          content:
            application/json:
              schema:
                $ref: "./openapi.yaml#/components/schemas/ClubeClientsResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "502":
          description: Falha ao consultar o serviço do Clube.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"

  /v2/clube/clients:
    get:
      tags:
        - Clube de Fidelidade
      summary: Listar clientes do Clube de Fidelidade (V2 paginada)
      description: >-
        Retorna uma página de clientes do Clube. Com OAuth, exige o escopo

        `clube:read`; a sessão do restaurante também é aceita. Se o restaurante

        não tem Clube configurado ou não tem uma loja ativa no Clube, retorna uma página vazia com HTTP 200.


        Retorna data e pagination; siga pagination.next mantendo os filtros. A V1 permanece disponível com seu
        contrato anterior.
      operationId: getClubeClientsV1PaginatedV2
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: per_page
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 100
      responses:
        '200':
          description: Página de clientes do Clube.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClubeClientsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          description: Falha ao consultar o serviço do Clube.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'

  /v1/financial/cash-flows:
    get:
      tags: [Financeiro]
      summary: Listar lançamentos financeiros
      description: |
        Replica os lançamentos da Área do Gestor, com pais e itens aninhados,
        totais do período e página fixa de 100. Com OAuth, exige
        `financial:read`; a sessão do restaurante também é aceita.
      operationId: listCashFlowsV1
      parameters:
        - $ref: "#/components/parameters/RestaurantId"
        - name: start_date
          in: query
          required: true
          schema: { type: string, format: date }
        - name: end_date
          in: query
          required: true
          description: Último dia, incluído por inteiro.
          schema: { type: string, format: date }
        - name: date_type
          in: query
          schema:
            type: string
            enum: [due_date, competence_date]
            default: due_date
        - name: offset
          in: query
          schema: { type: integer, minimum: 0, default: 0 }
        - name: paid
          in: query
          schema: { type: boolean }
        - name: is_earning
          in: query
          schema: { type: boolean }
        - name: provider_id
          in: query
          schema: { type: integer, minimum: 1 }
        - name: bank_account_id
          in: query
          schema: { type: integer, minimum: 1 }
        - name: payment_method_id
          in: query
          schema: { type: integer, minimum: 1 }
        - name: category_subcategory_id
          in: query
          schema: { type: integer, minimum: 1 }
      responses:
        "200":
          description: Página de lançamentos e totais do período completo.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CashFlowsResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /v1/financial/cost-centers:
    get:
      tags: [Financeiro]
      summary: Listar centros de custo
      operationId: listFinancialCostCenters
      description: |
        Centros de custo que a loja pode atribuir. O `id` é o `category_subcategory_id`
        dos lançamentos e o `cash_flow_category_subcategory_id` dos insumos.
        Exige `financial:read`; a sessão do restaurante também é aceita.
      security:
        - bearerAuth: []
      x-required-scope: financial:read
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
      responses:
        '200':
          description: Centros de custo da loja.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FinancialCostCenter'
        '401':
          description: Credencial inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ou loja não permitidos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/financial/bank-accounts:
    get:
      tags: [Financeiro]
      summary: Listar contas bancárias
      operationId: listFinancialBankAccounts
      description: Contas bancárias ativas da loja, com saldo. Exige `financial:read`.
      security:
        - bearerAuth: []
      x-required-scope: financial:read
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
      responses:
        '200':
          description: Contas da loja.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FinancialBankAccount'
        '401':
          description: Credencial inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ou loja não permitidos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/financial/payment-methods:
    get:
      tags: [Financeiro]
      summary: Listar formas de pagamento de lançamentos
      operationId: listFinancialPaymentMethods
      description: |
        Formas de pagamento de lançamentos financeiros (`cash_flow_payment_method_id`),
        diferentes das formas de pagamento de pedidos. Exige `financial:read`.
      security:
        - bearerAuth: []
      x-required-scope: financial:read
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
      responses:
        '200':
          description: Formas de pagamento da loja.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FinancialPaymentMethod'
        '401':
          description: Credencial inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ou loja não permitidos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/financial/cash-flows/bulk:
    patch:
      tags: [Financeiro]
      summary: Dar baixa em lançamentos em lote
      operationId: settleCashFlowsBulk
      description: |
        De 1 a 100 lançamentos distintos da mesma loja, aplicados inteiros ou nada.
        Mesmas regras da baixa individual. Exige `financial:write`.
      security:
        - bearerAuth: []
      x-required-scope: financial:write
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CashFlowSettlementBatch'
      responses:
        '200':
          description: Lançamentos na ordem enviada.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required: [items]
                properties:
                  items:
                    description: "Resultados das baixas, na ordem enviada; o lote é aplicado inteiro ou nada."
                    type: array
                    items:
                      $ref: '#/components/schemas/CashFlowSettlementResult'
        '400':
          description: Corpo inválido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Credencial inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ou loja não permitidos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Lançamento, conta ou forma de pagamento de outra loja (`cash_flow_not_found`, `cash_flow_bank_account_not_found`, `cash_flow_payment_method_not_found`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Conciliado com OFX, membro de título ou edição concorrente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: '`paid: true` sem conta bancária (`cash_flow_bank_account_required`) ou loja sem usuário principal para o histórico (`cash_flow_history_user_not_found`).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/financial/cash-flows/{id}:
    patch:
      tags: [Financeiro]
      summary: Dar baixa em um lançamento
      operationId: settleCashFlow
      description: |
        Marca o lançamento como pago ou não pago, com data, conta bancária e forma de
        pagamento, e ajusta o saldo da conta. Trocar a conta de um lançamento pago move
        o movimento entre as contas. Repetir o mesmo pedido não altera nada. Títulos
        propagam o pagamento aos lançamentos agrupados. Exige `financial:write`; a
        sessão do restaurante também é aceita.
      security:
        - bearerAuth: []
      x-required-scope: financial:write
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
        - name: id
          in: path
          required: true
          schema: { type: integer, minimum: 1, maximum: 2147483647 }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CashFlowSettlement'
      responses:
        '200':
          description: Lançamento após a baixa.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashFlowSettlementResult'
        '400':
          description: Corpo inválido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Credencial inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ou loja não permitidos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Lançamento, conta ou forma de pagamento de outra loja.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Conciliado com OFX (`cash_flow_ofx_reconciled`), membro de título (`cash_flow_title_member`) ou edição concorrente (`cash_flow_update_conflict`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: '`paid: true` sem conta bancária (`cash_flow_bank_account_required`) ou loja sem usuário principal para o histórico (`cash_flow_history_user_not_found`).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v2/financial/cash-flows:
    get:
      tags:
        - Financeiro
      summary: Listar lançamentos financeiros (V2 paginada)
      description: >-
        Replica os lançamentos da Área do Gestor, com pais e itens aninhados,

        totais do período e página fixa de 100. Com OAuth, exige

        `financial:read`; a sessão do restaurante também é aceita.


        Retorna data e pagination; siga pagination.next mantendo os filtros. A V1 permanece disponível com seu
        contrato anterior.
      operationId: listCashFlowsV1PaginatedV2
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
        - name: start_date
          in: query
          required: true
          schema:
            type: string
            format: date
        - name: end_date
          in: query
          required: true
          description: Último dia, incluído por inteiro.
          schema:
            type: string
            format: date
        - name: date_type
          in: query
          schema:
            type: string
            enum:
              - due_date
              - competence_date
            default: due_date
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: paid
          in: query
          schema:
            type: boolean
        - name: is_earning
          in: query
          schema:
            type: boolean
        - name: provider_id
          in: query
          schema:
            type: integer
            minimum: 1
        - name: bank_account_id
          in: query
          schema:
            type: integer
            minimum: 1
        - name: payment_method_id
          in: query
          schema:
            type: integer
            minimum: 1
        - name: category_subcategory_id
          in: query
          schema:
            type: integer
            minimum: 1
      responses:
        '200':
          description: Página de lançamentos e totais do período completo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashFlowsResponseV2'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /v1/inputs:
    get:
      tags: [Estoque]
      summary: Listar insumos
      description: |
        Registros não cancelados do restaurante, ordenados por nome e por ID
        em empates. Com OAuth exige `inputs:read`; aceita também a sessão
        do restaurante. Página fixa de 100 registros; não permite escrita.
        Quantidades mantêm o texto e os valores monetários têm duas casas decimais.
        Valores inválidos já armazenados preservam a string NaN do PostgreSQL.
      operationId: getInputsV1
      parameters:
        - $ref: "#/components/parameters/RestaurantId"
        - name: offset
          in: query
          description: Offset legado; ausente, inválido ou negativo vira zero. Prefixos inteiros são aceitos (12abc vira 12). Valores acima de 2147483647 são rejeitados.
          schema: { type: integer, minimum: 0, maximum: 2147483647, default: 0 }
      responses:
        "200":
          description: Página de insumos e contagem total.
          content:
            application/json:
              schema:
                $ref: "./openapi.yaml#/components/schemas/InputsResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /v2/inputs:
    get:
      tags:
        - Estoque
      summary: Listar insumos (V2 paginada)
      description: >-
        Registros não cancelados do restaurante, ordenados por nome e por ID

        em empates. Com OAuth exige `inputs:read`; aceita também a sessão

        do restaurante. Página fixa de 100 registros; não permite escrita.

        Quantidades mantêm o texto e os valores monetários têm duas casas decimais.

        Valores inválidos já armazenados preservam a string NaN do PostgreSQL.


        Retorna data e pagination; siga pagination.next mantendo os filtros. A V1 permanece disponível com seu
        contrato anterior.
      operationId: getInputsV1PaginatedV2
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
        - name: offset
          in: query
          description: >-
            Offset legado; ausente, inválido ou negativo vira zero. Prefixos inteiros são aceitos (12abc vira
            12). Valores acima de 2147483647 são rejeitados.
          schema:
            type: integer
            minimum: 0
            maximum: 2147483647
            default: 0
      responses:
        '200':
          description: Página de insumos e contagem total.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InputsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /v1/intermediaries:
    get:
      tags: [Estoque]
      summary: Listar produtos intermediários
      description: |
        Registros não cancelados do restaurante, ordenados por nome e por ID
        em empates. Com OAuth exige `intermediaries:read`; aceita também a sessão
        do restaurante. Página fixa de 100 registros; não permite escrita.
        Quantidades mantêm o texto e os valores monetários têm duas casas decimais.
        Valores inválidos já armazenados preservam a string NaN do PostgreSQL.
      operationId: getIntermediariesV1
      parameters:
        - $ref: "#/components/parameters/RestaurantId"
        - name: offset
          in: query
          description: Offset legado; ausente, inválido ou negativo vira zero. Prefixos inteiros são aceitos (12abc vira 12). Valores acima de 2147483647 são rejeitados.
          schema: { type: integer, minimum: 0, maximum: 2147483647, default: 0 }
      responses:
        "200":
          description: Página de produtos intermediários e contagem total.
          content:
            application/json:
              schema:
                $ref: "./openapi.yaml#/components/schemas/IntermediariesResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /v2/intermediaries:
    get:
      tags:
        - Estoque
      summary: Listar produtos intermediários (V2 paginada)
      description: >-
        Registros não cancelados do restaurante, ordenados por nome e por ID

        em empates. Com OAuth exige `intermediaries:read`; aceita também a sessão

        do restaurante. Página fixa de 100 registros; não permite escrita.

        Quantidades mantêm o texto e os valores monetários têm duas casas decimais.

        Valores inválidos já armazenados preservam a string NaN do PostgreSQL.


        Retorna data e pagination; siga pagination.next mantendo os filtros. A V1 permanece disponível com seu
        contrato anterior.
      operationId: getIntermediariesV1PaginatedV2
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
        - name: offset
          in: query
          description: >-
            Offset legado; ausente, inválido ou negativo vira zero. Prefixos inteiros são aceitos (12abc vira
            12). Valores acima de 2147483647 são rejeitados.
          schema:
            type: integer
            minimum: 0
            maximum: 2147483647
            default: 0
      responses:
        '200':
          description: Página de produtos intermediários e contagem total.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntermediariesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /v1/brands/{brand_id}/certificate:
    parameters:
      - $ref: '#/components/parameters/RestaurantId'
      - name: brand_id
        in: path
        required: true
        schema: { type: integer, minimum: 1, maximum: 2147483647 }
    get:
      tags: [Marcas]
      summary: Consultar certificado digital A1
      operationId: getBrandCertificateV1
      security:
        - certificateIntegration: []
      description: >-
        Exige certificates:read em access token OAuth ou derivado de chave de API.
        Não aceita sessão humana ou chave bruta. Consulta a Focus pelo CNPJ da marca ativa
        pertencente ao restaurante autorizado. Campos indisponíveis são null; certificate_cnpj
        nunca é inferido do cadastro da marca. Retorna Cache-Control no-store.
      responses:
        '200':
          description: Metadados do certificado.
          headers:
            Cache-Control:
              schema: { type: string, const: no-store }
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandCertificate'
        '400': { description: Identificador inválido ou restaurante não selecionado. }
        '401': { description: Access token inválido. }
        '403': { description: Escopo ou restaurante não autorizado. }
        '404': { description: Marca inexistente, inativa, excluída ou de outro restaurante. }
        '422': { description: Marca sem CNPJ válido ou empresa não cadastrada na Focus. }
        '502': { description: Falha na Focus ou resposta inválida. }
        '503': { description: Integração de certificados não configurada. }
        '504': { description: Timeout da Focus. }
    put:
      tags: [Marcas]
      summary: Renovar certificado digital A1
      operationId: renewBrandCertificateV1
      security:
        - certificateIntegration: []
      description: >-
        Exige certificates:write. Substitui o certificado somente da empresa selecionada,
        sem propagação para matriz e filiais. O CNPJ completo do titular deve coincidir.
        Arquivo e senha não são armazenados pela Takeat. Não há retry automático;
        em timeout consulte o GET antes de reenviar. Não atualiza o cache legado por restaurante.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              additionalProperties: false
              required: [file, password]
              properties:
                file:
                  type: string
                  format: binary
                  description: Um arquivo .pfx ou .p12, até 1048576 bytes.
                password:
                  type: string
                  maxLength: 4096
                  writeOnly: true
                  description: Senha preservada sem remover espaços.
      responses:
        '200':
          description: Atualização confirmada pela Focus.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required: [valid_until]
                properties:
                  valid_until: { description: "Fim da validade do novo certificado (ISO 8601, UTC), confirmado após o envio.", type: string, format: date-time }
        '400': { description: Multipart ou identificador inválido. }
        '401': { description: Access token inválido. }
        '403': { description: Escopo ou restaurante não autorizado. }
        '404': { description: Marca indisponível para este restaurante. }
        '413': { description: Arquivo maior que 1 MiB. }
        '422': { description: Certificado inválido, senha incorreta, CNPJ divergente, vencido, futuro ou recusado pela Focus. }
        '502': { description: Não foi possível confirmar a atualização. Consulte antes de reenviar. }
        '503': { description: Integração não configurada. }
        '504': { description: Resultado incerto por timeout. Consulte antes de reenviar. }

  /v1/brands:
    get:
      tags:
        - Marcas
      summary: Listar marcas do restaurante
      operationId: listBrandsV1
      description: >-
        OAuth exige brands:read; também aceita sessão autenticada de restaurante. Retorna marcas não
        excluídas, ativas ou inativas, ordenadas por padrão primeiro, nome e id. Não expõe credenciais
        fiscais nem cursor de distribuição.
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
      responses:
        '200':
          description: Consulta concluída.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FiscalBrand'
              example:
                - id: 3
                  restaurant_id: 2
                  tax_regime: '1'
                  identity:
                    name: loja-centro
                    fantasy_name: Loja Centro
                    cnpj: '00000000000002'
                  status:
                    active: true
                    default: true
                  image: null
                  timestamps:
                    created_at: '2026-09-03T09:18:56.774Z'
                    updated_at: '2026-09-03T09:18:56.774Z'
        '400':
          description: Parâmetro inválido ou período fora do limite.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Credencial ausente ou inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ausente ou restaurante não autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Limite de requisições excedido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Erro interno com resposta sanitizada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/nfe-received:
    get:
      tags:
        - Fiscal
      summary: Listar NF-e recebidas
      operationId: listReceivedNfesV1
      description: >-
        OAuth exige nfe-received:read; também aceita sessão autenticada de restaurante. Somente notas
        autorizada e sem cancelamento local, por emissão crescente e id. Intervalo máximo de 92 dias.
        Array completo, sem paginação; divida intervalos muito grandes. Não inclui transferências de
        estoque nem solicita manifestação. Valores locais podem diferir da consulta atual do detalhe.
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
        - name: start_date
          in: query
          required: true
          description: >-
            Data/hora ISO com segundos. Sem offset é UTC; aceita Z ou offset explícito. Limites
            inclusivos, sem expansão para início/fim do dia.
          schema:
            type: string
            example: '2026-09-01T03:00:00'
        - name: end_date
          in: query
          required: true
          description: >-
            Data/hora ISO com segundos. Sem offset é UTC; aceita Z ou offset explícito. Limites
            inclusivos, sem expansão para início/fim do dia.
          schema:
            type: string
            example: '2026-09-10T02:59:59'
        - name: pendente
          in: query
          description: >-
            true inclui manifestação null, ciencia ou desconhecimento. false (padrão) inclui somente
            confirmacao. Aceita apenas true/false.
          schema:
            type: boolean
            default: false
        - name: brand_id
          in: query
          description: >-
            Uma marca não excluída do restaurante. Ausente: marca padrão ou primeira por id. Seleção
            da padrão inclui notas sem marca. Se não há marcas e o parâmetro é omitido, não filtra
            marca. Marca inválida/estrangeira retorna 404, sem fallback.
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
      responses:
        '200':
          description: Consulta concluída.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReceivedNfe'
              example:
                - id: 1
                  restaurant_id: 2
                  brand_id: 3
                  brand:
                    id: 3
                    name: loja-centro
                    fantasy_name: Loja Centro
                    cnpj: '00000000000002'
                  identification:
                    access_key: '35260900000000000001550010000000011000000010'
                    number: '000000001'
                    series: null
                    state: null
                    type: '1'
                  issuer:
                    name: Empresa Exemplo
                    document: '00000000000001'
                  amounts:
                    total: '1219.50'
                  status:
                    situation: autorizada
                    complete: true
                  manifestation:
                    type: ciencia
                    manifested_at: null
                  correction:
                    number: null
                    text: null
                    issued_at: null
                  cancellation:
                    canceled_at: null
                    reason: null
                    locally_canceled_at: null
                  references:
                    return_reference: null
                    reference: null
                    url: null
                    provider_id: null
                  fiscal:
                    version: 1
                    digest: LGbQYJE1bnc2MjY6i6zsxVlhhXI=
                    sped: null
                  timestamps:
                    issued_at: '2026-09-02T16:45:21.000Z'
                    processing_at: null
                    created_at: '2026-09-03T09:18:56.774Z'
                    updated_at: '2026-09-03T09:18:56.774Z'
        '400':
          description: Parâmetro inválido ou período fora do limite.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Credencial ausente ou inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ausente ou restaurante não autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: NF-e ou marca não encontrada no restaurante.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Limite de requisições excedido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Erro interno com resposta sanitizada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/nfe-received/info/{nfe_received_id}:
    get:
      tags:
        - Fiscal
      summary: Consultar detalhe de NF-e recebida
      operationId: getReceivedNfeV1
      description: >-
        OAuth exige nfe-received:read; também aceita sessão autenticada de restaurante. Consulta a
        Focus no servidor usando a marca vinculada ou padrão quando a nota não possui marca. Não
        modifica a nota nem manifesta. Usa timeout de 15 segundos e resposta máxima de 5 MiB. Nota
        resumida pode retornar invoice/protocol null. Campos locais de correção, cancelamento e
        referências continuam sendo snapshots locais. Erros do provedor não são expostos.
      parameters:
        - $ref: '#/components/parameters/RestaurantId'
        - name: nfe_received_id
          in: path
          required: true
          description: ID Takeat obtido na listagem, não a chave de acesso.
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
      responses:
        '200':
          description: Consulta concluída.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceivedNfeDetail'
              example:
                id: 1
                restaurant_id: 2
                brand_id: 3
                brand:
                  id: 3
                  name: loja-centro
                  fantasy_name: Loja Centro
                  cnpj: '00000000000002'
                identification:
                  access_key: '35260900000000000001550010000000011000000010'
                  number: '000000001'
                  series: null
                  state: null
                  type: '1'
                issuer:
                  name: Empresa Exemplo
                  document: '00000000000001'
                amounts:
                  total: '1219.50'
                status:
                  situation: autorizada
                  complete: true
                manifestation:
                  type: confirmacao
                  manifested_at: null
                correction:
                  number: null
                  text: null
                  issued_at: null
                cancellation:
                  canceled_at: null
                  reason: null
                  locally_canceled_at: null
                references:
                  return_reference: null
                  reference: null
                  url: null
                  provider_id: 4
                fiscal:
                  version: 6250
                  digest: LGbQYJE1bnc2MjY6i6zsxVlhhXI=
                  sped: null
                timestamps:
                  issued_at: '2026-09-02T13:45:21-03:00'
                  processing_at: null
                  created_at: '2026-09-03T09:18:56.774Z'
                  updated_at: '2026-09-03T09:18:56.774Z'
                recipient:
                  cnpj: '00000000000002'
                  cpf: ''
                invoice:
                  identification:
                    versao: '4.00'
                    chave_nfe: NFe35260900000000000001550010000000011000000010
                    uf: '31'
                    codigo_unico: '67846522'
                    natureza_operacao: VENDA FORA ESTADO
                    modelo: '55'
                    serie: '1'
                    numero: '289191'
                    data_emissao: '2026-09-02T13:45:21-03:00'
                    data_entrada_saida: '2026-09-02T13:45:21-03:00'
                    tipo_documento: '1'
                    local_destino: '2'
                    municipio: '3144003'
                    formato_impressao: '1'
                    forma_emissao: '1'
                    digito_verificador: '6'
                    ambiente: '1'
                    finalidade_emissao: '1'
                    consumidor_final: '0'
                    presenca_comprador: '9'
                    indicador_intermediario: '0'
                    processo_emissao: '0'
                    versao_aplicativo: MagisTI_22.08 A
                  references:
                    notas_referenciadas: []
                    chaves_acesso_dfe_anteriores: []
                    chaves_nfe_antecipacao_pagamento: []
                  issuer:
                    cnpj_emitente: '00000000000001'
                    nome_emitente: Empresa Exemplo
                    logradouro_emitente: Exemplo
                    numero_emitente: SN
                    complemento_emitente: INDUSTRIA
                    bairro_emitente: Exemplo
                    codigo_municipio_emitente: '3144003'
                    municipio_emitente: MUTUM
                    uf_emitente: MG
                    cep_emitente: '00000'
                    codigo_pais_emitente: '1058'
                    pais_emitente: BRASIL
                    telefone_emitente: '1100000000'
                    inscricao_estadual_emitente: '00000'
                    inscricao_municipal_emitente: '00000'
                    cnae_fiscal_emitente: '1052000'
                    regime_tributario_emitente: '3'
                  recipient:
                    cnpj_destinatario: '00000000000002'
                    nome_destinatario: Empresa Exemplo
                    logradouro_destinatario: Exemplo
                    numero_destinatario: '5'
                    bairro_destinatario: Exemplo
                    codigo_municipio_destinatario: '3202405'
                    municipio_destinatario: GUARAPARI
                    uf_destinatario: ES
                    cep_destinatario: '00000'
                    codigo_pais_destinatario: '1058'
                    pais_destinatario: BRASIL
                    telefone_destinatario: '1100000000'
                    indicador_inscricao_estadual_destinatario: '1'
                    inscricao_estadual_destinatario: '00000'
                    email_destinatario: fiscal@example.test
                  authorized_parties:
                    pessoas_autorizadas:
                      - cnpj: '00000000000001'
                      - cnpj: '00000000000001'
                  taxes:
                    icms_base_calculo: '1219.50'
                    icms_valor_total: '85.37'
                    icms_valor_total_desonerado: '0.00'
                    fcp_valor_total: '0.00'
                    icms_base_calculo_st: '0.00'
                    icms_valor_total_st: '0.00'
                    fcp_valor_total_st: '0.00'
                    fcp_valor_total_retido_st: '0.00'
                    ibs_cbs_base_calculo: '1134.13'
                    ibs_cbs_is_valor_total: '1219.50'
                  totals:
                    valor_produtos: '1219.50'
                    valor_frete: '0.00'
                    valor_seguro: '0.00'
                    valor_desconto: '0.00'
                    valor_total_ii: '0.00'
                    valor_ipi: '0.00'
                    valor_ipi_devolvido: '0.00'
                    valor_pis: '0.00'
                    valor_cofins: '0.00'
                    valor_outras_despesas: '0.00'
                    valor_total: '1219.50'
                  transport:
                    modalidade_frete: '0'
                    cnpj_transportador: '00000000000001'
                    nome_transportador: Empresa Exemplo
                    inscricao_estadual_transportador: '00000'
                    endereco_transportador: Exemplo
                    municipio_transportador: MUTUM
                    uf_transportador: MG
                    reboques: []
                    volumes:
                      - quantidade: '2'
                        especie: Caixas
                        marca: IVECO
                        peso_liquido: '33.950'
                        peso_bruto: '34.340'
                        lacres: []
                  billing:
                    duplicatas: []
                    formas_pagamento:
                      - forma_pagamento: '99'
                        descricao_pagamento: OUTROS
                        valor_pagamento: '1219.50'
                        tipo_integracao: null
                  additional:
                    informacoes_adicionais_contribuinte: Documento de exemplo para testes.
                    observacoes_contribuinte: []
                    observacoes_fisco: []
                    processos_referenciados: []
                    cana_fornecimentos: []
                    cana_deducoes: []
                    agropecuario_defensivo: []
                  technical_contact:
                    cnpj_responsavel_tecnico: '00000000000001'
                    contato_responsavel_tecnico: Empresa Exemplo
                    email_responsavel_tecnico: fiscal@example.test
                    telefone_responsavel_tecnico: '1100000000'
                  additional_fields: {}
                  items:
                    - identification:
                        numero_item: '1'
                        codigo_produto: '1'
                        descricao: QUEIJO MUSSARELA MUTUMILK 3,500 KG - Cx. 1
                        codigo_ncm: '04061010'
                        nves: []
                        cest: '1702401'
                        cfop: '6101'
                      commercial:
                        codigo_barras_comercial: '97898963913019'
                        unidade_comercial: KG
                        quantidade_comercial: '27.9500'
                        valor_unitario_comercial: '38.0500000000'
                      taxes:
                        infos_credito_presumido: []
                        ipi_codigo_enquadramento_legal: '999'
                        icms_percentual_partilha: '100.0000'
                        ibs_cbs_situacao_tributaria: '200'
                        ibs_cbs_classificacao_tributaria: '200003'
                        ibs_cbs_base_calculo: '989.05'
                        ibs_uf_aliquota: '0.1000'
                        ibs_uf_percentual_reducao_aliquota: '100.0000'
                        ibs_uf_aliquota_efetiva: '0.0000'
                        ibs_uf_valor: '0.00'
                        ibs_mun_aliquota: '0.0000'
                        ibs_mun_percentual_reducao_aliquota: '100.0000'
                        ibs_mun_aliquota_efetiva: '0.0000'
                        ibs_mun_valor: '0.00'
                        ibs_valor_total: '0.0'
                        cbs_aliquota: '0.9000'
                        cbs_percentual_reducao_aliquota: '100.0000'
                        cbs_aliquota_efetiva: '0.0000'
                        cbs_valor: '0.00'
                        icms_origem: '0'
                        icms_situacao_tributaria: '00'
                        icms_modalidade_base_calculo: '3'
                        icms_base_calculo: '1063.50'
                        icms_aliquota: '7.0000'
                        icms_valor: '74.45'
                        ipi_situacao_tributaria: '51'
                        pis_situacao_tributaria: '06'
                        cofins_situacao_tributaria: '06'
                      amounts:
                        valor_bruto: '1063.50'
                        inclui_no_total: '1'
                        valor_total_item: '1063.50'
                      taxable:
                        codigo_barras_tributavel: '7898963913016'
                        unidade_tributavel: KG
                        quantidade_tributavel: '27.9500'
                        valor_unitario_tributavel: '38.0500000000'
                      additional:
                        documentos_importacao: []
                        detalhes_exportacao: []
                        rastros: []
                        armamentos: []
                        origens_combustivel: []
                        observacoes_contribuinte: []
                      additional_fields: {}
                    - identification:
                        numero_item: '2'
                        codigo_produto: '1627'
                        descricao: REQUEIJAO MUTUMILK PREMIUM BS 1500GR - Cx. 1
                        codigo_ncm: '04061090'
                        nves: []
                        cest: '1702301'
                        cfop: '6101'
                      commercial:
                        codigo_barras_comercial: '17898963913143'
                        unidade_comercial: UN
                        quantidade_comercial: '4.0000'
                        valor_unitario_comercial: '39.0000000000'
                      taxes:
                        infos_credito_presumido: []
                        ipi_codigo_enquadramento_legal: '999'
                        icms_percentual_partilha: '100.0000'
                        ibs_cbs_situacao_tributaria: '200'
                        ibs_cbs_classificacao_tributaria: '200003'
                        ibs_cbs_base_calculo: '145.08'
                        ibs_uf_aliquota: '0.1000'
                        ibs_uf_percentual_reducao_aliquota: '100.0000'
                        ibs_uf_aliquota_efetiva: '0.0000'
                        ibs_uf_valor: '0.00'
                        ibs_mun_aliquota: '0.0000'
                        ibs_mun_percentual_reducao_aliquota: '100.0000'
                        ibs_mun_aliquota_efetiva: '0.0000'
                        ibs_mun_valor: '0.00'
                        ibs_valor_total: '0.0'
                        cbs_aliquota: '0.9000'
                        cbs_percentual_reducao_aliquota: '100.0000'
                        cbs_aliquota_efetiva: '0.0000'
                        cbs_valor: '0.00'
                        icms_origem: '0'
                        icms_situacao_tributaria: '00'
                        icms_modalidade_base_calculo: '3'
                        icms_base_calculo: '156.00'
                        icms_aliquota: '7.0000'
                        icms_valor: '10.92'
                        ipi_situacao_tributaria: '51'
                        pis_situacao_tributaria: '06'
                        cofins_situacao_tributaria: '06'
                      amounts:
                        valor_bruto: '156.00'
                        inclui_no_total: '1'
                        valor_total_item: '156.00'
                      taxable:
                        codigo_barras_tributavel: '7898963913146'
                        unidade_tributavel: UN
                        quantidade_tributavel: '4.0000'
                        valor_unitario_tributavel: '39.0000000000'
                      additional:
                        documentos_importacao: []
                        detalhes_exportacao: []
                        rastros: []
                        armamentos: []
                        origens_combustivel: []
                        observacoes_contribuinte: []
                      additional_fields: {}
                protocol:
                  versao: '4.00'
                  ambiente: '1'
                  versao_aplicativo: J-3.4.32
                  chave_nfe: '35260900000000000001550010000000011000000010'
                  data_recebimento: '2026-09-02T13:44:48-03:00'
                  numero_protocolo: '131267873443386'
                  digest_value: LGbQYJE1bnc2MjY6i6zsxVlhhXI=
                  status: '100'
                  motivo: Autorizado o uso da NF-e
                processing:
                  return_in_progress: false
        '400':
          description: Parâmetro inválido ou período fora do limite.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Credencial ausente ou inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Escopo ausente ou restaurante não autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: NF-e ou marca não encontrada no restaurante.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Limite de requisições excedido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Erro interno com resposta sanitizada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '502':
          description: Consulta fiscal indisponível, inválida ou excedeu 15 segundos; resposta sanitizada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: Integração fiscal da marca não configurada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'

  /v1/waiter/me:
    get:
      tags:
        - Garçom · Perfil
      operationId: waiter-get-me
      summary: Consultar meu perfil
      description: >-
        Exige autorização OAuth pessoal de garçom. A loja vem da concessão; não envie restaurante, identidade
        alternativa ou corpo. Retorna apenas campos públicos aprovados, sem dados pessoais dos clientes,
        observações livres, chaves de sessão, dados de pagamentos ou configuração de terminais.
      x-authorization-profile: waiter
      x-mutates: false
      x-required-scope: waiter:profile:read
      security:
        - waiterOAuth: []
      responses:
        '200':
          description: Consulta concluída
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WaiterProfile'
        '400':
          description: Parâmetro não permitido, ID inválido ou corpo enviado em uma consulta.
        '401':
          description: Token inválido, concessão revogada ou vínculo de garçom indisponível.
        '403':
          description: Perfil ou permissão incompatível.
        '404':
          description: Recurso ausente, de outra loja ou fora do atendimento ativo.
        '429':
          description: Limite de chamadas atingido.
        '502':
          description: Dados de atendimento indisponíveis.
        '503':
          description: Não foi possível verificar a autorização ou a integração está indisponível.
  /v1/waiter/menu:
    get:
      tags:
        - Garçom · Cardápio
      operationId: waiter-get-menu
      summary: Consultar cardápio publicado
      description: >-
        Exige autorização OAuth pessoal de garçom. A loja vem da concessão; não envie restaurante, identidade
        alternativa ou corpo. Retorna apenas campos públicos aprovados, sem dados pessoais dos clientes,
        observações livres, chaves de sessão, dados de pagamentos ou configuração de terminais. Canal
        presencial, somente itens disponíveis, escolhas incluídas e dados fiscais desabilitados.
      x-authorization-profile: waiter
      x-mutates: false
      x-required-scope: waiter:menu:read
      security:
        - waiterOAuth: []
      parameters:
        - name: brand_id
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
          description: Marca ativa da loja autorizada.
      responses:
        '200':
          description: Consulta concluída
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MenuResponse'
        '400':
          description: Parâmetro não permitido, ID inválido ou corpo enviado em uma consulta.
        '401':
          description: Token inválido, concessão revogada ou vínculo de garçom indisponível.
        '403':
          description: Perfil ou permissão incompatível.
        '404':
          description: Recurso ausente, de outra loja ou fora do atendimento ativo.
        '429':
          description: Limite de chamadas atingido.
        '502':
          description: Dados de atendimento indisponíveis.
        '503':
          description: Não foi possível verificar a autorização ou a integração está indisponível.
  /v1/waiter/brands:
    get:
      tags:
        - Garçom · Cardápio
      operationId: waiter-get-brands
      summary: Listar marcas ativas
      description: >-
        Exige autorização OAuth pessoal de garçom. A loja vem da concessão; não envie restaurante, identidade
        alternativa ou corpo. Retorna apenas campos públicos aprovados, sem dados pessoais dos clientes,
        observações livres, chaves de sessão, dados de pagamentos ou configuração de terminais.
      x-authorization-profile: waiter
      x-mutates: false
      x-required-scope: waiter:menu:read
      security:
        - waiterOAuth: []
      parameters:
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
            maximum: 9999999
          description: Deslocamento na lista ordenada por ID; páginas fixas de 100 itens.
      responses:
        '200':
          description: Consulta concluída
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WaiterBrandPage'
        '400':
          description: Parâmetro não permitido, ID inválido ou corpo enviado em uma consulta.
        '401':
          description: Token inválido, concessão revogada ou vínculo de garçom indisponível.
        '403':
          description: Perfil ou permissão incompatível.
        '404':
          description: Recurso ausente, de outra loja ou fora do atendimento ativo.
        '429':
          description: Limite de chamadas atingido.
        '502':
          description: Dados de atendimento indisponíveis.
        '503':
          description: Não foi possível verificar a autorização ou a integração está indisponível.
  /v2/waiter/brands:
    get:
      tags:
        - Garçom · Cardápio
      operationId: waiter-get-brandsPaginatedV2
      summary: Listar marcas ativas (V2 paginada)
      description: >-
        Exige autorização OAuth pessoal de garçom. A loja vem da concessão; não envie restaurante, identidade
        alternativa ou corpo. Retorna apenas campos públicos aprovados, sem dados pessoais dos clientes,
        observações livres, chaves de sessão, dados de pagamentos ou configuração de terminais.

        Retorna data e pagination; siga pagination.next mantendo os filtros. A V1 permanece disponível com seu
        contrato anterior.
      x-authorization-profile: waiter
      x-mutates: false
      x-required-scope: waiter:menu:read
      security:
        - waiterOAuth: []
      parameters:
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
            maximum: 9999999
          description: Deslocamento na lista ordenada por ID; páginas fixas de 100 itens.
      responses:
        '200':
          description: Consulta concluída
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WaiterBrandPageV2'
        '400':
          description: Parâmetro não permitido, ID inválido ou corpo enviado em uma consulta.
        '401':
          description: Token inválido, concessão revogada ou vínculo de garçom indisponível.
        '403':
          description: Perfil ou permissão incompatível.
        '404':
          description: Recurso ausente, de outra loja ou fora do atendimento ativo.
        '429':
          description: Limite de chamadas atingido.
        '502':
          description: Dados de atendimento indisponíveis.
        '503':
          description: Não foi possível verificar a autorização ou a integração está indisponível.

  /v1/waiter/tables:
    get:
      tags:
        - Garçom · Mesas
      operationId: waiter-get-tables
      summary: Listar mesas
      description: >-
        Exige autorização OAuth pessoal de garçom. A loja vem da concessão; não envie restaurante, identidade
        alternativa ou corpo. Retorna apenas campos públicos aprovados, sem dados pessoais dos clientes,
        observações livres, chaves de sessão, dados de pagamentos ou configuração de terminais.
      x-authorization-profile: waiter
      x-mutates: false
      x-required-scope: waiter:tables:read
      security:
        - waiterOAuth: []
      parameters:
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
            maximum: 9999999
          description: Deslocamento na lista ordenada por ID; páginas fixas de 100 itens.
      responses:
        '200':
          description: Consulta concluída
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WaiterTablePage'
        '400':
          description: Parâmetro não permitido, ID inválido ou corpo enviado em uma consulta.
        '401':
          description: Token inválido, concessão revogada ou vínculo de garçom indisponível.
        '403':
          description: Perfil ou permissão incompatível.
        '404':
          description: Recurso ausente, de outra loja ou fora do atendimento ativo.
        '429':
          description: Limite de chamadas atingido.
        '502':
          description: Dados de atendimento indisponíveis.
        '503':
          description: Não foi possível verificar a autorização ou a integração está indisponível.
  /v2/waiter/tables:
    get:
      tags:
        - Garçom · Mesas
      operationId: waiter-get-tablesPaginatedV2
      summary: Listar mesas (V2 paginada)
      description: >-
        Exige autorização OAuth pessoal de garçom. A loja vem da concessão; não envie restaurante, identidade
        alternativa ou corpo. Retorna apenas campos públicos aprovados, sem dados pessoais dos clientes,
        observações livres, chaves de sessão, dados de pagamentos ou configuração de terminais.

        Retorna data e pagination; siga pagination.next mantendo os filtros. A V1 permanece disponível com seu
        contrato anterior.
      x-authorization-profile: waiter
      x-mutates: false
      x-required-scope: waiter:tables:read
      security:
        - waiterOAuth: []
      parameters:
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
            maximum: 9999999
          description: Deslocamento na lista ordenada por ID; páginas fixas de 100 itens.
      responses:
        '200':
          description: Consulta concluída
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WaiterTablePageV2'
        '400':
          description: Parâmetro não permitido, ID inválido ou corpo enviado em uma consulta.
        '401':
          description: Token inválido, concessão revogada ou vínculo de garçom indisponível.
        '403':
          description: Perfil ou permissão incompatível.
        '404':
          description: Recurso ausente, de outra loja ou fora do atendimento ativo.
        '429':
          description: Limite de chamadas atingido.
        '502':
          description: Dados de atendimento indisponíveis.
        '503':
          description: Não foi possível verificar a autorização ou a integração está indisponível.

  /v1/waiter/table-sessions:
    get:
      tags:
        - Garçom · Comandas
      operationId: waiter-get-table-sessions
      summary: Listar comandas ativas
      description: >-
        Exige autorização OAuth pessoal de garçom. A loja vem da concessão; não envie restaurante, identidade
        alternativa ou corpo. Retorna apenas campos públicos aprovados, sem dados pessoais dos clientes,
        observações livres, chaves de sessão, dados de pagamentos ou configuração de terminais. Limitado ao
        atendimento presencial ativo na loja; não é um histórico de vendas.
      x-authorization-profile: waiter
      x-mutates: false
      x-required-scope: waiter:sessions:read
      security:
        - waiterOAuth: []
      parameters:
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
            maximum: 9999999
          description: Deslocamento na lista ordenada por ID; páginas fixas de 100 itens.
      responses:
        '200':
          description: Consulta concluída
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WaiterSessionPage'
        '400':
          description: Parâmetro não permitido, ID inválido ou corpo enviado em uma consulta.
        '401':
          description: Token inválido, concessão revogada ou vínculo de garçom indisponível.
        '403':
          description: Perfil ou permissão incompatível.
        '404':
          description: Recurso ausente, de outra loja ou fora do atendimento ativo.
        '429':
          description: Limite de chamadas atingido.
        '502':
          description: Dados de atendimento indisponíveis.
        '503':
          description: Não foi possível verificar a autorização ou a integração está indisponível.
  /v2/waiter/table-sessions:
    get:
      tags:
        - Garçom · Comandas
      operationId: waiter-get-table-sessionsPaginatedV2
      summary: Listar comandas ativas (V2 paginada)
      description: >-
        Exige autorização OAuth pessoal de garçom. A loja vem da concessão; não envie restaurante, identidade
        alternativa ou corpo. Retorna apenas campos públicos aprovados, sem dados pessoais dos clientes,
        observações livres, chaves de sessão, dados de pagamentos ou configuração de terminais. Limitado ao
        atendimento presencial ativo na loja; não é um histórico de vendas.

        Retorna data e pagination; siga pagination.next mantendo os filtros. A V1 permanece disponível com seu
        contrato anterior.
      x-authorization-profile: waiter
      x-mutates: false
      x-required-scope: waiter:sessions:read
      security:
        - waiterOAuth: []
      parameters:
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
            maximum: 9999999
          description: Deslocamento na lista ordenada por ID; páginas fixas de 100 itens.
      responses:
        '200':
          description: Consulta concluída
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WaiterSessionPageV2'
        '400':
          description: Parâmetro não permitido, ID inválido ou corpo enviado em uma consulta.
        '401':
          description: Token inválido, concessão revogada ou vínculo de garçom indisponível.
        '403':
          description: Perfil ou permissão incompatível.
        '404':
          description: Recurso ausente, de outra loja ou fora do atendimento ativo.
        '429':
          description: Limite de chamadas atingido.
        '502':
          description: Dados de atendimento indisponíveis.
        '503':
          description: Não foi possível verificar a autorização ou a integração está indisponível.

  /v1/waiter/table-sessions/{sessionId}:
    get:
      tags:
        - Garçom · Comandas
      operationId: waiter-get-table-session
      summary: Consultar comanda ativa
      description: >-
        Exige autorização OAuth pessoal de garçom. A loja vem da concessão; não envie restaurante, identidade
        alternativa ou corpo. Retorna apenas campos públicos aprovados, sem dados pessoais dos clientes,
        observações livres, chaves de sessão, dados de pagamentos ou configuração de terminais. Limitado ao
        atendimento presencial ativo na loja; não é um histórico de vendas.
      x-authorization-profile: waiter
      x-mutates: false
      x-required-scope: waiter:sessions:read
      security:
        - waiterOAuth: []
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
          description: ID positivo de um recurso elegível na loja do garçom.
      responses:
        '200':
          description: Consulta concluída
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WaiterSessionDetail'
        '400':
          description: Parâmetro não permitido, ID inválido ou corpo enviado em uma consulta.
        '401':
          description: Token inválido, concessão revogada ou vínculo de garçom indisponível.
        '403':
          description: Perfil ou permissão incompatível.
        '404':
          description: Recurso ausente, de outra loja ou fora do atendimento ativo.
        '429':
          description: Limite de chamadas atingido.
        '502':
          description: Dados de atendimento indisponíveis.
        '503':
          description: Não foi possível verificar a autorização ou a integração está indisponível.
  /v1/waiter/orders:
    get:
      tags:
        - Garçom · Pedidos
      operationId: waiter-get-orders
      summary: Listar pedidos ativos
      description: >-
        Exige autorização OAuth pessoal de garçom. A loja vem da concessão; não envie restaurante, identidade
        alternativa ou corpo. Retorna apenas campos públicos aprovados, sem dados pessoais dos clientes,
        observações livres, chaves de sessão, dados de pagamentos ou configuração de terminais. Limitado ao
        atendimento presencial ativo na loja; não é um histórico de vendas. A lista considera os pedidos das
        últimas 48 horas que continuam ativos.
      x-authorization-profile: waiter
      x-mutates: false
      x-required-scope: waiter:orders:read
      security:
        - waiterOAuth: []
      parameters:
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
            maximum: 9999999
          description: Deslocamento na lista ordenada por ID; páginas fixas de 100 itens.
      responses:
        '200':
          description: Consulta concluída
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WaiterOrderPage'
        '400':
          description: Parâmetro não permitido, ID inválido ou corpo enviado em uma consulta.
        '401':
          description: Token inválido, concessão revogada ou vínculo de garçom indisponível.
        '403':
          description: Perfil ou permissão incompatível.
        '404':
          description: Recurso ausente, de outra loja ou fora do atendimento ativo.
        '429':
          description: Limite de chamadas atingido.
        '502':
          description: Dados de atendimento indisponíveis.
        '503':
          description: Não foi possível verificar a autorização ou a integração está indisponível.
  /v2/waiter/orders:
    get:
      tags:
        - Garçom · Pedidos
      operationId: waiter-get-ordersPaginatedV2
      summary: Listar pedidos ativos (V2 paginada)
      description: >-
        Exige autorização OAuth pessoal de garçom. A loja vem da concessão; não envie restaurante, identidade
        alternativa ou corpo. Retorna apenas campos públicos aprovados, sem dados pessoais dos clientes,
        observações livres, chaves de sessão, dados de pagamentos ou configuração de terminais. Limitado ao
        atendimento presencial ativo na loja; não é um histórico de vendas. A lista considera os pedidos das
        últimas 48 horas que continuam ativos.

        Retorna data e pagination; siga pagination.next mantendo os filtros. A V1 permanece disponível com seu
        contrato anterior.
      x-authorization-profile: waiter
      x-mutates: false
      x-required-scope: waiter:orders:read
      security:
        - waiterOAuth: []
      parameters:
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
            maximum: 9999999
          description: Deslocamento na lista ordenada por ID; páginas fixas de 100 itens.
      responses:
        '200':
          description: Consulta concluída
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WaiterOrderPageV2'
        '400':
          description: Parâmetro não permitido, ID inválido ou corpo enviado em uma consulta.
        '401':
          description: Token inválido, concessão revogada ou vínculo de garçom indisponível.
        '403':
          description: Perfil ou permissão incompatível.
        '404':
          description: Recurso ausente, de outra loja ou fora do atendimento ativo.
        '429':
          description: Limite de chamadas atingido.
        '502':
          description: Dados de atendimento indisponíveis.
        '503':
          description: Não foi possível verificar a autorização ou a integração está indisponível.

  /v1/waiter/order-baskets/{orderBasketId}:
    get:
      tags:
        - Garçom · Pedidos
      operationId: waiter-get-order-basket
      summary: Consultar itens de um pedido
      description: >-
        Exige autorização OAuth pessoal de garçom. A loja vem da concessão; não envie restaurante, identidade
        alternativa ou corpo. Retorna apenas campos públicos aprovados, sem dados pessoais dos clientes,
        observações livres, chaves de sessão, dados de pagamentos ou configuração de terminais. Limitado ao
        atendimento presencial ativo na loja; não é um histórico de vendas.
      x-authorization-profile: waiter
      x-mutates: false
      x-required-scope: waiter:orders:read
      security:
        - waiterOAuth: []
      parameters:
        - name: orderBasketId
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
          description: ID positivo de um recurso elegível na loja do garçom.
      responses:
        '200':
          description: Consulta concluída
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WaiterBasketItems'
        '400':
          description: Parâmetro não permitido, ID inválido ou corpo enviado em uma consulta.
        '401':
          description: Token inválido, concessão revogada ou vínculo de garçom indisponível.
        '403':
          description: Perfil ou permissão incompatível.
        '404':
          description: Recurso ausente, de outra loja ou fora do atendimento ativo.
        '429':
          description: Limite de chamadas atingido.
        '502':
          description: Dados de atendimento indisponíveis.
        '503':
          description: Não foi possível verificar a autorização ou a integração está indisponível.

  /v1/inventory/inputs/{id}/counts:
    post:
      tags: [Estoque]
      operationId: registerInputCount
      summary: Registrar contagem de inputs
      description: >-
        Altera o saldo real e registra o ajuste no histórico. Requer access token de integração com inputs:stock:write;
        sessões humanas e chaves tk_ diretas não são aceitas. Consulte stock_version antes da contagem.
        HTTP 409 exige nova leitura e revisão humana da contagem; não reenvie automaticamente.
        Mesmo pedido e Idempotency-Key retornam o resultado original, inclusive entre HTTP e MCP.
        counted_at é auditoria, sem reconstrução retroativa. Cadastros master e multiloja são recusados.
        Lotes são atômicos, com 1 a 100 IDs distintos. Disponibilidade depende da implantação da migration e API ESTR-1112.
      security:
      - inventoryIntegration: []
      x-required-scope: inputs:stock:write
      parameters:
      - $ref: '#/components/parameters/RestaurantId'
      - name: Idempotency-Key
        in: header
        required: true
        schema: { type: string, minLength: 1, maxLength: 200, pattern: '^[!-~]+$' }
      - name: id
        in: path
        required: true
        schema: { type: integer, minimum: 1, maximum: 2147483647 }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventoryCountRequest'
      responses:
        '201':
          description: Contagem aplicada ou resultado original de reenvio idêntico.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryCountResponse'
        '400':
          description: Payload ou chave inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Access token inválido ou sessão humana.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Permissão ou restaurante não autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Item não encontrado na loja autorizada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: inventory_update_conflict, inventory_idempotency_conflict ou inventory_managed_record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'

  /v1/inventory/inputs/counts/bulk:
    post:
      tags: [Estoque]
      operationId: registerInputCounts
      summary: Registrar contagem de inputs em lote
      description: >-
        Altera o saldo real e registra o ajuste no histórico. Requer access token de integração com inputs:stock:write;
        sessões humanas e chaves tk_ diretas não são aceitas. Consulte stock_version antes da contagem.
        HTTP 409 exige nova leitura e revisão humana da contagem; não reenvie automaticamente.
        Mesmo pedido e Idempotency-Key retornam o resultado original, inclusive entre HTTP e MCP.
        counted_at é auditoria, sem reconstrução retroativa. Cadastros master e multiloja são recusados.
        Lotes são atômicos, com 1 a 100 IDs distintos. Disponibilidade depende da implantação da migration e API ESTR-1112.
      security:
      - inventoryIntegration: []
      x-required-scope: inputs:stock:write
      parameters:
      - $ref: '#/components/parameters/RestaurantId'
      - name: Idempotency-Key
        in: header
        required: true
        schema: { type: string, minLength: 1, maxLength: 200, pattern: '^[!-~]+$' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventoryCountBatchRequest'
      responses:
        '201':
          description: Contagem aplicada ou resultado original de reenvio idêntico.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryCountBatchResponse'
        '400':
          description: Payload ou chave inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Access token inválido ou sessão humana.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Permissão ou restaurante não autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Item não encontrado na loja autorizada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: inventory_update_conflict, inventory_idempotency_conflict ou inventory_managed_record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'

  /v1/inventory/intermediaries/{id}/counts:
    post:
      tags: [Estoque]
      operationId: registerIntermediaryCount
      summary: Registrar contagem de intermediaries
      description: >-
        Altera o saldo real e registra o ajuste no histórico. Requer access token de integração com intermediaries:stock:write;
        sessões humanas e chaves tk_ diretas não são aceitas. Consulte stock_version antes da contagem.
        HTTP 409 exige nova leitura e revisão humana da contagem; não reenvie automaticamente.
        Mesmo pedido e Idempotency-Key retornam o resultado original, inclusive entre HTTP e MCP.
        counted_at é auditoria, sem reconstrução retroativa. Cadastros master e multiloja são recusados.
        Lotes são atômicos, com 1 a 100 IDs distintos. Disponibilidade depende da implantação da migration e API ESTR-1112.
      security:
      - inventoryIntegration: []
      x-required-scope: intermediaries:stock:write
      parameters:
      - $ref: '#/components/parameters/RestaurantId'
      - name: Idempotency-Key
        in: header
        required: true
        schema: { type: string, minLength: 1, maxLength: 200, pattern: '^[!-~]+$' }
      - name: id
        in: path
        required: true
        schema: { type: integer, minimum: 1, maximum: 2147483647 }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventoryCountRequest'
      responses:
        '201':
          description: Contagem aplicada ou resultado original de reenvio idêntico.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryCountResponse'
        '400':
          description: Payload ou chave inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Access token inválido ou sessão humana.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Permissão ou restaurante não autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Item não encontrado na loja autorizada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: inventory_update_conflict, inventory_idempotency_conflict ou inventory_managed_record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'

  /v1/inventory/intermediaries/counts/bulk:
    post:
      tags: [Estoque]
      operationId: registerIntermediaryCounts
      summary: Registrar contagem de intermediaries em lote
      description: >-
        Altera o saldo real e registra o ajuste no histórico. Requer access token de integração com intermediaries:stock:write;
        sessões humanas e chaves tk_ diretas não são aceitas. Consulte stock_version antes da contagem.
        HTTP 409 exige nova leitura e revisão humana da contagem; não reenvie automaticamente.
        Mesmo pedido e Idempotency-Key retornam o resultado original, inclusive entre HTTP e MCP.
        counted_at é auditoria, sem reconstrução retroativa. Cadastros master e multiloja são recusados.
        Lotes são atômicos, com 1 a 100 IDs distintos. Disponibilidade depende da implantação da migration e API ESTR-1112.
      security:
      - inventoryIntegration: []
      x-required-scope: intermediaries:stock:write
      parameters:
      - $ref: '#/components/parameters/RestaurantId'
      - name: Idempotency-Key
        in: header
        required: true
        schema: { type: string, minLength: 1, maxLength: 200, pattern: '^[!-~]+$' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventoryCountBatchRequest'
      responses:
        '201':
          description: Contagem aplicada ou resultado original de reenvio idêntico.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryCountBatchResponse'
        '400':
          description: Payload ou chave inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Access token inválido ou sessão humana.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Permissão ou restaurante não autorizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Item não encontrado na loja autorizada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: inventory_update_conflict, inventory_idempotency_conflict ou inventory_managed_record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'

components:
  examples:
    LojasIfoodVinculadas:
      summary: Loja vinculada ao restaurante autorizado
      value:
        - ifood_restaurant_id: 10
          ifood_merchant_id: abf92f77-0cbf-4c1e-9743-4df46a2ed000
          name: Loja Centro
          active: true
    ItensIfoodCatalogo:
      summary: Itens do catálogo com e sem código atual
      value:
        - ifood_item_id: 550e8400-e29b-41d4-a716-446655440000
          name: Takeat Burger
          external_code: null
        - ifood_item_id: 550e8400-e29b-41d4-a716-446655440001
          name: Takeat Burger no delivery
          external_code: ANTIGO-99
    EdicaoLocalPdv:
      summary: Editar o código somente na Takeat
      value:
        pdv_codes:
          - id: 123
            code: '00042'
        expected_updated_at: '2026-11-16T12:00:00.000Z'
        replicate_ifood: false
    PublicacaoProdutoIfood:
      summary: Editar e solicitar publicação em dois itens
      value:
        pdv_codes:
          - id: 123
            code: '00042'
        expected_updated_at: '2026-11-16T12:00:00.000Z'
        replicate_ifood: true
        ifood_targets:
          - code: '00042'
            ifood_restaurant_id: 10
            ifood_item_id: 550e8400-e29b-41d4-a716-446655440000
            force: false
          - code: '00042'
            ifood_restaurant_id: 10
            ifood_item_id: 550e8400-e29b-41d4-a716-446655440001
            force: false
    ProdutoComPublicacaoParcial:
      summary: Produto gravado com uma publicação concluída e outra em conflito
      value:
        image_id: null
        id: 42
        restaurant_id: 85
        product_category_id: 10
        custom_order: 0
        name: Takeat Burger
        description: null
        price: '28.00'
        price_promotion: null
        delivery_price: '31.00'
        delivery_price_promotion: null
        sold_off: false
        available: true
        available_in_delivery: true
        use_weight: false
        has_starting_price: false
        charge_service_tax: true
        pdv_codes:
          - id: 123
            code: '00042'
            integration: Takeat
        fiscal:
          ncm: null
          cfop: null
          csosn: null
          cst: null
          cest: null
          icms_origem: null
          aliquota: null
          base_calculo: null
          pis: null
          cofins: null
          pis_aliquota: null
          cofins_aliquota: null
          icms_modalidade_base_calculo: null
          icms_aliquota: null
          icms_valor: null
          cbenef: null
          fcp_percentual: null
          icms_base_calculo_retido_st: null
          icms_aliquota_final: null
          icms_valor_retido_st: null
          icms_valor_substituto: null
          icms_reducao_base_calculo: null
          icms_motivo_desoneracao: null
          icms_valor_desonerado: null
          icms_aliquota_credito_simples: null
          icms_valor_credito_simples: null
          ibs_cbs_situacao_tributaria: null
          ibs_cbs_classificacao_tributaria: null
          icms_modalidade_base_calculo_st: null
          icms_margem_valor_adicionado_st: null
          icms_reducao_base_calculo_st: null
          icms_aliquota_st: null
        created_at: '2026-11-16T12:00:00.000Z'
        updated_at: '2026-11-16T12:05:00.000Z'
        ifood_replication:
          results:
            - code: '00042'
              ifood_restaurant_id: 10
              ifood_item_id: 550e8400-e29b-41d4-a716-446655440000
              status: succeeded
              overwritten: false
            - code: '00042'
              ifood_restaurant_id: 10
              ifood_item_id: 550e8400-e29b-41d4-a716-446655440001
              status: failed
              error:
                key: ifood_external_code_exists
                message: O item iFood já possui outro código. Use force explicitamente para substituir.
    LoteMistoPdv:
      summary: Lote com publicação no primeiro produto e edição local no segundo
      value:
        - id: 42
          pdv_codes:
            - id: 123
              code: '00042'
          expected_updated_at: '2026-11-16T12:00:00.000Z'
          replicate_ifood: true
          ifood_targets:
            - code: '00042'
              ifood_restaurant_id: 10
              ifood_item_id: 550e8400-e29b-41d4-a716-446655440000
              force: false
            - code: '00042'
              ifood_restaurant_id: 10
              ifood_item_id: 550e8400-e29b-41d4-a716-446655440001
              force: false
        - id: 43
          price: 22
          replicate_ifood: false
          expected_updated_at: '2026-11-16T12:00:00.000Z'
    LoteComPublicacaoParcial:
      summary: Lote gravado com resultado parcial no iFood
      value:
        - image_id: null
          id: 42
          restaurant_id: 85
          product_category_id: 10
          custom_order: 0
          name: Takeat Burger
          description: null
          price: '28.00'
          price_promotion: null
          delivery_price: '31.00'
          delivery_price_promotion: null
          sold_off: false
          available: true
          available_in_delivery: true
          use_weight: false
          has_starting_price: false
          charge_service_tax: true
          pdv_codes:
            - id: 123
              code: '00042'
              integration: Takeat
          fiscal:
            ncm: null
            cfop: null
            csosn: null
            cst: null
            cest: null
            icms_origem: null
            aliquota: null
            base_calculo: null
            pis: null
            cofins: null
            pis_aliquota: null
            cofins_aliquota: null
            icms_modalidade_base_calculo: null
            icms_aliquota: null
            icms_valor: null
            cbenef: null
            fcp_percentual: null
            icms_base_calculo_retido_st: null
            icms_aliquota_final: null
            icms_valor_retido_st: null
            icms_valor_substituto: null
            icms_reducao_base_calculo: null
            icms_motivo_desoneracao: null
            icms_valor_desonerado: null
            icms_aliquota_credito_simples: null
            icms_valor_credito_simples: null
            ibs_cbs_situacao_tributaria: null
            ibs_cbs_classificacao_tributaria: null
            icms_modalidade_base_calculo_st: null
            icms_margem_valor_adicionado_st: null
            icms_reducao_base_calculo_st: null
            icms_aliquota_st: null
          created_at: '2026-11-16T12:00:00.000Z'
          updated_at: '2026-11-16T12:05:00.000Z'
          ifood_replication:
            results:
              - code: '00042'
                ifood_restaurant_id: 10
                ifood_item_id: 550e8400-e29b-41d4-a716-446655440000
                status: succeeded
                overwritten: false
              - code: '00042'
                ifood_restaurant_id: 10
                ifood_item_id: 550e8400-e29b-41d4-a716-446655440001
                status: failed
                error:
                  key: ifood_external_code_exists
                  message: O item iFood já possui outro código. Use force explicitamente para substituir.
        - image_id: null
          id: 43
          restaurant_id: 85
          product_category_id: 10
          custom_order: 0
          name: Batata frita
          description: null
          price: '22.00'
          price_promotion: null
          delivery_price: null
          delivery_price_promotion: null
          sold_off: false
          available: true
          available_in_delivery: true
          use_weight: false
          has_starting_price: false
          charge_service_tax: true
          pdv_codes:
            - id: 124
              code: '00043'
              integration: Takeat
          fiscal:
            ncm: null
            cfop: null
            csosn: null
            cst: null
            cest: null
            icms_origem: null
            aliquota: null
            base_calculo: null
            pis: null
            cofins: null
            pis_aliquota: null
            cofins_aliquota: null
            icms_modalidade_base_calculo: null
            icms_aliquota: null
            icms_valor: null
            cbenef: null
            fcp_percentual: null
            icms_base_calculo_retido_st: null
            icms_aliquota_final: null
            icms_valor_retido_st: null
            icms_valor_substituto: null
            icms_reducao_base_calculo: null
            icms_motivo_desoneracao: null
            icms_valor_desonerado: null
            icms_aliquota_credito_simples: null
            icms_valor_credito_simples: null
            ibs_cbs_situacao_tributaria: null
            ibs_cbs_classificacao_tributaria: null
            icms_modalidade_base_calculo_st: null
            icms_margem_valor_adicionado_st: null
            icms_reducao_base_calculo_st: null
            icms_aliquota_st: null
          created_at: '2026-11-16T12:00:00.000Z'
          updated_at: '2026-11-16T12:05:00.000Z'
    RepeticaoPublicacaoIfood:
      summary: Repetir somente a publicação sem alterar os dados locais
      value:
        replicate_ifood: true
        expected_updated_at: '2026-11-16T12:05:00.000Z'
        ifood_targets:
          - code: '00042'
            ifood_restaurant_id: 10
            ifood_item_id: 550e8400-e29b-41d4-a716-446655440001
            force: false
    ErroCodigoDestinoIfood:
      summary: Rejeição de código que não pertence ao produto
      value:
        statusCode: 400
        message: Código PDV não pertence ao produto.
        key: invalid_ifood_target_code

  securitySchemes:
    salonIntegration:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Access token de integração. O escopo exigido consta em cada operação; perfis pessoais de garçom e sessões
        humanas não são aceitos.
    reportsIntegration:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Access token obtido por OAuth ou troca de API key. Exige reports:payments:read, reports:customers:read, reports:products:read ou reports:kds:read conforme a rota. Não aceita sessões humanas, tokens de garçom ou chaves brutas.
    certificateIntegration:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Access token de integração. GET exige certificates:read; PUT exige certificates:write. API keys passam antes pela troca em /oauth/token. Não aceita sessões humanas nem OAuth pessoal de garçom.
    RestaurantOwnerSession:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Sessão humana de restaurante autenticada pela Takeat; nunca um access ou refresh token OAuth de app.
    inventoryIntegration:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Access token de integração com inputs:stock:write ou intermediaries:stock:write conforme a operação. Sessões humanas não são aceitas.
    storeOAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Access token de instalação OAuth Authorization Code + PKCE de app com
        perfil Restaurante. O client_id identifica o próprio app. Exige
        consentimento ativo, não expirado e app visível; exige store:reviews:read
        para consulta e store:reviews:write para criar, editar ou excluir. API keys, client credentials, sessões humanas, MCP e
        autorizações de garçom não são aceitos.
    waiterOAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Access token OAuth pessoal de garçom; sujeito e loja fixados na autorização.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Access token OAuth obtido em `POST /oauth/token` ou sessão autenticada
        do restaurante emitida pelo login Takeat. Tokens OAuth exigem os
        escopos de cada operação. A sessão não usa escopos de integração e
        fica limitada ao `restaurant_id` assinado. Chaves `tk_` não são aceitas.

  parameters:
    SalonRestaurantId:
      name: restaurant_id
      in: query
      description: Restaurante permitido pela credencial; obrigatório se a seleção não for inequívoca.
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 2147483647
    SalonStart:
      name: start_date
      in: query
      required: true
      description: Início inclusivo em ISO 8601 com timezone. Janela máxima de 31 dias.
      schema:
        type: string
        format: date-time
    SalonEnd:
      name: end_date
      in: query
      required: true
      description: Fim exclusivo em ISO 8601 com timezone. Métricas não aceitam instantes futuros.
      schema:
        type: string
        format: date-time
    SalonLimit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
    SalonCursor:
      name: cursor
      in: query
      schema:
        type: string
        maxLength: 512
      description: Opaco e vinculado ao restaurante, recurso, período e filtros originais.
    SalonTableId:
      name: tableId
      in: path
      required: true
      schema:
        type: integer
        minimum: 1
        maximum: 2147483647
    SalonReservationId:
      name: reservationId
      in: path
      required: true
      schema:
        type: integer
        minimum: 1
        maximum: 2147483647
    ReportRestaurantId:
      name: restaurant_id
      in: query
      required: false
      description: >-
        Restaurante autorizado pela credencial. Obrigatório quando houver mais de um restaurante; sem seleção
        implícita para credenciais universais.
      schema:
        type: string
    ReportStartDate:
      name: start_date
      in: query
      required: true
      description: Início do período (YYYY-MM-DD). No KDS também aceita ISO com timezone.
      schema:
        type: string
      example: '2026-11-01'
    ReportEndDate:
      name: end_date
      in: query
      required: true
      description: >-
        Fim do período (YYYY-MM-DD). KDS inclui o dia civil de Brasília; com ISO, o instante final é exclusivo.
        KDS: máximo 92 dias.
      schema:
        type: string
      example: '2026-11-07'
    ReportFill:
      name: fill
      in: query
      required: false
      description: Opção de preenchimento de períodos da API de relatórios.
      schema:
        type: string
    ReportStartMonth:
      name: start_month
      in: query
      required: true
      description: Primeiro mês (YYYY-MM).
      schema:
        type: string
      example: 2026-11
    ReportEndMonth:
      name: end_month
      in: query
      required: true
      description: Último mês (YYYY-MM).
      schema:
        type: string
      example: 2026-11
    ReportBrandId:
      name: brand_id
      in: query
      required: false
      description: ID da marca do restaurante.
      schema:
        type: string
    ReportChannelGroup:
      name: channel_group
      in: query
      required: false
      description: Grupo do canal de venda (presencial, delivery_takeat ou marketplaces).
      schema:
        type: string
    ReportChannel:
      name: channel
      in: query
      required: false
      description: Canal de venda do relatório de origem.
      schema:
        type: string
    ReportPaymentMethodId:
      name: payment_method_id
      in: query
      required: false
      description: ID do método de pagamento.
      schema:
        type: string
    ReportPaymentMethod:
      name: payment_method
      in: query
      required: false
      description: Filtro de forma de pagamento nas transações.
      schema:
        type: string
    ReportCursor:
      name: cursor
      in: query
      required: false
      description: Cursor opaco retornado em data.next_cursor. Omitir na primeira página; null encerra a paginação.
      schema:
        type: string
    ReportAno:
      name: ano
      in: query
      required: true
      description: Ano da consulta de sessões.
      schema:
        type: string
      example: '2026'
    ReportMes:
      name: mes
      in: query
      required: true
      description: Mês da consulta de sessões (1–12).
      schema:
        type: string
      example: '11'
    ReportPhoneBreakdown:
      name: phone_breakdown
      in: query
      required: false
      description: Detalhamento de telefone conforme o relatório de clientes.
      schema:
        type: string
    ReportSegment:
      name: segment
      in: query
      required: false
      description: Segmento de atividade do cliente.
      schema:
        type: string
    ReportOrigin:
      name: origin
      in: query
      required: false
      description: Origem dos clientes.
      schema:
        type: string
    ReportVisits:
      name: visits
      in: query
      required: false
      description: Filtro de quantidade de visitas.
      schema:
        type: string
    ReportMode:
      name: mode
      in: query
      required: false
      description: Modo de seleção dos clientes.
      schema:
        type: string
    ReportHasPhone:
      name: has_phone
      in: query
      required: false
      description: Filtro de presença de telefone.
      schema:
        type: string
    ReportCohortStartDateOptional:
      name: cohort_start_date
      in: query
      required: false
      description: Início da coorte (YYYY-MM-DD).
      schema:
        type: string
      example: '2026-11-01'
    ReportCohortEndDateOptional:
      name: cohort_end_date
      in: query
      required: false
      description: Fim da coorte (YYYY-MM-DD).
      schema:
        type: string
      example: '2026-11-07'
    ReportMinStage:
      name: min_stage
      in: query
      required: false
      description: Etapa mínima no funil de visitas.
      schema:
        type: string
    ReportCohortStartDate:
      name: cohort_start_date
      in: query
      required: true
      description: Início da coorte (YYYY-MM-DD).
      schema:
        type: string
      example: '2026-11-01'
    ReportCohortEndDate:
      name: cohort_end_date
      in: query
      required: true
      description: Fim da coorte (YYYY-MM-DD).
      schema:
        type: string
      example: '2026-11-07'
    ReportStage:
      name: stage
      in: query
      required: false
      description: Etapa da retenção por visitas.
      schema:
        type: string
    ReportView:
      name: view
      in: query
      required: false
      description: Visão da análise ABC/BCG suportada pela API de origem.
      schema:
        type: string
    ReportCategoryId:
      name: category_id
      in: query
      required: false
      description: ID da categoria.
      schema:
        type: string
    ReportIncludeToday:
      name: include_today
      in: query
      required: false
      description: Inclusão do dia corrente conforme o relatório de origem.
      schema:
        type: string
    ReportCompare:
      name: compare
      in: query
      required: false
      description: >-
        Comparação suportada pelo relatório. KDS: previous, same_days_previous_month, ou ambos separados por
        vírgula. Produtos: mesmos valores aceitos na manager-api.
      schema:
        type: string
    ReportMonth:
      name: month
      in: query
      required: true
      description: Mês consultado (YYYY-MM).
      schema:
        type: string
      example: 2026-11
    ReportProductId:
      name: product_id
      in: query
      required: false
      description: ID do produto para detalhamento ou associação.
      schema:
        type: string
    ReportGroupBy:
      name: group_by
      in: query
      required: false
      description: Agrupamento de cancelamentos suportado pela API de origem.
      schema:
        type: string
    ReportFilterBy:
      name: filter_by
      in: query
      required: false
      description: Recorte de cancelamentos suportado pela API de origem.
      schema:
        type: string
    ReportKdsIds:
      name: kds_ids
      in: query
      required: false
      description: IDs das telas KDS separados por vírgula.
      schema:
        type: string
    ReportChannels:
      name: channels
      in: query
      required: false
      description: Canais KDS separados por vírgula.
      schema:
        type: string
    ReportChannelGroups:
      name: channel_groups
      in: query
      required: false
      description: 'Grupos KDS separados por vírgula: in_person, marketplace, own_delivery.'
      schema:
        type: string
    ReportLimit:
      name: limit
      in: query
      required: false
      description: 'Limite do ranking KDS. Produtos: padrão 20; detratores e slowest: padrão 5. Slowest: máximo 50.'
      schema:
        type: string
    ReportMinSample:
      name: min_sample
      in: query
      required: false
      description: Amostra mínima dos detratores; padrão 10.
      schema:
        type: string
    ReportGapPct:
      name: gap_pct
      in: query
      required: false
      description: Diferença percentual por canal; padrão 25.
      schema:
        type: string
    ReportGapMin:
      name: gap_min
      in: query
      required: false
      description: Diferença em minutos por canal; padrão 3.
      schema:
        type: string
    ReportMinOrders:
      name: min_orders
      in: query
      required: false
      description: Quantidade mínima de pedidos por canal; padrão 30.
      schema:
        type: string
    StoreReviewRestaurantId:
      name: restaurant_id
      in: query
      required: false
      description: |
        Loja autorizada nesta conexão. Em GET, filtra avaliações e resumo;
        omitir lista todas as avaliações do app. Em POST/DELETE, seleciona a loja
        autora; obrigatório quando o token autoriza várias. Vínculos atuais e
        consentimento limitam a seleção. Uma loja não autorizada retorna 403.
      schema: { type: integer, minimum: 1, maximum: 2147483647, example: 85 }
    RatingsStartDate:
      name: start_date
      in: query
      required: true
      description: Primeiro dia do período, inclusivo em UTC; no máximo 92 dias com end_date.
      schema: { type: string, format: date, example: '2026-10-01' }
    RatingsEndDate:
      name: end_date
      in: query
      required: true
      description: Último dia do período, inclusivo em UTC; não pode anteceder start_date.
      schema: { type: string, format: date, example: '2026-10-19' }
    RatingsPage:
      name: page
      in: query
      schema: { type: integer, minimum: 1, maximum: 2147483647, default: 1 }
      description: Página a partir de 1. O deslocamento calculado deve caber em Int32.
    RatingsPerPage:
      name: per_page
      in: query
      schema: { type: integer, minimum: 1, maximum: 100, default: 100 }
    BrandId:
      name: brand_id
      in: query
      required: false
      description: |
        Filtra o recurso pela marca. A marca deve estar ativa, não removida e
        pertencer ao restaurante autorizado. Omitir preserva o comportamento
        agregado atual da rota.
      schema:
        type: integer
        minimum: 1
    ComplementId:
      name: complementId
      in: path
      required: true
      schema:
        type: integer
        minimum: 1
        maximum: 2147483647
    RestaurantId:
      name: restaurant_id
      in: query
      required: false
      description: |
        Omitido para sessões de restaurante ou credenciais com uma única loja.
        Obrigatório quando uma chave ou autorização OAuth multilojas, ou um
        parceiro, cobre várias lojas. É validado contra as lojas atualmente
        autorizadas pela credencial. Em uma sessão, um valor diferente do
        `restaurant_id` assinado responde 403.
      schema:
        type: integer
        minimum: 1
    ProductId:
      name: productId
      in: path
      required: true
      schema:
        type: integer
        minimum: 1

  responses:
    Report200Passthrough:
      description: >-
        Status e JSON da API de relatórios preservados. Inclui totais, séries e cursores quando fornecidos pelo
        relatório. Nenhum envelope adicional.
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
    Report400:
      description: Filtro ou período inválido. Validação do serviço de origem preservada.
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
    Report401:
      description: >-
        Access token ausente, inválido, expirado ou de audiência indevida. Sessões humanas e chaves brutas não são
        aceitas.
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
    Report403:
      description: Permissão insuficiente ou restaurante fora da autorização.
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
    Report404:
      description: Relatório ou combinação de visualização inexistente.
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
    Report502:
      description: Serviço de relatórios indisponível.
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
    Report503:
      description: Integração de relatórios não configurada no servidor.
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
    Report200Kds:
      description: Projeção KDS em snake_case, igual à manager-api. Durações em segundos; medidas ausentes permanecem null.
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
    BadRequest:
      description: Query inválida ou `restaurant_id` obrigatório não informado.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiError"
    Unauthorized:
      description: Access token ausente, inválido, expirado ou revogado.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiError"
    Forbidden:
      description: Escopo ausente ou restaurante não autorizado para a credencial.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiError"

  schemas:
    SalonTable:
      type: object
      properties:
        id:
          description: "ID da mesa; use em GET /v1/tables/{tableId}/history e /reservations."
          type: integer
          minimum: 1
          maximum: 2147483647
        number:
          description: "Número da mesa exibido no salão."
          type: integer
        name:
          description: "Nome cadastrado da mesa (até 20 caracteres); null quando não definido."
          type:
            - string
            - 'null'
        type:
          description: "Tipo da mesa, como table, command (comanda), balcony (balcão), lounge, prepaid, pos, self-service, foodpark ou drive-thru."
          type: string
        capacity:
          description: "Lugares da mesa no inventário de reservas; null quando a mesa não está vinculada a esse inventário."
          type:
            - integer
            - 'null'
        capacity_source:
          description: "Origem de `capacity`: reservation_inventory quando vem do inventário de reservas; null quando não há capacidade."
          type:
            - string
            - 'null'
          enum:
            - reservation_inventory
            - null
        area:
          type: 'null'
          description: Sem fonte confirmada no cadastro atual.
        status:
          description: "Estado atual: awaiting_bill (sessão ou comanda em fechamento), occupied (sessão aberta, reserva em atendimento ou mesa em uso), cleaning, available ou unknown (estado não reconhecido)."
          type: string
          enum:
            - available
            - occupied
            - awaiting_bill
            - cleaning
            - unknown
        active_sessions:
          description: "Sessões abertas ou em fechamento na mesa (exceto delivery), em ordem de ID."
          type: array
          items:
            type: object
            properties:
              id:
                description: "ID da sessão (atendimento); use em GET /v1/table-sessions/{sessionId}."
                type: integer
                minimum: 1
                maximum: 2147483647
              people:
                description: "Pessoas registradas na sessão; null quando o valor não é um inteiro positivo."
                type:
                  - integer
                  - 'null'
              consumption:
                description: "Consumo atual da sessão em reais, string decimal com 2 casas (total_price da sessão, sem taxa de serviço)."
                type:
                  - string
                  - 'null'
                pattern: ^-?[0-9]+\.[0-9]{2}$
              started_at:
                description: "Início da sessão (ISO 8601, UTC); null se não registrado."
                type:
                  - string
                  - 'null'
                format: date-time
              last_order_at:
                description: "Horário do último pedido não cancelado da sessão (ISO 8601, UTC); null quando ainda não há pedido."
                type:
                  - string
                  - 'null'
                format: date-time
            required:
              - id
              - people
              - consumption
              - started_at
              - last_order_at
            additionalProperties: false
      required:
        - id
        - number
        - name
        - type
        - capacity
        - capacity_source
        - area
        - status
        - active_sessions
      additionalProperties: false
    SalonHistory:
      type: object
      properties:
        id:
          description: "ID da sessão (atendimento); use em GET /v1/table-sessions/{sessionId}."
          type: integer
          minimum: 1
          maximum: 2147483647
        table_id:
          description: "ID da mesa à qual a sessão está vinculada hoje."
          type: integer
          minimum: 1
          maximum: 2147483647
        table_number:
          description: "Número da mesa da sessão."
          type: integer
        table_type:
          description: "Tipo da mesa da sessão (table, lounge, balcony, command etc.)."
          type: string
        status:
          description: "Status da sessão como gravado: open, closing, finished (fechada), completed (finalizada), canceled, transfer, unified, entre outros."
          type: string
        started_at:
          description: "Início da sessão (ISO 8601, UTC); null se não registrado."
          type:
            - string
            - 'null'
          format: date-time
        ended_at:
          description: "Encerramento da sessão (ISO 8601, UTC); null enquanto aberta."
          type:
            - string
            - 'null'
          format: date-time
        revenue:
          description: "Consumo líquido da sessão em reais, string com 2 casas (total_price, sem taxa de serviço); null se inválido."
          type:
            - string
            - 'null'
          pattern: ^-?[0-9]+\.[0-9]{2}$
        people:
          description: "Pessoas registradas; null quando não é um inteiro positivo."
          type:
            - integer
            - 'null'
        bill_count:
          description: "Quantidade de comandas individuais da sessão, incluindo as canceladas."
          type: integer
        transfers:
          description: "Transferências de mesa que envolvem esta sessão, em ordem cronológica; lista vazia quando não houve."
          type: array
          items:
            type: object
            properties:
              from_table_id:
                description: "ID da mesa de origem da transferência."
                type: integer
                minimum: 1
                maximum: 2147483647
              to_table_id:
                description: "ID da mesa de destino da transferência."
                type: integer
                minimum: 1
                maximum: 2147483647
              at:
                description: "Momento da transferência (ISO 8601, UTC)."
                type: string
                format: date-time
            required:
              - from_table_id
              - to_table_id
              - at
            additionalProperties: false
      required:
        - id
        - table_id
        - table_number
        - table_type
        - status
        - started_at
        - ended_at
        - revenue
        - people
        - bill_count
        - transfers
      additionalProperties: false
    SalonAssistance:
      type: object
      properties:
        id:
          description: "ID do chamado de atendimento."
          type: integer
          minimum: 1
          maximum: 2147483647
        table_id:
          description: "ID da mesa do chamado. Chamados cujo número não corresponde a uma única mesa física ativa não são retornados."
          type: integer
          minimum: 1
          maximum: 2147483647
        table_number:
          description: "Número da mesa informado no chamado."
          type: integer
        status:
          description: "pending: chamado ainda não atendido; attended: marcado como atendido."
          type: string
          enum:
            - pending
            - attended
        requested_at:
          description: "Momento em que o cliente chamou o garçom (ISO 8601, UTC)."
          type: string
          format: date-time
        updated_at:
          description: "Última atualização do chamado, como a marcação de atendido (ISO 8601, UTC)."
          type: string
          format: date-time
      required:
        - id
        - table_id
        - table_number
        - status
        - requested_at
        - updated_at
      additionalProperties: false
    SalonCashRegister:
      type: object
      properties:
        id:
          description: "ID do caixa; use como cashier_id para filtrar."
          type: integer
          minimum: 1
          maximum: 2147483647
        status:
          description: "Sempre open: somente caixas abertos são listados."
          const: open
        opened_at:
          description: "Abertura do caixa (ISO 8601, UTC)."
          type: string
          format: date-time
        initial_value:
          description: "Valor inicial (fundo de troco) em reais, string com 2 casas."
          type: string
        current_balance:
          description: "Saldo atual registrado no caixa em reais, string com 2 casas."
          type: string
        receives_pos:
          description: "Indica se o caixa recebe pagamentos feitos nas maquininhas (POS)."
          type: boolean
      required:
        - id
        - status
        - opened_at
        - initial_value
        - current_balance
        - receives_pos
      additionalProperties: false
    SalonReservation:
      type: object
      properties:
        id:
          description: "ID da reserva; use em GET /v1/reservations/{reservationId}."
          type: integer
          minimum: 1
          maximum: 2147483647
        restaurant_id:
          description: "ID do restaurante da reserva."
          type: integer
          minimum: 1
          maximum: 2147483647
        table_id:
          description: "ID da mesa vinculada; null quando a reserva ainda não tem mesa."
          type:
            - integer
            - 'null'
        status:
          description: "Status: pending_payment, confirmed, checked_in (cliente chegou), finished, cancelled, no_show ou expired."
          type: string
        customer_name:
          description: "Nome informado pelo cliente na reserva."
          type: string
        customer_phone:
          description: "Telefone informado pelo cliente, como gravado (sem normalização)."
          type: string
        people_count:
          description: "Quantidade de pessoas da reserva."
          type: integer
        slot_start_at:
          description: "Início do horário reservado (ISO 8601, UTC), convertido do horário local de Brasília gravado pelo motor de reservas."
          type: string
          format: date-time
        slot_end_at:
          description: "Fim do horário reservado (ISO 8601, UTC), convertido do horário local de Brasília gravado pelo motor de reservas."
          type: string
          format: date-time
        notes:
          description: "Observações do cliente; null quando ausentes."
          type:
            - string
            - 'null'
        payment_required:
          description: "Indica se a reserva exige pagamento antecipado."
          type: boolean
        payment_status:
          description: "Status do pagamento antecipado (pending, paid, expired, refunded, partially_refunded, failed); null quando não há cobrança."
          type:
            - string
            - 'null'
        created_at:
          description: "Criação da reserva (ISO 8601, UTC)."
          type: string
          format: date-time
        updated_at:
          description: "Última atualização da reserva (ISO 8601, UTC)."
          type: string
          format: date-time
      required:
        - id
        - restaurant_id
        - table_id
        - status
        - customer_name
        - customer_phone
        - people_count
        - slot_start_at
        - slot_end_at
        - notes
        - payment_required
        - payment_status
        - created_at
        - updated_at
      additionalProperties: false
    SalonMetric:
      type: object
      properties:
        table_id:
          description: "ID da mesa."
          type: integer
          minimum: 1
          maximum: 2147483647
        table_number:
          description: "Número da mesa."
          type: integer
        revenue:
          description: "Consumo líquido (total_price) dos atendimentos encerrados no período, em reais com 2 casas; null com transferências sem atribuição completa."
          type:
            - string
            - 'null'
          pattern: ^-?[0-9]+\.[0-9]{2}$
        ticket_per_person:
          description: "Receita dividida pelas pessoas registradas nos atendimentos encerrados (reais, 2 casas); null sem receita ou pessoas."
          type:
            - string
            - 'null'
          pattern: ^-?[0-9]+\.[0-9]{2}$
        revpash:
          description: "Receita por assento-hora disponível (reais, 2 casas): receita / (lugares × horas de funcionamento no período). null sem capacidade ou horário."
          type:
            - string
            - 'null'
          pattern: ^-?[0-9]+\.[0-9]{2}$
        average_ticket:
          description: "Receita dividida pelo número de atendimentos encerrados (reais, 2 casas); null sem atendimentos."
          type:
            - string
            - 'null'
          pattern: ^-?[0-9]+\.[0-9]{2}$
        turnover:
          description: "Ciclos de ocupação liberados no período; sessões simultâneas contam como um ciclo. null quando os dados não permitem o cálculo."
          type:
            - number
            - 'null'
        average_stay_seconds:
          description: "Duração média, em segundos, dos atendimentos encerrados no período; null sem atendimentos ou com horários inválidos."
          type:
            - number
            - 'null'
        occupancy:
          description: "Fração do tempo de funcionamento com a mesa ocupada (0 a 1; 0.75 = 75%); null sem horário de funcionamento."
          type:
            - number
            - 'null'
        seat_utilization:
          description: Indisponível (null); o legado não mantém histórico de pessoas ao longo da sessão.
          type:
            - number
            - 'null'
        bill_count:
          description: "Comandas individuais não canceladas dos atendimentos encerrados no período; null com transferências sem atribuição."
          type:
            - number
            - 'null'
        attendance_count:
          description: "Atendimentos (sessões) encerrados no período; null com transferências sem atribuição."
          type:
            - number
            - 'null'
        idle_seconds:
          description: "Segundos desde o último pedido válido de uma mesa com sessão aberta; null se a mesa está livre ou sem pedidos."
          type:
            - number
            - 'null'
        unavailable_reasons:
          description: "Motivos dos indicadores nulos, como table_transfer_history, capacity_history_unavailable, people_history_unavailable, no_completed_attendances, no_opening_time, opening_hours_unavailable."
          type: array
          items:
            type: string
      required:
        - table_id
        - table_number
        - revenue
        - ticket_per_person
        - revpash
        - average_ticket
        - turnover
        - average_stay_seconds
        - occupancy
        - seat_utilization
        - bill_count
        - attendance_count
        - idle_seconds
        - unavailable_reasons
      additionalProperties: false
    SalonHistoryPage:
      type: object
      properties:
        data:
          description: "Página atual de atendimentos, em ordem crescente de ID."
          type: array
          items:
            $ref: '#/components/schemas/SalonHistory'
        pagination:
          description: "Metadados da paginação por cursor."
          type: object
          properties:
            count:
              description: "Quantidade de itens retornados nesta página."
              type: integer
            limit:
              description: "Tamanho de página aplicado (1 a 100; padrão 50)."
              type: integer
            total:
              description: "Sempre null: a consulta não faz contagem global do conjunto filtrado."
              type: 'null'
            has_more:
              description: "true quando há mais itens após esta página; nesse caso `next` traz o cursor."
              type: boolean
            next:
              description: "Parâmetros da próxima chamada; null quando não há mais itens."
              oneOf:
                - type: 'null'
                - type: object
                  properties:
                    cursor:
                      description: "Cursor opaco da próxima página. Reenvie com o mesmo recurso, restaurante, período, limite e filtros; caso contrário retorna 400 invalid_salon_cursor."
                      type: string
                  required:
                    - cursor
                  additionalProperties: false
          required:
            - count
            - limit
            - total
            - has_more
            - next
          additionalProperties: false
      required:
        - data
        - pagination
      additionalProperties: false
    SalonAssistancePage:
      type: object
      properties:
        data:
          description: "Página atual de chamados de mesa, em ordem crescente de ID."
          type: array
          items:
            $ref: '#/components/schemas/SalonAssistance'
        pagination:
          description: "Metadados da paginação por cursor."
          type: object
          properties:
            count:
              description: "Quantidade de itens retornados nesta página."
              type: integer
            limit:
              description: "Tamanho de página aplicado (1 a 100; padrão 50)."
              type: integer
            total:
              description: "Sempre null: a consulta não faz contagem global do conjunto filtrado."
              type: 'null'
            has_more:
              description: "true quando há mais itens após esta página; nesse caso `next` traz o cursor."
              type: boolean
            next:
              description: "Parâmetros da próxima chamada; null quando não há mais itens."
              oneOf:
                - type: 'null'
                - type: object
                  properties:
                    cursor:
                      description: "Cursor opaco da próxima página. Reenvie com o mesmo recurso, restaurante, período, limite e filtros; caso contrário retorna 400 invalid_salon_cursor."
                      type: string
                  required:
                    - cursor
                  additionalProperties: false
          required:
            - count
            - limit
            - total
            - has_more
            - next
          additionalProperties: false
      required:
        - data
        - pagination
      additionalProperties: false
    SalonReservationPage:
      type: object
      properties:
        data:
          description: "Página atual de reservas, em ordem crescente de ID."
          type: array
          items:
            $ref: '#/components/schemas/SalonReservation'
        pagination:
          description: "Metadados da paginação por cursor."
          type: object
          properties:
            count:
              description: "Quantidade de itens retornados nesta página."
              type: integer
            limit:
              description: "Tamanho de página aplicado (1 a 100; padrão 50)."
              type: integer
            total:
              description: "Sempre null: a consulta não faz contagem global do conjunto filtrado."
              type: 'null'
            has_more:
              description: "true quando há mais itens após esta página; nesse caso `next` traz o cursor."
              type: boolean
            next:
              description: "Parâmetros da próxima chamada; null quando não há mais itens."
              oneOf:
                - type: 'null'
                - type: object
                  properties:
                    cursor:
                      description: "Cursor opaco da próxima página. Reenvie com o mesmo recurso, restaurante, período, limite e filtros; caso contrário retorna 400 invalid_salon_cursor."
                      type: string
                  required:
                    - cursor
                  additionalProperties: false
          required:
            - count
            - limit
            - total
            - has_more
            - next
          additionalProperties: false
      required:
        - data
        - pagination
      additionalProperties: false
    SalonTablesResponse:
      type: object
      properties:
        restaurant_id:
          description: "ID do restaurante consultado."
          type: integer
          minimum: 1
          maximum: 2147483647
        generated_at:
          description: "Momento em que o snapshot foi gerado (ISO 8601, UTC)."
          type: string
          format: date-time
        data:
          description: "Mesas do restaurante, ordenadas por número e ID. Exclui mesas de delivery e de cardápio QR e as removidas."
          type: array
          items:
            $ref: '#/components/schemas/SalonTable'
      required:
        - restaurant_id
        - generated_at
        - data
      additionalProperties: false
    SalonCashResponse:
      type: object
      properties:
        data:
          description: "Caixas abertos do restaurante, em ordem de ID (até 100)."
          type: array
          items:
            $ref: '#/components/schemas/SalonCashRegister'
      required:
        - data
      additionalProperties: false
    SalonMetricsResponse:
      type: object
      properties:
        restaurant_id:
          description: "ID do restaurante consultado."
          type: integer
          minimum: 1
          maximum: 2147483647
        generated_at:
          description: "Momento do cálculo (ISO 8601, UTC); também é o \"agora\" usado em idle_seconds e sessões abertas."
          type: string
          format: date-time
        time_zone:
          description: "Fuso usado para aplicar o horário de funcionamento (padrão America/Sao_Paulo)."
          type: string
        definition_version:
          description: "Versão das definições dos indicadores; sempre 1."
          const: 1
        period:
          description: "Período consultado, ecoando start_date e end_date enviados."
          type: object
          properties:
            start:
              description: "Início do período, exatamente como enviado em start_date (ISO 8601 com timezone); inclusivo."
              type: string
              format: date-time
            end:
              description: "Fim do período, exatamente como enviado em end_date (ISO 8601 com timezone); exclusivo."
              type: string
              format: date-time
          required:
            - start
            - end
          additionalProperties: false
        data:
          description: "Indicadores por mesa (somente tipos table e lounge existentes no período), em ordem de ID."
          type: array
          items:
            $ref: '#/components/schemas/SalonMetric'
        summary:
          description: "Totais das mesas retornadas em data."
          type: object
          additionalProperties: false
          required:
            - table_count
            - revenue
            - attendance_count
            - bill_count
            - tables_with_unavailable_metrics
          properties:
            table_count:
              description: "Quantidade de mesas em data."
              type: integer
            revenue:
              description: "Soma da receita das mesas em reais (2 casas); null se alguma mesa tiver receita indisponível."
              type:
                - string
                - 'null'
            attendance_count:
              description: "Soma dos atendimentos encerrados; null se alguma mesa tiver o valor indisponível."
              type:
                - integer
                - 'null'
            bill_count:
              description: "Soma das comandas; null se alguma mesa tiver o valor indisponível."
              type:
                - integer
                - 'null'
            tables_with_unavailable_metrics:
              description: "Quantidade de mesas com pelo menos um motivo em unavailable_reasons."
              type: integer
      required:
        - restaurant_id
        - generated_at
        - time_zone
        - definition_version
        - period
        - data
        - summary
      additionalProperties: false
    BrandCertificate:
      type: object
      additionalProperties: false
      required: [valid_from, valid_until, certificate_cnpj, company_name, status]
      properties:
        valid_from: { description: "Início da validade do certificado digital (ISO 8601, UTC). null quando não há certificado ou a data não foi informada.", type: [string, 'null'], format: date-time }
        valid_until: { description: "Fim da validade do certificado digital (ISO 8601, UTC). null quando não há certificado ou a data não foi informada.", type: [string, 'null'], format: date-time }
        certificate_cnpj: { description: "CNPJ titular do certificado, só dígitos (14). null quando ausente ou inválido; não é substituído pelo CNPJ da marca.", type: [string, 'null'], pattern: '^[0-9]{14}$' }
        company_name: { description: "Razão social cadastrada para o CNPJ da marca no emissor fiscal; null quando não informada.", type: [string, 'null'] }
        status:
          description: "Situação do certificado: valid (vigente), expired (vencido), not_yet_valid (início futuro), missing (sem certificado) ou unknown (dados incompletos)."
          type: string
          enum: [valid, expired, not_yet_valid, missing, unknown]
    InventoryCountRequest:
      type: object
      additionalProperties: false
      required: [quantidade, expected_stock_version, counted_at, reason]
      properties:
        quantidade: { type: string, maxLength: 40, pattern: '^(?:0|[1-9]\d*)(?:\.\d{1,12})?$', example: '8.500' }
        expected_stock_version: { type: string, maxLength: 19, pattern: '^(?:0|[1-9]\d*)$', example: '42' }
        counted_at: { type: string, format: date-time, example: '2026-10-28T14:00:00Z' }
        reason: { type: string, minLength: 1, maxLength: 255, pattern: '\S', description: Deve conter pelo menos um caractere que não seja espaço em branco., example: Contagem física }
    InventoryCountBatchRequest:
      type: object
      additionalProperties: false
      required: [items]
      properties:
        items:
          type: array
          minItems: 1
          maxItems: 100
          items:
            type: object
            additionalProperties: false
            required: [id, quantidade, expected_stock_version, counted_at, reason]
            properties:
              id: { type: integer, minimum: 1, maximum: 2147483647 }
              quantidade: { $ref: '#/components/schemas/InventoryCountRequest/properties/quantidade' }
              expected_stock_version: { $ref: '#/components/schemas/InventoryCountRequest/properties/expected_stock_version' }
              counted_at: { $ref: '#/components/schemas/InventoryCountRequest/properties/counted_at' }
              reason: { $ref: '#/components/schemas/InventoryCountRequest/properties/reason' }
    InventoryCountResponse:
      type: object
      additionalProperties: false
      required: [count_id, history_id, id, restaurant_id, unidade, previous_quantity, quantidade, quantity_delta, unitary_price, total_value, stock_version, counted_at, applied_at]
      properties:
        count_id: { description: "ID único (UUID) desta contagem.", type: string, format: uuid }
        history_id: { description: "ID do registro criado no histórico de movimentações do item.", type: integer }
        id: { description: "ID do insumo ou intermediário contado.", type: integer }
        restaurant_id: { description: "ID do restaurante dono do item.", type: integer }
        unidade: { description: "Unidade de medida do item; quantidades da contagem usam essa unidade.", type: string }
        previous_quantity: { description: "Saldo antes da contagem, preservando o texto armazenado.", type: string }
        quantidade: { description: "Novo saldo, igual à quantidade contada (string decimal).", type: string }
        quantity_delta: { description: "Diferença aplicada (quantidade − saldo anterior); negativa quando o saldo diminuiu.", type: string }
        unitary_price: { description: "Custo unitário vigente em reais, com duas casas; não é alterado pela contagem.", type: string }
        total_value: { description: "Novo valor do saldo em reais (quantidade × custo unitário), com duas casas.", type: string }
        stock_version: { description: "Nova versão do saldo após a contagem; use como `expected_stock_version` na próxima.", type: string }
        counted_at: { description: "Momento informado da contagem física (ISO 8601, UTC); só registro, sem efeito retroativo.", type: string, format: date-time }
        applied_at: { description: "Momento em que o saldo foi alterado (ISO 8601, UTC).", type: string, format: date-time }
    InventoryCountBatchResponse:
      type: object
      additionalProperties: false
      required: [items]
      properties:
        items:
          description: "Resultados das contagens, na ordem enviada."
          type: array
          items: { $ref: '#/components/schemas/InventoryCountResponse' }
    RestaurantClientsPage:
      type: object
      additionalProperties: false
      required: [page, per_page, total, total_pages, clients]
      properties:
        page: { description: "Página retornada (a partir de 1).", type: integer, minimum: 1 }
        per_page: { description: "Tamanho da página solicitado (1 a 200, padrão 100).", type: integer, minimum: 1, maximum: 200 }
        total: { description: "Total de buyers que atendem ao filtro, antes da paginação.", type: integer, minimum: 0 }
        total_pages: { description: "Total de páginas (teto de total ÷ per_page); 0 quando não há buyers.", type: integer, minimum: 0 }
        clients:
          description: "Buyers da página, ordenados por `id` crescente."
          type: array
          items:
            $ref: '#/components/schemas/RestaurantBuyer'
    RestaurantBuyer:
      type: object
      additionalProperties: false
      required: [id, name, phone, email, registered_in_clube, cashback, cashback_expires_at, purchases_count, last_purchase_at, total_spent, clube]
      properties:
        id:
          type: integer
          description: ID estável de buyers na Takeat; distinto do ID do Clube.
        name: { description: "Nome do buyer na Takeat; `null` quando não informado.", type: [string, 'null'] }
        phone:
          type: [string, 'null']
          pattern: '^55[0-9]{10,11}$'
          description: Telefone do buyer; null quando ausente ou não consultável.
        email: { description: "E-mail do buyer na Takeat; `null` quando não informado.", type: [string, 'null'] }
        registered_in_clube: { description: "`true` quando o telefone tem vínculo ativo no Clube desta loja; nesse caso `clube` vem preenchido.", type: boolean }
        cashback:
          type: [string, 'null']
          pattern: '^[0-9]+\.[0-9]{2}$'
          description: Saldo disponível em reais. Zero expirado/consumido; null sem Clube, no modelo de pontos ou sem telefone válido.
        cashback_expires_at: { description: "Expiração do saldo de cashback (ISO 8601, UTC): última compra + validade da loja. `null` quando o saldo é zero ou não se aplica.", type: [string, 'null'], format: date-time }
        purchases_count:
          type: integer
          minimum: 0
          description: Uma compra por buyer e sessão, independentemente de itens ou cestas.
        last_purchase_at:
          type: [string, 'null']
          format: date-time
          description: Maior início de sessão considerada, com criação da sessão como fallback.
        total_spent:
          type: string
          pattern: '^[0-9]+\.[0-9]{2}$'
          description: Soma decimal das cestas válidas atribuídas; não inclui frete, taxas ou pagamentos separados.
        clube:
          description: "Cadastro do buyer no Clube desta loja; `null` sem vínculo ativo ou sem Clube configurado."
          oneOf:
            - $ref: '#/components/schemas/BuyerClubeProfile'
            - type: 'null'
    BuyerClubeProfile:
      type: object
      additionalProperties: false
      required: [id, name, email, birthday, gender, registered_at, points]
      properties:
        id: { type: integer, description: ID do cliente no Clube. }
        name: { description: "Nome no cadastro do Clube; pode diferir do nome do buyer.", type: [string, 'null'] }
        email: { description: "E-mail no cadastro do Clube; `null` quando ausente.", type: [string, 'null'] }
        birthday: { description: "Data de nascimento no Clube (YYYY-MM-DD); `null` quando ausente.", type: [string, 'null'], format: date }
        gender: { description: "Gênero informado no Clube: `M`, `F` ou `O` (outro); `null` quando ausente.", type: [string, 'null'] }
        registered_at:
          type: [string, 'null']
          format: date-time
          description: Data de criação do vínculo ativo com a loja, não do cadastro global.
        points: { description: "Saldo de pontos do cliente nesta loja, como string; `null` quando ausente (lojas no modelo cashback).", type: [string, 'null'] }
    StoreAppReview:
      type: object
      additionalProperties: false
      required: [id, rating, comment, isExample, createdAt, updatedAt, userName, restaurantName]
      properties:
        id: { description: "ID da avaliação (UUID). Use em DELETE /v1/store/reviews/{reviewId} para removê-la.", type: string, format: uuid }
        rating: { description: "Nota dada ao app, de 1 a 5 estrelas (inteiro).", type: integer, minimum: 1, maximum: 5 }
        comment: { description: "Comentário escrito pelo restaurante sobre o app, com 3 a 1500 caracteres (espaços nas pontas são removidos).", type: string, minLength: 3, maxLength: 1500 }
        isExample: { type: boolean, description: Identifica avaliação fictícia de demonstração. }
        createdAt: { description: "Data e hora de criação da avaliação (ISO 8601, UTC).", type: string, format: date-time }
        updatedAt: { description: "Data e hora da última alteração (ISO 8601, UTC); muda ao reenviar nota/comentário ou ao restaurar uma avaliação excluída.", type: string, format: date-time }
        userName: { description: "Nome de exibição do usuário que avaliou. null em avaliações de demonstração ou quando o usuário foi excluído/não pertence mais à loja.", type: [string, 'null'] }
        restaurantName: { description: "Nome fantasia do restaurante autor da avaliação. null em avaliações de demonstração ou se o restaurante foi excluído.", type: [string, 'null'] }
    ConnectedStoreReviewsPage:
      type: object
      additionalProperties: false
      required: [data, pagination, meta]
      properties:
        data:
          description: "Avaliações do app na página atual, da mais recente para a mais antiga (até 10 por página)."
          type: array
          maxItems: 10
          items: { $ref: '#/components/schemas/StoreAppReview' }
        pagination: { description: "Metadados de paginação por página; siga pagination.next.page para a próxima página.", $ref: '#/components/schemas/Pagination' }
        meta:
          description: "Resumo da consulta: média, avaliação da própria loja, elegibilidade para avaliar e página atual."
          type: object
          additionalProperties: false
          required: [average, ownReview, canReview, page]
          properties:
            average: { description: "Média das notas (1 a 5) de todas as avaliações filtradas, sem arredondamento. null quando não há avaliações.", type: [number, 'null'], minimum: 1, maximum: 5 }
            ownReview:
              description: "Avaliação feita pela loja consultada (restaurant_id do filtro ou da conexão), ou null se ela ainda não avaliou o app."
              oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/StoreAppReview'
            canReview:
              type: boolean
              description: Conexão elegível; o envio ainda verifica o responsável ativo.
            page: { description: "Página retornada (1 a 1000); páginas de 10 avaliações.", type: integer, minimum: 1, maximum: 1000 }
    RestaurantFeaturesResponse:
      type: object
      additionalProperties: false
      required: [restaurant_id, is_active, operation_type, features, available_features]
      properties:
        restaurant_id: { description: "ID do restaurante consultado.", type: integer, minimum: 1 }
        is_active: { type: boolean, description: "Ativação da conta, sem relação com horário de abertura." }
        operation_type:
          description: "Modelo de operação: delivery-only (somente delivery), delivery-and-balcony (delivery e balcão, sem mesas) ou delivery-balcony-and-tables (delivery, balcão e mesas/comandas)."
          type: string
          enum: [delivery-only, delivery-and-balcony, delivery-balcony-and-tables]
        features:
          type: object
          additionalProperties: false
          description: 26 capacidades exportáveis nos cinco grupos de produto. Todas as flags permanecem presentes quando false.
          required: [operation, payments, offline, delivery, additional_features]
          properties:
            operation:
              type: object
              additionalProperties: false
              description: Operação
              required: [table_service, counter, drive_thru, dispatch_app, dark_kitchen, totem, tablet, pinpad, input, credit_register, fiscal_ai, fiscal, whatsapp_automation]
              properties:
                table_service: { type: boolean, description: 'Atendimento por mesas/comandas' }
                counter: { type: boolean, description: 'Balcão' }
                drive_thru: { type: boolean, description: 'Drive-thru' }
                dispatch_app: { type: boolean, description: 'App de despacho' }
                dark_kitchen: { type: boolean, description: 'Múltiplas marcas (Dark Kitchen)' }
                totem: { type: boolean, description: 'Totem' }
                tablet: { type: boolean, description: 'Tablet' }
                pinpad: { type: boolean, description: 'TEF no balcão' }
                input: { type: boolean, description: 'Cadastro de insumos' }
                credit_register: { type: boolean, description: 'Crediário' }
                fiscal_ai: { type: boolean, description: 'Assistência fiscal por IA' }
                fiscal: { type: boolean, description: 'Emissão fiscal' }
                whatsapp_automation: { type: boolean, description: 'Automação de WhatsApp' }
            payments:
              type: object
              additionalProperties: false
              description: Payments
              required: [online_pix, online_credit_card, online_payment, stock]
              properties:
                online_pix: { type: boolean, description: 'PIX online' }
                online_credit_card: { type: boolean, description: 'Cartão online' }
                online_payment: { type: boolean, description: 'PIX ou cartão online habilitado' }
                stock: { type: boolean, description: 'Estoque' }
            offline:
              type: object
              additionalProperties: false
              description: Operação offline
              required: [offline_operation]
              properties:
                offline_operation: { type: boolean, description: 'Permissão para ativar a operação offline, sem informar o estado dos equipamentos' }
            delivery:
              type: object
              additionalProperties: false
              description: Delivery
              required: [delivery_routing]
              properties:
                delivery_routing: { type: boolean, description: 'Roteirização de entregas' }
            additional_features:
              type: object
              additionalProperties: false
              description: Recursos adicionais
              required: [reservations, labels, balance, turnstile, multilinks, cashback, crm]
              properties:
                reservations: { type: boolean, description: 'Reservas' }
                labels: { type: boolean, description: 'Etiquetas de manipulados' }
                balance: { type: boolean, description: 'Balança' }
                turnstile: { type: boolean, description: 'Catraca' }
                multilinks: { type: boolean, description: 'MultiLinks' }
                cashback: { type: boolean, description: 'Clube/cashback' }
                crm: { type: boolean, description: 'CRM disponível, sem expor versão ou plano' }
        available_features:
          type: array
          uniqueItems: true
          description: Lista plana dos identificadores habilitados nos grupos de features, em ordem de grupo e declaração; vazia quando is_active é false. Ignore identificadores novos desconhecidos pelo app.
          items:
            type: string
            enum: [table_service, counter, drive_thru, dispatch_app, dark_kitchen, totem, tablet, pinpad, input, credit_register, fiscal_ai, fiscal, whatsapp_automation, online_pix, online_credit_card, online_payment, stock, offline_operation, delivery_routing, reservations, labels, balance, turnstile, multilinks, cashback, crm]


    ExternalRating:
      type: object
      additionalProperties: false
      required: [id, score, comment, source, customer, criteria, context, created_at, updated_at]
      properties:
        id: { type: integer, description: ID da avaliação no Takeat. }
        score: { type: number, description: Nota geral armazenada; normalmente de 1 a 5. Valores legados são preservados. }
        comment: { description: "Comentário livre do cliente. Pode vir como string vazia quando o cliente só deu nota; null é raro.", type: [string, 'null'] }
        source:
          description: "Origem da avaliação."
          type: object
          additionalProperties: false
          required: [channel]
          properties:
            channel: { type: string, description: Origem armazenada; por exemplo takeat ou clube. }
        customer:
          type: [object, 'null']
          additionalProperties: false
          required: [id, name, phone]
          description: Cliente associado; campos não informados permanecem null. Não contém dados de conta.
          properties:
            id: { description: "ID do cliente que avaliou.", type: integer }
            name: { description: "Nome informado pelo cliente; null quando não cadastrado.", type: [string, 'null'] }
            phone: { description: "Telefone do cliente, no formato mascarado \"(DD) NNNNN-NNNN\"; null quando não informado.", type: [string, 'null'] }
        criteria:
          type: array
          description: Critérios na ordem de cadastro. score null indica um rótulo sem nota numérica; zero é preservado.
          items:
            type: object
            additionalProperties: false
            required: [name, score]
            properties:
              name: { description: "Identificador do critério avaliado. Hoje vem como chave em inglês (service, food, price, environment/enviroment); rótulos personalizados aparecem como texto livre.", type: string, example: service }
              score: { description: "Nota do critério, normalmente de 1 a 5. null indica rótulo sem nota numérica; zero é preservado.", type: [number, 'null'] }
        context:
          description: "Onde a avaliação foi feita: mesa, comanda e compra do Clube relacionadas."
          type: object
          additionalProperties: false
          required: [table, table_session, clube_purchase_id]
          properties:
            table:
              description: "Mesa em que a avaliação foi feita; null em avaliações do Clube e quando não há mesa vinculada."
              type: [object, 'null']
              additionalProperties: false
              required: [id, number]
              properties:
                id: { description: "ID da mesa no Takeat.", type: integer }
                number: { description: "Número da mesa exibido no salão.", type: integer }
            table_session:
              description: "Comanda associada; null quando a avaliação não está ligada a uma comanda (sempre null no Clube)."
              type: [object, 'null']
              additionalProperties: false
              required: [id, session_number]
              properties:
                id: { type: integer, description: ID interno da comanda. }
                session_number: { type: [integer, 'null'], description: Número da comanda quando disponível. }
            clube_purchase_id: { type: [integer, 'null'], description: ID da compra no Clube; não é um ID de comanda Takeat. }
        created_at: { description: "Data e hora da avaliação (ISO 8601, UTC); base do filtro de período.", type: string, format: date-time }
        updated_at: { description: "Data e hora da última alteração da avaliação (ISO 8601, UTC).", type: string, format: date-time }
    RatingsResponse:
      type: object
      additionalProperties: false
      required: [data, pagination, meta]
      properties:
        data:
          description: "Avaliações da página atual, ordenadas por created_at e id decrescentes."
          type: array
          items: { $ref: '#/components/schemas/ExternalRating' }
        pagination:
          description: "Paginação por página; siga next.page/next.per_page mantendo os filtros."
          type: object
          additionalProperties: false
          required: [count, limit, total, has_more, next]
          properties:
            count: { description: "Quantidade de avaliações nesta página.", type: integer, minimum: 0 }
            limit: { description: "Tamanho da página aplicado (per_page; padrão e máximo 100).", type: integer, minimum: 1, maximum: 100 }
            total: { description: "Total de avaliações do período e filtros, em todas as páginas.", type: integer, minimum: 0 }
            has_more: { description: "true quando há mais páginas; nesse caso next não é null.", type: boolean }
            next:
              description: "Parâmetros da próxima página; null na última página."
              type: [object, 'null']
              additionalProperties: false
              required: [page, per_page]
              properties:
                page: { description: "Próxima página a solicitar.", type: integer, minimum: 2 }
                per_page: { description: "Tamanho de página a repetir na próxima chamada.", type: integer, minimum: 1, maximum: 100 }
        meta:
          description: "Contexto da consulta e resumo de todas as avaliações filtradas, independente da página."
          type: object
          additionalProperties: false
          required: [restaurant_id, period, channel, summary]
          properties:
            restaurant_id: { description: "ID do restaurante consultado.", type: integer }
            channel: { type: [string, 'null'], description: Filtro aplicado; null significa todas as origens. }
            period:
              description: "Período consultado, como recebido na requisição."
              type: object
              additionalProperties: false
              required: [start_date, end_date, timezone]
              properties:
                start_date: { description: "Início do período (YYYY-MM-DD), inclusivo, a partir de 00:00 UTC.", type: string, format: date }
                end_date: { description: "Fim do período (YYYY-MM-DD), inclusivo até 23:59:59 UTC.", type: string, format: date }
                timezone: { description: "Fuso das datas do período; sempre UTC.", type: string, const: UTC }
            summary:
              description: "Resumo de todas as avaliações do período e filtros."
              type: object
              additionalProperties: false
              required: [total, average_score]
              properties:
                total: { description: "Total de avaliações do período e filtros; igual a pagination.total.", type: integer, minimum: 0 }
                average_score: { type: [number, 'null'], description: Média geral de todas as correspondências arredondada para duas casas. null quando não há avaliações. }
    Pagination:
      type: object
      additionalProperties: false
      required:
        - count
        - limit
        - total
        - has_more
        - next
      properties:
        count:
          description: "Quantidade de registros retornados nesta página."
          type: integer
          minimum: 0
        limit:
          description: "Tamanho máximo da página aplicado nesta consulta."
          type: integer
          minimum: 1
        total:
          type:
            - integer
            - 'null'
          minimum: 0
          description: Total do conjunto filtrado; null quando a consulta evita uma contagem global.
        has_more:
          description: "true quando há mais registros; nesse caso next traz os parâmetros da próxima chamada."
          type: boolean
        next:
          description: Parâmetros para a próxima chamada, mantendo os filtros originais; null encerra a consulta.
          oneOf:
            - type: 'null'
            - type: object
              additionalProperties: false
              required:
                - offset
              properties:
                offset:
                  description: "Offset a enviar na próxima chamada, mantendo os demais filtros."
                  type: integer
                  minimum: 0
            - type: object
              additionalProperties: false
              required:
                - page
              properties:
                page:
                  description: "Número da próxima página a solicitar, mantendo os demais filtros."
                  type: integer
                  minimum: 1
                per_page:
                  description: "Tamanho de página a repetir na próxima chamada, quando a rota aceita per_page."
                  type: integer
                  minimum: 1
                  maximum: 200
            - type: object
              additionalProperties: false
              required:
                - cursor
              properties:
                cursor:
                  description: "Cursor opaco a enviar na próxima chamada; vinculado aos filtros originais."
                  type: string
    TableSessionsPage:
      type: object
      additionalProperties: false
      required:
        - data
        - pagination
      properties:
        data:
          description: "Sessões da página, em ordem crescente de ID (até 100)."
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/TableSessionV1'
        pagination:
          description: "Paginação por cursor; total é sempre null."
          $ref: '#/components/schemas/Pagination'
    InputsResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - pagination
      properties:
        data:
          description: "Insumos ativos desta página (até 100), ordenados por nome e ID."
          type: array
          maxItems: 100
          items:
            $ref: ./openapi.yaml#/components/schemas/Input
        pagination:
          description: "Metadados de paginação (`count`, `limit`, `total`, `has_more`, `next`). Continue com os parâmetros de `next` até `has_more=false`."
          $ref: '#/components/schemas/Pagination'
    IntermediariesResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - pagination
      properties:
        data:
          description: "Intermediários ativos desta página (até 100), ordenados por nome e ID."
          type: array
          maxItems: 100
          items:
            $ref: ./openapi.yaml#/components/schemas/Intermediary
        pagination:
          description: "Metadados de paginação (`count`, `limit`, `total`, `has_more`, `next`). Continue com os parâmetros de `next` até `has_more=false`."
          $ref: '#/components/schemas/Pagination'
    ClubeClientsResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - pagination
      properties:
        data:
          description: "Clientes do Clube desta página (até 200), com os campos de `ClubeClient`; vazio quando a loja não tem Clube."
          type: array
          maxItems: 200
          items:
            $ref: ./openapi.yaml#/components/schemas/ClubeClient
        pagination:
          description: "Metadados de paginação por página: `next` traz `page` e `per_page` da próxima consulta, ou `null` na última."
          $ref: '#/components/schemas/Pagination'
    CashFlowsResponseV2:
      type: object
      required:
        - data
        - pagination
        - meta
      properties:
        data:
          description: "Lançamentos principais da página (até 100), ordenados por vencimento e ID."
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/CashFlowEntry'
        pagination:
          description: "Metadados de paginação (`count`, `limit`, `total`, `has_more`, `next`). Continue com os parâmetros de `next` até `has_more=false`."
          $ref: '#/components/schemas/Pagination'
        meta:
          description: "Período, tipo de data e totais da consulta."
          type: object
          required:
            - start_date
            - end_date
            - date_type
            - totals
          properties:
            start_date:
              description: "Primeiro dia consultado (YYYY-MM-DD)."
              type: string
              format: date
            end_date:
              description: "Último dia consultado (YYYY-MM-DD), incluído por inteiro."
              type: string
              format: date
            date_type:
              description: "Data usada no filtro: `due_date` (vencimento) ou `competence_date` (competência; sem competência, usa o vencimento)."
              type: string
              enum:
                - due_date
                - competence_date
            totals:
              description: "Totais de receitas e despesas de todo o período filtrado, não só da página."
              $ref: '#/components/schemas/CashFlowTotals'
    ManagedInventoryPageV2:
      type: object
      additionalProperties: false
      required:
        - data
        - pagination
      properties:
        data:
          description: "Cadastros desta página (até 100), ordenados por nome e ID."
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/ManagedInventoryStock'
        pagination:
          description: "Metadados de paginação (`count`, `limit`, `total`, `has_more`, `next`). Continue com os parâmetros de `next` até `has_more=false`."
          $ref: '#/components/schemas/Pagination'
    WaiterBrandPageV2:
      type: object
      additionalProperties: false
      required:
        - data
        - pagination
      properties:
        data:
          description: "Marcas da página atual, ordenados por ID crescente (até 100)."
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/WaiterBrand'
        pagination:
          description: "Paginação por offset (limit 100); siga pagination.next.offset."
          $ref: '#/components/schemas/Pagination'
    WaiterTablePageV2:
      type: object
      additionalProperties: false
      required:
        - data
        - pagination
      properties:
        data:
          description: "Mesas da página atual, ordenados por ID crescente (até 100)."
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/WaiterTable'
        pagination:
          description: "Paginação por offset (limit 100); siga pagination.next.offset."
          $ref: '#/components/schemas/Pagination'
    WaiterSessionPageV2:
      type: object
      additionalProperties: false
      required:
        - data
        - pagination
      properties:
        data:
          description: "Sessões ativas de mesa da página atual, ordenados por ID crescente (até 100)."
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/WaiterSessionSummary'
        pagination:
          description: "Paginação por offset (limit 100); siga pagination.next.offset."
          $ref: '#/components/schemas/Pagination'
    WaiterOrderPageV2:
      type: object
      additionalProperties: false
      required:
        - data
        - pagination
      properties:
        data:
          description: "Itens de pedidos ativos da página atual, ordenados por ID crescente (até 100)."
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/WaiterActiveOrder'
        pagination:
          description: "Paginação por offset (limit 100); siga pagination.next.offset."
          $ref: '#/components/schemas/Pagination'

    WaiterProfile:
      type: object
      additionalProperties: false
      required:
        - id
        - name
        - restaurant_id
      properties:
        id:
          description: "ID do garçom autenticado (string numérica)."
          type: string
          pattern: ^[1-9]\d*$
        name:
          description: "Nome do garçom cadastrado no restaurante."
          type: string
          maxLength: 255
        restaurant_id:
          description: "ID do restaurante do garçom (string numérica)."
          type: string
          pattern: ^[1-9]\d*$
    WaiterBrand:
      type: object
      additionalProperties: false
      required:
        - id
        - name
        - display_name
        - is_default
      properties:
        id:
          description: "ID da marca; use como brand_id em GET /v1/waiter/menu."
          type: integer
          minimum: 1
          maximum: 2147483647
        name:
          description: "Nome interno da marca."
          type: string
          maxLength: 255
        display_name:
          description: "Nome para exibição: nome fantasia da marca ou, se ausente, name."
          type: string
          maxLength: 255
        is_default:
          description: "true para a marca padrão do restaurante."
          type: boolean
    WaiterTable:
      type: object
      additionalProperties: false
      required:
        - id
        - status
        - number
        - type
      properties:
        id:
          description: "ID da mesa."
          type: integer
          minimum: 1
          maximum: 2147483647
        status:
          description: "Situação da mesa: available (livre) ou ongoing (em atendimento)."
          type: string
          maxLength: 255
        number:
          description: "Número/identificação da mesa exibido no salão, sempre como string."
          type: string
        type:
          description: "Tipo da mesa, por exemplo table (mesa), command (comanda), balcony (balcão), delivery, prepaid, pos, self-service ou drive-thru."
          type: string
          maxLength: 255
    WaiterProductIdentity:
      type: object
      additionalProperties: false
      required:
        - id
        - name
      properties:
        id:
          description: "ID do produto."
          type: integer
          minimum: 1
          maximum: 2147483647
        name:
          description: "Nome do produto."
          type: string
          maxLength: 255
    WaiterSelectedChoice:
      type: object
      additionalProperties: false
      required:
        - id
        - name
        - amount
      properties:
        id:
          description: "ID do complemento."
          type: integer
          minimum: 1
          maximum: 2147483647
        name:
          description: "Nome do complemento."
          type: string
          maxLength: 255
        amount:
          description: "Quantidade do complemento selecionada."
          type: number
          minimum: 0
    WaiterChoiceGroup:
      type: object
      additionalProperties: false
      required:
        - id
        - name
        - items
      properties:
        id:
          description: "ID da categoria de complemento."
          type: integer
          minimum: 1
          maximum: 2147483647
        name:
          description: "Nome da categoria de complemento; usa a pergunta da categoria quando não há nome."
          type: string
          maxLength: 255
        items:
          description: "Complementos selecionados nesta categoria."
          type: array
          maxItems: 500
          items:
            $ref: '#/components/schemas/WaiterSelectedChoice'
    WaiterOrderItem:
      type: object
      additionalProperties: false
      required:
        - id
        - amount
        - product
        - price
        - total_price
        - total_service_price
        - weight
        - use_weight
        - choices
      properties:
        id:
          description: "ID do item do pedido."
          type: integer
          minimum: 1
          maximum: 2147483647
        amount:
          description: "Quantidade do item (unidades)."
          type: number
          minimum: 0
        product:
          description: "Produto pedido (ID e nome)."
          $ref: '#/components/schemas/WaiterProductIdentity'
        price:
          type:
            - string
            - 'null'
          pattern: ^-?\d+(?:\.\d+)?$
          description: Valor decimal sem conversão para ponto flutuante.
        total_price:
          type:
            - string
            - 'null'
          pattern: ^-?\d+(?:\.\d+)?$
          description: Valor decimal sem conversão para ponto flutuante.
        total_service_price:
          type:
            - string
            - 'null'
          pattern: ^-?\d+(?:\.\d+)?$
          description: Valor decimal sem conversão para ponto flutuante.
        weight:
          description: "Peso do item em kg quando vendido por peso; 0 nos demais itens, null apenas se não informado."
          type:
            - number
            - 'null'
          minimum: 0
        use_weight:
          description: "true quando o item é vendido por peso (ver weight)."
          type: boolean
        choices:
          description: "Complementos escolhidos, agrupados por categoria de complemento."
          type: array
          maxItems: 500
          items:
            $ref: '#/components/schemas/WaiterChoiceGroup'
    WaiterOrderBasket:
      type: object
      additionalProperties: false
      required:
        - id
        - status
        - items
      properties:
        id:
          description: "ID do pedido (cesta); use em GET /v1/waiter/order-baskets/{orderBasketId}."
          type: integer
          minimum: 1
          maximum: 2147483647
        status:
          description: "Situação do pedido: pending (aguardando aceite) ou accepted (aceito)."
          type: string
          enum:
            - pending
            - accepted
        items:
          description: "Itens do pedido."
          type: array
          maxItems: 500
          items:
            $ref: '#/components/schemas/WaiterOrderItem'
    WaiterBill:
      type: object
      additionalProperties: false
      required:
        - id
        - status
        - total_price
        - total_service_price
        - order_baskets
      properties:
        id:
          description: "ID da conta individual."
          type: integer
          minimum: 1
          maximum: 2147483647
        status:
          description: "Situação da conta: open (aberta) ou closing (em fechamento)."
          type: string
          enum:
            - open
            - closing
        total_price:
          type: string
          pattern: ^-?\d+(?:\.\d+)?$
          description: Valor decimal sem conversão para ponto flutuante.
        total_service_price:
          type: string
          pattern: ^-?\d+(?:\.\d+)?$
          description: Valor decimal sem conversão para ponto flutuante.
        order_baskets:
          description: "Pedidos da conta com status pending ou accepted; demais situações são omitidas."
          type: array
          maxItems: 500
          items:
            $ref: '#/components/schemas/WaiterOrderBasket'
    WaiterSessionSummary:
      type: object
      additionalProperties: false
      required:
        - id
        - status
        - table
        - total_price
        - total_service_price
      properties:
        id:
          description: "ID da sessão de mesa; use em GET /v1/waiter/table-sessions/{sessionId}."
          type: integer
          minimum: 1
          maximum: 2147483647
        status:
          description: "Situação da sessão: open (aberta) ou closing (fechamento solicitado). Sessões encerradas não são listadas."
          type: string
          enum:
            - open
            - closing
        table:
          description: "Mesa da sessão; null quando a sessão não tem mesa vinculada."
          oneOf:
            - $ref: '#/components/schemas/WaiterTable'
            - type: 'null'
        total_price:
          type: string
          pattern: ^-?\d+(?:\.\d+)?$
          description: Valor decimal sem conversão para ponto flutuante.
        total_service_price:
          type: string
          pattern: ^-?\d+(?:\.\d+)?$
          description: Valor decimal sem conversão para ponto flutuante.
    WaiterSessionDetail:
      type: object
      additionalProperties: false
      required:
        - id
        - status
        - table
        - total_price
        - total_service_price
        - people_at_table
        - bills
      properties:
        id:
          description: "ID da sessão de mesa."
          type: integer
          minimum: 1
          maximum: 2147483647
        status:
          description: "Situação da sessão: open (aberta) ou closing (fechamento solicitado). Sessões encerradas retornam 404."
          type: string
          enum:
            - open
            - closing
        table:
          description: "Mesa da sessão."
          $ref: '#/components/schemas/WaiterTable'
        total_price:
          type: string
          pattern: ^-?\d+(?:\.\d+)?$
          description: Valor decimal sem conversão para ponto flutuante.
        total_service_price:
          type: string
          pattern: ^-?\d+(?:\.\d+)?$
          description: Valor decimal sem conversão para ponto flutuante.
        people_at_table:
          description: "Número de pessoas informado na mesa; null quando não informado."
          type:
            - integer
            - 'null'
          minimum: 0
        bills:
          description: "Contas individuais ativas (open ou closing) da sessão."
          type: array
          maxItems: 500
          items:
            $ref: '#/components/schemas/WaiterBill'
    WaiterActiveOrder:
      type: object
      additionalProperties: false
      required:
        - id
        - amount
        - product
        - order_basket_id
        - table_session_id
        - status
        - choices
      properties:
        id:
          description: "ID do item do pedido."
          type: integer
          minimum: 1
          maximum: 2147483647
        amount:
          description: "Quantidade do item (unidades)."
          type: number
          minimum: 0
        product:
          description: "Produto pedido (ID e nome)."
          $ref: '#/components/schemas/WaiterProductIdentity'
        order_basket_id:
          description: "ID do pedido (cesta) do item; use em GET /v1/waiter/order-baskets/{orderBasketId}."
          type: integer
          minimum: 1
          maximum: 2147483647
        table_session_id:
          description: "ID da sessão de mesa do item; use em GET /v1/waiter/table-sessions/{sessionId}."
          type: integer
          minimum: 1
          maximum: 2147483647
        status:
          description: "Situação do pedido: pending (aguardando aceite) ou accepted (aceito)."
          type: string
          enum:
            - pending
            - accepted
        choices:
          description: "Complementos escolhidos, agrupados por categoria."
          type: array
          maxItems: 500
          items:
            $ref: '#/components/schemas/WaiterChoiceGroup'
    WaiterBasketItems:
      type: object
      additionalProperties: false
      required:
        - id
        - items
      properties:
        id:
          description: "ID do pedido (cesta) consultado, igual ao orderBasketId do path."
          type: integer
          minimum: 1
          maximum: 2147483647
        items:
          description: "Itens do pedido, sem paginação (até 500)."
          type: array
          maxItems: 500
          items:
            $ref: '#/components/schemas/WaiterOrderItem'
    WaiterBrandPage:
      type: object
      additionalProperties: false
      required:
        - items
        - offset
        - limit
        - has_more
      properties:
        items:
          description: "Marcas da página atual, ordenados por ID crescente (até 100)."
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/WaiterBrand'
        offset:
          description: "Offset usado nesta página, igual ao enviado na query (padrão 0)."
          type: integer
          minimum: 0
          maximum: 9999999
        limit:
          description: "Tamanho fixo da página: 100."
          type: integer
          const: 100
        has_more:
          description: "true quando há mais registros; repita a chamada com offset + 100."
          type: boolean
    WaiterTablePage:
      type: object
      additionalProperties: false
      required:
        - items
        - offset
        - limit
        - has_more
      properties:
        items:
          description: "Mesas da página atual, ordenados por ID crescente (até 100)."
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/WaiterTable'
        offset:
          description: "Offset usado nesta página, igual ao enviado na query (padrão 0)."
          type: integer
          minimum: 0
          maximum: 9999999
        limit:
          description: "Tamanho fixo da página: 100."
          type: integer
          const: 100
        has_more:
          description: "true quando há mais registros; repita a chamada com offset + 100."
          type: boolean
    WaiterSessionPage:
      type: object
      additionalProperties: false
      required:
        - items
        - offset
        - limit
        - has_more
      properties:
        items:
          description: "Sessões ativas de mesa (exceto delivery) da página atual, ordenados por ID crescente (até 100)."
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/WaiterSessionSummary'
        offset:
          description: "Offset usado nesta página, igual ao enviado na query (padrão 0)."
          type: integer
          minimum: 0
          maximum: 9999999
        limit:
          description: "Tamanho fixo da página: 100."
          type: integer
          const: 100
        has_more:
          description: "true quando há mais registros; repita a chamada com offset + 100."
          type: boolean
    WaiterOrderPage:
      type: object
      additionalProperties: false
      required:
        - items
        - offset
        - limit
        - has_more
      properties:
        items:
          description: "Itens de pedidos ativos da página atual, ordenados por ID crescente (até 100)."
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/WaiterActiveOrder'
        offset:
          description: "Offset usado nesta página, igual ao enviado na query (padrão 0)."
          type: integer
          minimum: 0
          maximum: 9999999
        limit:
          description: "Tamanho fixo da página: 100."
          type: integer
          const: 100
        has_more:
          description: "true quando há mais registros; repita a chamada com offset + 100."
          type: boolean
    InventoryInputBatchEdit:
      type: object
      additionalProperties: false
      minProperties: 2
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
        unidade:
          type: string
          minLength: 1
          maxLength: 50
        ideal_stock:
          type:
            - string
            - 'null'
          pattern: ^(?:0|[1-9]\d*)(?:\.\d{1,12})?$
          maxLength: 40
          description: Decimal em texto, com ponto e até 12 casas; sem notação exponencial.
        minimum_stock:
          type:
            - string
            - 'null'
          pattern: ^(?:0|[1-9]\d*)(?:\.\d{1,12})?$
          maxLength: 40
          description: Decimal em texto, com ponto e até 12 casas; sem notação exponencial.
        unitary_price:
          type: string
          pattern: ^(?:0|[1-9]\d*)(?:\.\d{1,12})?$
          maxLength: 40
          description: Decimal em texto, com ponto e até 12 casas; sem notação exponencial.
        expected_updated_at:
          type: string
          format: date-time
        id:
          type: integer
          minimum: 1
          maximum: 2147483647
      required:
        - id
    InventoryIntermediaryBatchEdit:
      type: object
      additionalProperties: false
      minProperties: 2
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
        unidade:
          type: string
          minLength: 1
          maxLength: 50
        ideal_stock:
          type:
            - string
            - 'null'
          pattern: ^(?:0|[1-9]\d*)(?:\.\d{1,12})?$
          maxLength: 40
          description: Decimal em texto, com ponto e até 12 casas; sem notação exponencial.
        minimum_stock:
          type:
            - string
            - 'null'
          pattern: ^(?:0|[1-9]\d*)(?:\.\d{1,12})?$
          maxLength: 40
          description: Decimal em texto, com ponto e até 12 casas; sem notação exponencial.
        expected_updated_at:
          type: string
          format: date-time
        id:
          type: integer
          minimum: 1
          maximum: 2147483647
      required:
        - id
    InventoryIntermediarySheetBatchEdit:
      type: object
      additionalProperties: false
      required:
        - yield
        - inputs
        - intermediaries
        - id
      properties:
        inputs:
          type: array
          maxItems: 1000
          items:
            $ref: '#/components/schemas/InventoryIngredientRequest'
        intermediaries:
          type: array
          maxItems: 1000
          items:
            $ref: '#/components/schemas/InventoryIngredientRequest'
        expected_updated_at:
          type: string
          format: date-time
        yield:
          type: string
          pattern: ^(?:0|[1-9]\d*)(?:\.\d{1,12})?$
          maxLength: 40
          description: Rendimento positivo com até 2 casas decimais.
        recipe:
          type:
            - string
            - 'null'
          maxLength: 1000
        id:
          type: integer
          minimum: 1
          maximum: 2147483647
    InventoryTechnicalSheetBatchEdit:
      type: object
      additionalProperties: false
      required:
        - inputs
        - intermediaries
        - id
      properties:
        inputs:
          type: array
          maxItems: 1000
          items:
            $ref: '#/components/schemas/InventoryIngredientRequest'
        intermediaries:
          type: array
          maxItems: 1000
          items:
            $ref: '#/components/schemas/InventoryIngredientRequest'
        expected_updated_at:
          type: string
          format: date-time
        id:
          type: integer
          minimum: 1
          maximum: 2147483647
    FinancialCostCenter:
      type: object
      additionalProperties: false
      required: [id, name, type]
      properties:
        id: { type: integer, description: 'category_subcategory_id' }
        name: { type: string, description: 'Categoria - Subcategoria' }
        type: { type: [string, 'null'], description: 'Tipo da categoria, como insumos.' }
    FinancialBankAccount:
      type: object
      additionalProperties: false
      required: [id, name, bank_id, bank_name, total]
      properties:
        id: { description: "ID da conta bancária; use como `bank_account_id`.", type: integer }
        name: { description: "Nome da conta definido pela loja.", type: string }
        bank_id: { description: "Código COMPE do banco (3 dígitos, ex.: `001`); `null` quando a conta não tem banco vinculado.", type: [string, 'null'] }
        bank_name: { description: "Nome do banco do código `bank_id`; `null` sem banco.", type: [string, 'null'] }
        total: { type: string, description: Saldo com duas casas. }
    FinancialPaymentMethod:
      type: object
      additionalProperties: false
      required: [id, name]
      properties:
        id: { description: "ID da forma de pagamento financeira; use como `cash_flow_payment_method_id`.", type: integer }
        name: { description: "Nome da forma de pagamento definido pela loja.", type: string }
    CashFlowSettlement:
      type: object
      additionalProperties: false
      required: [paid]
      properties:
        paid: { type: boolean }
        paid_at:
          type: string
          description: Dia AAAA-MM-DD (horário de Brasília) ou instante ISO 8601 com fuso. Só com paid=true; padrão é agora.
        bank_account_id: { type: integer, minimum: 1, description: Obrigatório para pagar se o lançamento não tiver conta. }
        cash_flow_payment_method_id: { type: [integer, 'null'], minimum: 1 }
        expected_updated_at: { type: string, format: date-time }
    CashFlowSettlementBatch:
      type: object
      additionalProperties: false
      required: [items]
      properties:
        items:
          type: array
          minItems: 1
          maxItems: 100
          items:
            allOf:
              - $ref: '#/components/schemas/CashFlowSettlement'
              - type: object
                required: [id]
                properties:
                  id: { type: integer, minimum: 1 }
    CashFlowSettlementResult:
      type: object
      additionalProperties: false
      required: [id, restaurant_id, value, is_earning, is_title, paid, paid_at, bank_account_id, cash_flow_payment_method_id, updated_at]
      properties:
        id: { description: "ID do lançamento alterado.", type: integer }
        restaurant_id: { description: "ID do restaurante dono do lançamento.", type: integer }
        value: { description: "Valor do lançamento em reais, string com duas casas.", type: string }
        is_earning: { description: "`true` para receita; `false` para despesa.", type: boolean }
        is_title: { description: "`true` quando o lançamento é um título; a baixa é propagada aos lançamentos agrupados.", type: boolean }
        paid: { description: "Situação após a operação: `true` pago/recebido; `false` em aberto.", type: boolean }
        paid_at: { description: "Data e hora da baixa (ISO 8601, UTC); `null` quando em aberto.", type: [string, 'null'], format: date-time }
        bank_account_id: { description: "Conta bancária do lançamento após a operação; `null` quando não definida.", type: [integer, 'null'] }
        cash_flow_payment_method_id: { description: "Forma de pagamento financeira após a operação; `null` quando não definida.", type: [integer, 'null'] }
        updated_at: { description: "Data da última alteração (ISO 8601, UTC); use como `expected_updated_at`.", type: string, format: date-time }
    InputCostCenter:
      type: object
      additionalProperties: false
      required: [cash_flow_category_subcategory_id]
      properties:
        cash_flow_category_subcategory_id: { type: [integer, 'null'], minimum: 1 }
        expected_updated_at: { type: string, format: date-time }
    InputCostCenterBatch:
      type: object
      additionalProperties: false
      required: [items]
      properties:
        items:
          type: array
          minItems: 1
          maxItems: 100
          items:
            allOf:
              - $ref: '#/components/schemas/InputCostCenter'
              - type: object
                required: [id]
                properties:
                  id: { type: integer, minimum: 1 }
    ManagedInventoryStock:
      type: object
      additionalProperties: false
      required:
        - id
        - restaurant_id
        - name
        - unidade
        - ideal_stock
        - minimum_stock
        - quantidade
        - stock_version
        - unitary_price
        - total_value
        - is_master
        - is_multistore
        - is_multistore_child
        - cash_flow_category_subcategory_id
        - yield
        - recipe
        - created_at
        - updated_at
      properties:
        stock_version: { type: string, description: Versão para registrar contagens com controle de concorrência. }
        cash_flow_category_subcategory_id:
          type: [integer, 'null']
          description: Centro de custo (`GET /v1/financial/cost-centers`). Sempre nulo para intermediários.
        id:
          description: "ID do insumo ou intermediário; use em `GET /v1/inventory/inputs/{id}` ou `/intermediaries/{id}`."
          type: integer
        restaurant_id:
          description: "ID do restaurante dono do cadastro."
          type: integer
        name:
          description: "Nome do insumo ou intermediário."
          type: string
          minLength: 1
          maxLength: 255
        unidade:
          description: "Unidade de medida do estoque, texto livre definido pela loja (ex.: `kg`, `un`, `l`). Saldo, custo e quantidades das fichas usam essa unidade."
          type: string
          minLength: 1
          maxLength: 50
        ideal_stock:
          type:
            - string
            - 'null'
          pattern: ^(?:0|[1-9]\d*)(?:\.\d{1,12})?$
          maxLength: 40
          description: Decimal em texto, com ponto e até 12 casas; sem notação exponencial.
        minimum_stock:
          type:
            - string
            - 'null'
          pattern: ^(?:0|[1-9]\d*)(?:\.\d{1,12})?$
          maxLength: 40
          description: Decimal em texto, com ponto e até 12 casas; sem notação exponencial.
        quantidade:
          type: string
          description: Saldo atual, somente leitura.
        unitary_price:
          description: "Custo unitário em reais por `unidade`, string decimal com duas casas. Em intermediários é calculado pela ficha técnica."
          type: string
        total_value:
          description: "Valor do saldo em estoque em reais (saldo × custo unitário), string decimal com duas casas."
          type: string
        is_master:
          description: "`true` quando é o insumo mestre criado automaticamente para controlar o estoque de um produto (unidade `un`). Sempre `false` para intermediários."
          type: boolean
        is_multistore:
          description: "`true` quando o cadastro pertence à rede multilojas (matriz); é gerido pela multilojas e não pode ser editado por estas rotas."
          type: boolean
        is_multistore_child:
          description: "`true` quando o cadastro foi replicado da rede multilojas para esta loja; só o centro de custo pode ser alterado."
          type: boolean
        yield:
          description: "Rendimento da receita do intermediário (quantas `unidade` um lote produz), decimal com duas casas. Sempre `null` para insumos."
          type:
            - string
            - 'null'
        recipe:
          description: "Modo de preparo do intermediário (texto livre, até 1000 caracteres) ou `null`. Sempre `null` para insumos."
          type:
            - string
            - 'null'
        created_at:
          description: "Data de criação do cadastro (ISO 8601, UTC)."
          type: string
          format: date-time
        updated_at:
          description: "Data da última alteração (ISO 8601, UTC). Envie como `expected_updated_at` para proteger edições concorrentes."
          type: string
          format: date-time
    ManagedInventoryPage:
      type: object
      additionalProperties: false
      required:
        - items
        - total
        - count
        - remaining
        - offset
        - limit
      properties:
        items:
          description: "Cadastros desta página, ordenados por nome e ID."
          type: array
          items:
            $ref: '#/components/schemas/ManagedInventoryStock'
        total:
          description: "Total de cadastros ativos (não cancelados) da loja."
          type: integer
        count:
          description: "Quantidade de itens retornados nesta página."
          type: integer
        remaining:
          description: "Itens ainda não retornados (total − offset − count, mínimo 0). Zero indica a última página."
          type: integer
        offset:
          description: "Deslocamento aplicado nesta consulta."
          type: integer
        limit:
          description: "Tamanho máximo da página, fixo em 100."
          type: integer
          const: 100
    InventoryIngredientRequest:
      type: object
      additionalProperties: false
      required:
        - id
        - quantidade
      properties:
        id:
          type: integer
          minimum: 1
          maximum: 2147483647
        quantidade:
          type: string
          pattern: ^(?:0|[1-9]\d*)(?:\.\d{1,12})?$
          maxLength: 40
          description: >-
            Positiva; intermediários usam quantidade por lote, produtos/complementos por unidade
            vendida.
    InventoryInputCreate:
      type: object
      additionalProperties: false
      required:
        - name
        - unidade
      properties:
        cash_flow_category_subcategory_id:
          type: [integer, 'null']
          minimum: 1
          description: Centro de custo da loja (`GET /v1/financial/cost-centers`).
        name:
          type: string
          minLength: 1
          maxLength: 255
        unidade:
          type: string
          minLength: 1
          maxLength: 50
        ideal_stock:
          type:
            - string
            - 'null'
          pattern: ^(?:0|[1-9]\d*)(?:\.\d{1,12})?$
          maxLength: 40
          description: Decimal em texto, com ponto e até 12 casas; sem notação exponencial.
        minimum_stock:
          type:
            - string
            - 'null'
          pattern: ^(?:0|[1-9]\d*)(?:\.\d{1,12})?$
          maxLength: 40
          description: Decimal em texto, com ponto e até 12 casas; sem notação exponencial.
        unitary_price:
          type: string
          pattern: ^(?:0|[1-9]\d*)(?:\.\d{1,12})?$
          maxLength: 40
          description: Não negativo, até duas casas; padrão 0.00.
    InventoryInputUpdate:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
        unidade:
          type: string
          minLength: 1
          maxLength: 50
        ideal_stock:
          type:
            - string
            - 'null'
          pattern: ^(?:0|[1-9]\d*)(?:\.\d{1,12})?$
          maxLength: 40
          description: Decimal em texto, com ponto e até 12 casas; sem notação exponencial.
        minimum_stock:
          type:
            - string
            - 'null'
          pattern: ^(?:0|[1-9]\d*)(?:\.\d{1,12})?$
          maxLength: 40
          description: Decimal em texto, com ponto e até 12 casas; sem notação exponencial.
        unitary_price:
          type: string
          pattern: ^(?:0|[1-9]\d*)(?:\.\d{1,12})?$
          maxLength: 40
          description: Decimal em texto, com ponto e até 12 casas; sem notação exponencial.
        expected_updated_at:
          type: string
          format: date-time
    InventoryIntermediaryCreate:
      type: object
      additionalProperties: false
      required:
        - name
        - unidade
        - yield
        - inputs
        - intermediaries
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
        unidade:
          type: string
          minLength: 1
          maxLength: 50
        ideal_stock:
          type:
            - string
            - 'null'
          pattern: ^(?:0|[1-9]\d*)(?:\.\d{1,12})?$
          maxLength: 40
          description: Decimal em texto, com ponto e até 12 casas; sem notação exponencial.
        minimum_stock:
          type:
            - string
            - 'null'
          pattern: ^(?:0|[1-9]\d*)(?:\.\d{1,12})?$
          maxLength: 40
          description: Decimal em texto, com ponto e até 12 casas; sem notação exponencial.
        inputs:
          type: array
          maxItems: 1000
          items:
            $ref: '#/components/schemas/InventoryIngredientRequest'
        intermediaries:
          type: array
          maxItems: 1000
          items:
            $ref: '#/components/schemas/InventoryIngredientRequest'
        yield:
          type: string
          pattern: ^(?:0|[1-9]\d*)(?:\.\d{1,12})?$
          maxLength: 40
          description: Rendimento positivo com até 2 casas decimais.
        recipe:
          type:
            - string
            - 'null'
          maxLength: 1000
    InventoryIntermediaryUpdate:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
        unidade:
          type: string
          minLength: 1
          maxLength: 50
        ideal_stock:
          type:
            - string
            - 'null'
          pattern: ^(?:0|[1-9]\d*)(?:\.\d{1,12})?$
          maxLength: 40
          description: Decimal em texto, com ponto e até 12 casas; sem notação exponencial.
        minimum_stock:
          type:
            - string
            - 'null'
          pattern: ^(?:0|[1-9]\d*)(?:\.\d{1,12})?$
          maxLength: 40
          description: Decimal em texto, com ponto e até 12 casas; sem notação exponencial.
        expected_updated_at:
          type: string
          format: date-time
    InventoryTechnicalSheetUpdate:
      type: object
      additionalProperties: false
      required:
        - inputs
        - intermediaries
      properties:
        inputs:
          type: array
          maxItems: 1000
          items:
            $ref: '#/components/schemas/InventoryIngredientRequest'
        intermediaries:
          type: array
          maxItems: 1000
          items:
            $ref: '#/components/schemas/InventoryIngredientRequest'
        expected_updated_at:
          type: string
          format: date-time
    InventoryIntermediarySheetUpdate:
      type: object
      additionalProperties: false
      required:
        - yield
        - inputs
        - intermediaries
      properties:
        inputs:
          type: array
          maxItems: 1000
          items:
            $ref: '#/components/schemas/InventoryIngredientRequest'
        intermediaries:
          type: array
          maxItems: 1000
          items:
            $ref: '#/components/schemas/InventoryIngredientRequest'
        expected_updated_at:
          type: string
          format: date-time
        yield:
          type: string
          pattern: ^(?:0|[1-9]\d*)(?:\.\d{1,12})?$
          maxLength: 40
          description: Rendimento positivo com até 2 casas decimais.
        recipe:
          type:
            - string
            - 'null'
          maxLength: 1000
    InventorySheetIngredient:
      type: object
      additionalProperties: false
      required:
        - id
        - name
        - unidade
        - quantidade
        - unitary_price
      properties:
        id:
          description: "ID do insumo ou intermediário usado (não do vínculo); use em `/v1/inventory/inputs/{id}` ou `/intermediaries/{id}`."
          type: integer
        name:
          description: "Nome do insumo ou intermediário usado."
          type: string
        unidade:
          description: "Unidade de medida do ingrediente; `quantidade` é expressa nela."
          type: string
        quantidade:
          description: "Quantidade do ingrediente na unidade dele, string decimal: por lote em intermediários (valor armazenado × `yield`) e por unidade vendida em produtos/complementos."
          type: string
        unitary_price:
          description: "Custo unitário atual do ingrediente em reais por `unidade`, com duas casas."
          type: string
    InventoryTechnicalSheet:
      type: object
      additionalProperties: false
      required:
        - id
        - restaurant_id
        - kind
        - name
        - updated_at
        - is_multistore
        - is_multistore_child
        - quantity_basis
        - yield
        - recipe
        - inputs
        - intermediaries
        - master_input
        - cost
      properties:
        id:
          description: "ID do dono da ficha: intermediário, produto ou complemento, conforme `kind`."
          type: integer
        restaurant_id:
          description: "ID do restaurante dono da ficha."
          type: integer
        kind:
          description: "Tipo do dono da ficha: `intermediary` (intermediário), `product` (produto) ou `complement` (complemento)."
          type: string
          enum:
            - intermediary
            - product
            - complement
        name:
          description: "Nome do intermediário, produto ou complemento dono da ficha."
          type: string
        updated_at:
          description: "Última alteração do dono da ficha (ISO 8601, UTC); use como `expected_updated_at` no PUT da ficha."
          type: string
          format: date-time
        is_multistore:
          description: "`true` quando o dono da ficha pertence à rede multilojas; a ficha é gerida pela multilojas."
          type: boolean
        is_multistore_child:
          description: "`true` quando o dono da ficha foi replicado da rede multilojas para esta loja."
          type: boolean
        quantity_basis:
          description: "Base das quantidades: `batch` (intermediário; quantidades do lote inteiro que rende `yield`) ou `sale_unit` (produto/complemento; por unidade vendida)."
          type: string
          enum:
            - batch
            - sale_unit
        yield:
          description: "Rendimento do lote do intermediário, na unidade dele, com duas casas. `null` para produtos e complementos."
          type:
            - string
            - 'null'
        recipe:
          description: "Modo de preparo do intermediário ou `null`. Sempre `null` para produtos e complementos."
          type:
            - string
            - 'null'
        inputs:
          description: "Insumos da composição (exceto o insumo mestre, que vem em `master_input`), em ordem de vínculo."
          type: array
          items:
            $ref: '#/components/schemas/InventorySheetIngredient'
        intermediaries:
          description: "Intermediários usados na composição, em ordem de vínculo."
          type: array
          items:
            $ref: '#/components/schemas/InventorySheetIngredient'
        master_input:
          description: "Insumo mestre do produto (controle de estoque do próprio produto), somente leitura; `null` quando não há, e sempre para intermediários e complementos."
          anyOf:
            - $ref: '#/components/schemas/InventorySheetIngredient'
            - type: 'null'
        cost:
          type: string
          description: Custo da receita/lote ou da unidade vendida; não é preço de venda.

    TableSessionStatusTimings:
      type: object
      additionalProperties: false
      required:
        - start_time
        - accepted_at
        - ready_at
        - ongoing_at
        - delivered_at
        - end_time
        - completed_at
        - delivery_canceled_at
      properties:
        start_time:
          type: [string, "null"]
          format: date-time
          description: Horário de início da sessão.
        accepted_at:
          type: [string, "null"]
          format: date-time
          description: Horário em que o pedido foi aceito.
        ready_at:
          type: [string, "null"]
          format: date-time
          description: Horário em que o pedido ficou pronto.
        ongoing_at:
          type: [string, "null"]
          format: date-time
          description: Horário em que o pedido entrou em rota.
        delivered_at:
          type: [string, "null"]
          format: date-time
          description: Horário em que o pedido foi entregue.
        end_time:
          type: [string, "null"]
          format: date-time
          description: Horário de encerramento da sessão.
        completed_at:
          type: [string, "null"]
          format: date-time
          description: Horário de conclusão da sessão.
        delivery_canceled_at:
          type: [string, "null"]
          format: date-time
          description: Horário de cancelamento da entrega.
    SessionMotoboy:
      type: object
      additionalProperties: false
      required: [id, name, phone]
      properties:
        id:
          description: "ID do entregador."
          type: integer
        name:
          description: "Nome do entregador; null quando não cadastrado."
          type: [string, "null"]
        phone:
          description: "Telefone do entregador como cadastrado; null quando ausente."
          type: [string, "null"]
    SessionIntendedPaymentMethod:
      type: object
      additionalProperties: false
      required: [id, name, keyword, method, brand]
      description: Forma escolhida para o pedido, independente dos pagamentos registrados.
      properties:
        id:
          description: "ID da forma de pagamento escolhida; use em GET /v1/payment-methods."
          type: integer
        name:
          description: "Nome da forma escolhida como cadastrada."
          type: string
        keyword:
          description: "Identificador textual (slug) da forma escolhida."
          type: string
        method:
          description: "Tipo do meio de pagamento (ex.: CREDIT, PIX); null em formas sem tipo."
          type: [string, "null"]
        brand:
          description: "Bandeira do cartão; null quando não se aplica."
          type: [string, "null"]
    SessionIntendedPayments:
      type: object
      additionalProperties: false
      required: [payment_method, change_for, is_prepaid, ifood_paid]
      description: >-
        Intenção de pagamento e sinalizadores originais do pedido, independentes dos
        pagamentos registrados. Sempre presente, mesmo antes de um recebimento.
        A API não calcula necessidade de maquininha nem troco a preparar: essas
        orientações dependem do saldo, da forma, do canal e dos sinalizadores.
        Consulte /externo/v1/pagamentos-na-entrega para os exemplos e regras do Comandas.
      properties:
        payment_method:
          description: Forma pretendida no checkout. Null quando ausente ou com vínculo contraditório; não comprova recebimento.
          oneOf:
            - $ref: "#/components/schemas/SessionIntendedPaymentMethod"
            - type: "null"
        change_for:
          type: [string, "null"]
          pattern: '^-?[0-9]+\.[0-9]{2}$'
          description: Valor original armazenado em user_change. No checkout nativo é o valor entregue pelo cliente (troco para), não o troco devolvido em payments[].change. Valores de integrações são preservados sem normalização; null e 0.00 permanecem distintos.
          examples: ["100.00", "0.00", null]
        is_prepaid:
          type: boolean
          description: Sinalizador original de pré-pagamento da sessão, sem inferência por nome da forma ou recálculo financeiro.
        ifood_paid:
          type: boolean
          description: Sinalizador legado de pagamento informado pela integração, preservado como armazenado. Também pode ser utilizado por outros canais.
    SessionCoupon:
      type: object
      required: [transaction_id, id, code, name, title, discount_type, discount, currency]
      properties:
        transaction_id:
          type: integer
          description: ID do uso do cupom nesta compra.
        id:
          type: integer
          description: ID do cupom utilizado.
        code:
          type: string
          description: Código atual do cupom no cadastro.
          example: SAVE10
        name:
          type: [string, "null"]
          description: Nome atual do cupom, quando cadastrado.
        title:
          type: string
          description: Título atual do cupom.
        discount_type:
          type: string
          description: Tipo registrado no uso do cupom, como percentage, absolute ou free-shipping.
        discount:
          type: string
          description: Valor monetário registrado na transação, com duas casas decimais. Não é o percentual nem um recálculo pela regra atual do cupom.
          example: "12.50"
        currency:
          description: "Moeda registrada no uso do cupom (padrão BRL)."
          type: string
          example: BRL
    TableSessionV1:
      allOf:
        - $ref: "./openapi.yaml#/components/schemas/TableSession"
        - type: object
          required: [status_timings, session_number, motoboy_id, motoboy, intended_payments, coupons]
          properties:
            coupons:
              type: array
              description: Usos não cancelados de cupons, ordenados pelo ID da transação; lista vazia quando ausentes. Vínculos ausentes ou de outro restaurante são omitidos. Cupons globais são aceitos; inativação ou exclusão lógica do cadastro não apaga o uso histórico. Código, nome e título refletem o cadastro atual, enquanto tipo, desconto e moeda vêm da transação.
              items:
                $ref: "#/components/schemas/SessionCoupon"
            intended_payments:
              $ref: "#/components/schemas/SessionIntendedPayments"
            session_number:
              type: [integer, "null"]
              description: Sequência da comanda no restaurante, independente do ID interno e da senha.
            motoboy_id:
              type: [integer, "null"]
              description: ID do entregador atribuído, com vínculo validado pelo restaurante.
            motoboy:
              description: "Entregador atribuído ao pedido; null sem entregador ou quando ele não pertence ao restaurante."
              oneOf:
                - $ref: "#/components/schemas/SessionMotoboy"
                - type: "null"
            status_timings:
              description: "Horários de cada etapa do pedido (ISO 8601, UTC); cada campo é null quando a etapa não ocorreu."
              $ref: "#/components/schemas/TableSessionStatusTimings"
    CreateProductCategoryRequest:
      type: object
      additionalProperties: false
      required: [name, brand_id]
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Nome da categoria. Espaços nas extremidades são removidos; não pode conter apenas espaços.
        brand_id:
          type: integer
          minimum: 1
          maximum: 2147483647
          description: Marca não removida do mesmo restaurante autorizado.
        available:
          type: boolean
          default: true
          description: Disponibilidade para venda presencial.
        available_in_delivery:
          type: boolean
          default: true
          description: Disponibilidade para delivery e retirada neste fluxo.
        available_in_self_service:
          type: boolean
          default: true
          description: Disponibilidade no autoatendimento.
        available_in_drive_thru:
          type: boolean
          default: false
          description: Disponibilidade no drive-thru.
        is_exclusive:
          type: boolean
          default: false
          description: Indica uma categoria exclusiva.
        custom_order:
          type: integer
          minimum: 0
          maximum: 2147483647
          default: 100
          description: Ordem de exibição da categoria.
        preparation_time:
          type: [integer, "null"]
          minimum: 0
          maximum: 2147483647
          description: Tempo de preparo cadastrado, em minutos.

    UpdateProductCategoryRequest:
      type: object
      additionalProperties: false
      description: |
        Atualização parcial. Pelo menos um campo editável deve ser enviado;
        `expected_updated_at` sozinho não constitui uma alteração. Campos
        omitidos mantêm seus valores atuais.
      anyOf:
        - required: [name]
        - required: [available]
        - required: [available_in_delivery]
        - required: [available_in_self_service]
        - required: [available_in_drive_thru]
        - required: [is_exclusive]
        - required: [custom_order]
        - required: [preparation_time]
      properties:
        brand_id:
          type: integer
          minimum: 1
          maximum: 2147483647
          description: Marca existente é imutável.
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Nome da categoria. Espaços nas extremidades são removidos; não pode conter apenas espaços.
        available:
          type: boolean
          description: Disponibilidade para venda presencial.
        available_in_delivery:
          type: boolean
          description: Disponibilidade para delivery e retirada neste fluxo.
        available_in_self_service:
          type: boolean
          description: Disponibilidade no autoatendimento.
        available_in_drive_thru:
          type: boolean
          description: Disponibilidade no drive-thru.
        is_exclusive:
          type: boolean
          description: Indica uma categoria exclusiva.
        custom_order:
          type: integer
          minimum: 0
          maximum: 2147483647
          description: Ordem de exibição da categoria.
        preparation_time:
          type: [integer, "null"]
          minimum: 0
          maximum: 2147483647
          description: Tempo de preparo cadastrado, em minutos; null remove o valor.
        expected_updated_at:
          type: string
          format: date-time
          description: Copie `updated_at` da última consulta; uma versão diferente retorna 409 `product_category_conflict`.

    ManagedProductCategory:
      type: object
      additionalProperties: false
      description: Estado atual de uma categoria de produtos não removida.
      required:
        - id
        - restaurant_id
        - brand_id
        - name
        - available
        - available_in_delivery
        - available_in_self_service
        - available_in_drive_thru
        - is_exclusive
        - custom_order
        - preparation_time
        - created_at
        - updated_at
      properties:
        id:
          description: "Identificador da categoria de produtos."
          type: integer
          minimum: 1
          maximum: 2147483647
        restaurant_id:
          description: "ID do restaurante dono da categoria."
          type: integer
          minimum: 1
          maximum: 2147483647
        brand_id:
          description: "ID da marca à qual a categoria pertence; imutável após a criação."
          type: integer
          minimum: 1
          maximum: 2147483647
        name:
          description: "Nome da categoria."
          type: string
          minLength: 1
          maxLength: 255
        available:
          description: "Categoria habilitada para venda presencial."
          type: boolean
        available_in_delivery:
          description: "Categoria habilitada para delivery/retirada."
          type: boolean
        available_in_self_service:
          description: "Categoria habilitada no autoatendimento (totem)."
          type: boolean
        available_in_drive_thru:
          description: "Categoria habilitada no drive-thru."
          type: boolean
        is_exclusive:
          description: "Uso exclusivo da equipe: true oculta a categoria nos apps do cliente (só garçom/PDV)."
          type: boolean
        custom_order:
          description: "Posição da categoria no cardápio (crescente)."
          type: integer
          minimum: 0
          maximum: 2147483647
        preparation_time:
          description: "Tempo de preparo da categoria, em minutos; null quando não configurado."
          type: [integer, "null"]
          minimum: 0
          maximum: 2147483647
        created_at:
          description: "Data de criação da categoria (ISO 8601, UTC)."
          type: string
          format: date-time
        updated_at:
          description: "Última alteração da categoria (ISO 8601, UTC); envie como expected_updated_at para detectar conflito."
          type: string
          format: date-time

    CreateComplementCategoryRequest:
      type: object
      additionalProperties: false
      required: [name, brand_id]
      properties:
        name: { type: string, minLength: 1, maxLength: 255 }
        brand_id: { type: integer, minimum: 1, maximum: 2147483647 }
        question: { type: string, nullable: true, maxLength: 255 }
        limit: { type: integer, minimum: 0, maximum: 2147483647 }
        minimum: { type: integer, nullable: true, minimum: 0, maximum: 2147483647 }
        available: { type: boolean }
        available_in_delivery: { type: boolean }
        optional: { type: boolean }
        single_choice: { type: boolean }
        additional: { type: boolean }
        more_expensive_only: { type: boolean }
        use_average: { type: boolean }
        complement_ids: { type: array, maxItems: 100, uniqueItems: true, items: { type: integer, minimum: 1, maximum: 2147483647 } }
    UpdateComplementCategoryRequest:
      type: object
      minProperties: 1
      additionalProperties: false
      properties:
        name: { type: string, minLength: 1, maxLength: 255 }
        brand_id: { type: integer, minimum: 1, maximum: 2147483647 }
        question: { type: string, nullable: true, maxLength: 255 }
        limit: { type: integer, minimum: 0, maximum: 2147483647 }
        minimum: { type: integer, nullable: true, minimum: 0, maximum: 2147483647 }
        available: { type: boolean }
        available_in_delivery: { type: boolean }
        optional: { type: boolean }
        single_choice: { type: boolean }
        additional: { type: boolean }
        more_expensive_only: { type: boolean }
        use_average: { type: boolean }
        complement_ids: { type: array, maxItems: 100, uniqueItems: true, items: { type: integer, minimum: 1, maximum: 2147483647 } }
        expected_updated_at: { type: string, format: date-time }
    ManagedComplementCategory:
      type: object
      additionalProperties: false
      required: [name, brand_id, question, limit, minimum, available, available_in_delivery, optional, single_choice, additional, more_expensive_only, use_average, complement_ids, id, restaurant_id, created_at, updated_at]
      properties:
        name: { description: "Nome do grupo de complementos.", type: string, minLength: 1, maxLength: 255 }
        brand_id: { description: "ID da marca do grupo (`GET /v1/brands`); imutável após a criação.", type: integer, minimum: 1, maximum: 2147483647 }
        question: { description: "Pergunta exibida ao cliente ao escolher os complementos; pode ser `null`.", type: string, nullable: true, maxLength: 255 }
        limit: { description: "Quantidade máxima de complementos escolhidos no grupo.", type: integer, minimum: 0, maximum: 2147483647 }
        minimum: { description: "Quantidade mínima de complementos no grupo; não excede `limit`. Pode ser `null` em grupos antigos (sem normalização).", type: integer, nullable: true, minimum: 0, maximum: 2147483647 }
        available: { description: "Grupo disponível na venda presencial.", type: boolean }
        available_in_delivery: { description: "Grupo disponível no delivery.", type: boolean }
        optional: { description: "`true` permite não escolher nenhum complemento; `false` torna o grupo obrigatório.", type: boolean }
        single_choice: { description: "Permite escolher apenas uma opção; exige `limit` 1.", type: boolean }
        additional: { description: "Regra de preço: `true` cobra o preço dos complementos escolhidos; `false` não cobra.", type: boolean }
        more_expensive_only: { description: "Regra de preço: cobra apenas o complemento mais caro escolhido.", type: boolean }
        use_average: { description: "Regra de preço: cobra a média dos complementos escolhidos.", type: boolean }
        complement_ids: { description: "IDs dos complementos ativos vinculados ao grupo (até 100); vazio em grupos sem vínculos.", type: array, maxItems: 100, uniqueItems: true, items: { type: integer, minimum: 1, maximum: 2147483647 } }
        id: { description: "ID do grupo de complementos.", type: integer, minimum: 1, maximum: 2147483647 }
        restaurant_id: { description: "ID do restaurante dono do grupo.", type: integer, minimum: 1, maximum: 2147483647 }
        created_at: { description: "Data de criação (ISO 8601, UTC).", type: string, format: date-time }
        updated_at: { description: "Data da última alteração (ISO 8601, UTC); use como `expected_updated_at`.", type: string, format: date-time }
    CreateComplementRequest:
      type: object
      additionalProperties: false
      required: [name, brand_id, price]
      properties:
        name: { type: string, minLength: 1, maxLength: 255 }
        brand_id: { type: integer, minimum: 1, maximum: 2147483647 }
        price: { type: number, minimum: 0, maximum: 9999999999999.99, multipleOf: 0.01 }
        description: { type: string, nullable: true, maxLength: 255 }
        delivery_price: { type: number, nullable: true, minimum: 0, maximum: 9999999999999.99, multipleOf: 0.01 }
        available: { type: boolean }
        available_in_delivery: { type: boolean }
        limit: { type: integer, minimum: 0, maximum: 2147483647 }
        show_on_report: { type: boolean }
        category_ids: { type: array, maxItems: 100, uniqueItems: true, items: { type: integer, minimum: 1, maximum: 2147483647 } }
    FiscalBrand:
      type: object
      properties:
        id:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: Identificador do registro na Takeat.
        restaurant_id:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: Restaurante autorizado ao qual o registro pertence.
        tax_regime:
          type: string
          description: >-
            Regime tributário do restaurante proprietário da marca, preservado
            como cadastrado. A API não infere nem normaliza este valor.
        identity:
          type: object
          properties:
            name:
              type: string
              description: Nome cadastrado.
            fantasy_name:
              anyOf:
                - type: string
                - type: 'null'
              description: Nome fantasia.
            cnpj:
              anyOf:
                - type: string
                - type: 'null'
              description: CNPJ preservado como texto, incluindo zeros à esquerda.
          required:
            - name
            - fantasy_name
            - cnpj
          additionalProperties: false
          description: Identificação comercial e fiscal da marca.
        status:
          type: object
          properties:
            active:
              type: boolean
              description: Indica se a marca está ativa. Marcas inativas não excluídas também são retornadas.
            default:
              type: boolean
              description: Indica a marca padrão do restaurante.
          required:
            - active
            - default
          additionalProperties: false
          description: Situação fiscal e disponibilidade do documento completo.
        image:
          anyOf:
            - type: object
              properties:
                id:
                  type: integer
                  minimum: -9007199254740991
                  maximum: 9007199254740991
                  description: Identificador do registro na Takeat.
                path:
                  type: string
                  description: Caminho armazenado do arquivo.
                url:
                  type: string
                  description: URL armazenada; na imagem, URL derivada usando a configuração de arquivos.
              required:
                - id
                - path
                - url
              additionalProperties: false
            - type: 'null'
          description: Arquivo da imagem ou null; URL derivada como no legado.
        timestamps:
          type: object
          properties:
            created_at:
              anyOf:
                - 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))$
                - type: 'null'
              description: Data de criação do registro local, em UTC.
            updated_at:
              anyOf:
                - 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))$
                - type: 'null'
              description: Data da última atualização local, em UTC.
          required:
            - created_at
            - updated_at
          additionalProperties: false
          description: Datas do registro. A emissão do detalhe vem da Focus e pode manter seu offset.
      required:
        - id
        - restaurant_id
        - tax_regime
        - identity
        - status
        - image
        - timestamps
      additionalProperties: false
    ReceivedNfe:
      type: object
      properties:
        id:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: Identificador do registro na Takeat.
        restaurant_id:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: Restaurante autorizado ao qual o registro pertence.
        brand_id:
          anyOf:
            - type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
          description: Marca originalmente vinculada à nota; null em notas antigas sem vínculo.
        brand:
          anyOf:
            - type: object
              properties:
                id:
                  type: integer
                  minimum: -9007199254740991
                  maximum: 9007199254740991
                  description: Identificador do registro na Takeat.
                name:
                  type: string
                  description: Nome cadastrado.
                fantasy_name:
                  anyOf:
                    - type: string
                    - type: 'null'
                  description: Nome fantasia.
                cnpj:
                  anyOf:
                    - type: string
                    - type: 'null'
                  description: CNPJ preservado como texto, incluindo zeros à esquerda.
              required:
                - id
                - name
                - fantasy_name
                - cnpj
              additionalProperties: false
            - type: 'null'
          description: Marca vinculada ou marca padrão usada como apresentação para notas sem vínculo.
        identification:
          type: object
          properties:
            access_key:
              type: string
              description: Chave de acesso de 44 dígitos, preservada como texto.
            number:
              anyOf:
                - type: string
                - type: 'null'
              description: Número da nota; na listagem é extraído da chave e preserva os nove dígitos.
            series:
              anyOf:
                - type: string
                - type: 'null'
              description: Série armazenada localmente, ou null.
            state:
              anyOf:
                - type: string
                - type: 'null'
              description: UF armazenada localmente, ou null.
            type:
              anyOf:
                - type: string
                - type: 'null'
              description: Código/tipo informado na origem; não é normalizado.
          required:
            - access_key
            - number
            - series
            - state
            - type
          additionalProperties: false
          description: Identificação da nota fiscal.
        issuer:
          type: object
          properties:
            name:
              type: string
              description: Nome cadastrado.
            document:
              type: string
              description: Documento do emitente, preservado como texto.
          required:
            - name
            - document
          additionalProperties: false
          description: Identificação do emitente/fornecedor.
        amounts:
          type: object
          properties:
            total:
              type: string
              description: >-
                Valor total em texto decimal; a listagem mantém duas casas e o detalhe mantém a precisão
                da Focus.
          required:
            - total
          additionalProperties: false
          description: Valores monetários da nota.
        status:
          type: object
          properties:
            situation:
              type: string
              description: Situação da nota na origem, como autorizada.
            complete:
              type: boolean
              description: Indica disponibilidade da NF-e completa; não significa que a operação foi confirmada.
          required:
            - situation
            - complete
          additionalProperties: false
          description: Situação fiscal e disponibilidade do documento completo.
        manifestation:
          type: object
          properties:
            type:
              anyOf:
                - type: string
                - type: 'null'
              description: Código/tipo informado na origem; não é normalizado.
            manifested_at:
              anyOf:
                - 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))$
                - type: 'null'
              description: Data local da manifestação ou null.
          required:
            - type
            - manifested_at
          additionalProperties: false
          description: Manifestação do destinatário.
        correction:
          type: object
          properties:
            number:
              anyOf:
                - type: integer
                  minimum: -9007199254740991
                  maximum: 9007199254740991
                - type: 'null'
              description: Número sequencial da carta de correção registrada localmente, ou null.
            text:
              anyOf:
                - type: string
                - type: 'null'
              description: Texto da carta de correção ou null.
            issued_at:
              anyOf:
                - 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))$
                - type: 'null'
              description: Data de emissão da carta de correção registrada localmente, em UTC, ou null.
          required:
            - number
            - text
            - issued_at
          additionalProperties: false
          description: Última carta de correção registrada localmente.
        cancellation:
          type: object
          properties:
            canceled_at:
              anyOf:
                - 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))$
                - type: 'null'
              description: Data de cancelamento fiscal ou null.
            reason:
              anyOf:
                - type: string
                - type: 'null'
              description: Justificativa do cancelamento ou null.
            locally_canceled_at:
              anyOf:
                - 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))$
                - type: 'null'
              description: Data de cancelamento local ou null.
          required:
            - canceled_at
            - reason
            - locally_canceled_at
          additionalProperties: false
          description: Cancelamento fiscal e cancelamento local são informações distintas.
        references:
          type: object
          properties:
            return_reference:
              anyOf:
                - type: string
                - type: 'null'
              description: Referência da devolução, ou null.
            reference:
              anyOf:
                - type: string
                - type: 'null'
              description: Referência local de emissão/processamento, ou null.
            url:
              anyOf:
                - type: string
                - type: 'null'
              description: URL armazenada; na imagem, URL derivada usando a configuração de arquivos.
            provider_id:
              anyOf:
                - type: integer
                  minimum: -9007199254740991
                  maximum: 9007199254740991
                - type: 'null'
              description: >-
                Fornecedor Takeat. Na lista é o vínculo armazenado; no detalhe é a busca por documento
                do emitente entre fornecedores ativos do restaurante.
          required:
            - return_reference
            - reference
            - url
            - provider_id
          additionalProperties: false
          description: Referências locais de integração e fornecedor.
        fiscal:
          type: object
          properties:
            version:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
              description: Versão de distribuição da nota.
            digest:
              anyOf:
                - type: string
                - type: 'null'
              description: Digest da nota, ou null.
            sped:
              description: Conteúdo fiscal SPED local (JSON) ou null.
          required:
            - version
            - digest
            - sped
          additionalProperties: false
          description: Metadados fiscais.
        timestamps:
          type: object
          properties:
            issued_at:
              type: string
              description: Data e hora de emissão; a listagem usa UTC e o detalhe preserva o offset da Focus.
            processing_at:
              anyOf:
                - 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))$
                - type: 'null'
              description: Data de início do processamento local, ou null.
            created_at:
              anyOf:
                - 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))$
                - type: 'null'
              description: Data de criação do registro local, em UTC.
            updated_at:
              anyOf:
                - 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))$
                - type: 'null'
              description: Data da última atualização local, em UTC.
          required:
            - issued_at
            - processing_at
            - created_at
            - updated_at
          additionalProperties: false
          description: Datas do registro. A emissão do detalhe vem da Focus e pode manter seu offset.
      required:
        - id
        - restaurant_id
        - brand_id
        - brand
        - identification
        - issuer
        - amounts
        - status
        - manifestation
        - correction
        - cancellation
        - references
        - fiscal
        - timestamps
      additionalProperties: false
    ReceivedNfeDetail:
      type: object
      properties:
        id:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: Identificador do registro na Takeat.
        restaurant_id:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: Restaurante autorizado ao qual o registro pertence.
        brand_id:
          anyOf:
            - type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
          description: Marca originalmente vinculada à nota; null em notas antigas sem vínculo.
        brand:
          anyOf:
            - type: object
              properties:
                id:
                  type: integer
                  minimum: -9007199254740991
                  maximum: 9007199254740991
                  description: Identificador do registro na Takeat.
                name:
                  type: string
                  description: Nome cadastrado.
                fantasy_name:
                  anyOf:
                    - type: string
                    - type: 'null'
                  description: Nome fantasia.
                cnpj:
                  anyOf:
                    - type: string
                    - type: 'null'
                  description: CNPJ preservado como texto, incluindo zeros à esquerda.
              required:
                - id
                - name
                - fantasy_name
                - cnpj
              additionalProperties: false
            - type: 'null'
          description: Marca vinculada ou marca padrão usada como apresentação para notas sem vínculo.
        identification:
          type: object
          properties:
            access_key:
              type: string
              description: Chave de acesso de 44 dígitos, preservada como texto.
            number:
              anyOf:
                - type: string
                - type: 'null'
              description: Número da nota; na listagem é extraído da chave e preserva os nove dígitos.
            series:
              anyOf:
                - type: string
                - type: 'null'
              description: Série armazenada localmente, ou null.
            state:
              anyOf:
                - type: string
                - type: 'null'
              description: UF armazenada localmente, ou null.
            type:
              anyOf:
                - type: string
                - type: 'null'
              description: Código/tipo informado na origem; não é normalizado.
          required:
            - access_key
            - number
            - series
            - state
            - type
          additionalProperties: false
          description: Identificação da nota fiscal.
        issuer:
          type: object
          properties:
            name:
              type: string
              description: Nome cadastrado.
            document:
              type: string
              description: Documento do emitente, preservado como texto.
          required:
            - name
            - document
          additionalProperties: false
          description: Identificação do emitente/fornecedor.
        amounts:
          type: object
          properties:
            total:
              type: string
              description: >-
                Valor total em texto decimal; a listagem mantém duas casas e o detalhe mantém a precisão
                da Focus.
          required:
            - total
          additionalProperties: false
          description: Valores monetários da nota.
        status:
          type: object
          properties:
            situation:
              type: string
              description: Situação da nota na origem, como autorizada.
            complete:
              type: boolean
              description: Indica disponibilidade da NF-e completa; não significa que a operação foi confirmada.
          required:
            - situation
            - complete
          additionalProperties: false
          description: Situação fiscal e disponibilidade do documento completo.
        manifestation:
          type: object
          properties:
            type:
              anyOf:
                - type: string
                - type: 'null'
              description: Código/tipo informado na origem; não é normalizado.
            manifested_at:
              anyOf:
                - 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))$
                - type: 'null'
              description: Data local da manifestação ou null.
          required:
            - type
            - manifested_at
          additionalProperties: false
          description: Manifestação do destinatário.
        correction:
          type: object
          properties:
            number:
              anyOf:
                - type: integer
                  minimum: -9007199254740991
                  maximum: 9007199254740991
                - type: 'null'
              description: Número sequencial da carta de correção registrada localmente, ou null.
            text:
              anyOf:
                - type: string
                - type: 'null'
              description: Texto da carta de correção ou null.
            issued_at:
              anyOf:
                - 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))$
                - type: 'null'
              description: Data de emissão da carta de correção registrada localmente, em UTC, ou null.
          required:
            - number
            - text
            - issued_at
          additionalProperties: false
          description: Última carta de correção registrada localmente.
        cancellation:
          type: object
          properties:
            canceled_at:
              anyOf:
                - 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))$
                - type: 'null'
              description: Data de cancelamento fiscal ou null.
            reason:
              anyOf:
                - type: string
                - type: 'null'
              description: Justificativa do cancelamento ou null.
            locally_canceled_at:
              anyOf:
                - 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))$
                - type: 'null'
              description: Data de cancelamento local ou null.
          required:
            - canceled_at
            - reason
            - locally_canceled_at
          additionalProperties: false
          description: Cancelamento fiscal e cancelamento local são informações distintas.
        references:
          type: object
          properties:
            return_reference:
              anyOf:
                - type: string
                - type: 'null'
              description: Referência da devolução, ou null.
            reference:
              anyOf:
                - type: string
                - type: 'null'
              description: Referência local de emissão/processamento, ou null.
            url:
              anyOf:
                - type: string
                - type: 'null'
              description: URL armazenada; na imagem, URL derivada usando a configuração de arquivos.
            provider_id:
              anyOf:
                - type: integer
                  minimum: -9007199254740991
                  maximum: 9007199254740991
                - type: 'null'
              description: >-
                Fornecedor Takeat. Na lista é o vínculo armazenado; no detalhe é a busca por documento
                do emitente entre fornecedores ativos do restaurante.
          required:
            - return_reference
            - reference
            - url
            - provider_id
          additionalProperties: false
          description: Referências locais de integração e fornecedor.
        fiscal:
          type: object
          properties:
            version:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
              description: Versão de distribuição da nota.
            digest:
              anyOf:
                - type: string
                - type: 'null'
              description: Digest da nota, ou null.
            sped:
              description: Conteúdo fiscal SPED local (JSON) ou null.
          required:
            - version
            - digest
            - sped
          additionalProperties: false
          description: Metadados fiscais.
        timestamps:
          type: object
          properties:
            issued_at:
              type: string
              description: Data e hora de emissão; a listagem usa UTC e o detalhe preserva o offset da Focus.
            processing_at:
              anyOf:
                - 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))$
                - type: 'null'
              description: Data de início do processamento local, ou null.
            created_at:
              anyOf:
                - 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))$
                - type: 'null'
              description: Data de criação do registro local, em UTC.
            updated_at:
              anyOf:
                - 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))$
                - type: 'null'
              description: Data da última atualização local, em UTC.
          required:
            - issued_at
            - processing_at
            - created_at
            - updated_at
          additionalProperties: false
          description: Datas do registro. A emissão do detalhe vem da Focus e pode manter seu offset.
        recipient:
          type: object
          properties:
            cnpj:
              anyOf:
                - type: string
                - type: 'null'
              description: CNPJ preservado como texto, incluindo zeros à esquerda.
            cpf:
              anyOf:
                - type: string
                - type: 'null'
              description: CPF preservado como texto; vazio quando a Focus retorna string vazia.
          required:
            - cnpj
            - cpf
          additionalProperties: false
          description: Documentos do destinatário informados pela Focus.
        invoice:
          anyOf:
            - type: object
              properties:
                identification:
                  type: object
                  properties:
                    versao:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        versao. Campo fiscal da Focus, preservado no formato de origem; ausente quando
                        não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    chave_nfe:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        chave NF-e. Campo fiscal da Focus, preservado no formato de origem; ausente
                        quando não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    uf:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        UF. Campo fiscal da Focus, preservado no formato de origem; ausente quando não
                        informado. Valores decimais e códigos textuais não são convertidos em números.
                    codigo_unico:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        codigo unico. Campo fiscal da Focus, preservado no formato de origem; ausente
                        quando não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    natureza_operacao:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        natureza operacao. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    modelo:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        modelo. Campo fiscal da Focus, preservado no formato de origem; ausente quando
                        não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    serie:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        serie. Campo fiscal da Focus, preservado no formato de origem; ausente quando
                        não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    numero:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        numero. Campo fiscal da Focus, preservado no formato de origem; ausente quando
                        não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    data_emissao:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        data emissao. Campo fiscal da Focus, preservado no formato de origem; ausente
                        quando não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    data_entrada_saida:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        data entrada saida. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    tipo_documento:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        tipo documento. Campo fiscal da Focus, preservado no formato de origem; ausente
                        quando não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    local_destino:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        local destino. Campo fiscal da Focus, preservado no formato de origem; ausente
                        quando não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    municipio:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        municipio. Campo fiscal da Focus, preservado no formato de origem; ausente
                        quando não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    formato_impressao:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        formato impressao. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    forma_emissao:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        forma emissao. Campo fiscal da Focus, preservado no formato de origem; ausente
                        quando não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    digito_verificador:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        digito verificador. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    ambiente:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        ambiente. Campo fiscal da Focus, preservado no formato de origem; ausente quando
                        não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    finalidade_emissao:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        finalidade emissao. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    consumidor_final:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        consumidor final. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    presenca_comprador:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        presenca comprador. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    indicador_intermediario:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        indicador intermediario. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    processo_emissao:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        processo emissao. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    versao_aplicativo:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        versao aplicativo. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                  additionalProperties: false
                  description: Identificação da nota fiscal.
                references:
                  type: object
                  properties:
                    notas_referenciadas:
                      anyOf:
                        - type: array
                          items:
                            description: Valor JSON definido pelo leiaute fiscal do provedor.
                        - type: 'null'
                      description: >-
                        notas referenciadas. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    chaves_acesso_dfe_anteriores:
                      anyOf:
                        - type: array
                          items:
                            description: Valor JSON definido pelo leiaute fiscal do provedor.
                        - type: 'null'
                      description: >-
                        chaves acesso dfe anteriores. Campo fiscal da Focus, preservado no formato de
                        origem; ausente quando não informado. Valores decimais e códigos textuais não
                        são convertidos em números.
                    chaves_nfe_antecipacao_pagamento:
                      anyOf:
                        - type: array
                          items:
                            description: Valor JSON definido pelo leiaute fiscal do provedor.
                        - type: 'null'
                      description: >-
                        chaves NF-e antecipacao pagamento. Campo fiscal da Focus, preservado no formato
                        de origem; ausente quando não informado. Valores decimais e códigos textuais não
                        são convertidos em números.
                  additionalProperties: false
                  description: Referências locais de integração e fornecedor.
                issuer:
                  type: object
                  properties:
                    cnpj_emitente:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        CNPJ emitente. Campo fiscal da Focus, preservado no formato de origem; ausente
                        quando não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    nome_emitente:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        nome emitente. Campo fiscal da Focus, preservado no formato de origem; ausente
                        quando não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    logradouro_emitente:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        logradouro emitente. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    numero_emitente:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        numero emitente. Campo fiscal da Focus, preservado no formato de origem; ausente
                        quando não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    complemento_emitente:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        complemento emitente. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    bairro_emitente:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        bairro emitente. Campo fiscal da Focus, preservado no formato de origem; ausente
                        quando não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    codigo_municipio_emitente:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        codigo municipio emitente. Campo fiscal da Focus, preservado no formato de
                        origem; ausente quando não informado. Valores decimais e códigos textuais não
                        são convertidos em números.
                    municipio_emitente:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        municipio emitente. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    uf_emitente:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        UF emitente. Campo fiscal da Focus, preservado no formato de origem; ausente
                        quando não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    cep_emitente:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        CEP emitente. Campo fiscal da Focus, preservado no formato de origem; ausente
                        quando não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    codigo_pais_emitente:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        codigo pais emitente. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    pais_emitente:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        pais emitente. Campo fiscal da Focus, preservado no formato de origem; ausente
                        quando não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    telefone_emitente:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        telefone emitente. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    inscricao_estadual_emitente:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        inscricao estadual emitente. Campo fiscal da Focus, preservado no formato de
                        origem; ausente quando não informado. Valores decimais e códigos textuais não
                        são convertidos em números.
                    inscricao_municipal_emitente:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        inscricao municipal emitente. Campo fiscal da Focus, preservado no formato de
                        origem; ausente quando não informado. Valores decimais e códigos textuais não
                        são convertidos em números.
                    cnae_fiscal_emitente:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        CNAE fiscal emitente. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    regime_tributario_emitente:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        regime tributario emitente. Campo fiscal da Focus, preservado no formato de
                        origem; ausente quando não informado. Valores decimais e códigos textuais não
                        são convertidos em números.
                  additionalProperties: false
                  description: Identificação do emitente/fornecedor.
                recipient:
                  type: object
                  properties:
                    cnpj_destinatario:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        CNPJ destinatario. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    nome_destinatario:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        nome destinatario. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    logradouro_destinatario:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        logradouro destinatario. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    numero_destinatario:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        numero destinatario. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    bairro_destinatario:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        bairro destinatario. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    codigo_municipio_destinatario:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        codigo municipio destinatario. Campo fiscal da Focus, preservado no formato de
                        origem; ausente quando não informado. Valores decimais e códigos textuais não
                        são convertidos em números.
                    municipio_destinatario:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        municipio destinatario. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    uf_destinatario:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        UF destinatario. Campo fiscal da Focus, preservado no formato de origem; ausente
                        quando não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    cep_destinatario:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        CEP destinatario. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    codigo_pais_destinatario:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        codigo pais destinatario. Campo fiscal da Focus, preservado no formato de
                        origem; ausente quando não informado. Valores decimais e códigos textuais não
                        são convertidos em números.
                    pais_destinatario:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        pais destinatario. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    telefone_destinatario:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        telefone destinatario. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    indicador_inscricao_estadual_destinatario:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        indicador inscricao estadual destinatario. Campo fiscal da Focus, preservado no
                        formato de origem; ausente quando não informado. Valores decimais e códigos
                        textuais não são convertidos em números.
                    inscricao_estadual_destinatario:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        inscricao estadual destinatario. Campo fiscal da Focus, preservado no formato de
                        origem; ausente quando não informado. Valores decimais e códigos textuais não
                        são convertidos em números.
                    email_destinatario:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        email destinatario. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                  additionalProperties: false
                  description: Documentos do destinatário informados pela Focus.
                authorized_parties:
                  type: object
                  properties:
                    pessoas_autorizadas:
                      anyOf:
                        - type: array
                          items:
                            type: object
                            properties:
                              cnpj:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: CNPJ preservado como texto, incluindo zeros à esquerda.
                            additionalProperties:
                              description: Valor JSON definido pelo leiaute fiscal do provedor.
                        - type: 'null'
                      description: >-
                        pessoas autorizadas. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                  additionalProperties: false
                  description: >-
                    authorized parties. Campo fiscal da Focus, preservado no formato de origem; ausente
                    quando não informado. Valores decimais e códigos textuais não são convertidos em
                    números.
                taxes:
                  type: object
                  properties:
                    icms_base_calculo:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        ICMS base calculo. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    icms_valor_total:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        ICMS valor total. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    icms_valor_total_desonerado:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        ICMS valor total desonerado. Campo fiscal da Focus, preservado no formato de
                        origem; ausente quando não informado. Valores decimais e códigos textuais não
                        são convertidos em números.
                    fcp_valor_total:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        FCP valor total. Campo fiscal da Focus, preservado no formato de origem; ausente
                        quando não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    icms_base_calculo_st:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        ICMS base calculo ST. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    icms_valor_total_st:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        ICMS valor total ST. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    fcp_valor_total_st:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        FCP valor total ST. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    fcp_valor_total_retido_st:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        FCP valor total retido ST. Campo fiscal da Focus, preservado no formato de
                        origem; ausente quando não informado. Valores decimais e códigos textuais não
                        são convertidos em números.
                    ibs_cbs_base_calculo:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        IBS CBS base calculo. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    ibs_cbs_is_valor_total:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        IBS CBS is valor total. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                  additionalProperties: false
                  description: >-
                    taxes. Campo fiscal da Focus, preservado no formato de origem; ausente quando não
                    informado. Valores decimais e códigos textuais não são convertidos em números.
                totals:
                  type: object
                  properties:
                    valor_produtos:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        valor produtos. Campo fiscal da Focus, preservado no formato de origem; ausente
                        quando não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    valor_frete:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        valor frete. Campo fiscal da Focus, preservado no formato de origem; ausente
                        quando não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    valor_seguro:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        valor seguro. Campo fiscal da Focus, preservado no formato de origem; ausente
                        quando não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    valor_desconto:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        valor desconto. Campo fiscal da Focus, preservado no formato de origem; ausente
                        quando não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    valor_total_ii:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        valor total II. Campo fiscal da Focus, preservado no formato de origem; ausente
                        quando não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    valor_ipi:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        valor IPI. Campo fiscal da Focus, preservado no formato de origem; ausente
                        quando não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    valor_ipi_devolvido:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        valor IPI devolvido. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    valor_pis:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        valor PIS. Campo fiscal da Focus, preservado no formato de origem; ausente
                        quando não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    valor_cofins:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        valor COFINS. Campo fiscal da Focus, preservado no formato de origem; ausente
                        quando não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    valor_outras_despesas:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        valor outras despesas. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    valor_total:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        valor total. Campo fiscal da Focus, preservado no formato de origem; ausente
                        quando não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                  additionalProperties: false
                  description: >-
                    totals. Campo fiscal da Focus, preservado no formato de origem; ausente quando não
                    informado. Valores decimais e códigos textuais não são convertidos em números.
                transport:
                  type: object
                  properties:
                    modalidade_frete:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        modalidade frete. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    cnpj_transportador:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        CNPJ transportador. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    nome_transportador:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        nome transportador. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    inscricao_estadual_transportador:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        inscricao estadual transportador. Campo fiscal da Focus, preservado no formato
                        de origem; ausente quando não informado. Valores decimais e códigos textuais não
                        são convertidos em números.
                    endereco_transportador:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        endereco transportador. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    municipio_transportador:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        municipio transportador. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    uf_transportador:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        UF transportador. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    reboques:
                      anyOf:
                        - type: array
                          items:
                            description: Valor JSON definido pelo leiaute fiscal do provedor.
                        - type: 'null'
                      description: >-
                        reboques. Campo fiscal da Focus, preservado no formato de origem; ausente quando
                        não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    volumes:
                      anyOf:
                        - type: array
                          items:
                            type: object
                            properties:
                              quantidade:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: >-
                                  quantidade. Campo fiscal da Focus, preservado no formato de origem;
                                  ausente quando não informado. Valores decimais e códigos textuais não
                                  são convertidos em números.
                              especie:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: >-
                                  especie. Campo fiscal da Focus, preservado no formato de origem;
                                  ausente quando não informado. Valores decimais e códigos textuais não
                                  são convertidos em números.
                              marca:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: >-
                                  marca. Campo fiscal da Focus, preservado no formato de origem; ausente
                                  quando não informado. Valores decimais e códigos textuais não são
                                  convertidos em números.
                              peso_liquido:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: >-
                                  peso liquido. Campo fiscal da Focus, preservado no formato de origem;
                                  ausente quando não informado. Valores decimais e códigos textuais não
                                  são convertidos em números.
                              peso_bruto:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: >-
                                  peso bruto. Campo fiscal da Focus, preservado no formato de origem;
                                  ausente quando não informado. Valores decimais e códigos textuais não
                                  são convertidos em números.
                              lacres:
                                anyOf:
                                  - type: array
                                    items:
                                      description: Valor JSON definido pelo leiaute fiscal do provedor.
                                  - type: 'null'
                                description: >-
                                  lacres. Campo fiscal da Focus, preservado no formato de origem;
                                  ausente quando não informado. Valores decimais e códigos textuais não
                                  são convertidos em números.
                            additionalProperties:
                              description: Valor JSON definido pelo leiaute fiscal do provedor.
                        - type: 'null'
                      description: >-
                        volumes. Campo fiscal da Focus, preservado no formato de origem; ausente quando
                        não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                  additionalProperties: false
                  description: >-
                    transport. Campo fiscal da Focus, preservado no formato de origem; ausente quando
                    não informado. Valores decimais e códigos textuais não são convertidos em números.
                billing:
                  type: object
                  properties:
                    duplicatas:
                      anyOf:
                        - type: array
                          items:
                            description: Valor JSON definido pelo leiaute fiscal do provedor.
                        - type: 'null'
                      description: >-
                        duplicatas. Campo fiscal da Focus, preservado no formato de origem; ausente
                        quando não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    formas_pagamento:
                      anyOf:
                        - type: array
                          items:
                            type: object
                            properties:
                              forma_pagamento:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: >-
                                  forma pagamento. Campo fiscal da Focus, preservado no formato de
                                  origem; ausente quando não informado. Valores decimais e códigos
                                  textuais não são convertidos em números.
                              descricao_pagamento:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: >-
                                  descricao pagamento. Campo fiscal da Focus, preservado no formato de
                                  origem; ausente quando não informado. Valores decimais e códigos
                                  textuais não são convertidos em números.
                              valor_pagamento:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: >-
                                  valor pagamento. Campo fiscal da Focus, preservado no formato de
                                  origem; ausente quando não informado. Valores decimais e códigos
                                  textuais não são convertidos em números.
                              tipo_integracao:
                                description: >-
                                  tipo integracao. Campo fiscal da Focus, preservado no formato de
                                  origem; ausente quando não informado. Valores decimais e códigos
                                  textuais não são convertidos em números.
                            additionalProperties:
                              description: Valor JSON definido pelo leiaute fiscal do provedor.
                        - type: 'null'
                      description: >-
                        formas pagamento. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                  additionalProperties: false
                  description: >-
                    billing. Campo fiscal da Focus, preservado no formato de origem; ausente quando não
                    informado. Valores decimais e códigos textuais não são convertidos em números.
                additional:
                  type: object
                  properties:
                    informacoes_adicionais_contribuinte:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        informacoes adicionais contribuinte. Campo fiscal da Focus, preservado no
                        formato de origem; ausente quando não informado. Valores decimais e códigos
                        textuais não são convertidos em números.
                    observacoes_contribuinte:
                      anyOf:
                        - type: array
                          items:
                            description: Valor JSON definido pelo leiaute fiscal do provedor.
                        - type: 'null'
                      description: >-
                        observacoes contribuinte. Campo fiscal da Focus, preservado no formato de
                        origem; ausente quando não informado. Valores decimais e códigos textuais não
                        são convertidos em números.
                    observacoes_fisco:
                      anyOf:
                        - type: array
                          items:
                            description: Valor JSON definido pelo leiaute fiscal do provedor.
                        - type: 'null'
                      description: >-
                        observacoes fisco. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    processos_referenciados:
                      anyOf:
                        - type: array
                          items:
                            description: Valor JSON definido pelo leiaute fiscal do provedor.
                        - type: 'null'
                      description: >-
                        processos referenciados. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    cana_fornecimentos:
                      anyOf:
                        - type: array
                          items:
                            description: Valor JSON definido pelo leiaute fiscal do provedor.
                        - type: 'null'
                      description: >-
                        cana fornecimentos. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                    cana_deducoes:
                      anyOf:
                        - type: array
                          items:
                            description: Valor JSON definido pelo leiaute fiscal do provedor.
                        - type: 'null'
                      description: >-
                        cana deducoes. Campo fiscal da Focus, preservado no formato de origem; ausente
                        quando não informado. Valores decimais e códigos textuais não são convertidos em
                        números.
                    agropecuario_defensivo:
                      anyOf:
                        - type: array
                          items:
                            description: Valor JSON definido pelo leiaute fiscal do provedor.
                        - type: 'null'
                      description: >-
                        agropecuario defensivo. Campo fiscal da Focus, preservado no formato de origem;
                        ausente quando não informado. Valores decimais e códigos textuais não são
                        convertidos em números.
                  additionalProperties: false
                  description: >-
                    additional. Campo fiscal da Focus, preservado no formato de origem; ausente quando
                    não informado. Valores decimais e códigos textuais não são convertidos em números.
                technical_contact:
                  type: object
                  properties:
                    cnpj_responsavel_tecnico:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        CNPJ responsavel tecnico. Campo fiscal da Focus, preservado no formato de
                        origem; ausente quando não informado. Valores decimais e códigos textuais não
                        são convertidos em números.
                    contato_responsavel_tecnico:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        contato responsavel tecnico. Campo fiscal da Focus, preservado no formato de
                        origem; ausente quando não informado. Valores decimais e códigos textuais não
                        são convertidos em números.
                    email_responsavel_tecnico:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        email responsavel tecnico. Campo fiscal da Focus, preservado no formato de
                        origem; ausente quando não informado. Valores decimais e códigos textuais não
                        são convertidos em números.
                    telefone_responsavel_tecnico:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        telefone responsavel tecnico. Campo fiscal da Focus, preservado no formato de
                        origem; ausente quando não informado. Valores decimais e códigos textuais não
                        são convertidos em números.
                  additionalProperties: false
                  description: >-
                    technical contact. Campo fiscal da Focus, preservado no formato de origem; ausente
                    quando não informado. Valores decimais e códigos textuais não são convertidos em
                    números.
                additional_fields:
                  type: object
                  propertyNames:
                    type: string
                  additionalProperties:
                    description: Valor JSON definido pelo leiaute fiscal do provedor.
                  description: >-
                    Campos fiscais adicionais introduzidos pelo provedor, preservados com seus nomes e
                    tipos JSON originais.
                items:
                  type: array
                  items:
                    type: object
                    properties:
                      identification:
                        type: object
                        properties:
                          numero_item:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              numero item. Campo fiscal da Focus, preservado no formato de origem;
                              ausente quando não informado. Valores decimais e códigos textuais não são
                              convertidos em números.
                          codigo_produto:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              codigo produto. Campo fiscal da Focus, preservado no formato de origem;
                              ausente quando não informado. Valores decimais e códigos textuais não são
                              convertidos em números.
                          descricao:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              descricao. Campo fiscal da Focus, preservado no formato de origem; ausente
                              quando não informado. Valores decimais e códigos textuais não são
                              convertidos em números.
                          codigo_ncm:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              codigo NCM. Campo fiscal da Focus, preservado no formato de origem;
                              ausente quando não informado. Valores decimais e códigos textuais não são
                              convertidos em números.
                          nves:
                            anyOf:
                              - type: array
                                items:
                                  description: Valor JSON definido pelo leiaute fiscal do provedor.
                              - type: 'null'
                            description: >-
                              nves. Campo fiscal da Focus, preservado no formato de origem; ausente
                              quando não informado. Valores decimais e códigos textuais não são
                              convertidos em números.
                          cest:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              CEST. Campo fiscal da Focus, preservado no formato de origem; ausente
                              quando não informado. Valores decimais e códigos textuais não são
                              convertidos em números.
                          cfop:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              CFOP. Campo fiscal da Focus, preservado no formato de origem; ausente
                              quando não informado. Valores decimais e códigos textuais não são
                              convertidos em números.
                        additionalProperties: false
                        description: Identificação da nota fiscal.
                      commercial:
                        type: object
                        properties:
                          codigo_barras_comercial:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              codigo barras comercial. Campo fiscal da Focus, preservado no formato de
                              origem; ausente quando não informado. Valores decimais e códigos textuais
                              não são convertidos em números.
                          unidade_comercial:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              unidade comercial. Campo fiscal da Focus, preservado no formato de origem;
                              ausente quando não informado. Valores decimais e códigos textuais não são
                              convertidos em números.
                          quantidade_comercial:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              quantidade comercial. Campo fiscal da Focus, preservado no formato de
                              origem; ausente quando não informado. Valores decimais e códigos textuais
                              não são convertidos em números.
                          valor_unitario_comercial:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              valor unitario comercial. Campo fiscal da Focus, preservado no formato de
                              origem; ausente quando não informado. Valores decimais e códigos textuais
                              não são convertidos em números.
                        additionalProperties: false
                        description: >-
                          commercial. Campo fiscal da Focus, preservado no formato de origem; ausente
                          quando não informado. Valores decimais e códigos textuais não são convertidos
                          em números.
                      taxes:
                        type: object
                        properties:
                          infos_credito_presumido:
                            anyOf:
                              - type: array
                                items:
                                  description: Valor JSON definido pelo leiaute fiscal do provedor.
                              - type: 'null'
                            description: >-
                              infos credito presumido. Campo fiscal da Focus, preservado no formato de
                              origem; ausente quando não informado. Valores decimais e códigos textuais
                              não são convertidos em números.
                          ipi_codigo_enquadramento_legal:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              IPI codigo enquadramento legal. Campo fiscal da Focus, preservado no
                              formato de origem; ausente quando não informado. Valores decimais e
                              códigos textuais não são convertidos em números.
                          icms_percentual_partilha:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              ICMS percentual partilha. Campo fiscal da Focus, preservado no formato de
                              origem; ausente quando não informado. Valores decimais e códigos textuais
                              não são convertidos em números.
                          ibs_cbs_situacao_tributaria:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              IBS CBS situacao tributaria. Campo fiscal da Focus, preservado no formato
                              de origem; ausente quando não informado. Valores decimais e códigos
                              textuais não são convertidos em números.
                          ibs_cbs_classificacao_tributaria:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              IBS CBS classificacao tributaria. Campo fiscal da Focus, preservado no
                              formato de origem; ausente quando não informado. Valores decimais e
                              códigos textuais não são convertidos em números.
                          ibs_cbs_base_calculo:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              IBS CBS base calculo. Campo fiscal da Focus, preservado no formato de
                              origem; ausente quando não informado. Valores decimais e códigos textuais
                              não são convertidos em números.
                          ibs_uf_aliquota:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              IBS UF aliquota. Campo fiscal da Focus, preservado no formato de origem;
                              ausente quando não informado. Valores decimais e códigos textuais não são
                              convertidos em números.
                          ibs_uf_percentual_reducao_aliquota:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              IBS UF percentual reducao aliquota. Campo fiscal da Focus, preservado no
                              formato de origem; ausente quando não informado. Valores decimais e
                              códigos textuais não são convertidos em números.
                          ibs_uf_aliquota_efetiva:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              IBS UF aliquota efetiva. Campo fiscal da Focus, preservado no formato de
                              origem; ausente quando não informado. Valores decimais e códigos textuais
                              não são convertidos em números.
                          ibs_uf_valor:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              IBS UF valor. Campo fiscal da Focus, preservado no formato de origem;
                              ausente quando não informado. Valores decimais e códigos textuais não são
                              convertidos em números.
                          ibs_mun_aliquota:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              IBS municipal aliquota. Campo fiscal da Focus, preservado no formato de
                              origem; ausente quando não informado. Valores decimais e códigos textuais
                              não são convertidos em números.
                          ibs_mun_percentual_reducao_aliquota:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              IBS municipal percentual reducao aliquota. Campo fiscal da Focus,
                              preservado no formato de origem; ausente quando não informado. Valores
                              decimais e códigos textuais não são convertidos em números.
                          ibs_mun_aliquota_efetiva:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              IBS municipal aliquota efetiva. Campo fiscal da Focus, preservado no
                              formato de origem; ausente quando não informado. Valores decimais e
                              códigos textuais não são convertidos em números.
                          ibs_mun_valor:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              IBS municipal valor. Campo fiscal da Focus, preservado no formato de
                              origem; ausente quando não informado. Valores decimais e códigos textuais
                              não são convertidos em números.
                          ibs_valor_total:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              IBS valor total. Campo fiscal da Focus, preservado no formato de origem;
                              ausente quando não informado. Valores decimais e códigos textuais não são
                              convertidos em números.
                          cbs_aliquota:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              CBS aliquota. Campo fiscal da Focus, preservado no formato de origem;
                              ausente quando não informado. Valores decimais e códigos textuais não são
                              convertidos em números.
                          cbs_percentual_reducao_aliquota:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              CBS percentual reducao aliquota. Campo fiscal da Focus, preservado no
                              formato de origem; ausente quando não informado. Valores decimais e
                              códigos textuais não são convertidos em números.
                          cbs_aliquota_efetiva:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              CBS aliquota efetiva. Campo fiscal da Focus, preservado no formato de
                              origem; ausente quando não informado. Valores decimais e códigos textuais
                              não são convertidos em números.
                          cbs_valor:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              CBS valor. Campo fiscal da Focus, preservado no formato de origem; ausente
                              quando não informado. Valores decimais e códigos textuais não são
                              convertidos em números.
                          icms_origem:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              ICMS origem. Campo fiscal da Focus, preservado no formato de origem;
                              ausente quando não informado. Valores decimais e códigos textuais não são
                              convertidos em números.
                          icms_situacao_tributaria:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              ICMS situacao tributaria. Campo fiscal da Focus, preservado no formato de
                              origem; ausente quando não informado. Valores decimais e códigos textuais
                              não são convertidos em números.
                          icms_modalidade_base_calculo:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              ICMS modalidade base calculo. Campo fiscal da Focus, preservado no formato
                              de origem; ausente quando não informado. Valores decimais e códigos
                              textuais não são convertidos em números.
                          icms_base_calculo:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              ICMS base calculo. Campo fiscal da Focus, preservado no formato de origem;
                              ausente quando não informado. Valores decimais e códigos textuais não são
                              convertidos em números.
                          icms_aliquota:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              ICMS aliquota. Campo fiscal da Focus, preservado no formato de origem;
                              ausente quando não informado. Valores decimais e códigos textuais não são
                              convertidos em números.
                          icms_valor:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              ICMS valor. Campo fiscal da Focus, preservado no formato de origem;
                              ausente quando não informado. Valores decimais e códigos textuais não são
                              convertidos em números.
                          ipi_situacao_tributaria:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              IPI situacao tributaria. Campo fiscal da Focus, preservado no formato de
                              origem; ausente quando não informado. Valores decimais e códigos textuais
                              não são convertidos em números.
                          pis_situacao_tributaria:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              PIS situacao tributaria. Campo fiscal da Focus, preservado no formato de
                              origem; ausente quando não informado. Valores decimais e códigos textuais
                              não são convertidos em números.
                          cofins_situacao_tributaria:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              COFINS situacao tributaria. Campo fiscal da Focus, preservado no formato
                              de origem; ausente quando não informado. Valores decimais e códigos
                              textuais não são convertidos em números.
                        additionalProperties: false
                        description: >-
                          taxes. Campo fiscal da Focus, preservado no formato de origem; ausente quando
                          não informado. Valores decimais e códigos textuais não são convertidos em
                          números.
                      amounts:
                        type: object
                        properties:
                          valor_bruto:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              valor bruto. Campo fiscal da Focus, preservado no formato de origem;
                              ausente quando não informado. Valores decimais e códigos textuais não são
                              convertidos em números.
                          inclui_no_total:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              inclui no total. Campo fiscal da Focus, preservado no formato de origem;
                              ausente quando não informado. Valores decimais e códigos textuais não são
                              convertidos em números.
                          valor_total_item:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              valor total item. Campo fiscal da Focus, preservado no formato de origem;
                              ausente quando não informado. Valores decimais e códigos textuais não são
                              convertidos em números.
                        additionalProperties: false
                        description: Valores monetários da nota.
                      taxable:
                        type: object
                        properties:
                          codigo_barras_tributavel:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              codigo barras tributavel. Campo fiscal da Focus, preservado no formato de
                              origem; ausente quando não informado. Valores decimais e códigos textuais
                              não são convertidos em números.
                          unidade_tributavel:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              unidade tributavel. Campo fiscal da Focus, preservado no formato de
                              origem; ausente quando não informado. Valores decimais e códigos textuais
                              não são convertidos em números.
                          quantidade_tributavel:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              quantidade tributavel. Campo fiscal da Focus, preservado no formato de
                              origem; ausente quando não informado. Valores decimais e códigos textuais
                              não são convertidos em números.
                          valor_unitario_tributavel:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              valor unitario tributavel. Campo fiscal da Focus, preservado no formato de
                              origem; ausente quando não informado. Valores decimais e códigos textuais
                              não são convertidos em números.
                        additionalProperties: false
                        description: >-
                          taxable. Campo fiscal da Focus, preservado no formato de origem; ausente
                          quando não informado. Valores decimais e códigos textuais não são convertidos
                          em números.
                      additional:
                        type: object
                        properties:
                          documentos_importacao:
                            anyOf:
                              - type: array
                                items:
                                  description: Valor JSON definido pelo leiaute fiscal do provedor.
                              - type: 'null'
                            description: >-
                              documentos importacao. Campo fiscal da Focus, preservado no formato de
                              origem; ausente quando não informado. Valores decimais e códigos textuais
                              não são convertidos em números.
                          detalhes_exportacao:
                            anyOf:
                              - type: array
                                items:
                                  description: Valor JSON definido pelo leiaute fiscal do provedor.
                              - type: 'null'
                            description: >-
                              detalhes exportacao. Campo fiscal da Focus, preservado no formato de
                              origem; ausente quando não informado. Valores decimais e códigos textuais
                              não são convertidos em números.
                          rastros:
                            anyOf:
                              - type: array
                                items:
                                  description: Valor JSON definido pelo leiaute fiscal do provedor.
                              - type: 'null'
                            description: >-
                              rastros. Campo fiscal da Focus, preservado no formato de origem; ausente
                              quando não informado. Valores decimais e códigos textuais não são
                              convertidos em números.
                          armamentos:
                            anyOf:
                              - type: array
                                items:
                                  description: Valor JSON definido pelo leiaute fiscal do provedor.
                              - type: 'null'
                            description: >-
                              armamentos. Campo fiscal da Focus, preservado no formato de origem;
                              ausente quando não informado. Valores decimais e códigos textuais não são
                              convertidos em números.
                          origens_combustivel:
                            anyOf:
                              - type: array
                                items:
                                  description: Valor JSON definido pelo leiaute fiscal do provedor.
                              - type: 'null'
                            description: >-
                              origens combustivel. Campo fiscal da Focus, preservado no formato de
                              origem; ausente quando não informado. Valores decimais e códigos textuais
                              não são convertidos em números.
                          observacoes_contribuinte:
                            anyOf:
                              - type: array
                                items:
                                  description: Valor JSON definido pelo leiaute fiscal do provedor.
                              - type: 'null'
                            description: >-
                              observacoes contribuinte. Campo fiscal da Focus, preservado no formato de
                              origem; ausente quando não informado. Valores decimais e códigos textuais
                              não são convertidos em números.
                        additionalProperties: false
                        description: >-
                          additional. Campo fiscal da Focus, preservado no formato de origem; ausente
                          quando não informado. Valores decimais e códigos textuais não são convertidos
                          em números.
                      additional_fields:
                        type: object
                        propertyNames:
                          type: string
                        additionalProperties:
                          description: Valor JSON definido pelo leiaute fiscal do provedor.
                        description: >-
                          Campos fiscais adicionais introduzidos pelo provedor, preservados com seus
                          nomes e tipos JSON originais.
                    required:
                      - identification
                      - commercial
                      - taxes
                      - amounts
                      - taxable
                      - additional
                      - additional_fields
                    additionalProperties: false
                  description: >-
                    items. Campo fiscal da Focus, preservado no formato de origem; ausente quando não
                    informado. Valores decimais e códigos textuais não são convertidos em números.
              required:
                - identification
                - references
                - issuer
                - recipient
                - authorized_parties
                - taxes
                - totals
                - transport
                - billing
                - additional
                - technical_contact
                - additional_fields
              additionalProperties: false
            - type: 'null'
          description: Documento fiscal completo agrupado por assunto, ou null quando indisponível.
        protocol:
          anyOf:
            - type: object
              properties:
                versao:
                  anyOf:
                    - type: string
                    - type: 'null'
                  description: >-
                    versao. Campo fiscal da Focus, preservado no formato de origem; ausente quando não
                    informado. Valores decimais e códigos textuais não são convertidos em números.
                ambiente:
                  anyOf:
                    - type: string
                    - type: 'null'
                  description: >-
                    ambiente. Campo fiscal da Focus, preservado no formato de origem; ausente quando não
                    informado. Valores decimais e códigos textuais não são convertidos em números.
                versao_aplicativo:
                  anyOf:
                    - type: string
                    - type: 'null'
                  description: >-
                    versao aplicativo. Campo fiscal da Focus, preservado no formato de origem; ausente
                    quando não informado. Valores decimais e códigos textuais não são convertidos em
                    números.
                chave_nfe:
                  anyOf:
                    - type: string
                    - type: 'null'
                  description: >-
                    chave NF-e. Campo fiscal da Focus, preservado no formato de origem; ausente quando
                    não informado. Valores decimais e códigos textuais não são convertidos em números.
                data_recebimento:
                  anyOf:
                    - type: string
                    - type: 'null'
                  description: >-
                    data recebimento. Campo fiscal da Focus, preservado no formato de origem; ausente
                    quando não informado. Valores decimais e códigos textuais não são convertidos em
                    números.
                numero_protocolo:
                  anyOf:
                    - type: string
                    - type: 'null'
                  description: >-
                    numero protocolo. Campo fiscal da Focus, preservado no formato de origem; ausente
                    quando não informado. Valores decimais e códigos textuais não são convertidos em
                    números.
                digest_value:
                  anyOf:
                    - type: string
                    - type: 'null'
                  description: >-
                    digest value. Campo fiscal da Focus, preservado no formato de origem; ausente quando
                    não informado. Valores decimais e códigos textuais não são convertidos em números.
                status:
                  anyOf:
                    - type: string
                    - type: 'null'
                  description: Situação fiscal e disponibilidade do documento completo.
                motivo:
                  anyOf:
                    - type: string
                    - type: 'null'
                  description: >-
                    motivo. Campo fiscal da Focus, preservado no formato de origem; ausente quando não
                    informado. Valores decimais e códigos textuais não são convertidos em números.
              additionalProperties:
                description: Valor JSON definido pelo leiaute fiscal do provedor.
            - type: 'null'
          description: Protocolo fiscal da Focus ou null.
        processing:
          type: object
          properties:
            return_in_progress:
              type: boolean
              description: >-
                Existe nota do restaurante com a referência de devolução e situação
                processando_autorizacao. Sem referência, false.
          required:
            - return_in_progress
          additionalProperties: false
          description: Estado de processamento da devolução na base local.
      required:
        - id
        - restaurant_id
        - brand_id
        - brand
        - identification
        - issuer
        - amounts
        - status
        - manifestation
        - correction
        - cancellation
        - references
        - fiscal
        - timestamps
        - recipient
        - invoice
        - protocol
        - processing
      additionalProperties: false

    ApiKeyGrantRequest:
      type: object
      required: [grant_type, api_key]
      properties:
        grant_type:
          type: string
          const: api_key
        api_key:
          type: string
          format: password
          description: Chave completa `tk_live_...` ou `tk_test_...`.
        scope:
          type: string
          description: Subconjunto opcional, separado por espaços, dos escopos da chave.

    ApiKeyRefreshRequest:
      type: object
      required: [grant_type, refresh_token]
      properties:
        grant_type:
          type: string
          const: refresh_token
        refresh_token:
          type: string
          format: password
          description: Refresh token rotativo atual, prefixado por `tk_api_refresh_`.

    AuthorizationCodeGrantRequest:
      type: object
      required:
        - grant_type
        - client_id
        - code
        - redirect_uri
        - code_verifier
      properties:
        grant_type:
          type: string
          const: authorization_code
        client_id:
          type: string
          pattern: ^tk_app_
          description: Client ID público do aplicativo.
        code:
          type: string
          format: password
          description: Código curto, de uso único, recebido no callback.
        redirect_uri:
          type: string
          format: uri
          description: Mesma URI exata usada na autorização.
        code_verifier:
          type: string
          format: password
          minLength: 43
          maxLength: 128
          description: Verifier original usado para gerar o challenge S256.

    OAuthClientRefreshRequest:
      type: object
      required: [grant_type, client_id, refresh_token]
      properties:
        grant_type:
          type: string
          const: refresh_token
        client_id:
          type: string
          pattern: ^tk_app_
          description: Client ID público do aplicativo instalado.
        refresh_token:
          type: string
          format: password
          description: Refresh token rotativo atual, prefixado por `tk_refresh_`.

    TokenResponse:
      type: object
      required:
        - access_token
        - refresh_token
        - token_type
        - expires_in
        - scope
      properties:
        access_token:
          type: string
          description: JWT de acesso curto usado exclusivamente em `/v1/*`.
        refresh_token:
          type: string
          description: Credencial rotativa usada para renovar o access token.
        token_type:
          description: "Tipo do token; sempre Bearer (envie no header Authorization)."
          type: string
          const: Bearer
        expires_in:
          description: "Validade do access token em segundos (padrão 900, 15 minutos)."
          type: integer
          example: 900
        scope:
          description: "Escopos concedidos ao token, separados por espaço."
          type: string
          example: menu:read products:read complements:read
        access_scope:
          type: string
          enum:
            - multistore
          description: Presente nos grants de instalação multilojas. Credenciais anteriores mantêm seu alcance.
        restaurants:
          type: array
          description: >-
            Lojas elegíveis da concessão multilojas na troca de código ou refresh; novas lojas não entram
            automaticamente.
          items:
            type: object
            required:
              - id
              - fantasy_name
            properties:
              id:
                description: "ID da loja incluída na concessão multilojas (string numérica); use como restaurant_id."
                type: string
              fantasy_name:
                description: "Nome fantasia da loja."
                type: string
        restaurant:
          type: object
          additionalProperties: false
          required:
            - id
            - email
            - fantasy_name
          description: >-
            Presente na troca de authorization_code e no refresh de uma instalação OAuth. Em multilojas identifica
            a conta raiz administrativa, nunca uma loja de dados. Dados atuais da conta do restaurante conectado,
            não do usuário que aprovou o acesso. Ausente nos fluxos com chave de API.
          properties:
            id:
              description: "ID do restaurante conectado (string numérica)."
              type: string
              example: '123'
            email:
              description: "E-mail de cadastro da conta do restaurante."
              type: string
              example: contato@restaurante.example
            fantasy_name:
              description: "Nome fantasia do restaurante conectado."
              type: string
              example: Restaurante Exemplo
    RevokeTokenRequest:
      type: object
      required: [token, client_id]
      properties:
        token:
          type: string
          description: Access ou refresh token que deve ser revogado.
        token_type_hint:
          type: string
          enum: [access_token, refresh_token]
        client_id:
          type: string
          description: Client ID que emitiu o token.
        client_secret:
          type: string
          format: password
          description: Não usado por aplicativos públicos `tk_app_...`.

    OAuthError:
      type: object
      required: [error]
      properties:
        error:
          type: string
          example: invalid_client
        error_description:
          type: string

    ApiError:
      type: object
      required: [statusCode, message, key]
      properties:
        statusCode:
          type: integer
          example: 400
        message:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        key:
          type: string
          example: restaurant_id_required

    ProductWriteFields:
      type: object
      description: |
        Campos de criação. Preços são números JSON com até duas casas decimais;
        os valores monetários da resposta são strings. Os defaults se aplicam
        apenas à criação. Consulte a referência de campos em /externo/v1/campos-do-produto.
      properties:
        image_id:
          type: [integer, "null"]
          minimum: 1
          maximum: 2147483647
          description: ID de imagem enviada em POST /v1/files para o mesmo restaurante; null remove, omitido preserva na edição.
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Nome do produto. Espaços nas extremidades são removidos; não pode conter apenas espaços. Não é identificador único.
          example: Takeat Burger
        product_category_id:
          type: integer
          minimum: 1
          description: ID de categoria não removida do mesmo restaurante. A categoria tem disponibilidade própria por canal.
          example: 10
        price:
          type: number
          exclusiveMinimum: 0
          multipleOf: 0.01
          description: Preço base presencial e último fallback do delivery. Positivo na criação; não inclui complementos ou taxas. Por quilo se use_weight=true.
          example: 28.90
        description:
          type: [string, "null"]
          maxLength: 255
          description: Texto descritivo do produto. Omitido na criação assume null; na edição, null limpa o texto.
        price_promotion:
          type: [number, "null"]
          minimum: 0
          multipleOf: 0.01
          description: Preço promocional presencial que substitui price, não um desconto a subtrair. null indica ausência de promoção; zero é válido. Não é fallback do delivery no menu V1.
        delivery_price:
          type: [number, "null"]
          minimum: 0
          multipleOf: 0.01
          description: Preço de delivery e retirada nesse fluxo. Sem promoção de delivery, null usa price no menu V1; zero define preço zero. Não altera o preço próprio do iFood.
        delivery_price_promotion:
          type: [number, "null"]
          minimum: 0
          multipleOf: 0.01
          description: Preço promocional do delivery, com prioridade sobre delivery_price. null indica ausência de promoção; zero é válido.
        sold_off:
          type: boolean
          default: false
          description: Esgotamento temporário para os dois canais, sem alterar suas disponibilidades. O menu V1 o exclui com only_available=true; com false, retorna availability.sold_out.
        available:
          type: boolean
          default: true
          description: Disponibilidade para venda presencial, independente do delivery. O menu filtrado também exige disponibilidade da categoria.
        available_in_delivery:
          type: boolean
          default: true
          description: Disponibilidade para delivery e retirada nesse fluxo, independente do presencial. Não limpa sold_off.
        use_weight:
          type: boolean
          default: false
          description: Venda por peso. O preço é por quilo; o menu não calcula o total da porção.
        has_starting_price:
          type: boolean
          default: false
          description: Sinaliza apresentação “a partir de”. Não altera os preços. O menu calcula pricing.resolved.minimum com escolhas obrigatórias independentemente desta flag.
        charge_service_tax:
          type: boolean
          default: true
          description: Inclui o item na base da taxa de serviço presencial quando aplicada pelo restaurante e pela comanda. Não define percentual nem altera pricing.resolved.base.
    CreateProductRequest:
      allOf:
        - $ref: "#/components/schemas/ProductWriteFields"
        - type: object
          required: [name, product_category_id, price]
      unevaluatedProperties: false

    ManagedComplement:
      type: object
      description: >-
        Snapshot do complemento. Preços são strings com duas casas; fiscal e fiscal_info contêm os
        mesmos 32 atributos públicos. Associações a grupos permanecem intactas.
      required:
        - id
        - restaurant_id
        - name
        - description
        - price
        - delivery_price
        - available
        - available_in_delivery
        - fiscal_info
        - fiscal
        - created_at
        - updated_at
        - limit
        - show_on_report
      properties:
        id:
          description: "ID do complemento."
          type: integer
        restaurant_id:
          description: "ID do restaurante dono do complemento."
          type: integer
        name:
          description: "Nome do complemento."
          type: string
        description:
          description: "Texto descritivo do complemento; `null` quando não informado."
          type:
            - string
            - 'null'
        price:
          description: "Preço base presencial em reais, string com duas casas; zero é permitido."
          type: string
          example: '28.00'
        delivery_price:
          description: "Preço de delivery em reais, com duas casas; `null` usa `price` no delivery."
          type:
            - string
            - 'null'
          example: '31.00'
        available:
          description: "Disponível para venda presencial."
          type: boolean
        available_in_delivery:
          description: "Disponível no delivery, independentemente de `available`."
          type: boolean
        fiscal_info:
          $ref: '#/components/schemas/ProductFiscal'
          description: Alias de compatibilidade de fiscal, sem identificadores internos.
        fiscal:
          $ref: '#/components/schemas/ProductFiscal'
        created_at:
          description: "Data de criação (ISO 8601, UTC)."
          type: string
          format: date-time
        updated_at:
          description: "Data da última alteração (ISO 8601, UTC); envie como `expected_updated_at` nas edições."
          type: string
          format: date-time
        limit:
          description: "Quantidade máxima deste complemento numa escolha, independente do limite dos grupos."
          type: integer
        show_on_report:
          description: "Se o complemento aparece nos relatórios de vendas."
          type: boolean
      additionalProperties: false
    UpdateComplementFields:
      type: object
      description: |
        Pelo menos um campo editável é necessário; expected_updated_at e id
        sozinhos não constituem uma alteração. Campos omitidos mantêm seus valores,
        sem aplicar os defaults de criação. null limpa apenas campos que o aceitam;
        zero é um preço válido e não ativa fallback. Preços são números JSON.
      anyOf:
        - required:
            - name
        - required:
            - price
        - required:
            - description
        - required:
            - delivery_price
        - required:
            - available
        - required:
            - available_in_delivery
        - required:
            - fiscal_info
          properties:
            fiscal_info:
              minProperties: 1
        - required:
            - limit
        - required:
            - show_on_report
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Nome não vazio; espaços nas extremidades são removidos.
        price:
          type: number
          minimum: 0
          multipleOf: 0.01
          description: Preço base presencial. Zero é válido.
          maximum: 9999999999999.99
        description:
          type:
            - string
            - 'null'
          maxLength: 255
          description: Texto descritivo. null limpa; omitir mantém o valor atual.
        delivery_price:
          type:
            - number
            - 'null'
          minimum: 0
          multipleOf: 0.01
          description: Preço de delivery. null usa o preço base no menu V1; zero é um preço válido.
          maximum: 9999999999999.99
        available:
          type: boolean
          description: Disponibilidade independente por canal.
        available_in_delivery:
          type: boolean
          description: Disponibilidade independente por canal.
        expected_updated_at:
          type: string
          format: date-time
          description: >-
            Copie updated_at da última consulta. Uma versão desatualizada retorna 409
            complement_update_conflict.
        fiscal_info:
          type: object
          description: >-
            Edição parcial dos atributos fiscais, apenas no PUT. Valores são strings ou null; null limpa
            o atributo, mas o objeto fiscal_info não pode ser null. fiscal_group_id não é editável. Um
            objeto vazio não constitui uma alteração.
          propertyNames:
            enum:
              - ncm
              - cfop
              - csosn
              - cst
              - cest
              - icms_origem
              - aliquota
              - base_calculo
              - pis
              - cofins
              - pis_aliquota
              - cofins_aliquota
              - icms_modalidade_base_calculo
              - icms_aliquota
              - icms_valor
              - cbenef
              - fcp_percentual
              - icms_base_calculo_retido_st
              - icms_aliquota_final
              - icms_valor_retido_st
              - icms_valor_substituto
              - icms_reducao_base_calculo
              - icms_motivo_desoneracao
              - icms_valor_desonerado
              - icms_aliquota_credito_simples
              - icms_valor_credito_simples
              - ibs_cbs_situacao_tributaria
              - ibs_cbs_classificacao_tributaria
              - icms_modalidade_base_calculo_st
              - icms_margem_valor_adicionado_st
              - icms_reducao_base_calculo_st
              - icms_aliquota_st
          additionalProperties:
            type:
              - string
              - 'null'
        limit:
          type: integer
          minimum: 0
          maximum: 2147483647
          description: Limite do complemento; não modifica limites dos grupos ou pivôs.
        show_on_report:
          type: boolean
          description: Participação do complemento nos relatórios.
    UpdateComplementRequest:
      $ref: '#/components/schemas/UpdateComplementFields'
      unevaluatedProperties: false
    UpdateComplementAvailabilityRequest:
      type: object
      additionalProperties: false
      anyOf:
        - required:
            - available
        - required:
            - available_in_delivery
      properties:
        available:
          type: boolean
        available_in_delivery:
          type: boolean
        expected_updated_at:
          type: string
          format: date-time

    UpdateProductRequest:
      $ref: "#/components/schemas/UpdateProductFields"
      unevaluatedProperties: false

    UpdateProductFields:
      type: object
      description: |
        Pelo menos um campo editável é necessário; expected_updated_at e id
        sozinhos não constituem uma alteração. Campos omitidos mantêm seus valores,
        sem aplicar os defaults de criação. null limpa apenas campos que o aceitam;
        zero é um preço válido e não ativa fallback. Preços são números JSON.
      allOf:
        - if:
            required: [replicate_ifood]
            properties:
              replicate_ifood: { const: true }
          then:
            required: [ifood_targets]
            properties:
              ifood_targets: { minItems: 1 }
      anyOf:
        - required: [pdv_codes]
          properties:
            pdv_codes: { minItems: 1 }
        - required: [replicate_ifood, ifood_targets]
          properties:
            replicate_ifood: { const: true }
            ifood_targets: { minItems: 1 }
        - required: [image_id]
        - required: [name]
        - required: [custom_order]
        - required: [product_category_id]
        - required: [price]
        - required: [description]
        - required: [price_promotion]
        - required: [delivery_price]
        - required: [delivery_price_promotion]
        - required: [sold_off]
        - required: [available]
        - required: [available_in_delivery]
        - required: [use_weight]
        - required: [has_starting_price]
        - required: [charge_service_tax]
        - required: [fiscal_info]
          properties:
            fiscal_info: { minProperties: 1 }
      properties:
        pdv_codes:
          type: array
          maxItems: 100
          description: Ajustes parciais por vínculo. id edita um vínculo Takeat/iFood do produto; sem id cadastra um código unificado Takeat. Omissões preservam códigos; não remove nem transfere códigos de outros produtos.
          items:
            type: object
            additionalProperties: false
            required: [code]
            properties:
              id: { type: integer, minimum: 1, maximum: 2147483647 }
              code: { type: string, minLength: 1, maxLength: 255, description: Texto aparado, preservando zeros à esquerda. }
        replicate_ifood:
          type: boolean
          default: false
          description: Apenas true tenta publicar após a confirmação da gravação local. OAuth exige também ifood:catalog:write. Por produto no lote; false não consulta token nem chama iFood.
        ifood_targets:
          type: array
          maxItems: 100
          description: Obrigatório e não vazio quando replicate_ifood=true; ignorado quando false. Cada código deve pertencer ao produto após a edição local. Máximo de 100 destinos somando todo o pedido; não repetir a mesma loja/item.
          items:
            type: object
            additionalProperties: false
            required: [code, ifood_restaurant_id, ifood_item_id]
            properties:
              code: { type: string, minLength: 1, maxLength: 255 }
              ifood_restaurant_id: { type: integer, minimum: 1, maximum: 2147483647 }
              ifood_item_id: { type: string, format: uuid }
              force: { type: boolean, default: false, description: Autoriza substituir um código remoto diferente. }
        custom_order:
          type: integer
          minimum: 0
          maximum: 2147483647
          description: Ordem crescente dentro da categoria, com desempate por ID. Compartilhada entre canais. Omitido preserva a ordem; ao trocar categoria, omitido coloca no final e explícito define a posição. Não renumera outros produtos.
        image_id:
          type: [integer, "null"]
          minimum: 1
          maximum: 2147483647
          description: ID de imagem enviada em POST /v1/files para o mesmo restaurante; null remove, omitido preserva na edição.
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Nome não vazio. Espaços nas extremidades são removidos; use o id para identificar o produto, não o nome.
        product_category_id:
          type: integer
          minimum: 1
          description: Categoria não removida do mesmo restaurante. Enviar este campo posiciona o produto ao final da categoria destino e usa a marca vinculada a ela.
        price:
          type: number
          minimum: 0
          multipleOf: 0.01
          description: Preço base presencial e último fallback do delivery; zero é aceito na edição. Não encerra promoções existentes. Por quilo se use_weight=true.
        description:
          type: [string, "null"]
          maxLength: 255
          description: Texto descritivo. null limpa; omitir mantém o valor atual.
        price_promotion:
          type: [number, "null"]
          minimum: 0
          multipleOf: 0.01
          description: Substitui price no presencial. null encerra a promoção; zero é um preço válido. Não é fallback do delivery no menu V1.
        delivery_price:
          type: [number, "null"]
          minimum: 0
          multipleOf: 0.01
          description: Preço de delivery e retirada nesse fluxo. Sem promoção de delivery, null usa price no menu V1; zero define preço zero. Não altera o preço próprio do iFood.
        delivery_price_promotion:
          type: [number, "null"]
          minimum: 0
          multipleOf: 0.01
          description: Preço promocional prioritário no delivery. null encerra a promoção sem alterar os demais preços; zero é válido.
        sold_off:
          type: boolean
          description: true sinaliza esgotamento; false sinaliza reposição. Não altera os canais habilitados. O menu V1 exclui esgotados com only_available=true e os mantém inspecionáveis com false.
        available:
          type: boolean
          description: Habilita ou desabilita o presencial, sem alterar delivery ou sold_off.
        available_in_delivery:
          type: boolean
          description: Habilita ou desabilita delivery e retirada nesse fluxo, sem alterar presencial ou sold_off.
        use_weight:
          type: boolean
          description: Indica venda por peso e preço por quilo. O fluxo de pedido precisa tratar o peso.
        has_starting_price:
          type: boolean
          description: Sinaliza “a partir de”; não transforma o produto em combo nem desativa o cálculo de pricing.resolved.minimum.
        charge_service_tax:
          type: boolean
          description: Participação na base da taxa de serviço presencial, quando aplicada. Não define percentual ou taxa de entrega.
        expected_updated_at:
          type: string
          format: date-time
          description: Copie o updated_at consultado, sem gerar uma nova data. Uma versão diferente retorna 409 product_update_conflict e impede todo o lote, quando usado em bulk.
        fiscal_info:
          type: object
          description: Edição parcial dos atributos fiscais, apenas no PUT. Valores são strings ou null; null limpa o atributo, mas o objeto fiscal_info não pode ser null. fiscal_group_id não é editável. Um objeto vazio não constitui uma alteração.
          propertyNames:
            enum:
              [
                ncm,
                cfop,
                csosn,
                cst,
                cest,
                icms_origem,
                aliquota,
                base_calculo,
                pis,
                cofins,
                pis_aliquota,
                cofins_aliquota,
                icms_modalidade_base_calculo,
                icms_aliquota,
                icms_valor,
                cbenef,
                fcp_percentual,
                icms_base_calculo_retido_st,
                icms_aliquota_final,
                icms_valor_retido_st,
                icms_valor_substituto,
                icms_reducao_base_calculo,
                icms_motivo_desoneracao,
                icms_valor_desonerado,
                icms_aliquota_credito_simples,
                icms_valor_credito_simples,
                ibs_cbs_situacao_tributaria,
                ibs_cbs_classificacao_tributaria,
                icms_modalidade_base_calculo_st,
                icms_margem_valor_adicionado_st,
                icms_reducao_base_calculo_st,
                icms_aliquota_st,
              ]
          additionalProperties: { type: [string, "null"] }

    UpdateProductAvailabilityRequest:
      type: object
      minProperties: 1
      description: Envie pelo menos um canal. Omitir o outro mantém seu valor; sold_off deve ser alterado no PUT individual ou em lote.
      properties:
        available:
          type: boolean
          description: Disponibilidade presencial. Não altera delivery nem esgotamento; a categoria também precisa estar disponível no menu filtrado.
        available_in_delivery:
          type: boolean
          description: Disponibilidade para delivery e retirada nesse fluxo. Não altera presencial nem esgotamento.
      additionalProperties: false

    ProductFiscal:
      type: object
      additionalProperties: false
      description: |
        Cadastro fiscal público do produto, não cálculo de tributos ou validação
        fiscal. Todos os atributos estão presentes; ausência de informação é null.
        Códigos e valores textuais preservam o cadastro; FCP é string decimal.
        Não inclui fiscal_group_id, custos, margens comerciais ou credenciais.
      required:
        [
          ncm,
          cfop,
          csosn,
          cst,
          cest,
          icms_origem,
          aliquota,
          base_calculo,
          pis,
          cofins,
          pis_aliquota,
          cofins_aliquota,
          icms_modalidade_base_calculo,
          icms_aliquota,
          icms_valor,
          cbenef,
          fcp_percentual,
          icms_base_calculo_retido_st,
          icms_aliquota_final,
          icms_valor_retido_st,
          icms_valor_substituto,
          icms_reducao_base_calculo,
          icms_motivo_desoneracao,
          icms_valor_desonerado,
          icms_aliquota_credito_simples,
          icms_valor_credito_simples,
          ibs_cbs_situacao_tributaria,
          ibs_cbs_classificacao_tributaria,
          icms_modalidade_base_calculo_st,
          icms_margem_valor_adicionado_st,
          icms_reducao_base_calculo_st,
          icms_aliquota_st,
        ]
      properties:
        ncm:
          type: [string, "null"]
          description: Código da Nomenclatura Comum do Mercosul, classificação da mercadoria.
        cfop:
          type: [string, "null"]
          description: Código Fiscal de Operações e Prestações cadastrado para o produto.
        csosn:
          type: [string, "null"]
          description: Código de Situação da Operação no Simples Nacional (ICMS).
        cst:
          type: [string, "null"]
          description: Código de Situação Tributária do ICMS no regime normal.
        cest:
          type: [string, "null"]
          description: Código Especificador da Substituição Tributária.
        icms_origem:
          type: [string, "null"]
          description: Código de origem da mercadoria usado no ICMS; não é endereço ou país em texto livre.
        aliquota:
          type: [string, "null"]
          description: Alíquota genérica legada, preservada como cadastrada; não é alias de icms_aliquota nem define um tributo por si só.
        base_calculo:
          type: [string, "null"]
          description: Base de cálculo genérica legada; não inferimos tributo, unidade ou valor calculado a partir deste campo.
        pis:
          type: [string, "null"]
          description: Código de situação tributária do PIS, não sua alíquota.
        cofins:
          type: [string, "null"]
          description: Código de situação tributária da COFINS, não sua alíquota.
        pis_aliquota:
          type: [string, "null"]
          description: Alíquota percentual de PIS cadastrada.
        cofins_aliquota:
          type: [string, "null"]
          description: Alíquota percentual de COFINS cadastrada.
        icms_modalidade_base_calculo:
          type: [string, "null"]
          description: Código da modalidade de determinação da base de cálculo do ICMS.
        icms_aliquota:
          type: [string, "null"]
          description: Alíquota de ICMS cadastrada; o FCP tem campo próprio.
        icms_valor:
          type: [string, "null"]
          description: Valor de ICMS cadastrado; não é o imposto calculado para um pedido.
        cbenef:
          type: [string, "null"]
          description: Código de benefício fiscal estadual (cBenef).
        fcp_percentual:
          type: [string, "null"]
          description: Percentual do Fundo de Combate à Pobreza (FCP).
        icms_base_calculo_retido_st:
          type: [string, "null"]
          description: Base de cálculo do ICMS-ST retido anteriormente.
        icms_aliquota_final:
          type: [string, "null"]
          description: Alíquota de ICMS-ST suportada pelo consumidor final.
        icms_valor_retido_st:
          type: [string, "null"]
          description: Valor de ICMS-ST retido anteriormente.
        icms_valor_substituto:
          type: [string, "null"]
          description: Valor do ICMS próprio do substituto tributário na operação anterior.
        icms_reducao_base_calculo:
          type: [string, "null"]
          description: Percentual de redução da base de cálculo do ICMS.
        icms_motivo_desoneracao:
          type: [string, "null"]
          description: Código do motivo de desoneração do ICMS.
        icms_valor_desonerado:
          type: [string, "null"]
          description: Valor de ICMS desonerado cadastrado.
        icms_aliquota_credito_simples:
          type: [string, "null"]
          description: Alíquota percentual de crédito de ICMS do Simples Nacional.
        icms_valor_credito_simples:
          type: [string, "null"]
          description: Valor de crédito de ICMS do Simples Nacional cadastrado.
        ibs_cbs_situacao_tributaria:
          type: [string, "null"]
          description: Código de situação tributária de IBS/CBS cadastrado.
        ibs_cbs_classificacao_tributaria:
          type: [string, "null"]
          description: Código de classificação tributária de IBS/CBS (cClassTrib) cadastrado.
        icms_modalidade_base_calculo_st:
          type: [string, "null"]
          description: Código da modalidade de determinação da base de cálculo do ICMS-ST.
        icms_margem_valor_adicionado_st:
          type: [string, "null"]
          description: Percentual da margem de valor adicionado (MVA) do ICMS-ST.
        icms_reducao_base_calculo_st:
          type: [string, "null"]
          description: Percentual de redução da base de cálculo do ICMS-ST.
        icms_aliquota_st:
          type: [string, "null"]
          description: Alíquota de ICMS-ST cadastrada.

    ProductItem:
      allOf:
        - $ref: "./openapi.yaml#/components/schemas/ProductItem"
        - type: object
          required: [fiscal]
          properties:
            fiscal:
              $ref: "#/components/schemas/ProductFiscal"

    ProductCategory:
      allOf:
        - $ref: "./openapi.yaml#/components/schemas/ProductCategory"
        - type: object
          properties:
            products:
              description: "Produtos da categoria (contrato plano de /v1/products), na ordem retornada pelo cadastro."
              type: array
              items:
                $ref: "#/components/schemas/ProductItem"

    ManagedProductPdvCode:
      type: object
      additionalProperties: false
      required: [id, code, integration]
      properties:
        id: { type: integer, description: ID do vínculo PDV, distinto do ID do produto. Use-o para editar um vínculo ativo Takeat ou Ifood do próprio produto. }
        code: { description: "Código PDV do vínculo (identificador do item no canal de integração).", type: string }
        integration: { type: string, description: Origem do vínculo; campo de leitura. Somente vínculos Takeat e Ifood são editáveis neste fluxo. }

    IfoodProductReplication:
      description: Resultado por destino após a gravação local. Um resultado diferente de succeeded produz HTTP 207 e preserva os dados locais. Consulte o guia /externo/v1/codigos-pdv-ifood para erros e recuperação.
      type: object
      required: [results]
      properties:
        results:
          description: "Um resultado por destino iFood solicitado, na ordem de ifood_targets."
          type: array
          items:
            type: object
            required: [code, ifood_restaurant_id, ifood_item_id, status]
            properties:
              code: { description: "Código PDV que foi (ou seria) gravado como código externo no item iFood.", type: string }
              ifood_restaurant_id: { description: "ID do vínculo da loja iFood (de GET /v1/integrations/ifood/merchants) usado como destino.", type: integer }
              ifood_item_id: { description: "ID (UUID) do item no catálogo iFood que recebe o código.", type: string, format: uuid }
              status:
                type: string
                enum: [succeeded, failed, unknown, not_attempted]
                description: succeeded confirma escrita ou código já igual; failed identifica falha; unknown exige consultar o código remoto antes de repetir; not_attempted indica destino não iniciado no prazo.
              overwritten: { type: boolean, description: Presente em sucesso; true indica substituição de um código remoto diferente. }
              error:
                description: "Erro do destino; presente apenas quando status não é succeeded."
                type: object
                required: [key, message]
                properties:
                  key: { description: "Código do erro (ex.: ifood_item_not_found, ifood_external_code_exists, ifood_deadline_exceeded, ifood_publication_failed).", type: string }
                  message: { description: "Mensagem legível (pt-BR) do erro do destino.", type: string }

    ManagedProduct:
      type: object
      description: |
        Estado atual do produto após consulta ou escrita. Preços são strings
        com duas casas decimais, ou null quando opcionais. Para editar, envie
        apenas campos aceitos e converta preços para números JSON. Use updated_at
        como expected_updated_at na próxima edição para detectar conflitos.
      required:
        - image_id
        - id
        - restaurant_id
        - product_category_id
        - custom_order
        - name
        - price
        - sold_off
        - available
        - available_in_delivery
        - use_weight
        - has_starting_price
        - charge_service_tax
        - fiscal
        - pdv_codes
        - created_at
        - updated_at
      properties:
        image_id:
          type: [integer, "null"]
          minimum: 1
          maximum: 2147483647
          description: ID de imagem enviada em POST /v1/files para o mesmo restaurante; null remove, omitido preserva na edição.
        id: { description: "Identificador do produto.", type: integer }
        restaurant_id: { description: "ID do restaurante dono do produto.", type: integer }
        product_category_id: { description: "ID da categoria de produtos à qual o produto pertence; veja GET /v1/product-categories.", type: integer }
        custom_order: { type: integer, description: Ordem atual dentro da categoria. }
        name: { description: "Nome do produto.", type: string }
        description: { description: "Descrição do produto; null quando não cadastrada.", type: [string, "null"] }
        price: { description: "Preço presencial em reais, string com 2 casas (ex.: \"28.00\").", type: string, example: "28.00" }
        price_promotion: { description: "Preço promocional presencial em reais (string, 2 casas); null sem promoção.", type: [string, "null"], example: "25.00" }
        delivery_price: { description: "Preço de delivery em reais (string, 2 casas); null faz o delivery usar price.", type: [string, "null"], example: "31.00" }
        delivery_price_promotion: { description: "Preço promocional de delivery em reais (string, 2 casas); null sem promoção. Não herda price_promotion.", type: [string, "null"] }
        sold_off: { description: "Produto esgotado: continua no cardápio, mas indisponível para venda (sold_out em /v1/menu).", type: boolean }
        available: { description: "Produto habilitado para venda presencial.", type: boolean }
        available_in_delivery: { description: "Produto habilitado para delivery/retirada.", type: boolean }
        use_weight: { description: "Se true, o produto é vendido por peso e os preços são por quilo; se false, por unidade.", type: boolean }
        has_starting_price: { description: "Se true, o preço é exibido como \"a partir de\" (valor mínimo); é apenas apresentação.", type: boolean }
        charge_service_tax: { description: "Se true (padrão na criação), o produto entra no cálculo da taxa de serviço.", type: boolean }
        pdv_codes:
          description: "Vínculos ativos do produto com códigos PDV por integração; lista vazia quando não há."
          type: array
          items: { $ref: "#/components/schemas/ManagedProductPdvCode" }
        ifood_replication:
          $ref: "#/components/schemas/IfoodProductReplication"
        fiscal:
          $ref: "#/components/schemas/ProductFiscal"
        created_at: { description: "Data de criação do produto (ISO 8601, UTC).", type: string, format: date-time }
        updated_at: { description: "Última alteração do produto (ISO 8601, UTC); envie como expected_updated_at na próxima edição para detectar conflito.", type: string, format: date-time }

    CashFlowNamedReference:
      type: object
      required: [id, name]
      properties:
        id: { description: "ID da conta bancária ou forma de pagamento referenciada.", type: integer }
        name: { description: "Nome da conta bancária ou forma de pagamento.", type: [string, "null"] }

    CashFlowProvider:
      type: object
      required: [id, name, cnpj, deleted]
      properties:
        id: { description: "ID do fornecedor.", type: integer }
        name: { description: "Nome do fornecedor; `null` quando não informado.", type: [string, "null"] }
        cnpj: { description: "CNPJ do fornecedor como armazenado (texto); `null` quando não informado.", type: [string, "null"] }
        deleted: { description: "`true` quando o fornecedor foi excluído após o lançamento.", type: boolean }

    CashFlowInvoice:
      type: object
      required: [numero, chave_nfe, data_emissao]
      properties:
        numero: { description: "Número da NF-e de entrada; `null` quando ausente.", type: [string, "null"] }
        chave_nfe: { description: "Chave de acesso da NF-e (44 dígitos); `null` quando ausente.", type: [string, "null"] }
        data_emissao: { description: "Data e hora de emissão da NF-e (ISO 8601, UTC); `null` quando ausente.", type: [string, "null"], format: date-time }

    CashFlowEntry:
      type: object
      required:
        - id
        - entry_type
        - counts_for_result
        - description
        - information
        - value
        - is_earning
        - paid
        - due_date
        - competence_date
        - paid_at
        - created_at
        - category
        - provider
        - bank_account
        - payment_method
        - invoice
      properties:
        id: { description: "ID do lançamento; use em `PATCH /v1/financial/cash-flows/{id}`.", type: integer }
        entry_type:
          description: "`standalone` (avulso), `invoice` (nota de entrada com itens), `invoice_item` (item da nota), `title` (título agrupador) ou `title_entry` (lançamento do título)."
          type: string
          enum: [standalone, invoice, invoice_item, title, title_entry]
        counts_for_result:
          type: boolean
          description: Se o lançamento deve entrar na análise por centro de custo.
        description: { description: "Descrição do lançamento informada na loja; `null` quando vazia.", type: [string, "null"] }
        information: { description: "Observações adicionais do lançamento; `null` quando vazias.", type: [string, "null"] }
        value: { description: "Valor do lançamento em reais, string com duas casas, sem sinal (use `is_earning`). Em notas e títulos é a soma dos `items`.", type: string, example: "1250.00" }
        is_earning: { description: "`true` para receita (a receber); `false` para despesa (a pagar).", type: boolean }
        paid: { description: "`true` quando o lançamento já foi pago/recebido (baixado).", type: boolean }
        due_date: { description: "Data de vencimento (YYYY-MM-DD, dia em UTC).", type: string, format: date }
        competence_date: { description: "Data de competência (YYYY-MM-DD, dia em UTC); `null` quando não informada.", type: [string, "null"], format: date }
        paid_at: { description: "Data e hora da baixa (ISO 8601, UTC); `null` enquanto em aberto.", type: [string, "null"], format: date-time }
        created_at: { description: "Data de criação do lançamento (ISO 8601, UTC).", type: string, format: date-time }
        category: { description: "Centro de custo no formato `Categoria: Subcategoria` (com subníveis, se houver); string vazia sem centro de custo.", type: string, example: "Insumos: Alimentos" }
        provider:
          description: "Fornecedor do lançamento; `null` quando não vinculado."
          oneOf:
            - $ref: "#/components/schemas/CashFlowProvider"
            - type: "null"
        bank_account:
          description: "Conta bancária do lançamento (`GET /v1/financial/bank-accounts`); `null` quando não definida."
          oneOf:
            - $ref: "#/components/schemas/CashFlowNamedReference"
            - type: "null"
        payment_method:
          description: "Forma de pagamento financeira (`GET /v1/financial/payment-methods`); `null` quando não definida."
          oneOf:
            - $ref: "#/components/schemas/CashFlowNamedReference"
            - type: "null"
        invoice:
          description: "Nota fiscal de entrada vinculada ao lançamento; `null` quando não há nota."
          oneOf:
            - $ref: "#/components/schemas/CashFlowInvoice"
            - type: "null"
        items:
          type: array
          description: Presente somente nos lançamentos do nível principal.
          items: { $ref: "#/components/schemas/CashFlowEntry" }

    CashFlowTotals:
      type: object
      required:
        - total_earnings
        - total_earnings_paid
        - total_expenses
        - total_expenses_paid
      properties:
        total_earnings: { description: "Soma em reais das receitas principais do período filtrado (pagas e abertas), com duas casas.", type: string, example: "12500.00" }
        total_earnings_paid: { description: "Soma em reais das receitas já recebidas (`paid: true`) do período, com duas casas.", type: string, example: "12000.00" }
        total_expenses: { description: "Soma em reais das despesas principais do período filtrado (pagas e abertas), com duas casas; valor positivo.", type: string, example: "8800.00" }
        total_expenses_paid: { description: "Soma em reais das despesas já pagas (`paid: true`) do período, com duas casas.", type: string, example: "1250.00" }

    CashFlowsResponse:
      type: object
      required:
        - total
        - count
        - remaining
        - limit
        - offset
        - start_date
        - end_date
        - date_type
        - totals
        - cash_flows
      properties:
        total: { description: "Total de lançamentos principais que atendem aos filtros no período (itens não contam).", type: integer }
        count: { description: "Quantidade de lançamentos principais nesta página.", type: integer }
        remaining: { description: "Lançamentos principais ainda não retornados (total − offset − count, mínimo 0).", type: integer }
        limit: { description: "Tamanho da página, fixo em 100 lançamentos principais.", type: integer, const: 100 }
        offset: { description: "Quantidade de lançamentos principais pulados nesta consulta.", type: integer }
        start_date: { description: "Primeiro dia consultado (YYYY-MM-DD).", type: string, format: date }
        end_date: { description: "Último dia consultado (YYYY-MM-DD), incluído por inteiro.", type: string, format: date }
        date_type:
          description: "Data usada no filtro de período: `due_date` (vencimento) ou `competence_date` (competência; sem competência, usa o vencimento)."
          type: string
          enum: [due_date, competence_date]
        totals: { description: "Totais de receitas e despesas de todo o período filtrado, não só da página.", $ref: "#/components/schemas/CashFlowTotals" }
        cash_flows:
          description: "Lançamentos principais da página, ordenados por vencimento e ID; notas e títulos trazem filhos em `items`."
          type: array
          items: { $ref: "#/components/schemas/CashFlowEntry" }

    PdvCode:
      type: object
      required: [code, integration]
      properties:
        code:
          description: "Código pelo qual o canal de integração conhece o item (ex.: código externo no iFood); null quando nunca publicado."
          type: [string, "null"]
        integration:
          description: "Canal de integração do código: Takeat, Ifood, Neemo, Keeta, DiDi, Repediu, Wabiz, Agilizone, PickNGo ou CardapioWeb. Valores desconhecidos viram Takeat."
          type: string

    MenuMoney:
      type: "string"
      pattern: "^-?\\d+\\.\\d{2}$"
      example: "20.00"
    MenuNullableMoney:
      type: ["string", "null"]
      pattern: "^-?\\d+\\.\\d{2}$"
      example: "20.00"
    MenuChannels:
      type: "object"
      additionalProperties: false
      required: ["in_store", "delivery", "self_service"]
      properties:
        in_store:
          description: "Item habilitado para venda presencial (canal in_store)."
          type: "boolean"
        delivery:
          description: "Item habilitado para delivery/retirada (canal delivery)."
          type: "boolean"
        self_service:
          description: "Item habilitado no autoatendimento (totem). Informativo; não entra no cálculo de resolved."
          type: "boolean"
    MenuSchedule:
      type: "object"
      additionalProperties: false
      required: ["enabled", "weekdays", "start_time", "end_time", "time_zone"]
      properties:
        enabled:
          description: "Se true, a janela de dias/horários restringe a venda; se false, o item vale em qualquer dia e horário."
          type: "boolean"
        weekdays:
          description: "Dias da semana permitidos (sunday…saturday), derivados da máscara de 7 dias iniciando no domingo."
          type: "array"
          items:
            type: "string"
            enum:
              [
                "sunday",
                "monday",
                "tuesday",
                "wednesday",
                "thursday",
                "friday",
                "saturday",
              ]
        start_time:
          type: ["string", "null"]
          description: "Horário local HH:mm:ss; início inclusivo."
        end_time:
          type: ["string", "null"]
          description: "Horário local HH:mm:ss; fim exclusivo. Intervalos noturnos pertencem ao dia do início."
        time_zone:
          description: "Fuso em que start_time/end_time são interpretados; igual a evaluation.time_zone."
          type: "string"
          example: "America/Sao_Paulo"
    MenuResolvedAvailability:
      type: "object"
      additionalProperties: false
      required: ["available", "reason"]
      properties:
        available:
          description: "true quando o item pode ser vendido no canal e instante avaliados."
          type: "boolean"
        reason:
          description: "Primeiro impedimento encontrado (null se disponível): channel_disabled, outside_schedule, sold_out, parent_unavailable, required_choices_unavailable ou invalid_configuration."
          type: ["string", "null"]
          enum:
            [
              null,
              "channel_disabled",
              "outside_schedule",
              "sold_out",
              "parent_unavailable",
              "required_choices_unavailable",
              "invalid_configuration",
            ]
    MenuImage:
      type: ["object", "null"]
      additionalProperties: false
      required: ["url", "thumbnail_url"]
      properties:
        url:
          description: "URL pública da imagem em tamanho original."
          type: "string"
          format: "uri"
        thumbnail_url:
          description: "URL pública da miniatura; quando não existe miniatura, repete a URL da imagem original."
          type: "string"
          format: "uri"
    MenuTag:
      type: ["object", "null"]
      additionalProperties: false
      required: ["id", "name", "color", "background_color"]
      properties:
        id:
          description: "Identificador da tag definido nas configurações de vitrine do restaurante."
          type: "string"
        name:
          description: "Nome da tag exibido no cardápio."
          type: "string"
        color:
          description: "Cor do texto da tag em hexadecimal (#RRGGBB); null se ausente ou fora desse formato."
          type: ["string", "null"]
        background_color:
          description: "Cor de fundo da tag em hexadecimal (#RRGGBB); null se ausente ou fora desse formato."
          type: ["string", "null"]
    MenuConfiguredPrice:
      type: "object"
      additionalProperties: false
      required: ["regular", "promotional"]
      properties:
        regular:
          description: "Preço de delivery cadastrado (string, reais, 2 casas); null usa o preço presencial regular."
          $ref: "#/components/schemas/MenuNullableMoney"
        promotional:
          description: "Preço promocional de delivery (string, reais, 2 casas); null sem promoção. A promoção presencial não é herdada."
          $ref: "#/components/schemas/MenuNullableMoney"
    MenuProductPricing:
      type: "object"
      additionalProperties: false
      required:
        [
          "currency",
          "in_store",
          "delivery",
          "resolved",
          "has_starting_price",
          "is_combo",
        ]
      properties:
        currency:
          description: "Código ISO 4217 da moeda do restaurante (padrão BRL)."
          type: "string"
          example: "BRL"
        in_store:
          description: "Preços configurados para venda presencial."
          type: "object"
          additionalProperties: false
          required: ["regular", "promotional"]
          properties:
            regular:
              description: "Preço presencial cadastrado, em reais, string decimal com 2 casas (ex.: \"20.00\")."
              $ref: "#/components/schemas/MenuMoney"
            promotional:
              description: "Preço promocional presencial em reais (string com 2 casas); null sem promoção. Quando presente, é a base resolvida em in_store."
              $ref: "#/components/schemas/MenuNullableMoney"
        delivery:
          description: "Preços configurados para delivery; valores null caem para os preços presenciais na resolução."
          $ref: "#/components/schemas/MenuConfiguredPrice"
        resolved:
          description: "Preços calculados no servidor para o canal avaliado: base, mínimo com escolhas obrigatórias e mínimo sem promoção."
          type: "object"
          additionalProperties: false
          required: ["channel", "base", "minimum", "minimum_without_promotion"]
          properties:
            channel:
              description: "Canal ao qual os preços resolvidos se referem; igual ao channel da resposta."
              type: "string"
              enum: ["in_store", "delivery"]
            base:
              $ref: "#/components/schemas/MenuMoney"
              description: "Primeiro preço não nulo: presencial promotional → regular; delivery promotional → regular → in_store.regular. Zero é válido; a promoção presencial não é herdada no delivery."
            minimum:
              $ref: "#/components/schemas/MenuNullableMoney"
              description: "Base mais o menor custo válido das escolhas obrigatórias. Null quando o produto não está elegível. Considera uma unidade de precificação (kg ou unidade), não o peso real, taxas ou frete."
            minimum_without_promotion:
              $ref: "#/components/schemas/MenuNullableMoney"
              description: "Mesmas escolhas mínimas com o preço base regular do canal; null quando inelegível."
        has_starting_price:
          type: "boolean"
          description: "Preferência de apresentação “a partir de”; não ativa ou desativa o cálculo do mínimo."
        is_combo:
          type: "boolean"
          description: "Nos combos, grupos obrigatórios compõem o preço mesmo com additional=false. Os preços das opções não são reescritos como diferenças."
    MenuComplement:
      type: "object"
      additionalProperties: false
      required:
        [
          "id",
          "name",
          "description",
          "custom_order",
          "created_at",
          "pricing",
          "availability",
          "selection",
          "presentation",
          "identifiers",
        ]
      properties:
        id:
          description: "Identificador do complemento (opção)."
          type: "integer"
        name:
          description: "Nome do complemento."
          type: "string"
        description:
          description: "Descrição do complemento; null quando não cadastrada."
          type: ["string", "null"]
        custom_order:
          description: "Posição da opção dentro deste grupo (crescente); a mesma opção pode ter posições diferentes em grupos diferentes."
          type: "integer"
        created_at:
          description: "Data de criação do complemento (ISO 8601, UTC)."
          type: "string"
          format: "date-time"
        pricing:
          description: "Preços do complemento: moeda, preços configurados por canal e preço resolvido."
          type: "object"
          additionalProperties: false
          required: ["currency", "in_store", "delivery", "resolved"]
          properties:
            currency:
              description: "Código ISO 4217 da moeda do restaurante (padrão BRL)."
              type: "string"
            in_store:
              description: "Preço presencial configurado do complemento."
              type: "object"
              additionalProperties: false
              required: ["regular", "promotional"]
              properties:
                regular:
                  description: "Preço presencial do complemento em reais, string com 2 casas (ex.: \"2.50\"). \"0.00\" indica opção sem custo."
                  $ref: "#/components/schemas/MenuMoney"
                promotional:
                  description: "Sempre null: complementos não têm preço promocional."
                  type: "null"
            delivery:
              description: "Preço de delivery configurado do complemento."
              type: "object"
              additionalProperties: false
              required: ["regular", "promotional"]
              properties:
                regular:
                  description: "Preço de delivery do complemento (string, reais, 2 casas); null usa o preço presencial."
                  $ref: "#/components/schemas/MenuNullableMoney"
                promotional:
                  description: "Sempre null: complementos não têm preço promocional de delivery."
                  type: "null"
            resolved:
              description: "Preço unitário da opção resolvido para o canal avaliado."
              type: "object"
              additionalProperties: false
              required: ["channel", "base"]
              properties:
                channel:
                  description: "Canal ao qual o preço resolvido se refere; igual ao channel da resposta."
                  type: "string"
                  enum: ["in_store", "delivery"]
                base:
                  description: "Preço unitário da opção no canal (reais, 2 casas): delivery usa delivery.regular ou, se null, in_store.regular."
                  $ref: "#/components/schemas/MenuMoney"
        availability:
          description: "Disponibilidade da opção: flags de canal, horários e resultado resolvido."
          type: "object"
          additionalProperties: false
          required: ["channels", "schedule", "resolved"]
          properties:
            channels:
              description: "Habilitação da opção por canal (in_store, delivery, self_service), como cadastrada."
              $ref: "#/components/schemas/MenuChannels"
            schedule:
              description: "Janela de dias e horários em que a opção é oferecida, no fuso evaluation.time_zone."
              $ref: "#/components/schemas/MenuSchedule"
            resolved:
              description: "Resultado da avaliação da opção; invalid_configuration quando max_quantity ≤ 0 ou preço negativo."
              $ref: "#/components/schemas/MenuResolvedAvailability"
        selection:
          description: "Limite de quantidade da opção (max_quantity: unidades desta opção permitidas por item pedido)."
          type: "object"
          additionalProperties: false
          required: ["max_quantity"]
          properties:
            max_quantity:
              type: "integer"
              description: "Máximo de unidades desta opção dentro do grupo."
        presentation:
          description: "Dados de exibição da opção: imagem e traduções."
          type: "object"
          additionalProperties: false
          required: ["image", "translations"]
          properties:
            image:
              description: "Imagem da opção com URLs públicas; null quando não cadastrada."
              $ref: "#/components/schemas/MenuImage"
            translations: { description: "Traduções livres da opção por idioma; null quando não há.",}
        identifiers:
          description: "Códigos de identificação da opção nas integrações."
          type: "object"
          additionalProperties: false
          required: ["pdv_codes"]
          properties:
            pdv_codes:
              description: "Códigos da opção em cada canal de integração em que está publicada; lista vazia se nenhum."
              type: "array"
              items:
                $ref: "#/components/schemas/PdvCode"
    MenuComplementCategory:
      type: "object"
      additionalProperties: false
      required:
        [
          "id",
          "name",
          "question",
          "custom_order",
          "selection",
          "pricing",
          "availability",
          "presentation",
          "complements",
        ]
      properties:
        id:
          description: "Identificador do grupo de complementos."
          type: "integer"
        name:
          description: "Nome interno do grupo de complementos."
          type: "string"
        question:
          description: "Pergunta exibida ao cliente para o grupo (ex.: \"Escolha o ponto da carne\"); null quando não cadastrada."
          type: ["string", "null"]
        custom_order:
          description: "Posição do grupo dentro deste produto (ordem do vínculo produto–grupo, crescente)."
          type: "integer"
        selection:
          description: "Regras de seleção do grupo: opcionalidade, mínimo e máximo normalizados, escolha única e obrigatoriedade."
          type: "object"
          additionalProperties: false
          required:
            ["optional", "minimum", "maximum", "single_choice", "required"]
          properties:
            optional:
              type: "boolean"
              description: "Permite não escolher nenhuma opção. Se houver escolhas, o mínimo configurado continua aplicável."
            minimum:
              type: "integer"
              description: "Mínimo normalizado: null na origem significa 1 para grupo obrigatório ou 0 para opcional; zero explícito continua zero."
            maximum:
              type: "integer"
              description: "Máximo total de unidades; limitado a 1 em single_choice."
            single_choice:
              description: "Se true, o cliente escolhe no máximo uma opção (maximum fica limitado a 1)."
              type: "boolean"
            required:
              description: "true quando o grupo é obrigatório: não opcional e com mínimo normalizado maior que zero."
              type: "boolean"
        pricing:
          description: "Regras de cobrança do grupo: modo resolvido, flags configuradas e acréscimo mínimo."
          type: "object"
          additionalProperties: false
          required:
            [
              "mode",
              "additional",
              "use_average",
              "more_expensive_only",
              "minimum",
            ]
          properties:
            mode:
              type: "string"
              enum: ["included", "sum", "average", "highest"]
              description: "Regra canônica. included não acrescenta custo; sum soma preço × quantidade; average usa média ponderada por quantidade; highest usa o maior preço unitário escolhido. highest prevalece sobre average."
            additional:
              description: "Flag configurada: se true, as opções escolhidas somam ao preço do produto; se false, são incluídas sem custo (exceto grupos obrigatórios de combo). Use pricing.mode."
              type: "boolean"
            use_average:
              description: "Flag configurada: cobra a média dos preços escolhidos em vez da soma. Use pricing.mode como regra final."
              type: "boolean"
            more_expensive_only:
              description: "Flag configurada: cobra apenas a opção mais cara escolhida; prevalece sobre use_average. Use pricing.mode."
              type: "boolean"
            minimum:
              $ref: "#/components/schemas/MenuNullableMoney"
              description: "Menor acréscimo obrigatório do grupo; zero quando opcional e utilizável; null quando indisponível ou sem configuração válida."
        availability:
          description: "Disponibilidade do grupo: flags de canal, exclusividade, horários e resultado resolvido."
          type: "object"
          additionalProperties: false
          required: ["channels", "exclusive", "schedule", "resolved"]
          properties:
            channels:
              description: "Habilitação do grupo por canal (in_store, delivery, self_service), como cadastrada."
              $ref: "#/components/schemas/MenuChannels"
            exclusive:
              description: "Uso exclusivo da equipe: true indica grupo ocultado pelos apps do cliente. Não altera resolved."
              type: "boolean"
            schedule:
              description: "Janela de dias e horários em que o grupo é oferecido, no fuso evaluation.time_zone."
              $ref: "#/components/schemas/MenuSchedule"
            resolved:
              description: "Resultado da avaliação do grupo; fica indisponível se o produto estiver indisponível ou se nenhuma opção válida atender ao mínimo."
              $ref: "#/components/schemas/MenuResolvedAvailability"
        presentation:
          description: "Dados de exibição do grupo (traduções)."
          type: "object"
          additionalProperties: false
          required: ["translations"]
          properties:
            translations: { description: "Traduções livres do grupo por idioma; null quando não há.",}
        complements:
          description: "Opções do grupo ordenadas pela posição no grupo e id. Com only_available=true, só opções elegíveis."
          type: "array"
          items:
            $ref: "#/components/schemas/MenuComplement"
    MenuProduct:
      type: "object"
      additionalProperties: false
      required:
        [
          "id",
          "name",
          "description",
          "custom_order",
          "created_at",
          "pricing",
          "availability",
          "presentation",
          "sale",
          "identifiers",
        ]
      properties:
        id:
          description: "Identificador do produto."
          type: "integer"
        name:
          description: "Nome do produto."
          type: "string"
        description:
          description: "Descrição do produto; null quando não cadastrada."
          type: ["string", "null"]
        custom_order:
          description: "Posição do produto dentro da categoria (crescente); empates pelo id."
          type: "integer"
        created_at:
          description: "Data de criação do produto (ISO 8601, UTC)."
          type: "string"
          format: "date-time"
        pricing:
          description: "Preços do produto: moeda, preços configurados por canal e preços resolvidos para o canal consultado."
          $ref: "#/components/schemas/MenuProductPricing"
        availability:
          description: "Disponibilidade do produto: flags de canal, agendamento, esgotamento, horários e resultado resolvido."
          type: "object"
          additionalProperties: false
          required:
            ["channels", "scheduled_orders", "sold_out", "schedule", "resolved"]
          properties:
            channels:
              description: "Habilitação do produto por canal de venda, como cadastrada."
              $ref: "#/components/schemas/MenuChannels"
            scheduled_orders:
              type: "boolean"
              description: "Permissão de catálogo para entrega agendada, independente da flag de delivery imediato. Não garante horário de entrega ou capacidade."
            sold_out:
              description: "Produto esgotado no momento: continua listado com only_available=false, mas resolved fica indisponível com reason sold_out."
              type: "boolean"
            schedule:
              description: "Janela de dias e horários em que o produto é vendido, no fuso evaluation.time_zone."
              $ref: "#/components/schemas/MenuSchedule"
            resolved:
              description: "Resultado da avaliação do produto; herda indisponibilidade da categoria e considera esgotamento, preço e grupos obrigatórios."
              $ref: "#/components/schemas/MenuResolvedAvailability"
        presentation:
          description: "Dados de exibição do produto: imagem, destaque, rótulo de promoção, traduções e tag."
          type: "object"
          additionalProperties: false
          required:
            [
              "image",
              "translations",
              "featured",
              "featured_at",
              "promotion_label",
              "tag",
            ]
          properties:
            image:
              description: "Imagem do produto com URLs públicas; null quando não cadastrada."
              $ref: "#/components/schemas/MenuImage"
            translations: { description: "Traduções livres do produto por idioma (ex.: {\"en\": {\"name\": ...}}); null quando não há.",}
            featured:
              description: "Produto marcado como destaque no cardápio."
              type: "boolean"
            featured_at:
              description: "Quando o produto foi marcado como destaque (ISO 8601, UTC); null se não houver registro."
              type: ["string", "null"]
              format: "date-time"
            promotion_label:
              description: "Texto livre de promoção cadastrado no produto; null quando ausente."
              type: ["string", "null"]
            tag:
              description: "Tag de vitrine (delivery) atribuída ao produto; null quando não há tag."
              $ref: "#/components/schemas/MenuTag"
        sale:
          description: "Regras de venda do produto: unidade de precificação, quantidade única e taxa de serviço."
          type: "object"
          additionalProperties: false
          required: ["unit", "is_unitary", "service_tax_applicable"]
          properties:
            unit:
              description: "Unidade de precificação: kg (vendido por peso; preços são por quilo) ou unit (por unidade)."
              type: "string"
              enum: ["kg", "unit"]
            is_unitary:
              description: "Se true, o item é pedido sempre com quantidade 1 (sem seletor de quantidade; \"Escolha única\" no painel)."
              type: "boolean"
            service_tax_applicable:
              description: "Se true, o produto entra na base de cálculo da taxa de serviço. O menu não calcula a taxa."
              type: "boolean"
        identifiers:
          description: "Códigos de identificação do produto: EANs e códigos por integração/PDV."
          type: "object"
          additionalProperties: false
          required: ["ean_codes", "pdv_codes"]
          properties:
            ean_codes:
              description: "Códigos de barras (EAN/GTIN) do produto; lista vazia quando não há."
              type: "array"
              items:
                type: "string"
            pdv_codes:
              description: "Códigos do produto em cada canal de integração em que está publicado; lista vazia se nenhum."
              type: "array"
              items:
                $ref: "#/components/schemas/PdvCode"
        complement_categories:
          type: "array"
          items:
            $ref: "#/components/schemas/MenuComplementCategory"
          description: "Presente somente com include_complements=true. Sua omissão não muda os preços nem a disponibilidade resolvida."
        fiscal:
          $ref: "#/components/schemas/ProductFiscal"
          description: "Presente somente com include_fiscal_info=true. Sem alias fiscal_info nem identificadores internos."
    MenuCategory:
      type: "object"
      additionalProperties: false
      required:
        [
          "id",
          "name",
          "custom_order",
          "created_at",
          "preparation_time_minutes",
          "availability",
          "presentation",
          "products",
        ]
      properties:
        brand:
          type: ["object", "null"]
          description: Marca da categoria; apenas ID e nome de exibição, verificados no restaurante. Ausente para metadados de marca excluída.
          additionalProperties: false
          required: [id, name]
          properties:
            id: { description: "ID da marca à qual a categoria pertence; use em brand_id para filtrar o cardápio.", type: integer, minimum: 1 }
            name: { description: "Nome público da marca: nome fantasia, nome cadastrado ou \"Marca #<id>\".", type: string }
        id:
          description: "Identificador da categoria de produtos."
          type: "integer"
        name:
          description: "Nome da categoria exibido no cardápio."
          type: "string"
        custom_order:
          description: "Posição da categoria no cardápio (crescente); empates são desempatados pelo id."
          type: "integer"
        created_at:
          description: "Data de criação da categoria (ISO 8601, UTC)."
          type: "string"
          format: "date-time"
        preparation_time_minutes:
          description: "Tempo de preparo configurado para a categoria, em minutos; null quando não configurado."
          type: ["integer", "null"]
        availability:
          description: "Flags de canal, exclusividade, janela de horários e resultado resolvido da disponibilidade da categoria."
          type: "object"
          additionalProperties: false
          required: ["channels", "exclusive", "schedule", "resolved"]
          properties:
            channels:
              description: "Habilitação da categoria em cada canal de venda, como configurado. Apenas in_store e delivery entram no cálculo de resolved."
              type: "object"
              additionalProperties: false
              required: ["in_store", "delivery", "self_service", "drive_thru"]
              properties:
                in_store:
                  description: "Categoria habilitada para venda presencial (canal in_store)."
                  type: "boolean"
                delivery:
                  description: "Categoria habilitada para delivery/retirada (canal delivery)."
                  type: "boolean"
                self_service:
                  description: "Categoria habilitada no autoatendimento (totem). Informativo; não afeta resolved."
                  type: "boolean"
                drive_thru:
                  description: "Categoria habilitada no drive-thru. Informativo; não afeta resolved."
                  type: "boolean"
            exclusive:
              description: "Uso exclusivo da equipe: true indica categoria que os apps do cliente ocultam (só aparece para garçom/PDV). Não altera resolved."
              type: "boolean"
            schedule:
              description: "Janela de dias e horários em que a categoria é vendida, no fuso evaluation.time_zone."
              $ref: "#/components/schemas/MenuSchedule"
            resolved:
              description: "Resultado da avaliação de disponibilidade da categoria no canal e instante avaliados."
              $ref: "#/components/schemas/MenuResolvedAvailability"
        presentation:
          description: "Dados de exibição da categoria: imagem, ícone e traduções."
          type: "object"
          additionalProperties: false
          required: ["image", "translations", "icon"]
          properties:
            image:
              description: "Imagem da categoria com URLs públicas; null quando não cadastrada."
              $ref: "#/components/schemas/MenuImage"
            translations: { description: "Traduções livres definidas no editor de cardápio, por idioma (ex.: {\"en\": {\"name\": ...}}); null quando não há.",}
            icon:
              description: "Identificador do ícone da categoria usado no app de tablet; null quando não configurado."
              type: ["string", "null"]
        products:
          description: "Produtos da categoria, ordenados por custom_order e id. Com only_available=true, só os produtos elegíveis."
          type: "array"
          items:
            $ref: "#/components/schemas/MenuProduct"
    MenuResponse:
      type: "object"
      additionalProperties: false
      required: ["restaurant_id", "restaurant_identity", "channel", "evaluation", "categories"]
      properties:
        restaurant_id:
          description: "ID do restaurante cujo cardápio foi resolvido."
          type: "integer"
        restaurant_identity:
          type: ["object", "null"]
          additionalProperties: false
          description: "Somente nome público e avatar do restaurante autorizado, sem dados privados da conta."
          required: ["name", "image"]
          properties:
            name:
              description: "Nome público do restaurante: nome fantasia, ou razão/nome cadastrado, ou \"Restaurante #<id>\" quando ambos estão vazios."
              type: "string"
              example: "Bistrô Aurora"
            image:
              description: "Avatar do restaurante com URLs públicas (imagem e miniatura); null quando não há avatar cadastrado."
              $ref: "#/components/schemas/MenuImage"
        channel:
          description: "Canal avaliado (eco do parâmetro channel, padrão in_store). Define preços resolvidos e flags de canal usadas na disponibilidade."
          type: "string"
          enum: ["in_store", "delivery"]
        evaluation:
          description: "Contexto em que disponibilidade e horários foram avaliados: instante, fuso e modo (imediato ou agendado)."
          type: "object"
          additionalProperties: false
          required: ["at", "time_zone", "mode"]
          properties:
            at:
              description: "Instante avaliado (ISO 8601 UTC): o scheduled_at enviado ou o horário do servidor na requisição."
              type: "string"
              format: "date-time"
            time_zone:
              description: "Fuso usado para avaliar horários (configuração do serviço, padrão America/Sao_Paulo); não é configurável por restaurante."
              type: "string"
              example: "America/Sao_Paulo"
            mode:
              description: "immediate: avaliado no instante da requisição; scheduled: avaliado no scheduled_at informado (exige channel=delivery)."
              type: "string"
              enum: ["immediate", "scheduled"]
        categories:
          description: "Seções do cardápio ordenadas por custom_order e depois id. Com only_available=true, seções indisponíveis ou sem produtos elegíveis são removidas."
          type: "array"
          items:
            $ref: "#/components/schemas/MenuCategory"
