openapi: 3.0.1
info:
  title: idworks API
  version: '2026-05-29'
  description: >-
    Documentação da API idworks (sa-east-1). Cobre Contas a Pagar (`/accounts/payable`), Contas a Receber
    (`/accounts/receivable`) — incluindo conciliação de adquirentes e marketplace — Contas Bancárias
    (`/accounts/bank-account`), Conciliação Bancária (`/accounts/bank-statement`, incluindo transferências e regras),
    Fluxo de Caixa (`/accounts/cash-flow`), Plano de Contas (`/type/account/type`), Tipo Pedido (`/type/order/type`),
    Marcas, Fornecedores, Categorias de Fornecedores, Tipo Documento, DE-PARA CFOP recebimento, Webhook, Perfil de
    Acesso, Ações em Massa e Integrações.


    Convenção de erro: as mensagens de erro vêm prefixadas, e cada prefixo corresponde a um status HTTP — `[BadRequest]
    ...` → 400 e `Error: ...` → 500. Respostas sem prefixo são tratadas como 200, e Produção (Linha de Produção e Ordens
    de Produção). Inclui também a configuração de Mensagem Tracking (templates de e-mail e webhook disparados nas
    transições de status de rastreio).
  license:
    name: Proprietary
    url: https://idworks.com.br
servers:
  - url: https://{AccountName}.api-idworks.com.br/{basePath}
    description: Produção (substitua AccountName pelo nome da sua conta)
    variables:
      AccountName:
        default: teste
        description: Nome da conta idworks do cliente (use "teste" para a conta de demonstração).
      basePath:
        default: '1.0'
        description: Versão da API
security:
  - JWT: []
tags:
  - name: Agendamento de Recebimento
  - name: Armazéns
  - name: Arquivos
  - name: Autenticação
  - name: Boleto Bancário
  - name: CT-e
  - name: Cadastro de Clientes
  - name: Cadastro de Fornecedores
  - name: Cadastro de Usuários
  - name: Categorias Similares
  - name: Categorias de Fornecedor
  - name: Categorias de Produto
  - name: Centros de Distribuição
  - name: Cobrança
  - name: Coleções
  - name: Conciliação Bancária
  - name: Contas Bancárias
  - name: Contas a Pagar
  - name: Contas a Receber
  - name: Correios — PI
  - name: Cotação de Frete
  - name: Códigos Similares
  - name: Códigos de Barras
  - name: Códigos de Barras (Embalagem)
  - name: DE-PARA CFOP Recebimento
  - name: Dashboards
  - name: Departamentos Tributários
  - name: Endereços de Estoque
  - name: Especificações de SKU
  - name: Especificações por Categoria
  - name: Etiquetas (Empresa)
  - name: Faixa de Etiquetas Correios
  - name: Feed de NF-e
  - name: Fluxo de Caixa
  - name: Fornecedores ↔ SKUs
  - name: Frente de Caixa
  - name: Grupos de SKU
  - name: Hub — Anúncios
  - name: Hub — Categorias
  - name: Hub — DE-PARA Adquirentes
  - name: Hub — DE-PARA Transportadora
  - name: Hub — DE-PARA Variações
  - name: Hub — Estoque
  - name: Hub — Marcas
  - name: Hub — Notificações
  - name: Hub — Pagamento
  - name: Hub — Pedidos
  - name: Hub — Política Comercial
  - name: Hub — Recursos
  - name: Hub — Tipos de Referência
  - name: Imagens de SKU
  - name: Integrações
  - name: Inventário
  - name: Inventário (Legacy)
  - name: Jobs e Tarefas
  - name: Jornada de Trabalho
  - name: Kits
  - name: Log de SKU
  - name: Logs de Webhook
  - name: Logística Reversa Correios
  - name: Lotes
  - name: Marcas
  - name: Metas
  - name: Minha Empresa
  - name: Modalidades de Transporte
  - name: Movimentação de Estoque
  - name: Módulos Contratados
  - name: NF-e / NFC-e
  - name: NFS-e
  - name: Notificações de Versão
  - name: Números de Série
  - name: Packing
  - name: Pagamento PDV
  - name: Pedido de Compra
  - name: Pedidos
  - name: Perfis de Acesso
  - name: Picking
  - name: Políticas Comerciais
  - name: Preços
  - name: Produtos e SKUs
  - name: Produção
  - name: Promoção PDV
  - name: Recebimento
  - name: Recálculo de Custo
  - name: Relatórios Customizados
  - name: Ressuprimento
  - name: SKU — Etiqueta
  - name: Saldo de Estoque
  - name: Tags de SKU
  - name: Templates de Importação
  - name: Templates de Rastreamento
  - name: Tipos de Embalagem
  - name: Tipos — CT-e
  - name: Tipos — Canal de Venda
  - name: Tipos — Cliente
  - name: Tipos — Compras
  - name: Tipos — Contas e Pagamento
  - name: Tipos — Cotação
  - name: Tipos — Empresa
  - name: Tipos — Etiquetas
  - name: Tipos — Fornecedor
  - name: Tipos — Fulfillment
  - name: Tipos — Impostos
  - name: Tipos — Jobs
  - name: Tipos — Metas
  - name: Tipos — Nota Fiscal
  - name: Tipos — PDV
  - name: Tipos — Pedido
  - name: Tipos — Relatórios
  - name: Tipos — SKU
  - name: Tipos — Usuário
  - name: Transições de Status
  - name: Variações (Grade)
paths:
  /accounts/bank-account:
    get:
      operationId: bankAccountList
      tags:
        - Contas Bancárias
      summary: Lista contas bancárias da empresa
      description: >-
        Retorna as contas bancárias ativas da empresa. Cada item traz o saldo atual e o saldo previsto até uma data
        futura. Aceita filtros opcionais por faturador e número do banco.
      parameters:
        - name: DateForecast
          in: query
          required: false
          description: >-
            Data limite (inclusive) para o cálculo de `BalanceForecast`. Default: data atual (não calcula saldo futuro
            além de hoje).
          schema:
            type: string
            format: date
        - name: IDCompanyInvoice
          in: query
          required: false
          description: Filtra apenas contas cujo faturador corresponde a este id de empresa.
          schema:
            type: integer
        - name: BankNumber
          in: query
          required: false
          description: Filtra pelo código Febraban do banco. Aceita string de até 3 caracteres.
          schema:
            type: string
            maxLength: 3
      responses:
        '200':
          description: Lista de contas bancárias (vazia se não houver match).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BankAccountListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: bankAccountPost
      tags:
        - Contas Bancárias
      summary: Cadastra uma conta bancária
      description: >-
        Cria uma conta bancária para a empresa. Quando a conta é marcada como **principal de recebimento** ou
        **principal de pagamento**, qualquer outra conta da mesma combinação de empresa e faturador é automaticamente
        desmarcada (só uma pode ser principal por vez).


        O faturador, a integração bancária e o tipo de pedido (quando informados) são validados contra os cadastros da
        empresa.


        A resposta é a lista atualizada de contas bancárias, no mesmo formato do `GET /accounts/bank-account`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankAccountCreate'
        description: >-
          Dados da conta bancária a cadastrar. `Bank` e `BankNumber` são obrigatórios; demais campos são opcionais.
          Marcar `MainIncome=1` ou `MainPayment=1` desmarca automaticamente a conta principal anterior do mesmo
          faturador.
      responses:
        '200':
          description: Conta criada. Retorna a lista atualizada de contas bancárias.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BankAccountListItem'
        '400':
          description: >-
            Validação falhou (prefixo `[BadRequest]`). Mensagens possíveis: `Empresa não existe`, `Faturador não
            existe`, `Integração não existe`, `Integração Pix não existe`, `Tipo pedido não existe`, `Tipo pedido não
            esta habilitado para frente de caixa`, `Tipo pedido não esta habilitado para esta empresa/faturador, ajustar
            no cadastro`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /accounts/bank-account/{idbankaccount}:
    parameters:
      - name: idbankaccount
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador da conta bancária.
    put:
      operationId: bankAccountPut
      tags:
        - Contas Bancárias
      summary: Atualiza uma conta bancária
      description: >-
        Atualiza a conta bancária de forma parcial — apenas os campos enviados são alterados.


        A operação tem **dois modos**, decididos pelo corpo da requisição:


        - **Atualização de cadastro** (modo padrão): altera dados como `Bank`, `BankNumber`, `BankRouting`,
        `AccountNumber`, integração, faturador, terminal TEF, tipo de pedido. Vale a mesma regra do POST: marcar uma
        conta como principal de recebimento ou pagamento desmarca as demais. Tentar mudar `BankNumber` quando a conta
        atual é interna (`000`) e existe caixa aberto vinculado é bloqueado.

        - **Ajuste de saldo inicial**: quando `InitialBalance` e `InitialBalanceDate` são enviados, o endpoint calcula a
        diferença entre o saldo desejado e o saldo atual até o dia anterior à data informada, e insere um lançamento de
        ajuste no extrato bancário. Quando a diferença é zero, responde com erro.


        A resposta (no modo cadastro ou quando há ajuste de saldo aplicado) é a lista atualizada de contas bancárias.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankAccountUpdate'
        description: >-
          Campos da conta bancária a atualizar (atualização parcial — só os enviados são aplicados). Para ativar o
          **modo de ajuste de saldo inicial**, envie `InitialBalance` junto com `InitialBalanceDate`; nesse modo os
          demais campos são ignorados e um lançamento de ajuste é gravado no extrato.
      responses:
        '200':
          description: Conta atualizada. Retorna a lista atualizada de contas bancárias.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BankAccountListItem'
        '400':
          description: >-
            Validação falhou (prefixo `[BadRequest]`). Possíveis mensagens: `Empresa não existe`, `Faturador não
            existe`, `Integração não existe`, `Integração Pix não existe`, `Tipo pedido não existe`, `Tipo pedido não
            esta habilitado para frente de caixa`, `Tipo pedido não esta habilitado para esta empresa/faturador, ajustar
            no cadastro`, `Conta possui caixa aberto e não pode editado`, `Nenhum ajuste aplicado` (quando o ajuste de
            saldo resulta em diferença zero).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: bankAccountDelete
      tags:
        - Contas Bancárias
      summary: Exclui (inativa) uma conta bancária
      description: |-
        Inativa a conta bancária (`Status = 0`). Não exclui fisicamente o registro.

        **Regras impeditivas**:
        - A conta não pode ter lançamentos de pagamento ou recebimento.
        - A conta não pode estar vinculada como conta prevista em algum título a pagar ou receber.
        - A conta não pode ter sido usada em abertura de caixa do PDV.

        A resposta é a lista atualizada de contas bancárias.
      responses:
        '200':
          description: Conta inativada. Retorna a lista atualizada de contas bancárias.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BankAccountListItem'
        '400':
          description: >-
            Regras impeditivas (prefixo `[BadRequest]`): `Conta bancária não existe`, `Conta bancária já possui
            pagamento / recebimento e não pode ser excluída`, `Contas a pagar/receber esta com esta conta bancária e não
            pode ser excluída`, `Conta bacária já foi utilizada em abertura de caixa (PDV) e não pode ser excluída`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /accounts/bank-statement:
    get:
      operationId: bankStatementList
      tags:
        - Conciliação Bancária
      summary: Extrato bancário ou conciliação bancária
      description: >-
        Retorna lançamentos do extrato bancário. O comportamento muda conforme o valor de `Source`:


        - **`Source=1` (extrato interno)**: lista os lançamentos do extrato do idworks (entradas e saídas conciliadas
        com títulos a pagar/receber), com saldo corrente calculado linha a linha (`Balance`), saldo do período anterior
        (`PreviousBalance`), totais de recebimentos/pagamentos e saldo final. A resposta é um objeto único agregado.

        - **`Source=2` (extrato bancário)**: lista os lançamentos importados do banco (conciliação), agrupados por
        `IDBankStatementConciliation`, com a lista de contas internas (`InternalAccounts[]`) que casam com cada
        lançamento bancário, totais por tipo e diferença entre o valor lançado no banco e a soma das contas internas. A
        resposta é um array.

        - **`Source=1` com `IDBankStatementConciliation`** (modo especial): retorna apenas as contas internas vinculadas
        a uma conciliação bancária específica, como array.


        Quando `Source` não é `1` nem `2`, devolve erro. Aceita filtros de data (`DateFrom`/`DateTo`), conta bancária,
        tipo de transação, status de conciliação, e suporta paginação por `Page`.
      parameters:
        - name: Source
          in: query
          required: true
          schema:
            type: integer
            enum:
              - 1
              - 2
          description: '`1` extrato interno (idworks), `2` extrato bancário (importado).'
        - name: IDBankAccount
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por conta bancária.
        - name: IDCompany
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por empresa (quando o usuário tem acesso a múltiplas).
        - name: IDTypeAccount
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: 'Tipo do lançamento: 0=entrada, 1=saída.'
        - name: DateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data inicial. No modo `Source=2`, default é `2025-01-01` quando omitida.
        - name: DateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: 'Data final. Default: hoje quando `DateFrom` for informada.'
        - name: Page
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: Página (5000 itens por página).
        - name: IDBankStatement
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por lançamento interno específico.
        - name: IDBankStatementConciliation
          in: query
          required: false
          schema:
            type: integer
          description: >-
            Em `Source=1`, ativa o modo especial que retorna apenas contas internas dessa conciliação. Em `Source=2`,
            restringe ao grupo.
        - name: IDTypeStatusConciliation
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 3
              - 4
          description: (Source=2) Filtra por status da conciliação.
        - name: OnlyTransfer
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
          description: (Source=1) Quando `1`, traz apenas transferências (lançamentos sem título associado).
        - name: Ignore
          in: query
          required: false
          schema:
            type: integer
          description: Reservado (lido do query mas sem efeito documentado no caminho atual).
      responses:
        '200':
          description: Resultado depende de `Source` e dos filtros.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/BankStatementInternalResponse'
                  - type: array
                    items:
                      $ref: '#/components/schemas/BankStatementConciliationEntry'
                    description: Resposta no modo `Source=2`.
                  - type: array
                    items:
                      $ref: '#/components/schemas/BankStatementConciliationInternal'
                    description: Resposta no modo `Source=1` com `IDBankStatementConciliation`.
        '400':
          description: Erro de validação dos filtros enviados.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: bankStatementPost
      tags:
        - Conciliação Bancária
      summary: Concilia títulos ou transferências com um lançamento bancário ou de adquirente
      description: >-
        Vincula um conjunto de títulos a pagar/receber **ou** de transferências entre contas a um único lançamento —
        bancário ou de adquirente. O corpo deve identificar **exatamente uma** das duas conciliações em
        `IDBankStatementConciliation` (conciliação bancária) ou `IDAccountsPayableReceivableConciliation` (conciliação
        de adquirente), e também **exatamente uma** das listas: `Accounts[]` para títulos a pagar/receber, ou
        `Transfers[]` para transferências entre contas já lançadas.


        Fluxo:


        - **Conciliação de adquirente** com `Accounts[]`: cria os lançamentos no extrato interno
        (`AccountsPayableReceivableBankStatement`) para cada título, vincula via
        `AccountsPayableReceivableConciliationMatch` e marca a conciliação de adquirente como `ConciliationStatus=3`
        (Manual).

        - **Conciliação bancária** com `Accounts[]`: o status final depende dos valores — `3` quando o total dos títulos
        bate com o valor bancário, `4` (parcial) quando ainda falta reconciliar.

        - **Quando o título já tem lançamento** com a mesma data da conciliação, o lançamento existente é reaproveitado
        em vez de criar novo. Lançamentos já vinculados a outra conciliação bloqueiam a operação.

        - **`Transfers[]`** liga transferências entre contas pré-lançadas (sem título associado) à conciliação.
        Transferências já conciliadas são rejeitadas.


        O valor total das contas não pode ultrapassar o valor do lançamento de conciliação (comparação em módulo, para
        suportar estornos).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankStatementConciliationCreate'
        description: >-
          Identifique **exatamente uma** conciliação (`IDBankStatementConciliation` ou
          `IDAccountsPayableReceivableConciliation`) e **exatamente uma** das listas (`Accounts` para vincular títulos a
          pagar/receber, `Transfers` para vincular transferências). `IDBankAccount` é obrigatório.
      responses:
        '200':
          description: >-
            Conciliação efetuada. Retorna um array com 1 item — a conciliação resultante com os lançamentos vinculados e
            o status final.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BankStatementConciliationCreateResponse'
                maxItems: 1
        '400':
          description: >-
            Erros de validação (prefixo `[BadRequest]`):

            - `Lançamento de conciliação não selecionado`

            - `Informe apenas uma conciliação: bancária ou de adquirente`

            - `Conta bancária não selecionada`

            - `Contas a receber/pagar é obrigatório e deve ser um array com pelo menos um item`

            - `Transferência é obrigatória e deve ser um array com pelo menos um item`

            - `Accounts[<i>]. Conta a pagar/receber não informada ou inválida`

            - `Transfers[<i>]. Transferência não informada ou inválida`

            - `Empresa não encontrada`

            - `Lançamento de conciliação de adquirente não encontrado`

            - `Lançamento conciliação bancária não encontrado`

            - `Conta bancária não encontrada`

            - `Contas não encontradas: <ids>`

            - `O valor total dos lançamentos (<x>) é maior que o valor do título (<y>). Código do título: <id>.
            Lançamentos: <detalhes>`

            - `Divergência na data dos pagamentos realizados e a data do <lançamento de conciliação de
            adquirente|lançamento bancário>`

            - `Título <id> já esta conciliado na conciliação bancária código: <id>`

            - `O valor total das contas (<x>) é maior que o valor do <lançamento de conciliação de adquirente|lançamento
            bancário> (<y>). Não é possível conciliar.`

            - `Transferência(s) não encontradas ou já conciliadas: <ids>`

            - `Falha ao processar conciliação`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /accounts/bank-statement/transfer:
    post:
      operationId: bankStatementTransferPost
      tags:
        - Conciliação Bancária
      summary: Cria uma transferência entre contas bancárias
      description: >-
        Registra uma transferência de valor entre duas contas bancárias da empresa. Gera dois lançamentos no extrato
        interno (`AccountsPayableReceivableBankStatement`): um de débito (saída) na conta de origem e um de crédito
        (entrada) na conta de destino. Os dois lançamentos ficam ligados por uma referência única
        (`AccountsPayableReceivableBankStatementTransfer`), o que permite tratá-los como o mesmo movimento ao
        reconciliar.


        As descrições dos lançamentos são geradas automaticamente concatenando a descrição informada (ou o texto padrão
        `Transferência entre contas`) com o banco e o número da conta do outro lado da operação. A origem e o destino
        não podem ser a mesma conta.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankStatementTransferCreate'
        description: >-
          Dados da transferência entre contas. `IDBankFrom`, `IDBankTo` e `Value` são obrigatórios; `IDBankTo` precisa
          ser diferente de `IDBankFrom` e `Value` precisa ser maior que zero. A descrição informada é concatenada com o
          banco e a conta do outro lado nos dois lançamentos gerados.
      responses:
        '200':
          description: Transferência registrada. Retorna detalhes da transferência e os dois lançamentos criados.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankStatementTransferCreateResponse'
        '400':
          description: |-
            Erros de validação (prefixo `[BadRequest]`):
            - `Conta bancária de origem não informada`
            - `Conta bancária de destino não informada`
            - `A conta de origem e destino não podem ser a mesma`
            - `Valor deve ser maior que zero`
            - `Empresa não encontrada`
            - `Uma ou ambas as contas bancárias não foram encontradas ou não pertencem a esta empresa`
            - `Conta bancária de origem não encontrada`
            - `Conta bancária de destino não encontrada`
            - `Falha ao inserir transação de débito`
            - `Falha ao inserir transação de crédito`
            - `Falha ao processar transferência`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /accounts/bank-statement/transfer/{idbankstatement}:
    parameters:
      - name: idbankstatement
        in: path
        required: true
        description: >-
          Identificador de **um** dos dois lançamentos da transferência (débito ou crédito). O outro lado é resolvido
          automaticamente pelo sistema.
        schema:
          type: integer
          format: int32
    delete:
      operationId: bankStatementTransferDelete
      tags:
        - Conciliação Bancária
      summary: Exclui uma transferência entre contas bancárias
      description: >-
        Remove uma transferência interna criada por `POST /accounts/bank-statement/transfer`. O endpoint aceita o id de
        **qualquer um dos dois lados** da transferência (débito ou crédito); a partir dele, identifica o par completo
        (via `AccountsPayableReceivableBankStatementTransfer`), valida que ambos os lançamentos pertencem à empresa
        autenticada e remove **a referência da transferência e os dois lançamentos** do extrato.


        Falha quando o lançamento informado não é parte de uma transferência ou quando um dos lados pertence a outra
        empresa.
      responses:
        '200':
          description: Transferência excluída. Retorna a referência removida e os dados resumidos dos dois lançamentos apagados.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankStatementTransferDeleteResponse'
        '400':
          description: |-
            Erros de validação (prefixo `[BadRequest]`):
            - `Empresa não encontrada`
            - `Lançamento não é uma transferência ou não foi encontrado`
            - `Uma ou ambas as transações não pertencem a esta empresa`
            - `Falha ao excluir as transações`
            - `Falha ao excluir transferência`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /accounts/bank-statement/conciliation-rule:
    get:
      operationId: bankStatementConciliationRuleList
      tags:
        - Conciliação Bancária
      summary: Lista regras de conciliação automática
      description: >-
        Retorna as regras de conciliação automática cadastradas. Quando o OFX é importado, cada lançamento bancário é
        cruzado com essas regras para determinar se a conciliação acontece automaticamente, e contra qual tipo de
        movimento (título a pagar/receber ou transferência entre contas).


        Cada regra é restrita a uma **conta bancária** e a um **tipo de transação** (débito ou crédito). Tem um **tipo
        de regra**: `1` (contas a pagar/receber) — onde os campos opcionais funcionam como filtros adicionais (plano de
        contas, tipo documento, tipo pagamento, fornecedor, cliente) — ou `2` (transferência), que requer a **conta
        bancária de destino** (`IDBankAccountTo`).
      parameters:
        - name: IDBankAccount
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por conta bancária.
        - name: IDBankStatementConciliationRule
          in: query
          required: false
          schema:
            type: integer
          description: Retorna apenas a regra com o identificador informado.
        - name: Page
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: Página (5000 itens por página).
      responses:
        '200':
          description: Lista de regras (ou array vazio quando não há resultados).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BankStatementConciliationRuleListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: bankStatementConciliationRulePost
      tags:
        - Conciliação Bancária
      summary: Cria uma regra de conciliação automática
      description: >-
        Cadastra uma nova regra para conciliação automática. Conforme `IDTypeRule`:


        - **`IDTypeRule=1` (contas a pagar/receber)** — o campo `IDBankAccountTo` é descartado. Os campos
        `IDTypeAccountPayableReceivable`, `IDTypeDocument`, `IDTypePayment`, `IDSupplier` e `IDConsumer` são opcionais e
        funcionam como filtros adicionais para o casamento automático.

        - **`IDTypeRule=2` (transferência)** — o campo `IDBankAccountTo` é **obrigatório** e os filtros de título (plano
        de contas, tipo documento, tipo pagamento, fornecedor, cliente) são descartados.


        Não é permitido repetir uma descrição (`Description`) para a mesma conta bancária. A conta bancária de origem
        (`IDBankAccount`) e a de destino (`IDBankAccountTo`) não podem ser iguais.


        A resposta é a representação completa da regra recém-criada, no mesmo formato de `GET
        /accounts/bank-statement/conciliation-rule`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankStatementConciliationRuleCreate'
        description: >-
          Dados da regra de conciliação. `IDBankAccount` e `IDTypeRule` são obrigatórios. Para `IDTypeRule=1` (contas a
          pagar/receber), os campos de filtro são opcionais; para `IDTypeRule=2` (transferência), `IDBankAccountTo`
          passa a ser obrigatório e os filtros são ignorados.
      responses:
        '200':
          description: Regra criada. Retorna o item completo (mesmo formato do `GET`).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BankStatementConciliationRuleListItem'
                maxItems: 1
        '400':
          description: >-
            Erros de validação (prefixo `[BadRequest]`):

            - `Empresa não existe`

            - `Já existe uma regra com a mesma descrição para essa conta bancária`

            - `Conta bancária obrigatória` / `Conta bancária não existe`

            - `Conta bancária destino obrigatória em regra do tipo transferência` / `Conta bancária destino não existe`
            / `Conta bancária destino e origem não podem ser igual`

            - `Tipo regra obrigatório` / `Tipo regra não existe`

            - `Tipo pagamento não existe` / `Tipo documento não existe`

            - `Fornecedor não existe` / `Cliente não existe`

            - `Erro ao criar regra`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /accounts/bank-statement/conciliation-rule/{idbankstatementconciliationrule}:
    parameters:
      - name: idbankstatementconciliationrule
        in: path
        required: true
        description: Identificador da regra de conciliação.
        schema:
          type: integer
          format: int32
    put:
      operationId: bankStatementConciliationRulePut
      tags:
        - Conciliação Bancária
      summary: Atualiza uma regra de conciliação automática
      description: >-
        Atualiza uma regra de conciliação existente. As mesmas regras de criação valem: `IDTypeRule=1` descarta
        `IDBankAccountTo`; `IDTypeRule=2` exige `IDBankAccountTo` e descarta os filtros de título. Apenas os campos
        enviados no corpo são considerados; a unicidade da descrição por conta bancária também é validada.


        A resposta é a representação completa da regra atualizada, no mesmo formato de `GET
        /accounts/bank-statement/conciliation-rule`.
      requestBody:
        required: true
        description: Estrutura idêntica ao corpo de criação. Campos ausentes são tratados como `null` e descartados da atualização.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankStatementConciliationRuleCreate'
      responses:
        '200':
          description: Regra atualizada (mesmo formato do `GET`).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BankStatementConciliationRuleListItem'
                maxItems: 1
        '400':
          description: >-
            Erros de validação (prefixo `[BadRequest]`):

            - `Regra não existe`

            - `Já existe uma regra com a mesma descrição para essa conta bancária`

            - `Conta bancária obrigatória` / `Conta bancária não existe`

            - `Conta bancária destino obrigatória em regra do tipo transferência` / `Conta bancária destino não existe`
            / `Conta bancária destino e origem não podem ser igual`

            - `Tipo regra obrigatório` / `Tipo regra não existe`

            - `Tipo pagamento não existe` / `Tipo documento não existe`

            - `Fornecedor não existe` / `Cliente não existe`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: bankStatementConciliationRuleDelete
      tags:
        - Conciliação Bancária
      summary: Exclui uma regra de conciliação automática
      description: Remove a regra. Falha quando a regra não pertence a uma conta bancária da empresa autenticada.
      responses:
        '200':
          description: Exclusão bem-sucedida. O corpo é a string `"sucesso"`.
          content:
            application/json:
              schema:
                type: string
                enum:
                  - sucesso
        '400':
          description: 'Validação falhou (prefixo `[BadRequest]`). Mensagem: `Regra não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /carrier/modal:
    get:
      operationId: carrierModalList
      tags:
        - Modalidades de Transporte
      summary: Lista modalidades de transportadora
      description: >-
        Retorna as modalidades de transportadora cadastradas pela empresa, ordenadas por nome. Cada modalidade descreve
        a forma como uma transportadora opera (Rodoviário, Aéreo, Marítimo, Fluvial, Próprio, Motoboy, Drone, etc.) e
        fica disponível para seleção no cadastro do fornecedor que opera como transportadora.
      parameters:
        - name: IDCarrierModal
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por identificador único da modalidade.
      responses:
        '200':
          description: Lista de modalidades da empresa.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CarrierModalListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: carrierModalPost
      tags:
        - Modalidades de Transporte
      summary: Cadastra uma modalidade
      description: >-
        Cria uma modalidade de transportadora na empresa autenticada. O nome (`CarrierModal`) precisa ser único dentro
        da empresa — o sistema bloqueia o cadastro de outra modalidade com o mesmo nome. A resposta é a lista atualizada
        de modalidades.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierModalCreate'
        description: >-
          Cria uma nova modalidade de transportadora (ex.: `Rodoviário`, `Aéreo`, `Motoboy`). O nome precisa ser único
          dentro da empresa.
      responses:
        '200':
          description: Modalidade criada. Retorna a lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CarrierModalListItem'
        '400':
          description: |-
            Erros de validação (prefixo `[BadRequest]`):
            - `Já existe uma Modalidade com essa conta`
            - `Empresa não existe`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /carrier/modal/{idcarriermodal}:
    parameters:
      - name: idcarriermodal
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador da modalidade de transportadora.
    put:
      operationId: carrierModalPut
      tags:
        - Modalidades de Transporte
      summary: Atualiza uma modalidade
      description: >-
        Atualiza o nome da modalidade. Mesma regra de unicidade do `POST` — o novo nome não pode bater com outra
        modalidade já cadastrada na mesma empresa.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierModalCreate'
        description: Atualiza o nome da modalidade. Mesma estrutura do `POST` — o nome precisa continuar único na empresa.
      responses:
        '200':
          description: Modalidade atualizada. Retorna a lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CarrierModalListItem'
        '400':
          description: |-
            Erros de validação (prefixo `[BadRequest]`):
            - `Modalidade não existe`
            - `Já existe uma Modalidade com essa conta`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: carrierModalDelete
      tags:
        - Modalidades de Transporte
      summary: Exclui uma modalidade
      description: >-
        **Exclusão física** — a modalidade é apagada do banco. O sistema bloqueia a exclusão em duas situações: (1)
        **existe alguma transportadora** (fornecedor com `IDCarrierModal` apontando para esta) — é preciso
        remover/trocar a modalidade no cadastro da transportadora; (2) **existe configuração no de/para de
        transportadora** em `HubCarrier` apontando para esta.


        A resposta em sucesso é a lista atualizada de modalidades.
      responses:
        '200':
          description: Modalidade excluída. Retorna a lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CarrierModalListItem'
        '400':
          description: |-
            Bloqueios (prefixo `[BadRequest]`):
            - `Modalidade não existe`
            - `Há transportadora com essa modalidade, remover no cadastro da transportadora`
            - `Modalidade esta configurada no de/para de transportadora`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /brand:
    get:
      operationId: brandList
      tags:
        - Marcas
      summary: Lista marcas
      description: >-
        Retorna as marcas ativas da empresa. Aceita uma busca textual por `Search` que casa contra o id e o nome. Limite
        máximo de 5000 resultados.
      parameters:
        - name: Search
          in: query
          required: false
          schema:
            type: string
          description: Busca textual contra identificador `IDBrand` e nome `Name`. Cada espaço vira um curinga `%` interno.
      responses:
        '200':
          description: Lista de marcas.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BrandListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: brandPost
      tags:
        - Marcas
      summary: Cadastra uma marca
      description: >-
        Cria uma marca para a empresa. Os campos `Description`, `Keywords` e `Title` herdam o valor de `Name` quando
        ausentes ou vazios. `IsActive` assume `1` por padrão, `MenuHome` assume `0`, e `Score` fica nulo.


        A resposta é o detalhe da marca recém-criada (mesmo formato do `GET /brand/{idbrand}`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrandCreate'
        description: >-
          Dados da marca a cadastrar. Apenas `Name` é obrigatório; `Description`, `Keywords` e `Title` herdam o valor de
          `Name` quando ausentes ou vazios, `IsActive` assume 1 e `MenuHome` assume 0.
      responses:
        '200':
          description: Marca criada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Brand'
                maxItems: 1
        '400':
          description: 'Empresa não localizada. Mensagem: `[BadRequest] - Company não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /brand/{idbrand}:
    parameters:
      - name: idbrand
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador da marca.
    get:
      operationId: brandGet
      tags:
        - Marcas
      summary: Detalha uma marca
      description: Retorna o cadastro completo de uma marca.
      responses:
        '200':
          description: Marca encontrada (array com 1 item) ou array vazio quando o id não pertence à empresa.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Brand'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    put:
      operationId: brandPut
      tags:
        - Marcas
      summary: Atualiza uma marca
      description: >-
        Atualiza a marca de forma parcial — apenas os campos enviados são alterados. A resposta é o detalhe da marca
        atualizada.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrandUpdate'
        description: >-
          Campos da marca a atualizar. Todos os campos são opcionais — apenas os enviados são aplicados; os demais
          permanecem com o valor atual.
      responses:
        '200':
          description: Marca atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Brand'
                maxItems: 1
        '400':
          description: 'Marca não encontrada. Mensagem: `[BadRequest] - Brand não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: brandDelete
      tags:
        - Marcas
      summary: Exclui (inativa) uma marca
      description: >-
        Inativa a marca (`Status = 0`). Não exclui fisicamente o registro. A exclusão é bloqueada quando há produtos
        ativos vinculados à marca.
      responses:
        '200':
          description: Marca inativada. Devolve a string `"sucesso"`.
          content:
            application/json:
              schema:
                type: string
                enum:
                  - sucesso
        '400':
          description: >-
            Regras impeditivas (prefixo `[BadRequest]`): `marca não existe`, `Marca possui produto ativos. Alterar a
            marca no cadastro do item antes de excluir a marca`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/movement:
    get:
      summary: Lista movimentações de estoque
      description: >-
        Substituir o parágrafo de derivação do `TypeMovement` por: "O campo `TypeMovement` é derivado das vinculações da
        movimentação: `Transferência endereço` quando há movimentação de origem (`IDOriginIDSkuMovement > 0`); `Ajuste
        saldo estoque` quando há ajuste de saldo (`IDStockKeepingUnitInventory`); `Inventário` quando há apuração de
        inventário (`IDStockKeepingUnitInventorySummary`); `Recebimento` quando há recebimento (`IDPurchase`); quando há
        pedido (`IDOrder`), `Transferência CD` se o tipo do pedido é de transferência entre centros de distribuição
        (`IsTransfer=1`) ou `Venda` caso contrário; `Produção` quando há produção (`IDStockKeepingUnitProduction`). O
        campo `IsTransfer` (flag do tipo do pedido) passou a ser retornado. `TypeSkuMovement` é `Saída` para
        `IDTypeMovement=1` e `Entrada` para `IDTypeMovement=0`."
      tags:
        - Movimentação de Estoque
      parameters:
        - name: Type
          in: query
          required: false
          schema:
            type: string
            enum:
              - Kardex
              - kardex
              - KardexLocation
              - KardexBatch
              - SkuInbound
              - SkuOutbound
              - SkuFiscalConciliation
          description: >-
            Modo de operacao. Quando ausente, retorna a listagem padrao. Valores aceitos: `Kardex` (ou `kardex`),
            `KardexLocation`, `KardexBatch`, `SkuInbound`, `SkuOutbound`, `SkuFiscalConciliation`. O shape da resposta
            muda conforme o `Type`.
        - name: Page
          in: query
          required: false
          schema:
            type: integer
          description: >-
            Numero da pagina (offset = `Page * 1000` na listagem padrao, `Page * 8000` em
            `Kardex`/`KardexLocation`/`KardexBatch`, `Page * 1000` em `SkuInbound`/`SkuOutbound`).
        - name: OrderBy
          in: query
          required: false
          schema:
            type: string
            enum:
              - ASC
              - DESC
          description: >-
            Ordenação do `RecordTimestamp` no Kardex. `ASC` (mais antigos primeiro) ou `DESC` (mais recentes primeiro).
            Padrão `ASC`.
        - name: IDSku
          in: query
          required: false
          schema:
            type: string
          description: >-
            SKU. Aceita um ou vários códigos separados por vírgula ou espaço (ex.: `33895,398` ou `33895 398`).
            Obrigatório quando `Type` é `Kardex`, `KardexLocation`, `SkuInbound`, `SkuOutbound` ou
            `SkuFiscalConciliation`.
        - name: IDStockKeepingUnitWarehouse
          in: query
          required: false
          schema:
            type: integer
          description: Armazém da movimentação. Obrigatório quando `Type=Kardex` (ou `kardex`).
        - name: IDStockKeepingUnitLocation
          in: query
          required: false
          schema:
            type: integer
          description: Endereço físico. Obrigatório quando `Type=KardexLocation`.
        - name: IDCompany
          in: query
          required: false
          schema:
            type: integer
          description: Conta a filtrar (em multi-empresa). Quando ausente, usa a conta autenticada.
        - name: DateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Início do intervalo de data da movimentação (`YYYY-MM-DD`).
        - name: DateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: >-
            Fim do intervalo de data da movimentação (`YYYY-MM-DD`). O sistema acrescenta automaticamente `23:59:59` ao
            final.
        - name: SkuName
          in: query
          required: false
          schema:
            type: string
          description: Nome do produto (busca parcial — `LIKE`).
        - name: BarCode
          in: query
          required: false
          schema:
            type: string
          description: Código de barras do SKU.
        - name: IDBrand
          in: query
          required: false
          schema:
            type: integer
          description: Marca do produto.
        - name: SupplierCode
          in: query
          required: false
          schema:
            type: string
          description: Código do SKU usado pelo fornecedor (busca parcial — `LIKE`).
        - name: IDSupplier
          in: query
          required: false
          schema:
            type: integer
          description: Fornecedor (quando origem é recebimento).
        - name: Package
          in: query
          required: false
          schema:
            type: string
          description: Embalagem cadastrada no SKU.
        - name: IDSkuCompany
          in: query
          required: false
          schema:
            type: string
          description: Código de referência do SKU (busca parcial — `LIKE`).
        - name: IDSkuHub
          in: query
          required: false
          schema:
            type: string
          description: Código do SKU no canal de venda (`IDSkuHub`).
        - name: IDSkuMovement
          in: query
          required: false
          schema:
            type: integer
          description: Identificador específico de uma movimentação.
        - name: BalanceChange
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Filtra apenas movimentações que alteram o saldo (`1`) ou que não alteram (`0`).
        - name: IDTypeMovement
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Sentido da movimentação. `0` = entrada, `1` = saída.
        - name: IDTypeFulfillmentNonconformity
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 4
              - 5
              - 6
          description: Tipo de não conformidade no fulfillment.
        - name: ConsumerNameCorporateName
          in: query
          required: false
          schema:
            type: string
          description: Nome ou razão social do cliente do pedido (busca parcial).
        - name: ConsumerCpfCnpj
          in: query
          required: false
          schema:
            type: string
          description: CPF/CNPJ do cliente (busca parcial).
        - name: ConsumerEmail
          in: query
          required: false
          schema:
            type: string
          description: E-mail do cliente (busca parcial).
        - name: Order
          in: query
          required: false
          schema:
            type: string
          description: Número/identificador do pedido (busca exata).
        - name: OrderFrom
          in: query
          required: false
          schema:
            type: string
          description: Origem do pedido (`OrderFrom`).
        - name: IDOrder
          in: query
          required: false
          schema:
            type: integer
          description: Pedido específico.
        - name: IDConsumer
          in: query
          required: false
          schema:
            type: integer
          description: Cliente específico.
        - name: NfeNumber
          in: query
          required: false
          schema:
            type: integer
          description: Número da NF-e vinculada.
        - name: IDSalesChannel
          in: query
          required: false
          schema:
            type: integer
          description: Canal de venda (`IDSalesChannel`).
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
          description: Integração de venda (`CompanyIntegration`).
        - name: IDStatusOrder
          in: query
          required: false
          schema:
            type: integer
          description: Status do pedido.
        - name: IDStatusInvoice
          in: query
          required: false
          schema:
            type: integer
          description: Status da NF-e.
        - name: IDCarrier
          in: query
          required: false
          schema:
            type: integer
          description: Transportadora do pedido.
        - name: IDOrderType
          in: query
          required: false
          schema:
            type: integer
          description: Tipo do pedido.
        - name: ShippingState
          in: query
          required: false
          schema:
            type: string
          description: UF de entrega do pedido.
        - name: IDCompanyInvoice
          in: query
          required: false
          schema:
            type: integer
          description: Empresa faturadora do pedido.
        - name: InvoiceDateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Início do intervalo da data de emissão da NF-e.
        - name: InvoiceDateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Fim do intervalo da data de emissão da NF-e (acrescenta `23:59:59`).
        - name: ShippingDateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Início do intervalo da data de envio.
        - name: ShippingDateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Fim do intervalo da data de envio.
        - name: ValueOrderFrom
          in: query
          required: false
          schema:
            type: number
          description: Valor mínimo do pedido.
        - name: ValueOrderTo
          in: query
          required: false
          schema:
            type: number
          description: Valor máximo do pedido.
        - name: OrderDateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Início do intervalo da data de criação do pedido.
        - name: OrderDateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Fim do intervalo da data de criação do pedido (acrescenta `23:59:59`).
        - name: IncludeValueDashboard
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Filtra por tipo de pedido marcado como `Incluir valor dashboard`.
        - name: BatchComments
          in: query
          required: false
          schema:
            type: string
          description: Descrição/Comentários do lote (busca exata).
        - name: SinceDateLastRecordModification
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: >-
            Retorna apenas movimentações com `DateLastRecordModification >=` a data informada (`YYYY-MM-DD HH:MM:SS`).
            Útil para sincronização incremental.
        - name: IDBatch
          in: query
          required: false
          schema:
            type: integer
          description: >-
            Lote (`IDBatch`). Obrigatorio quando `Type=KardexBatch`. Nos demais modos, quando informado, restringe a
            movimentacao ao lote.
      responses:
        '200':
          description: Lista de movimentações conforme o `Type` requisitado.
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/SkuMovementListItem'
                  - type: array
                    items:
                      $ref: '#/components/schemas/SkuMovementKardexItem'
                  - type: array
                    items:
                      $ref: '#/components/schemas/SkuMovementKardexLocationItem'
                  - type: array
                    items:
                      $ref: '#/components/schemas/SkuMovementInboundItem'
                  - type: array
                    items:
                      $ref: '#/components/schemas/SkuMovementOutboundItem'
                  - type: array
                    items:
                      $ref: '#/components/schemas/SkuMovementFiscalConciliationItem'
                  - type: array
                    items:
                      $ref: '#/components/schemas/SkuMovementKardexBatchItem'
        '400':
          description: >-
            Falha de validação. Possíveis mensagens:

            - `[BadRequest] - Precisa informar o armazem e sku` — `Type=Kardex` sem
            `IDSku`/`IDStockKeepingUnitWarehouse`.

            - `[BadRequest] - Precisa informar o endereço e sku` — `Type=KardexLocation` sem
            `IDSku`/`IDStockKeepingUnitLocation`.

            - `[BadRequest] - Precisa informar o lote` — `Type=KardexBatch` sem `IDBatch`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
      operationId: skuMovementList
  /sku/movement/transfer:
    post:
      summary: Transfere quantidade entre armazéns/endereços
      description: >-
        Move quantidade de um SKU entre dois armazéns ou dois endereços/lotes, gerando **duas movimentações vinculadas**
        (saída na origem, entrada no destino). O custo unitário usado em ambas é o custo médio do armazém de origem — ou
        o valor de `CostSet` quando a parametrização `UseCostFromCostSet` está ativa.


        Origem e destino precisam estar no **mesmo Centro de Distribuição** (`IDStockKeepingUnitDistributionCenter`). O
        SKU precisa ser do tipo Produto/Variação, Matéria-prima ou Insumo.


        **Modos de transferência:**

        - **Entre armazéns** — envie `IDStockKeepingUnitWarehouseFrom` + `IDStockKeepingUnitWarehouseTo`. O sistema
        consome lotes na ordem FIFO (mais antigo primeiro) até completar `Quantity`. Para SKU sem rastreabilidade
        (`Batch = 0`) usa o lote padrão.

        - **Entre lotes/endereços** — envie `IDBatchFrom` + (`IDBatchTo` **ou** `IDStockKeepingUnitLocationTo`). Quando
        vier só `IDStockKeepingUnitLocationTo`, o sistema procura um lote compatível no destino (mesma
        validade/fabricação/comentário) e o reutiliza; se não existir, cria um novo lote. Com a parametrização
        `KeepUniqueBatchForFiscalConciliation` ativa, **sempre cria um novo lote no destino**.


        **Validações:**

        - Se a quantidade total do lote origem for menor que `Quantity`, devolve `[BadRequest] - Quantidade total
        insuficiente para transferencia`. Pode ser contornado com `IgnoreBalance=1` (query) ou ativando
        `AllowNegativeBalanceTransfer`.

        - Em transferência entre endereços com SKU rastreável (`Batch = 1`), se o endereço destino já tem o mesmo SKU em
        lote divergente (validade/fabricação/comentário diferentes) e a parametrização
        `AllowSameItemDifferentBatchSameLocation` está inativa, devolve `[BadRequest] - Item possui lotes divergentes no
        endereço de destino`.


        **Efeitos colaterais:**

        - Atualiza `StockKeepingUnitBalance` (saldo agregado) do SKU no armazém de destino.

        - Reprocessa pedidos no armazém de destino com status "Falta produto" (e equivalentes — `IDStatusOrder IN (11,
        12, 24)`), limpando `QuantityNonconformity` à medida que a quantidade transferida cobre as faltas, e devolvendo
        o pedido a `IDStatusOrder = 1` (Fechado) quando todos os itens voltam a ter saldo. Cada alteração gera evento de
        pedido (`IDEvent = 35`).

        - Publica a notificação `SkuBalanceTransfer` para o webhook da empresa.


        **Resposta:** por padrão devolve as duas movimentações criadas (`SkuMovementTransferResponseItem`). Quando
        `BatchResponse=1` é enviado na query, devolve a lista completa de lotes ativos do SKU
        (`SkuMovementTransferBatchResponseItem`) — útil para o frontend recarregar o painel de saldos sem nova chamada.
      tags:
        - Movimentação de Estoque
      parameters:
        - name: BatchResponse
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: >-
            Quando `1`, a resposta troca de array de movimentações para a lista completa de lotes ativos do SKU. Padrão
            `0`.
        - name: IgnoreBalance
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: >-
            Quando `1`, ignora a validação de saldo na transferência por lote (mesma semântica de
            `AllowNegativeBalanceTransfer`, mas pontual). Vale apenas no fluxo `IDBatchFrom + (IDBatchTo |
            IDStockKeepingUnitLocationTo)`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuMovementTransferBody'
        description: >-
          Transferência de estoque de um SKU entre dois depósitos. Informe `IDSku`, `Quantity`,
          `IDStockKeepingUnitWarehouseFrom` (origem), `IDStockKeepingUnitWarehouseTo` (destino) e — quando o SKU é
          controlado por lote — `IDBatchFrom` e `IDBatchTo`. `IDStockKeepingUnitLocationTo` direciona o endereço de
          destino.
      responses:
        '200':
          description: >-
            Transferência criada com sucesso. Quando `BatchResponse=1`, retorna a lista de lotes ativos do SKU; caso
            contrário, retorna as duas movimentações criadas.
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/SkuMovementTransferResponseItem'
                  - type: array
                    items:
                      $ref: '#/components/schemas/SkuMovementTransferBatchResponseItem'
        '400':
          description: >-
            Falha de validação. Possíveis mensagens:

            - `[BadRequest] - Quantidade precisa ser maior que zero` — `Quantity` ausente ou zero.

            - `[BadRequest] - SKU não existe` — `IDSku` inválido ou não pertence à conta.

            - `[BadRequest] - Item não é do tipo SKU, materia prima ou insumo` — `IDTypeSku` fora de `(3, 6, 7)`.

            - `[BadRequest] - Lote origem não existe` — `IDBatchFrom` inválido.

            - `[BadRequest] - Lote destino não existe` — `IDBatchTo` inválido.

            - `[BadRequest] - Endereço destino não existe` — `IDStockKeepingUnitLocationTo` inválido.

            - `[BadRequest] - Armazém origem não existe` / `[BadRequest] - Armazém destino não existe` — armazém
            inválido ou de outra empresa.

            - `[BadRequest] - Centro de distribuição de origem diferente do destino` — armazéns/endereços em CDs
            diferentes.

            - `[BadRequest] - Item possui lotes divergentes no endereço de destino e não pode ser transferido` —
            bloqueio quando `AllowSameItemDifferentBatchSameLocation` está inativo.

            - `[BadRequest] - Quantidade total insuficiente para transferencia: Origem: X Transferência: Y` — saldo
            insuficiente (libere com `AllowNegativeBalanceTransfer` ou `IgnoreBalance=1`).

            - `[BadRequest] - Quantidade insuficiente para transferência` — não há lote disponível para consumir no
            armazém de origem.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
      operationId: skuMovementTransferPost
  /sku/{idsku}/cost/recalculate:
    post:
      summary: Recalcula o custo médio do SKU (assíncrono)
      description: >-
        Despacha o **reprocessamento do histórico de movimentações** do SKU para refazer o cálculo de custo médio a
        partir do zero. A chamada é assíncrona — a API devolve imediatamente e o reprocessamento roda em segundo plano.
        Use quando o custo médio na tela de Saldo / Lotes ficar inconsistente com o que o Kardex calcularia (importação
        de movimentações antigas, correção retroativa do custo de um recebimento, estorno de compra etc.).


        Atenção: a operação é **irreversível** e pode demorar minutos em SKUs com muito histórico.
      tags:
        - Recálculo de Custo
      parameters:
        - name: idsku
          in: path
          required: true
          schema:
            type: integer
          description: SKU a ter o custo recalculado.
      responses:
        '200':
          description: Recálculo aceito e despachado para processamento em segundo plano.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkuCostRecalculateAcceptedResponse'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
      operationId: skuCostRecalculatePost
  /supplier:
    get:
      operationId: supplierList
      tags:
        - Cadastro de Fornecedores
      summary: Lista fornecedores e transportadoras
      description: >-
        Retorna o catálogo de fornecedores (e transportadoras — compartilham o mesmo cadastro) da empresa autenticada.
        Apenas cadastros ativos (`SupplierStatus=1`) entram na resposta. Aceita filtros por categoria, tipo de
        fornecedor, CPF/CNPJ, sinal de leilão de frete e nome; aceita ainda uma busca textual genérica (`Search`) que
        cruza nome, e-mail, CPF/CNPJ e id.


        Quando o usuário tem categorias de fornecedor vinculadas em **Configurações → Usuários** **e** a parametrização
        **Permitir visualizar registros apenas fornecedores vinculados ao usuário** está ativada, o resultado é
        automaticamente restrito a essas categorias. Paginação por `Page` com 2000 itens por página.
      parameters:
        - name: Page
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: Página (2000 itens por página).
        - name: Search
          in: query
          required: false
          schema:
            type: string
          description: >-
            Busca textual genérica. O texto é separado em letras (nome/e-mail) e dígitos (CPF/CNPJ/id) e cruzado contra
            `SupplierNameCorporateName`, `SupplierEmail`, `SupplierCpfCnpj` e `IDSupplier`.
        - name: SupplierNameCorporateName
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo nome ou razão social (LIKE).
        - name: SupplierCpfCnpj
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo CPF ou CNPJ (LIKE, somente dígitos).
        - name: IDSupplierCategory
          in: query
          required: false
          schema:
            type: string
          description: Filtra por uma ou mais categorias de fornecedor. Lista separada por vírgula.
        - name: IDTypeSupplier
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo tipo de fornecedor (vinculado à categoria).
        - name: CarrierAuction
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Filtra transportadoras que participam (1) ou não (0) do leilão de frete.
      responses:
        '200':
          description: Lista de fornecedores ativos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SupplierListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: supplierPost
      tags:
        - Cadastro de Fornecedores
      summary: Cadastra um fornecedor
      description: >-
        Cria um novo fornecedor (ou transportadora — depende da categoria informada). Quando `SupplierCpfCnpj` é
        informado, o sistema tenta consultar `publica.cnpj.ws/cnpj/<valor>` com timeout de 5 s. Se a consulta retornar
        com sucesso (típico para CNPJ válido), os campos de endereço, telefone, e-mail, razão social, nome fantasia,
        inscrição estadual e data de início de atividade são **sobrescritos** com os dados da Receita — qualquer valor
        enviado no corpo para esses campos é ignorado. Em caso de falha (CPF, CNPJ inexistente, timeout,
        indisponibilidade do serviço externo), o sistema cai de volta para os valores do corpo.


        Quando a parametrização **Bloquear cadastro duplicado de fornecedor** (`BlockDuplicateSupplier`, grupo
        *Fornecedor*) está ativada, o sistema bloqueia o cadastro se já existir outro fornecedor ativo com o mesmo
        CPF/CNPJ.


        A resposta é o detalhe completo do fornecedor recém-criado (mesmo formato de `GET /supplier/{idsupplier}`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SupplierCreate'
        description: >-
          Cadastro de um novo fornecedor (produto, transportadora, serviço, etc.). Quando `SupplierCpfCnpj` é informado
          e a parametrização **Não Permitir Cadastros Duplicados Para Fornecedor** está ativa, o sistema rejeita
          CPF/CNPJ já cadastrado e ativo na empresa. Para CNPJ, os campos de identificação (`SupplierNameCorporateName`,
          `SupplierTradeName`, `SupplierStateInscription`), contato (`SupplierTelephone`, `SupplierEmail`), endereço
          (`ShippingStreet`, `ShippingNumber`, `ShippingComplement`, `ShippingNeighborhood`, `ShippingCity`,
          `ShippingState`, `ShippingPostalCode`) e `SupplierBirthDate` são sobrescritos com os dados retornados pela
          Receita (consulta a `publica.cnpj.ws`); se a consulta falhar, valem os valores enviados no corpo.
      responses:
        '200':
          description: Fornecedor criado. Retorna o cadastro completo.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SupplierDetail'
                maxItems: 1
        '400':
          description: |-
            Erros de validação (prefixo `[BadRequest]`):
            - `Já existe um fornecedor com esse CPF/CNPJ` (quando `BlockDuplicateSupplier=1`)
            - `Categoria fornecedor não existe`
            - `Empresa não existe`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /supplier/{idsupplier}:
    parameters:
      - name: idsupplier
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do fornecedor (ou transportadora — compartilham o mesmo cadastro).
    get:
      operationId: supplierGet
      tags:
        - Cadastro de Fornecedores
      summary: Detalha um fornecedor ou transportadora
      description: >-
        Retorna o cadastro completo de um fornecedor. O mesmo cadastro também é usado para transportadoras — os campos
        com prefixo `Carrier*` ficam preenchidos apenas quando o fornecedor opera como transportadora.


        A resposta inclui descrições resolvidas dos relacionamentos (categoria, tipo de fornecedor, integração, banco,
        estado civil, plano de contas), uma lista de contatos, faixas de SRO dos Correios (transportadoras), uploads de
        tabela de frete (transportadoras), centros de custo padrão para os títulos gerados e um campo textual com o
        status do último upload de tabela de frete.


        Não retorna erro quando o id não existe ou não pertence à empresa — a resposta é `200 []`.
      responses:
        '200':
          description: Fornecedor encontrado (array com 1 item) ou array vazio quando o id não pertence à empresa autenticada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SupplierDetail'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    put:
      operationId: supplierPut
      tags:
        - Cadastro de Fornecedores
      summary: Atualiza um fornecedor
      description: >-
        Atualiza parcialmente o cadastro do fornecedor — apenas os campos enviados no corpo são alterados. As validações
        disparam quando os campos correspondentes vêm preenchidos:


        - Se `SupplierCpfCnpj` mudar **e** a parametrização **Bloquear cadastro duplicado de fornecedor** estiver ativa,
        o sistema bloqueia o salvamento quando já existe outro fornecedor ativo com o mesmo documento.

        - Se `IDSupplierCategory` for informado, a categoria precisa pertencer à empresa autenticada.

        - Se `IDTypeAccountPayableReceivable` for informado, o plano de contas precisa existir na empresa.

        - Se `IDCompanyLabel` mudar, o template de etiqueta precisa pertencer à empresa autenticada ou à empresa-padrão
        de etiquetas (id 54) e ser do tipo etiqueta de transportadora.

        - Se `CarrierAuction=1` e o fornecedor ainda não tinha `CarrierQuotationExternalId`, o sistema atribui um id
        sequencial dentro da empresa.


        Sempre que o cadastro muda para/de transportadora, a lista de transportadoras de leilão de frete é regravado.


        A resposta é o detalhe completo do fornecedor atualizado.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SupplierUpdate'
        description: >-
          Atualização parcial: envie apenas os campos que precisa alterar — o sistema só atualiza chaves presentes no
          corpo. Quando `SupplierCpfCnpj` muda e a parametrização **Não Permitir Cadastros Duplicados Para Fornecedor**
          está ativa, valida duplicidade contra outros fornecedores ativos da empresa. Quando `CarrierAuction` passa
          para 1 e o fornecedor ainda não tem `CarrierQuotationExternalId`, o sistema atribui automaticamente o próximo
          identificador sequencial e, ao mudar o tipo do fornecedor para/de transportadora, atualiza a lista de
          transportadoras de leilão da empresa. `IDTypeAccountPayableReceivable` e `IDCompanyLabel` são validados contra
          os respectivos cadastros da empresa.
      responses:
        '200':
          description: Fornecedor atualizado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SupplierDetail'
                maxItems: 1
        '400':
          description: |-
            Erros de validação (prefixo `[BadRequest]`):
            - `Fornecedor não existe`
            - `Categoria fornecedor não existe`
            - `Já existe um fornecedor com esse CPF/CNPJ`
            - `Plano de contas não existe`
            - `Etiqueta não existe`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: supplierDelete
      tags:
        - Cadastro de Fornecedores
      summary: Exclui (inativa) um fornecedor
      description: >-
        Marca o fornecedor como inativo e limpa os vínculos com integração (`IDCompanyIntegration`) e leilão de frete
        (`CarrierAuction`). Não há exclusão física do registro: o `SupplierStatus` passa para **0** quando o fornecedor
        nunca teve título a pagar/receber, ou para **2** quando já existe pelo menos um título vinculado — isso preserva
        o histórico financeiro mas remove o fornecedor das listas ativas.


        A resposta é a lista atualizada de fornecedores (mesmo formato de `GET /supplier`).
      responses:
        '200':
          description: Fornecedor inativado. Retorna a lista de fornecedores ativos atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SupplierListItem'
        '400':
          description: 'Fornecedor não localizado. Mensagem: `[BadRequest] - Supplier não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /supplier/{idsupplier}/contact:
    parameters:
      - name: idsupplier
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do fornecedor.
    post:
      operationId: supplierContactPost
      tags:
        - Cadastro de Fornecedores
      summary: Adiciona um contato ao fornecedor
      description: >-
        Cria um contato (pessoa física) vinculado ao fornecedor. A resposta é o detalhe completo do fornecedor
        atualizado, com a nova entrada já visível em `Contacts[]`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SupplierContactCreate'
        description: Dados do contato a ser adicionado ao fornecedor.
      responses:
        '200':
          description: Contato criado. Retorna o detalhe atualizado do fornecedor.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SupplierDetail'
                maxItems: 1
        '400':
          description: 'Fornecedor não localizado. Mensagem: `[BadRequest] - Fornecedor não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /supplier/{idsupplier}/contact/{idsupplierscontact}:
    parameters:
      - name: idsupplier
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do fornecedor.
      - name: idsupplierscontact
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do contato.
    put:
      operationId: supplierContactPut
      tags:
        - Cadastro de Fornecedores
      summary: Atualiza um contato do fornecedor
      description: >-
        Atualiza parcialmente um contato — apenas os campos enviados no corpo são alterados. A resposta é o detalhe
        completo do fornecedor atualizado.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SupplierContactUpdate'
        description: 'Atualização parcial dos campos do contato: somente as chaves presentes no corpo são alteradas.'
      responses:
        '200':
          description: Contato atualizado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SupplierDetail'
                maxItems: 1
        '400':
          description: 'Fornecedor ou contato não encontrados. Mensagem: `[BadRequest] - Fornecedor não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: supplierContactDelete
      tags:
        - Cadastro de Fornecedores
      summary: Remove um contato do fornecedor
      description: >-
        Apaga fisicamente o contato. A resposta é o detalhe completo do fornecedor atualizado, já sem o contato
        removido.
      responses:
        '200':
          description: Contato removido. Retorna o detalhe atualizado do fornecedor.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SupplierDetail'
                maxItems: 1
        '400':
          description: 'Fornecedor não localizado. Mensagem: `[BadRequest] - Fornecedor não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /supplier/{idsupplier}/cost-center:
    parameters:
      - name: idsupplier
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do fornecedor.
    post:
      operationId: supplierCostCenterPost
      tags:
        - Cadastro de Fornecedores
      summary: Define o rateio padrão de centros de custo do fornecedor
      description: >-
        Substitui (apaga e regrava) o rateio padrão de centros de custo aplicado nos títulos gerados a partir deste
        fornecedor. O corpo é um **array** de pares `IDTypeCostCenter` + `ValueRatio`, onde a soma de `ValueRatio`
        precisa fechar em **1** (100%). Quando o array é vazio (`[]`), o rateio padrão é removido. Todos os centros de
        custo precisam existir na empresa.


        O comportamento é atômico: o sistema valida primeiro a soma e os centros, depois apaga o rateio anterior e
        insere o novo de uma vez. A resposta é a string `"sucesso"` quando o array é vazio, ou o detalhe completo do
        fornecedor atualizado quando há centros a gravar.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/SupplierCostCenterRatio'
        description: >-
          Array com o rateio completo de centros de custo do fornecedor. Cada item tem `IDTypeCostCenter` (centro de
          custo da empresa) e `ValueRatio` (proporção decimal entre 0 e 1). A soma de `ValueRatio` precisa fechar em 1
          (100%). O sistema **substitui** o rateio existente: apaga todos os vínculos atuais e insere os enviados.
          Enviar array vazio remove todo o rateio.
      responses:
        '200':
          description: >-
            Rateio aplicado. Retorna o detalhe atualizado do fornecedor, ou a string `"sucesso"` quando o rateio foi
            removido (array vazio).
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/SupplierDetail'
                  - type: string
                    enum:
                      - sucesso
        '400':
          description: |-
            Erros de validação (prefixo `[BadRequest]`):
            - `Fornecedor não existe`
            - `Rateio precisa somar 100%`
            - `Precisa enviar ao menos um centro de custo`
            - `Centro de custo(s) não localizado(s): <ids>`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /supplier/{idsupplier}/logo:
    parameters:
      - name: idsupplier
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do fornecedor.
    post:
      operationId: supplierLogoPost
      tags:
        - Cadastro de Fornecedores
      summary: Sobe ou troca o logotipo do fornecedor
      description: >-
        Aceita duas formas de envio do logotipo:


        - **Upload multipart** (`multipart/form-data` com campo `file`) — sobe o arquivo direto do cliente.

        - **URL externa** (`application/json` com `{ "Url": "..." }`) — o sistema baixa a imagem da URL informada e
        grava no S3.


        Nos dois casos a imagem é salva no bucket público do idworks
        (`https://public.idworks.com.br/Image/Suppliers/...`) com um nome único, e o campo `SupplierLogoUrl` do
        fornecedor é atualizada. A resposta é um corpo vazio com status HTTP — `200` em sucesso, `404` se o fornecedor
        não existe, `400` se a URL informada não retorna a imagem.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: Arquivo de imagem (PNG/JPG).
          application/json:
            schema:
              type: object
              required:
                - Url
              properties:
                Url:
                  type: string
                  format: uri
                  description: URL pública de onde o sistema deve baixar a imagem.
        description: >-
          Envio do logotipo do fornecedor. Aceita duas formas: (1) `multipart/form-data` com o campo `file` contendo o
          arquivo de imagem; ou (2) JSON com `{ "Url": "..." }` para que o sistema baixe a imagem da URL informada. O
          arquivo é armazenado em `https://public.idworks.com.br/Image/Suppliers/` e o `SupplierLogoUrl` do fornecedor é
          atualizado.
      responses:
        '200':
          description: Logotipo aplicado (corpo vazio).
          content: {}
        '400':
          description: 'Falha ao baixar imagem da URL informada. Mensagem: `[BadRequest] - erro ao baixar imagem`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '404':
          description: Fornecedor não encontrado (corpo vazio).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /supplier/category:
    get:
      operationId: supplierCategoryList
      tags:
        - Categorias de Fornecedor
      summary: Lista categorias de fornecedor
      description: >-
        Retorna as categorias ativas da empresa, ordenadas pela descrição. Cada item já vem com o tipo de fornecedor
        resolvido (`TypeSupplier`). Aceita filtro opcional por `IDSupplierCategory` para retornar uma única categoria.
        Quando a empresa autenticada é a `all` (multi-conta), retorna as categorias de todas as empresas vinculadas.
      parameters:
        - name: IDSupplierCategory
          in: query
          required: false
          schema:
            type: integer
            format: int32
          description: Filtra por identificador de categoria. Quando omitido, devolve todas as categorias ativas da empresa.
      responses:
        '200':
          description: Lista de categorias.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SupplierCategoryListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: supplierCategoryPost
      tags:
        - Categorias de Fornecedor
      summary: Cadastra uma categoria de fornecedor
      description: >-
        Cria uma categoria para a empresa autenticada. A resposta repete o formato da listagem — array com 1 item — já
        com o tipo de fornecedor resolvido.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SupplierCategoryCreate'
        description: >-
          Dados da categoria a ser cadastrada. `CategoryDescription` é o nome exibido na lista de categorias;
          `IDTypeSupplier` define o tipo (Produto, Transportadora, Serviço, etc.).
      responses:
        '200':
          description: Categoria criada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SupplierCategoryListItem'
                maxItems: 1
        '400':
          description: 'Empresa não localizada. Mensagem: `[BadRequest] - Empresa não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /supplier/category/{idsuppliercategory}:
    parameters:
      - name: idsuppliercategory
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador da categoria de fornecedor.
    put:
      operationId: supplierCategoryPut
      tags:
        - Categorias de Fornecedor
      summary: Atualiza uma categoria de fornecedor
      description: >-
        Atualiza a descrição e/ou o tipo de fornecedor de uma categoria existente. Ambos os campos são considerados em
        toda chamada — não é uma atualização parcial. A resposta repete o formato da listagem.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SupplierCategoryUpdate'
        description: >-
          Novos valores da categoria. Os dois campos são gravados via `UPDATE` direto, então envie-os mesmo quando só um
          precisa mudar.
      responses:
        '200':
          description: Categoria atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SupplierCategoryListItem'
                maxItems: 1
        '400':
          description: 'Categoria não encontrada para a empresa. Mensagem: `[BadRequest] - Categoria fornecedor não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: supplierCategoryDelete
      tags:
        - Categorias de Fornecedor
      summary: Exclui (inativa) uma categoria de fornecedor
      description: >-
        Inativa a categoria (`SuppliersCategoryStatus = 0`). Não exclui fisicamente o registro. A exclusão é bloqueada
        quando há fornecedores ativos vinculados à categoria — nesse caso é preciso primeiro alterar a categoria no
        cadastro de cada fornecedor. A resposta é a lista atualizada das categorias ativas da empresa.
      responses:
        '200':
          description: Categoria inativada. Devolve a lista atualizada das categorias ativas.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SupplierCategoryListItem'
        '400':
          description: >-
            Categoria não encontrada ou possui fornecedores ativos. Mensagens: `[BadRequest] - Categoria fornecedor não
            existe`; `[BadRequest] - Existem fornecedores nessa categoria, alterar a categoria dentro do cadastro do
            fornecedor antes de excluir`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /accounts/cash-flow:
    get:
      operationId: cashFlowList
      tags:
        - Fluxo de Caixa
      summary: Lista o fluxo de caixa
      description: >-
        Retorna o fluxo de caixa da empresa em dois modos, controlados pelo parâmetro `Type`:


        - **Resumo** (default, sem `Type`): consolidado mês a mês (ou dia a dia, com `GroupBy=day`) do **previsto**
        `TotalValue` e do **realizado** `ValuePaid`, agrupado por plano de contas. Cada item inclui a árvore completa do
        plano de contas em `CategoryTree`. Considera o ano inteiro definido em `Year` (ou o ano corrente quando omitido)
        e ignora contas com status **Não lançado**.

        - **Detalhe** (`Type=Detail`): lista os títulos individuais (`AccountsPayableReceivable`) que compõem uma célula
        do resumo. Use `IDTypeAccountPayableReceivable` para restringir ao plano de contas selecionado e `Date`
        (primeiro dia do mês `YYYY-MM-DD`) combinado com `DateType` para restringir ao mês — `DateType=DateDue` filtra
        pelo vencimento (coluna **Previsto**); qualquer outro valor (a UI envia `DatePayment`) filtra pela data de
        pagamento lançado (coluna **Realizado**).


        Valores são assinados pelo tipo de lançamento: contas a pagar (`IDTypeAccount=1`) entram negativas; contas a
        receber (`IDTypeAccount=0`) entram positivas.
      parameters:
        - name: Year
          in: query
          required: false
          schema:
            type: integer
          description: 'Ano de referência (default: ano corrente). O resumo cobre de 01/jan a 31/dez deste ano.'
        - name: GroupBy
          in: query
          required: false
          schema:
            type: string
            enum:
              - month
              - day
            default: month
          description: >-
            Granularidade do agrupamento no modo Resumo: `month` consolida por mês, `day` consolida por dia. Ignorado no
            modo Detalhe.
        - name: Type
          in: query
          required: false
          schema:
            type: string
            enum:
              - Detail
          description: >-
            Quando `Detail`, lista os títulos individuais (modo de detalhamento, usado pelo drill-through). Omitido:
            modo Resumo.
        - name: Date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: >-
            **Modo Detalhe**. Primeiro dia do mês a detalhar (`YYYY-MM-DD`); o sistema deriva o último dia do mesmo mês
            como limite superior.
        - name: DateType
          in: query
          required: false
          schema:
            type: string
            enum:
              - DateDue
              - DatePayment
          description: >-
            **Modo Detalhe**. Define a coluna do `Date`: `DateDue` filtra pelo vencimento (lançamentos previstos do
            mês); `DatePayment` filtra pela data do pagamento lançado (lançamentos realizados do mês).
        - name: IDTypeAccountPayableReceivable
          in: query
          required: false
          schema:
            type: integer
          description: '**Modo Detalhe**. Restringe ao plano de contas selecionado.'
        - name: IDBankAccountForecast
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pela conta bancária prevista do lançamento.
        - name: IDBankAccount
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por lançamentos que tenham pelo menos um pagamento (entrada do extrato) na conta bancária informada.
        - name: IDCompanyInvoice
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pela empresa faturadora (filial) do lançamento.
      responses:
        '200':
          description: >-
            Fluxo de caixa retornado. O formato depende de `Type`: array de itens consolidados (modo Resumo) ou array de
            títulos individuais (modo Detalhe). Quando não há registros no Resumo, retorna `[]`.
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/CashFlowSummaryItem'
                  - type: array
                    items:
                      $ref: '#/components/schemas/CashFlowDetailItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /accounts/payable:
    get:
      operationId: accountsPayableList
      tags:
        - Contas a Pagar
      summary: Lista contas a pagar
      description: >-
        Retorna as contas a pagar da empresa, com totais já calculados — valor total `ValueTotal`, valor pago
        `ValuePaid`, saldo devedor `ValuePaymentPending`. Aceita filtros por data (vencimento, documento, competência,
        último pagamento, registro), valor, status, fornecedor, cliente, tipo de documento, tipo de pagamento, plano de
        contas, centro de custo, conta bancária, pedido associado e mais. Paginação por `Page` (5000 itens por página).


        Quando a parametrização **Permitir visualizar registros apenas fornecedores vinculados ao usuário** da empresa
        está ativa, os resultados são restritos às categorias de fornecedor vinculadas ao usuário autenticado.


        Use `IDTypeEntity=1` para trazer apenas títulos com cliente e `IDTypeEntity=2` para apenas títulos com
        fornecedor.
      parameters:
        - name: Page
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: Página (cada página tem 5000 itens).
        - name: IDAccountPayableReceivable
          in: query
          required: false
          schema:
            type: string
          description: Filtra por um ou mais ids (lista separada por vírgula). Útil para retornar lotes recém-criados.
        - name: IDStatusAccountPayableReceivable
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
              enum:
                - 0
                - 1
                - 2
                - 3
                - 4
                - 5
                - 6
            default:
              - 0
              - 1
              - 2
              - 3
              - 5
          description: >-
            Filtro de status (lista separada por vírgula). Valores: 0=Aberto, 1=Vencido, 2=Pago, 3=Pago Parcialmente,
            4=Não lançado, 5=Pago com acréscimo, 6=Vence hoje. Default `0,1,2,3,5` (não traz Pago, Não lançado nem Vence
            hoje).
          style: form
          explode: false
        - name: IDSupplier
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por fornecedor.
        - name: IDConsumer
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por cliente.
        - name: IDTypeEntity
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
              - 2
          description: 'Restringe ao tipo: `1` apenas com cliente, `2` apenas com fornecedor.'
        - name: DocumentNumber
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo número do documento.
        - name: IDTypeAccountPayableReceivable
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por plano de contas.
        - name: IDTypePayment
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por tipo de pagamento.
        - name: IDTypeDocument
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por tipo de documento.
        - name: Scheduled
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Apenas títulos agendados (`1`) ou não (`0`).
        - name: Forecast
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Apenas previsões (`1`) ou apenas reais (`0`).
        - name: IDOrder
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por pedido associado.
        - name: IDCompanyInvoice
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por empresa faturadora.
        - name: IDBankAccountForecast
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pela conta bancária prevista para pagamento.
        - name: IDBankAccount
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pela conta bancária do pagamento já lançado.
        - name: ValueFrom
          in: query
          required: false
          schema:
            type: number
          description: Valor mínimo.
        - name: ValueTo
          in: query
          required: false
          schema:
            type: number
          description: Valor máximo.
        - name: DateDueFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Vencimento a partir de.
        - name: DateDueTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Vencimento até.
        - name: DateDocumentFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data do documento a partir de.
        - name: DateDocumentTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data do documento até.
        - name: DateCompetenceFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Competência a partir de.
        - name: DateCompetenceTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Competência até.
        - name: DateLastPaymentFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Último pagamento a partir de.
        - name: DateLastPaymentTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Último pagamento até (inclusivo até 23:59).
        - name: DateRecordTimestampFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data de criação do registro a partir de.
        - name: DateRecordTimestampTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data de criação do registro até (inclusivo até 23:59).
        - name: IDTypeCostCenter
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por centro de custo. Traz apenas os títulos vinculados ao centro de custo informado.
      responses:
        '200':
          description: >-
            Lista de contas a pagar com totais calculados (vazia quando o usuário não tem acesso pela parametrização de
            governança).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AccountsPayableListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: accountsPayablePost
      tags:
        - Contas a Pagar
      summary: Cria contas a pagar (com suporte a recorrência e retenção de impostos)
      description: >-
        Cria uma ou mais contas a pagar. Suporta recorrência mensal, semanal ou personalizada, tratamento de feriado e
        fim de semana, retenção de impostos (que gera contas filhas e abate o valor da conta principal) e replicação
        automática dos centros de custo do fornecedor. A criação é registrada no histórico para auditoria. A resposta
        traz as contas recém-criadas no mesmo formato da listagem.


        **Regras de negócio**:

        - `IDConsumer` e `IDSupplier` não podem ser enviados juntos.

        - Quando `IDBankAccountForecast` é omitido e a empresa tem **exatamente uma** conta bancária cadastrada, ela é
        usada automaticamente.

        - Para recorrência mensal, `PeriodTypeValue` deve estar entre 1 e 31 (dia do mês).

        - Para recorrência semanal, `PeriodTypeValue` deve estar entre 0 e 6 (dia da semana).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountsPayableCreate'
        description: >-
          Dados do título a pagar. `DateDue`, `Value`, `IDTypeDocument` e `IDTypeAccountPayableReceivable` são
          obrigatórios. Para criar uma **série recorrente**, envie `PeriodType`, `QuantityRepeat` e `PeriodTypeValue` —
          o sistema gera as próximas ocorrências ajustando feriados/finais de semana conforme `Holiday`.
      responses:
        '200':
          description: Conta(s) criada(s). Retorna a lista das contas recém-criadas.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AccountsPayableListItem'
        '400':
          description: >-
            Validação falhou (prefixo `[BadRequest]`). Possíveis mensagens:

            - `Fornecedor ou cliente precisa ser preenchido (apenas um dos dois)`

            - `Fornecedor não existe` / `Cliente não existe`

            - `Faturador não existe` / `Empresa não existe`

            - `Type Payment não existe` / `Tipo documento não existe` / `Plano de contas não existe`

            - `Pedido não existe` / `Conta bancária não existe`

            - `Fornecedor retenção é obrigatório` / `Valor retenção é obrigatório` / `Data vencimento retenção é
            obrigatória`

            - `Valor retenção superior ao valor do título`

            - `Fornecedores(s) retenção imposto não localizado(s): ...`

            - `Dia do mês precisa ser entre 1 e 31` / `Dia do semana precisa ser entre 0 e 6` / `Precisa enviar o
            intervalo` / `Precisa enviar o tipo de frequencia`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /accounts/payable/{idaccountpayable}:
    parameters:
      - name: idaccountpayable
        in: path
        required: true
        description: Identificador da conta a pagar.
        schema:
          type: integer
          format: int32
    get:
      operationId: accountsPayableGet
      tags:
        - Contas a Pagar
      summary: Detalha uma conta a pagar
      description: >-
        Retorna a conta a pagar completa: dados próprios, status, fornecedor ou cliente, tipo de documento, tipo de
        pagamento, plano de contas, total da nota fiscal de origem, indicações de quais tipos de arquivo estão anexados,
        lista de pagamentos e arquivos, GNREs, histórico de alterações, centros de custo rateados e as contas filhas
        geradas por retenção de impostos.


        Atenção: quando o id não existe ou a conta pertence a outra empresa, a resposta é `200` com `[]` (array vazio) —
        este endpoint não retorna erro para "não encontrado".
      responses:
        '200':
          description: Conta encontrada (objeto único em array) ou array vazio quando não encontrada.
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/AccountsPayableDetail'
                    minItems: 1
                    maxItems: 1
                  - type: array
                    maxItems: 0
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    put:
      operationId: accountsPayablePut
      tags:
        - Contas a Pagar
      summary: Atualiza uma conta a pagar
      description: >-
        Atualiza a conta a pagar de forma parcial — apenas os campos enviados são alterados (o `PUT` se comporta como
        `PATCH`). Quando `ChangeNextRepeat=1`, a alteração é propagada para todas as ocorrências futuras da mesma série
        de recorrência.


        A diferença campo a campo é registrada no histórico de alterações. A resposta é a representação completa da
        conta atualizada, no mesmo formato de `GET /accounts/payable/{idaccountpayable}`.
      parameters:
        - name: ChangeNextRepeat
          in: query
          required: false
          description: >-
            Quando `1`, propaga a atualização para as próximas ocorrências da mesma recorrência (com `DateDue`
            posterior).
          schema:
            type: integer
            enum:
              - 1
      requestBody:
        required: true
        description: Todos os campos são opcionais; só os enviados são atualizados.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountsPayableUpdate'
      responses:
        '200':
          description: Conta atualizada. Retorna o mesmo formato do `GET /accounts/payable/{idaccountpayable}`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AccountsPayableDetail'
        '400':
          description: |-
            Validação falhou (prefixo `[BadRequest]`). Mensagens possíveis:
            - `Fornecedor ou cliente precisa ser preenchido (apenas um dos dois)`
            - `Contas a pagar não existe`
            - `Fornecedor não existe` / `Cliente não existe` / `Faturador não existe`
            - `Tipo pagamento não existe` (×2 — também acionado quando `TypeDocument` não é encontrado)
            - `Conta bancária não existe`
            - `Plano de contas não existe`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: accountsPayableDelete
      tags:
        - Contas a Pagar
      summary: Exclui uma conta a pagar
      description: >-
        Remove a conta a pagar e desvincula as GNREs associadas.


        **Regras**:

        - Não é possível excluir quando a conta está agendada.

        - Não é possível excluir quando já existem pagamentos lançados.

        - Quando a conta está vinculada a uma compra e a parametrização **Não permitir excluir contas pagar com
        recebimento** da empresa está ativa, a exclusão é bloqueada.

        - Quando `ChangeNextRepeat=1`, também remove as ocorrências futuras da mesma série de recorrência.

        - Quando a conta está atrelada a um pedido ou ordem de serviço, registra o evento no histórico correspondente e
        devolve a representação atualizada do recurso pai. Caso contrário, devolve a string `"sucesso"`.
      parameters:
        - name: ChangeNextRepeat
          in: query
          required: false
          description: Quando `1`, também exclui as próximas ocorrências da mesma recorrência.
          schema:
            type: integer
            enum:
              - 1
      responses:
        '200':
          description: >-
            Exclusão bem-sucedida. O corpo varia: `"sucesso"` quando não há pedido nem ordem de serviço associada;
            objeto representando o pedido/ordem de serviço atualizada quando houver.
          content:
            application/json:
              schema:
                oneOf:
                  - type: string
                    enum:
                      - sucesso
                  - type: object
                    description: Representação do pedido ou da ordem de serviço — schema não documentado neste piloto.
        '400':
          description: |-
            Regras impeditivas (prefixo `[BadRequest]`):
            - `Pagamento não existe`
            - `Título esta agendado e não pode ser excluído`
            - `Não é possível excluir um contas a pagar atrelado a um recebimento`
            - `Contas a pagar já tem pagamento`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /accounts/payable/file:
    post:
      operationId: accountsPayableFileDownload
      tags:
        - Contas a Pagar
      summary: Gera ZIP com arquivos de contas a pagar e envia por e-mail
      description: >-
        Recebe uma lista de ids de contas a pagar, compacta todos os arquivos anexados num `.zip`, faz upload no S3 e
        envia o link de download para o e-mail do usuário autenticado. O link tem validade de **2 dias**.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: array
                  items:
                    type: integer
                  description: Array direto de IDs.
                - type: object
                  required:
                    - IDAccountPayableReceivable
                  properties:
                    IDAccountPayableReceivable:
                      type: array
                      items:
                        type: integer
                      description: Lista de ids de contas a pagar.
        description: >-
          Lista de identificadores de contas a pagar cujos arquivos serão compactados. Aceita um array direto de
          inteiros ou um objeto com a chave `IDAccountPayableReceivable` contendo o array.
      responses:
        '200':
          description: URL assinada do ZIP gerado no S3 (válida por 48 horas). O arquivo também é enviado para o e-mail do usuário.
          content:
            application/json:
              schema:
                type: string
                format: uri
        '400':
          description: |-
            Erros de validação (prefixo `[BadRequest]`):
            - `IDs inválidos`
            - `Nenhum arquivo encontrado`
            - `Usuário não encontrado`
            - `Empresa inválida`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /accounts/payable/{idaccountpayable}/payment:
    parameters:
      - name: idaccountpayable
        in: path
        required: true
        description: Identificador da conta a pagar.
        schema:
          type: integer
          format: int32
    post:
      operationId: accountsPayablePaymentPost
      tags:
        - Contas a Pagar
      summary: Lança um pagamento na conta a pagar
      description: >-
        Registra um pagamento na conta a pagar, atualizando o status conforme o saldo devedor resultante. Quando
        `FinishIfPossible=1` e há pedido vinculado, tenta finalizar o pedido se todos os títulos estiverem pagos.
      parameters:
        - name: FinishIfPossible
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
          description: >-
            Quando `1`, tenta finalizar o pedido vinculado se todos os seus títulos estiverem pagos após este
            lançamento.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountsPayablePaymentCreate'
        description: >-
          Dados do pagamento a lançar. `IDBankAccount` e `DateTransactionTimestamp` são obrigatórios. Quando `Value` é
          omitido, o sistema assume o saldo devedor total (`ValueTotal - ValuePaid`).
      responses:
        '200':
          description: Pagamento lançado. Retorna a conta a pagar atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AccountsPayableDetail'
        '400':
          description: |-
            Erros de validação (prefixo `[BadRequest]`):
            - `Conta a receber/pagar não existe`
            - `Conta bancária não existe`
            - `Caixinha esta aberto e não pode ter pagamentos efetuados`
            - `Valor a conciliar divergente de valor do título e não há outro lançamento relacionado`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /accounts/payable/{idaccountpayable}/payment/{idaccountpayment}:
    parameters:
      - name: idaccountpayable
        in: path
        required: true
        description: Identificador da conta a pagar.
        schema:
          type: integer
          format: int32
      - name: idaccountpayment
        in: path
        required: true
        description: Identificador do lançamento de pagamento (`IDBankStatement`).
        schema:
          type: integer
          format: int32
    delete:
      operationId: accountsPayablePaymentDelete
      tags:
        - Contas a Pagar
      summary: Cancela um pagamento lançado
      description: >-
        Remove o lançamento de pagamento e reverte o status da conta a pagar. Quando o pagamento está vinculado a uma
        conciliação bancária, desfaz o vínculo e recalcula o status da conciliação. Registra a exclusão no histórico da
        conta.
      parameters:
        - name: IDBankStatementConciliation
          in: query
          required: false
          schema:
            type: integer
          description: >-
            Quando informado, garante que o pagamento só seja excluído se pertencer a esta conciliação. Pagamentos
            vinculados a outra conciliação são bloqueados.
      responses:
        '200':
          description: Pagamento cancelado. Retorna a conta a pagar atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AccountsPayableDetail'
        '400':
          description: |-
            Erros de validação (prefixo `[BadRequest]`):
            - `Pagamento não existe`
            - `Pagamento foi realizado em um caixa e não pode ser excluído`
            - `Caixinha esta aberto e não pode ter pagamentos efetuados`
            - `Não é possível excluir um pagamento vinculado a outra conciliação bancária`
            - `Problema ao deletar pagamento`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /accounts/payable/{idaccountpayable}/cost-center:
    parameters:
      - name: idaccountpayable
        in: path
        required: true
        description: Identificador da conta a pagar.
        schema:
          type: integer
          format: int32
    post:
      operationId: accountsPayableReceivableCostCenterPost
      tags:
        - Contas a Pagar
      summary: Define o rateio de centros de custo
      description: >-
        Substitui completamente o rateio de centros de custo da conta a pagar. Enviar array vazio remove todos os
        centros. A soma de `ValueRatio` de todos os itens deve ser exatamente `1` (100%).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AccountsPayableCostCenterSetItem'
              description: Lista de centros de custo com suas proporções. Array vazio limpa todos os centros.
        description: >-
          Array com os centros de custo e suas proporções (`ValueRatio`). A soma dos `ValueRatio` precisa ser exatamente
          `1` (100%). Array vazio remove todos os centros de custo da conta.
      responses:
        '200':
          description: Rateio atualizado. Retorna a conta a pagar atualizada ou `"sucesso"` quando o array foi vazio.
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/AccountsPayableDetail'
                  - type: string
                    enum:
                      - sucesso
        '400':
          description: |-
            Erros de validação (prefixo `[BadRequest]`):
            - `Conta a receber/pagar não existe`
            - `Rateio precisa somar 100%`
            - `Centro de custo(s) não localizado(s): {ids}`
            - `Precisa enviar ao menos um centro de custo`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /accounts/payable/{idaccountpayable}/bank-integration:
    parameters:
      - name: idaccountpayable
        in: path
        required: true
        description: Identificador da conta a pagar.
        schema:
          type: integer
          format: int32
    post:
      operationId: accountsPayableBankPaymentPost
      tags:
        - Contas a Pagar
      summary: Envia a conta a pagar para pagamento bancário integrado
      description: >-
        Processa o pagamento via integração bancária. Após o envio, retorna a conta atualizada, salvo quando
        `NoInvoke=1`.
      parameters:
        - name: NoInvoke
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
          description: Quando `1`, não consulta `accountsPayableGet` após o envio e devolve apenas `"Sucesso"`.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              description: Corpo não utilizado; pode ser omitido.
        description: Corpo não utilizado; pode ser omitido. O envio é sempre referente ao título identificado no path.
      responses:
        '200':
          description: Envio bem-sucedido. Retorna a conta a pagar atualizada ou `"Sucesso"` quando `NoInvoke=1`.
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/AccountsPayableDetail'
                  - type: string
                    enum:
                      - Sucesso
        '400':
          description: |-
            Erros de validação (prefixo `[BadRequest]`):
            - `Título precisa ser enviado`
            - Mensagens de erro retornadas pelo processo bancário.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /accounts/payable/{idaccountpayable}/file:
    parameters:
      - name: idaccountpayable
        in: path
        required: true
        description: Identificador da conta a pagar.
        schema:
          type: integer
          format: int32
    post:
      operationId: accountsFilePost
      tags:
        - Contas a Pagar
      summary: Anexa um arquivo à conta a pagar
      description: >-
        Faz upload de um arquivo via `multipart/form-data` (campo `file`) e o vincula à conta a pagar. O tipo do arquivo
        é definido pelo parâmetro `IDTypeFile`. Ao anexar um boleto, o sistema tenta ler automaticamente o código de
        barras ou o PIX copia-e-cola do arquivo; quando a conta ainda não tem `BankSlipBarCode` preenchido, o valor lido
        é gravado. Retorna o detalhe atualizado da conta a pagar.
      parameters:
        - name: IDTypeFile
          in: query
          required: true
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 3
              - 4
              - 5
              - 6
              - 7
              - 8
          description: >-
            Tipo do arquivo: 1=Documento Fiscal PDF, 2=Documento Fiscal XML, 3=Boleto Bancário, 4=Comprovante Pagamento,
            5=Carta de Correção PDF, 6=Carta de Correção XML, 7=Inutilização NF XML, 8=Cancelamento NF XML.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: Arquivo a ser anexado.
        description: >-
          Upload `multipart/form-data` com o campo `file` contendo o binário do arquivo. O tipo é controlado pelo
          parâmetro de query `IDTypeFile`.
      responses:
        '200':
          description: Arquivo anexado. Retorna a conta a pagar atualizada com o novo arquivo listado em `Files`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AccountsPayableDetail'
        '404':
          description: Conta a pagar não encontrada para a empresa. Corpo vazio.
  /accounts/payable/{idaccountpayable}/file/{idfile}:
    parameters:
      - name: idaccountpayable
        in: path
        required: true
        description: Identificador da conta a pagar.
        schema:
          type: integer
          format: int32
      - name: idfile
        in: path
        required: true
        description: Identificador do arquivo.
        schema:
          type: integer
          format: int32
    get:
      operationId: accountsFileGet
      tags:
        - Contas a Pagar
      summary: Baixa um arquivo anexado à conta a pagar
      description: >-
        Serve o arquivo diretamente do S3. A implementação não foi localizada localmente — comportamento inferido a
        partir das URLs geradas em `accountsPayableGet`. Aceita `View=1` e `token` como query params conforme o link
        gerado.


        ⚠️ *Sistema não confirmado em código.*
      parameters:
        - name: View
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
          description: Quando `1`, serve o arquivo para visualização no browser.
        - name: token
          in: query
          required: false
          schema:
            type: string
          description: Token de autenticação (alternativa ao header `Authorization` para uso em links diretos).
        - name: File
          in: query
          required: false
          schema:
            type: string
          description: Parâmetro de roteamento interno gerado pelo sistema.
      responses:
        '200':
          description: Conteúdo binário do arquivo.
    delete:
      operationId: accountsFileDelete
      tags:
        - Contas a Pagar
      summary: Remove um arquivo anexado à conta a pagar
      description: Exclui o arquivo do banco e retorna a conta a pagar atualizada.
      responses:
        '200':
          description: Arquivo removido. Retorna a conta a pagar atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AccountsPayableDetail'
        '400':
          description: Arquivo não encontrado para esta conta.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /accounts/receivable:
    get:
      operationId: accountsReceivableList
      tags:
        - Contas a Receber
      summary: Lista contas a receber
      description: >-
        Retorna as contas a receber da empresa, com totais calculados — valor total `ValueTotal`, valor pago
        `ValuePaid`, saldo pendente `ValuePaymentPending`. Cada item traz também dados resolvidos do pedido associado,
        da nota fiscal de origem (quando há) e da integração. Aceita filtros por data, valor, status, cliente,
        fornecedor, plano de contas, tipo de documento, tipo de pagamento, conta bancária, pedido, adquirente
        (`TID`/`NSU`) e mais. Paginação por `Page` (4000 itens por página).


        Quando a parametrização **Permitir visualizar registros apenas fornecedores vinculados ao usuário** da empresa
        está ativa, os resultados são restritos às categorias de fornecedor vinculadas ao usuário autenticado.


        Use `IDTypeEntity=1` para trazer apenas títulos com cliente (cobrança) e `IDTypeEntity=2` para apenas títulos
        com fornecedor (devolução ou estorno).
      parameters:
        - name: Page
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: Página (cada página tem 4000 itens).
        - name: IDAccountPayableReceivable
          in: query
          required: false
          schema:
            type: string
          description: Filtra por um ou mais ids da conta a receber (lista separada por vírgula).
        - name: IDStatusAccountPayableReceivable
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
              enum:
                - 0
                - 1
                - 2
                - 3
                - 4
                - 5
                - 6
            default:
              - 0
              - 1
              - 2
              - 3
              - 5
          description: >-
            Filtro de status (lista separada por vírgula). Valores: 0=Aberto, 1=Vencido, 2=Pago, 3=Pago Parcialmente,
            4=Não lançado, 5=Pago com acréscimo, 6=Vence hoje. Default `0,1,2,3,5` (omite Pago, Não lançado e Vence
            hoje).
          style: form
          explode: false
        - name: IDConsumer
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por cliente.
        - name: IDSupplier
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por fornecedor (caso de devolução/estorno em contas a receber).
        - name: ConsumerNameCorporateName
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo nome ou razão social do cliente (ou do fornecedor, quando o título é de fornecedor).
        - name: IDTypeEntity
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
              - 2
          description: 'Restringe ao tipo: `1` apenas com cliente, `2` apenas com fornecedor.'
        - name: DocumentNumber
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo número do documento.
        - name: NfeNumber
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo número da nota fiscal de origem.
        - name: IDTypeAccountPayableReceivable
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por plano de contas.
        - name: IDTypePayment
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por tipo de pagamento.
        - name: IDTypeDocument
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por tipo de documento.
        - name: IDOrder
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo identificador interno do pedido associado.
        - name: Order
          in: query
          required: false
          schema:
            type: string
          description: 'Filtra pelo número externo do pedido (ex.: `OT-1234`, `ML-5678`).'
        - name: OrderFrom
          in: query
          required: false
          schema:
            type: string
          description: Filtra por pedido de origem (lista de canais de venda associados ao pedido).
        - name: IDCompanyInvoice
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pela empresa faturadora.
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pela integração originadora do título (marketplace, adquirente, ERP).
        - name: IDBankAccountForecast
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pela conta bancária prevista para recebimento.
        - name: IDBankAccount
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pela conta bancária onde o pagamento já foi lançado.
        - name: TID
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo TID (identificador da transação do adquirente).
        - name: NSU
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo NSU (identificador sequencial único do adquirente).
        - name: TIDorNSU
          in: query
          required: false
          schema:
            type: string
          description: >-
            Procura o mesmo valor em `TID` **ou** `NSU` (cláusula `OR`). Use quando o usuário não sabe a origem do
            identificador.
        - name: NSUorTID
          in: query
          required: false
          schema:
            type: string
          description: Alias adicional ao filtro `TIDorNSU` — combinado a ele, expande o `OR` para um segundo par de valores.
        - name: ValueFrom
          in: query
          required: false
          schema:
            type: number
          description: Valor total mínimo (`Value + ValuePenalty + ValueInterest - ValueDiscount`).
        - name: ValueTo
          in: query
          required: false
          schema:
            type: number
          description: Valor total máximo.
        - name: DateDueFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Vencimento a partir de.
        - name: DateDueTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Vencimento até.
        - name: DateDocumentFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data do documento a partir de.
        - name: DateDocumentTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data do documento até.
        - name: DateCompetenceFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Competência a partir de.
        - name: DateCompetenceTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Competência até.
        - name: DateLastPaymentFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data do último pagamento a partir de.
        - name: DateLastPaymentTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data do último pagamento até (inclusivo até 23:59).
        - name: DateRecordTimestampFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data de cadastro do registro a partir de.
        - name: DateRecordTimestampTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data de cadastro do registro até (inclusivo até 23:59).
        - name: InvoiceDateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data de emissão da nota fiscal de origem a partir de.
        - name: InvoiceDateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data de emissão da nota fiscal de origem até (inclusivo até 23:59:59).
      responses:
        '200':
          description: >-
            Lista de contas a receber com totais calculados (vazia quando o usuário não tem acesso pela parametrização
            de governança ou não há matches).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AccountsReceivableListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: accountsReceivablePost
      tags:
        - Contas a Receber
      summary: Cria uma conta a receber
      description: >-
        Cria uma nova conta a receber. A resposta é a representação completa da conta recém-criada, no mesmo formato de
        `GET /accounts/receivable/{idaccountreceivable}` (objeto único dentro de array).


        **Regras de negócio**:

        - `IDConsumer` e `IDSupplier` não podem ser enviados juntos — apenas um dos dois.

        - Quando `IDCompanyInvoice` é omitido, assume a empresa autenticada.

        - Strings vazias são tratadas como nulas — equivalentes a omitir o campo.

        - Cria sempre como conta de **entrada** (`IDTypeAccount=0`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountsReceivableCreate'
        description: >-
          Dados do título a receber. `DateDue`, `Value`, `IDTypeDocument` e `IDTypeAccountPayableReceivable` são
          obrigatórios. `IDTypePayment` é opcional — quando informado é validado contra a tabela de tipos de pagamento.
          `IDConsumer` e `IDSupplier` são mutuamente exclusivos.
      responses:
        '200':
          description: Conta criada. Retorna a representação completa da conta no formato detalhado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AccountsReceivableDetail'
                minItems: 1
                maxItems: 1
        '400':
          description: |-
            Validação falhou (prefixo `[BadRequest]`). Possíveis mensagens:
            - `Fornecedor ou cliente precisa ser preenchido (apenas um dos dois)`
            - `Empresa não existe`
            - `Cliente não existe` / `Fornecedor não existe`
            - `Faturador não existe`
            - `Type Payment não existe`
            - `Tipo documento não existe` / `Plano de contas não existe`
            - `IDBankAccountForecast não existe`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /accounts/receivable/conciliation:
    get:
      operationId: accountsReceivableConciliationList
      tags:
        - Contas a Receber
      summary: Lista conciliações de adquirentes (auditoria de taxas)
      description: >-
        Retorna as conciliações de adquirentes recebidas. Há dois modos de operação:


        - **Default (`AuditRate` omitido ou `0`)**: lista as conciliações com seus vínculos a contas a receber e a
        lançamentos bancários, devolvendo valores brutos (`TotalValue`, `ReceivedValue`), taxas efetivas
        (`MerchantDiscountRateEffectiveValue`, `AnticipationRateEffectiveValue`) e a sugestão de `IDTypePayment` baseada
        no tipo de adquirente.

        - **Auditoria (`AuditRate=1`)**: compara as taxas efetivas pagas pelo adquirente com as taxas configuradas em
        `TypePaymentRate`, calculando os percentuais aplicados, esperados e a diferença em valor. Devolve também um
        `IDAuditStatus` (1=verde/OK, 2=azul/com prejuízo, 3=amarelo/sem configuração, 4=laranja/taxa configurada não
        aplicada, 5=vermelho/diferença grande). Use `IDAuditStatus` para filtrar apenas conciliações com determinado
        resultado de auditoria.


        Paginação por `Page` (5000 itens por página).
      parameters:
        - name: Page
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: Página (cada página tem 5000 itens).
        - name: AuditRate
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Quando `1`, ativa o modo de auditoria de taxas — a resposta usa `AccountsReceivableConciliationAuditItem`.
        - name: IDAuditStatus
          in: query
          required: false
          schema:
            type: string
          description: >-
            Filtra por resultado de auditoria (apenas quando `AuditRate=1`). Lista separada por vírgula. Valores:
            1=verde, 2=azul, 3=amarelo, 4=laranja, 5=vermelho.
        - name: IDAccountsPayableReceivableConciliation
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por identificador único da conciliação.
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pela integração adquirente.
        - name: IDTypePaymentFrom
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo tipo de pagamento do adquirente (`TypeAcquirerPayment`).
        - name: IDOrder
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo pedido vinculado a alguma conta a receber conciliada (não aplicável quando `AuditRate=1`).
        - name: TID
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo TID da conciliação.
        - name: NSU
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo NSU da conciliação.
        - name: ExternalIDOrderReference
          in: query
          required: false
          schema:
            type: string
          description: Filtra pela referência externa do pedido enviada pelo adquirente.
        - name: Status
          in: query
          required: false
          schema:
            type: integer
          description: >-
            Filtra pelo status retornado pelo adquirente (`IDTypeAcquirerStatus`). Ex.: 1=Pagamento, 3=Devolução,
            4=Chargeback.
        - name: ConciliationStatus
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 3
              - 4
          description: >-
            Status de conciliação interno: 1=Não conciliado, 2=Conciliação automática, 3=Conciliação manual,
            4=Conciliação parcial (não aplicável quando `AuditRate=1`).
        - name: ReceivableIDBank
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo banco em que o adquirente liberou o valor.
        - name: IDTypeAcquirerReleaseType
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo tipo de liberação do adquirente.
        - name: SaleDateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data da venda a partir de.
        - name: SaleDateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data da venda até. Default `4000-01-01` (sem limite superior).
        - name: ReceivedDateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data de recebimento a partir de.
        - name: ReceivedDateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data de recebimento até. Default `4000-01-01` (sem limite superior).
        - name: RecordTimestampFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data de cadastro do registro a partir de.
        - name: RecordTimestampTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data de cadastro do registro até (inclusivo até 23:59:59).
      responses:
        '200':
          description: Lista de conciliações. O schema do item depende de `AuditRate`.
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/AccountsReceivableConciliationListItem'
                    description: Resposta default (`AuditRate=0`).
                  - type: array
                    items:
                      $ref: '#/components/schemas/AccountsReceivableConciliationAuditItem'
                    description: Resposta com auditoria de taxas (`AuditRate=1`).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /accounts/receivable/conciliation/{idaccountspayablereceivableconciliation}:
    parameters:
      - name: idaccountspayablereceivableconciliation
        in: path
        required: true
        description: Identificador da conciliação de adquirente.
        schema:
          type: integer
          format: int32
    put:
      operationId: accountsReceivableConciliationPut
      tags:
        - Contas a Receber
      summary: Atualiza observações de uma conciliação
      description: >-
        Atualiza apenas o campo `Comments` da conciliação. Demais campos da conciliação não podem ser alterados por esta
        rota. A resposta é a conciliação atualizada no mesmo formato da listagem default.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountsReceivableConciliationUpdate'
        description: Apenas `Comments` é alterável; demais campos da conciliação são ignorados.
      responses:
        '200':
          description: Conciliação atualizada. Retorna a conciliação no mesmo formato de `GET /accounts/receivable/conciliation`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AccountsReceivableConciliationListItem'
        '400':
          description: 'Conciliação não existe. Mensagem: `[BadRequest] - Conciliação não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /accounts/receivable/marketplace-conciliation:
    get:
      operationId: accountsReceivableMarketplaceConciliationList
      tags:
        - Contas a Receber
      summary: Lista conciliações de marketplace
      description: >-
        Retorna as conciliações de marketplace, ou seja, os valores liberados por integrações de marketplace para cada
        pedido — já decompostos em comissão (`MarketplaceFeeValue`), antecipação (`MarketplaceFinancingFeeValue`), frete
        (`MarketplaceShippingFeeValue`), cupom (`MarketplaceCouponValue`), impostos (`MarketplaceTaxesValue`) e outras
        taxas (`MarketplaceOtherFeeValue`).


        Cada item agrupa as contas a receber internas vinculadas (`InternalAccounts`) e soma os valores líquidos em
        `ERPValueTotal`, permitindo bater o que entrou no banco com o que o marketplace declara.


        Paginação por `Page` (5000 itens por página).
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: Página (cada página tem 5000 itens).
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pela integração de marketplace.
        - name: IDOrder
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo pedido interno vinculado (via `HubOrder`).
        - name: OrderID
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo identificador externo do pedido no marketplace.
        - name: TID
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo TID da conciliação.
        - name: IDTypeAcquirerStatus
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo status do marketplace (`IDTypeAcquirerStatus`).
        - name: IDTypeStatusConciliation
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 3
              - 4
          description: >-
            Status de conciliação: `1` Não conciliado, `2` Conciliado automaticamente, `3` Conciliado manualmente, `4`
            Conciliado parcialmente.
        - name: Installment
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo número da parcela.
        - name: InstallmentTotal
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo total de parcelas.
        - name: SaleDateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data da venda a partir de.
        - name: SaleDateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data da venda até. Default `4000-01-01`.
        - name: ReceivedDateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data de recebimento a partir de.
        - name: ReceivedDateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data de recebimento até. Default `4000-01-01`.
        - name: Page
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: Página dos resultados (cada página tem 5000 itens).
      responses:
        '200':
          description: Lista de conciliações de marketplace agrupadas, cada uma com suas contas internas vinculadas.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AccountsReceivableMarketplaceConciliationItem'
  /accounts/receivable/{idaccountreceivable}:
    parameters:
      - name: idaccountreceivable
        in: path
        required: true
        description: Identificador da conta a receber.
        schema:
          type: integer
          format: int32
    get:
      operationId: accountsReceivableGet
      tags:
        - Contas a Receber
      summary: Detalha uma conta a receber
      description: >-
        Retorna a conta a receber completa: dados próprios, status, cliente ou fornecedor, tipo de documento, tipo de
        pagamento, plano de contas, banco previsto, integração originadora, lista de pagamentos lançados, arquivos
        anexados, histórico de alterações, centros de custo rateados e as contas filhas geradas por conciliação (taxa
        adquirente, comissão de marketplace, etc.).


        Atenção: quando o id não existe ou a conta pertence a outra empresa, a resposta é `200` com `[]` (array vazio) —
        este endpoint não retorna erro para "não encontrado".
      responses:
        '200':
          description: Conta encontrada (objeto único em array) ou array vazio quando não encontrada.
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/AccountsReceivableDetail'
                    minItems: 1
                    maxItems: 1
                  - type: array
                    maxItems: 0
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    put:
      operationId: accountsReceivablePut
      tags:
        - Contas a Receber
      summary: Atualiza uma conta a receber
      description: >-
        Atualiza a conta a receber de forma parcial — apenas os campos enviados são alterados (o `PUT` se comporta como
        `PATCH`). A diferença campo a campo é registrada no histórico de alterações da conta.


        Quando o título tem um boleto ou link de pagamento (`ConsumerBankSlip`) associado:

        - Se o boleto está pago, **a alteração de valor ou vencimento é bloqueada**.

        - Se o boleto está aberto ou cancelado, a alteração é propagada para o gateway de pagamento.


        Quando `IDSupplier` é enviado, `IDConsumer` é zerado (e vice-versa) — não é possível ter os dois ao mesmo tempo.
        A resposta é a representação completa da conta atualizada.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountsReceivableUpdate'
        description: >-
          Campos do título a atualizar (atualização parcial — só os enviados são aplicados). Quando o título tem
          boleto/link de pagamento associado, alterações de `Value` ou `DateDue` podem ser bloqueadas (boleto já pago)
          ou propagadas ao gateway (boleto em aberto).
      responses:
        '200':
          description: Conta atualizada. Retorna o mesmo formato de `GET /accounts/receivable/{idaccountreceivable}`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AccountsReceivableDetail'
        '400':
          description: |-
            Validação falhou (prefixo `[BadRequest]`). Possíveis mensagens:
            - `Conta a receber não existe`
            - `Fornecedor ou cliente precisa ser preenchido (apenas um dos dois)`
            - `Cliente não existe` / `Fornecedor não existe`
            - `Faturador não existe`
            - `Pagamento não existe` / `Banco não existe`
            - `Tipo documento não existe` / `Plano de contas não existe`
            - `Integração não existe`
            - `Boleto / link pagamento já esta pago e não pode ser alterado`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: accountsReceivableDelete
      tags:
        - Contas a Receber
      summary: Exclui uma conta a receber
      description: >-
        Exclui a conta a receber. Bloqueado quando: (a) o título está agendado para pagamento automático
        (`Scheduled=1`); (b) já existe pelo menos um pagamento lançado; (c) o título está vinculado a um recebimento de
        mercadoria (`IDPurchase`) e a parametrização **Não permitir excluir contas pagar com recebimento** está ativa.


        A exclusão também limpa o vínculo de eventuais GNREs (`IDAccountsPayable`). Quando o título foi originado de
        pedido ou ordem de serviço, registra um evento no histórico do pedido/OS.
      parameters:
        - name: ChangeNextRepeat
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
          description: >-
            Quando `1`, exclui também as próximas ocorrências da mesma série de recorrência (vinculadas pelo
            `IDAccountPayableReceivableMain`, com `DateDue` posterior à do título atual).
      responses:
        '200':
          description: Conta excluída. Retorna a string `"sucesso"`.
          content:
            application/json:
              schema:
                type: string
                enum:
                  - sucesso
        '400':
          description: |-
            Erros de validação (prefixo `[BadRequest]`):
            - `Pagamento não existe`
            - `Título esta agendado e não pode ser excluído`
            - `Não é possível excluir um contas a pagar atrelado a um recebimento`
            - `Contas a pagar já tem pagamento`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /accounts/receivable/{idaccountreceivable}/cost-center:
    parameters:
      - name: idaccountreceivable
        in: path
        required: true
        description: Identificador da conta a receber.
        schema:
          type: integer
          format: int32
    post:
      operationId: accountsReceivableCostCenterPost
      tags:
        - Contas a Receber
      summary: Define o rateio de centros de custo
      description: >-
        Substitui completamente o rateio de centros de custo da conta a receber. Enviar array vazio remove todos os
        centros. A soma de `ValueRatio` de todos os itens deve ser exatamente `1` (100%). Os centros enviados precisam
        estar ativos e pertencer à empresa da conta.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AccountsPayableCostCenterSetItem'
              description: Lista de centros de custo com suas proporções. Array vazio limpa todos os centros.
        description: >-
          Array com os centros de custo e suas proporções (`ValueRatio`). A soma dos `ValueRatio` precisa ser exatamente
          `1` (100%). Array vazio remove todos os centros de custo da conta.
      responses:
        '200':
          description: Rateio atualizado. Retorna a conta a receber atualizada ou `"sucesso"` quando o array foi vazio.
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/AccountsReceivableDetail'
                  - type: string
                    enum:
                      - sucesso
        '400':
          description: |-
            Erros de validação (prefixo `[BadRequest]`):
            - `Conta a receber/pagar não existe`
            - `Rateio precisa somar 100%`
            - `Centro de custo(s) não localizado(s): {ids}`
            - `Precisa enviar ao menos um centro de custo`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /accounts/receivable/{idaccountreceivable}/payment:
    parameters:
      - name: idaccountreceivable
        in: path
        required: true
        description: Identificador da conta a receber.
        schema:
          type: integer
          format: int32
    post:
      operationId: accountsReceivablePaymentPost
      tags:
        - Contas a Receber
      summary: Lança um pagamento na conta a receber
      description: >-
        Registra um pagamento na conta a receber, atualizando o status conforme o saldo pendente. Regras:


        - Quando a conta tinha **previsão** (`Forecast=1`), a flag é zerada após o lançamento.

        - Quando a conta não tinha banco previsto (`IDBankAccountForecast`), assume o banco do pagamento como previsão.

        - Quando `IDAccountsPayableReceivableConciliation` é informado e o valor pago difere do título, o sistema
        procura outro lançamento relacionado pelo mesmo `IDOrder`/`TID`/`NSU` e redistribui a diferença entre os dois —
        se não encontrar, falha. Adicionalmente, cria automaticamente o lançamento de **taxa adquirente**
        (`IDTypeAccountPayableReceivable` configurado na integração) abatendo o valor da comissão.

        - Quando `IDAccountsPayableReceivableConciliationMarketplace` é informado, gera automaticamente as contas filhas
        para comissão, antecipação, frete, cupom e impostos do marketplace conforme parametrização da integração.

        - Pagamentos em conta de **caixinha** (`BankNumber=000`) só são aceitos com a caixinha fechada.

        - Quando `FinishIfPossible=1` e há pedido vinculado, tenta finalizar o pedido se todos os títulos estiverem
        pagos após este lançamento.
      parameters:
        - name: FinishIfPossible
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
          description: >-
            Quando `1`, tenta finalizar o pedido vinculado se todos os seus títulos estiverem pagos após este
            lançamento.
        - name: query
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
          description: >-
            Quando `1`, retorna apenas a string `"sucesso"` (não invoca a recuperação completa da conta). Usado em
            fluxos em massa para evitar latência.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountsReceivablePaymentCreate'
        description: >-
          Dados do recebimento a lançar. `IDBankAccount` e `DateTransactionTimestamp` são obrigatórios. Quando
          `IDAccountsPayableReceivableConciliation` é informado e o valor difere do título, o sistema procura outro
          lançamento relacionado para redistribuir a diferença e gera o lançamento automático da taxa do adquirente.
          Quando `IDAccountsPayableReceivableConciliationMarketplace` é informado, gera as contas filhas (comissão,
          antecipação, frete, cupom, impostos) conforme a parametrização da integração.
      responses:
        '200':
          description: Pagamento lançado. Retorna a conta a receber atualizada (ou a string `"sucesso"` quando `query=1`).
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/AccountsReceivableDetail'
                  - type: string
                    enum:
                      - sucesso
        '400':
          description: |-
            Erros de validação (prefixo `[BadRequest]`):
            - `Conta a receber/pagar não existe`
            - `Conta bancária não existe`
            - `Caixinha esta aberto e não pode ter pagamentos efetuados`
            - `Valor a conciliar divergente de valor do título e não há outro lançamento relacionado`
            - `Conciliação marketplace inexistente`
            - `Erro ao criar lançamento de taxa adquirente`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /accounts/receivable/{idaccountreceivable}/payment/{idaccountpayment}:
    parameters:
      - name: idaccountreceivable
        in: path
        required: true
        description: Identificador da conta a receber.
        schema:
          type: integer
          format: int32
      - name: idaccountpayment
        in: path
        required: true
        description: Identificador do lançamento de pagamento (`IDBankStatement`).
        schema:
          type: integer
          format: int32
    delete:
      operationId: accountsReceivablePaymentDelete
      tags:
        - Contas a Receber
      summary: Cancela um pagamento lançado
      description: >-
        Remove o lançamento de pagamento e reverte o status da conta a receber. Regras:


        - Pagamentos lançados em **caixa** (`IDStoreFrontCashier` preenchido) não podem ser excluídos por esta rota.

        - Pagamentos em conta de **caixinha** (`BankNumber=000`) só podem ser excluídos com a caixinha fechada.

        - Quando o pagamento está vinculado a uma **conciliação bancária** (`BankStatementConciliationReference`),
        desvincula e recalcula o status da conciliação para parcial ou não conciliado conforme o resto das referências.

        - Quando o pagamento está vinculado a uma **conciliação adquirente** ou **marketplace**
        (`AccountsPayableReceivableConciliationMatch` / `AccountsPayableReceivableConciliationMarketplaceReference`),
        desvincula e reabre a conciliação correspondente.

        - A exclusão é registrada no histórico da conta.
      parameters:
        - name: IDBankStatementConciliation
          in: query
          required: false
          schema:
            type: integer
          description: >-
            Quando informado, garante que o pagamento só seja excluído se pertencer a esta conciliação bancária.
            Pagamentos vinculados a outra conciliação são bloqueados.
      responses:
        '200':
          description: Pagamento cancelado. Retorna a conta a receber atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AccountsReceivableDetail'
        '400':
          description: |-
            Erros de validação (prefixo `[BadRequest]`):
            - `Pagamento não existe`
            - `Pagamento foi realizado em um caixa e não pode ser excluído`
            - `Caixinha esta aberto e não pode ter pagamentos efetuados`
            - `Não é possível excluir um pagamento vinculado a outra conciliação bancária`
            - `Erro ao atualizar conciliação bancária`
            - `Erro ao verificar vínculos de conciliação`
            - `Problema ao deletar pagamento`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/account/type:
    get:
      operationId: typeAccountTypeList
      tags:
        - Tipos — Contas e Pagamento
      summary: Lista o plano de contas
      description: >-
        Retorna os planos de contas **ativos** (`Status=1`) da empresa em dois formatos, controlados por `Type`:


        - **Árvore** (`Type=Tree`): cada item raiz traz seus descendentes recursivamente em `Children[]`, ordenado por
        descrição. Quando o item tem `ExternalCode`, a descrição é prefixada (`<código>-<descrição>`). Inclui categoria
        do plano (`IDTypeCategoryAccountPayble` / `TypeCategoryAccountPaybleDescription`) já propagada do pai para os
        filhos.

        - **Lista plana** (default, sem `Type`): array com todos os planos no escopo (raiz e filhos), cada item traz o
        caminho hierárquico completo em `CategoryTree` (texto separado por ` -> `, do nível mais alto até a folha) e a
        mesma categoria já propagada.


        Aceita filtros opcionais por tipo (`IDTypeAccount`), categoria (`IDTypeCategoryAccountPayble`) e identificador
        (`IDTypeAccountPayble`) — este último só é considerado no modo Árvore.
      parameters:
        - name: Type
          in: query
          required: false
          schema:
            type: string
            enum:
              - Tree
          description: >-
            Quando `Tree`, devolve estrutura aninhada com `Children[]`. Sem o parâmetro, devolve lista plana com
            `CategoryTree`.
        - name: IDTypeAccount
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: 'Filtra pelo tipo do lançamento: `0` entrada (a receber), `1` saída (a pagar).'
        - name: IDTypeCategoryAccountPayble
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pela categoria do plano (ver `GET /type/account/type/category`).
        - name: IDTypeAccountPayble
          in: query
          required: false
          schema:
            type: integer
          description: (Apenas no modo Árvore) Restringe ao plano com o id informado. Ignorado na lista plana.
      responses:
        '200':
          description: >-
            Plano de contas retornado. O formato depende de `Type`. Quando a lista plana não tem resultados, retorna
            `[]`.
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/TypeAccountTreeNode'
                    description: Modo Árvore.
                  - type: array
                    items:
                      $ref: '#/components/schemas/TypeAccountFlatItem'
                    description: Modo Lista plana (default).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: typeAccountTypePost
      tags:
        - Tipos — Contas e Pagamento
      summary: Cadastra um plano de contas
      description: >-
        Cria um plano de contas. Quando `IDTypeAccountPaybleFather` é informado, o plano nasce como **filho** do pai
        indicado e a categoria informada (`IDTypeCategoryAccountPayble`) é descartada — a categoria do filho é sempre a
        do pai. Quando o pai é omitido, a categoria informada é gravada (opcional).


        Marcar **`DefaultOrder=1`** ou **`DefaultPurchase=1`** transforma este plano no padrão da empresa — qualquer
        outro plano marcado é automaticamente desmarcado. Se `ExternalCode` ou `InternalCode` forem informados, precisam
        ser únicos entre os planos ativos da empresa.


        A resposta retorna o plano recém-criado no formato controlado pelo query `Type` (mesmo do `GET`).
      parameters:
        - name: Type
          in: query
          required: false
          schema:
            type: string
            enum:
              - Tree
            default: Tree
          description: Formato do plano retornado na resposta. Default `Tree`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TypeAccountCreate'
        description: >-
          Dados do plano de contas a cadastrar. `TypeAccountPaybleDescription` obrigatório. Quando
          `IDTypeAccountPaybleFather` é informado, o plano nasce como filho do pai indicado e a
          `IDTypeCategoryAccountPayble` enviada é descartada (filho herda do pai). `ExternalCode` e `InternalCode`,
          quando informados, precisam ser únicos entre os planos ativos da empresa. Marcar `DefaultOrder=1` ou
          `DefaultPurchase=1` desmarca automaticamente o anterior.
      responses:
        '200':
          description: Plano criado. Retorna o item recém-criado no formato indicado por `Type`.
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/TypeAccountTreeNode'
                  - type: array
                    items:
                      $ref: '#/components/schemas/TypeAccountFlatItem'
        '400':
          description: |-
            Erros de validação (prefixo `[BadRequest]`):
            - `Empresa não existe`
            - `Plano de contas superior não existe`
            - `Já existe um plano com o mesmo cód. referência externo`
            - `Já existe um plano com o mesmo cód. referência interno`
            - `IDTypeCategoryAccountPayble não existe`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/account/type/{idtypeaccount}:
    parameters:
      - name: idtypeaccount
        in: path
        required: true
        description: Identificador do plano de contas (`IDTypeAccountPayble`).
        schema:
          type: integer
          format: int32
    put:
      operationId: typeAccountTypePut
      tags:
        - Tipos — Contas e Pagamento
      summary: Atualiza um plano de contas
      description: >-
        Atualiza o plano de contas com o id informado. As mesmas regras do POST valem: pai descarta categoria,
        `ExternalCode`/`InternalCode` precisam ser únicos entre os planos ativos da empresa, e marcar `DefaultOrder=1`
        ou `DefaultPurchase=1` desmarca o anterior.


        **Diferença importante em relação ao POST**: quando o cliente envia `DefaultOrder=0` (ou omite) e **não existe
        outro plano** marcado como padrão de pedido na empresa (excluindo este), a operação **falha** — sempre é preciso
        ter exatamente um padrão de pedido. A mesma regra vale para `DefaultPurchase=0`.


        A resposta retorna toda a lista atual do plano de contas no formato Árvore (chama internamente o `GET`).
      parameters:
        - name: Type
          in: query
          required: false
          schema:
            type: string
            enum:
              - Tree
            default: Tree
          description: Formato da lista retornada na resposta. Default `Tree`.
      requestBody:
        required: true
        description: Mesmos campos do POST.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TypeAccountCreate'
      responses:
        '200':
          description: Plano atualizado. Retorna a lista completa do plano de contas (mesmo formato do `GET`).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeAccountTreeNode'
        '400':
          description: |-
            Erros de validação (prefixo `[BadRequest]`):
            - `Plano de contas não existe`
            - `Plano de contas superior não existe`
            - `Já existe um plano com o mesmo cód. referência externo`
            - `Já existe um plano com o mesmo cód. referência interno`
            - `IDTypeCategoryAccountPayble não existe`
            - `É preciso ter um plano de contas padrão para pedido`
            - `É preciso ter um plano de contas padrão para compras`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: typeAccountTypeDelete
      tags:
        - Tipos — Contas e Pagamento
      summary: Inativa um plano de contas
      description: >-
        Inativa o plano de contas (soft delete — define `Status=0` e zera `IDTypeAccountPaybleFather`).


        **Bloqueios**:

        - O plano não pode ter filhos ativos — é preciso remover os filhos primeiro.

        - O plano não pode estar referenciado em alguma parametrização da empresa do tipo **GNRE**
        (`GnreIDTypeAccountPayableReceivable`) — a parametrização precisa ser removida antes.


        A resposta retorna a lista atual do plano de contas (chama internamente o `GET` no formato lista plana).
      responses:
        '200':
          description: Exclusão bem-sucedida. Retorna a lista atual do plano de contas (formato lista plana, sem `Type`).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeAccountFlatItem'
        '400':
          description: |-
            Erros de validação (prefixo `[BadRequest]`):
            - `Plano de contas a receber/pagar não existe`
            - `Plano de contas esta na parametrização da empresa. Remover a parametrização antes de excluir o documento`
            - `Remover o plano de conta filho antes de excluir o pai`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/account/type/category:
    get:
      operationId: typeAccountCategoryList
      tags:
        - Tipos — Contas e Pagamento
      summary: Lista as categorias do plano de contas
      description: >-
        Retorna o catálogo fixo de categorias do plano de contas (`TypeAccountPaybleCategory`). Compartilhado por todas
        as empresas — não há filtro por empresa nem por tipo. Cada plano de contas raiz pode ser classificado em uma
        categoria; planos filhos herdam a categoria do pai.


        O identificador é devolvido como **string** para preservar zeros à esquerda em integrações.
      responses:
        '200':
          description: Lista de categorias, ordenada pela descrição.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeAccountCategoryListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/account/document:
    get:
      operationId: typeAccountDocumentList
      tags:
        - Tipos — Contas e Pagamento
      summary: Lista tipos de documento
      description: >-
        Retorna os tipos de documento ativos da empresa, ordenados pela descrição. Quando a empresa autenticada é a
        `all` (multi-conta), retorna os tipos de todas as empresas vinculadas.
      responses:
        '200':
          description: Lista de tipos de documento.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeDocumentListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: typeAccountDocumentPost
      tags:
        - Tipos — Contas e Pagamento
      summary: Cadastra um tipo de documento
      description: >-
        Cria um tipo de documento para a empresa autenticada. Após gravar, o a listagem para `/type/account/document` é
        invalidado. A resposta é a lista completa atualizada (formato de `GET /type/account/document`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TypeDocumentCreate'
        description: >-
          Dados do tipo de documento a cadastrar. `TypeDocument` é a descrição (ex.: `Nota Fiscal`, `Boleto`).
          `DefaultOrder` e `DefaultPurchase` marcam o tipo como padrão de pedido de venda e de compra, respectivamente.
      responses:
        '200':
          description: Tipo de documento criado. Devolve a lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeDocumentListItem'
        '400':
          description: 'Empresa não localizada. Mensagem: `[BadRequest] - Empresa não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/account/document/{idtypedocument}:
    parameters:
      - name: idtypedocument
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do tipo de documento.
    put:
      operationId: typeAccountDocumentPut
      tags:
        - Tipos — Contas e Pagamento
      summary: Atualiza um tipo de documento
      description: >-
        Atualiza descrição e flags de padrão (`DefaultOrder`, `DefaultPurchase`) de um tipo de documento existente. Os
        três campos são considerados em toda chamada — **não é atualização parcial**: enviar somente um deles
        sobrescreverá os outros com vazio/nulo. Após gravar, o a listagem para `/type/account/document` é invalidado. A
        resposta é a lista completa atualizada.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TypeDocumentUpdate'
        description: Atualiza os mesmos campos do POST (`TypeDocument`, `DefaultOrder`, `DefaultPurchase`).
      responses:
        '200':
          description: Tipo de documento atualizado. Devolve a lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeDocumentListItem'
        '400':
          description: 'Tipo de documento não encontrado para a empresa. Mensagem: `[BadRequest] - Tipo Documento não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: typeAccountDocumentDelete
      tags:
        - Tipos — Contas e Pagamento
      summary: Exclui (inativa) um tipo de documento
      description: >-
        Inativa o tipo de documento (`Status = 0`). Não exclui fisicamente o registro. A exclusão é **bloqueada** quando
        o tipo está referenciado na parametrização **Tipo de documento para criar contas a pagar GNRE operação** da
        integração GNRE — nesse caso é preciso primeiro trocar a parametrização. Após gravar, o a listagem é invalidado
        e a resposta é a lista completa atualizada.
      responses:
        '200':
          description: Tipo de documento inativado. Devolve a lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeDocumentListItem'
        '400':
          description: >-
            Tipo de documento não encontrado ou referenciado por parametrização. Mensagens: `[BadRequest] - Tipo
            documento não existe`; `[BadRequest] - Tipo documento esta na parametrização da empresa. Remover a
            parametrização antes de excluir o documento`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/order/status:
    get:
      operationId: typeOrderStatusList
      tags:
        - Tipos — Pedido
      summary: Lista os status de pedido da empresa
      description: >-
        Retorna a lista de **status de pedido** configurados para a empresa autenticada, com o nome editado
        (`StatusOrder`), a cor (`StatusColorCode`) e a descrição padrão do sistema (`StatusOrderDescription`). A lista
        de status é fixa no sistema (até 58 valores diferentes, abrangendo todo o ciclo do pedido — Aberto, Fechado,
        Picking, Packing, Enviado, Entregue, Cancelado, OS, Orçamento, etc.), e cada empresa pode renomear/colorir esses
        status mas não pode adicionar novos.


        A resposta vem ordenada por `Order` (posição do status no fluxo). O campo `IDStatusOrder` é devolvido como
        string (`CAST AS CHAR`).
      parameters:
        - name: ChangeOnCreate
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: >-
            Filtra apenas os status que podem ser usados como **status inicial** ao criar um pedido
            (`ChangeOnCreate=1`). Esses são, por exemplo: Aberto, Fechado, Enviado, Entregue, Em espera, A faturar, Nota
            Fiscal, Cancelado, Em devolução, Fulfillment e os status de OS.
      responses:
        '200':
          description: Lista de status do pedido configurados para a empresa.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeOrderStatusListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/order/status/{idstatusorder}:
    parameters:
      - name: idstatusorder
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: >-
          Identificador do status de pedido (fixo no sistema). Valores comuns: 0=Aberto, 1=Fechado, 2=Iniciado picking,
          3=Pré picking-list, 4=Finalizado picking, 5=Segurar pedido, 6=Aguardando expedição, 7=Enviado, 8=Entregue com
          sucesso, 9=Em espera, 21=A faturar, 90=Cancelado, 100=Deletado, etc.
    put:
      operationId: typeOrderStatusPut
      tags:
        - Tipos — Pedido
      summary: Atualiza o nome e a cor de um status de pedido
      description: >-
        Atualiza o **nome local** (`StatusOrder`) e a **cor** (`StatusColorCode`) que a empresa autenticada usa para o
        status. **Não é possível** criar status novos nem excluir os existentes — a tabela de status do sistema é fixa.
        A resposta é a lista atualizada de status (mesmo formato de `GET /type/order/status`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TypeOrderStatusUpdate'
        description: >-
          Atualiza a descrição e a cor do status do pedido para a empresa autenticada. `StatusOrder` é o nome amigável
          exibido na tela; `StatusColorCode` é a cor de destaque (formato hexadecimal `#RRGGBB`).
      responses:
        '200':
          description: Status atualizado. Retorna a lista de status atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeOrderStatusListItem'
        '400':
          description: 'Status não localizado na empresa. Mensagem: `[BadRequest] - Status pedido não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/order/type:
    get:
      operationId: typeOrderTypeList
      tags:
        - Tipos — Pedido
      summary: Lista tipos de pedido
      description: >-
        Retorna os tipos de pedido **ativos** (`Status=1`) da empresa autenticada, com a descrição amigável da política
        comercial, do faturador, do armazém padrão, do armazém de devolução, do tipo de retorno simbólico de
        armazenagem, do tipo de devolução, do plano de contas, do centro de custo e da finalidade da NFe. Ordenado por
        nome.


        Aceita filtros opcionais por: `EnableFrenteCaixa` (apenas tipos visíveis no PDV), `IDCompanyInvoice` (filtra
        pelo faturador), `ServiceRequest` (apenas tipos marcados como ordem de serviço) e `IsTransfer` (apenas tipos de
        transferência entre filiais).
      parameters:
        - name: EnableFrenteCaixa
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Quando `1`, traz apenas tipos com **Ativo frente de caixa = Sim**.
        - name: IDCompanyInvoice
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo faturador (filial) configurado no tipo de pedido.
        - name: ServiceRequest
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Quando `1`, traz apenas tipos marcados como **Ordem de Serviço**.
        - name: IsTransfer
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Quando `1`, traz apenas tipos de **transferência** entre filiais.
      responses:
        '200':
          description: Lista de tipos de pedido.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeOrderListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: orderTypeOrderPost
      tags:
        - Tipos — Pedido
      summary: Cadastra um tipo de pedido
      description: >-
        Cria um novo tipo de pedido. **Regras de unicidade**: cada empresa pode ter no máximo **um** tipo marcado como
        `Default=1`, `Resend=1`, `Return=1` e `SymbolicReturn=1` — ao salvar com qualquer um desses flags em `1`, o tipo
        anterior é automaticamente desmarcado.


        **Validações**: faturador (se diferente da própria conta) precisa ser uma filial; armazém (padrão e de
        devolução) precisa estar ativo na mesma empresa; tipo de pedido para retorno simbólico e tipo de pedido para
        devolução precisam existir na mesma empresa; plano de contas e centro de custo precisam pertencer à empresa;
        `TypeOrderOrderPriority` aceita `0`–`10`.


        A resposta retorna **a lista completa** de tipos de pedido da empresa (mesmo formato de `GET /type/order/type`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TypeOrderCreate'
        description: >-
          Dados do tipo de pedido a cadastrar. Cobre uma grande área de configuração: flags de uso (`Default`, `Resend`,
          `Return`, `SymbolicReturn` — cada uma, quando `1`, desmarca o tipo anteriormente marcado da empresa), prefixo
          do número do pedido (`OrderPrefix`), política comercial (`IDCompanySalesPolicy`), faturador padrão
          (`IDCompanyInvoice`), armazém padrão e de devolução
          (`IDStockKeepingUnitWarehouse`/`IDStockKeepingUnitWarehouseReturn`), comportamento de NF
          (`CreateBankSlipAfterInvoice`, `RecalculateAccountsDueDateAfterInvoice`, `BlockInvoiceToCompanySameDocument`,
          `IssueNFCe`, `TypeOrderNfeindFinal`, `TypeOrderNfeComments`, `InvoiceIntermedCNPJ`,
          `IncludeInboundInvoiceReferenceKey`, `CfopConsiderSymbolicStorageReturn`), regras de movimentação
          (`BalanceChange`, `IsTransfer`, `ServiceRequest`), regras comerciais (`MinimumMarkup`,
          `MaximumDiscountPerItem`, `BlockSkuZeroValue`, `SafetyStockPercent`, `AutomaticCancelOpenOrderAfterHour`,
          `OrderFinishConfirmation`, `ConsumerVoucherDefault`), cotação de frete (`CarrierQuotation`), prioridade WMS
          (`TypeOrderOrderPriority`, 0–10), e financeiro (`IDTypeAccountPayableReceivable`, `IDTypeCostCenter`).
          Existências de armazém, faturador, política comercial, tipo de pedido de devolução, plano de contas e centro
          de custo são validadas contra a empresa autenticada.
      responses:
        '200':
          description: Tipo criado. Retorna a lista completa atual de tipos de pedido.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeOrderListItem'
        '400':
          description: |-
            Erros de validação (prefixo `[BadRequest]`):
            - `Empresa não existe`
            - `Politica comercial não existe`
            - `Faturador não existe`
            - `Armazém não existe` / `Armazém devolução não existe`
            - `Tipo de pedido para retorno simbólico de armazenagem não localizado`
            - `Tipo de pedido de devolução não localizado`
            - `Plano de contas não existe`
            - `Centro de custo não existe`
            - `Prioridade pedido precisa ser entre 0 e 10`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/order/type/{idordertype}:
    parameters:
      - name: idordertype
        in: path
        required: true
        description: Identificador do tipo de pedido (`IDTypeOrder`).
        schema:
          type: integer
          format: int32
    get:
      operationId: orderTypeOrderGet
      tags:
        - Tipos — Pedido
      summary: Detalha um tipo de pedido
      description: >-
        Retorna o detalhe do tipo de pedido informado, **acrescido das regras fiscais** (`TypeOrderTax[]`) — uma entrada
        por departamento fiscal cadastrado para SKUs na empresa, com o vínculo opcional `IDTax` da regra fiscal aplicada
        ao tipo de pedido.


        Quando o id não existe ou pertence a outra empresa, devolve `[]` em status `200`.
      responses:
        '200':
          description: Tipo encontrado (array com 1 item) ou `[]` quando não encontrado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeOrderDetail'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    put:
      operationId: orderTypeOrderPut
      tags:
        - Tipos — Pedido
      summary: Atualiza um tipo de pedido
      description: |-
        Atualiza o tipo de pedido. As mesmas regras de unicidade e validação do POST valem.

        A resposta retorna **a lista completa** de tipos de pedido da empresa (mesmo formato de `GET /type/order/type`).
      requestBody:
        required: true
        description: Mesmo formato do POST.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TypeOrderCreate'
      responses:
        '200':
          description: Tipo atualizado. Retorna a lista completa atual de tipos de pedido.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeOrderListItem'
        '400':
          description: |-
            Mesmas validações do POST. Mensagens possíveis:
            - `Tipo pedido não existe`
            - `Politica comercial não existe`
            - `Faturador não existe`
            - `Armazém não existe` / `Armazém devolução não existe`
            - `Tipo de pedido para retorno simbólico de armazenagem não localizado`
            - `Tipo de pedido de devolução não localizado`
            - `Plano de contas não existe`
            - `Centro de custo não existe`
            - `Prioridade pedido precisa ser entre 0 e 10`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: orderTypeOrderDelete
      tags:
        - Tipos — Pedido
      summary: Inativa um tipo de pedido
      description: >-
        Inativa o tipo de pedido (soft delete — `Status=0`). Antes de inativar, remove **todas** as regras fiscais
        (`TypeOrderTax`) vinculadas a este tipo.


        **Bloqueios**:

        - Tipo já usado em pedidos (`Orders`).

        - Tipo configurado como **de/para de armazém** em `HubWarehouse`.

        - Tipo configurado como **de/para de política comercial** em `HubSalesPolicy`.

        - Tipo atrelado a uma **conta bancária** (`IDTypeOrder`).

        - Tipo referenciado por outro tipo como **retorno simbólico de armazenagem**
        (`IDTypeOrderSymbolicStorageReturn`).

        - Tipo referenciado por outro tipo como **devolução padrão** (`IDTypeOrderDefaultReturn`) — apenas se o outro
        tipo ainda está ativo.


        A resposta retorna a lista completa atual (chama internamente o `GET`).
      responses:
        '200':
          description: Tipo inativado. Retorna a lista completa atual de tipos de pedido.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeOrderListItem'
        '400':
          description: >-
            Erros de validação (prefixo `[BadRequest]`):

            - `Tipo pedido não existe`

            - `Tipo de pedido já tem pedido criado e não pode ser excluído`

            - `Tipo de pedido tem de/para de armazém e não pode ser excluído`

            - `Tipo de pedido tem de/para de política comercial e não pode ser excluído`

            - `Tipo de pedido  esta atrelado a conta bancária e não pode ser excluído`

            - `Tipo de pedido esta atrelado a tipo de pedido retorno simbólico armazenagem no tipo de pedido
            <descrição>`

            - `Tipo de pedido esta atrelado como tipo de pedido de devolução padrão no tipo de pedido <descrição>`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/order/payment:
    get:
      operationId: typeOrderPaymentList
      tags:
        - Tipos — Pedido
      summary: Lista tipos de pagamento
      description: >-
        Retorna os tipos de pagamento ativos da empresa, ordenados por descrição. Cada item traz a categoria (cartão de
        crédito, débito, Pix, boleto, dinheiro, vale, etc.) e a bandeira (`NfTBand`) quando a categoria exige uma —
        categorias `1` (cartão de crédito) e `6` (cartão de débito) sempre vêm com bandeira.
      parameters:
        - name: EnableFrenteCaixa
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Filtra apenas tipos habilitados (1) ou não habilitados (0) para frente de caixa.
      responses:
        '200':
          description: Lista de tipos de pagamento ativos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypePaymentListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: typeOrderPaymentPost
      tags:
        - Tipos — Pedido
      summary: Cadastra um tipo de pagamento
      description: >-
        Cria um tipo de pagamento na empresa autenticada. Quando `Category` for `1` (cartão de crédito) ou `6` (cartão
        de débito), o campo `NfTBand` é obrigatório e precisa existir na tabela de bandeiras suportadas. A resposta é a
        lista atualizada de tipos de pagamento.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TypePaymentCreate'
        description: >-
          Dados do tipo de pagamento a cadastrar. `TypePaymentDescription` é o nome amigável. `Category` agrupa
          pagamentos para apuração. `DaysDue` é o prazo padrão (em dias) usado para gerar a data de vencimento das
          contas. `DefaultOrder`/`DefaultPurchase` marcam o tipo como padrão de pedido de venda/compra. `NfTBand`,
          quando informada, define a bandeira reportada na NFe e é validada contra `NfTBand`. `EnableFrenteCaixa=1`
          habilita o tipo no PDV. `IncludeComission=1` (default) inclui o pagamento no cálculo de comissão.
      responses:
        '200':
          description: Tipo criado. Retorna a lista atualizada (mesmo formato de `GET /type/order/payment`).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypePaymentListItem'
        '400':
          description: |-
            Erros de validação (prefixo `[BadRequest]`):
            - `Company não existe`
            - `Bandeira não existe`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/order/payment/{idtypepayment}:
    parameters:
      - name: idtypepayment
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do tipo de pagamento.
    put:
      operationId: typeOrderPaymentPut
      tags:
        - Tipos — Pedido
      summary: Atualiza um tipo de pagamento
      description: >-
        Substitui o cadastro do tipo de pagamento. **Atualização total** — todos os campos do corpo são gravados (campos
        omitidos viram `null` ou recebem o default do endpoint). A resposta é a lista atualizada de tipos de pagamento.
        Mesma regra de `NfTBand` obrigatório quando `Category` é `1` ou `6`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TypePaymentCreate'
        description: >-
          Atualiza o tipo de pagamento. Mesmos campos do POST: `TypePaymentDescription`, `Category`, `DaysDue`,
          `DefaultOrder`, `DefaultPurchase`, `NfTBand`, `EnableFrenteCaixa`, `IncludeComission`. Quando `NfTBand` muda,
          é validada contra `NfTBand`.
      responses:
        '200':
          description: Tipo atualizado. Retorna a lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypePaymentListItem'
        '400':
          description: |-
            Erros de validação (prefixo `[BadRequest]`):
            - `Tipo pagamento não existe`
            - `Bandeira não existe`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: typeOrderPaymentDelete
      tags:
        - Tipos — Pedido
      summary: Exclui (inativa) um tipo de pagamento
      description: >-
        Marca o tipo de pagamento como inativo (`Status=0`); o registro não é apagado fisicamente. A resposta é a lista
        de tipos ativos atualizada.
      responses:
        '200':
          description: Tipo inativado. Retorna a lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypePaymentListItem'
        '400':
          description: 'Tipo não localizado. Mensagem: `[BadRequest] - Tipo Pagamento não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/order/payment/{idtypepayment}/rate:
    parameters:
      - name: idtypepayment
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do tipo de pagamento.
    get:
      operationId: typeOrderPaymentRateGet
      tags:
        - Tipos — Pedido
      summary: Lista as taxas adquirentes do tipo de pagamento
      description: >-
        Retorna a lista de taxas (MDR + AR ou taxa fixa) vinculadas ao tipo de pagamento, com os identificadores e
        descrições resolvidas da integração e do método de pagamento do adquirente (`TypePayment`). Cada item descreve
        uma combinação de **integração adquirente** + **método de pagamento (bandeira/modalidade)** + **faixa de
        parcelas** + **vigência**, com a taxa correspondente.
      responses:
        '200':
          description: Lista de taxas adquirentes.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypePaymentRateItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: typeOrderPaymentRatePost
      tags:
        - Tipos — Pedido
      summary: Cadastra uma taxa adquirente para o tipo de pagamento
      description: >-
        Cria uma combinação de integração + método de pagamento + faixa de parcelas + vigência, com a taxa
        correspondente. O sistema bloqueia o salvamento quando já existe outra taxa cobrindo a mesma faixa de parcelas
        em um período sobreposto com a mesma integração — a mensagem indica em qual tipo de pagamento a colisão
        acontece. Taxas negativas (`FixedRate`, `MerchantDiscountRate` ou `AnticipationRate < 0`) também são rejeitadas.
        A resposta é a lista atualizada de taxas do tipo de pagamento.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TypePaymentRateCreate'
        description: >-
          Combinação adquirente + método + faixa de parcelas + vigência com a taxa cobrada nesse cenário. Pode ser **MDR
          + AR** (deixe `FixedRate=0`) ou **taxa fixa** (deixe `MerchantDiscountRate=0` e `AnticipationRate=0`). Taxas
          negativas são rejeitadas. `MinInstallment` ≤ `MaxInstallment`. `IDCompanyIntegration` e `IDTypePaymentFrom`
          (combinação bandeira + modalidade do adquirente) são obrigatórios e validados contra `TypeAcquirerPayment` +
          `CompanyIntegration` da empresa (categoria adquirente). A combinação (faixa de parcelas + vigência) não pode
          sobrepor com outra taxa já cadastrada.
      responses:
        '200':
          description: Taxa criada. Retorna a lista atualizada (mesmo formato de `GET /type/order/payment/{idtypepayment}/rate`).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypePaymentRateItem'
        '400':
          description: >-
            Erros de validação (prefixo `[BadRequest]`):

            - `Taxas não podem ter valor negativo`

            - `Empresa não existe`

            - `Integração obrigatório`

            - `Integração não existe`

            - `Método de pagamento obrigatório`

            - `O mínimo de parcelas não pode ser maior que o máximo de parcelas`

            - `Já existe uma taxa com a mesma quantidade de parcela e data de vigência`

            - `Já existe uma taxa com a mesma quantidade de parcela e data de vigência para o tipo de pagamento código:
            <id>`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/order/payment/{idtypepayment}/rate/{idtypepaymentrate}:
    parameters:
      - name: idtypepayment
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do tipo de pagamento.
      - name: idtypepaymentrate
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador da taxa adquirente.
    put:
      operationId: typeOrderPaymentRatePut
      tags:
        - Tipos — Pedido
      summary: Atualiza uma taxa adquirente
      description: >-
        Atualização **parcial** — apenas os campos enviados no corpo são alterados. Mesmas regras de sobreposição e
        taxas negativas do `POST`. A resposta é a lista atualizada de taxas do tipo de pagamento.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TypePaymentRateUpdate'
        description: >-
          Atualização parcial da taxa — apenas os campos enviados são alterados. Mantém as regras do POST: taxas não
          negativas, faixa de parcelas válida, vigência sem sobreposição com outras taxas da mesma integração.
      responses:
        '200':
          description: Taxa atualizada. Retorna a lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypePaymentRateItem'
        '400':
          description: >-
            Erros de validação (prefixo `[BadRequest]`):

            - `Taxas não podem ter valor negativo`

            - `Tipo taxa pagamento não existe`

            - `Integração obrigatório`

            - `Integração não existe`

            - `Método de pagamento obrigatório`

            - `O mínimo de parcelas não pode ser maior que o máximo de parcelas`

            - `Já existe uma taxa com a mesma quantidade de parcela e data de vigência`

            - `Já existe uma taxa com a mesma quantidade de parcela e data de vigência para o tipo de pagamento código:
            <id>`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: typeOrderPaymentRateDelete
      tags:
        - Tipos — Pedido
      summary: Exclui uma taxa adquirente
      description: Apaga fisicamente a taxa (não é exclusão lógica). A resposta é a string `"sucesso"`.
      responses:
        '200':
          description: Taxa excluída. Retorna a string `"sucesso"`.
          content:
            application/json:
              schema:
                type: string
                enum:
                  - sucesso
        '400':
          description: 'Taxa ou tipo de pagamento não encontrados. Mensagem: `[BadRequest] - Tipo taxa de pagamento não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/account/cost-center:
    get:
      operationId: typeAccountCostCenterList
      tags:
        - Tipos — Contas e Pagamento
      summary: Lista centros de custo
      description: >-
        Retorna os centros de custo ativos da empresa, ordenados por descrição. Cada item traz a descrição, o código
        externo opcional (usado para casar com sistemas terceiros — ERP contábil, integração de governança) e o
        subdomínio da empresa.
      responses:
        '200':
          description: Lista de centros de custo ativos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeCostCenterListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: typeAccountCostCenterPost
      tags:
        - Tipos — Contas e Pagamento
      summary: Cadastra um centro de custo
      description: >-
        Cria um centro de custo na empresa autenticada. Quando `ExternalCode` for informado, o sistema bloqueia o
        cadastro se já existir outro centro de custo ativo na mesma empresa com o mesmo código externo. A resposta é a
        lista atualizada de centros de custo.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TypeCostCenterCreate'
        description: >-
          Dados do centro de custo a cadastrar. `TypeCostCenter` (descrição) obrigatório. `ExternalCode`, quando
          informado, precisa ser único na empresa entre os centros ativos.
      responses:
        '200':
          description: Centro criado. Retorna a lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeCostCenterListItem'
        '400':
          description: |-
            Erros de validação (prefixo `[BadRequest]`):
            - `Empresa não existe`
            - `Já existe um centro de custo com este código externo`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/account/cost-center/{idtypecostcenter}:
    parameters:
      - name: idtypecostcenter
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do centro de custo.
    put:
      operationId: typeAccountCostCenterPut
      tags:
        - Tipos — Contas e Pagamento
      summary: Atualiza um centro de custo
      description: >-
        Atualiza a descrição e o código externo do centro de custo. Quando `ExternalCode` mudar, o sistema aplica a
        mesma checagem de duplicidade do `POST`. A resposta é a lista atualizada.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TypeCostCenterCreate'
        description: >-
          Atualiza descrição e/ou `ExternalCode` do centro de custo. `ExternalCode` mantém a regra de unicidade na
          empresa.
      responses:
        '200':
          description: Centro atualizado. Retorna a lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeCostCenterListItem'
        '400':
          description: |-
            Erros de validação (prefixo `[BadRequest]`):
            - `Centro de custo não existe`
            - `Já existe um centro de custo com este código externo`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: typeAccountCostCenterDelete
      tags:
        - Tipos — Contas e Pagamento
      summary: Exclui (inativa) um centro de custo
      description: >-
        Marca o centro de custo como inativo (`Status=0`). O registro não é apagado fisicamente — rateios e títulos
        antigos continuam apontando para ele, mas o centro não aparece mais nas listas e seletores. A resposta é a lista
        atualizada de centros ativos.
      responses:
        '200':
          description: Centro inativado. Retorna a lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeCostCenterListItem'
        '400':
          description: 'Centro não localizado. Mensagem: `[BadRequest] - Centro de custo não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /purchase/cfop-inbound:
    get:
      operationId: purchaseCfopInboundList
      tags:
        - DE-PARA CFOP Recebimento
      summary: Lista regras DE-PARA de CFOP de recebimento
      description: >-
        Retorna todos os pares CFOP origem → CFOP destino cadastrados para a empresa, ordenados pelo CFOP de origem.
        Cada item já vem com a descrição de cada CFOP. Quando a empresa autenticada é a `all` (multi-conta), retorna as
        regras de todas as empresas vinculadas.
      responses:
        '200':
          description: Lista de regras DE-PARA.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PurchaseCfopInboundListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: purchaseCfopInboundPost
      tags:
        - DE-PARA CFOP Recebimento
      summary: Cadastra uma regra DE-PARA de CFOP
      description: >-
        Cria uma regra para a empresa autenticada. Valida que `CfopFrom` e `CfopTo` existem no catálogo nacional de
        CFOPs e que o par ainda não foi cadastrado para a empresa (a tabela tem chave única em `CfopFrom + CfopTo +
        IDCompany`). A resposta é a **lista completa atualizada** das regras da empresa.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseCfopInboundCreate'
        description: >-
          Dados da regra de conversão de CFOP no recebimento. Obrigatorio enviar `CfopFrom` (CFOP de origem) e `CfopTo`
          (CFOP de destino); ambos precisam existir na tabela de CFOPs e a combinação não pode estar duplicada para a
          empresa.
      responses:
        '200':
          description: Regra criada. Devolve a lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PurchaseCfopInboundListItem'
        '400':
          description: >-
            Erros de validação. Mensagens possíveis: `[BadRequest] - Esta regra já existe e não será adicionada
            novamente`; `[BadRequest] - CFOP de origem <X> não existe`; `[BadRequest] - CFOP de destino <X> não existe`;
            `[BadRequest] - Empresa não existe`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /purchase/cfop-inbound/{idstockkeepingunitpurchasecfopinbound}:
    parameters:
      - name: idstockkeepingunitpurchasecfopinbound
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador da regra DE-PARA.
    put:
      operationId: purchaseCfopInboundPut
      tags:
        - DE-PARA CFOP Recebimento
      summary: Atualiza uma regra DE-PARA
      description: >-
        Atualiza o par `CfopFrom`/`CfopTo` de uma regra existente. Ambos os campos são considerados em toda chamada (não
        é atualização parcial). Aplica as mesmas validações do POST: os CFOPs precisam existir no catálogo nacional e o
        novo par não pode colidir com outra regra da empresa. A resposta é a lista completa atualizada.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseCfopInboundUpdate'
        description: >-
          Novos valores da regra de conversão de CFOP. Enviar `CfopFrom` e `CfopTo`; ambos precisam existir e a
          combinação não pode coincidir com outra regra já cadastrada na empresa.
      responses:
        '200':
          description: Regra atualizada. Devolve a lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PurchaseCfopInboundListItem'
        '400':
          description: >-
            Erros de validação. Mensagens possíveis: `[BadRequest] - De/Para de CFOP não existe`; `[BadRequest] - Esta
            regra já existe e não será adicionada novamente`; `[BadRequest] - CFOP de origem <X> não existe`;
            `[BadRequest] - CFOP de destino <X> não existe`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: purchaseCfopInboundDelete
      tags:
        - DE-PARA CFOP Recebimento
      summary: Exclui uma regra DE-PARA
      description: >-
        **Remove fisicamente** o registro (não é exclusão lógica). Não há regra de bloqueio: a exclusão é sempre
        permitida quando a regra pertence à empresa. A resposta é a lista completa atualizada.
      responses:
        '200':
          description: Regra excluída. Devolve a lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PurchaseCfopInboundListItem'
        '400':
          description: 'Regra não encontrada. Mensagem: `[BadRequest] - De/Para de CFOP não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /company/sales-policy:
    get:
      operationId: companySalesPolicyGet
      tags:
        - Políticas Comerciais
      summary: Lista políticas comerciais
      description: >-
        Retorna as políticas comerciais (tabelas de preço) cadastradas pela empresa, ordenadas por nome. Cada item traz
        o tipo da política (`TypeCompanySalesPolicy` — Normal / Custo médio / Relativa), o nome da política base
        (`CompanySalesPolicyFrom`, quando é uma política relativa), o tipo de operação
        (`TypeCompanySalesPolicyOperation` — Multiplicação ou Soma), o valor da operação e o markup configurado.
      parameters:
        - name: IDCompanySalesPolicy
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por identificador único da política comercial.
        - name: IDTypeCompanySalesPolicy
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 3
          description: 'Filtra por tipo de política: 1=Normal, 2=Custo médio, 3=Relativa à outra política.'
      responses:
        '200':
          description: Lista de políticas comerciais da empresa.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanySalesPolicyListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: companySalesPolicyPost
      tags:
        - Políticas Comerciais
      summary: Cadastra uma política comercial
      description: >-
        Cria uma política comercial na empresa autenticada. Regras:


        - Quando `IDTypeCompanySalesPolicy=3` (Relativa), `IDCompanySalesPolicyFrom`,
        `IDTypeCompanySalesPolicyOperation` e `OperationValue` são **obrigatórios**.

        - A política base (`IDCompanySalesPolicyFrom`) **não pode** ser do tipo Relativa (3) — só Normal ou Custo médio
        podem servir de base. Isso evita cadeias de políticas relativas.

        - Quando `Default=1`, o sistema **desmarca** automaticamente a política padrão anterior, garantindo que sempre
        haja exatamente uma política padrão por empresa.

        - `IDTypeCompanySalesPolicy` default = `1` (Normal) quando omitido.


        A resposta é o detalhe da política recém-criada (mesmo formato de `GET
        /company/sales-policy?IDCompanySalesPolicy=<novo>`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanySalesPolicyCreate'
        description: >-
          Dados da política comercial a cadastrar. Obrigatório `CompanySalesPolicy` (nome). Campos opcionais: `Default`
          (1 marca como padrão e desmarca a anterior), `CostAverage`, `Markup`, `IDTypeCompanySalesPolicy` (1 = comum, 2
          = atacado, 3 = relativa — quando 3, exige `IDCompanySalesPolicyFrom`, `IDTypeCompanySalesPolicyOperation` e
          `OperationValue`), `IDCompanySalesPolicyFrom`, `PriceRounding`, `IDTypeCompanySalesPolicyOperation` e
          `OperationValue`.
      responses:
        '200':
          description: Política criada. Retorna o detalhe da política recém-cadastrada (array com 1 item).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanySalesPolicyListItem'
                maxItems: 1
        '400':
          description: >-
            Erros de validação (prefixo `[BadRequest]`):

            - `Para política do tipo relativa, obrigatório o preenchimento do tipo operação, política comercial base e
            valor da operação`

            - `Empresa não existe`

            - `Tipo política comercial não existe`

            - `Política comercial base não existe`

            - `Tipo operação não existe`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /company/sales-policy/{idcompanysalespolicy}:
    parameters:
      - name: idcompanysalespolicy
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador da política comercial.
    put:
      operationId: companySalesPolicyPut
      tags:
        - Políticas Comerciais
      summary: Atualiza uma política comercial
      description: >-
        Atualiza uma política comercial. Atenção: apenas o nome `CompanySalesPolicy` e a marca padrão `Default` são
        aplicados parcialmente (só mudam quando enviados); os demais campos são sempre regravados e, quando omitidos,
        voltam ao padrão (`IDTypeCompanySalesPolicy`→1 Normal, `CostAverage`→0,
        `Markup`/`IDCompanySalesPolicyFrom`/`IDTypeCompanySalesPolicyOperation`/`OperationValue`/`PriceRounding`→nulo),
        o que reverte o tipo para Normal e zera a configuração de política Relativa — por isso, envie a configuração
        completa a cada atualização. Regras:


        - Quando `IDTypeCompanySalesPolicy=3` (Relativa), `IDCompanySalesPolicyFrom`,
        `IDTypeCompanySalesPolicyOperation` e `OperationValue` são **obrigatórios**.

        - A política base não pode ser do tipo Relativa.

        - Quando `Default=1`, o sistema desmarca a política padrão anterior. Quando `Default=0`, o sistema **bloqueia**
        o salvamento se essa for a única política padrão da empresa — com a mensagem `É preciso ter uma politica
        comercial padrão`.

        - **Recálculo de preços**: quando o tipo final da política for Relativa, os preços de venda vigentes vinculados
        a ela (com vigência que inclui a data atual) são recalculados de forma assíncrona com base na nova política base
        e operação; a API responde imediatamente.


        A resposta é o detalhe atualizado da política (array com 1 item).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanySalesPolicyUpdate'
        description: >-
          Campos da política comercial a atualizar — apenas os enviados são aplicados. Aceita `CompanySalesPolicy`,
          `Default`, `CostAverage`, `Markup`, `IDTypeCompanySalesPolicy`, `IDCompanySalesPolicyFrom`, `PriceRounding`,
          `IDTypeCompanySalesPolicyOperation` e `OperationValue`. Para `IDTypeCompanySalesPolicy = 3` (relativa) os
          campos de operação e política base são obrigatórios; tirar a marca padrão exige que outra política já esteja
          como padrão.
      responses:
        '200':
          description: Política atualizada. Retorna o detalhe atualizado (array com 1 item).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanySalesPolicyListItem'
                maxItems: 1
        '400':
          description: >-
            Erros de validação (prefixo `[BadRequest]`):

            - `Politica comercial não existe`

            - `Para política do tipo relativa, obrigatório o preenchimento do tipo operação, política comercial base e
            valor da operação`

            - `É preciso ter uma politica comercial padrão`

            - `Tipo política comercial não existe`

            - `Política comercial base não existe`

            - `Tipo operação não existe`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: companySalesPolicyDelete
      tags:
        - Políticas Comerciais
      summary: Exclui uma política comercial
      description: >-
        **Exclusão física** — a política é apagada definitivamente do banco. O sistema bloqueia a exclusão em cinco
        situações:


        1. A política é a **padrão** (`Default=1`) — defina outra como padrão antes.

        2. Existem **preços vinculados** a ela em `StockKeepingUnitPricing`.

        3. Existem **de/para de canal de venda** em `HubSalesPolicy` apontando para ela como destino.

        4. Existem **tipos de pedido** em `TypeOrder` configurados para usar essa política como padrão.

        5. Existem **promoções de PDV** em `StockKeepingUnitPromotionSalesPolicies` vinculadas.


        A resposta em sucesso é a lista atualizada de políticas (mesmo formato de `GET /company/sales-policy`).
      responses:
        '200':
          description: Política excluída. Retorna a lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanySalesPolicyListItem'
        '400':
          description: |-
            Bloqueios de exclusão (prefixo `[BadRequest]`):
            - `Politica comercial não existe`
            - `Precisa definir outra política comercial padrão antes de deletar`
            - `Existem preços vinculados a essa politica comercial`
            - `Existem de/para vinculados a essa politica comercial`
            - `Existem tipos de pedido vinculados a essa politica comercial`
            - `Existem promoções PDV vinculadas a essa politica comercial`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /company:
    get:
      operationId: companyGet
      tags:
        - Minha Empresa
      summary: Detalha a empresa autenticada
      description: >-
        Retorna o cadastro completo da empresa identificada pelo subdomínio (`AccountName`) usado na chamada — todos os
        campos do cadastro da empresa mais os dados agregados: descrição do regime tributário (CRT), URL do logotipo
        (com sufixo `-thumbnail`), id da integração NFe/NFSe principal (`IDCompanyIntegration` com
        `IDTypeCompanyIntegration=16`), array de inscrições estaduais em `StateInscription` e array de créditos do
        Simples Nacional em `CompanySimplesCred`.


        O campo `CertificadoPassword` é sempre retornado como `null` (a senha do certificado nunca é exposta pela API).
      responses:
        '200':
          description: Cadastro da empresa.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyDetail'
                maxItems: 1
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    put:
      operationId: companyPut
      tags:
        - Minha Empresa
      summary: Atualiza a empresa autenticada
      description: >-
        Atualização parcial — apenas os campos enviados são alterados. Regras de validação:


        - `NfeSerie` e `NfceSerie` não podem ser maiores que 999.

        - Quando `NfeSerie` muda, todas as notas pendentes (`IDStatusInvoice IN (0,1)`) da série anterior, modelo 55,
        têm o flag `Main` zerado.

        - Quando `NfceSerie` muda, mesma regra para modelo 65.

        - Quando `CompanyAddressPostalCode` muda, o sistema consulta o CEP novo e atualiza o
        `CompanyAddressIbgeCityCode` automaticamente (a menos que tenha sido informado no body).

        - Quando `CteFeedStatus=1`, o sistema bloqueia se já existe outra empresa com o **mesmo CNPJ** e CTe ativo (a
        feature de CTe não suporta duas empresas com mesmo CNPJ).


        A cada alteração, o sistema gera um log em `CompanyLog` com os campos alterados (DE → PARA) e devolve o cadastro
        completo atualizado.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyUpdate'
        description: >-
          Campos da empresa autenticada a atualizar. Atualização parcial — apenas os campos enviados são alterados; os
          demais permanecem com o valor atual. Quando `CompanyAddressPostalCode` muda, o sistema recalcula
          `CompanyAddressIbgeCityCode`.
      responses:
        '200':
          description: Cadastro atualizado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyDetail'
                maxItems: 1
        '400':
          description: |-
            Erros de validação (prefixo `[BadRequest]`):
            - `Serie NFe não pode ser maior que 999`
            - `Serie NFCe não pode ser maior que 999`
            - `Empresa não existe`
            - `CNPJ já tem recurso de CTe ativo e não pode estar em duas empresas com mesmo CNPJ`
            - `erro consultar cep` (quando o CEP novo é inválido)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /company/branch:
    get:
      operationId: companyBranchGet
      tags:
        - Minha Empresa
      summary: Lista a empresa-matriz e suas filiais
      description: >-
        Retorna a empresa-matriz autenticada e a lista de **filiais** vinculadas a ela via `CompanyMain` (que aponta
        para a matriz). A resposta traz os campos principais da matriz e um array `Branch[]` com os dados das filiais
        (id, subdomínio, CNPJ, razão social, nome fantasia, logo, certificado, série NFe/NFCe, regime tributário).
      responses:
        '200':
          description: Dados da matriz + lista de filiais.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyBranchResponse'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /company/company-logo:
    post:
      operationId: companyLogoPost
      tags:
        - Minha Empresa
      summary: Sobe ou troca o logotipo da empresa
      description: >-
        Aceita duas formas de envio do logotipo:


        - **Upload multipart** (`multipart/form-data` com campo `file`) — sobe o arquivo direto do cliente.

        - **URL externa** (`application/json` com `{ "Url": "..." }`) — o sistema baixa a imagem da URL informada e
        grava no S3.


        A imagem é salva no bucket público do idworks (`https://public.idworks.com.br/Image/<accountname>_<uuid>.<ext>`)
        e o campo `CompanyLogoUrl` é atualizado. Resposta é um status HTTP — `200` em sucesso (corpo vazio), `404` se a
        empresa não existe, `400` quando a URL externa não retorna a imagem.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: Arquivo de imagem (PNG/JPG).
          application/json:
            schema:
              type: object
              required:
                - Url
              properties:
                Url:
                  type: string
                  format: uri
                  description: URL pública de onde o sistema deve baixar a imagem.
        description: >-
          Logotipo da empresa. Aceita duas formas: (a) upload `multipart/form-data` com o arquivo no campo padrão do
          formulário; (b) corpo JSON com `{ "url": "https://..." }` — o sistema baixa a imagem da URL informada. O
          arquivo é gravado no bucket público da empresa e o `CompanyLogoUrl` (mais o `CompanyLogoUrlThumbnail`) é
          atualizado no cadastro.
      responses:
        '200':
          description: Logotipo aplicado (corpo vazio).
          content: {}
        '400':
          description: 'Falha ao baixar imagem da URL informada. Mensagem: `[BadRequest] - erro ao baixar imagem`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '404':
          description: Empresa não encontrada (corpo vazio).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /company/state-inscription:
    post:
      operationId: companyStateInscriptionPost
      tags:
        - Minha Empresa
      summary: Adiciona uma inscrição estadual
      description: >-
        Cria uma inscrição estadual (IE) vinculada à empresa. Regras:


        - A inscrição é validada com o algoritmo oficial por UF (pacote `ie`). Quando inválida, o salvamento é
        bloqueado.

        - Para Minas Gerais (`State=MG`), o sistema faz padding com zeros à esquerda até 13 dígitos.

        - A inscrição não pode duplicar entre estados na mesma empresa.

        - A empresa só pode ter **uma** inscrição por estado.


        A resposta é o detalhe atualizado da empresa (mesmo formato de `GET /company`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyStateInscriptionCreate'
        description: >-
          Dados da inscrição estadual a cadastrar para a empresa. Apenas `State` e `StateInscription` são obrigatórios.
          A inscrição é validada com o algoritmo oficial da UF e cada empresa pode ter no máximo uma inscrição por UF.
      responses:
        '200':
          description: Inscrição adicionada. Retorna o detalhe atualizado da empresa.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyDetail'
                maxItems: 1
        '400':
          description: |-
            Erros de validação (prefixo `[BadRequest]`):
            - `Empresa não existe`
            - `Inscrição estadual não é válida`
            - `Inscrição estadual já adicionada no estado <UF>`
            - `Estado já tem configuração`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /company/state-inscription/{idstateinscription}:
    parameters:
      - name: idstateinscription
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador da inscrição estadual (`IDCompanyStateInscription`).
    put:
      operationId: companyStateInscriptionPut
      tags:
        - Minha Empresa
      summary: Atualiza uma inscrição estadual
      description: >-
        Atualização total — todos os campos do corpo são gravados. Mesmas regras de validação do `POST` (algoritmo
        oficial por UF, padding MG, unicidade por estado).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyStateInscriptionCreate'
        description: >-
          Atualização total da inscrição estadual — todos os campos do corpo são gravados (sobrescreve o cadastro).
          Mantém as mesmas validações do `POST`.
      responses:
        '200':
          description: Inscrição atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyDetail'
                maxItems: 1
        '400':
          description: |-
            Erros (prefixo `[BadRequest]`):
            - `Inscrição estadual não existe`
            - `Inscrição estadual não é válida`
            - `Inscrição estadual já adicionada no estado <UF>`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: companyStateInscriptionDelete
      tags:
        - Minha Empresa
      summary: Remove uma inscrição estadual
      description: Apaga fisicamente a inscrição estadual. A resposta é o detalhe atualizado da empresa.
      responses:
        '200':
          description: Inscrição removida.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyDetail'
                maxItems: 1
        '400':
          description: 'Inscrição não localizada. Mensagem: `[BadRequest] - State Inscription não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /company/simples-cred:
    post:
      operationId: companySimplesCredPost
      tags:
        - Minha Empresa
      summary: Cadastra créditos do Simples Nacional para um período
      description: >-
        Cria um registro de crédito do Simples Nacional para um mês/ano (`MonthYear`). O sistema converte a data para o
        primeiro dia do mês (`MonthYear`) e último dia do mês (`MonthYearTo`) automaticamente. Um período só pode ter um
        registro — duplicidade é bloqueada.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanySimplesCredCreate'
        description: Dados do crédito do Simples Nacional a registrar para um período (mês/ano).
      responses:
        '200':
          description: Crédito cadastrado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyDetail'
                maxItems: 1
        '400':
          description: |-
            Erros (prefixo `[BadRequest]`):
            - `Company não existe`
            - `Já existe configuração para este periodo`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /company/simples-cred/{idcompanysimplescred}:
    parameters:
      - name: idcompanysimplescred
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do crédito do Simples.
    put:
      operationId: companySimplesCredPut
      tags:
        - Minha Empresa
      summary: Atualiza créditos do Simples Nacional
      description: Atualização total — todos os campos do corpo são gravados. Mesma regra de unicidade por período do `POST`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanySimplesCredCreate'
        description: Atualização total do crédito do Simples Nacional — todos os campos do corpo são gravados.
      responses:
        '200':
          description: Crédito atualizado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyDetail'
                maxItems: 1
        '400':
          description: |-
            Erros (prefixo `[BadRequest]`):
            - `IDCompanySimplesCred não existe`
            - `Já existe configuração para este periodo`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: companySimplesCredDelete
      tags:
        - Minha Empresa
      summary: Remove um crédito do Simples Nacional
      description: Apaga fisicamente o registro de crédito. A resposta é o detalhe atualizado da empresa.
      responses:
        '200':
          description: Crédito removido.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyDetail'
                maxItems: 1
        '400':
          description: 'Crédito não localizado. Mensagem: `[BadRequest] - IDCompanySimplesCred não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /company/certificate:
    post:
      operationId: companyCertificatePost
      tags:
        - Minha Empresa
      summary: Importa o certificado digital da empresa
      description: >-
        Importa um arquivo de certificado digital A1 (`.pfx`) com a senha informada. O arquivo é enviado como
        `multipart/form-data` no campo `certificado` e a senha vai na query `Password`. O sistema valida o certificado,
        confere que o CNPJ do certificado bate com o da empresa (8 primeiros dígitos), extrai a data de validade
        (`CertificadoBestBeforeDate`) e o emissor (`CertificadoIssuer1`/`CertificadoIssuer2`) e o armazena de forma
        segura para uso na assinatura de notas fiscais (NFe/NFCe/NFSe/CTe).


        **Erros possíveis:** `O arquivo não esta no formato .pfx`; `Não foi possivel ler o certificado, verificar
        senha`; `Certificado inválido: não foi possível extrair o CNPJ do certificado`; `CNPJ do certificado (<cnpj>)
        diferente do CNPJ da empresa (<cnpj>)`.
      responses:
        '200':
          description: Certificado importado.
        '400':
          description: Erros de validação do certificado (prefixo `[BadRequest]`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /company/report:
    get:
      operationId: companyReportList
      tags:
        - Relatórios Customizados
      summary: Lista o catálogo de relatórios disponíveis para a empresa
      description: >-
        Retorna o **catálogo de relatórios** que a empresa autenticada tem habilitados — agrupados por categoria
        (`TypeCompanyReportGroup`: Vendas, Financeiro, Fiscal, Estoque, WMS, TMS, Anúncios, Integração, Customizado,
        etc.) e detalhando para cada relatório os **filtros aceitos** (`TypeCompanyReportQuery`).


        Cada filtro tem um `Type` (RangerPicker para intervalo de datas, InputGroup para par de campos, Select para
        lista, Input para texto livre), um `Label` (legenda exibida) e um `Param` (lista de nomes de query string que o
        front envia ao gerar o relatório). Para o relatório de id `85` (Estoque por integração), o sistema injeta
        dinamicamente os parâmetros `IDTypeCompanyIntegration` e `ListSalesChannel` no filtro de Integração.
      responses:
        '200':
          description: >-
            Catálogo de relatórios (array de grupos, cada um com `TypeCompanyReport[]` e seus
            `TypeCompanyReportQuery[]`).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyReportGroup'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /user/report:
    get:
      operationId: userReportList
      tags:
        - Cadastro de Usuários
      summary: Lista os relatórios já gerados pelo usuário
      description: >-
        Retorna o histórico de relatórios que **o usuário autenticado** gerou — ordenado pela data de criação
        descendente. Cada item traz o tipo de relatório (`TypeCompanyReport`), os filtros usados (`Query`), o status
        (`Status`: pendente, processando, concluído, erro), comentários, link de download (`Link`, preenchido quando o
        processamento termina) e a data/hora da geração.
      responses:
        '200':
          description: Histórico de relatórios do usuário.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserReportListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: userReportPost
      tags:
        - Cadastro de Usuários
      summary: Enfileira a geração de um relatório
      description: >-
        Cria um pedido de geração de relatório para o tipo (`IDTypeCompanyReport`) e filtros (`Query`) informados. O
        processamento é **assíncrono**: o sistema insere o registro em `UserReport` com status pendente, envia a
        mensagem para a fila assíncrona `reports.fifo` (com `MessageGroupId` igual ao subdomínio da empresa, garantindo
        serialização por empresa) e devolve a lista atualizada de relatórios do usuário. O processo consome a fila,
        executa a query, gera o arquivo, sobe para o storage e atualiza `Link` no registro.


        **Duplicidade**: o sistema bloqueia se já existe um relatório do **mesmo tipo**, com a **mesma query**, do
        **mesmo usuário**, ainda **sem `Link`** e com `IDTypeStatusUserReport=1` (pendente), criado nas **últimas 3
        horas** — para evitar gerar o mesmo relatório duas vezes em paralelo. Mensagem: `Relatório já esta em
        processamento, favor aguardar`.


        Quando `SendEmail=1`, o processo envia o link do arquivo para o e-mail do usuário ao terminar a geração.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserReportCreate'
        description: >-
          Pedido de geração de relatório. `IDTypeCompanyReport` e `Query` (string `chave1=valor1&chave2=valor2` com os
          filtros do relatório) são obrigatórios. `SendEmail=1` faz o processo enviar o link por email ao usuário quando
          terminar. Bloqueado por duplicidade: se já existe um relatório do mesmo tipo, mesma `Query`, mesmo usuário,
          sem `Link` e criado nas últimas 3 horas.
      responses:
        '200':
          description: >-
            Relatório enfileirado. Retorna o histórico atualizado de relatórios do usuário (mesmo formato de `GET
            /user/report`).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserReportListItem'
        '400':
          description: |-
            Erros (prefixo `[BadRequest]`):
            - `Empresa não existe`
            - `Relatório já esta em processamento, favor aguardar`
            - `Problema ao gerar relatório`
            - `Query deve ser uma querystring (ex: DateFrom=2026-06-23&DateTo=2026-06-23), recebido JSON: <valor>`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /user/{iduser}/comission:
    parameters:
      - name: iduser
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do usuário (vendedor) ao qual a comissão será vinculada.
    post:
      operationId: userComissionPost
      tags:
        - Cadastro de Usuários
      summary: Adiciona uma regra de comissão para o vendedor
      description: >-
        Cria uma regra de comissão (`SalesmanComission`) vinculada ao usuário. A regra define a vigência
        (`DateFrom`/`DateTo`), o percentual de comissão (`ComissionPercent`) e o limite máximo de desconto
        (`DiscountPercentLimit`) — vendas com desconto **acima do limite** não pagam essa comissão. Quando `IDCategory`
        é informado, a regra **só vale** para vendas de SKUs daquela categoria (permite ter percentuais diferentes por
        categoria de produto).


        A cada criação, o sistema também grava um log da operação em `UserLog`. A resposta é o detalhe completo do
        usuário atualizado, com a nova regra já em `SalesmanComission[]`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserComissionCreate'
        description: >-
          Regra de comissão a cadastrar para o vendedor. `DateFrom`, `DateTo` e `ComissionPercent` são obrigatórios.
          `DiscountPercentLimit` limita o desconto da venda que ainda paga essa regra. `IDCategory` (opcional) restringe
          a regra a vendas de SKUs da categoria informada.
      responses:
        '200':
          description: Regra de comissão criada. Retorna o detalhe do usuário com a lista atualizada de regras.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserComissionDetail'
                maxItems: 1
        '400':
          description: |-
            Erros (prefixo `[BadRequest]`):
            - `Usuário não encontrado`
            - `Categoria não existe` (quando `IDCategory` aponta para categoria de outra empresa ou inexistente)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /user/{iduser}/comission/{idsalesmancomission}:
    parameters:
      - name: iduser
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do usuário (vendedor).
      - name: idsalesmancomission
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador da regra de comissão.
    put:
      operationId: userComissionPut
      tags:
        - Cadastro de Usuários
      summary: Atualiza uma regra de comissão
      description: >-
        Atualização total da regra — todos os campos do corpo são gravados. Quando `IDCategory` é informado, é validado
        contra `StockKeepingUnitCategory` da empresa autenticada. A operação também grava um log em `UserLog` e devolve
        o detalhe atualizado do usuário.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserComissionCreate'
        description: >-
          Atualização total da regra de comissão — todos os campos do corpo substituem o valor anterior. Mesmos campos
          do POST.
      responses:
        '200':
          description: Regra atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserComissionDetail'
                maxItems: 1
        '400':
          description: |-
            Erros (prefixo `[BadRequest]`):
            - `Comissão vendedor não encontrada`
            - `Categoria não existe`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: userComissionDelete
      tags:
        - Cadastro de Usuários
      summary: Remove uma regra de comissão
      description: >-
        Apaga fisicamente a regra de comissão. Grava log em `UserLog` com o id da regra removida. A resposta é o detalhe
        atualizado do usuário.
      responses:
        '200':
          description: Regra removida.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserComissionDetail'
                maxItems: 1
        '400':
          description: 'Regra não encontrada para o usuário/empresa. Mensagem: `[BadRequest] - Comissão vendedor não encontrada`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /store-front/cashier/history:
    get:
      operationId: storeFrontCashierHistoryList
      tags:
        - Frente de Caixa
      summary: Lista sessões de caixa do PDV
      description: >-
        Lista as sessões de caixa (`StoreFrontCashier`) — cada item é uma abertura/fechamento de caixa de uma das contas
        bancárias do tipo "caixa do PDV" da empresa. A listagem traz o operador (`Login`/`UserName`), o caixa (`Bank` da
        conta), as datas e os comentários de abertura/fechamento.


        O escopo é multi-empresa: respeita o contexto `accountname`/`idcompanylist` do token. Quando
        `accountname=["all"]`, lista de todas as empresas do grupo; caso contrário, filtra pelas empresas habilitadas no
        token.


        Ordenação: data de abertura **decrescente**.
      parameters:
        - name: IDBankAccount
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por conta bancária (caixa) específica.
        - name: RecordUserCreated
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo usuário que abriu o caixa.
        - name: IDStoreFrontCashier
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por identificador único da sessão de caixa.
        - name: IDCompanyInvoice
          in: query
          required: false
          schema:
            type: integer
          description: Filtra apenas sessões cujo banco usa este faturador.
        - name: DateFromOpen
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data inicial (inclusive) da abertura do caixa.
        - name: DateToOpen
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data final (inclusive — fim do dia) da abertura do caixa.
      responses:
        '200':
          description: Lista de sessões de caixa.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StoreFrontCashierHistoryListItem'
        '400':
          description: Configuração de empresa inválida (prefixo `[BadRequest]`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /store-front/cashier/history/{idstorefrontcashier}:
    parameters:
      - name: idstorefrontcashier
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador da sessão de caixa do PDV.
    get:
      operationId: storeFrontCashierHistoryGet
      tags:
        - Frente de Caixa
      summary: Detalhe (extrato) de uma sessão de caixa
      description: >-
        Retorna o **extrato completo** de uma sessão de caixa, com 3 listas agregadas:


        - **`OrderList[]`** — pedidos atendidos no caixa, **uma linha por recebimento** (`AccountsPayableReceivable`),
        com o tipo de pagamento, NSU, TID, parcelas, vendedor, cliente e o status do pedido (`IDStatusOrder` = `90`
        indica venda cancelada). Vem do join de `StoreFrontCashierOrder` × `AccountsPayableReceivable`.

        - **`TransactionList[]`** — lançamentos bancários (`AccountsPayableReceivableBankStatement`) gerados na sessão:
        sangrias, suprimentos, recebimentos baixados etc. `IDTypeAccount = 1` é débito (a tela inverte o sinal do valor)
        e demais valores são crédito.

        - **`PaymentSummary[]`** — soma dos recebimentos **válidos** (pedidos não cancelados) por tipo de pagamento. A
        lista começa com os tipos de pagamento habilitados no PDV (`EnableFrenteCaixa=1`) zerados e é incrementada
        conforme `OrderList` é processada.


        Além disso, traz os totais agregados `TotalOrderValue` (soma de `OrderList`) e `TotalTransactionValue` (soma de
        `TransactionList`).
      responses:
        '200':
          description: Extrato da sessão (array com 1 item).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StoreFrontCashierHistoryDetail'
                maxItems: 1
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /store-front/cashier/history/{idstorefrontcashier}/adjust/{idaccountpayablereceivable}:
    parameters:
      - name: idstorefrontcashier
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador da sessão de caixa do PDV.
      - name: idaccountpayablereceivable
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do recebimento (`AccountsPayableReceivable`) a ajustar.
    put:
      operationId: storeFrontCashierHistoryPut
      tags:
        - Frente de Caixa
      summary: Ajusta um recebimento da sessão de caixa
      description: >-
        Corrige os dados de um recebimento gerado dentro de uma sessão de caixa do PDV. Permite trocar o **tipo de
        pagamento** (`IDTypePayment`), informar/atualizar **TID** e **NSU** da maquininha e alterar a **quantidade de
        parcelas** (`InstallmentTotal`).


        Regras importantes:


        - O recebimento precisa estar com status conciliação **ainda aberto** — só são aceitos
        `IDStatusAccountPayableReceivable` ∈ `{0, 1, 6}`. Recebimentos já conciliados/baixados retornam `[BadRequest] -
        Recebimento já foi conciliado e não pode ser editado`.

        - `IDTypePayment` precisa pertencer à mesma empresa do recebimento (`IDCompany`).

        - O update afeta **todas as parcelas** do mesmo agrupamento `(IDOrder, IDTypePayment, IDTypeAccount, NSU, TID)`
        — quando há parcelamento, todas as linhas relacionadas recebem a mesma alteração.

        - Quando `InstallmentTotal` muda, o sistema **recria o parcelamento** com a nova quantidade de parcelas (apaga
        os recebimentos antigos e gera os novos com o valor recalculado). Quando `InstallmentTotal` permanece igual,
        apenas os campos enviados são gravados.

        - Cada alteração de campo (`IDTypePayment`/`TID`/`NSU`) é registrada em `AccountsPayableReceivableLog` no
        formato `DE: <antigo> PARA: <novo>`.


        Na frente, o botão de edição exige a privilégio `PrivilegePointOfSaleEditTransaction` — quem não tem precisa
        autorizar via senha de gerente (`POST /user/{iduser}/verify`).


        A resposta é o extrato atualizado da sessão (mesma forma do `GET
        /store-front/cashier/history/{idstorefrontcashier}`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreFrontCashierHistoryAdjust'
        description: >-
          Edita os campos do recebimento (`AccountsPayableReceivable`) feito no caixa: pode trocar a forma de pagamento,
          TID, NSU e a quantidade de parcelas. Quando `InstallmentTotal` é diferente do atual, o sistema apaga o
          agrupamento `(IDOrder, IDTypePayment, NSU, TID)` e recria o parcelamento com o valor total dividido nas novas
          parcelas. Cada alteração efetiva é registrada em `AccountsPayableReceivableLog`. A operação só é aceita
          enquanto nenhuma das parcelas tiver sido conciliada (`IDStatusAccountPayableReceivable` em `0`, `1` ou `6`).
      responses:
        '200':
          description: Recebimento ajustado. Retorna o extrato atualizado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StoreFrontCashierHistoryDetail'
                maxItems: 1
        '400':
          description: |-
            Erros (prefixo `[BadRequest]`):
            - `Conta a receber não existe`
            - `Conta a receber não existe (parcelamentos)`
            - `Recebimento já foi conciliado e não pode ser editado`
            - `Tipo pagamento não existe`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`). Inclui falha do processo de retaguarda durante o recálculo do parcelamento.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/promotion:
    get:
      operationId: skuPromotionList
      tags:
        - Promoção PDV
      summary: Lista promoções do PDV
      description: >-
        Lista as promoções (`StockKeepingUnitPromotion`) cadastradas para a(s) empresa(s) do contexto. Aceita filtros
        por **tipo** (`IDTypeSkuPromotion` = 1 Regular, 2 Compre e Ganhe, 3 Desconto Progressivo, 4 Compre Junto),
        **status** (`IDTypeSkuPromotionStatus` = 0 Excluída, 1 Ativo, 2 Programada, 3 Finalizada, 4 Inativa — default
        `1,2,3,4`, ou seja, esconde excluídas), **nome** (`StockKeepingUnitPromotionName`, busca parcial) e dois
        intervalos de datas independentes (sobre `DateFrom` e sobre `DateTo`).


        O escopo é multi-empresa: respeita o contexto `accountname`/`idcompanylist` do token. Quando
        `accountname=["all"]`, lista de todas as empresas do grupo.
      parameters:
        - name: IDTypeSkuPromotion
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 3
              - 4
          description: Filtra por tipo de promoção.
        - name: IDTypeSkuPromotionStatus
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
              enum:
                - 0
                - 1
                - 2
                - 3
                - 4
            default:
              - 1
              - 2
              - 3
              - 4
          description: >-
            Lista CSV de status. Default `1,2,3,4` (oculta `0`=Excluída). Pode ser usado para mostrar só ativas (`1`),
            só programadas (`2`) etc.
          style: form
          explode: false
        - name: StockKeepingUnitPromotionName
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo nome (busca parcial, case-insensitive).
        - name: DateFromDateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Início do intervalo a aplicar sobre o campo `DateFrom` da promoção.
        - name: DateFromDateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Fim do intervalo a aplicar sobre o campo `DateFrom` da promoção (inclusive — fim do dia).
        - name: DateToDateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Início do intervalo a aplicar sobre o campo `DateTo` da promoção.
        - name: DateToDateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Fim do intervalo a aplicar sobre o campo `DateTo` da promoção (inclusive — fim do dia).
      responses:
        '200':
          description: Lista de promoções (cabeçalho apenas — sem itens vinculados).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuPromotionListItem'
        '400':
          description: Configuração de empresa inválida (prefixo `[BadRequest]`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: skuPromotionPost
      tags:
        - Promoção PDV
      summary: Cria uma promoção
      description: >-
        Cria uma promoção do tipo informado em `IDTypeSkuPromotion`. Os campos exigidos e ignorados variam **por tipo**
        — o body abaixo descreve o conjunto completo, mas o sistema só usa o que faz sentido para o tipo escolhido e
        zera o resto.


        ## Regras por tipo


        ### Tipo 1 — Regular

        Desconto em **% ou R$** aplicado a todos os produtos ou apenas aos que casam com as **restrições**
        (`StockKeepingUnitPromotionCategories`, `StockKeepingUnitPromotionBrands`, `StockKeepingUnitPromotionProducts`,
        `StockKeepingUnitPromotionSkus`).

        - Use **um** entre `PercentualDiscountValue` (fração `0–1`, ex.: `0.10` = 10%) **ou** `NominalDiscountValue`
        (R$).

        - `MinOrderValue` / `MaxOrderValue` (opcionais): só vale quando o total do pedido cai nesse intervalo.

        - Para cada restrição há um flag de **inclusão/exclusão** (`BrandsIncluded`, `CategoriesIncluded`,
        `ProductsIncluded`, `SkusIncluded` — default `1` = iguais a; `0` = diferentes de). Quando a lista correspondente
        é vazia, a restrição **não filtra**.


        ### Tipo 2 — Compre e Ganhe

        Cliente compra `MinimumQuantityBuyTogether` unidades dos itens em `StockKeepingUnitPromotionSkus` e ganha
        (grátis, valor zero) os itens listados em `StockKeepingUnitPromotionSkusBuyTogether`.

        - `StockKeepingUnitPromotionSkus` **obrigatório** (itens que devem ser comprados).

        - `StockKeepingUnitPromotionSkusBuyTogether` **obrigatório** (itens de brinde).

        - `MinimumQuantityBuyTogether` **obrigatório** e > 0.

        - Campos de desconto/range/restrição são ignorados.


        ### Tipo 3 — Desconto Progressivo

        Quanto mais unidades, maior o desconto. Cada faixa em `StockKeepingUnitPromotionProgressive` tem `Quantity` (a
        partir de quantas unidades vale) e `DiscountPercent` **OU** `FixedPrice` (preço unitário fixo).

        - Itens elegíveis: `StockKeepingUnitPromotionSkus` (SKUs) **OU** `StockKeepingUnitPromotionProducts` (produtos
        pai).

        - `Quantity` precisa ser **único** entre as faixas (não pode ter duas faixas com mesma quantidade).

        - Combine com `ExactlyQuantity=1` (no cabeçalho) para aplicar a faixa apenas quando a quantidade for **múltipla
        exata** (4, 8, 12... para faixa de 4).


        ### Tipo 4 — Compre Junto

        Duas listas com descontos separados. Compre `MinimumQuantityBuyTogether` unidades da **lista principal**
        (`StockKeepingUnitPromotionSkus`) com desconto `PercentualDiscountValue`; ao adicionar itens da **lista
        complementar** (`StockKeepingUnitPromotionSkusBuyTogether`), eles recebem `PercentualDiscountValueBuyTogether`.

        - Todos os 4 campos são obrigatórios.

        - `PercentualDiscountValue` e `PercentualDiscountValueBuyTogether` em fração `0–1`.


        ## Flags do cabeçalho (todos os tipos)


        - **`Cumulative`** — quando `1`, pode acumular com **outras promoções de tipos diferentes** no mesmo item (regra
        de prioridade depois do desempate por maior desconto).

        - **`CumulativeManualPrice`** — quando `1`, aplica o desconto mesmo se o item já tem um **preço manual** (preço
        de venda diferente do preço de lista). Quando `0`, a promoção é descartada se houver desconto manual.

        - **`AllowDifferentItemQuantitySum`** — quando `1`, a `MinimumQuantityBuyTogether` (Compre e Ganhe / Compre
        Junto) ou a `Quantity` da faixa (Progressivo) considera a **soma de quantidades de SKUs diferentes** que entram
        na promoção. Quando `0`, só conta o mesmo SKU.

        - **`ExactlyQuantity`** — quando `1` (Progressivo), aplica a faixa só quando a quantidade for múltiplo exato;
        quando `0`, aplica assim que a quantidade atinge a faixa (com lógica greedy decrescente).

        - **`OnlyRegisteredConsumer`** — quando `1`, a promoção só é aplicada se o pedido tem `IDConsumer` informado
        (cliente cadastrado).

        - **`DateFrom`/`DateTo`** — vigência. Para promoção **"para sempre"**, envie `DateFrom = "1900-01-01"` e `DateTo
        = "4000-01-01"`.


        ## Vínculos opcionais


        - **`StockKeepingUnitPromotionTypeOrders`** — lista de tipos de pedido (`Status=1`) em que a promoção vale.
        Vazio = vale para todos.

        - **`StockKeepingUnitPromotionSalesPolicies`** — lista de políticas comerciais aceitas. Vazio = vale para todas.


        ## Detalhes


        - A nova promoção passa a valer imediatamente para a empresa (ordem de aplicação: tipo → maior % → maior R$).

        - O nome (`StockKeepingUnitPromotionName`) é gravado **sem acentos** (normalização NFD).


        A resposta é o detalhe completo da promoção criada (mesmo formato de `GET /sku/promotion/{id}`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuPromotionCreate'
        description: >-
          Dados da promoção a cadastrar. `IDTypeSkuPromotion` define o tipo: `1` Regular (desconto direto), `2` Compre e
          ganhe, `3` Desconto progressivo, `4` Compre junto. Para tipo `1` informe as listas de marcas, categorias,
          produtos ou SKUs participantes; para tipo `4` use `StockKeepingUnitPromotionSkusBuyTogether[]` com os SKUs do
          grupo. `DateFrom` precisa ser menor que `DateTo`.
      responses:
        '200':
          description: Promoção criada. Retorna o detalhe (array com 1 item).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuPromotionDetail'
                maxItems: 1
        '400':
          description: >-
            Erros de validação (prefixo `[BadRequest]`):

            - `Empresa não existe`

            - `Tipo de promoção não existe`

            - `Promoção sem regra de cadastro` (tipo diferente de 1/2/3/4)

            - `Data de precisa ser maior que data até`

            - `Tipo pedido(s) não localizada(s): <ids>`

            - `Politica(s) comercial não localizada(s): <ids>`

            - `Marca(s)/Categoria(s)/Produtos(s)/Sku(s) não localizada(s): <ids>` (valida que pertencem à empresa e
            estão com status ativo)

            - `Quantidade mínima é obrigatória na promoção compre e ganhe`

            - `Quantidade mínima é obrigatória na promoção compre junto`

            - `Percentual desconto lista um é obrigatória` (Compre Junto)

            - `Percentual desconto lista dois é obrigatória` (Compre Junto)

            - `Obrigatório informar itens` / `Obrigatório informar itens brinde` / `Obrigatório informar itens lista
            dois`

            - `Obrigatório informar quantidade e % desconto` (Progressivo sem faixas)

            - `Campo quantidade precisa ser único` (Progressivo com faixas duplicadas)

            - `Erro ao criar promoção`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/promotion/{idstockkeepingunitpromotion}:
    parameters:
      - name: idstockkeepingunitpromotion
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador da promoção.
    get:
      operationId: skuPromotionGet
      tags:
        - Promoção PDV
      summary: Detalhe completo de uma promoção
      description: >-
        Retorna a promoção com **todas as listas vinculadas** resolvidas: marcas (`StockKeepingUnitPromotionBrands`),
        categorias (`StockKeepingUnitPromotionCategories`), produtos (`StockKeepingUnitPromotionProducts`), SKUs
        (`StockKeepingUnitPromotionSkus`), tipos de pedido (`StockKeepingUnitPromotionTypeOrders`), políticas comerciais
        (`StockKeepingUnitPromotionSalesPolicies`), faixas progressivas (`StockKeepingUnitPromotionProgressive`) e SKUs
        de brinde/lista complementar (`StockKeepingUnitPromotionSkusBuyTogether` — com URL da imagem principal). Esse é
        o corpo usado pelo modal de edição da tela.
      responses:
        '200':
          description: Detalhe da promoção (array com 1 item ou vazio se não existe).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuPromotionDetail'
                maxItems: 1
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    put:
      operationId: skuPromotionPut
      tags:
        - Promoção PDV
      summary: Atualiza uma promoção
      description: >-
        Atualiza parcialmente o cabeçalho da promoção e **substitui** as listas vinculadas. O **tipo
        (`IDTypeSkuPromotion`) não pode ser alterado** — vem da promoção existente; o sistema respeita as regras do tipo
        original e zera campos que não fazem sentido (ex.: para tipo 1 zera `MinimumQuantityBuyTogether` e
        `PercentualDiscountValueBuyTogether`).


        Valida o mesmo conjunto de regras do `POST` (vigência, existência de marcas/categorias/produtos/SKUs na empresa,
        faixas únicas no Progressivo, etc.).


        **Sincronização das listas** (diff inteligente): quando você envia uma lista (qualquer um dos campos
        `StockKeepingUnitPromotionBrands`, `Categories`, `Products`, `Skus`, `TypeOrders`, `SalesPolicies`,
        `SkusBuyTogether`, `Progressive`), o sistema:

        1. Lê os vínculos atuais.

        2. **Insere** os itens da lista enviada que ainda não existem.

        3. **Apaga** os itens existentes que não estão na lista enviada.

        4. Mantém o resto inalterado.


        Enviar uma **lista vazia** (`[]`) apaga todos os vínculos daquele tipo. Para **não tocar** numa lista, **omita**
        o campo do body.


        As alterações passam a valer imediatamente. Trava `PercentualDiscountValue > 1` com `[BadRequest] - Desconto
        percentual não pode ser maior que 100%`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuPromotionUpdate'
        description: Atualização parcial da promoção. Todos os campos são opcionais; apenas os enviados são aplicados.
      responses:
        '200':
          description: Promoção atualizada. Retorna o detalhe (mesmo formato do GET).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuPromotionDetail'
                maxItems: 1
        '400':
          description: |-
            Erros (prefixo `[BadRequest]`):
            - `Promoção não localizada`
            - `Desconto percentual não pode ser maior que 100%`
            - `Data de precisa ser maior que data até`
            - demais erros do POST (faixas duplicadas, vínculos inexistentes, obrigatórios faltando para o tipo)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: skuPromotionDelete
      tags:
        - Promoção PDV
      summary: Exclui uma promoção
      description: >-
        Exclusão **híbrida** — depende de a promoção já ter sido usada em pedidos:


        - Se **não há** promoções vinculadas a pedidos vinculados → **exclusão física** do registro.

        - Se já foi usada → **exclusão lógica** (`IDTypeSkuPromotionStatus = 0`, status "Excluída"). Isso preserva o
        histórico nos pedidos antigos.


        Dispara a regravação interno (excluídas e inativas ficam de fora ).
      responses:
        '200':
          description: 'Promoção excluída (resposta: string `sucesso`).'
          content:
            application/json:
              schema:
                type: string
                example: sucesso
        '400':
          description: |-
            Erros (prefixo `[BadRequest]`):
            - `Promoção não localizada`
            - `Erro ao excluir promoção`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/promotion/sku/{idsku}:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do SKU (`IDSku`).
    get:
      operationId: skuPromotionSkuGet
      tags:
        - Promoção PDV
      summary: Lista promoções aplicáveis a um SKU
      description: >-
        Retorna **todas as promoções vigentes** que se aplicam ao SKU informado — usado pela tela do produto para
        mostrar o selo de promoção. Avalia: vigência (data atual ∈ `[DateFrom, DateTo]`), restrição por marca,
        categoria, produto e SKU (respeitando as flags `*Included` = `1` para igualdade ou `0` para diferença). Itens
        listados em `StockKeepingUnitPromotionSkusBuyTogether` (lista de brindes) também entram
        (`IncludeSkuTogether=1`).


        Sem token de empresa válido, retorna `[NotFound] - Sku não existe`.
      responses:
        '200':
          description: Promoções aplicáveis ao SKU.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuPromotionSkuItem'
        '404':
          description: 'Sku não encontrado: `[NotFound] - Sku não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/promotion/order/validate:
    post:
      operationId: skuPromotionOrderValidateGet
      tags:
        - Promoção PDV
      summary: Aplica promoções ao carrinho do PDV
      description: >-
        Recebe a lista de itens em montagem no PDV e **aplica todas as promoções vigentes** retornando o carrinho com os
        preços recalculados (`PriceSelling`, `PriceSellingTotal`, `ValueDiscount`, `ValueDiscountTotal`,
        `OriginalPriceSelling`, `PromotionDiscountPercent`) e a lista de promoções usadas
        (`IDStockKeepingUnitPromotion`/`StockKeepingUnitPromotionName`) por item.


        ## Regras de elegibilidade (por promoção × item)


        Uma promoção é aplicada quando passa em **todos** os testes:


        1. **Vigência** — data/hora atual ∈ `[DateFrom, DateTo]`.

        2. **Restrição de marca** — quando `BrandsIncluded=1`, a marca do SKU está na lista; quando `BrandsIncluded=0`,
        **não** está.

        3. **Restrição de categoria** — mesma lógica de `CategoriesIncluded`.

        4. **Restrição de produto** — mesma lógica de `ProductsIncluded` (compara `IDProduct` da variação).

        5. **Restrição de SKU** — mesma lógica de `SkusIncluded`.

        6. **Tipo de pedido** — quando `StockKeepingUnitPromotionTypeOrders` não vazio, `IDOrderType` precisa estar na
        lista.

        7. **Política comercial** — quando `StockKeepingUnitPromotionSalesPolicies` não vazio, `IDCompanySalesPolicy` do
        item precisa estar na lista.

        8. **Acúmulo com preço manual** — quando `CumulativeManualPrice=0` e `PriceListTotal ≠ PriceSellingTotal` (preço
        foi alterado manualmente), descarta.

        9. **Cliente cadastrado** — quando `OnlyRegisteredConsumer=1`, `IDConsumer` precisa estar informado.

        10. **Faixa de valor do pedido** (Regular) — `totalvalue ∈ [MinOrderValue, MaxOrderValue]`.


        ## Cálculo do preço


        - **Regular**: aplica `PercentualDiscountValue` (multiplica `PriceSellingTotal × (1 - %)`) ou
        `NominalDiscountValue × Quantity` (com piso em 0).

        - **Compre e Ganhe**: se `Quantity ≥ MinimumQuantityBuyTogether`, cada item em `SkusBuyTogether` é
        adicionado/atualizado no carrinho com `PriceSellingTotal=0` (brinde).

        - **Desconto Progressivo (ExactlyQuantity=0)**: percorre as faixas (ordenadas desc por `Quantity`) e aplica a
        primeira em que `progressive.Quantity ≤ Quantity` ou `≤ GroupedQuantity` (com
        `AllowDifferentItemQuantitySum=1`).

        - **Desconto Progressivo (ExactlyQuantity=1)**: lógica **greedy** — para cada faixa (desc por `Quantity`),
        encaixa múltiplos exatos (`floor(remaining / Quantity)`), gera um objeto de carrinho por faixa aplicada, e o
        resíduo vira um objeto **sem desconto**.

        - **Compre Junto**: se `Quantity ≥ MinimumQuantityBuyTogether` da lista principal e existe item da lista
        complementar no carrinho, aplica `PercentualDiscountValue` no principal e `PercentualDiscountValueBuyTogether`
        no complementar.


        ## Desempate entre promoções


        Quando o mesmo item bate em **várias promoções**:

        1. Ordena por **maior desconto** (`PreValueDiscountTotal`).

        2. Mantém a primeira; mantém também subsequentes desde que **mesmo tipo + Cumulative=1** (acumula promoções do
        mesmo tipo cumulativas) **ou tipo diferente** (deixa o resto da lógica decidir).


        ## `StoreFrontCashierOrderTemp`


        O endpoint também **persiste** o estado do carrinho em `StoreFrontCashierOrderTemp` (vinculado ao caixa aberto
        via `IDStoreFrontCashier`/`IDBankAccount`). Se você passar `IDStoreFrontCashierOrderTemp`, atualiza esse
        registro; senão insere um novo e devolve o `IDStoreFrontCashierOrderTemp` gerado no corpo da resposta. Isso é o
        que permite o PDV retomar o pedido em outro terminal.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuPromotionOrderValidateBody'
        description: >-
          Pedido a validar contra as promoções vigentes da empresa. Informe a lista de itens (`Items[]`) com SKU,
          quantidade e preço, o tipo de pedido (`IDOrderType`), opcionalmente o consumidor (`IDConsumer`, exigido por
          promoções `OnlyRegisteredConsumer=1`) e o caixa (`IDStoreFrontCashier`). O retorno traz os descontos e ajustes
          calculados para cada item.
      responses:
        '200':
          description: Carrinho com os preços e promoções recalculados.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkuPromotionOrderValidateResponse'
        '400':
          description: |-
            Erros (prefixo `[BadRequest]`):
            - `Pedido não tem itens` (lista vazia)
            - `Item não encontrado` (SKU informado não existe ou não é da empresa)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/sku/promotion/type:
    get:
      operationId: typeSkuPromotionList
      tags:
        - Tipos — SKU
      summary: Lista os tipos de promoção do PDV
      description: >-
        Lista de valores fixos do sistema (`TypeSkuPromotion`) usados no seletor de tipo do modal: `1`=Regular,
        `2`=Compre e ganhe, `3`=Desconto progressivo, `4`=Compre junto.
      responses:
        '200':
          description: Tipos de promoção.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeSkuPromotion:
                      type: string
                      description: Identificador do tipo de promoção.
                    TypeSkuPromotion:
                      type: string
                      description: Nome do tipo de promoção (`Regular`, `Compre e Ganhe`, `Desconto Progressivo`, `Compre Junto`).
  /type/sku/promotion/status:
    get:
      operationId: typeSkuPromotionStatusList
      tags:
        - Tipos — SKU
      summary: Lista os status possíveis de promoção do PDV
      description: >-
        Lista de valores fixos (`TypeSkuPromotionStatus`): `0`=Excluída, `1`=Ativo, `2`=Programada, `3`=Finalizada,
        `4`=Inativa.
      responses:
        '200':
          description: Status possíveis.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeSkuPromotionStatus:
                      type: string
                      description: Identificador do status da promoção.
                    TypeSkuPromotionStatus:
                      type: string
                      description: 'Descrição do status (ex.: `Ativa`, `Inativa`, `Excluída`).'
  /store-front/payment:
    get:
      operationId: storeFrontPaymentList
      tags:
        - Pagamento PDV
      summary: Lista transações TEF/Pix do PDV
      description: >-
        Lista as transações de pagamento feitas no PDV — tanto via maquininha (PayGo/ControlPay) quanto via Pix (Stark
        Bank, Pagar.me). Cada item traz o valor, o status, o tipo de pagamento, o adquirente, o último número do cartão
        (4 dígitos), TID, código de autorização, e o ZPL dos comprovantes (`Receipt` para via estabelecimento,
        `ReceiptBuyer` para via cliente — ambos vêm com `\r\n VA` apendado para impressão direta).


        A listagem é multi-empresa: respeita `accountname`/`idcompanylist` do token. Quando `accountname=["all"]`, lista
        de todas as empresas do grupo. Limite de **2000 itens por página** — use `Page` (zero-indexed) para paginar (o
        deslocamento é `Page × 2000`).


        **Janela padrão de 30 dias:** quando a chamada não traz nenhum filtro seletivo — identificador da transação
        `IDStoreFrontCashierPayment`, `TID`, código de autorização `AuthId`, terminal `TefTerminal`, início do período
        de criação `DateFrom` ou início do período de cancelamento `DateCancelFrom` — a listagem devolve apenas as
        transações dos últimos 30 dias, contadas pela data de criação `RecordTimestamp`. Filtrar somente por status
        `IDTypeStatusStoreFrontCashierPayment`, por caixa `IDBankAccount`, por faturador `IDCompanyInvoice`, por
        `DateTo` ou por `DateCancelTo` **não** amplia essa janela; para varrer o histórico completo, informe `DateFrom`
        (ou outro dos filtros seletivos).


        Cada item já vem com o `IDOrder` do pedido associado resolvido (ligação feita pelo `IDOrderIntention`, o UUID
        que conecta a tentativa de pagamento ao pedido fechado).


        Ordenação: `IDStoreFrontCashierPayment` decrescente (mais recentes primeiro).
      parameters:
        - name: Page
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: Página zero-indexed. Offset = `Page × 2000`.
        - name: IDCompanyInvoice
          in: query
          required: false
          schema:
            type: integer
          description: Filtra apenas transações cuja conta bancária tem este faturador.
        - name: IDBankAccount
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por caixa/maquininha (conta bancária do PDV).
        - name: TefTerminal
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo código do terminal TEF (ID PayGo).
        - name: TID
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo TID retornado pela maquininha.
        - name: AuthId
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo código de autorização do adquirente.
        - name: IDTypeStatusStoreFrontCashierPayment
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 3
              - 4
              - 5
              - 6
              - 7
              - 8
          description: >-
            Filtra por status (1=Pendente, 2=Em pagamento, 3=Creditado, 4=Expirado, 5=Cancelamento iniciado, 6=Em
            cancelamento, 7=Cancelado, 8=Pagamento recusado).
        - name: IDStoreFrontCashierPayment
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por identificador único da transação.
        - name: DateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Início do intervalo da data de criação da transação.
        - name: DateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Fim do intervalo da data de criação da transação (inclusive — fim do dia).
        - name: DateCancelFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Início do intervalo da data de cancelamento.
        - name: DateCancelTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Fim do intervalo da data de cancelamento (inclusive — fim do dia).
      responses:
        '200':
          description: Lista de transações.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StoreFrontPaymentListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /store-front/cashier/{idbankaccount}/payment:
    parameters:
      - name: idbankaccount
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: >-
          Conta bancária do caixa do PDV (`IDBankAccount`) — define qual integração (PayGo/StarkBank/Pagar.me) será
          usada e em que terminal a venda é direcionada.
    post:
      operationId: storeFrontPaymentPost
      tags:
        - Frente de Caixa
      summary: Inicia uma cobrança TEF ou Pix
      description: >-
        Cria o registro `StoreFrontCashierPayment` (status inicial **Pendente**) e dispara a cobrança no provedor
        configurado pela integração da conta bancária (`IDCompanyIntegration` → `IDTypeCompanyIntegration`).


        ## Direcionamento por integração


        - **PayGo / ControlPay** (`IDTypeCompanyIntegration = 17`): manda a venda para a maquininha (TEF) com
        `formaPagamentoId` derivado da categoria do tipo de pagamento (`22`=crédito → `21`, `23`=débito → `22`, `24`=Pix
        → `24`). Exige `TefTerminal` preenchido e `Token` da integração configurado. Em sucesso de conexão, status vira
        **Em pagamento** (`2`). Erro de conexão em 15s vira status **Expirado** (`4`) com mensagem `Erro ao conectar ao
        terminal TEF...`.

        - **StarkBank** (`131`): gera um QR Code Pix dinâmico (`CreateDynamicBrcode`) com 3600s de expiração. Retorna
        `PixCopiaCola` (string copia-cola) e `QrCodeImageUrl`. Status vira **Em pagamento**.

        - **Pagar.me** (`13`): só suporta **Pix** (`Category = 24`). Outras categorias dão `Integração Pagarme no PDV
        suporta apenas Pix`. Retorna `PixCopiaCola`, `QrCodeImageUrl` e o `TID`.


        ## Categorias de tipo de pagamento aceitas


        Apenas tipos de pagamento com `Category` ∈ `{22 crédito, 23 débito, 24 Pix}`. Outros valores retornam `Tipo de
        pagamento <id> inválido (categoria recebida: <cat>), permitido apenas crédito, débito e Pix`.


        ## IDOrderIntention


        Quando o cliente envia `IDOrderIntention` (UUID), o sistema usa esse valor para ligar a tentativa ao pedido.
        Quando omite, o sistema gera um UUID novo e devolve no body. Esse UUID é o que casa com `IDOrderIntention`
        (ligação tentativa → pedido fechado).


        A partir daí, o cliente deve fazer **polling** via `GET
        /store-front/cashier/{idbankaccount}/payment/{idstorefrontcashierpayment}` até obter `Success=1` ou um status
        final.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreFrontPaymentPostBody'
        description: >-
          Inicia uma cobrança no PDV. `IDTypePayment` precisa pertencer à empresa e ter `Category` em `22` (crédito),
          `23` (débito) ou `24` (Pix). A integração da cobrança é resolvida automaticamente a partir da conta bancária:
          Pix usa `IDCompanyIntegrationPix`; crédito e débito usam `IDCompanyIntegration`. O comportamento varia por
          integração — **PayGo (TEF)**: dispara venda no terminal físico via API ControlPay (`/Venda/Vender`), exige
          `TefTerminal` e o token da integração; **StarkBank**: gera BR Code Pix dinâmico (default 1h de expiração);
          **Pagar.me**: gera cobrança Pix (suporta apenas Pix neste fluxo). `IDOrderIntention` é o UUID que liga a
          cobrança ao pedido fechado pelo PDV; quando omitido o sistema gera um novo.
      responses:
        '200':
          description: >-
            Cobrança iniciada (status retornado = `2` Em pagamento). PayGo (TEF) retorna `IDStoreFrontCashierPayment`,
            `IDOrderIntention`, `IDTypeStatusStoreFrontCashierPayment` e `ExternalId`. Pix (StarkBank/Pagar.me) retorna
            ainda `PixCopiaCola`, `QrCodeImageUrl` e `QrcodeExpirationTimeInSeconds`; Pagar.me inclui também o `TID`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreFrontPaymentPostResponse'
        '400':
          description: >-
            Erros de validação (prefixo `[BadRequest]`):

            - `Necessário enviar dados para cobrança`

            - `Precisa enviar o valor, conta bancária e código do tipo de pagamento`

            - `Conta bancária não localizada`

            - `Conta bancária não tem integração selecionada`

            - `Conta bancária não tem integração configurada`

            - `Tipo pagamento <id> não encontrado`

            - `Tipo de pagamento <id> inválido (categoria recebida: <cat>), permitido apenas crédito, débito e Pix`

            - `Conta bancária não tem terminal TEF preenchido` (PayGo)

            - `Token integração TEF não esta preenchido` (PayGo)

            - `Erro ao conectar ao terminal TEF. Verificar conexão da máquininha (PIN PAD) com computador, internet e
            aplicativo paygo` (PayGo, status 15)

            - `Integração Pagarme no PDV suporta apenas Pix` (Pagar.me, categoria ≠ 24)

            - `Integração não suportada para este fluxo de pagamento`

            - `<mensagem do adquirente>` (quando o provedor recusa a cobrança)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno inesperado (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /store-front/cashier/{idbankaccount}/payment/{idstorefrontcashierpayment}:
    parameters:
      - name: idbankaccount
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Conta bancária do caixa do PDV.
      - name: idstorefrontcashierpayment
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador da transação criada em `POST /store-front/cashier/{idbankaccount}/payment`.
    get:
      operationId: storeFrontPaymentGet
      tags:
        - Frente de Caixa
      summary: Consulta status de uma transação TEF/Pix (polling)
      description: >-
        Faz **polling síncrono no adquirente** dentro de um loop limitado a **60 tentativas** (1s entre elas) — quando
        esgota, retorna **HTTP 504** sem corpo. Por isso a chamada deve ser feita com **timeout client-side ≥ 60s** (a
        frente usa 180s).


        ## Por integração


        - **PayGo / ControlPay**: consulta `IntencaoVenda/GetByFiltros` a cada segundo. Extrai do retorno o último
        `pagamentosExternos` (sempre o mais recente) e popula:
          - `IDTypeStatusStoreFrontCashierPayment` ← mapeamento de `intencaoVendaStatus.id` via `ExternalId`.
          - `TID` ← `nsuTid`, `AuthId` ← `autorizacao`, `Acquirer` ← `adquirente`, `PaymentSystemName` ← `bandeira` (Visa, Master etc.).
          - `ReturnCode` ← `codigoRespostaAdquirente`, `ReturnMessage` ← `mensagemRespostaAdquirente`.
          - `Receipt` (via estabelecimento) e `ReceiptBuyer` (via cliente) ← extraídos do `respostaAdquirente` (texto ZPL bruto entre `PWINFO_RCPTMERCH =` e `PWINFO_RCPTCHOLDER`/etc).
          - `CardLastDigits` ← últimos 4 dígitos do PAN extraído da string `CARTAO:` ou `PWINFO_CARDPARCPAN`.
        - **StarkBank**: chama `CheckPaymentByTag(ExternalId)` a cada segundo. Quando `paid === true`, status vira
        **Creditado** (`3`) com `Success=1`. Retorno inclui `PixCopiaCola`, `QrCodeImageUrl`,
        `QrcodeExpirationTimeInSeconds`.

        - **Pagar.me**: chama `GetPix(IDCompanyIntegration, ExternalId)` a cada segundo. `IDStatusBankSlip=2` →
        **Creditado**; `IDStatusBankSlip=4` → **Cancelado**; demais → continua **Em pagamento**.


        ## Sucesso vs. falha


        O endpoint retorna **`Success`** no corpo para o cliente decidir o que fazer:


        - `Success=1` → transação finalizada com sucesso (Creditado ou Cancelado bem sucedido).

        - `Success=0` → falha (Expirado, Pagamento recusado, ou caso especial PayGo `codigoRespostaExecTransac=-2596` ou
        `idPagamento` vazio com status `15`).


        Ao final do polling (sucesso ou falha definitiva), o sistema grava a atualização final em
        `StoreFrontCashierPayment` via `StoreFrontPaymentUpdate`. Se o loop esgotar sem decisão, retorna HTTP 504 e o
        cliente deve fazer nova chamada.
      responses:
        '200':
          description: >-
            Status retornado. Sempre inclui o status (`IDTypeStatusStoreFrontCashierPayment` +
            `TypeStatusStoreFrontCashierPayment`) e `Success` (0/1).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreFrontPaymentGetResponse'
        '400':
          description: |-
            Erros de validação:
            - `Transação não localizada idw`
            - `Transação não localizada controlpay` (PayGo)
            - `Transação divergente (referência controlpay: <ref>, esperado: <id>)`
            - `Integração não suportada para este fluxo de pagamento`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '504':
          description: Timeout do polling — 60 tentativas esgotadas sem resultado final. Cliente deve repetir a chamada.
    delete:
      operationId: storeFrontPaymentDelete
      tags:
        - Frente de Caixa
      summary: Cancela uma transação TEF/Pix
      description: >-
        Cancela uma transação **autorizada** (status `3` Creditado) ou **em cancelamento** (status `6`). Outros status
        retornam `Transação não esta aprovada. O cancelamento é permitido apenas em transações autorizadas`.


        ## Por integração


        - **PayGo / ControlPay**: chama `Venda/CancelarVenda` com `senhaTecnica` (senha técnica do TEF, passada via
        query `TEFPassword`). **Obrigatória** — se omitida, retorna `Precisa informar a senha do TEF para cancelamento
        (TEFPassword)`. Em sucesso de conexão, status vira **Em cancelamento** (`6`); cliente deve fazer polling via
        `GET` até o status final virar **Cancelado** (`7`). Erro de conexão → mensagem `Erro ao conectar ao terminal
        TEF...`.

        - **StarkBank**: retorna direto `Não é possível cancelar uma cobrança Pix. O QR Code apenas expira após o tempo
        configurado.` — Pix Stark Bank **não é cancelável** (só expira).

        - **Pagar.me**: chama `CancelPix(IDCompanyIntegration, ExternalId)`. Status vira **Cancelado** (`7`) com
        `RecordTimestampCancel` e `IDUserCancel` preenchidos.


        Em todos os casos com sucesso de conexão, grava `RecordTimestampCancel` (data/hora atual) e `IDUserCancel`
        (usuário que iniciou o cancelamento, vindo do token via `LAMBDA_REQUEST_CONTEXT.authorizer.User`).


        A frente de cancelamento da tela faz polling do `GET` por até 180 segundos com intervalo de 2s entre tentativas,
        mostrando "Aguarde ou digite o número do cartão..." enquanto espera o cliente operar a maquininha.
      parameters:
        - name: TEFPassword
          in: query
          required: false
          schema:
            type: string
          description: >-
            Senha técnica do TEF (PayGo). Obrigatória para integração ControlPay; ignorada para StarkBank (não suporta)
            e opcional para Pagar.me.
      responses:
        '200':
          description: >-
            Cancelamento solicitado. Para PayGo retorna o `StoreFrontCashierPayment` com status atualizado para Em
            cancelamento (`6`) — cliente deve fazer polling via `GET`. Para Pagar.me retorna com status Cancelado (`7`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreFrontPaymentListItem'
        '400':
          description: |-
            Erros:
            - `Transação não localizada`
            - `Transação não esta aprovada. O cancelamento é permitido apenas em transações autorizadas`
            - `Conta bancária não tem integração selecionada`
            - `Precisa informar a senha do TEF para cancelamento (TEFPassword)` (PayGo)
            - `Token integração TEF não está preenchido` (PayGo)
            - `Erro ao conectar ao terminal TEF...` (PayGo, status 15)
            - `Não é possível cancelar uma cobrança Pix. O QR Code apenas expira após o tempo configurado.` (StarkBank)
            - `Transação Pagarme sem ExternalId, não é possível cancelar`
            - `Integração da conta bancária não suportada para cancelamento`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/store-front/payment/status:
    get:
      operationId: typeStoreFrontPaymentStatus
      tags:
        - Tipos — PDV
      summary: Lista os status possíveis de transação TEF/Pix
      description: >-
        Lista de valores fixos (`TypeStatusStoreFrontCashierPayment`):


        | Id | Descrição | ExternalId (PayGo) |

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

        | 1 | Pendente | 5 |

        | 2 | Em pagamento | 6 |

        | 3 | Creditado | 10 |

        | 4 | Expirado | 15 |

        | 5 | Cancelamento iniciado | 18 |

        | 6 | Em cancelamento | 19 |

        | 7 | Cancelado | 20 |

        | 8 | Pagamento recusado | 25 |


        O `ExternalId` é usado pelo sistema `GET` para mapear o status retornado pelo PayGo/ControlPay para o status
        interno.
      responses:
        '200':
          description: Status possíveis.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeStatusStoreFrontCashierPayment:
                      type: string
                      description: Identificador do status da transação do PDV.
                    TypeStatusStoreFrontCashierPayment:
                      type: string
                      description: Descrição do status (`Pendente`, `Em processamento`, `Creditado`, `Cancelado`, etc.).
  /store-front/cashier:
    get:
      operationId: storeFrontCashierList
      tags:
        - Frente de Caixa
      summary: Lista os caixas (caixinhas) do PDV
      description: >-
        Lista todos os **caixas do PDV** (`BankAccount` com `BankNumber = '000'`, status ativo) da(s) empresa(s) do
        contexto. Cada item traz o **status** derivado (Aberto/Fechado), o **operador** logado (quando aberto), o
        **saldo** corrente do caixa (`Balance` = soma de todos os lançamentos em
        `AccountsPayableReceivableBankStatement` até agora) e o faturador (`IDCompanyInvoice`) que será usado na NFC-e.


        O escopo é multi-empresa: respeita `accountname`/`idcompanylist` do token. Quando `accountname=["all"]`, lista
        todos os caixas do grupo.


        O front da Frente de Caixa filtra ainda na própria tela: mostra primeiro os caixas **abertos pelo usuário
        corrente** (oferecendo "Retomar Caixa"), em seguida os caixas **fechados** disponíveis, e bloqueia os caixas
        **abertos por outro usuário**.
      parameters:
        - name: IDCompanyInvoice
          in: query
          required: false
          schema:
            type: integer
          description: >-
            Filtra caixas cujo faturador é esta empresa. Usado pela tela de abertura para mostrar só os caixas da
            empresa selecionada.
        - name: StoreFrontCashierStatus
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
              - 2
          description: 'Filtra pelo status: `1`=Fechado (sem sessão aberta), `2`=Aberto (com sessão ativa).'
      responses:
        '200':
          description: Lista de caixas.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StoreFrontCashierListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /store-front/cashier/{idbankaccount}:
    parameters:
      - name: idbankaccount
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Conta bancária do caixa do PDV.
    get:
      operationId: storeFrontCashierGet
      tags:
        - Frente de Caixa
      summary: Snapshot do caixa aberto (resumo financeiro + ZPL)
      description: >-
        Retorna o **caixa aberto** com cálculos financeiros completos da sessão atual + **dois recibos ZPL** prontos
        para impressão (usados no fechamento e na conferência diária).


        ## Campos calculados


        - **`Balance`** — saldo atual do caixa (soma de todos os créditos menos débitos em
        `AccountsPayableReceivableBankStatement` até agora).

        - **`Income`** — soma de **créditos** desde a abertura do caixa (`IDTypeAccount=0`) **menos** o que foi pago em
        dinheiro nos pedidos (porque o dinheiro do cliente já entrou pela venda; evita contagem dupla).

        - **`Outcome`** — soma de **débitos** desde a abertura.

        - **`AdjustIn`** — reforços (créditos sem `IDAccountPayableReceivable` vinculado).

        - **`AdjustOut`** — sangrias (débitos sem `IDAccountPayableReceivable` vinculado).

        - **`TotalValueCancelled`** — diferença entre `Income` original e a soma dos pagamentos em dinheiro (usada para
        conciliar quando há vendas canceladas).

        - **`PaymentSummary`** — vendas da sessão agrupadas por **tipo de pagamento** (com descrição), incluindo os
        tipos zerados habilitados para PDV (`EnableFrenteCaixa=1`).

        - **`PaymentCategorySummary`** — vendas agrupadas por **categoria** de pagamento (Crédito, Débito, Dinheiro, Pix
        etc.).

        - **`InvoiceSummary`** — vendas agrupadas por modelo de NF emitida (`NfeModelo` = 55 NFe, 65 NFCe, ou null para
        pendentes).


        ## Recibos ZPL


        - **`ReceiptBase64Encode`** — "Fechamento de caixa" para conferência (Saldo Anterior + Total Vendas por tipo +
        Reforço + Sangria + Saldo Final).

        - **`ReceiptFiscalBase64Encode`** — "Resumo Fiscal" (Total NFCe, Total NFe, Pendentes + quantidade de cada).


        Ambos os ZPL vêm codificados em **base64 + cp850** (encoding necessário para a maioria das impressoras térmicas
        Bematech/Daruma/Epson). Use o `PrintService` (com QzTray) para enviá-los para a impressora padrão
        (`LabelReceiptDefaultPrinter`).


        ## Quando o caixa está fechado


        Mesmo com o caixa fechado, o endpoint retorna o `BankAccount` com `Balance` corrente — apenas os campos da
        sessão (`RecordTimestampOpen`, `Income`, `Outcome`, etc.) vêm vazios.


        ## Tipo de pedido padrão


        Quando a `IDTypeOrder` está nula, o sistema busca o **tipo de pedido marcado como padrão para Frente de Caixa**
        (`DefaultFrenteCaixa=1`). Se também não houver, retorna `[BadRequest] - Não existe tipo de pedido padrão para
        frente de caixa`.
      responses:
        '200':
          description: Snapshot do caixa.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StoreFrontCashierDetail'
                maxItems: 1
        '400':
          description: |-
            Erros (prefixo `[BadRequest]`):
            - `Caixa não existe`
            - `Não existe tipo de pedido padrão para frente de caixa`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /store-front/cashier/{idbankaccount}/open:
    parameters:
      - name: idbankaccount
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Conta bancária do caixa do PDV a abrir.
    post:
      operationId: storeFrontCashierOpenPost
      tags:
        - Frente de Caixa
      summary: Abre o caixa do PDV
      description: >-
        Abre uma **nova sessão** de caixa (`StoreFrontCashier`) ou **retoma** a sessão atual quando o caixa já está
        aberto pelo mesmo usuário.


        ## Pré-condições


        1. **Controle de concorrência** (TTL 10s) chaveado por `IDBankAccount` — evita abertura concorrente do mesmo
        caixa.

        2. **Conta precisa ser caixinha do PDV** — `BankNumber = '000'`. Se não for, retorna `Banco informado não é do
        tipo Caixinha`.

        3. **Tipo de pedido padrão** — `IDTypeOrder` precisa estar preenchido (configurado no cadastro da conta).

        4. **Caixa não pode estar aberto por outro usuário** — se está, retorna `Caixa já esta aberto e precisa fechar
        antes de abrir novamente`. Se for o **mesmo usuário**, a chamada é **idempotente** — retoma a sessão existente
        sem criar nova.

        5. **Usuário não pode ter outro caixa aberto** — se tem, retorna `Usuário já possui outro caixa aberto`.

        6. **Senha** — validada com `bcrypt.compare` contra a senha cadastrada do usuário. Senha errada → `Senha
        incorreta`. Usuário sem senha → `Usuário não tem senha cadastrada`.


        ## Validações condicionais (parâmetro CompanyParameter)


        Quando `CheckConfigCashierOpen = 1`, o sistema **valida configurações fiscais** antes de abrir:


        - `NfceUltima`, `NfceSerie`, `NfceCSC`, `NfceCSCid` preenchidos (campos para emissão de NFCe).

        - Existe pelo menos uma `TypeTax` com `IssueNFCe=1` para a empresa.

        - Essa `TypeTax` tem pelo menos uma configuração `StockKeepingUnitIcmsTaxInterstate` (ICMS para consumidor
        final).

        - Existe pelo menos um `TypePayment` ativo com `EnableFrenteCaixa=1`.


        Falha em qualquer um → mensagem específica (`Precisa preencher o número da última NFCe...`, `Não existe nenhuma
        regra fiscal para emissão de NFCe...`, etc.).


        ## Side-effects


        - Cria registro em `StoreFrontCashier` (ou reutiliza o existente em retomada).

        - Se `InitialBalance` difere do `Balance` atual em mais de R$ 0,01, gera lançamento
        `AccountsPayableReceivableBankStatement` com descrição **"Ajuste abertura de caixa"** (crédito se positivo,
        débito se negativo) — registra a divergência declarada pelo operador ("o caixa tinha mais/menos do que o sistema
        dizia").

        - Grava `CommentsOpen` quando preenchido.


        ## Resposta


        Retorna o caixa aberto com o **contexto operacional** (`IDStoreFrontCashier`, `RecordTimestampOpen`, `Login`,
        tipo de pedido, política comercial, armazém, faturador, flag `IssueNFCe`) — tudo que o front precisa para
        inicializar a tela do PDV.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreFrontCashierOpenBody'
        description: >-
          Abre a sessão de caixa do operador autenticado. Faz validação prévia da configuração quando a parametrização
          **Validar configurações na abertura do caixa** está ativa: checa série/numeração/CSC da NFCe no cadastro da
          empresa, regra fiscal ativa para emissão de NFCe (`IssueNFCe=1`), configuração de ICMS para consumidor final
          na regra fiscal e ao menos um tipo de pagamento habilitado no PDV (`EnableFrenteCaixa=1`). Em seguida valida a
          senha do operador via bcrypt contra a senha cadastrada do usuário. Quando o mesmo operador já tem a sessão
          aberta, a chamada é idempotente e devolve a sessão atual. Diferenças entre `InitialBalance` e o saldo
          calculado da `BankAccount` geram lançamento `Ajuste abertura de caixa` no extrato bancário. Bloqueios comuns:
          caixa de outro operador já aberto, banco que não é caixinha (`BankNumber != '000'`), banco sem tipo de pedido
          padrão, usuário sem senha cadastrada. Controle de concorrência (TTL 10s, chaveado por `IDBankAccount`) evita
          aberturas simultâneas do mesmo caixa.
      responses:
        '200':
          description: Caixa aberto (ou retomado). Resposta inclui o contexto operacional para inicializar o PDV.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StoreFrontCashierOpenResponse'
                maxItems: 1
        '400':
          description: >-
            Erros (prefixo `[BadRequest]`):

            - `Caixa já esta em processo de abertura` (controle de concorrência)

            - `Caixa não existe`

            - `Banco informado não é do tipo Caixinha`

            - `Banco informado não tem tipo de pedido padrão cadastrado`

            - `Caixa já esta aberto e precisa fechar antes de abrir novamente`

            - `Usuário não localizado`

            - `Usuário não tem senha cadastrada`

            - `Senha incorreta`

            - `Usuário já possui outro caixa aberto`

            - `Erro ao abrir caixa. Verificar se o mesmo já esta aberto`

            - `Não existe tipo de pedido padrão para frente de caixa`

            - Validações fiscais (com `CheckConfigCashierOpen=1`): `Precisa preencher o número da última NFCe...`,
            `Precisa preencher a séria da NFCe...`, `Precisa preencher ID CSC...`, `Precisa preencher código de
            contribuinte...`, `Não existe nenhuma regra fiscal para emissão de NFCe...`, `Não existe nenhuma configração
            de ICMS na regra fiscal para consumidor final`, `Não existe tipo de pagamento configurado para frente de
            caixa`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /store-front/cashier/{idbankaccount}/close:
    parameters:
      - name: idbankaccount
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Conta bancária do caixa a fechar.
    post:
      operationId: storeFrontCashierClosePost
      tags:
        - Frente de Caixa
      summary: Fecha o caixa do PDV
      description: >-
        Fecha a sessão atual do caixa, gravando `RecordTimestampClose` com o momento do fechamento.


        ## Validações


        - Caixa precisa estar **aberto** — se não, retorna `Caixa não esta aberto e precisa abrir antes de fechar`.

        - **Senha** validada com bcrypt — `Senha incorreta` se errada, `Usuário não tem senha cadastrada` se vazia.

        - Usuário precisa existir (`Usuário não localizado` se não bate com a empresa).


        ## Side-effects


        - Se `FinalBalance` difere do `Balance` atual em mais de R$ 0,01, gera lançamento
        `AccountsPayableReceivableBankStatement` com descrição **"Ajuste fechamento de caixa"** (crédito ou débito
        conforme o sinal) — registra a divergência apurada pelo operador na conferência física ("contei R$ 850 mas o
        sistema dizia R$ 870").

        - Grava `CommentsClose` quando preenchido.

        - A frente normalmente exige **obrigatório** o campo `Comments` quando há divergência (`FinalBalance !=
        Balance`).


        O caixa não permite ser fechado se ainda há **pedido em montagem** ou **transação TEF em aberto** — o front
        bloqueia o botão de fechamento quando `listItems.length > 0`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreFrontCashierCloseBody'
        description: >-
          Encerra a sessão de caixa atual (gravando `RecordTimestampClose`). A senha do operador autenticado é validada
          via bcrypt. Quando `FinalBalance` difere em mais de R$ 0,01 do saldo calculado, gera um lançamento `Ajuste
          fechamento de caixa` no extrato bancário (entrada se sobrou, saída se faltou). Falha quando a sessão não está
          aberta.
      responses:
        '200':
          description: 'Caixa fechado. Resposta: string `Sucesso`.'
          content:
            application/json:
              schema:
                type: string
                example: Sucesso
        '400':
          description: |-
            Erros (prefixo `[BadRequest]`):
            - `Caixa não existe`
            - `Caixa não esta aberto e precisa abrir antes de fechar`
            - `Usuário não localizado`
            - `Usuário não tem senha cadastrada`
            - `Senha incorreta`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /store-front/cashier/{idbankaccount}/adjust:
    parameters:
      - name: idbankaccount
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Conta bancária do caixa.
    post:
      operationId: storeFrontCashierAdjustPost
      tags:
        - Frente de Caixa
      summary: Sangria ou reforço de caixa
      description: >-
        Registra uma **sangria** (saída de dinheiro do caixa para o cofre/banco, `Type=2`) ou **reforço** (entrada de
        dinheiro no caixa, geralmente troco, `Type=1`).


        ## Validações


        - Caixa precisa estar **aberto** — `Caixa não esta aberto e não pode ter sangria/reforço` caso contrário.

        - Senha do usuário validada via bcrypt.

        - **Sangria não pode ultrapassar o saldo** — se `Balance - Value < 0`, retorna `Sangria não pode ser realizada,
        pois valor é maior que disponível`.

        - Campo `Type` é **obrigatório** — se omitido, retorna `Precisa informar o Type (1 - reforço, 2 - sangria)`.


        ## Side-effects


        - Cria lançamento em `AccountsPayableReceivableBankStatement` com:
          - `IDTypeAccount = 0` (crédito) para reforço, `1` (débito) para sangria.
          - `TransactionDescription = "Reforço: <Comments>"` ou `"Sangria: <Comments>"`.
          - `IDStoreFrontCashier` vinculado à sessão atual.

        ## Recibo ZPL


        A resposta inclui um **recibo ZPL** (`ReceiptBase64Encode`, base64 + cp850) com cabeçalho da empresa, operador,
        tipo (REFORÇO/SANGRIA), valor formatado em R$, data/hora, caixa e observações. O recibo tem espaço para
        assinatura do responsável e é impresso automaticamente pelo PDV (geralmente em 2 vias — uma fica com o operador,
        outra com quem recebeu o dinheiro retirado).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreFrontCashierAdjustBody'
        description: >-
          Registra reforço (`Type=1`, entrada de dinheiro) ou sangria (`Type=2`, retirada de dinheiro) no caixa aberto,
          gravando um lançamento em `AccountsPayableReceivableBankStatement` com a descrição `Reforço: <Comments>` ou
          `Sangria: <Comments>`. A senha do operador é validada via bcrypt. Sangria que excede o saldo disponível é
          rejeitada. A resposta inclui o recibo do operador em `ReceiptBase64Encode` (texto cp850 + base64) pronto para
          a impressora.
      responses:
        '200':
          description: Sangria/reforço registrado. Retorna o ZPL do recibo.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ReceiptBase64Encode:
                    type: string
                    format: byte
                    description: ZPL do recibo (base64 + cp850).
        '400':
          description: |-
            Erros (prefixo `[BadRequest]`):
            - `Precisa informar o Type (1 - reforço, 2 - sangria)`
            - `Caixa não existe`
            - `Caixa não esta aberto e não pode ter sangria/reforço`
            - `Sangria não pode ser realizada, pois valor é maior que disponível`
            - `Usuário não localizado`
            - `Usuário não tem senha cadastrada`
            - `Senha incorreta`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /store-front/cashier/{idbankaccount}/order-temp:
    parameters:
      - name: idbankaccount
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Conta bancária do caixa.
    get:
      operationId: storeFrontCashierOrderTempGet
      tags:
        - Frente de Caixa
      summary: Lista rascunhos de pedido do caixa
      description: >-
        Lista os **rascunhos de pedido** (`StoreFrontCashierOrderTemp`) salvos no caixa. Esses rascunhos são **gerados
        automaticamente** pelo motor de promoções `POST /sku/promotion/order/validate` a cada alteração do carrinho —
        funcionam como um "backup" do estado do PDV para permitir **retomar uma venda interrompida** em outro terminal.


        Cada item tem o `OrderData` (JSON parseado) com a estrutura completa do carrinho: itens, cliente, pagamentos,
        tipo de pedido, política comercial, vendedor, etc.


        A tela usa esses rascunhos no menu **Rascunho de Pedido** — o operador pode escolher um rascunho e o sistema
        **restaura todo o estado** da venda (chama internamente `startOrderByTemp`).
      responses:
        '200':
          description: Lista de rascunhos com `OrderData` em JSON parseado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StoreFrontCashierOrderTempItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /store-front/cashier/{idbankaccount}/order-temp/{idstorefrontcashierordertemp}:
    parameters:
      - name: idbankaccount
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Conta bancária do caixa.
      - name: idstorefrontcashierordertemp
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do rascunho.
    delete:
      operationId: storeFrontCashierOrderTempDelete
      tags:
        - Frente de Caixa
      summary: Apaga um rascunho de pedido
      description: >-
        Remove fisicamente o rascunho de venda. Usado pelo PDV quando o operador descarta uma venda ou quando o pedido é
        efetivamente finalizado (`POST /orders`).
      responses:
        '200':
          description: 'Rascunho removido. Resposta: string `sucesso`.'
          content:
            application/json:
              schema:
                type: string
                example: sucesso
        '400':
          description: 'Rascunho não encontrado. Mensagem: `[BadRequest] - Rascunho pedido não encontrado`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /company/label:
    get:
      operationId: typeCompanyLabelList
      tags:
        - Etiquetas (Empresa)
      summary: Lista modelos de etiqueta
      description: >-
        Retorna os modelos de etiqueta cadastrados pela empresa, ordenados pelo nome (`LabelName`), limitados a **3000
        itens** por chamada. Aceita filtros por categoria (`IDTypeLabelCategory`) e por identificador único
        (`IDCompanyLabel`). Cada item traz as dimensões, o código ZPL bruto (quando o modelo foi escrito em modo ZPL) e
        o nome da categoria já resolvido.
      parameters:
        - name: IDTypeLabelCategory
          in: query
          required: false
          schema:
            type: integer
          description: >-
            Filtra por categoria da etiqueta (`TypeLabelCategory`). Valores conhecidos: 1=Embarque (adicional
            transportadora), 2=Itens (recebimento), 3=Endereços, 4=Itens (cadastro), 5=Transportadora (embarque),
            6=Cesto Picking, 7=Transportadora (cadastro), 8=Ressuprimento pendente, 9=Inconformidade picking/packing.
        - name: IDCompanyLabel
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por identificador único da etiqueta.
        - name: Page
          in: query
          required: false
          schema:
            type: integer
          description: >-
            Reservado (lido do query mas sem efeito no caminho atual — todos os itens já vêm na mesma chamada, até
            3000).
      responses:
        '200':
          description: Lista de modelos de etiqueta.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyLabelListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: typeCompanyLabelPost
      tags:
        - Etiquetas (Empresa)
      summary: Cadastra um modelo de etiqueta
      description: >-
        Cria um modelo de etiqueta na empresa autenticada. `IDTypeLabelCategory` precisa existir na tabela de categorias
        do sistema. `EditorMode` controla a forma como o modelo é desenhado: `1` (default) é o modo **Canvas** —
        interface visual com variáveis e elementos drag-and-drop; `2` é o modo **ZPL** — código bruto colado no editor.
        A resposta é a lista de etiquetas filtrada pelo id recém-criado (mesmo formato de `GET
        /company/label?IDCompanyLabel=<novo>`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyLabelCreate'
        description: >-
          Dados do modelo de etiqueta. Obrigatórios: `LabelName`, `IDTypeLabelCategory`, `HeightCm`, `WidthCm`. Quando
          `EditorMode=2` (ZPL), o campo `LabelZpl` é obrigatório; no modo Canvas (1, default) o ZPL é gerado pelo front
          a partir do layout visual.
      responses:
        '200':
          description: Modelo criado. Retorna a etiqueta recém-cadastrada (array com 1 item, mesmo formato da listagem).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyLabelListItem'
                maxItems: 1
        '400':
          description: |-
            Erros de validação (prefixo `[BadRequest]`):
            - `Empresa não existe`
            - `Tipo etiqueta não existe`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /company/label/{idcompanylabel}:
    parameters:
      - name: idcompanylabel
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do modelo de etiqueta.
    put:
      operationId: typeCompanyLabelPut
      tags:
        - Etiquetas (Empresa)
      summary: Atualiza um modelo de etiqueta
      description: >-
        Atualiza parcialmente o modelo — apenas os campos enviados são alterados. Quando `IDTypeLabelCategory` for
        informado, precisa existir na tabela de categorias. A resposta é a etiqueta atualizada no mesmo formato da
        listagem.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyLabelUpdate'
        description: Campos do modelo de etiqueta a atualizar. Atualização parcial — apenas os campos enviados são alterados.
      responses:
        '200':
          description: Modelo atualizado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyLabelListItem'
                maxItems: 1
        '400':
          description: |-
            Erros de validação (prefixo `[BadRequest]`):
            - `Etiqueta não existe`
            - `Tipo etiqueta não existe`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: typeCompanyLabelDelete
      tags:
        - Etiquetas (Empresa)
      summary: Exclui um modelo de etiqueta
      description: >-
        **Exclusão física** — diferente de outros cadastros do idworks, o modelo é apagado definitivamente do banco.
        Transportadoras e fornecedores que apontavam para essa etiqueta via `IDCompanyLabel` passam a ter o vínculo
        quebrado (o id deixa de existir). A resposta é a string `"Sucesso"` (com S maiúsculo).
      responses:
        '200':
          description: Modelo excluído. Retorna a string `"Sucesso"`.
          content:
            application/json:
              schema:
                type: string
                enum:
                  - Sucesso
        '400':
          description: |-
            Erros (prefixo `[BadRequest]`):
            - `Etiqueta não existe`
            - `Erro ao deletar etiqueta`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /webhook:
    get:
      operationId: webhookList
      tags:
        - Logs de Webhook
      summary: Lista logs de envio de webhook
      description: >-
        Retorna o histórico de tentativas de envio de webhook da empresa, do mais recente para o mais antigo. Cada item
        representa **uma tentativa** de envio identificada pelo `UUID` da mensagem SQS — o campo `Attempts` indica
        quantas vezes a tentativa foi retentada. Aceita filtros opcionais por `Topic`, `Status`, faixa de data e
        paginação (2000 registros por página).


        Fluxo de origem dos registros: quando uma ação habilitada no idworks ocorre (criar SKU, emitir NF, atualizar
        tracking, etc.), o sistema enfileira a notificação para envio ao webhook. O consumidor (`webhookPost`) lê a
        fila, consulta o endpoint e as credenciais configuradas para a empresa na integração `Webhook`
        (`IDTypeCompanyIntegration=52`), faz `POST` no endpoint do cliente com timeout de 10s e grava o resultado nesta
        tabela (`Status = 1` em sucesso, `Status = 0` em erro). Falhas voltam para a fila e incrementam `Attempts` na
        próxima tentativa.
      parameters:
        - name: Page
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: 'Página (zero-based). Cada página devolve no máximo 2000 itens. Default: 0.'
        - name: Topic
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo nome técnico do tópico (`SkuPost`, `InvoiceIssue`, `OrderStatus`, etc.). Match exato.
        - name: Status
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: 'Filtra pelo status do envio: `1` = sucesso (o destino respondeu 2xx), `0` = erro.'
        - name: DateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data inicial (inclusive) do `RecordTimestamp`. Combina com `DateTo`.
        - name: DateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data final do `RecordTimestamp`, inclusivo até `23:59:59`. Combina com `DateFrom`.
      responses:
        '200':
          description: Lista de tentativas (até 2000 por página).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WebhookLogListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /user/privilege-group:
    get:
      operationId: userPrivilegeGroupList
      tags:
        - Perfis de Acesso
      summary: Lista perfis de acesso
      description: >-
        Retorna os perfis de acesso (grupos de privilégios) ativos da empresa, ordenados pelo nome. Quando a empresa
        autenticada é a `all` (multi-conta), retorna os perfis de todas as empresas vinculadas.
      responses:
        '200':
          description: Lista de perfis.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserPrivilegeGroupListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: userPrivilegeGroupPost
      tags:
        - Perfis de Acesso
      summary: Cadastra um perfil de acesso
      description: >-
        Cria um perfil **vazio** para a empresa autenticada — só com o nome. Para atribuir os privilégios, chame em
        seguida `POST /user/privilege-group/{idprivilegegroup}/resource` com a lista de `IDUserPrivilege`. A resposta é
        o detalhe do perfil recém-criado, no formato de `GET /user/privilege-group/{idprivilegegroup}`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserPrivilegeGroupCreate'
        description: >-
          Perfil de acesso a cadastrar. Apenas `PrivilegeGroupName` é obrigatório. O perfil nasce sem privilégios — use
          `POST /user/privilege-group/{idprivilegegroup}/resource` para atribuir a lista de privilégios depois.
      responses:
        '200':
          description: Perfil criado. Devolve o detalhe (lista de módulos/privilégios atribuídos — vazia logo após o POST).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserPrivilegeGroupDetail'
        '400':
          description: 'Empresa não localizada. Mensagem: `[BadRequest] - Company não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /user/privilege-group/{idprivilegegroup}:
    parameters:
      - name: idprivilegegroup
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do perfil de acesso.
    get:
      operationId: userPrivilegeGroupGet
      tags:
        - Perfis de Acesso
      summary: Detalha um perfil com os privilégios atribuídos
      description: >-
        Retorna os **privilégios atribuídos** ao perfil, agrupados por área do menu (`ModuleGroupDescription`) e, dentro
        de cada área, por módulo (`ModuleDescription`). **Não devolve** privilégios disponíveis que não foram atribuídos
        — a tela do frontend cruza este resultado com `GET /company/module` (catálogo completo) para mostrar os
        checkboxes marcados e desmarcados.


        Quando o perfil ainda está vazio (logo após o `POST`), a resposta é `[]`.
      responses:
        '200':
          description: Detalhe do perfil. Array de áreas, cada uma com a lista de módulos do perfil e seus privilégios.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserPrivilegeGroupDetail'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    put:
      operationId: userPrivilegeGroupPut
      tags:
        - Perfis de Acesso
      summary: Renomeia um perfil de acesso
      description: >-
        Atualiza **apenas o nome** do perfil (`PrivilegeGroupName`). Para alterar os privilégios atribuídos, use `POST
        /user/privilege-group/{idprivilegegroup}/resource`. A resposta é o detalhe do perfil atualizado (mesmo formato
        do `GET`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserPrivilegeGroupUpdate'
        description: Atualiza apenas o nome do perfil (`PrivilegeGroupName`).
      responses:
        '200':
          description: Perfil renomeado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserPrivilegeGroupDetail'
        '400':
          description: 'Perfil não encontrado para a empresa. Mensagem: `[BadRequest] - Privelege Group não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: userPrivilegeGroupDelete
      tags:
        - Perfis de Acesso
      summary: Exclui (inativa) um perfil de acesso
      description: >-
        Inativa o perfil (`UserPrivilegeGroupStatus = 0`) e **remove fisicamente** todos os vínculos com privilégios
        (`UserPrivilegeGroupResource`). A exclusão é **bloqueada** quando o perfil ainda está vinculado a algum usuário
        (`UserPrivilege`) — nesse caso é preciso primeiro desvincular o perfil de cada usuário em **Configurações →
        Usuários**.


        A resposta é a lista atualizada dos perfis ativos (mesmo formato do `GET /user/privilege-group`).
      responses:
        '200':
          description: Perfil inativado. Devolve a lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserPrivilegeGroupListItem'
        '400':
          description: >-
            Perfil não encontrado ou ainda vinculado a usuários. Mensagens: `[BadRequest] - Grupo privilégio não
            existe`; `[BadRequest] - Perfil de acesso esta vinculado a usuários e não pode ser excluído`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /user/privilege-group/{idprivilegegroup}/resource:
    parameters:
      - name: idprivilegegroup
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do perfil de acesso.
    post:
      operationId: userPrivilegeGroupResourcePost
      tags:
        - Perfis de Acesso
      summary: Substitui a lista de privilégios do perfil
      description: >-
        Sobrescreve a lista de privilégios atribuídos ao perfil — **não é incremento**. O body é um array com os
        identificadores (`IDUserPrivilege`) que devem ficar atribuídos: tudo que estava antes e não está no array é
        removido, tudo que está no array passa a ser atribuído.


        A cada chamada o sistema:

        1. Grava um registro de auditoria em `UserPrivilegeGroupLog` com o usuário, o `Data` enviado e o id do perfil.

        2. Apaga todas as linhas de `UserPrivilegeGroupResource` do perfil e insere a nova lista.

        3. Devolve o detalhe do perfil atualizado.


        > A alteração só passa a valer para o usuário **depois que ele faz logout e login de novo** no sistema — a
        sessão ativa ainda guarda os privilégios anteriores.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: integer
                format: int32
              description: >-
                Array de `IDUserPrivilege` que devem ficar atribuídos ao perfil. Pode ser vazio para deixar o perfil sem
                nenhum privilégio.
        description: >-
          Array de `IDUserPrivilege` que devem ficar atribuídos ao perfil. Sobrescreve a lista existente — não é
          incremento. Aceita array vazio para deixar o perfil sem nenhum privilégio. A alteração só vale para o usuário
          no próximo login (a sessão atual ainda mantém os privilégios anteriores).
      responses:
        '200':
          description: Privilégios atualizados. Devolve o detalhe do perfil.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserPrivilegeGroupDetail'
        '400':
          description: 'Perfil não encontrado. Mensagem: `[BadRequest] - Privilegio não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /job:
    get:
      operationId: jobsResultList
      tags:
        - Jobs e Tarefas
      summary: Lista jobs de ação em massa
      description: >-
        Retorna os jobs disparados pela empresa, do mais recente para o mais antigo. Cada item traz o tipo da ação
        (`TypeJob`) e o login do usuário que criou. Aceita filtro opcional por `IDTypeJob`. Quando a empresa autenticada
        é a `all` (multi-conta), retorna jobs de todas as empresas vinculadas.
      parameters:
        - name: IDTypeJob
          in: query
          required: false
          schema:
            type: integer
          description: >-
            Filtra pelo tipo da ação (`IDTypeJob`). Ex.: 1=Criar sku/produto, 3=Criar pedido, 6=Criar Contas a pagar,
            7=Criar Contas a receber, 38=Importar extrato OFX, 41=Importar conciliação adquirente.
      responses:
        '200':
          description: Lista de jobs.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/JobListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: jobsResultPost
      tags:
        - Jobs e Tarefas
      summary: Dispara um job de ação em massa (upload de planilha)
      description: >-
        Cria um job para processar em lote a ação indicada por `IDTypeJob`. O sistema:


        1. Valida o `IDTypeJob` contra o catálogo de `TypeJob` (cada tipo sabe processar um formato de planilha —
        importação de SKU, de pedidos, etc.).

        2. Faz upload do arquivo enviado (multipart `file`, até 5 MB no frontend) para o armazenamento temporário e
        calcula o **hash SHA-256** do conteúdo.

        3. Se já existe um job da mesma empresa com o **mesmo hash** ainda em processamento, **reaproveita** o job
        existente e retorna o `IDJob` atual sem disparar de novo — bloqueio anti-duplicação.

        4. Caso contrário, registra um novo job e dispara o processamento de forma **assíncrona**.

        5. Devolve `IDJob` ao cliente. O resultado real é gravado linha-a-linha e o usuário recebe a confirmação por
        e-mail. Acompanhe via `GET /job/{idjob}`.
      parameters:
        - name: IDTypeJob
          in: query
          required: true
          schema:
            type: integer
          description: >-
            Identificador do tipo de ação. Define qual rotina processa o arquivo. Lista completa em `TypeJob` — ex.:
            1=Criar sku/produto, 3=Criar pedido, 6=Criar Contas a pagar, 7=Criar Contas a receber, 38=Importar extrato
            OFX, 41=Importar conciliação adquirente.
        - name: IDBankAccount
          in: query
          required: false
          schema:
            type: integer
          description: >-
            **Obrigatório quando `IDTypeJob = 38`** (Importar extrato OFX). Identificador da conta bancária de destino.
            Vai como `Metadata` do job.
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
          description: >-
            **Obrigatório quando `IDTypeJob = 41`** (Importar conciliação adquirente). Identificador da integração de
            adquirente. Vai como `Metadata` do job.
        - name: IDSupplier
          in: query
          required: false
          schema:
            type: integer
          description: >-
            Usado por algumas ações de tabela de frete (`IDTypeJob` 4, 5, 10). Vai como `Metadata` do job junto com o
            nome do arquivo.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: >-
                    Planilha `.xlsx` ou `.xls` com os dados a importar. Até 5 MB. O modelo da planilha de cada tipo é
                    baixado em `TemplateUrl` (quando preenchido).
        description: >-
          Upload `multipart/form-data` com o campo `file` contendo a planilha (XLSX/CSV, até 5 MB). O tipo da ação é
          definido por `IDTypeJob` na query. O sistema grava o arquivo em armazenamento temporário, calcula um hash
          SHA-256 do conteúdo e, se já existe um job em processamento com o mesmo hash para a empresa, reaproveita o
          `IDJob` existente — bloqueio anti-duplicação. Caso contrário, dispara o processamento associado de forma
          assíncrona.
      responses:
        '200':
          description: >-
            Job criado (ou reaproveitado). Devolve `IDJob` para acompanhamento. O processamento é assíncrono — o
            resultado vem por e-mail e pode ser acompanhado em `GET /job/{idjob}`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobPostResponse'
        '400':
          description: >-
            Falha de validação. Mensagens possíveis: `[BadRequest] - Ação não encontrada` (IDTypeJob inválido);
            `[BadRequest] - Erro ao processar ação em massa` (combinação rota/tipo não mapeada); `[BadRequest] -
            IDBankAccount é obrigatório`; `[BadRequest] - IDCompanyIntegration é obrigatório`. Também devolve **400 sem
            corpo** quando o `file` está ausente para uma ação que exige arquivo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '404':
          description: Empresa do `accountname` não localizada (404 sem corpo).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /job/{idjob}:
    parameters:
      - name: idjob
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do job.
    get:
      operationId: jobsResultGet
      tags:
        - Jobs e Tarefas
      summary: Detalha um job com os resultados linha-a-linha
      description: >-
        Retorna o cabeçalho do job (datas, usuário, tipo, etc.) e o array `Result` com **uma entrada por linha**
        processada — cada uma com a aba (`Sheet`), o número da linha (`Line`), o status (`1` = sucesso, `0` = erro), a
        descrição da ação ou do erro, e o id e nome do recurso afetado. A resposta também traz uma **URL pré-assinada**
        (`UrlFile`) para baixar o arquivo enviado (válida por 2 dias).


        Paginação por `Page` (5000 linhas de resultado por página). Quando o id não pertence à empresa autenticada,
        devolve `[]`.
      parameters:
        - name: Page
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: >-
            Página zero-based para a lista de resultados (`Result`). Cada página devolve no máximo 5000 linhas. Default:
            0.
      responses:
        '200':
          description: Detalhe do job (array com 1 item) ou `[]` quando o id não pertence à empresa.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/JobDetail'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /company/integration:
    get:
      operationId: companyParameterList
      tags:
        - Integrações
      summary: Lista as integrações da empresa
      description: >-
        Retorna as integrações configuradas pela empresa (`CompanyIntegration`) com o tipo já resolvido (logo, nome,
        categoria) e o nível de reputação consolidado a partir das parametrizações. Aceita filtros opcionais por
        categoria, tipo, identificador, status e flag de gift card. Quando a empresa autenticada é a `all`
        (multi-conta), retorna integrações de todas as empresas vinculadas.
      parameters:
        - name: IDTypeCompanyIntegrationCategory
          in: query
          required: false
          schema:
            type: string
          description: >-
            Filtra por categoria do tipo de integração. Aceita um id único ou uma lista separada por vírgula (ex.:
            `1,4`). Categorias usuais: 1=Canal de Venda, 2=Gateway, 3=Transportadora, 4=Adquirente, 9=Banco. Outras:
            7=ERP, 8=WMS, 10=Hub, 14=Plataformas de e-commerce.
        - name: IDTypeCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
          description: >-
            Filtra por tipo de integração (`IDTypeCompanyIntegration`). Ex.: 10=Mercado Livre, 16=idworks, 50=Correios,
            131=Stark Bank.
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por identificador específico da integração da empresa.
        - name: Status
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
              - 2
              - 3
          description: 'Filtra pelo status da integração: `1`=Ativo, `2`=Erro de autenticação, `3`=Não autenticado, `0`=Inativo.'
        - name: GiftCard
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Filtra pela flag `GiftCard` (tipos voltados a vale-presente).
      responses:
        '200':
          description: Lista de integrações.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyIntegrationListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: companyParameterPost
      tags:
        - Integrações
      summary: Cria uma integração da empresa
      description: >-
        Cadastra uma nova `CompanyIntegration` para a empresa autenticada, partindo de um tipo
        (`IDTypeCompanyIntegration`).


        O **status inicial** depende do tipo:

        - Se o tipo tem parametrização com `Key = "Validate"` no catálogo, a integração nasce com `Status = 3` (**Não
        Autenticado**). É preciso passar pelo fluxo de autenticação para virar `Ativo`.

        - Caso contrário, nasce com `Status = 1` (**Ativo**) direto.


        Devolve o detalhe da integração recém-criada (formato de `GET /company/integration/{idcompanyintegration}`),
        pronto para preencher as parametrizações.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyIntegrationCreate'
        description: >-
          Dados da integração a cadastrar. `IDTypeCompanyIntegration` aponta para o catálogo de tipos disponíveis
          (canais de venda como Mercado Livre, Shopee, VTEX; adquirentes como Cielo, Rede; transportadoras; bancos;
          etc.). Após criar, as credenciais e demais opções devem ser informadas via `PUT
          /company/integration/{idcompanyintegration}/parameter`.
      responses:
        '200':
          description: Integração criada. Devolve o detalhe (array de parametrizações, vazio até preencher).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyIntegrationParameter'
        '400':
          description: >-
            Erros de validação. Mensagens: `[BadRequest] - Tipo integração não existe`; `[BadRequest] - Empresa não
            existe`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /company/integration/{idcompanyintegration}:
    parameters:
      - name: idcompanyintegration
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador da integração.
    put:
      operationId: companyIntegrationPut
      tags:
        - Integrações
      summary: Atualiza nome e status de uma integração
      description: >-
        Atualiza o **nome** (`CompanyIntegrationName`) e o **status** (`Status`) da integração. Os outros dados (tipo,
        parametrizações) ficam intocados.


        A resposta repete o detalhe da integração (mesmo formato do `GET`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyIntegrationUpdate'
        description: >-
          Atualiza os atributos administrativos da integração (nome amigável e status). Para alterar
          credenciais/configurações use `PUT /company/integration/{idcompanyintegration}/parameter`.
      responses:
        '200':
          description: Integração atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyIntegrationParameter'
        '400':
          description: 'Integração não encontrada. Mensagem: `[BadRequest] - Integração não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: companyIntegrationDelete
      tags:
        - Integrações
      summary: Exclui (inativa) uma integração
      description: >-
        Inativa a integração (`Status = 0`, `Show = 0`) e **remove fisicamente**:

        - Todas as parametrizações (`CompanyParameters`).

        - Todos os mapas de Hub (`HubCategory`, `HubBrand`, `HubCarrier`, `HubPayment`, `HubSalesPolicy`,
        `HubVariation`, `HubWarehouse`).


        Exclusão é **bloqueada** por categoria:

        - **Transportadora** (categoria 3): bloqueia quando há fornecedor ativo com esta integração — fornecedores
        inativos são desvinculados (limpa `IDCompanyIntegration`).

        - **Gateway / Adquirente / Banco** (categorias 2, 4, 9 — respectivamente Gateway, Adquirente, Banco): bloqueia
        quando há conta bancária ativa vinculada — contas inativas são desvinculadas.

        - **Anúncios**: bloqueia quando há `HubProduct` apontando para esta integração — é preciso excluir os anúncios
        antes.


        A resposta é a lista atualizada das integrações (mesmo formato do `GET /company/integration`).
      responses:
        '200':
          description: Integração inativada. Devolve a lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyIntegrationListItem'
        '400':
          description: >-
            Integração não encontrada ou bloqueada por vínculo. Mensagens: `[BadRequest] - Integração não existe`;
            `[BadRequest] - Existe fornecedor vinculado a essa integração, remover antes de excluir a integração`;
            `[BadRequest] - Existe conta bancária vinculada a essa integração, remover antes de excluir a integração`;
            `[BadRequest] - Integração possui anúncios, excluir antes de deletar a integração`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /company/integration/{idcompanyintegration}/check:
    parameters:
      - name: idcompanyintegration
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador da integração.
    get:
      operationId: companyIntegrationCheckGet
      tags:
        - Integrações
      summary: Verifica credenciais de uma integração
      description: >-
        Faz uma checagem síncrona das credenciais configuradas para a integração no sistema externo. A verificação é
        roteada conforme o tipo da integração — Correios (tipo 50), E-mail (tipo 51) e os demais canais de venda, cada
        um pelo seu conector próprio.


        A resposta é o que o serviço de integração devolver — geralmente um JSON com `Status`, `Message` e detalhes do
        diagnóstico. Use para confirmar, antes de salvar parametrizações, que as credenciais respondem ao canal externo.
      responses:
        '200':
          description: Resultado da checagem retornado pelo serviço de integração (formato varia por integração).
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                description: >-
                  Conteúdo bruto da resposta do serviço de integração. Tipicamente inclui status e mensagem do
                  diagnóstico.
        '400':
          description: >-
            Falha de roteamento ou integração inválida. Mensagens: `[BadRequest] - Integração não encontrada`;
            `[BadRequest] - Integracão não tem consulta de status` (tipo não suporta check ou serviço de integração
            devolveu 404); mensagem do serviço de integração em outros casos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /company/integration/{idcompanyintegration}/parameter:
    parameters:
      - name: idcompanyintegration
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador da integração.
    get:
      operationId: companyParameterGet
      tags:
        - Integrações
      summary: Lista as parametrizações da integração
      description: >-
        Devolve o catálogo de parametrizações do tipo da integração cruzado com os valores já gravados pela empresa — é
        o que a tela usa para montar o formulário de configuração, agrupado por `TypeCompanyParametersGroup`.


        Detalhes do retorno:


        - Só vêm parametrizações com `Type` diferente de `hidden`, ordenadas por `ParameterOrder`.

        - Para `Type` `list`/`multi_list`, o campo `List` traz as opções disponíveis (itens de tabelas-tipo, planos de
        contas, contas bancárias, status, etc., conforme a `Key`).

        - Para `Type` `string_copy`/`url_get`, o campo `Value` pode ser **calculado** (ex.: URL de webhook/leilão de
        frete personalizada para a empresa, com tokens embutidos), em vez do valor cru gravado.


        **Modo alternativo** — quando `Type=ImportOffer`, o endpoint não retorna parametrizações: devolve o último job
        de importação de anúncios da integração com o progresso (`QuantityProcessed`, `QuantityPending`,
        `QuantityTotal`).
      parameters:
        - name: Type
          in: query
          required: false
          schema:
            type: string
          description: >-
            Modo de consulta. Em branco (padrão) retorna as parametrizações. Com `ImportOffer`, retorna o progresso do
            último job de importação de anúncios da integração.
      responses:
        '200':
          description: >-
            Lista de parametrizações da integração (ou, quando `Type=ImportOffer`, o progresso do último job de
            importação). Array vazio quando não há registros.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyIntegrationParameter'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    put:
      operationId: companyParameterPut
      tags:
        - Integrações
      summary: Atualiza as parametrizações da integração
      description: >-
        Sobrescreve (upsert) os valores das parametrizações da integração. O body é um **array** de `{Key, Value}`. Para
        cada item:


        1. Valida que a `Key` é uma parametrização válida do tipo da integração (`TypeCompanyParameters` com `Type`
        diferente de `hidden`, `string_copy` e `url_validate`).

        2. Faz upsert em `CompanyParameters` (chave única `IDCompanyIntegration + Key`).

        3. Grava o evento em `CompanyParametersLog` com o usuário autenticado e o body inteiro como `Data`.


        Não é necessário enviar todas as parametrizações — só as que mudaram. A resposta é o detalhe atualizado (mesmo
        formato do `GET`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CompanyParameterValue'
              description: Lista de pares chave/valor a gravar/atualizar.
        description: >-
          Mapa de parametrizações da integração no formato `{ "<Key>": <valor>, ... }`, onde cada `<Key>` corresponde ao
          campo `Key` retornado por `GET /company/integration/{idcompanyintegration}/parameter` (ex.: `EndPoint`,
          `HeaderKeyAuth`, `TagBusiness`, `GnreIDTypeDocument`, `IDCompanyInvoice`). Tipos:
          `string`/`password`/`string_copy` → string; `boolean`/`checkbox` → `0` ou `1`; `list` → o `Value` da opção
          escolhida; `multi_list` → array de `Value`. Faz upsert: chaves enviadas substituem o valor atual; chaves
          omitidas permanecem inalteradas.
      responses:
        '200':
          description: Parametrizações atualizadas.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyIntegrationParameter'
        '400':
          description: 'Integração não encontrada. Mensagem: `[BadRequest] - Integração não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /company/integration/{idcompanyintegration}/parameter/import:
    parameters:
      - name: idcompanyintegration
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador da integração.
    post:
      operationId: companyParameterImportPost
      tags:
        - Integrações
      summary: Dispara importação automática de anúncios
      description: >-
        Dispara a importação automática de anúncios do canal de venda configurado (`idcompanyintegration`), repassando
        os demais parâmetros recebidos na query. Usado pela tela de importação direto do canal para popular a área
        temporária de produtos importados da integração.


        A resposta é o que o serviço de integração devolver (geralmente confirmação de enfileiramento).
      responses:
        '200':
          description: Resposta do serviço de integração (formato varia).
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                description: >-
                  Resposta da importação de parâmetros — o formato varia por canal (geralmente confirmação de
                  enfileiramento).
        '400':
          description: Falha do serviço de integração. Devolve o `errorMessage` recebido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/production:
    get:
      operationId: skuProductionList
      tags:
        - Produção
      summary: Lista ordens de produção
      description: >-
        Retorna as ordens de produção da empresa, com SKU produzido, armazém, status, pedido vinculado (quando há) e
        dados do usuário criador. Aceita filtros por id, SKU, status e faixa de data de cadastro.
      parameters:
        - name: IDStockKeepingUnitProduction
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por id específico da OP.
        - name: IDSku
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo SKU produzido.
        - name: IDSkuCompany
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo código externo do SKU (`IDSkuCompany`).
        - name: IDTypeStatusSkuProduction
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 3
              - 4
          description: 'Filtra pelo status: 1=Finalizado, 2=Aberto, 3=Em andamento, 4=Cancelado.'
        - name: DateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Faixa inicial de `RecordTimestamp` (cadastro).
        - name: DateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Faixa final de `RecordTimestamp`, inclusivo até `23:59:59`.
      responses:
        '200':
          description: Lista de ordens de produção.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProductionListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: skuProductionPost
      tags:
        - Produção
      summary: Cria uma ordem de produção
      description: >-
        Cria uma OP para um SKU configurado como `OwnProduction = 1`. Efeitos no momento da criação:


        1. Gera lançamentos em `StockKeepingUnitMovement` (tipo 1 = consumo) para **cada componente** do kit
        (`StockKeepingUnitKitItems`), na quantidade necessária × `Quantity`, debitando o saldo do armazém indicado.

        2. Valida que cada componente tem saldo disponível no armazém — falha se não tiver.

        3. Custos do consumo seguem `UseCostFromCostSet` da empresa: quando ativo, usa `CostSet` do SKU; senão, calcula
        pelo saldo (`InventoryValue / QtyAvailable`).

        4. Copia as etapas da `StockKeepingUnitProductionLine` vinculada ao SKU (ou da linha padrão da empresa) para
        `StockKeepingUnitProductionSteps`.

        5. Status inicial = 2 (Aberto). A resposta é o detalhe da OP recém-criada (formato de `GET
        /sku/production/{idstockkeepingunitproduction}`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductionCreate'
        description: >-
          Dados de cadastro da ordem de produção (cabeçalho). Os itens (SKUs a produzir) são enviados depois via `POST
          /sku/production/{idstockkeepingunitproduction}/sku`.
      responses:
        '200':
          description: Ordem de produção criada (detalhe).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProductionDetail'
        '400':
          description: >-
            `[BadRequest] - Empresa não existe`; `[BadRequest] - Sku não existe`; `[BadRequest] - Sku não tem produção
            própria`; `[BadRequest] - Armazém não existe`; `[BadRequest] - Pedido não existe`; `[BadRequest] - Sku: <id>
            Quantidade disponível (<x>) menor que quantidade solicitada (<y>)`; `[BadRequest] - Sku não tem saldo
            disponível`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/production/{idstockkeepingunitproduction}:
    parameters:
      - name: idstockkeepingunitproduction
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador da ordem de produção.
    get:
      operationId: skuProductionGet
      tags:
        - Produção
      summary: Detalha uma ordem de produção
      description: >-
        Retorna a OP completa com: cabeçalho, lista de **itens consumidos** (`Items` — array de
        `StockKeepingUnitMovement` de cada insumo com SKU, quantidade, custo total e unitário, armazém), lista de
        **etapas** (`StockKeepingUnitProductionLineSteps` — array com status, tempo gasto, tempo decorrido, usuário que
        finalizou cada uma) e somatórios de tempo (`TimeSpentTotal`, `TimeElapsedTotal`) e custo (`ValueCostTotal`).
      responses:
        '200':
          description: Detalhe da OP (array com 1 item).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProductionDetail'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    put:
      operationId: skuProductionPut
      tags:
        - Produção
      summary: Atualiza uma ordem de produção
      description: >-
        Atualiza campos editáveis (`DateEstimated`, `Comments`, `IDTypeStatusSkuProduction`, `IDOrder`) — apenas os
        campos enviados são alterados. Bloqueia atualização quando a OP está **Finalizada** com pedido vinculado ou
        **Cancelada**. Quando `IDTypeStatusSkuProduction` é enviado, valida que existe no catálogo. A resposta é o
        detalhe atualizado.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductionUpdate'
        description: Atualização parcial da ordem de produção. Apenas os campos enviados são aplicados.
      responses:
        '200':
          description: OP atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProductionDetail'
        '400':
          description: >-
            `[BadRequest] - Produção não existe`; `[BadRequest] - Produção esta finalizada`; `[BadRequest] - Produção
            esta cancelada`; `[BadRequest] - Status não existe`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: skuProductionDelete
      tags:
        - Produção
      summary: Cancela uma ordem de produção
      description: >-
        **Cancelamento lógico**: marca a OP como `IDTypeStatusSkuProduction = 4` (Cancelado) e remove fisicamente os
        movimentos de insumos consumidos (`StockKeepingUnitMovement`) e as etapas (`StockKeepingUnitProductionSteps`).
        Reverte automaticamente o saldo dos insumos no armazém. Bloqueado quando a OP já está **Finalizada** ou
        **Cancelada**. A resposta é o detalhe da OP cancelada.
      responses:
        '200':
          description: OP cancelada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProductionDetail'
        '400':
          description: >-
            `[BadRequest] - Produção não existe`; `[BadRequest] - Produção esta finalizada`; `[BadRequest] - Produção
            esta cancelada`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/production/{idstockkeepingunitproduction}/finish:
    parameters:
      - name: idstockkeepingunitproduction
        in: path
        required: true
        schema:
          type: integer
        description: Identificador da OP.
    post:
      operationId: skuProductionFinishPost
      tags:
        - Produção
      summary: Finaliza a ordem de produção (gera Recebimento)
      description: >-
        Conclui a OP marcando como `IDTypeStatusSkuProduction = 1` (Finalizado). Efeitos colaterais:


        1. Cria um **Recebimento** (`purchasePost`) ou reaproveita o `IDPurchase` enviado no body. O fornecedor é o
        **fornecedor padrão de recebimento** da empresa.

        2. Lança no recebimento o **produto produzido** (`purchaseSkuPost` com `BypassValidation=1`), na quantidade e
        custo total acumulados da OP.

        3. Atualiza os movimentos de consumo (`IDStatusSku = 1`).

        4. Vincula o `IDPurchase` ao registro da OP.


        Bloqueado quando a OP já está Finalizada/Cancelada. Devolve o detalhe do Recebimento gerado (mesmo formato de
        `GET /purchase/{idpurchase}`).
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductionFinish'
        description: >-
          Finalização da ordem de produção — efetiva a entrada dos SKUs produzidos no depósito de destino e consome os
          componentes (no caso de produção de kits). O corpo geralmente é vazio; o sistema usa o estado da ordem para
          concluir a movimentação.
      responses:
        '200':
          description: Detalhe do recebimento gerado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProductionFinishResponse'
        '400':
          description: >-
            `[BadRequest] - Produção não existe`; `[BadRequest] - Produção esta finalizada`; `[BadRequest] - Produção
            esta cancelada`; `[BadRequest] - Não existe fornecedor padrão para recebimento cadastrado`; `[BadRequest] -
            Erro ao criar recebimento`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/production/{idstockkeepingunitproduction}/sku:
    parameters:
      - name: idstockkeepingunitproduction
        in: path
        required: true
        schema:
          type: integer
        description: Identificador da OP.
    post:
      operationId: skuProductionSkuPost
      tags:
        - Produção
      summary: Adiciona um insumo extra à OP
      description: >-
        Adiciona um item consumido (insumo/matéria-prima) à OP além dos componentes copiados na criação. O SKU informado
        precisa ser do tipo SKU (3), matéria-prima (6) ou variante (7), ter saldo disponível no armazém indicado (ou no
        armazém da OP), e o custo é calculado conforme o flag `UseCostFromCostSet` da empresa. Bloqueado quando a OP
        está Finalizada/Cancelada. Devolve o detalhe da OP atualizada.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductionSkuAdd'
        description: Adiciona um SKU à ordem de produção. Informe `Quantity` (quantidade a produzir) e opcionalmente `Comments`.
      responses:
        '200':
          description: Insumo adicionado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProductionDetail'
        '400':
          description: >-
            `[BadRequest] - Produção não existe`; `[BadRequest] - Item não é do tipo Sku ou matéria prima`;
            `[BadRequest] - Sku não existe`; `[BadRequest] - Sku não tem saldo disponível`; `[BadRequest] - Quantidade
            disponível (<x>) menor que quantidade solicitada (<y>)`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/production/{idstockkeepingunitproduction}/sku/{idskumovement}:
    parameters:
      - name: idstockkeepingunitproduction
        in: path
        required: true
        schema:
          type: integer
        description: Identificador da OP.
      - name: idskumovement
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do movimento de consumo (linha de insumo na OP).
    put:
      operationId: skuProductionSkuPut
      tags:
        - Produção
      summary: Atualiza um insumo da OP
      description: >-
        Edita um item já consumido na OP: quantidade, armazém, custo total e observações. Quando aumenta a quantidade,
        valida saldo disponível no armazém para a diferença. Bloqueado quando OP está Finalizada/Cancelada. Devolve o
        detalhe da OP.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductionSkuUpdate'
        description: Atualiza a quantidade ou o depósito de destino de um item da ordem de produção.
      responses:
        '200':
          description: Insumo atualizado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProductionDetail'
        '400':
          description: >-
            `[BadRequest] - Produção não existe`; `[BadRequest] - Produção esta finalizada`; `[BadRequest] - Produção
            esta cancelada`; `[BadRequest] - Armazém não existe`; `[BadRequest] - Quantidade disponível (<x>) menor que
            quantidade adicional solicitada (<y>)`; `[BadRequest] - Sku não tem saldo disponível`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: skuProductionSkuDelete
      tags:
        - Produção
      summary: Remove um insumo da OP
      description: >-
        Remove uma linha de insumo consumido na OP. Bloqueado quando OP está Finalizada/Cancelada. Devolve o detalhe da
        OP atualizada.
      responses:
        '200':
          description: Insumo removido.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProductionDetail'
        '400':
          description: >-
            `[BadRequest] - Produção não existe`; `[BadRequest] - Produção esta finalizada`; `[BadRequest] - Produção
            esta cancelada`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/production/{idstockkeepingunitproduction}/steps/{idstockkeepingunitproductionsteps}:
    parameters:
      - name: idstockkeepingunitproduction
        in: path
        required: true
        schema:
          type: integer
        description: Identificador da OP.
      - name: idstockkeepingunitproductionsteps
        in: path
        required: true
        schema:
          type: integer
        description: Identificador da etapa dentro da OP.
    put:
      operationId: skuProductionStepsPut
      tags:
        - Produção
      summary: Atualiza uma etapa da OP (status e tempo gasto)
      description: >-
        Marca o progresso de uma etapa específica da OP: muda o status (`IDTypeStatusSkuProduction`) e registra o tempo
        gasto (`TimeSpent`, formato `HH:MM:SS`). Quando muda para `3` (Em andamento), grava `RecordTimestampStart` com o
        momento atual. Quando muda para `1` (Finalizado), grava `RecordTimestampEnd` com o momento atual e
        `RecordUserCreatedEnd` com o usuário autenticado. Como efeito colateral, a OP-mãe passa para status `3` (Em
        andamento) — sai do Aberto. Devolve o detalhe da OP.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductionStepUpdate'
        description: Atualiza o status da etapa da ordem de produção (avanço no fluxo de etapas configurado na linha de produção).
      responses:
        '200':
          description: Etapa atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProductionDetail'
        '400':
          description: '`[BadRequest] - Etapa produção não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/production/line:
    get:
      operationId: skuProductionLineList
      tags:
        - Produção
      summary: Lista linhas de produção
      description: >-
        Retorna as linhas de produção ativas da empresa, cada uma com a **contagem** de etapas (`QtySteps`) e o
        **array** de etapas (`StockKeepingUnitProductionLineSteps`) ordenado por `ProductionLineStepOrder`. Aceita
        filtros por id e por nome.
      parameters:
        - name: IDStockKeepingUnitProductionLine
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por id da linha.
        - name: ProductionLineName
          in: query
          required: false
          schema:
            type: string
          description: Filtra por nome exato da linha.
      responses:
        '200':
          description: Lista de linhas de produção.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProductionLineListItem'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: skuProductionLinePost
      tags:
        - Produção
      summary: Cria uma linha de produção
      description: >-
        Cria uma linha **sem etapas** (etapas são adicionadas depois com `POST .../steps`). Quando `Default = 1`,
        desmarca a linha que estava como padrão antes — apenas uma linha pode ser padrão por empresa. A resposta repete
        o formato da listagem.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductionLineCreate'
        description: Dados da linha de produção a cadastrar.
      responses:
        '200':
          description: Linha criada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProductionLineListItem'
        '400':
          description: '`[BadRequest] - Empresa não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/production/line/{idstockkeepingunitproductionline}:
    parameters:
      - name: idstockkeepingunitproductionline
        in: path
        required: true
        schema:
          type: integer
        description: Identificador da linha de produção.
    put:
      operationId: skuProductionLinePut
      tags:
        - Produção
      summary: Atualiza uma linha de produção
      description: >-
        Atualiza o nome (`ProductionLineName`) e/ou a flag de padrão (`Default`). Quando muda para `Default = 1`,
        desmarca a linha que estava como padrão. Quando muda para `Default = 0`, exige que **outra linha** já esteja
        marcada como padrão — não permite ficar sem padrão. Devolve a lista atualizada.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductionLineUpdate'
        description: Atualiza a linha de produção.
      responses:
        '200':
          description: Linha atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProductionLineListItem'
        '400':
          description: '`[BadRequest] - Linha de produção não existe`; `[BadRequest] - É preciso ter uma linha de produção padrão`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: skuProductionLineDelete
      tags:
        - Produção
      summary: Exclui uma linha de produção
      description: >-
        **Remove fisicamente** o registro. Bloqueado quando a linha **ainda tem etapas** cadastradas (precisa excluir
        etapas antes) ou **produtos vinculados** (precisa desvincular no cadastro do produto antes). Devolve a string
        `"Sucesso"` no caso de sucesso.
      responses:
        '200':
          description: Linha excluída.
          content:
            application/json:
              schema:
                type: string
                enum:
                  - Sucesso
        '400':
          description: >-
            `[BadRequest] - Linha de produção não existe`; `[BadRequest] - Precisa excluir etapas de produção antes de
            excluir a linha`; `[BadRequest] - Há produtos com essa linha de produção, remover no cadastro do produto
            antes de excluir a linha`; `[BadRequest] - Erro ao excluir linha de produção`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/production/line/{idstockkeepingunitproductionline}/steps:
    parameters:
      - name: idstockkeepingunitproductionline
        in: path
        required: true
        schema:
          type: integer
        description: Identificador da linha de produção.
    post:
      operationId: skuProductionLineStepPost
      tags:
        - Produção
      summary: Cria uma etapa em uma linha de produção
      description: >-
        Adiciona uma etapa à linha. Etapas são ordenadas por `ProductionLineStepOrder` (decimal — permite inserir entre
        etapas existentes com `1.5`). Devolve a lista atualizada de linhas.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductionLineStepCreate'
        description: 'Adiciona uma etapa à linha de produção (ex.: Corte, Costura).'
      responses:
        '200':
          description: Etapa criada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProductionLineListItem'
        '400':
          description: '`[BadRequest] - Linha de produção não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/production/line/{idstockkeepingunitproductionline}/steps/{idstockkeepingunitproductionlinesteps}:
    parameters:
      - name: idstockkeepingunitproductionline
        in: path
        required: true
        schema:
          type: integer
        description: Identificador da linha.
      - name: idstockkeepingunitproductionlinesteps
        in: path
        required: true
        schema:
          type: integer
        description: Identificador da etapa.
    put:
      operationId: skuProductionLineStepPut
      tags:
        - Produção
      summary: Atualiza uma etapa de uma linha
      description: Atualiza nome e/ou ordem da etapa. Devolve a lista atualizada.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductionLineStepCreate'
        description: Atualiza o nome da etapa da linha de produção.
      responses:
        '200':
          description: Etapa atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProductionLineListItem'
        '400':
          description: '`[BadRequest] - Etapa da linha de produção não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: skuProductionLineStepDelete
      tags:
        - Produção
      summary: Remove uma etapa de uma linha
      description: >-
        Exclui fisicamente a etapa. Atenção: ordens de produção criadas antes mantêm as etapas que foram copiadas no
        momento da criação. Devolve a lista atualizada.
      responses:
        '200':
          description: Etapa removida.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProductionLineListItem'
        '400':
          description: '`[BadRequest] - Etapa da linha de produção não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /carrier/tracking-template:
    get:
      operationId: trackingTemplateList
      tags:
        - Templates de Rastreamento
      summary: Lista templates de Mensagem Tracking
      description: >-
        Retorna os templates de mensagem tracking ativos da empresa, ordenados por `EmailTitle`. Cada item já vem com o
        status do tracking resolvido (`StatusTracking`), o tipo do template (`TypeCarrierTrackingTemplate` = 'e-mail' ou
        'WhatsApp'), o nome da integração de mensagem (`CompanyIntegration` = `IntegrationName -
        CompanyIntegrationName`), além das listas de integração de origem do pedido (`IDCompanyIntegrationOrderList`) e
        tipo de pedido (`IDTypeOrderList`) devolvidas como arrays a partir do CSV armazenado no banco.
      parameters:
        - name: IDCarrierTrackingTemplate
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por id específico do template.
        - name: Page
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          description: >-
            Página dos resultados, começando em `0`. Cada página retorna até 1000 templates: `Page=0` traz os primeiros
            1000, `Page=1` os 1000 seguintes, e assim por diante. Se omitido ou vazio, assume `0`.
      responses:
        '200':
          description: Uma página de templates, com até 1000 itens.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TrackingTemplateListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: trackingTemplatePost
      tags:
        - Templates de Rastreamento
      summary: Cria um template de Mensagem Tracking
      description: >-
        Cria um template para a empresa autenticada. Validações:

        - `CC` e `CCO` (quando preenchidos) precisam ter e-mails válidos separados por vírgula.

        - `IDCompanyIntegration` (integração de mensagem — e-mail/WhatsApp) precisa pertencer à empresa autenticada.

        - `IDCompanyIntegrationOrderList` (integrações que originam pedidos) e `IDTypeOrderList` (tipos de pedido)
        precisam existir para a empresa e estar ativos.


        Depois de salvar, devolve o detalhe do template recém-criado (formato da listagem). Não há `Lista de status de
        tracking` no body — o sistema aceita qualquer valor numérico em `IDStatusTracking`, mas a UI usa
        `TypeStatusTracking` (1=Finalizado, 2=Em andamento, 3=Atenção, 4=Não iniciado, 5=Saiu para entrega,
        6=Extraviado, 7=Devolvido, 8=Postado).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrackingTemplateCreate'
        description: >-
          Cria um template de rastreio (regra de disparo de mensagem amarrada a um macro status de tracking). Validações
          executadas: cada e-mail em `CC` e `CCO` é validado por regex; quando `IDCompanyIntegration` for enviado
          precisa pertencer à empresa; `IDCompanyIntegrationOrderList` aceita lista de integrações de origem (validadas
          com `Show = 1`); `IDTypeOrderList` aceita lista de tipos de pedido (validados com `Status = 1`). Ambas as
          listas aceitam array ou string separada por vírgula — o sistema normaliza para CSV antes de gravar. Quando
          vazias, o template dispara para todas as integrações/tipos de pedido.
      responses:
        '200':
          description: Template criado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TrackingTemplateListItem'
                maxItems: 1
        '400':
          description: >-
            Validações: `[BadRequest] - Email CCO não é válido <email>`; `[BadRequest] - Empresa não existe`;
            `[BadRequest] - Integração não existe`; `[BadRequest] - Integração(s) não localizada(s): <ids>`;
            `[BadRequest] - Tipo pedido(s) não localizado(s): <ids>`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /carrier/tracking-template/{idcarriertrackingtemplate}:
    parameters:
      - name: idcarriertrackingtemplate
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do template.
    put:
      operationId: trackingTemplatePut
      tags:
        - Templates de Rastreamento
      summary: Atualiza um template de Mensagem Tracking
      description: >-
        Atualiza um template existente. **Atualização parcial** — somente os campos enviados são alterados. Aplica as
        mesmas validações do POST para `CC`, `CCO`, `IDCompanyIntegration`, `IDCompanyIntegrationOrderList` e
        `IDTypeOrderList`. A resposta repete o formato da listagem com o detalhe atualizado.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrackingTemplateUpdate'
        description: >-
          Atualização parcial — apenas campos enviados são alterados. Mesmas validações do `POST` (regex de e-mail em
          `CC`/`CCO`, existência de `IDCompanyIntegration`, integrações de origem com `Show=1`, tipos de pedido com
          `Status=1`).
      responses:
        '200':
          description: Template atualizado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TrackingTemplateListItem'
                maxItems: 1
        '400':
          description: >-
            Validações: `[BadRequest] - Tracking template não existe`; `[BadRequest] - Email CCO não é válido <email>`;
            `[BadRequest] - Integração tipo mensagem não existe`; `[BadRequest] - Integração(s) não localizada(s):
            <ids>`; `[BadRequest] - Tipo pedido(s) não localizado(s): <ids>`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: trackingTemplateDelete
      tags:
        - Templates de Rastreamento
      summary: Exclui um template de Mensagem Tracking
      description: >-
        **Remove fisicamente** o template (exclusão definitiva, sem soft delete nem histórico). Não há regras de
        bloqueio. Devolve a string literal `"Sucesso!"`.
      responses:
        '200':
          description: Template excluído.
          content:
            application/json:
              schema:
                type: string
                enum:
                  - Sucesso!
        '400':
          description: '`[BadRequest] - IDCarrierTrackingTemplate não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /carrier/quotation/rule:
    get:
      operationId: carrierQuotationRuleList
      tags:
        - Cotação de Frete
      summary: Lista regras de simulação de frete
      description: >-
        Retorna as regras da empresa **ordenadas por `Priority` crescente** e, em empate, por `IDCarrierQuotationRule`
        DESC (até 1000 itens). Inclui regras Ativas (`Status=1`) e Inativas (`Status=0`), mas oculta as Excluídas
        (`Status=2`). Cada item já vem com `ConditionsRules` (array de condições com `ConditionValue` quebrado em vetor
        pelo separador `,`), `ConditionNames` (string concatenada com nomes das condições, usada na grid) e
        `CarrierQuotationRuleLog` (histórico de alterações em formato `DE: <antes> PARA: <depois>`).
      responses:
        '200':
          description: Lista das regras (até 1000).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CarrierQuotationRuleListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
      parameters:
        - name: Page
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          description: >-
            Índice da página para paginação, começando em `0`. Cada página retorna até 1000 regras; informe `1` para as
            próximas 1000, e assim por diante. Quando omitido, assume `0` (primeira página).
    post:
      operationId: carrierQuotationRulePost
      tags:
        - Cotação de Frete
      summary: Cria uma regra de simulação de frete
      description: >-
        Cria uma regra para a empresa autenticada, com 1+ condições e 1 ação. O sistema valida cada condição pelo
        `IDTypeCarrierQuotationConditionRule` informado:


        - **1 — Estado/Região**: cada item é a sigla UF (2 letras) opcionalmente concatenada com `CAPITAL` ou `INTERIOR`
        (ex.: `SP`, `SPCAPITAL`, `RJINTERIOR`). UFs aceitas: AC, AL, AP, AM, BA, CE, DF, ES, GO, MA, MT, MS, MG, PA, PB,
        PR, PE, PI, RJ, RN, RS, RO, RR, SC, SP, SE, TO.

        - **2 — CEP Destino** e **10 — CEP Origem**: cada item é a faixa `<CEPDe>|<CEPAté>`, sem hífens, 8 dígitos cada.
        `CEPDe` precisa ser **menor** que `CEPAté`.

        - **3 — Transportadora**: cada item é o `IDSupplier` de um fornecedor da empresa com `IDTypeSupplier=2`
        (Transportadora). Quando a ação é `9` (Excluir transportadoras), a condição 3 é **obrigatória** e a UI marca
        automaticamente.

        - **4 — Valor do pedido**: cada item é a faixa `<ValorDe>|<ValorAté>` em reais. `ValorDe` precisa ser **menor**
        que `ValorAté`, ambos ≥ 0.

        - **6 — Integração**: cada item é o `IDCompanyIntegration` de uma integração configurada pela empresa.

        - **7 — Peso (kg)**: cada item é a faixa `<PesoDe>|<PesoAté>` em kg.

        - **8 — SKUs iguais a** e **9 — SKUs diferentes de**: cada item tem o formato `<IDSku>|<descrição>`. Não há
        validação de existência do SKU no sistema.


        A regra passa a valer imediatamente para a próxima cotação. Devolve o detalhe da regra recém-criada (formato do
        GET por id).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierQuotationRuleCreate'
        description: >-
          Cria uma regra de simulação de frete. Toda regra precisa de pelo menos uma condição. O `ConditionValue` é
          validado de acordo com o tipo da condição: estados pelo cadastro oficial; faixas de CEP exigem 8 dígitos e
          `cepInicial < cepFinal`; transportadoras precisam existir como `Suppliers` da empresa com `IDTypeSupplier=2`;
          faixas de valor exigem `de < até` ambos positivos; integrações precisam pertencer à empresa. A regra passa a
          valer imediatamente para a próxima cotação (`POST /carrier/quotation`).
      responses:
        '200':
          description: Regra criada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CarrierQuotationRuleDetail'
                maxItems: 1
        '400':
          description: >-
            Validações: `[BadRequest] - Empresa não existe`; `[BadRequest] - Ação inativa ou não existe`; `[BadRequest]
            - Estado <UF> não encontrado`; `[BadRequest] - Faixa de cep <de>-<até> inválida`; `[BadRequest] - ID da
            transportadora <id> não encontrado`; `[BadRequest] - Preço <de>|<até> inválido, preço De precisa ser menor
            que preço Para`; `[BadRequest] - ID da integração <id> não encontrado`; `[BadRequest] - Falha ao adicionar
            regra de cotação`; `[BadRequest] - Falha ao adicionar condições da regra de cotação`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /carrier/quotation/rule/{idcarrierquotationrule}:
    parameters:
      - name: idcarrierquotationrule
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador da regra.
    get:
      operationId: carrierQuotationRuleGet
      tags:
        - Cotação de Frete
      summary: Detalha uma regra de simulação de frete
      description: >-
        Retorna a regra completa: cabeçalho (`CarrierQuotationRuleName`, `Priority`, `Status`, `DateFrom`, `DateTo`,
        ação e valor), `ConditionsRules` com cada condição quebrada em vetor pelo separador `,`, e
        `CarrierQuotationRuleLog` ordenado por `IDCarrierQuotationRuleLog` DESC (histórico de alterações em formato `DE:
        <antes> PARA: <depois>` e `<NomeCondicao>_Adicionado` / `<NomeCondicao>_Removido`).
      responses:
        '200':
          description: Detalhe da regra.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CarrierQuotationRuleDetail'
                maxItems: 1
        '400':
          description: '`[BadRequest] - Regra de cotação não encontrada`; `[BadRequest] - Parâmetros inválidos`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    put:
      operationId: carrierQuotationRulePut
      tags:
        - Cotação de Frete
      summary: Atualiza uma regra de simulação de frete
      description: >-
        **Atualização total** do cabeçalho (`CarrierQuotationRuleName`, `Priority`, `Status`, `DateFrom`, `DateTo`,
        `IDTypeCarrierQuotationActionRule`, `ActionValue`) — campos que não vêm no body são gravados como NULL. As
        **condições** seguem a lógica de diff: o sistema compara `Conditions` com o que já está em
        `CarrierQuotationRuleCondition` e:


        - Insere o que está no body e não existe (grava `<NomeCondicao>_Adicionado` no log).

        - Apaga o que existe e não veio no body (grava `<NomeCondicao>_Removido` no log).

        - Mantém o que já estava igual.


        Qualquer mudança de campo do cabeçalho gera linha no log no formato `DE: <antes> PARA: <depois>`. Datas são
        comparadas truncadas para `YYYY-MM-DD`. As alterações passam a valer imediatamente. Devolve o detalhe da regra
        atualizada.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierQuotationRuleUpdate'
        description: >-
          Atualiza a regra. **Não é atualização parcial** — campos do cabeçalho ausentes são gravados como `NULL`. Para
          `Conditions`, é feito diff: condições novas são inseridas e ausentes são removidas. As mudanças passam a valer
          imediatamente.
      responses:
        '200':
          description: Regra atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CarrierQuotationRuleDetail'
                maxItems: 1
        '400':
          description: >-
            Validações: `[BadRequest] - Regra de cotação não existe`; `[BadRequest] - Estado <UF> não encontrado`;
            `[BadRequest] - Faixa de cep <de>-<até> inválida`; `[BadRequest] - ID da transportadora <id> não
            encontrado`; `[BadRequest] - Preço <de>|<até> inválido, preço De precisa ser menor que preço Até`;
            `[BadRequest] - ID da integração <id> não encontrado`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: carrierQuotationRuleDelete
      tags:
        - Cotação de Frete
      summary: Exclui uma regra de simulação de frete
      description: >-
        **Soft delete** — marca a regra com `Status = 2` (Excluída). A regra deixa de aparecer na listagem (que só traz
        `Status IN (0,1)`) e deixa de ser usada nas próximas cotações. Devolve a string literal `"Sucesso!"`.
      responses:
        '200':
          description: Regra excluída.
          content:
            application/json:
              schema:
                type: string
                enum:
                  - Sucesso!
        '400':
          description: '`[BadRequest] - Regra de cotação não existe`; `[BadRequest] - Erro ao e executar ação`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /carrier/quotation:
    get:
      operationId: carrierQuotationList
      tags:
        - Cotação de Frete
      summary: Lista simulações de frete
      description: >-
        Lista as simulações de frete já feitas pela empresa, ordenadas por `IDCarrierQuotation` DESC (até 5000 por
        página). Cada item traz cabeçalho da simulação (CEP destino, peso, dimensões totais, valor da nota, usuário que
        rodou, integração de origem quando veio de canal externo) e o resumo das transportadoras que responderam
        (`CarriersName` — lista de razões sociais separadas por vírgula).


        Não devolve as linhas detalhadas de cada transportadora — para isso use `GET
        /carrier/quotation/{idcarrierquotation}`.
      parameters:
        - name: DateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Filtra `RecordTimestamp` ≥ esta data.
        - name: DateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Filtra `RecordTimestamp` ≤ esta data 23:59:59.
        - name: ShippingPostalCode
          in: query
          required: false
          schema:
            type: string
          description: Filtra por CEP destino (apenas dígitos; pontuação é ignorada na comparação).
        - name: Description
          in: query
          required: false
          schema:
            type: string
          description: Busca parcial (`LIKE`) por descrição.
        - name: IDCarrierQuotation
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por id da simulação.
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
          description: Filtra simulações originadas de uma integração específica.
        - name: Page
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: Página de paginação (offset = `Page * 5000`).
      responses:
        '200':
          description: Lista das simulações (até 5000 por página).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CarrierQuotationListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: carrierQuotationPost
      tags:
        - Cotação de Frete
      summary: Roda uma simulação de frete
      description: |-
        Roda uma cotação para o CEP destino + lista de volumes/produtos.

        Validações iniciais (retornam 400):
        - `ShippingPostalCode` precisa estar preenchido.
        - Pelo menos 1 item em `Quotations` com `Weight > 0`.
        - CEP precisa existir na base de CEPs (caso contrário grava erro tipo `3` em `CarrierQuotationError`).

        Lógica:
        - Peso total = soma dos `Weight` de cada item.
        - Largura total = soma dos `Width`.
        - Altura e comprimento totais = **máximo** entre os itens.
        - Para cada transportadora ativa de leilão de frete (`CarrierAuction = 1`):
          - Calcula cubagem usando `CarrierCubageKmM` (padrão 167) e compara com `CarrierCubageFreeWeight` para definir `WeightSelected` (peso real ou cubado).
          - Busca a faixa de CEP em `CarrierScope`; se não atende, marca `Attended=0`.
          - Busca preço em `CarrierRate` por `RateType` + `WeightFrom/WeightTo`; quando o peso excede a maior faixa e existe entrada com `WeightTo=-1`, extrapola linearmente.
          - Soma componentes do frete (rate, gris, advalorem, pedágio, taxas de difícil acesso, despacho, etc.) → subtotal.
          - Aplica ICMS interestadual (se origem e destino diferem de estado **e** transportadora não tem `CarrierICMSIncluded`).
          - Aplica `CarrierAuctionPenalty` da transportadora e regras de **Regras Simulação Frete** (adição de dias e/ou valor).
        - Persiste cabeçalho em `CarrierQuotation` e linhas em `CarrierQuotationRate`.

        Devolve um array com 1 item: o detalhe da simulação criada (mesmo formato do GET por id).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierQuotationCreate'
        description: >-
          Simula frete para um destino. Mínimo: `ShippingPostalCode` (CEP destino) e `Quotations[]` com `Weight`,
          `Height`, `Width` e `Length` por volume. O sistema padroniza o CEP em 8 dígitos com zero à esquerda, agrega
          medidas (soma peso/largura/valor da nota, pega maior altura/comprimento, conta volumes) e percorre todas as
          transportadoras ativas da empresa com gateway interno (`IDCarrierGateway=1`). Para cada transportadora aplica
          regras de cubagem, tabela de preços por faixa de peso, Gris, Advalorem, TDE, pedágio, ICMS interestadual e
          demais taxas. Depois aplica as regras de simulação cadastradas (`POST /carrier/quotation/rule`) na ordem da
          `Priority`. A resposta vem ordenada por atendimento e prazo crescente. Quando `IDOrder` é enviado e já existe
          uma simulação para esse pedido, o registro existente é reaproveitado. Quando chamado por integração de
          marketplace (Mercado Livre, Tray, Convertize etc.), o sistema adapta o corpo de resposta ao formato do canal.
          CEP destino inexistente gera entrada em `GET /carrier/quotation/error` (tipo `3` Cep não localizado).
      responses:
        '200':
          description: Simulação criada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CarrierQuotationDetail'
                maxItems: 1
        '400':
          description: >-
            `Precisa enviar o CEP destino`; `Peso precisa ser maior que zero`; `Dados para cotação não enviados`; `CEP
            destino <postalcode> não existe`; `Empresa não localizada (2)`. (Mensagens sem o prefixo `[BadRequest]`.)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /carrier/quotation/{idcarrierquotation}:
    parameters:
      - name: idcarrierquotation
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador da simulação.
    get:
      operationId: carrierQuotationGet
      tags:
        - Cotação de Frete
      summary: Detalha uma simulação de frete
      description: >-
        Retorna a simulação com **todas** as linhas por transportadora. Cada linha (`CarrierQuotations[]`) traz:


        - `IDCarrier` + `SupplierNameCorporateName` + `CarrierLogoUrl` + `CarrierModal` (modalidade da transportadora).

        - `Attended` (1=Atende, 0=Não atende, 3=Excluído por regra, 4=Fora da faixa) e `AttendedDescription` (texto
        pronto para exibição).

        - Componentes do preço: `ShipingValue`, `GrisValue`, `AdvaloremValue`, `TollValue`, `AccessDifficultyRateValue`,
        `DispatchFeeValue`, `DeliveryDifficultyRateValue`, `SECCATValue`, `TollFractionValue`,
        `TrafficRestrictionFeeValue`, `AdministrationFeeValue`, `CTEFeeValue`, `SUFRAMAFeeValue`, `FluvialInsuranceFee`,
        `OtherFee`, `OtherFeeValue`, `IcmsValue`.

        - Totais calculados pelo sistema: `SubtotalShippingValue` (soma dos componentes), `TotalShippingValue` (subtotal
        + ICMS), `IcmsValuePercent`, `ShippingShowValue` (total + ajustes de regra + `PriceRounding`).

        - Prazo: `DaysTime` (transportadora) + `CarrierAdditionalBusinessDays` (transportadora) + `CutDaysTime` (1
        quando saiu fora do horário de corte) + `RuleAdditionalDays` (regra) → `TotalDaysTime` / `TotalShowDaysTime`.

        - Cubagem: `WeightCubed`, `WeightSelected`, `CarrierCubageKmM`, `CarrierCubageFreeWeight`.

        - Quando regras de simulação foram aplicadas: `CarrierQuotationRuleValueName`, `CarrierQuotationRuleDaysName`,
        `RuleAdditionalValue`, `RuleAdditionalDays`.


        Ordenação: `Attended DESC` (quem atende primeiro), `TotalDaysTime ASC` (prazo curto primeiro),
        `TotalShippingValue ASC` (preço baixo).
      responses:
        '200':
          description: Detalhe da simulação. `[]` quando o id não existe ou pertence a outra empresa.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CarrierQuotationDetail'
                maxItems: 1
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /orders:
    get:
      operationId: ordersList
      tags:
        - Pedidos
      summary: Lista pedidos
      description: >-
        Lista os pedidos da empresa autenticada — endpoint compartilhado entre **Outbound** (default `IDStatusOrder=1` +
        `OrderBy=ASC`), **Pedidos**, **Retirada em Mãos** (`IDStatusOrder=17&Budget=0&SkuView=0`) e demais telas que
        listam pedidos. Paginação fixa em **2000 registros por página** (`Page=N` → offset `N*2000`).


        **Etapas internas** (`OrdersGet`):


        1. Resolve `IDCompany` a partir do prefix da conta + `accountname` do header. Quando o usuário tem mais de uma
        conta vinculada, busca a posição correspondente em `IDCompanyList` (CSV indexado por `accountnamelist`).

        2. Se o usuário tem **centros de distribuição vinculados**, restringe à lista dele. Querystring
        `IDStockKeepingUnitDistributionCenter` é validada contra essa lista — se não pertence, retorna `[]`
        imediatamente.

        3. Quando `Search` é informado, limita `IDOrder` aos últimos 3 meses (busca rápida só varre essa janela).

        4. Quando o usuário é vendedor (`Salesman=1`) com `restrictaccesssalesman=1`, restringe aos pedidos cujos
        consumidores estão vinculados ao usuário em `ConsumerSalesman`.

        5. Em duas etapas: primeiro resolve os `IDOrder` paginados (2000 por página); depois carrega cada pedido
        completo com todos os dados resolvidos (status, integração, nota fiscal, transportadora, faturador, CD).

        6. `SkuView=1` muda o segundo passo para retornar `Items` agregados (array JSON de SKUs do pedido com nome,
        quantidade, valor unitário, kit, inconformidade e imagem principal) em vez das colunas planas. Frontend usa para
        preview de linha expandida.


        **Busca rápida (`Search`)** — quando informada, casa contra qualquer um dos campos:

        - `Order`.

        - `ConsumerNameCorporateName` / `ShippingReceiverName` (exige ≥4 caracteres alfabéticos).

        - `ConsumerEmail`.

        - `ConsumerCpfCnpj` (apenas dígitos, comprimento entre 11 e 14).

        - `NfeNumber` (apenas dígitos, ≤9).

        - `IDOrder` (apenas dígitos, ≤11).

        - `OrderFrom` (qualquer marketplace).

        - `PackId` (apenas dígitos com comprimento > 15).


        **Endpoint compartilhado por várias telas** — esta documentação cobre o conjunto **completo** de querystrings;
        cada tela usa um subconjunto.
      parameters:
        - name: Page
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: Página (0-indexada). Offset aplicado = `Page * 2000`.
        - name: OrderBy
          in: query
          required: false
          schema:
            type: string
            enum:
              - ASC
              - DESC
            default: DESC
          description: >-
            Direção de ordenação por `IDOrder`. O Outbound passa `OrderBy=ASC` por padrão para mostrar os pedidos mais
            antigos primeiro.
        - name: OrderByRule
          in: query
          required: false
          schema:
            type: string
            enum:
              - SkuNameAsc
              - SkuNameDesc
              - IDSkuCompanyAsc
              - IDSkuCompanyDesc
          description: >-
            `1` adiciona à resposta o campo `OrderByRule` com os 2 primeiros nomes/códigos de SKU do pedido (em ordem
            ascendente). Frontend usa para ordenar a tela pela coluna escolhida.
        - name: Search
          in: query
          required: false
          schema:
            type: string
          description: >-
            Busca rápida unificada. Pesquisa simultaneamente em `Order`, `ConsumerNameCorporateName`,
            `ShippingReceiverName`, `ConsumerEmail`, `ConsumerCpfCnpj`, `NfeNumber`, `IDOrder`, `OrderFrom` e `PackId`.
            Limita a varredura aos últimos 3 meses (`IDOrder ≥ IDOrderThreeMonthsAgo`).
        - name: SkuView
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
            default: 0
          description: >-
            `1` faz a resposta incluir o agregado `Items` (array de SKUs do pedido com nome, quantidade, valor, kit,
            inconformidade e imagem principal). Frontend usa para expandir linha. Sem esta flag, a resposta vem com
            colunas planas.
        - name: DateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Filtra pedidos com `RecordTimestamp` a partir desta data (inclusive) — data de criação do pedido.
        - name: DateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Filtra pedidos com `RecordTimestamp` até o final desta data (inclusive) — data de criação do pedido.
        - name: InvoiceDateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Filtra pedidos com `NfedhEmi` (data de emissão da NF principal) a partir desta data (inclusive).
        - name: InvoiceDateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Filtra pedidos com `NfedhEmi` (data de emissão da NF principal) até o final desta data (inclusive).
        - name: ShippingDateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Existe pelo menos um `ShippingDate` ≥ data para o pedido.
        - name: ShippingDateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Existe pelo menos um `ShippingDate` ≤ data + ` 23:59:59`.
        - name: ShippingHandlingLimitDateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: >-
            `ShippingEstimateHandlingLimitDate` ≥ data. Aplicável apenas a pedidos integrados (data estimada de
            expedição vinda do canal — usado principalmente pelo Mercado Livre).
        - name: ShippingHandlingLimitDateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: '`ShippingEstimateHandlingLimitDate` ≤ data.'
        - name: ShippingEstimateDateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: '`ShippingEstimateDate` ≥ data (data prevista de entrega ao cliente).'
        - name: ShippingEstimateDateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: '`ShippingEstimateDate` ≤ data + ` 23:59:59`.'
        - name: SinceRecordTimestamp
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: '`RecordTimestamp` ≥ timestamp. Útil para sincronizações incrementais (consumidores externos).'
        - name: SinceDateLastRecordModification
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: '`DateLastRecordModification` ≥ timestamp. Pega pedidos modificados depois do timestamp.'
        - name: IDStatusOrder
          in: query
          required: false
          schema:
            type: string
          description: >-
            Status do pedido. Aceita CSV (`IDStatusOrder=1,4,21`). Valores em `TypeStatusOrder` — ver tabela completa em
            `support data/TypeStatusOrder.csv`.
        - name: IDStatusInvoice
          in: query
          required: false
          schema:
            type: string
          description: >-
            Status da nota fiscal principal (`IDStatusInvoice`). CSV. Quando contém o valor `0`, expande para incluir
            também pedidos **sem NF** (`NOT EXISTS` em `NfCompany`).
        - name: IDOrder
          in: query
          required: false
          schema:
            type: string
          description: Código interno do pedido. CSV aceito (`IDOrder=1234,5678`).
        - name: Order
          in: query
          required: false
          schema:
            type: string
          description: >-
            Número do pedido (`Order`). Aceita múltiplos valores separados por vírgula ou espaço (ex.:
            `OT-1234,ML-5648`).
        - name: OrderFrom
          in: query
          required: false
          schema:
            type: string
          description: Número do pedido no canal de origem (`OrderFrom`). CSV aceito.
        - name: Budget
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`Budget`. `0` = pedido firme, `1` = orçamento. Tela de Pedidos passa `Budget=0`.'
        - name: BalanceChange
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: 'Tipo: `1` = pedido que movimenta estoque, `0` = nota fiscal sem movimento de estoque.'
        - name: NfeNoPayment
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`NfeNoPayment=1` filtra pedidos cuja NF foi emitida sem pagamento associado.'
        - name: IDCarrier
          in: query
          required: false
          schema:
            type: string
          description: Transportadora (`IDCarrier` → `IDSupplier`). CSV aceito.
        - name: IDOrderType
          in: query
          required: false
          schema:
            type: string
          description: Tipo de pedido (`IDOrderType` → `TypeOrder`). CSV aceito.
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: string
          description: Conta de integração vinculada ao pedido (`IDCompanyIntegration`). CSV aceito.
        - name: IDTypeCompanyIntegration
          in: query
          required: false
          schema:
            type: string
          description: Tipo de integração / canal de vendas (`IDTypeCompanyIntegration`). CSV aceito.
        - name: IDCompanyInvoice
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Empresa faturadora do pedido (`IDCompanyInvoice`).
        - name: IDSalesman
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Vendedor responsável pelo pedido (`IDSalesman` → `IDUser`).
        - name: IDConsumer
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Cliente do pedido (`IDConsumer`).
        - name: IDTypeOrderReturn
          in: query
          required: false
          schema:
            type: string
          description: Motivo de devolução. CSV aceito (`IDTypeOrderReturn`).
        - name: IDPickingList
          in: query
          required: false
          schema:
            type: string
          description: Pedidos vinculados a esta(s) picking-list(s). CSV aceito.
        - name: IDOrdersCarrierCollectionList
          in: query
          required: false
          schema:
            type: string
          description: Pedidos vinculados a este(s) romaneio(s). CSV aceito.
        - name: nullCollection
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` filtra apenas pedidos sem romaneio (`IDOrdersCarrierCollectionList IS NULL`).'
        - name: IDStockKeepingUnitDistributionCenter
          in: query
          required: false
          schema:
            type: string
          description: >-
            Centro de distribuição. CSV aceito. Validado contra a lista de CDs vinculados ao usuário; se o usuário tem
            restrição e o valor não pertence, a resposta volta vazia.
        - name: IDStockKeepingUnitWarehouse
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Armazém. Filtra pedidos que têm pelo menos um item vinculado ao armazém (via `StockKeepingUnitMovement`).
        - name: IDSku
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Pedidos que contêm o SKU informado (verificado em `StockKeepingUnitMovement`).
        - name: IDSkuCompany
          in: query
          required: false
          schema:
            type: string
          description: Pedidos que contêm um SKU com o código de referência informado (`IDSkuCompany`).
        - name: ConsumerNameCorporateName
          in: query
          required: false
          schema:
            type: string
          description: Nome / razão social do cliente (LIKE em `ConsumerNameCorporateName`).
        - name: ConsumerCpfCnpj
          in: query
          required: false
          schema:
            type: string
          description: >-
            CPF ou CNPJ do cliente. Aceita formato com pontuação — o sistema normaliza para apenas dígitos antes de
            comparar.
        - name: ConsumerEmail
          in: query
          required: false
          schema:
            type: string
          description: E-mail do cliente (LIKE em `ConsumerEmail`).
        - name: ConsumerTelephone
          in: query
          required: false
          schema:
            type: string
          description: Telefone do cliente. O sistema normaliza para apenas dígitos antes de comparar.
        - name: NfeNumber
          in: query
          required: false
          schema:
            type: string
          description: Número da nota fiscal principal (`NfeNumber`). CSV aceito (`NfeNumber=1234,5678`).
        - name: NfeSerie
          in: query
          required: false
          schema:
            type: integer
          description: Série da nota fiscal principal (`NfeSerie`).
        - name: NfeChaveAcesso
          in: query
          required: false
          schema:
            type: string
            minLength: 44
            maxLength: 44
          description: Chave de acesso da NF-e (44 dígitos). Busca exata em `NfeChaveAcesso`.
        - name: ShippingId
          in: query
          required: false
          schema:
            type: string
          description: Código de rastreio. Filtra pedidos que têm um `ShippingId` correspondente.
        - name: ShippingPostalCode
          in: query
          required: false
          schema:
            type: string
          description: CEP do destinatário (`ShippingPostalCode`).
        - name: ShippingState
          in: query
          required: false
          schema:
            type: string
          description: UF do destinatário (`ShippingState`). CSV aceito.
        - name: ValueOrderFrom
          in: query
          required: false
          schema:
            type: number
            format: double
          description: Valor mínimo do pedido (soma dos itens + frete + acessórios).
        - name: ValueOrderTo
          in: query
          required: false
          schema:
            type: number
            format: double
          description: Valor máximo do pedido.
        - name: OrderPriority
          in: query
          required: false
          schema:
            type: integer
          description: Prioridade do pedido (`OrderPriority`).
        - name: OrdersSalesChannelLabelStatus
          in: query
          required: false
          schema:
            type: string
          description: Status da etiqueta no canal de venda (`Header`).
        - name: Tags
          in: query
          required: false
          schema:
            type: string
          description: Filtra pedidos que têm a tag informada em `Tag`.
        - name: IncludeValueDashboard
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Filtra pelo flag `IncludeValueDashboard` do tipo de pedido.
        - name: ServiceRequest
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Filtra pelo flag `ServiceRequest` do tipo de pedido (pedidos de serviço).
        - name: PickingListBasketExternalId
          in: query
          required: false
          schema:
            type: string
          description: Cesto da picking-list (`ExternalId`). Usado quando a tela mostra pedidos amarrados a um cesto físico bipado.
        - name: IDStoreFrontCashier
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Caixa do PDV (`IDStoreFrontCashier`). Filtra pedidos lançados em um caixa específico.
        - name: LastID
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: >-
            Cursor de paginacao por chave. Quando informado, a listagem ignora o deslocamento de Page e retorna os 2000
            pedidos seguintes com IDOrder maior que este valor (quando OrderBy=ASC) ou menor (quando OrderBy=DESC). Use
            o IDOrder do ultimo item da pagina anterior para percorrer grandes volumes de forma incremental.
      responses:
        '200':
          description: >-
            Array de pedidos. Retorna até 2000 itens por página. Cada item traz o pedido + status + integração + NF
            principal + transportadora + faturador + CD. Quando `SkuView=1`, traz também o array `Items` com os SKUs do
            pedido. Quando nenhum pedido casa com os filtros, retorna `[]` (com `200`).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrdersListItem'
    post:
      operationId: ordersCreate
      tags:
        - Pedidos
      summary: Cria pedido
      description: >-
        Cria um pedido da empresa autenticada — endpoint **compartilhado** por todas as telas que criam pedidos
        (**Pedidos**, **PDV/Store Front**, **Ordem de serviço**, devolução/Reversa, importação). A tela de **Ordem de
        serviço** usa este mesmo endpoint enviando o tipo de pedido marcado como ordem de serviço; o subconjunto de
        campos enviado por cada tela varia.


        **O que o endpoint faz:**


        1. Resolve a empresa a partir do token e, quando `ShareDataWithRelatedCompanies=1`, o grupo de empresas
        relacionadas.

        2. Valida tipo de pedido, vendedor, centro de distribuição, integração, cliente e endereços; monta itens,
        pagamentos e dados fiscais e grava o pedido.

        3. Quando o tipo de pedido emite NFCe (PDV), o pedido já nasce como `StoreFrontOrder=1`.

        4. Retorna a ficha completa do pedido recém-criado, acrescentando `Danfe65Base64Encode` (PDF da DANFE NFCe em
        base64, quando houver).


        **Campos obrigatórios** dependem do tipo de pedido e das parametrizações da empresa: há fallbacks para tipo de
        pedido padrão, centro de distribuição padrão e vendedor automático (`AutomaticSetSalesmanNewOrder`). O
        `required` abaixo reflete o conjunto exigido pelo fluxo de criação padrão do frontend.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - IDOrderType
                - IDSalesman
                - IDStockKeepingUnitDistributionCenter
                - IDConsumer
                - IDAddress
                - ShippingEstimateDate
              properties:
                IDOrderType:
                  type: integer
                  format: int64
                  description: >-
                    Tipo de pedido. Na criacao de ordem de servico, apenas os tipos marcados como ordem de servico. Sem
                    valor, usa o tipo de pedido padrao da empresa; se nao houver padrao, retorna 400.
                IDSalesman:
                  type: integer
                  format: int64
                  description: >-
                    Vendedor responsavel (na ordem de servico, o tecnico responsavel). Quando ausente e a empresa usa
                    atribuicao automatica de vendedor, e preenchido pelo sistema.
                IDStockKeepingUnitDistributionCenter:
                  type: integer
                  format: int64
                  description: >-
                    Centro de distribuicao de onde o pedido sera atendido. Sem valor, usa o centro de distribuicao
                    padrao da empresa; se nao houver padrao, retorna 400.
                IDConsumer:
                  type: integer
                  format: int64
                  description: Cliente do pedido. Deve estar cadastrado para a empresa.
                IDAddress:
                  type: integer
                  format: int64
                  description: Endereco de cobranca do cliente (IDConsumer).
                IDAddressDelivery:
                  type: integer
                  format: int64
                  description: Endereco de entrega, quando diferente do endereco de cobranca.
                ShippingEstimateDate:
                  type: string
                  format: date-time
                  description: >-
                    Data/hora prevista para entrega/atendimento (na ordem de servico, a data de previsao do
                    atendimento).
                IDCompanyIntegration:
                  type: integer
                  format: int64
                  description: >-
                    Integracao de origem do pedido. Quando o tipo de pedido exige integracao e o valor nao e informado,
                    retorna 400.
                IDCompanyInvoice:
                  type: integer
                  format: int64
                  description: Empresa faturadora, quando diferente da empresa do pedido.
                Order:
                  type: string
                  description: Numero/identificador externo do pedido. Quando ausente, o sistema gera a numeracao.
                OrderComments:
                  type: string
                  description: Observacao do pedido (texto livre).
                OrderFrom:
                  type: string
                  description: Origem do pedido (canal/marketplace de procedencia), quando aplicavel.
                OrderGift:
                  type: integer
                  description: 1 marca o pedido como presente.
                Budget:
                  type: integer
                  enum:
                    - 0
                    - 1
                  default: 0
                  description: 1 cria o registro como orcamento (nao movimenta estoque ate a conversao).
                BalanceChange:
                  type: integer
                  enum:
                    - 0
                    - 1
                  description: 'Tipo do registro: 1 Pedido (movimenta estoque) x 0 Nota Fiscal (sem movimentacao).'
                IDStatusOrder:
                  type: integer
                  format: int64
                  description: Status inicial do pedido. Sem valor, o pedido nasce em 0 (Aberto). Status invalido retorna 400.
                IDServiceOrder:
                  type: integer
                  format: int64
                  description: Ordem de servico vinculada, quando o pedido e gerado a partir de uma OS existente.
                ValueShipping:
                  type: number
                  format: double
                  default: 0
                  description: Valor do frete do pedido.
                IDCarrier:
                  type: integer
                  format: int64
                  description: Transportadora do pedido. Quando informada, deve estar cadastrada e ativa.
                Consumer:
                  type: object
                  description: >-
                    Dados do cliente para cadastro/atualizacao no ato da criacao (alternativa a informar um IDConsumer
                    ja existente). Campos aceitos incluem ConsumerCpfCnpj, ConsumerNameCorporateName, ConsumerTradeName,
                    ConsumerEmail, ConsumerTelephone, ConsumerType, Address e DeliveryAddress.
                  additionalProperties: true
                Invoice:
                  type: object
                  description: >-
                    Dados da nota fiscal a emitir/vincular junto com o pedido. Campos aceitos incluem NfeNumber,
                    NfeSerie, NfeChaveAcesso, NfeModelo, NfeTotalValue, NfedhEmi, NfecStat, NfenProt, NfetpEmis.
                  additionalProperties: true
                Tags:
                  type: array
                  description: Etiquetas/marcadores a vincular ao pedido.
                  items:
                    type: object
                    additionalProperties: true
                InvoiceType:
                  type: integer
                  enum:
                    - 1
                    - 2
                  description: 'Tipo de comprovante: 1 documento fiscal, 2 recibo.'
                IssueInvoice:
                  type: integer
                  enum:
                    - 0
                    - 1
                  description: 1 solicita a emissao da nota fiscal ja na criacao do pedido.
                NFCe:
                  type: integer
                  enum:
                    - 0
                    - 1
                  description: 1 indica pedido com NFCe (PDV); forca StoreFrontOrder=1.
                StoreFrontOrder:
                  type: integer
                  enum:
                    - 0
                    - 1
                  description: 1 marca o pedido como originado no PDV/Store Front.
                IDStoreFrontCashier:
                  type: integer
                  format: int64
                  description: Caixa do PDV em que o pedido foi lancado.
                IDStoreFrontCashierOrderTemp:
                  type: integer
                  format: int64
                  description: Identificador temporario do pedido em aberto no caixa do PDV, usado para consolidar o lancamento.
                IDOrderIntention:
                  type: integer
                  format: int64
                  description: Intencao de pedido (pre-pedido) a partir da qual este pedido e materializado.
                IDTypeOrderReturn:
                  type: integer
                  format: int64
                  description: Motivo de devolucao. Obrigatorio quando o pedido e uma devolucao (Reversa).
                IDTypeOrderReturnCategory:
                  type: integer
                  format: int64
                  enum:
                    - 1
                    - 2
                    - 3
                  description: >-
                    Categoria de devolucao. Obrigatoria quando o pedido e uma devolucao (Reversa): 1=Troca/Vale,
                    2=Reembolso, 3=Insucesso de entrega.
                IDOrderOriginReturn:
                  type: integer
                  format: int64
                  description: Pedido original que esta sendo devolvido (quando este pedido e a devolucao).
                IDStockKeepingUnitWarehouseReturn:
                  type: integer
                  format: int64
                  description: Armazem de retorno dos itens na devolucao.
                ConsumerVoucher:
                  type: number
                  format: double
                  description: Valor de vale-compras do cliente aplicado ao pedido. Nao pode exceder o disponivel para a loja.
                CreateInbound:
                  type: integer
                  enum:
                    - 0
                    - 1
                  description: 1 gera tambem o recebimento (inbound) associado ao pedido.
                SendEmail:
                  type: integer
                  enum:
                    - 0
                    - 1
                  default: 0
                  description: 1 dispara o e-mail de confirmacao ao cliente.
                NFeFin:
                  type: string
                  description: Finalidade da NF-e (normal, complementar, ajuste, devolucao).
                NFeType:
                  type: integer
                  enum:
                    - 0
                    - 1
                  description: 'Tipo da NF-e: 0 entrada, 1 saida.'
                NfeindFinal:
                  type: integer
                  description: Indicador de consumidor final da NF-e.
                NfeModFrete:
                  type: string
                  description: Modalidade de frete da NF-e.
                NfeNatureOperation:
                  type: string
                  description: Natureza da operacao da NF-e.
                NfeCfopPriority:
                  type: string
                  description: CFOP prioritario a aplicar na NF-e.
                NfeComments:
                  type: string
                  description: Informacoes complementares da NF-e.
                NfeAccessoryExpenses:
                  type: number
                  format: double
                  default: 0
                  description: Despesas acessorias da NF-e.
                NfeFactorPercent:
                  type: number
                  format: double
                  description: Percentual de fator aplicado no calculo da NF-e.
                NfeNoPayment:
                  type: integer
                  enum:
                    - 0
                    - 1
                  description: 1 permite faturar sem pagamento cadastrado (depende de privilegio); tambem ignora o array Payments.
                NfeChaveAcessoDevolucao:
                  type: string
                  description: Chave de acesso da NF-e referenciada em devolucao.
                ShippingEstimateHandlingLimitDate:
                  type: string
                  format: date-time
                  description: >-
                    Data/hora limite estimada de expedicao (prazo de manuseio). Usada principalmente em pedidos
                    integrados de canais de venda. Campo novo (adicionado em 2026-06-22).
                Items:
                  type: array
                  description: Itens do pedido. Podem ser enviados aqui na criacao ou pelos endpoints filhos de item.
                  items:
                    type: object
                    required:
                      - IDSku
                      - Quantity
                    properties:
                      IDSku:
                        type: integer
                        format: int64
                        description: >-
                          SKU do item. Deve estar cadastrado para a loja; item do tipo Produto (pai) nao pode ser
                          adicionado ao pedido.
                      Quantity:
                        type: number
                        format: double
                        description: Quantidade do item.
                      PriceSelling:
                        type: number
                        format: double
                        description: Preco de venda unitario praticado no item.
                      OriginalPriceSelling:
                        type: number
                        format: double
                        description: Preco de venda unitario antes de desconto manual, usado no calculo do limite de desconto.
                      ValueDiscount:
                        type: number
                        format: double
                        description: Valor de desconto aplicado ao item.
                      ValueCost:
                        type: number
                        format: double
                        description: Custo unitario do item.
                      IDStockKeepingUnitWarehouse:
                        type: integer
                        format: int64
                        description: >-
                          Armazem de onde o item sai. Quando omitido, usa o armazem do tipo de pedido ou o armazem
                          padrao da empresa. Deve pertencer ao centro de distribuicao do pedido.
                      IDCompanySalesPolicy:
                        type: integer
                        format: int64
                        description: Politica comercial usada para buscar o preco de lista/tabela do item.
                      IDUserDiscount:
                        type: integer
                        format: int64
                        description: Usuario que concede o desconto; usado para validar o limite de desconto permitido.
                      IDStockKeepingUnitPromotion:
                        type: integer
                        format: int64
                        description: Promocao aplicada ao item (dispensa a validacao de limite de desconto manual).
                      IDTypeOrderReturn:
                        type: integer
                        format: int64
                        description: Motivo de devolucao especifico do item (em pedidos de devolucao).
                      IDPurchase:
                        type: integer
                        format: int64
                        description: Compra vinculada ao item, quando aplicavel.
                      BalanceChange:
                        type: integer
                        enum:
                          - 0
                          - 1
                        description: 1 movimenta estoque para o item; 0 nao movimenta.
                Payments:
                  type: array
                  description: >-
                    Pagamentos do pedido. Ignorados quando NfeNoPayment=1. A soma dos Value compoe o total de pagamento
                    do pedido.
                  items:
                    type: object
                    required:
                      - Value
                    properties:
                      IDTypePayment:
                        type: integer
                        format: int64
                        description: >-
                          Tipo de pagamento. Deve estar cadastrado para a empresa; quando omitido, usa o tipo de
                          pagamento padrao de pedido da empresa.
                      Value:
                        type: number
                        format: double
                        description: Valor do pagamento.
                      IDBankAccount:
                        type: integer
                        format: int64
                        description: Conta bancaria do pagamento. Quando informada, deve estar cadastrada.
                      IDBankAccountForecast:
                        type: integer
                        format: int64
                        description: Conta bancaria de previsao do pagamento. Quando informada, deve estar cadastrada.
                      NoSplit:
                        type: integer
                        enum:
                          - 0
                          - 1
                        description: 1 impede o split/parcelamento automatico do pagamento.
        description: >-
          Dados do pedido a criar. Cabeçalho (cliente, endereço, vendedor, CD, tipo de pedido) é obrigatório; itens,
          pagamento, pacotes e arquivos podem ser enviados aqui ou nos endpoints filhos. Quando `IDOrderType`,
          `IDStockKeepingUnitDistributionCenter`, `IDSalesman` ou `ShippingEstimateDate` são omitidos, o sistema tenta
          resolver pelo padrão da empresa — sem padrão configurado retorna `400`.
      responses:
        '200':
          description: >-
            Pedido criado. Retorna um array com a ficha completa do pedido recém-criado (mesma estrutura do registro de
            pedido), acrescido de `Danfe65Base64Encode` (PDF da DANFE NFCe em base64, `null` quando não aplicável).
          content:
            application/json:
              schema:
                type: array
                items:
                  allOf:
                    - $ref: '#/components/schemas/OrdersListItem'
                    - type: object
                      properties:
                        Danfe65Base64Encode:
                          type: string
                          nullable: true
                          description: PDF da DANFE da NFCe em base64, quando o pedido emitiu NFCe; caso contrário, `null`.
        '400':
          description: >-
            Dados inválidos ou cadastro ausente. Mensagens emitidas (sem o prefixo): `Precisa enviar a conta para criar
            o pedido`, `Empresa não encontrada`, `Tipo pedido informado não cadastrado ou empresa não possui tipo pedido
            padrão`, `Status pedido não cadastrado ou inválido ao criar pedido`, `Vendedor não existe`, `Centro de
            distribuição não existe`, `Empresa não possui centro de distribuição padrão`, `Integração não cadastrada`,
            `Obrigatório informar a integração`, `Empresa faturadora não encontrada`, `Consumidor não cadastrado`,
            `Endereço não cadastrado`, `Endereço entrega não cadastrado`, `Transportadora não cadastrada ou inativa`,
            `SKU(s) não cadastrados: …`, `Itens são tipo produto e não pode ser adicionado ao pedido`, `Armazém(s) não
            cadastrado: …`, `Tipo documento padrão não cadastrado`, `Plano de contas padrão não cadastrado`, `Não tem
            motivo de devolução cadastrado`, `Não tem categoria de devolução cadastrada`, `Pedido com emissão de NFCe,
            mas não tem tipo de pedido para NFCe`, `Tipo pedido emite NFCe e nota fiscal é devolução. Não é permitido
            emitir NFCe de devolução`, `Valor do vale compras é acima do disponível para a loja: …`, `Problema adicionar
            pagamento: …`, `Erro ao criar pedido`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /orders/{idorder}/status:
    put:
      operationId: orderStatusPut
      tags:
        - Pedidos
      summary: Altera status do pedido
      description: >-
        Move o pedido de um status para outro, respeitando as transições configuradas em `TypeStatusOrderRule` para a
        empresa. Usado pelo botão **Cancelar** da tela **Outbound** com `IDOrderStatusTo=90`, mas serve a **todas as
        transições** disparadas pelas telas de operação (Pedidos, Picking-List, Romaneio, Tracking, etc.).


        **Fluxo do sistema:**


        1. Localiza o pedido pelo `IDOrder` da rota + `AccountName` do contexto (`AccountName = prefix`).

        2. Lê `IDStatusOrder` atual + `IDCarrierType`, `IDStatusInvoice` da NF principal,
        `IDOrdersCarrierCollectionList`, `IDPickingList`.

        3. Consulta `TypeStatusOrderRule` (transições permitidas saindo do status atual) e valida que `IDOrderStatusTo`
        está na lista. Se não estiver, retorna `[BadRequest] - Status não permite alteração`.

        4. Aplica validações específicas do **status destino** (cada `IDOrderStatusTo` tem o seu `case`). Os casos mais
        relevantes:
           - **`0` Aberto** — reverte para Aberto. Quando a NF principal está em status `IN (2, 3, 4, 5, 7, 8)` (Enviada/Emitida/Processando/Pendente conciliação EPEC/Cancelada/Denegada) e a parametrização `AllowOpenOrderInvoiced != 1`, bloqueia com `[BadRequest] - Desvincular nota fiscal antes de alterar status`. Reseta `BalanceChange` em movimentos e `Budget=0` quando o status origem está em margem/crédito.
           - **`1` Fechado** — só permitido a partir de `11` (Falta produto) ou `93` (Em produção).
           - **`90` Cancelado** (botão da tela Outbound) — bloqueia quando `IDOrdersCarrierCollectionList > 0` (`[BadRequest] - Pedido esta em romaneio X, retirar antes de mudar status`) ou `IDPickingList > 0` (`[BadRequest] - Pedido esta na Picking List X, retirar antes de mudar status`). Caso liberado: zera `BalanceChange` dos movimentos, deleta `Packages`, ajusta `AccountsPayableReceivable` (status `4` Cancelado quando ainda em aberto; mantém status quando pago; cria contra-lançamento em `AccountsPayableReceivableBankStatement` quando pagamento foi em dinheiro / `Category=7`), zera `PickingBasket`/`IDOrdersCarrierCollectionList`/`IDPickingList` no pedido e atualiza `IDStatusOrder=90`.
           - **`91` Extraviado**, **`92` Extraviado parcialmente**, **`94` Devolvido**, **`95` Em devolução**, **`97` Reversa finalizada** — disponíveis para transições típicas do pós-envio. Bloqueio depende da regra cadastrada em `TypeStatusOrderRule`.
        5. Grava um evento em `OrderEvents` (`IDEvent=35` para Aberto, `19` para Cancelado, etc.) com
        `RecordUserCreated` e `StatusDate`.


        **Validações de body comuns**:


        - `IDOrderStatusTo` precisa estar na lista de transições permitidas a partir do status atual.

        - Quando o `CommentsRequired=1` para o destino e `StatusComment` está vazio, retorna `[BadRequest] - Comentário
        precisa ser preenchido`.

        - `StatusDate` não pode ser mais de 5 min no futuro (`[BadRequest] - Data Evento não pode ser superior a data
        atual`).
      parameters:
        - name: idorder
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Código interno do pedido (`IDOrder`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderStatusPutPayload'
        description: >-
          Movimento de status do pedido. `IDOrderStatusTo` indica o status destino (ver `support
          data/TypeStatusOrder.csv`); `StatusComment` é a justificativa registrada no histórico (obrigatória para alguns
          status — ex.: cancelamento). O motor de status valida transições proibidas (pedidos faturados, picking
          iniciado, etc.) e dispara recálculos/cancelamentos de NF quando o destino é cancelamento.
      responses:
        '200':
          description: Transição aplicada. Body de resposta é a string literal `"sucesso"`.
          content:
            application/json:
              schema:
                type: string
                example: sucesso
        '400':
          description: >-
            Validação falhou. Mensagens emitidas:

            - `[BadRequest] - não localizado` (path `idorder` ausente/inválido).

            - `[BadRequest] - Status não permite alteração` (transição não cadastrada em `TypeStatusOrderRule` para a
            empresa).

            - `[BadRequest] - Comentário precisa ser preenchido` (quando o destino exige comentário e `StatusComment`
            veio vazio).

            - `[BadRequest] - Data Evento não pode ser superior a data atual` (`StatusDate` > agora + 5 min).

            - `[BadRequest] - Desvincular nota fiscal antes de alterar status` (transição → `0` Aberto com NF em status
            conflitante).

            - `[BadRequest] - Pedido esta em romaneio X, retirar antes de mudar status` (transição → `90` Cancelado com
            pedido amarrado em romaneio).

            - `[BadRequest] - Pedido esta na Picking List X, retirar antes de mudar status` (transição → `90` com pedido
            em picking-list ativa).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '404':
          description: Pedido não encontrado. Mensagens emitidas pela operação começam com `[NotFound]`.
        '500':
          description: Erro inesperado. Mensagens começam com `Error:`.
  /orders/log:
    get:
      operationId: ordersLogList
      tags:
        - Pedidos
      summary: Lista eventos do pedido (Log Pedidos)
      description: >-
        Lista o histórico de ações realizadas em pedidos (`OrderEvents`), com `EventDescription`, executor (`User`),
        `Order` e conta já resolvidos. Paginação fixa em **5000 registros por página** (`Page=N` → offset `N*5000`),
        ordenado por `IDOrderEvents` decrescente (mais recentes primeiro). Em contexto multi-conta (`accountname =
        all`), traz todas as contas acessíveis ao usuário.


        Nenhum filtro é obrigatório. Todos os filtros são combinados com AND. A faixa de data filtra eventos com
        `RecordTimestamp` entre `DateFrom` e o final de `DateTo` (inclusive).
      parameters:
        - name: IDOrder
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo código interno do pedido (mostrado como **Código pedido** na tela).
        - name: Order
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo número do pedido visível ao cliente (`Order`).
        - name: IDEvent
          in: query
          required: false
          schema:
            type: integer
          description: >-
            Filtra pelo tipo da ação (`IDEvent`). Ex.: `0` Pedido criado, `2` Finalizar pedido, `19` Cancelar pedido,
            `35` Alteração status. Lista completa em `support data/TypeOrderEvents.csv`.
        - name: Header
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
              - 2
          description: >-
            Resultado da ação: `0` Erro (Problema), `1` Sucesso, `2` Inativo. O select da tela só oferece Erro e Sucesso
            — `2` (Inativo) aparece na lista mas não é selecionável no filtro.
        - name: RecordUserCreated
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo usuário que disparou a ação (`IDUser`).
        - name: DateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: >-
            Data inicial da janela: traz eventos com `RecordTimestamp` a partir desta data (inclusive). Quando informada
            sem `DateTo`, o limite superior fica aberto.
        - name: DateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data final da janela. O sistema concatena ` 23:59:59` para incluir o dia inteiro.
        - name: Page
          in: query
          required: false
          schema:
            type: integer
          description: Página (offset = `Page * 5000`).
      responses:
        '200':
          description: Lista de eventos de pedido.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderEventLogItem'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /orders/gnre:
    get:
      operationId: orderGnreList
      tags:
        - Pedidos
      summary: Lista GNRE (ou apuração DIFAL com Summary=1)
      description: >-
        Endpoint compartilhado pelas telas **GNRE** e **Apuração DIFAL**. O comportamento depende da querystring
        `Summary`:


        - **`Summary` omitido ou `0`** — tela **GNRE**. Devolve uma linha por guia (`Gnre`) com `IDGnre`, `BarCode`,
        `DueDate`, `RevenueCode` (com `Description` resolvido), `ReceiptNumber`, `StatusProcessCode`
        (`StatusDescription`), `GnreValue`/`GnreInterest`/`GnreRestatement`/`GnrePenalty` (computa `GnreTotalValue =
        soma dos quatro`), `IDOrder`, `Order`, `NfeNumber/Serie/dhEmi/StatusInvoice`, `SupplierNameCorporateName` (da
        transportadora), `AccountName` da conta e da NF, `OrderFrom` (canais concatenados).

        - **`Summary=1`** — tela **Apuração DIFAL**. Devolve uma linha por pedido com NF principal de modelo `55`
        (`NfeModelo = 55`), trazendo `NfedhEmi`, `NfeChaveAcesso`, `NfeNumber/Serie`, `IDStatusInvoice`+`StatusInvoice`,
        `GnreStatusDescription` (descrição do último status de processamento da guia do pedido),
        `CompanyIntegrationName`, `StatusOrder`, `TypeOrder`, `ShippingDate` (max de Packages), `ValueOrder` (soma de
        `PriceSellingTotal` + `ValueShipping` + `NfeAccessoryExpenses`), `NfeValueIcmsUfDest` e `NfeValueFcpUfDest`
        (soma do movimento). O sinal dos valores é positivo quando `NfeType=1` (saída) e negativo quando `NfeType=0`
        (entrada).


        Paginação fixa em **5000 registros por página** (`Page=N` → offset `N*5000`). Em contexto multi-conta
        (`accountname = all`), traz todas as contas acessíveis.
      parameters:
        - name: Summary
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` ativa o modo apuração DIFAL; omitido ou `0` lista as guias GNRE.'
        - name: Order
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo número do pedido (`Order`).
        - name: IDOrder
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo código interno do pedido (`IDOrder`).
        - name: NfeNumber
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo número da NF principal (`NfeNumber`).
        - name: NfeSerie
          in: query
          required: false
          schema:
            type: string
          description: Filtra pela série da NF principal.
        - name: OrderFrom
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo canal de origem do pedido (busca em `OrderFrom`).
        - name: IDStatusOrder
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo status do pedido.
        - name: IDStatusInvoice
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo status da NF principal.
        - name: IDCarrier
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pela transportadora (`IDCarrier`).
        - name: ShippingState
          in: query
          required: false
          schema:
            type: string
          description: Filtra pela UF de destino (`ShippingState`).
        - name: ReceiptNumber
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo número de protocolo da guia (`ReceiptNumber`).
        - name: IDCompanyInvoice
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo faturador (`IDCompanyInvoice`).
        - name: IDOrderType
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo tipo do pedido.
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pela integração de origem do pedido.
        - name: DateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data inicial de criação da guia (`Recordtimestamp ≥`). Aplicado apenas no modo guias (`Summary=0`).
        - name: DateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data final de criação da guia (concatenada com ` 23:59:59`).
        - name: InvoiceDateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data inicial de emissão da NF (`NfedhEmi`).
        - name: InvoiceDateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data final de emissão da NF.
        - name: ShippingDateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data inicial de envio (`ShippingDate`).
        - name: ShippingDateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: >-
            Data final de envio. **Observação**: por bug no sistema, o limite superior usa `InvoiceDateTo` em vez de
            `ShippingDateTo`.
        - name: DueDateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Vencimento mínimo da guia (`DueDate ≥`).
        - name: DueDateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Vencimento máximo da guia.
        - name: Page
          in: query
          required: false
          schema:
            type: integer
          description: Página (offset = `Page * 5000`).
      responses:
        '200':
          description: >-
            Lista de guias GNRE (default) ou de linhas de apuração DIFAL (`Summary=1`). `[]` quando nada bate com os
            filtros.
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/GnreListItem'
                  - type: array
                    items:
                      $ref: '#/components/schemas/DifalSummaryItem'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: orderGnrePost
      tags:
        - Pedidos
      summary: Gera GNRE em massa para os pedidos selecionados
      description: >-
        Aciona a geração de GNRE para uma lista de pedidos. Para cada pedido valida que existe NF principal (`Main=1`)
        com status emitido (`IDStatusInvoice=3`). Os pedidos válidos são agrupados por `AccountNameInvoice` (faturador)
        e processados em paralelo: para cada grupo, o sistema gera a GNRE e envia o lote à SEFAZ. Devolve `"sucesso"`
        quando todos os lotes são gerados com OK; o primeiro erro aborta com a mensagem propagada.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: integer
              description: Array de `IDOrder`.
        description: >-
          Array de `IDOrder` para emitir GNRE em lote. Todos os pedidos precisam ter nota fiscal emitida
          (`IDStatusInvoice=3`) — caso contrário retorna `400`. Os pedidos são agrupados pela empresa faturadora e
          enviados ao processo fiscal.
      responses:
        '200':
          description: 'Sucesso. Corpo: string `"sucesso"`.'
          content:
            application/json:
              schema:
                type: string
                example: sucesso
        '400':
          description: >-
            `[BadRequest] - Nota fiscal não emitida` (NF do primeiro pedido ainda não está em `IDStatusInvoice=3`);
            `[BadRequest] - Pedido não localizado` (nenhum pedido válido encontrado para o `AccountName` do contexto).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro propagado pela geração da GNRE — mensagem retornada pelo serviço de emissão à SEFAZ.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /orders/gnre/file:
    post:
      operationId: gnreFileDownload
      tags:
        - Pedidos
      summary: Baixa ZIP com os PDFs das guias selecionadas
      description: >-
        Recebe um array de `IDGnre` e gera um arquivo ZIP contendo `<IDGnre>.pdf` para cada guia válida da empresa. O
        ZIP é gravado em `Temp/<uuid>.zip` no bucket S3 e retornado por meio de **URL assinada válida por 2 dias**. Em
        paralelo, dispara um e-mail (SES, modelo `Html/exportar-XML.html`) para o usuário solicitante com o mesmo link.
        O corpo da resposta é a URL assinada.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: integer
              description: Array de `IDGnre`.
        description: Array de `IDGnre` cujos PDFs serão zipados e disponibilizados por e-mail ao usuário solicitante.
      responses:
        '200':
          description: URL assinada do arquivo ZIP (válida por 2 dias).
          content:
            application/json:
              schema:
                type: string
                format: uri
                example: >-
                  https://idworks-bucket.s3.amazonaws.com/Temp/abc123-def456.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600
        '500':
          description: Erro interno (falha de upload S3, falha SES).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /orders/gnre/{idgnre}:
    get:
      operationId: gnreFileGet
      tags:
        - Pedidos
      summary: Devolve o PDF de uma guia individual
      description: >-
        Usado pela ação **Visualizar arquivo** na tela GNRE para abrir o PDF da guia em um modal. Resposta: stream/URL
        do PDF correspondente ao `IDGnre` informado.
      parameters:
        - name: idgnre
          in: path
          required: true
          schema:
            type: integer
          description: Id da guia GNRE.
      responses:
        '200':
          description: Conteúdo/URL do PDF da guia.
        '404':
          description: Guia não encontrada.
        '500':
          description: Erro interno.
  /orders/tracking:
    get:
      operationId: orderTrackingList
      tags:
        - Pedidos
      summary: Lista pedidos em rastreamento
      description: >-
        Lista pedidos com informação de rastreio agregada. Retorna até 3000 itens por página (`Page` controla o offset =
        `Page * 3000`). Inclui dados do pedido, último evento de tracking da transportadora, status calculados de
        entrega e indicadores de pontualidade.


        Quando `TrackingEnabled=1` é informado, a listagem restringe aos pedidos cuja transportadora tem
        `TrackingEnabled = 1` (integração de rastreio ativa); pedidos sem transportadora vinculada deixam de aparecer
        nesse modo.
      parameters:
        - name: DateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: '`RecordTimestamp` ≥ data.'
        - name: DateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: '`RecordTimestamp` ≤ data 23:59:59.'
        - name: ShippingDateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data de postagem ≥ (filtra `ShippingDate`).
        - name: ShippingDateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data de postagem ≤ 23:59:59.
        - name: ShippingEstimateDateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data estimada de entrega ≥ (`ShippingEstimateDate`).
        - name: ShippingEstimateDateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data estimada de entrega ≤ 23:59:59.
        - name: Order
          in: query
          required: false
          schema:
            type: string
          description: Busca parcial pelo número do pedido (`LIKE`).
        - name: IDOrder
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo identificador do pedido.
        - name: NfeNumber
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo número da NF-e.
        - name: OrderFrom
          in: query
          required: false
          schema:
            type: string
          description: Origem externa do pedido (chave-código no `OrderFrom`).
        - name: ConsumerNameCorporateName
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo nome ou razão social do cliente (busca parcial).
        - name: ConsumerCpfCnpj
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo CPF ou CNPJ do cliente.
        - name: ConsumerEmail
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo e-mail do cliente.
        - name: IDCarrier
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo identificador da transportadora.
        - name: IDSalesChannel
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo identificador do canal de venda.
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo identificador da integração da empresa.
        - name: TrackingIDStatus
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo último status do tracking do pacote.
        - name: IDStatusDeliveryConsumer
          in: query
          required: false
          schema:
            type: integer
          description: >-
            Filtra pelo indicador de pontualidade consumidor (calculado: 1=Antes do prazo, 2=Após o prazo, 3=Em curso,
            4=Atrasado, 6=No prazo). Aplicado como HAVING.
        - name: IDStatusDeliveryCarrier
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo indicador de pontualidade transportadora (mesmos códigos). Aplicado como HAVING.
        - name: TrackingEnabled
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` força filtro pelos pedidos cuja transportadora tem integração de rastreio ativa.'
        - name: Page
          in: query
          required: false
          schema:
            type: integer
          description: Página (offset = `Page * 3000`).
      responses:
        '200':
          description: Lista de pedidos em rastreamento (até 3000).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderTrackingListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/location/group:
    get:
      operationId: skuLocationGroupList
      tags:
        - Endereços de Estoque
      summary: Lista grupos de endereços
      description: Lista grupos de endereços (`StockKeepingUnitLocationGroup`) da empresa, ordenados pelo nome.
      parameters:
        - name: IDStockKeepingUnitLocationGroup
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo identificador do grupo de localização do SKU.
        - name: StockKeepingUnitLocationGroupName
          in: query
          required: false
          schema:
            type: string
          description: Nome exato do grupo.
      responses:
        '200':
          description: Lista de grupos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuLocationGroupListItem'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: skuLocationGroupPost
      tags:
        - Endereços de Estoque
      summary: Cria um grupo de endereços
      description: Cria um grupo de endereços para a empresa autenticada. Nome precisa ser **único** dentro da empresa.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuLocationGroupCreate'
        description: Dados do grupo de endereços a cadastrar (agrupamento de endereços que compartilham configuração).
      responses:
        '200':
          description: Grupo criado (retorna o detalhe via list).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuLocationGroupListItem'
                maxItems: 1
        '400':
          description: >-
            `[BadRequest] - Empresa não existe`; `[BadRequest] - Grupo já existente`; `[BadRequest] - Erro ao inserir a
            grupo`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/location/group/{idstockkeepingunitlocationgroup}:
    parameters:
      - name: idstockkeepingunitlocationgroup
        in: path
        required: true
        schema:
          type: integer
    put:
      operationId: skuLocationGroupPut
      tags:
        - Endereços de Estoque
      summary: Atualiza um grupo de endereços
      description: Atualiza o nome do grupo. Valida unicidade do nome dentro da empresa (excluindo o próprio registro).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuLocationGroupCreate'
        description: Atualiza o grupo de endereços. Mesmo schema do POST.
      responses:
        '200':
          description: Grupo atualizado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuLocationGroupListItem'
                maxItems: 1
        '400':
          description: >-
            `[BadRequest] - Preencha corretamente o nome do grupo`; `[BadRequest] - Grupo não encontrada`; `[BadRequest]
            - Grupo já existente`; `[BadRequest] - Grupo não atualizado`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: skuLocationGroupDelete
      tags:
        - Endereços de Estoque
      summary: Exclui um grupo de endereços
      description: >-
        **Exclusão física** do grupo de endereços. Bloqueada quando existe pelo menos um endereço
        (`StockKeepingUnitLocation`) vinculado ao grupo — neste caso devolve `200` com mensagem texto `Grupo esta
        vinculado a endereço. Editar endereço antes de excluir o grupo` (sem prefixo `[BadRequest]`).
      responses:
        '200':
          description: Grupo excluído (string literal `"sucesso"`) ou mensagem de bloqueio.
          content:
            application/json:
              schema:
                type: string
        '400':
          description: '`[BadRequest] - Grupo não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/batch:
    get:
      operationId: skuBatchList
      tags:
        - Lotes
      summary: Lista lotes e endereços de SKU
      description: >-
        Lista os lotes de SKU da empresa com dados do produto, do endereço de armazenagem (armazém, centro de
        distribuição, grupo, categoria e tipo de endereço), validade, data de fabricação, comentários e saldos
        calculados: saldo do lote `BatchBalance`, quantidade em movimentação `QtyHandling` e saldo disponível do SKU no
        armazém `QtyAvailable`. Retorna também preço de venda `PriceSell` e preço de tabela `PriceList`; ao informar uma
        política comercial em `IDCompanySalesPolicy`, os preços seguem essa política e, havendo promoção ativa, o
        desconto percentual `PercentualDiscountValue` é aplicado ao `PriceSell`. Considera apenas SKUs não deletados dos
        tipos Sku, Matéria-prima e Uso e consumo. Respeita a restrição de centros de distribuição do usuário e o
        compartilhamento de estoque entre empresas relacionadas.
      parameters:
        - name: IDSku
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo identificador do produto/SKU.
        - name: IDBatch
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo identificador do lote.
        - name: IDStockKeepingUnitLocation
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo identificador da localização do SKU.
        - name: IDStockKeepingUnitWarehouse
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo identificador do depósito do SKU.
        - name: IDStockKeepingUnitDistributionCenter
          in: query
          required: false
          schema:
            type: string
          description: Aceita CSV.
        - name: SkuName
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo nome do produto (busca parcial).
        - name: IDSkuCompany
          in: query
          required: false
          schema:
            type: string
          description: Código de referência do SKU (`LIKE`).
        - name: BarCode
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo código de barras do produto.
        - name: Address
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo logradouro do endereço (busca parcial).
        - name: DateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: '`BestBeforeDate` ≥ data.'
        - name: DateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: '`BestBeforeDate` ≤ data.'
        - name: Status
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` lotes Ativos (com saldo), `0` Inativos (sem saldo).'
        - name: Search
          in: query
          required: false
          schema:
            type: string
          description: Busca multi-campo (SKU, nome, endereço, código de barras). `nulladdress` filtra lotes sem endereço.
        - name: Page
          in: query
          required: false
          schema:
            type: integer
          description: Número da página da listagem (1-based). Padrão `1`.
        - name: IDCompanySalesPolicy
          in: query
          required: false
          schema:
            type: integer
          description: >-
            Identificador da política comercial usada para calcular os preços `PriceSell` e `PriceList` de cada lote.
            Quando informada e diferente da política padrão, promoções ativas do SKU também são aplicadas (desconto
            retornado em `PercentualDiscountValue`). Quando omitida, usa a política comercial padrão da empresa.
      responses:
        '200':
          description: Lista de lotes.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuBatchItem'
        '400':
          description: >-
            Validação falhou. Prefixo `[BadRequest]`. Mensagem: `Política comercial não existe` — quando
            `IDCompanySalesPolicy` é informado mas não corresponde a nenhuma política comercial da empresa.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/batch/{idsku}:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
    post:
      operationId: skuBatchPost
      tags:
        - Lotes
      summary: Cria lote para um SKU
      description: >-
        Cria um lote no SKU em um endereço específico. Validações:


        - **SKU sem controle de lote** (`Batch != 1`): se já existe lote desse SKU no endereço, devolve `[BadRequest] -
        SKU já tem este endereço`.

        - **Endereço** precisa pertencer à empresa (ou empresa relacionada com `ShareSkuLocationWithRelatedCompanies =
        1`).

        - Quando `Default = 1`, zera o `Default` dos demais lotes do SKU antes de inserir.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuBatchCreate'
        description: >-
          Dados do lote a cadastrar para o SKU. `BestBeforeDate` (validade) e `ManufacturingDate` (fabricação) são
          obrigatórios; `IDStockKeepingUnitLocation` define o endereço de alocação. `Default=1` marca este lote como o
          de saída prioritária nas vendas.
      responses:
        '200':
          description: Lote criado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuBatchItem'
                maxItems: 1
        '400':
          description: >-
            `[BadRequest] - SKU não existe`; `[BadRequest] - SKU já tem este endereço`; `[BadRequest] - Endereço SKU não
            existe`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    put:
      operationId: skuBatchPutByBody
      tags:
        - Lotes
      summary: Atualiza lote (id no body)
      description: Versão do PUT em que o `IDBatch` vem no corpo. Mesmas validações do PUT por path.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuBatchUpdate'
        description: >-
          Atualização parcial do lote (sem mudança do identificador do lote — para alterar um lote específico use `PUT
          /sku/batch/{idsku}/{idbatch}`).
      responses:
        '200':
          description: Atualizado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuBatchItem'
  /sku/batch/{idsku}/{idbatch}:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
      - name: idbatch
        in: path
        required: true
        schema:
          type: integer
    put:
      operationId: skuBatchPut
      tags:
        - Lotes
      summary: Atualiza lote
      description: >-
        Atualiza validade (`BestBeforeDate`), fabricação (`ManufacturingDate`), endereço, descrição (`Comments`) e flag
        de padrão. Validações:


        - `ManufacturingDate ≤ BestBeforeDate` e `ManufacturingDate ≤ 2099-12-31`.

        - `IDStockKeepingUnitLocation = null` é rejeitado (`Endereço não pode ser removido`).

        - Endereço novo precisa pertencer ao **mesmo armazém** do endereço atual (ou empresa relacionada).

        - Quando seta `Default = 1`, zera os demais lotes do SKU.


        Requer privilégio `PrivilegeSkuBatch` (Editar Validade Lote Sku).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuBatchUpdate'
        description: Atualização parcial do lote identificado por `{idbatch}`.
      responses:
        '200':
          description: Lote atualizado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuBatchItem'
                maxItems: 1
        '400':
          description: >-
            `[BadRequest] - Lote não existe`; `[BadRequest] - Data de fabricação não pode ser maior que data de validade
            nem 31/12/2099`; `[BadRequest] - Data de fabricação não pode ser maior que data de validade`; `[BadRequest]
            - Endereço não pode ser removido`; `[BadRequest] - Endereço SKU não existe ou pertence a outro armazém`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: skuBatchDelete
      tags:
        - Lotes
      summary: Remove lote
      description: >-
        Remove um lote de SKU. A exclusão é bloqueada quando o lote ainda tem saldo em estoque (saldo diferente de
        zero); nesse caso, transfira a quantidade para outro endereço ou consuma-a via venda/saída antes de excluir.
      responses:
        '200':
          description: Lote removido.
          content:
            application/json:
              schema:
                type: string
        '400':
          description: '`[BadRequest] - Lote não existe`; `[BadRequest] - Lote tem saldo, transferir quantidade para deletar`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/resupply:
    get:
      operationId: skuResupplyList
      tags:
        - Ressuprimento
      summary: Lista ressuprimentos
      description: >-
        Lista ressuprimentos da empresa com totais agregados (`QtyOrder`, `QtyResupply`, `QtyResupplyItems`). Aceita
        filtros por status, modalidade, tipo, CD, colaborador, datas. Respeita restrição de CDs do usuário.
      responses:
        '200':
          description: Lista de ressuprimentos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ResupplyItem'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: skuResupplyPost
      tags:
        - Ressuprimento
      summary: Cria ressuprimento
      description: >-
        Cria um ressuprimento manualmente ou a partir de um pedido (`IDOrder`).


        **Modo manual** (sem `IDOrder`): valida tipo de ressuprimento (1=Picking, 2=Pulmão, 3=Recebimento), modalidade
        (1=Individual, 2=Agrupado, 3=Indireto) e CD (usa o CD padrão da empresa se omitido).


        **Modo automático por pedido** (com `IDOrder`): o sistema analisa o pedido e gera as listas de ressuprimento
        necessárias. Pode falhar com `Empresa não tem armazém configurado para ressuprimento`, `Não há itens marcados
        para ressuprimento neste pedido`, `Itens deste pedido já estão em ressuprimento`, `Itens deste pedido já têm
        quantidade disponível no picking, ressuprimento não necessário`, `Não há saldo disponível em outros endereços
        para ressuprir este pedido`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResupplyCreate'
        description: >-
          Dados do ressuprimento a abrir. `IDTypeResupply` define o fluxo (`1` Picking — do pulmão para o picking; `2`
          Pulmão — chegada nova ao pulmão; `3` Recebimento — do recebimento para o estoque). `IDTypeResupplyMode` define
          a forma de execução (Individual, Agrupado, Indireto).
      responses:
        '200':
          description: Ressuprimento criado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResupplyItem'
        '400':
          description: Validações conforme sistema.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/resupply/{idstockkeepingunitresupplylist}:
    parameters:
      - name: idstockkeepingunitresupplylist
        in: path
        required: true
        schema:
          type: integer
    get:
      operationId: skuResupplyGet
      tags:
        - Ressuprimento
      summary: Detalha ressuprimento
      description: Detalhe completo do ressuprimento, com itens, eventos e colaborador atribuído.
      responses:
        '200':
          description: Detalhe.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ResupplyItem'
                maxItems: 1
    put:
      operationId: skuResupplyPut
      tags:
        - Ressuprimento
      summary: Atualiza ressuprimento (status, atribuição, modalidade, prioridade, finalização)
      description: >-
        Atualização parcial. Usado para: mudar status (Aberto → Iniciado → Finalizado / Cancelado), atribuir
        colaborador, alterar modalidade, alterar prioridade. As ações em massa da tela (modalidade, prioridade, atribuir
        colaborador) iteram esse endpoint.
      requestBody:
        description: Atualização parcial da lista de ressuprimento.
        content:
          application/json:
            schema:
              type: object
              properties:
                Comments:
                  type: string
                  description: Observações da lista de ressuprimento.
                RecordUserStart:
                  type: string
                  description: Login do colaborador que iniciou o ressuprimento.
                IDResupplyStatus:
                  type: integer
                  enum:
                    - 1
                    - 2
                    - 3
                    - 4
                  description: 'Status do ressuprimento: `1` Aberto, `2` Iniciado, `3` Finalizado, `4` Cancelado.'
                IDTypeResupplyMode:
                  type: integer
                  description: Modo de ressuprimento.
                IDStockKeepingUnitDistributionCenter:
                  type: integer
                  description: Centro de distribuição.
                StockKeepingUnitResupplyListPriority:
                  type: integer
                  description: Prioridade da lista na fila de ressuprimento.
      responses:
        '200':
          description: Atualizado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ResupplyItem'
                maxItems: 1
    delete:
      operationId: skuResupplyDelete
      tags:
        - Ressuprimento
      summary: Exclui ressuprimento
      description: Bloqueada quando há itens pendentes de abastecimento (`QtyResupply > 0`).
      responses:
        '200':
          description: Excluído.
          content:
            application/json:
              schema:
                type: string
        '400':
          description: Bloqueios de exclusão.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/resupply/{idstockkeepingunitresupplylist}/merge:
    parameters:
      - name: idstockkeepingunitresupplylist
        in: path
        required: true
        schema:
          type: integer
    post:
      operationId: skuResupplyMergePost
      tags:
        - Ressuprimento
      summary: Consolida ressuprimentos
      description: >-
        Move todos os itens de uma lista de ressuprimentos de origem (informada no body) para o ressuprimento de destino
        (id na URL). Apenas ressuprimentos com status Aberto podem ser consolidados.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                IDStockKeepingUnitResupplyList:
                  type: array
                  items:
                    type: integer
                  description: >-
                    Identificador da lista de ressuprimento de **origem**, que será mesclada na lista de destino (path
                    param).
        description: >-
          Mescla este ressuprimento com outros pendentes do mesmo centro de distribuição. O corpo geralmente é vazio; o
          sistema usa o identificador da URL para identificar o destino da mesclagem.
      responses:
        '200':
          description: Consolidado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ResupplyItem'
  /sku/resupply/{idstockkeepingunitresupplylist}/sku:
    parameters:
      - name: idstockkeepingunitresupplylist
        in: path
        required: true
        schema:
          type: integer
    post:
      operationId: skuResupplySkuPost
      tags:
        - Ressuprimento
      summary: Adiciona item ao ressuprimento
      description: Adiciona um SKU/lote ao ressuprimento (endereço origem, endereço destino, quantidade).
      responses:
        '200':
          description: Item adicionado.
          content:
            application/json:
              schema:
                type: array
      requestBody:
        description: Adiciona um item à lista de ressuprimento.
        content:
          application/json:
            schema:
              type: object
              properties:
                IDSku:
                  type: integer
                  description: SKU a ressuprir.
                IDBatchFrom:
                  type: integer
                  description: Lote de origem (de onde o estoque sai). Opcional.
                IDBatchTo:
                  type: integer
                  description: Lote de destino. Opcional.
                IDStockKeepingUnitLocationTo:
                  type: integer
                  description: Endereço de destino do ressuprimento.
                QtyTransferRecommendation:
                  type: number
                  format: double
                  description: Quantidade recomendada de transferência. Opcional.
  /sku/resupply/{idstockkeepingunitresupplylist}/sku/{idstockkeepingunitresupply}:
    parameters:
      - name: idstockkeepingunitresupplylist
        in: path
        required: true
        schema:
          type: integer
      - name: idstockkeepingunitresupply
        in: path
        required: true
        schema:
          type: integer
    put:
      operationId: skuResupplySkuPut
      tags:
        - Ressuprimento
      summary: Atualiza item de ressuprimento
      description: >-
        Altera quantidade, endereço destino ou conclui a movimentação do item. Privilégio
        `PrivilegeResupplyAllowUserSetLocationTo` controla quem pode mudar o endereço destino. Privilégio
        `PrivilegeResupplyAllowEditQuantity` controla quem pode mudar a quantidade.
      responses:
        '200':
          description: Item atualizado.
          content:
            application/json:
              schema:
                type: array
      requestBody:
        description: Atualiza um item da lista de ressuprimento (quantidade, endereço, não-conformidade).
        content:
          application/json:
            schema:
              type: object
              properties:
                IDSku:
                  type: integer
                  description: SKU do item de ressuprimento.
                IDBatchFrom:
                  type: integer
                  description: Lote de origem. Opcional.
                IDBatchTo:
                  type: integer
                  description: Lote de destino. Opcional.
                IDStockKeepingUnitLocationTo:
                  type: integer
                  description: Endereço de destino.
                QtyTransferRecommendation:
                  type: number
                  format: double
                  description: Quantidade recomendada de transferência.
                IDSkuMovement:
                  type: integer
                  description: Movimentação de estoque vinculada. Opcional.
                QuantityNonconformity:
                  type: number
                  format: double
                  description: Quantidade em não-conformidade. Opcional.
                IDTypeFulfillmentNonconformity:
                  type: integer
                  enum:
                    - 1
                    - 2
                    - 4
                    - 5
                    - 6
                  description: 'Tipo de não-conformidade: `1` Avariado, `2` Vencido, `4` Em Produção, `5` Falta, `6` Ressuprimento.'
    delete:
      operationId: skuResupplySkuDelete
      tags:
        - Ressuprimento
      summary: Remove item do ressuprimento
      responses:
        '200':
          description: Item removido.
          content:
            application/json:
              schema:
                type: string
      description: Remove um item específico da lista de ressuprimento. Devolve a lista de ressuprimento atualizada.
  /type/sku/resupply:
    get:
      operationId: typeSkuRessuply
      tags:
        - Tipos — SKU
      summary: Lista tipos de ressuprimento
      description: Devolve a lista de `TypeResupply` (`1` Picking, `2` Pulmão, `3` Recebimento).
      responses:
        '200':
          description: Lista.
          content:
            application/json:
              schema:
                type: array
  /type/sku/resupply/status:
    get:
      operationId: typeSkuResuplyStatusList
      tags:
        - Tipos — SKU
      summary: Lista status do ressuprimento
      description: Devolve a lista de `StatusResupply` (`1` Aberto, `2` Iniciado, `3` Finalizado, `4` Cancelado).
      responses:
        '200':
          description: Lista.
          content:
            application/json:
              schema:
                type: array
  /charge/bank-slip:
    get:
      operationId: chargeBankSlipList
      tags:
        - Boleto Bancário
      summary: Lista boletos bancários
      description: >-
        Lista os boletos da empresa autenticada com dados do cliente, valor, vencimento, status (`TypeStatusBankSlip`),
        URL e código de barras gerados pelo banco. Cada linha traz também os flags `BankSlipUpdate` e `BankSlipCancel`
        (booleans calculados pelo sistema de acordo com o estado atual e o banco) — são eles que governam quais ações
        ficam habilitadas no frontend.
      parameters:
        - name: Page
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: Número da página da listagem (1-based). Padrão `1`.
        - name: IDStatusBankSlip
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
              enum:
                - 1
                - 2
                - 3
                - 4
                - 5
                - 6
          description: >-
            Status do boleto: `1` Aguardando pagamento, `2` Pago, `3` Pendente, `4` Cancelado, `5` Baixa manual, `6`
            Protesto.
          style: form
          explode: false
        - name: DateDueFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data de vencimento ≥ data.
        - name: DateDueTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data de vencimento ≤ data.
        - name: DateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data de criação ≥ data.
        - name: DateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data de criação ≤ data.
        - name: ConsumerNameCorporateName
          in: query
          required: false
          schema:
            type: string
          description: Nome / razão social do cliente (LIKE).
        - name: ConsumerCpfCnpj
          in: query
          required: false
          schema:
            type: string
          description: CPF/CNPJ do cliente.
        - name: ConsumerEmail
          in: query
          required: false
          schema:
            type: string
          description: E-mail do cliente (LIKE).
        - name: IDOrder
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Pedido vinculado.
        - name: TID
          in: query
          required: false
          schema:
            type: string
          description: Identificador da transação no banco.
      responses:
        '200':
          description: Array de boletos.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDBankSlip:
                      type: integer
                      format: int64
                      description: Identificador único do boleto.
                    IDConsumer:
                      type: integer
                      format: int64
                      description: Identificador do cliente sacado.
                    ConsumerNameCorporateName:
                      type: string
                      description: Nome (PF) ou razão social (PJ) do sacado.
                    ConsumerCpfCnpj:
                      type: string
                      description: CPF/CNPJ do sacado, apenas dígitos.
                    ConsumerEmail:
                      type: string
                      nullable: true
                      description: E-mail do sacado. `null` quando não informado.
                    IDOrder:
                      type: integer
                      format: int64
                      nullable: true
                      description: Identificador do pedido vinculado ao boleto, quando aplicável.
                    Order:
                      type: string
                      nullable: true
                      description: Número/identificador externo do pedido vinculado, quando aplicável.
                    IDServiceOrder:
                      type: integer
                      format: int64
                      nullable: true
                      description: Identificador da NF de serviço vinculada, quando aplicável.
                    Value:
                      type: number
                      format: double
                      description: Valor original do boleto em R$.
                    ValuePaid:
                      type: number
                      format: double
                      nullable: true
                      description: Valor efetivamente pago em R$. `null` quando o boleto ainda não foi liquidado.
                    DateDue:
                      type: string
                      format: date
                      description: Data de vencimento do boleto (`YYYY-MM-DD`).
                    DatePaid:
                      type: string
                      format: date
                      nullable: true
                      description: Data de pagamento (`YYYY-MM-DD`). `null` enquanto não houver liquidação.
                    IDStatusBankSlip:
                      type: integer
                      enum:
                        - 1
                        - 2
                        - 3
                        - 4
                        - 5
                        - 6
                      description: >-
                        Status do boleto: `1` Aguardando pagamento, `2` Pago, `3` Pendente, `4` Cancelado, `5` Baixa
                        manual, `6` Protesto.
                    StatusBankSlip:
                      type: string
                      description: Descrição amigável do status do boleto.
                    BankSlipUrl:
                      type: string
                      format: uri
                      nullable: true
                      description: URL do PDF do boleto (S3 público, pode expirar). `null` quando ainda não emitido.
                    BankSlipBarCode:
                      type: string
                      nullable: true
                      description: Linha digitável / código de barras do boleto. `null` quando ainda não emitido.
                    BankSlipUpdate:
                      type: boolean
                      description: Indica se o boleto pode ser editado neste estado.
                    BankSlipCancel:
                      type: boolean
                      description: Indica se o boleto pode ser cancelado neste estado.
                    TID:
                      type: string
                      nullable: true
                      description: Identificador único da transação no gateway/adquirente, quando o boleto é gerado por integração.
                    IDCompanyIntegration:
                      type: integer
                      format: int64
                      description: Integração que emitiu o boleto (Stark Bank, Bradesco, Itaú, etc.).
                    CompanyIntegration:
                      type: string
                      description: Nome amigável da integração emissora do boleto.
                    RecordUserCreated:
                      type: string
                      description: Login do usuário que criou o boleto.
                    RecordTimestamp:
                      type: string
                      format: date-time
                      description: Data e hora de criação do boleto.
    post:
      operationId: chargeBankSlipPost
      tags:
        - Boleto Bancário
      summary: Gera um novo boleto
      description: >-
        Cria um boleto via API do banco configurado em `IDCompanyIntegration`. Pode ser avulso, vinculado a pedido
        (`IDOrder`) ou a NFSe (`IDServiceOrder`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - IDConsumer
                - Value
                - DateDue
                - IDCompanyIntegration
              properties:
                IDConsumer:
                  type: integer
                  format: int64
                  description: Cliente a ser cobrado.
                IDCompanyIntegration:
                  type: integer
                  format: int64
                  description: Integração bancária que emitirá o boleto.
                Value:
                  type: number
                  format: double
                  description: Valor do boleto.
                DateDue:
                  type: string
                  format: date
                  description: Data de vencimento.
                Comments:
                  type: string
                  description: Observações que aparecem no boleto.
                IDOrder:
                  type: integer
                  format: int64
                  description: (Opcional) Vincula a um pedido — o banco cria o boleto referenciando o pedido.
                IDServiceOrder:
                  type: integer
                  format: int64
                  description: (Opcional) Vincula a uma NFSe.
        description: >-
          Dados do boleto a emitir. `IDConsumer`, `IDCompanyIntegration`, `Value` e `DateDue` são obrigatórios;
          `IDOrder` ou `IDServiceOrder` vinculam opcionalmente o boleto a um pedido ou a uma NFSe. O sistema dispara a
          emissão do boleto na API do banco.
      responses:
        '200':
          description: 'Boleto criado. Retorna `{ response: [<boleto>] }` com `BankSlipUrl` e `BankSlipBarCode` preenchidos.'
        '400':
          description: 'Erros conhecidos: cliente sem endereço, integração indisponível, banco rejeitou os dados.'
  /charge/bank-slip/{idbankslip}:
    get:
      operationId: chargeBankSlipGet
      tags:
        - Boleto Bancário
      summary: Consulta status no banco e atualiza
      description: >-
        Consulta a API do banco para buscar o status atualizado do boleto e atualiza no idworks. Chamado pelo ícone
        **Atualizar** da linha. Bloqueado pelo frontend quando o boleto já está pago (`IDStatusBankSlip=2`).
      parameters:
        - name: idbankslip
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do boleto.
      responses:
        '200':
          description: Status atualizado. Retorna a linha do boleto com os campos refrescados.
        '400':
          description: Falha na consulta ao banco.
    put:
      operationId: chargeBankSlipPut
      tags:
        - Boleto Bancário
      summary: Atualiza o boleto
      description: >-
        Atualiza valor, vencimento ou observações do boleto. Quais campos são editáveis depende do banco — o frontend
        bloqueia o botão Editar quando `BankSlipUpdate=false`.
      parameters:
        - name: idbankslip
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do boleto.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                Value:
                  type: number
                  format: double
                  description: Novo valor do boleto em R$.
                DateDue:
                  type: string
                  format: date
                  description: Nova data de vencimento (`YYYY-MM-DD`).
                Comments:
                  type: string
                  description: Observações do boleto.
        description: >-
          Campos do boleto a atualizar (`Value`, `DateDue`, `Comments`). Quais campos são editáveis depende do banco — o
          frontend só libera o botão Editar quando o boleto traz `BankSlipUpdate=true`. Campos omitidos preservam o
          valor atual.
      responses:
        '200':
          description: Boleto atualizado.
        '400':
          description: Banco recusou alteração ou campos inválidos.
    delete:
      operationId: chargeBankSlipDelete
      tags:
        - Boleto Bancário
      summary: Cancela o boleto (com ou sem dar baixa)
      description: >-
        Cancela o boleto via API do banco. Dois modos:


        - **Sem querystring** (Somente Cancelar) — apenas cancela. A conta a receber vinculada (se houver) **fica em
        aberto**.

        - **Com `ValuePaid` e `DatePaid`** (Dar Baixa e Cancelar) — cria um lançamento de pagamento na conta bancária
        (`AccountsPayableReceivableBankStatement`) com a data e o valor informados, dá baixa na conta a receber, e em
        seguida cancela o boleto. Usado quando o cliente já pagou por outro meio (PIX, transferência) e o boleto
        continua aberto.


        Bloqueado pelo frontend quando `BankSlipCancel=false` ou quando `IDStatusBankSlip ∉ {1, 3}`.
      parameters:
        - name: idbankslip
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do boleto.
        - name: ValuePaid
          in: query
          required: false
          schema:
            type: number
            format: double
          description: Valor pago — quando informado junto com `DatePaid`, ativa o modo Dar Baixa e Cancelar.
        - name: DatePaid
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data do pagamento — obrigatória junto com `ValuePaid`.
      responses:
        '200':
          description: Boleto cancelado (e pagamento registrado quando aplicável).
        '400':
          description: Boleto já cancelado, já pago, ou banco recusou cancelamento.
  /consumer:
    get:
      operationId: consumerList
      tags:
        - Cadastro de Clientes
      summary: Lista clientes
      description: >-
        Lista os clientes da empresa autenticada, com métricas agregadas: receita total (soma dos valores das contas a
        receber vinculadas), quantidade total de pedidos do cliente, receita de NFs de serviço emitidas (`ServiceOrder`
        em status `IDStatusInvoice=3`) e vendedores vinculados (lista de `UserName` via `ConsumerSalesman`). Paginação
        fixa em **3000 por página** (`Page=N` → offset `N*3000`). Por padrão, o sistema filtra por `StatusConsumer IN
        (1,2,3)` — clientes Deletados (`StatusConsumer=0`) não aparecem.


        **Restrição de vendedor**: quando `Salesman=1` e `RestrictAccessSalesman=1`, o sistema restringe a listagem aos
        clientes vinculados ao usuário logado em `ConsumerSalesman`.
      parameters:
        - name: Page
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: Página 0-indexada. Offset = `Page * 3000`.
        - name: Search
          in: query
          required: false
          schema:
            type: string
          description: >-
            Busca rápida unificada — testa o termo contra `ConsumerNameCorporateName` (LIKE), `ConsumerCpfCnpj` (apenas
            dígitos, ≥10 caracteres), `ConsumerEmail` (LIKE) e `IDConsumer` (apenas dígitos).
        - name: ConsumerNameCorporateName
          in: query
          required: false
          schema:
            type: string
          description: Busca textual no nome / razão social (LIKE).
        - name: ConsumerCpfCnpj
          in: query
          required: false
          schema:
            type: string
          description: CPF/CNPJ. O sistema normaliza para apenas dígitos antes da consulta (aceita formato com pontuação).
        - name: ConsumerEmail
          in: query
          required: false
          schema:
            type: string
          description: E-mail (LIKE).
        - name: ConsumerTelephone
          in: query
          required: false
          schema:
            type: string
          description: Telefone. O sistema normaliza para apenas dígitos.
        - name: IDTypeStatusConsumer
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
              enum:
                - 0
                - 1
                - 2
                - 3
            default:
              - 1
              - 2
              - 3
          description: >-
            Status do cliente. Aceita CSV (ex.: `1,2,3`). Valores: `0` Deletado, `1` Ativo, `2` Inativo, `3`
            Inadimplente. Default `1,2,3` (não traz Deletados).
          style: form
          explode: false
        - name: ConsumerPriority
          in: query
          required: false
          schema:
            type: integer
          description: Prioridade interna (`ConsumerPriority`).
        - name: IDSalesman
          in: query
          required: false
          schema:
            type: string
          description: Vendedor vinculado. CSV aceito. Filtra apenas clientes com o vendedor informado em `ConsumerSalesman`.
        - name: DateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Filtra clientes com `RecordTimestamp` a partir desta data (inclusive).
        - name: DateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Filtra clientes com `RecordTimestamp` até o final desta data (inclusive).
        - name: SinceDateLastRecordModification
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Pega apenas clientes modificados após o timestamp informado. Útil para sincronizações incrementais.
      responses:
        '200':
          description: Array de clientes.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDConsumer:
                      type: integer
                      format: int64
                      description: Identificador único do cliente.
                    AccountName:
                      type: string
                      description: Conta (prefixo) à qual o cliente pertence — útil em contexto multi-conta.
                    ConsumerType:
                      type: integer
                      enum:
                        - 1
                        - 2
                        - 3
                      description: 'Tipo do cliente: `1` Pessoa Física, `2` Pessoa Jurídica, `3` Estrangeiro.'
                    ConsumerNameCorporateName:
                      type: string
                      description: Nome (PF) ou razão social (PJ) do cliente.
                    ConsumerCpfCnpj:
                      type: string
                      description: CPF (PF) ou CNPJ (PJ) do cliente, apenas dígitos.
                    ConsumerEmail:
                      type: string
                      nullable: true
                      description: E-mail principal do cliente. `null` quando não informado.
                    ConsumerTelephone:
                      type: string
                      nullable: true
                      description: Telefone principal do cliente, apenas dígitos. `null` quando não informado.
                    IDTypeStatusConsumer:
                      type: integer
                      enum:
                        - 0
                        - 1
                        - 2
                        - 3
                      description: >-
                        Status do cliente: `0` Deletado, `1` Ativo, `2` Inativo, `3` Inadimplente. Por padrão a listagem
                        traz apenas `1,2,3` (Deletados ficam de fora).
                    TypeStatusConsumer:
                      type: string
                      description: Descrição amigável do status (corresponde ao `IDTypeStatusConsumer`).
                    ConsumerPriority:
                      type: integer
                      nullable: true
                      description: >-
                        Prioridade interna do cliente (valor numérico definido pela empresa). `null` quando não
                        definida.
                    RecordTimestamp:
                      type: string
                      format: date-time
                      description: Data e hora em que o cliente foi cadastrado.
                    DateLastRecordModification:
                      type: string
                      format: date-time
                      nullable: true
                      description: >-
                        Data e hora da última modificação do cadastro. `null` quando nunca foi alterado depois do
                        cadastro inicial.
                    OrderQuantity:
                      type: integer
                      description: Quantidade total de pedidos do cliente.
                    OrderRevenueValueTotal:
                      type: number
                      format: double
                      description: Soma dos valores das contas vinculadas ao cliente.
                    ServiceOrderRevenueValueTotal:
                      type: number
                      format: double
                      description: >-
                        Receita total das NFs de serviço emitidas (`IDStatusInvoice=3`) para o cliente — soma de
                        quantidade × valor unitário de cada item da NFSe.
                    Salesman:
                      type: string
                      nullable: true
                      description: Lista (separada por vírgula) dos vendedores vinculados ao cliente.
    post:
      operationId: consumerPost
      tags:
        - Cadastro de Clientes
      summary: Cria um cliente
      description: >-
        Cria um cliente (PF ou PJ) no cadastro central. Usado pelo modal **Novo Cliente** e pela importação em massa via
        planilha (uma chamada por linha).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - ConsumerType
                - ConsumerNameCorporateName
                - ConsumerCpfCnpj
              properties:
                ConsumerType:
                  type: integer
                  enum:
                    - 1
                    - 2
                    - 3
                  description: 'Tipo do cliente: `1` Pessoa Física, `2` Pessoa Jurídica, `3` Estrangeiro.'
                ConsumerNameCorporateName:
                  type: string
                  description: Nome (PF) ou Razão Social (PJ).
                ConsumerCpfCnpj:
                  type: string
                  description: >-
                    CPF (11 dígitos) ou CNPJ (14 dígitos). Aceita apenas dígitos; é completado com zeros à esquerda até
                    11 ou 14.
                ConsumerEmail:
                  type: string
                  format: email
                  description: >-
                    E-mail do cliente. Aceita múltiplos e-mails separados por vírgula; cada um é validado
                    individualmente.
                ConsumerTelephone:
                  type: string
                  description: Telefone principal do cliente.
                ConsumerTradeName:
                  type: string
                  description: >-
                    Nome fantasia (PJ). Quando `ConsumerType=2` e o CNPJ é consultado automaticamente, é preenchido a
                    partir da base pública.
                ConsumerBirthDate:
                  type: string
                  format: date
                  description: Data de nascimento (PF) ou início de atividade (PJ), formato `YYYY-MM-DD`.
                Comments:
                  type: string
                  description: Observações livres sobre o cliente.
                IDTypeConsumerClassification:
                  type: integer
                  enum:
                    - 1
                    - 2
                    - 3
                    - 4
                    - 5
                    - 6
                    - 7
                    - 8
                  description: >-
                    Classificação do cliente: `1` Consumidor Final, `2` Empresa Simples (revenda), `3` Empresa Normal
                    (revenda), `4` Empresa Normal (uso e consumo), `5` Indústria (compra para industrialização), `6`
                    Empresa com Regime Especial, `7` Produtor Rural, `8` Empresa Simples (uso e consumo).
                ConsumerPriority:
                  type: integer
                  minimum: 0
                  maximum: 10
                  description: Prioridade interna do cliente, de 0 a 10.
                IDCarrier:
                  type: integer
                  description: Transportadora padrão do cliente (`IDSupplier` de uma transportadora cadastrada).
        description: >-
          Dados do cliente a cadastrar. `ConsumerType`, `ConsumerNameCorporateName` e `ConsumerCpfCnpj` são
          obrigatórios; os demais são opcionais. Quando `ConsumerType=2` (PJ) com CNPJ válido, o sistema completa
          automaticamente endereço, nome fantasia e demais dados a partir da base pública de CNPJ. CPF/CNPJ é validado e
          não pode duplicar dentro da empresa.
      responses:
        '200':
          description: >-
            Cliente criado. Retorna um array com o detalhe completo do cliente recém-criado (mesmo formato do `GET
            /consumer/{idconsumer}`), com o `IDConsumer` atribuído.
        '400':
          description: Erros de validação (CPF/CNPJ duplicado, formato inválido, etc.).
  /consumer/{idconsumer}:
    get:
      operationId: consumerGet
      tags:
        - Cadastro de Clientes
      summary: Detalhe do cliente
      description: >-
        Retorna o cadastro completo do cliente (dados básicos + dados fiscais + métricas agregadas). Endpoints separados
        servem cada bloco do detalhe (`/consumer/{idconsumer}/address`, `/consumer/{idconsumer}/salesman`,
        `/consumer/{idconsumer}/credit`, `/consumer/{idconsumer}/voucher`).
      parameters:
        - name: idconsumer
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do cliente.
        - name: IDCompanyInvoice
          in: query
          required: false
          schema:
            type: integer
            format: int32
          description: >-
            Restringe o saldo de vale retornado (`ConsumerVoucherValue`) a um faturador específico. Só é considerado
            quando a empresa está configurada para restringir vale por faturador; caso contrário é ignorado.
      responses:
        '200':
          description: Detalhe do cliente.
        '404':
          description: '`[NotFound] - Cliente não encontrado`.'
    put:
      operationId: consumerPut
      tags:
        - Cadastro de Clientes
      summary: Atualiza dados do cliente
      description: >-
        Atualiza dados básicos do cliente. Os blocos do detalhe (endereços, vendedores, créditos) têm endpoints
        próprios.
      parameters:
        - name: idconsumer
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do cliente.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Atualização parcial do cliente — apenas os campos enviados são alterados.
              properties:
                ConsumerType:
                  type: integer
                  enum:
                    - 1
                    - 2
                    - 3
                  description: 'Tipo do cliente: `1` Pessoa Física, `2` Pessoa Jurídica, `3` Estrangeiro.'
                ConsumerNameCorporateName:
                  type: string
                  description: Nome (PF) ou Razão Social (PJ).
                ConsumerCpfCnpj:
                  type: string
                  description: CPF (11 dígitos) ou CNPJ (14 dígitos). Aceita apenas dígitos.
                ConsumerEmail:
                  type: string
                  format: email
                  description: >-
                    E-mail do cliente. Aceita múltiplos e-mails separados por vírgula; cada um é validado
                    individualmente.
                ConsumerTelephone:
                  type: string
                  description: Telefone principal do cliente.
                ConsumerTradeName:
                  type: string
                  description: Nome fantasia (PJ).
                ConsumerBirthDate:
                  type: string
                  format: date
                  nullable: true
                  description: >-
                    Data de nascimento (PF) ou início de atividade (PJ), `YYYY-MM-DD`. Enviar string vazia limpa o
                    campo.
                Comments:
                  type: string
                  description: Observações livres sobre o cliente.
                StatusConsumer:
                  type: integer
                  enum:
                    - 0
                    - 1
                    - 2
                    - 3
                  description: 'Status do cliente: `0` Deletado, `1` Ativo, `2` Inativo, `3` Inadimplente.'
                IDTypeConsumerClassification:
                  type: integer
                  enum:
                    - 1
                    - 2
                    - 3
                    - 4
                    - 5
                    - 6
                    - 7
                    - 8
                  description: >-
                    Classificação do cliente: `1` Consumidor Final, `2` Empresa Simples (revenda), `3` Empresa Normal
                    (revenda), `4` Empresa Normal (uso e consumo), `5` Indústria (compra para industrialização), `6`
                    Empresa com Regime Especial, `7` Produtor Rural, `8` Empresa Simples (uso e consumo).
                ConsumerPriority:
                  type: integer
                  minimum: 0
                  maximum: 10
                  description: Prioridade interna do cliente, de 0 a 10.
                IDCarrier:
                  type: integer
                  description: Transportadora padrão (`IDSupplier` de uma transportadora cadastrada para a empresa).
                IDCompanySalesPolicy:
                  type: integer
                  description: >-
                    Política comercial padrão vinculada ao cliente (`IDCompanySalesPolicy` de uma política cadastrada
                    para a empresa).
        description: Atualização do cadastro do cliente (parcial). Aceita os mesmos campos do POST mais `StatusConsumer`.
      responses:
        '200':
          description: Cliente atualizado.
        '400':
          description: Erro de validação.
        '404':
          description: Cliente não encontrado.
    delete:
      operationId: consumerDelete
      tags:
        - Cadastro de Clientes
      summary: Remove cliente (soft delete)
      description: >-
        Marca o cliente como **Deletado** (`StatusConsumer=0`). **Não apaga fisicamente** — preserva histórico de
        pedidos, contas a receber e NFs emitidas. O cliente deixa de aparecer na listagem padrão (que filtra
        `StatusConsumer IN (1,2,3)`).
      parameters:
        - name: idconsumer
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do cliente.
      responses:
        '200':
          description: Cliente marcado como deletado.
        '400':
          description: Cliente tem vínculos ativos que impedem a remoção.
        '404':
          description: Cliente não encontrado.
  /cte:
    get:
      operationId: cteFeedGet
      tags:
        - CT-e
      summary: Lista o feed de CT-e
      description: >-
        Lista os CT-e emitidos contra o CNPJ da empresa, baixados automaticamente da SEFAZ. Para cada CT-e, traz: dados
        do documento (`CarrierInvoice`), descrição do tipo (`CtTpCte`), situação SEFAZ (`CtCSit`), tomador (`CtToma`),
        serviço prestado (`CttpServ`), pedido vinculado (`Orders` resolvido pela chave da NF-e citada), eventual conta a
        pagar associada (`AccountsPayableReceivable` resolvida por fornecedor + `CTeNumber`), peso do pedido vs. peso
        cobrado e diferenças, valores de frete e impostos, e URLs assinadas para XML/DANFE (servidor
        `Cte/<chave-acesso>.xml|pdf`).


        Quando o filtro `FreightConciliation=1` é informado, o sistema retorna uma listagem alternativa que cruza com
        `CarrierQuotation` + `CarrierQuotationRate` (leilão de frete) e expõe o campo calculado
        `IDStatusShippingAuctionDif` (`1` = simulado < cobrado, `2` = simulado > cobrado, `3` = empate), filtrável pelo
        parâmetro de mesmo nome. Útil para análise de divergência de frete.


        Paginação: **1000 por página** (`Page=N` → offset `N*1000`). Ordenação: registros agrupados por
        `IDCarrierInvoice` (uma linha por CT-e, sem ordenação explícita).
      parameters:
        - name: Page
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: Página 0-indexada. Offset = `Page * 1000`.
        - name: IDCompanyInvoice
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Empresa faturadora destinatária do CT-e (`IDCompanyInvoice`).
        - name: DateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: '`CTeDate` ≥ data.'
        - name: DateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: '`CTeDate` ≤ data + ` 23:59:59`.'
        - name: Order
          in: query
          required: false
          schema:
            type: string
          description: Número do pedido vinculado (`Order`).
        - name: IDOrder
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Código interno do pedido vinculado (`IDOrder`).
        - name: InvoiceNumber
          in: query
          required: false
          schema:
            type: integer
          description: >-
            Número da NF-e de produto citada no CT-e. Extraído das posições 26 a 34 da chave de acesso
            (`InvoiceAccessKey`).
        - name: InvoiceAccessKey
          in: query
          required: false
          schema:
            type: string
            minLength: 44
            maxLength: 44
          description: Chave de acesso da NF-e de produto citada (44 dígitos).
        - name: SupplierNameCorporateName
          in: query
          required: false
          schema:
            type: string
          description: Nome/razão social da transportadora emissora do CT-e (LIKE).
        - name: IDCarrier
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Transportadora cadastrada com integração ativa (`IDSupplier` com `TypeCarrier`).
        - name: CTeSit
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
              - 3
          description: 'Situação SEFAZ: `1` Uso autorizado, `3` CT-e Cancelada (`SitCte`).'
        - name: CTeType
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
              - 2
              - 3
              - 4
          description: 'Tipo: `0` Normal, `1` Complementar, `2` Anulação, `3` Substituição, `4` Fatura (`CtTpCte`).'
        - name: CTeToma
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
              - 2
              - 3
              - 4
          description: >-
            Tipo de tomador do frete: `0` Remetente, `1` Expedidor, `2` Recebedor, `3` Destinatário, `4` Outros
            (`CtToma`).
        - name: FreightConciliation
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: >-
            `1` ativa modo de conciliação de frete (compara o `R$ frete total` cobrado com o `ShipingValue` da
            `CarrierQuotationRate`). Habilita o filtro `IDStatusShippingAuctionDif`.
        - name: IDStatusShippingAuctionDif
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 3
          description: >-
            Aplicável apenas com `FreightConciliation=1`. Filtra pelo resultado da comparação: `1` simulado < cobrado,
            `2` simulado > cobrado, `3` empate.
      responses:
        '200':
          description: >-
            Array de CT-e. Quando nenhum casa com os filtros, retorna `[]`. Cada item segue o schema
            `CarrierInvoiceFeedItem`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CarrierInvoiceFeedItem'
  /cte/invoice-xml:
    get:
      operationId: cteFeedXmlGet
      tags:
        - CT-e
      summary: Serve XML/PDF individual de um CT-e
      description: >-
        Serve o XML (`Type=XML`) ou o PDF da DANFE (`Type=PDF`) de um CT-e individual. Não é chamado diretamente pelo
        frontend — as URLs já vêm prontas no corpo de `GET /cte` nos campos `XmlFile` (XML) e `XmlDanfe` (PDF),
        assinadas com o `token` do contexto do usuário.
      parameters:
        - name: Folder
          in: query
          required: true
          schema:
            type: string
            enum:
              - Cte
          description: Pasta no S3 — sempre `Cte`.
        - name: Type
          in: query
          required: true
          schema:
            type: string
            enum:
              - XML
              - PDF
          description: '`XML` devolve o arquivo XML do CT-e; `PDF` devolve o PDF da DANFE.'
        - name: token
          in: query
          required: true
          schema:
            type: string
          description: Token de autenticação do usuário (já incluído nas URLs geradas por `GET /cte`).
        - name: File
          in: query
          required: true
          schema:
            type: string
          description: Nome do arquivo no S3 — `<chave-acesso-44-digitos>.xml`.
      responses:
        '200':
          description: Conteúdo binário (XML ou PDF).
    post:
      operationId: cteFeedXmlDownload
      tags:
        - CT-e
      summary: Baixa XML de vários CT-e em lote
      description: >-
        Empacota em um único `.zip` os XMLs dos CT-e informados e gera uma URL pré-assinada do S3 para download.


        Body: **array de inteiros** com os `IDCarrierInvoice` das linhas selecionadas. O sistema localiza os CT-e
        correspondentes no bucket (`Cte/<chave>.xml`), compacta e devolve a URL.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: integer
                format: int64
                description: Código interno (`IDCarrierInvoice`) da linha do CT-e.
        description: >-
          Array de `IDCarrierInvoice` (inteiros) — as linhas selecionadas na listagem de CT-e a incluir no pacote
          `.zip`. O sistema localiza o XML de cada CT-e em `Cte/<chave-acesso>.xml` no S3, compacta e envia uma URL
          pré-assinada (válida por 2 dias) pelo e-mail do usuário; a resposta da chamada também devolve a URL.
      responses:
        '200':
          description: URL pré-assinada para download do zip.
          content:
            application/json:
              schema:
                type: string
                format: uri
  /purchase/buy-order:
    get:
      operationId: buyOrderList
      tags:
        - Pedido de Compra
      summary: Lista pedidos de compra
      description: >-
        Lista os pedidos de compra da empresa autenticada com dados do fornecedor, status, comprador, data prevista de
        entrega, totais e flags relevantes. Sem filtro de status na querystring, a tela aplica filtro default `0,3,1,6`
        (Aberto, Pedido Confirmado, Aguardando Recebimento, Recebido Parcialmente) — para incluir
        Finalizado/Cancelado/Mesclado, o consumidor precisa informar `IDStatusBuyOrder` explicitamente.
      parameters:
        - name: Page
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: Número da página da listagem (1-based). Padrão `1`.
        - name: IDStatusBuyOrder
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
              enum:
                - 0
                - 1
                - 2
                - 3
                - 5
                - 6
                - 7
          description: >-
            Status. CSV aceito. Valores: `0` Aberto, `1` Aguardando Recebimento, `2` Cancelado, `3` Pedido Confirmado,
            `5` Finalizado, `6` Recebido Parcialmente, `7` Mesclado.
          style: form
          explode: false
        - name: IDBuyOrder
          in: query
          required: false
          schema:
            type: string
          description: Código interno do pedido. CSV aceito.
        - name: DateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data de criação ≥ data.
        - name: DateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data de criação ≤ data.
        - name: DateDueFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: >-
            Data prevista de entrega ≥ data. Combinado com `IDStatusBuyOrder=1,6` e data menor que hoje, identifica
            pedidos atrasados.
        - name: DateDueTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data prevista de entrega ≤ data.
        - name: IDSupplier
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Fornecedor (`IDSupplier`).
        - name: SupplierNameCorporateName
          in: query
          required: false
          schema:
            type: string
          description: Razão social do fornecedor (LIKE).
        - name: RecordUserCreated
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Comprador (usuário) que criou o pedido.
        - name: IDSku
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pedidos que contêm o SKU informado.
        - name: IDStockKeepingUnitDistributionCenter
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Centro de distribuição destino.
      responses:
        '200':
          description: >-
            Array de pedidos de compra com dados do fornecedor, status, totais (`ValueProductsTotal`, `SkuQuantity`,
            `ItemsQuantity`) e flags.
    post:
      operationId: buyOrderPost
      tags:
        - Pedido de Compra
      summary: Cria pedido de compra
      description: >-
        Cria um pedido novo. Quando a parametrização `BuyOrderComments` está preenchida, o sistema injeta o texto no
        campo `Comments`. Quando `ShowAllSuppliersBuyOrder=0` (default), o sistema valida que o fornecedor tenha
        categoria Produto.
      requestBody:
        description: >-
          Cria o cabeçalho do pedido de compra. Os itens são adicionados depois via `POST
          /purchase/buy-order/{idbuyorder}/sku`.
        content:
          application/json:
            schema:
              type: object
              properties:
                IDSupplier:
                  type: integer
                  description: Fornecedor do pedido de compra.
                IDOrder:
                  type: integer
                  description: Pedido de venda vinculado, quando o pedido de compra nasce de uma venda. Opcional.
                Comments:
                  type: string
                  description: Observações do pedido de compra.
                IDCompanyInvoice:
                  type: integer
                  description: Faturador (empresa do grupo) do pedido de compra.
                EstimatedReceiptDate:
                  type: string
                  format: date
                  description: Data estimada de recebimento (`YYYY-MM-DD`).
                IDStockKeepingUnitDistributionCenter:
                  type: integer
                  description: Centro de distribuição de destino.
              required:
                - IDSupplier
      responses:
        '200':
          description: 'Pedido criado. Retorna `{ response: [{IDBuyOrder, SupplierNameCorporateName, ...}] }`.'
        '400':
          description: 'Erros: fornecedor de categoria inválida, item sem SKU, etc.'
  /purchase/buy-order/{idbuyorder}:
    get:
      operationId: buyOrderGet
      tags:
        - Pedido de Compra
      summary: Detalhe do pedido de compra
      parameters:
        - name: idbuyorder
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do pedido de compra.
      responses:
        '200':
          description: Detalhe completo do pedido.
        '404':
          description: Pedido não encontrado.
      description: >-
        Retorna o detalhe completo de um pedido de compra: fornecedor, itens (SKU, quantidade, preço unitário), centro
        de distribuição de destino e situação. Use para conferência e acompanhamento do pedido antes do recebimento.
    put:
      operationId: buyOrderPut
      tags:
        - Pedido de Compra
      summary: Atualiza pedido de compra
      description: >-
        Atualiza dados básicos, itens, valores ou status. Quais alterações são permitidas depende do `IDStatusBuyOrder`
        atual — pedidos `Aberto` aceitam tudo; `Pedido Confirmado` em diante restringe alterações de itens/valores.
        Mudança para status `Finalizado` exige `PrivilegeBuyOrderFinish` e é irreversível.
      parameters:
        - name: idbuyorder
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do pedido de compra.
      requestBody:
        description: Atualização parcial do cabeçalho do pedido de compra.
        content:
          application/json:
            schema:
              type: object
              properties:
                IDSupplier:
                  type: integer
                  description: Fornecedor do pedido de compra.
                IDOrder:
                  type: integer
                  description: Pedido de venda vinculado. Opcional.
                Comments:
                  type: string
                  description: Observações.
                IDStatusBuyOrder:
                  type: integer
                  enum:
                    - 0
                    - 1
                    - 2
                    - 3
                    - 5
                    - 6
                    - 7
                  description: >-
                    Status do pedido de compra: `0` Aberto, `1` Aguardando Recebimento, `2` Cancelado, `3` Pedido
                    Confirmado, `5` Finalizado, `6` Recebido Parcialmente, `7` Mesclado.
                IDCompanyInvoice:
                  type: integer
                  description: Faturador do pedido de compra.
                EstimatedReceiptDate:
                  type: string
                  format: date
                  description: Data estimada de recebimento (`YYYY-MM-DD`).
                IDStockKeepingUnitDistributionCenter:
                  type: integer
                  description: Centro de distribuição de destino.
                IDStockKeepingUnitWarehouse:
                  type: integer
                  description: Armazém de destino.
      responses:
        '200':
          description: Pedido atualizado.
        '400':
          description: Transição de status inválida ou alteração não permitida no status atual.
    delete:
      operationId: buyOrderDelete
      tags:
        - Pedido de Compra
      summary: Remove pedido de compra
      description: >-
        Remove o pedido. Bloqueado quando o status é `Finalizado` (5), `Cancelado` (2), `Recebido Parcialmente` (6) ou
        `Mesclado` (7) — nesses casos, retorna `[BadRequest]` com mensagem específica.
      parameters:
        - name: idbuyorder
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do pedido de compra.
      responses:
        '200':
          description: Pedido removido.
        '400':
          description: Pedido em status que bloqueia remoção.
  /purchase/feed:
    get:
      operationId: purchaseFeed
      tags:
        - Feed de NF-e
      summary: Lista o feed de NF-e recebidas
      description: >-
        Lista as NF-e emitidas contra o CNPJ da empresa, baixadas automaticamente da SEFAZ. Cada linha vem com dados da
        nota (número, série, chave de acesso, fornecedor, valor, datas), descrição do tipo (Entrada/Saída via `NfTpNf`),
        descrição do último evento (`NfTpEvent`), situação SEFAZ (`NfCSit`), tags internas, eventual recebimento criado
        (`IDPurchase`), eventual conta a pagar associada (`IDAccountPayableReceivable`, resolvida por fornecedor +
        número de documento) e URLs assinadas para o **XML** e a **DANFE** (servidor
        `/invoice/danfe?Folder=Inbound&Type=XML|PDF&Origin=Feed&token=...&File=<chave-acesso>`).


        Paginação: **500 por página** (`Page=N` → offset `N*500`). Ordenação: `ORDER BY IDNfEvents DESC`.
      parameters:
        - name: Page
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: Página 0-indexada. Offset = `Page * 500`.
        - name: IDCompanyInvoice
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Empresa faturadora (`IDCompanyInvoice` → `IDCompany`). Usado em ambientes multi-empresa.
        - name: SupplierNameCorporateName
          in: query
          required: false
          schema:
            type: string
          description: Nome/razão social do fornecedor (LIKE em `SupplierNameCorporateName`).
        - name: NfeNumber
          in: query
          required: false
          schema:
            type: string
          description: Número da NF-e (`NFeNumber`). Aceita com pontuação — apenas os dígitos são considerados.
        - name: SupplierCpfCnpj
          in: query
          required: false
          schema:
            type: string
          description: CPF/CNPJ do fornecedor (LIKE). Pontuação é removida pelo sistema antes da consulta.
        - name: DateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: '`NFeDate` ≥ data (data de emissão).'
        - name: DateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: '`NFeDate` ≤ data + ` 23:59:59`.'
        - name: IDNfEvents
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Código interno da linha do feed. Útil para buscar uma linha específica.
        - name: Tags
          in: query
          required: false
          schema:
            type: string
          description: Filtra apenas linhas que têm a tag informada em `Tag`.
      responses:
        '200':
          description: Lista de NF-e do feed. Quando nenhum registro casa com os filtros, retorna `[]`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PurchaseFeedItem'
  /purchase/feed/{idnfevents}:
    put:
      operationId: purchaseFeedPut
      tags:
        - Feed de NF-e
      summary: Atualiza tags da NF do feed
      description: >-
        Sincroniza as tags internas da linha (`NfEventsTag`) com o array `Tags` enviado no body. Fluxo:


        1. Localiza a nota por `IDNfEvents` + `AccountName = prefix`. Falha com `[BadRequest] - Nota fiscal não existe`
        se não encontrar.

        2. Compara as tags atuais com o array enviado.

        3. Tags presentes no array enviado que ainda não existem são adicionadas.

        4. Tags atuais que não estão no array enviado são removidas.

        5. Quando o array vier vazio, todas as tags da linha são removidas.

        6. Devolve a linha atualizada.


        O array `Tags` é livre — qualquer string de até 255 caracteres pode ser usada como tag. A tela usa o componente
        Select com modo `tags` para criar/reutilizar.
      parameters:
        - name: idnfevents
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Código interno da linha do feed.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - Tags
              properties:
                Tags:
                  type: array
                  items:
                    type: string
                  description: Estado desejado das tags. Para limpar, envie `[]`.
        description: >-
          Estado desejado das tags da nota fiscal. O array é a verdade — tags atuais que não estão no array são
          removidas, e tags do array que ainda não existem são criadas. Enviar `[]` apaga todas as tags da nota.
      responses:
        '200':
          description: Linha do feed atualizada (array com 1 item, mesmo schema de `GET /purchase/feed`).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PurchaseFeedItem'
        '400':
          description: 'Mensagens emitidas: `[BadRequest] - Nota fiscal não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /purchase/feed/{idnfevents}/manifest:
    post:
      operationId: purchaseFeedManifestPut
      tags:
        - Feed de NF-e
      summary: Manifesta a NF perante a SEFAZ
      description: >-
        Envia um evento de manifestação do destinatário à SEFAZ para a nota informada. O evento fica registrado no
        histórico oficial da nota e não pode ser desfeito. Eventos aceitos: `210200` Confirmação da Operação, `210210`
        Ciência da Emissão, `210220` Desconhecimento da Operação e `210240` Operação não Realizada — este último exige
        `Comments` com pelo menos 15 caracteres. O frontend usa o mesmo endpoint na ação em lote, iterando uma chamada
        por nota selecionada.
      parameters:
        - name: idnfevents
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Código interno da linha do feed.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - Event
              properties:
                Event:
                  type: integer
                  enum:
                    - 210200
                    - 210210
                    - 210220
                    - 210240
                  description: >-
                    Código do evento de manifestação do destinatário enviado à SEFAZ: `210200` Confirmação da Operação,
                    `210210` Ciência da Emissão, `210220` Desconhecimento da Operação, `210240` Operação não Realizada.
                    Outro valor é rejeitado com `Evento não permitido`.
                Comments:
                  type: string
                  minLength: 15
                  description: >-
                    Motivo da manifestação. Obrigatório apenas quando `Event=210240` (Operação não Realizada), com no
                    mínimo 15 caracteres — abaixo disso a operação é recusada. Para os demais eventos é opcional e
                    ignorado.
      responses:
        '200':
          description: >-
            Manifestação aceita pela SEFAZ. O evento fica registrado no histórico da nota e passa a aparecer na coluna
            `Evento` do feed.
        '400':
          description: >-
            Validação ou erro retornado pela SEFAZ. Mensagens possíveis: `Evento não permitido` (quando `Event` está
            fora dos valores aceitos), `Motivo do evento precisa ser maior que 15 caracteres` (`Event=210240` com
            `Comments` abaixo de 15 caracteres), `Nota não encontrada`, `Empresa não localizada`, `Certificado digital
            não encontrado`, além do motivo (`xMotivo`) devolvido pela própria SEFAZ quando a manifestação é rejeitada.
  /purchase/feed/invoice-xml:
    post:
      operationId: purchaseFeedXmlGet
      tags:
        - Feed de NF-e
      summary: Baixa XML de várias NFs em lote
      description: >-
        Empacota em um único `.zip` os XMLs das notas informadas e gera uma **URL pré-assinada do S3** (TTL 2 dias) para
        download. Em paralelo, envia o link **por e-mail** ao usuário logado (template `Inbound`).


        Fonte dos arquivos: bucket `idworks`, prefixo `Inbound/<chave-acesso>.xml`. Os XMLs são copiados/arquivados via
        `s3-zip` (sem preservar hierarquia de pastas) e o zip resultante é gravado em `Temp/<uuid>.zip`.


        O body é um **array de strings** no formato `<chave-acesso>.xml` (cada string corresponde a uma nota). O
        frontend filtra antes de enviar — exclui linhas sem `NFeNumber` e linhas com situação diferente de `Uso
        autorizado`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
                description: Nome do arquivo XML no S3 — `<chave-de-acesso-44-digitos>.xml`.
                minLength: 48
                maxLength: 48
        description: >-
          Array com os nomes dos arquivos XML a empacotar, no formato `<chave-de-acesso-44-digitos>.xml`. O frontend
          exclui antes de enviar as linhas sem `NFeNumber` e as com situação SEFAZ diferente de `Uso autorizado`.
      responses:
        '200':
          description: >-
            URL pré-assinada para download do zip. Resposta é a URL pura (string). Em paralelo, um e-mail com o mesmo
            link é enviado ao usuário logado.
          content:
            application/json:
              schema:
                type: string
                format: uri
                example: https://idworks.s3.amazonaws.com/Temp/abc.zip?X-Amz-Algorithm=...
        '500':
          description: Falha ao compactar ou subir o zip. Mensagens começam com `zipFile.upload error` ou `catched error:`.
  /purchase/feed/invoice-danfe:
    post:
      operationId: purchaseFeedDanfeBulkPost
      tags:
        - Feed de NF-e
      summary: Baixa DANFE de várias NFs em lote
      description: >-
        Empacota em um único `.zip` os PDFs de DANFE das notas informadas e gera uma URL para download (mesmo fluxo do
        `invoice-xml`, mas para PDFs).


        O body é um **array de inteiros** com os `IDNfEvents` das notas a baixar.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: integer
                format: int64
                description: Código interno (`IDNfEvents`) da linha do feed.
        description: >-
          Array de `IDNfEvents` (códigos internos das linhas do feed) cujas DANFEs PDF serão empacotadas em um único
          `.zip`.
      responses:
        '200':
          description: URL pré-assinada para download do zip de PDFs.
          content:
            application/json:
              schema:
                type: string
                format: uri
  /purchase/feed/tag:
    get:
      operationId: purchaseFeedTagList
      tags:
        - Feed de NF-e
      summary: Lista tags do feed
      description: >-
        Lista todas as tags já cadastradas em notas do feed da empresa autenticada (`Tag` agrupado). Usado pelo seletor
        de Tags do modal **Adicionar Tag** e pelo filtro **Tags** do painel de filtros.
      responses:
        '200':
          description: Array com as tags distintas.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    Tag:
                      type: string
                      description: Texto da tag.
  /purchase/xml:
    post:
      operationId: purchaseInvoiceXmlPost
      tags:
        - Recebimento
      summary: Cria recebimento a partir de NF do Feed, pedido próprio ou XML cru
      description: >-
        Wrapper para criar e popular o recebimento em um único chamado. Resolve o XML de 3 fontes:

        1. `?IDNfEvents=` — usa o XML do Feed NF (NFEvents).

        2. `?IDOrder=` — usa o XML de um pedido próprio (devolução de cliente).

        3. Body — XML cru no body da requisição.


        Fluxo:

        - Resolve fornecedor por CNPJ (cria novo `Suppliers` quando não existe, vinculando à categoria padrão de
        produto).

        - Cria `StockKeepingUnitPurchase` em status 0.

        - Processa o XML completo (impostos, SKUs, lotes, duplicatas).

        - Se a importação falha, deleta o recebimento criado.


        **`?OnlyPayment=1`** pula a criação do recebimento e cria apenas as contas a pagar do XML.
      parameters:
        - name: IDNfEvents
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: ID da NF do Feed NF (`NfEvents`).
        - name: IDOrder
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Pedido de venda própria (para criar recebimento de devolução).
        - name: OnlyPayment
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` cria apenas contas a pagar do XML.'
        - name: IDStockKeepingUnitWarehouse
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pelo identificador do depósito do SKU.
        - name: IDStockKeepingUnitDistributionCenter
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pelo identificador do centro de distribuição do SKU.
        - name: ImportType
          in: query
          required: false
          schema:
            type: string
          description: >-
            Critério de matching de SKU (CSV). `1`=código fornecedor, `2`=código de barras, `3`=código de referência,
            `5`=código integração/hub.
      requestBody:
        required: false
        content:
          application/xml:
            schema:
              type: string
              format: binary
              description: XML da NF-e cru (alternativa a `IDNfEvents`/`IDOrder`).
        description: >-
          Corpo do `POST /purchase/xml`: conteúdo bruto do XML da NF-e a importar (texto, geralmente enviado como
          `text/xml` e podendo vir em base64 que o sistema decodifica). Só é exigido quando a importação não é feita por
          `IDOrder` ou `IDNfEvents` na query string.
      responses:
        '200':
          description: Recebimento criado.
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `Precisa ser enviado o IDOrder ou IDNfEvents ou XML`
            - `Nota fiscal não encontrada`
            - `Nota fiscal de saída não permite criar recebimento. Gerar pedido de devolução para criar recebimento`
            - `Armazém não encontrado`
            - `Já existe contas a pagar cadastrada` (OnlyPayment)
            Mais erros propagados do processamento do XML (XML inválido, SKU não encontrado, etc.).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /purchase/schedule:
    get:
      operationId: purchaseScheduleList
      tags:
        - Agendamento de Recebimento
      summary: Lista agendamentos de recebimento
      description: >-
        Lista os agendamentos da empresa, ordenados por `StartTime` ascendente. Cada item traz cabeçalho (`StartTime`,
        `EndTime`, `ScheduleTitle`, `Comments`, `IDPurchase`) **e** dados resolvidos do recebimento amarrado (quando
        houver):


        - Fornecedor: `SupplierCpfCnpj`, `SupplierNameCorporateName`.

        - Nota fiscal: `serie`, `nNF`, `dhEmi` (emissão), `qVol` (volumes), `pesoB` (peso bruto, exposto como `Weight`).

        - Recebimento: `CheckinTimestamp`, `StatusPurchase`, `IDStatusPurchase`.

        - Agregados calculados: `ItemsQuantity` (soma de quantidades em `StockKeepingUnitMovement`) e `SkuQuantity`
        (SKUs distintos no recebimento).

        - `StockKeepingUnitPurchaseScheduleStatus` (`1`-`4`) + `StockKeepingUnitPurchaseScheduleStatusDescription`
        (`Recebido`, `Agendado`, `Atrasado`, `Não agendado`) — derivado de `CheckinTimestamp` e `EndTime` em relação ao
        momento atual: `Recebido` quando há check-in, `Agendado` quando o `EndTime` ainda não passou, `Atrasado` quando
        passou sem check-in, `Não agendado` quando não há recebimento amarrado.
      parameters:
        - name: IDStockKeepingUnitPurchaseSchedule
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo identificador do agendamento de compra do SKU.
        - name: IDPurchase
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo identificador da compra.
        - name: StartTime
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Filtra agendamentos com `StartTime` a partir desta data (inclusive).
        - name: EndTime
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Filtra agendamentos com `EndTime` até o final desta data (inclusive).
      responses:
        '200':
          description: Lista de agendamentos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PurchaseScheduleItem'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: purchaseSchedulePost
      tags:
        - Agendamento de Recebimento
      summary: Cria agendamento
      description: >-
        Cria um agendamento. Validações:


        - `StartTime ≤ EndTime` — caso contrário `Data de início precisa ser menor que data de término`.

        - Quando `IDPurchase` é informado: o recebimento precisa existir na empresa **e** ainda não ter agendamento
        ativo. Se já tem, devolve `Recebimento já esta agendado para <data>`.

        - `IDPurchase` ausente cria **agendamento avulso** (bloqueio na agenda sem amarrar recebimento).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseScheduleCreate'
        description: >-
          Dados do agendamento de recebimento a cadastrar. Obrigatórios `StartTime` e `EndTime` (com `StartTime` <=
          `EndTime`). Opcionais: `Comments`, `ScheduleTitle` e `IDPurchase` (recebimento associado — quando informado,
          precisa existir e não pode já estar agendado).
      responses:
        '200':
          description: Agendamento criado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PurchaseScheduleItem'
                maxItems: 1
        '400':
          description: >-
            `[BadRequest] - Data de início precisa ser menor que data de término`; `[BadRequest] - Recebimento já esta
            agendado para <data>`; `[BadRequest] - Recebimento não existe`; `[BadRequest] - Empresa não existe`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /purchase/schedule/{idstockkeepingunitpurchaseschedule}:
    parameters:
      - name: idstockkeepingunitpurchaseschedule
        in: path
        required: true
        schema:
          type: integer
    put:
      operationId: purchaseSchedulePut
      tags:
        - Agendamento de Recebimento
      summary: Atualiza agendamento
      description: >-
        Atualização parcial. Mesmas validações do POST (data início ≤ fim; recebimento único). Trocar `IDPurchase` exige
        que o novo recebimento não esteja agendado ainda.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseScheduleCreate'
        description: >-
          Campos do agendamento de recebimento a atualizar — apenas os enviados são aplicados. Aceita `StartTime`,
          `EndTime`, `Comments`, `ScheduleTitle` e `IDPurchase`; quando ambas as datas são enviadas, `StartTime` precisa
          ser menor ou igual a `EndTime` e o recebimento informado não pode já estar agendado em outro registro.
      responses:
        '200':
          description: Agendamento atualizado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PurchaseScheduleItem'
                maxItems: 1
        '400':
          description: '`[BadRequest] - Agendamento não existe`; demais idem POST.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: purchaseScheduleDelete
      tags:
        - Agendamento de Recebimento
      summary: Exclui agendamento
      description: >-
        Exclusão física. Sem regra de bloqueio — agendamento amarrado a recebimento já recebido pode ser apagado (mas
        geralmente se mantém para histórico).
      responses:
        '200':
          description: Agendamento excluído.
          content:
            application/json:
              schema:
                type: string
        '400':
          description: '`[BadRequest] - Agendamento não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /purchase/schedule/config:
    get:
      operationId: purchaseScheduleConfigList
      tags:
        - Agendamento de Recebimento
      summary: Lista configurações de agendamento de recebimento
      description: >-
        Lista as configurações de agendamento da empresa. Cada item traz o cabeçalho da configuração (duração, limites,
        antecedência, tolerância) **e** o array `StockKeepingUnitPurchaseScheduleConfigTimetable` com todas as faixas de
        horário por dia da semana já resolvidas (ordenadas por `WeekDay ASC, StartTime ASC`).
      parameters:
        - name: IDStockKeepingUnitPurchaseScheduleConfig
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por id específico.
      responses:
        '200':
          description: Lista de configurações.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PurchaseScheduleConfigItem'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: purchaseScheduleConfigPost
      tags:
        - Agendamento de Recebimento
      summary: Cria configuração de agendamento
      description: >-
        Cria a configuração para um CD. Validações:

        - `IDStockKeepingUnitDistributionCenter` obrigatório e precisa pertencer à empresa.

        - **Um CD pode ter apenas 1 configuração** — segunda tentativa devolve `[BadRequest] - Já existe uma agenda para
        esse centro de distribuição`.

        - `StockKeepingUnitPurchaseScheduleConfigTimetable` (quando enviado) é um array de faixas de horário, cada uma
        com `WeekDay` (0-6), `StartTime` e `EndTime`. Quando omitido, a configuração é criada sem horários e o
        agendamento fica indisponível até o operador editar.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseScheduleConfigCreate'
        description: >-
          Configurações da agenda de recebimento de um centro de distribuição. Obrigatório
          `IDStockKeepingUnitDistributionCenter` (precisa existir e não pode já ter agenda cadastrada). Campos:
          `ScheduleDurationMinutes`, `ScheduleMaximumTimeAheadDay`, `ScheduleMinimumAdvanceTimeHour`,
          `MaxSchedulePerDay`, `MaxItemsPerDay`, `HourDifferenceAllowed` e
          `StockKeepingUnitPurchaseScheduleConfigTimetable` (array com a janela semanal — cada item tem `WeekDay`,
          `StartTime` e `EndTime`).
      responses:
        '200':
          description: Configuração criada (formato da listagem).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PurchaseScheduleConfigItem'
                maxItems: 1
        '400':
          description: >-
            `[BadRequest] - Centro de distribuição precisa ser informado`; `[BadRequest] - Centro de distribuição não
            existe`; `[BadRequest] - Já existe uma agenda para esse centro de distribuição`; `[BadRequest] - Empresa não
            existe`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /purchase/schedule/config/{idstockkeepingunitpurchasescheduleconfig}:
    parameters:
      - name: idstockkeepingunitpurchasescheduleconfig
        in: path
        required: true
        schema:
          type: integer
    put:
      operationId: purchaseScheduleConfigPut
      tags:
        - Agendamento de Recebimento
      summary: Atualiza configuração de agendamento
      description: >-
        Atualização parcial. Comportamento do `StockKeepingUnitPurchaseScheduleConfigTimetable`:

        - **Não enviado**: timetable atual fica intacta.

        - **Array vazio** (`[]`): **apaga** todas as faixas atuais — agendamento fica indisponível.

        - **Array preenchido**: **substitui** as faixas atuais (DELETE + INSERT em bloco).


        Validações: troca de `IDStockKeepingUnitDistributionCenter` exige que o novo CD não tenha outra configuração
        existente.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseScheduleConfigUpdate'
        description: >-
          Campos da configuração da agenda a atualizar — apenas os enviados são aplicados. Aceita
          `ScheduleDurationMinutes`, `ScheduleMaximumTimeAheadDay`, `ScheduleMinimumAdvanceTimeHour`,
          `MaxSchedulePerDay`, `MaxItemsPerDay`, `IDStockKeepingUnitDistributionCenter`, `HourDifferenceAllowed` e
          `StockKeepingUnitPurchaseScheduleConfigTimetable` (substitui a janela semanal — array vazio remove todos os
          horários; cada item tem `WeekDay`, `StartTime` e `EndTime`).
      responses:
        '200':
          description: Configuração atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PurchaseScheduleConfigItem'
                maxItems: 1
        '400':
          description: >-
            `[BadRequest] - Configuração agendamento não existe`; `[BadRequest] - Centro de distribuição não existe`;
            `[BadRequest] - Já existe uma agenda para esse centro de distribuição`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: purchaseScheduleConfigDelete
      tags:
        - Agendamento de Recebimento
      summary: Exclui configuração de agendamento
      description: >-
        **Exclusão física**. As faixas de horário vinculadas são removidas automaticamente em cascata. Devolve a string
        literal `sucesso`.
      responses:
        '200':
          description: Configuração excluída.
          content:
            application/json:
              schema:
                type: string
        '400':
          description: '`[BadRequest] - Configuração agendamento não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /fulfillment/picking/configuration:
    get:
      operationId: orderFulfillmentPickingConfigurationList
      tags:
        - Picking
      summary: Lista configurações de geração de picking list
      description: >-
        Lista as configurações da empresa. Retorna o nome resolvido do CD (`DistributionCenterName`) e do tipo de
        picking (`TypePickingList`). As listas CSV (`IDCompanyIntegrationList`, `IDOrderTypeList`, `IDCarrierList`,
        `WeekIntervalAutoGenerate`) são devolvidas como **arrays** depois do `split(',')`.
      parameters:
        - name: IDPickingListConfiguration
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo identificador da configuração de lista de separação.
      responses:
        '200':
          description: Lista das configurações.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PickingListConfigurationItem'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: orderFulfillmentPickingConfigurationPost
      tags:
        - Picking
      summary: Cria uma configuração de picking list
      description: |-
        Cria uma configuração. Validações:

        - `PickingListConfigurationName` obrigatório e **único** dentro da empresa.
        - `StartAutoGenerateTime` e `FinishAutoGenerateTime` obrigatórios e `Start ≤ Finish`.
        - `ItemsQtyLimit`, `OrderQtyLimit`, `SkuQtyLimit` precisam ser numéricos (quando informados).
        - `OrderPriority` entre 0 e 10 (quando informado).
        - `WeekIntervalAutoGenerate` é um array de inteiros 0-6 (0=Domingo, 6=Sábado).
        - Cada `IDCompanyIntegration` precisa pertencer à empresa e ter `Show = 1`.
        - Cada `IDTypeOrder` precisa pertencer à empresa e ter `Status = 1`.
        - Cada `IDCarrier` precisa ser um fornecedor da empresa com `IDTypeSupplier = 2` (Transportadora).
        - `IDStockKeepingUnitDistributionCenter` precisa pertencer à empresa.
        - `IDTypePickingList` precisa existir (1=Picking, 2=Picking & Packing, 3=Monopedido, 4=Colméia).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PickingListConfigurationCreate'
        description: >-
          Cria uma configuração de geração automática de picking-list. Define o CD, o tipo de coleta gerado, a janela
          diária (início/fim/dias da semana), os filtros de pedido (integração, tipo, transportadora) e os limites
          (itens, pedidos, SKUs, cestos). Veja `PickingListConfigurationCreate`.
      responses:
        '200':
          description: Configuração criada (formato da listagem).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PickingListConfigurationItem'
                maxItems: 1
        '400':
          description: >-
            `[BadRequest] - Preencha corretamente o nome da configuração`; `[BadRequest] - Nome de configuração já
            existente`; `[BadRequest] - Preencha corretamente quantidade de itens, pedidos e skus`; `[BadRequest] -
            Preencha corretamente horário de início e fim de geração de picking-list`; `[BadRequest] - Horário de início
            precisa ser menor que horário final`; `[BadRequest] - Prioridade pedido precisa ser entre 0 e 10`;
            `[BadRequest] - Preencha corretamente os dias de geração de picking-list`; `[BadRequest] - Integração(s) não
            localizada(s): <ids>`; `[BadRequest] - Tipo pedido(s) não localizada(s): <ids>`; `[BadRequest] -
            Transportadora(s) não localizada(s): <ids>`; `[BadRequest] - Centro de distribuição não existe`;
            `[BadRequest] - Tipo de picking list não existe`; `[BadRequest] - Empresa não existe`; `[BadRequest] - Erro
            ao cadastrar configuração`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /fulfillment/picking/configuration/{idpickinglistconfiguration}:
    parameters:
      - name: idpickinglistconfiguration
        in: path
        required: true
        schema:
          type: integer
    put:
      operationId: orderFulfillmentPickingConfigurationPut
      tags:
        - Picking
      summary: Atualiza uma configuração de picking list
      description: >-
        Atualização parcial. Aplica as mesmas validações do POST (exceto que `PickingListConfigurationName` não é
        validado por unicidade — pode manter o nome original). Aceita listas vazias para limpar campos CSV
        (`IDCompanyIntegrationList`, `IDOrderTypeList`, `IDCarrierList`, `WeekIntervalAutoGenerate`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PickingListConfigurationUpdate'
        description: >-
          Atualização parcial da configuração. Aceita qualquer subconjunto dos campos de
          `PickingListConfigurationCreate`; campos omitidos preservam o valor atual.
      responses:
        '200':
          description: Configuração atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PickingListConfigurationItem'
                maxItems: 1
        '400':
          description: Validações idem POST + `[BadRequest] - Configuração picking list não encontrada`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: orderFulfillmentPickingConfigurationDelete
      tags:
        - Picking
      summary: Exclui uma configuração de picking list
      description: >-
        **Exclusão física**. Sem regras de bloqueio — picking lists geradas continuam no histórico mesmo após excluir a
        configuração que as gerou. Devolve a string literal `Configuração de picking-list excluída com sucesso`.
      responses:
        '200':
          description: Configuração excluída.
          content:
            application/json:
              schema:
                type: string
        '400':
          description: >-
            `[BadRequest] - Informe corretamente a configuração de picking-list`; `[BadRequest] - Empresa não existe`
            (também usado quando a configuração não pertence à empresa).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/distribution-center:
    get:
      operationId: skuDistributionCenterList
      tags:
        - Centros de Distribuição
      summary: Lista centros de distribuição
      description: >-
        Lista os CDs da empresa, ordenados por `DistributionCenterName`. Respeita restrição de CDs permitidos ao
        usuário.
      parameters:
        - name: IDStockKeepingUnitDistributionCenter
          in: query
          required: false
          schema:
            type: string
          description: Filtra por id; aceita lista CSV.
      responses:
        '200':
          description: Lista de CDs.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DistributionCenterItem'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: skuDistributionCenterPost
      tags:
        - Centros de Distribuição
      summary: Cria centro de distribuição
      description: >-
        Cria um CD. Nome único por empresa. Quando `Default = 1` (default ausente), o sistema zera o `Default` dos
        demais CDs da empresa antes de inserir. Devolve a lista completa atualizada.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DistributionCenterCreate'
        description: Dados do centro de distribuição a cadastrar.
      responses:
        '200':
          description: CD criado (devolve lista completa).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DistributionCenterItem'
        '400':
          description: '`[BadRequest] - Já existe um centro de distribuição com este nome`; `[BadRequest] - Company não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/distribution-center/{idstockkeepingunitdistributioncenter}:
    parameters:
      - name: idstockkeepingunitdistributioncenter
        in: path
        required: true
        schema:
          type: integer
    put:
      operationId: skuDistributionCenterPut
      tags:
        - Centros de Distribuição
      summary: Atualiza centro de distribuição
      description: >-
        Atualização parcial. Valida unicidade do nome dentro da empresa. Marcar `Default = 1` zera o `Default` dos
        demais CDs.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DistributionCenterCreate'
        description: Atualiza o centro de distribuição. Mesmo schema do POST.
      responses:
        '200':
          description: CD atualizado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DistributionCenterItem'
        '400':
          description: >-
            `[BadRequest] - Centro de distribuição não existe`; `[BadRequest] - Já existe um centro de distribuição com
            este nome`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: skuDistributionCenterDelete
      tags:
        - Centros de Distribuição
      summary: Exclui centro de distribuição
      description: |-
        **Exclusão física** com várias regras de bloqueio em cascata:

        1. Armazéns vinculados → bloqueia.
        2. CD padrão → exige definir outro antes.
        3. Histórico de recebimento (`StockKeepingUnitPurchase`) → bloqueia.
        4. Histórico de pedidos (`Orders`) → bloqueia.
        5. Histórico de pedido de compra (`StockKeepingUnitBuyOrder`) → bloqueia.
        6. Usuários com vínculo (`UserCompanyDistributionCenter`) → bloqueia.
        7. Ressuprimento (`StockKeepingUnitResupplyList`) → bloqueia.
        8. Inventário (`StockKeepingUnitInventorySummary`) → bloqueia.
      responses:
        '200':
          description: CD excluído.
          content:
            application/json:
              schema:
                type: string
        '400':
          description: >-
            `[BadRequest] - Existem armazéns vinculados a este centro de distribuição`; `[BadRequest] - Precisa definir
            outro centro de distribuição padrão antes de deletar`; `[BadRequest] - Centro de distribuição já teve
            recebimento e não pode ser excluído`; `[BadRequest] - Centro de distribuição já teve pedido e não pode ser
            excluído`; `[BadRequest] - Centro de distribuição já teve pedido de compra e não pode ser excluído`;
            `[BadRequest] - Centro de distribuição está vinculado a usuário e não pode ser excluído`; `[BadRequest] -
            Centro de distribuição está vinculado a ressuprimento e não pode ser excluído`; `[BadRequest] - Centro de
            distribuição está vinculado a inventário e não pode ser excluído`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/warehouse:
    get:
      operationId: skuWareHouseList
      tags:
        - Armazéns
      summary: Lista armazéns
      description: >-
        Lista armazéns Ativos (`Status = 1`) da empresa, ordenados por `WarehouseName`. Inclui o nome resolvido do tipo
        (`TypeStockKeepingUnitWarehouse`), CD pai e empresa faturadora (`IDCompanyInvoice`). Respeita restrição de CDs
        do usuário.
      parameters:
        - name: IDStockKeepingUnitDistributionCenter
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo identificador do centro de distribuição do SKU.
      responses:
        '200':
          description: Lista de armazéns.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WarehouseItem'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: skuWareHousePost
      tags:
        - Armazéns
      summary: Cria armazém
      description: >-
        Cria um armazém dentro de um CD. Validações:

        - `IDStockKeepingUnitDistributionCenter` precisa pertencer à empresa.

        - `IDCompanyInvoice` (quando informado) precisa ser uma empresa associada à conta autenticada via `CompanyMain`.

        - Quando `Default = 1`, zera o `Default` dos demais armazéns da empresa.

        - Quando `DefaultPurchase = 1`, zera o `DefaultPurchase` dos demais armazéns.


        Comportamento especial: o POST cria **simultaneamente** o armazém **e** um endereço padrão dentro dele em
        `StockKeepingUnitLocation` (Address = WarehouseName, Default = 1).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WarehouseCreate'
        description: >-
          Dados do depósito a cadastrar. `IDTypeStockKeepingUnitWarehouse` define a natureza (saudável, divergência,
          quarentena, etc.); `Default=1` define como padrão de venda; `DefaultPurchase=1` define como padrão de compra;
          `SumQuantity=1` faz o saldo deste depósito entrar no estoque disponível total.
      responses:
        '200':
          description: Armazém criado (lista completa).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WarehouseItem'
        '400':
          description: >-
            `[BadRequest] - Company not found`; `[BadRequest] - Faturador não existe`; `[BadRequest] - Centro de
            distribuição não existe`; `[BadRequest] - Could not add warehouse`; `[BadRequest] - Could not add location`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/warehouse/{idstockkeepingunitwarehouse}:
    parameters:
      - name: idstockkeepingunitwarehouse
        in: path
        required: true
        schema:
          type: integer
    put:
      operationId: skuWareHousePut
      tags:
        - Armazéns
      summary: Atualiza armazém
      description: >-
        Atualização parcial. Mesmas validações do POST quando trocar CD ou faturador. Quando seta `Default=1` zera os
        demais armazéns.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WarehouseCreate'
        description: Atualiza o depósito. Mesmo schema do POST.
      responses:
        '200':
          description: Armazém atualizado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WarehouseItem'
        '400':
          description: >-
            `[BadRequest] - Armazém não existe`; `[BadRequest] - Centro de distribuição não existe`; `[BadRequest] -
            Faturador não existe`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: skuWareHouseDelete
      tags:
        - Armazéns
      summary: Inativa armazém
      description: >-
        **Soft delete** (`Status=0`, `SumQuantity=0`, `Default=0`). Bloqueada quando o armazém tem endereço cadastrado
        (`StockKeepingUnitLocation`) ou aparece como destino em de/para de armazém (`HubWarehouse`).
      responses:
        '200':
          description: Armazém inativado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WarehouseItem'
        '400':
          description: >-
            `[BadRequest] - Armazém não existe`; `[BadRequest] - Armazém possui endereço cadastrado e não  pode ser
            excluído`; `[BadRequest] - Armazém tem de/para de armazém e não pode ser excluído`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/location/category:
    get:
      operationId: skuLocationCategoryList
      tags:
        - Endereços de Estoque
      summary: Lista categorias de endereço
      description: Lista categorias **Ativas** (`IsActive=1`) da empresa, ordenadas pelo nome.
      parameters:
        - name: IDStockKeepingUnitLocationCategory
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo identificador da categoria de localização do SKU.
      responses:
        '200':
          description: Lista de categorias.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuLocationCategoryItem'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: skuLocationCategoryPost
      tags:
        - Endereços de Estoque
      summary: Cria categoria de endereço
      description: Cria uma categoria. Nome único por empresa.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuLocationCategoryCreate'
        description: Dados da categoria de endereço a cadastrar.
      responses:
        '200':
          description: Categoria criada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuLocationCategoryItem'
                maxItems: 1
        '400':
          description: >-
            `[BadRequest] - Categoria já existente`; `[BadRequest] - Empresa não existe`; `[BadRequest] - Erro ao
            inserir a categoria`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/location/category/{idstockkeepingunitlocationcategory}:
    parameters:
      - name: idstockkeepingunitlocationcategory
        in: path
        required: true
        schema:
          type: integer
    put:
      operationId: skuLocationCategoryPut
      tags:
        - Endereços de Estoque
      summary: Atualiza categoria de endereço
      description: Atualização parcial. Valida unicidade do nome.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuLocationCategoryCreate'
        description: Atualiza a categoria de endereço. Mesmo schema do POST.
      responses:
        '200':
          description: Categoria atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuLocationCategoryItem'
                maxItems: 1
        '400':
          description: '`[BadRequest] - Categoria não existe`; `[BadRequest] - Categoria já existente`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: skuLocationCategoryDelete
      tags:
        - Endereços de Estoque
      summary: Inativa categoria de endereço
      description: >-
        **Soft delete** — `IsActive=0` e prefixa o nome com o id (`<id><nome>`) para liberar o nome para reuso.
        Bloqueada quando há endereço (`StockKeepingUnitLocation`) ou SKU (`StockKeepingUnit`) vinculado à categoria.
      responses:
        '200':
          description: Categoria inativada (string `sucesso`).
          content:
            application/json:
              schema:
                type: string
        '400':
          description: >-
            `[BadRequest] - Categoria não existe`; `[BadRequest] - Categoria esta vinculado a endereço. Editar endereço
            antes de excluir a categoria`; `[BadRequest] - Categoria esta vinculado a SKU. Editar SKU antes de excluir a
            categoria`; `[BadRequest] - Erro ao apagar a categoria`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /fulfillment/picking/basket:
    get:
      operationId: orderFulfillmentPickingBasketList
      tags:
        - Picking
      summary: Lista cestos picking
      description: >-
        Lista cestos Ativos (`PickingListBasketStatus = 1`) com pedido atualmente amarrado (`IDOrder`), CD, dimensões e
        histórico (`PickingListBasketHistory`).
      parameters:
        - name: IDPickingListBasket
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo identificador do cesto da lista de separação.
        - name: IDStockKeepingUnitDistributionCenter
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo identificador do centro de distribuição do SKU.
        - name: ExternalId
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo identificador externo (definido pelo cliente da API).
        - name: Page
          in: query
          required: false
          schema:
            type: integer
          description: Número da página da listagem (1-based). Padrão `1`.
      responses:
        '200':
          description: Lista de cestos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PickingListBasketItem'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: orderFulfillmentPickingBasketPost
      tags:
        - Picking
      summary: Cria cesto picking
      description: >-
        Cria um cesto vinculado a um CD. `ExternalId` é único por CD; quando não informado, o sistema usa o próprio
        `IDPickingListBasket` como ExternalId.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PickingListBasketCreate'
        description: >-
          Cadastra um cesto físico de coleta para um CD. `IDStockKeepingUnitDistributionCenter` é obrigatório;
          `ExternalId` (etiqueta/código de barras impresso no cesto) é opcional — quando ausente o sistema usa o próprio
          `IDPickingListBasket` como `ExternalId`. Dimensões e peso máximo alimentam a sugestão automática de embalagem.
      responses:
        '200':
          description: Cesto criado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PickingListBasketItem'
                maxItems: 1
        '400':
          description: >-
            `[BadRequest] - Centro de distribuição não existe`; `[BadRequest] - Já existe um cesto para este centro de
            distribuição com o mesmo código`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /fulfillment/picking/basket/{idpickinglisbasket}:
    parameters:
      - name: idpickinglisbasket
        in: path
        required: true
        schema:
          type: integer
    put:
      operationId: orderFulfillmentPickingBasketPut
      tags:
        - Picking
      summary: Atualiza cesto picking
      description: >-
        O cesto também pode ser vinculado a uma picking-list via IDPickingList (fluxo colméia), além do vínculo por
        pedido via IDOrder; IDOrder e IDPickingList são mutuamente exclusivos e não podem ser enviados se o cesto já
        tiver o outro tipo de vínculo. Enviar IDOrder=null desvincula o pedido atualmente amarrado.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PickingListBasketCreate'
        description: >-
          Atualiza cadastro do cesto. Aceita os mesmos campos do POST. Enviar `IDOrder = null` desvincula o pedido
          atualmente atrelado ao cesto.
      responses:
        '200':
          description: Cesto atualizado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PickingListBasketItem'
                maxItems: 1
        '400':
          description: '`[BadRequest] - Cesto picking não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: orderFulfillmentPickingBasketDelete
      tags:
        - Picking
      summary: Inativa cesto picking
      description: >-
        **Soft delete** — `PickingListBasketStatus = 0` e libera o `ExternalId` (define como `NULL`) para permitir reuso
        do mesmo código em um novo cesto.
      responses:
        '200':
          description: Cesto inativado (string `sucesso`).
          content:
            application/json:
              schema:
                type: string
        '400':
          description: '`[BadRequest] - Cesto picking não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /fulfillment/picking/basket/{idpickinglisbasket}/label:
    parameters:
      - name: idpickinglisbasket
        in: path
        required: true
        schema:
          type: integer
    get:
      operationId: pickingBasketLabelGet
      tags:
        - Picking
      summary: Gera etiqueta ZPL do cesto
      description: Devolve o ZPL pronto para impressão da etiqueta do cesto (reaproveita o sistema `purchaseLabelGet`).
      responses:
        '200':
          description: Etiqueta ZPL.
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/location:
    get:
      operationId: skuLocationList
      tags:
        - Endereços de Estoque
      summary: Lista endereços do armazém
      description: >-
        Lista endereços (`StockKeepingUnitLocation`) da empresa. **Dois modos de listagem** controlados pelo query param
        `OnlyLocation`:


        - `OnlyLocation=1` (modo padrão da tela): traz **somente** o cadastro do endereço (sem expandir lotes/SKUs).
        Inclui dimensões, tipo, categoria, grupo, armazém e centro de distribuição. Filtra por `Status` do endereço
        (quando informado) e respeita restrição de Centros de Distribuição do usuário
        (`UserCompanyDistributionCenter:<prefix>:<user>`).

        - `OnlyLocation` ausente (modo legado): devolve uma linha por **lote** vinculado ao endereço, com saldo em
        estoque (`QtyAddress`). Útil para visualizar o que tem em cada endereço. Sempre considera apenas endereços com
        `Status = 1`.


        Suporta filtro `Empty` (`QtyAddress = 0` ou `<> 0`) só no modo legado. Paginação por `Page * 5000`.


        Quando a empresa tem parametrização `ShareSkuLocationWithRelatedCompanies = 1` em uma integração tipo `16`, a
        listagem inclui também os endereços da empresa-mãe (`IDCompanyMain`).
      parameters:
        - name: OnlyLocation
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` = só cadastro de endereço; ausente = endereço × lote (com saldo).'
        - name: IDStockKeepingUnitLocation
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo identificador da localização do SKU.
        - name: IDStockKeepingUnitWarehouse
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo identificador do depósito do SKU.
        - name: IDStockKeepingUnitDistributionCenter
          in: query
          required: false
          schema:
            type: string
          description: Lista CSV de centros de distribuição. Sistema valida contra a lista permitida ao usuário.
        - name: IDStockKeepingUnitLocationGroup
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo identificador do grupo de localização do SKU.
        - name: IDStockKeepingUnitLocationCategory
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo identificador da categoria de localização do SKU.
        - name: IDTypeAddress
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 3
          description: 1=Picking, 2=Pulmão, 3=Blocado.
        - name: Address
          in: query
          required: false
          schema:
            type: string
          description: Busca parcial (`LIKE`) pelo nome do endereço.
        - name: Floor
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo andar do endereço.
        - name: Street
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo nome da rua do endereço (busca parcial).
        - name: Module
          in: query
          required: false
          schema:
            type: string
          description: Nome do módulo do sistema (semântica específica do endpoint).
        - name: Column
          in: query
          required: false
          schema:
            type: string
          description: Nome da coluna usada na operação (semântica específica do endpoint).
        - name: Level
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo nível.
        - name: IDSku
          in: query
          required: false
          schema:
            type: integer
          description: Filtro só no modo legado (com lote).
        - name: IDSkuCompany
          in: query
          required: false
          schema:
            type: string
          description: Busca parcial pelo código de referência do SKU (modo legado).
        - name: SkuName
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo nome do produto (busca parcial).
        - name: BarCode
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo código de barras do produto.
        - name: Status
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Aplicado só com `OnlyLocation=1`.
        - name: Empty
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: 'Modo legado: `0`=só endereços vazios, `1`=só endereços com saldo.'
        - name: Page
          in: query
          required: false
          schema:
            type: integer
          description: Número da página da listagem (1-based). Padrão `1`.
      responses:
        '200':
          description: >-
            Lista (até 5000). Modo `OnlyLocation=1` devolve `SkuLocationListItem`; modo legado devolve
            `SkuLocationBatchItem`.
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/SkuLocationListItem'
                  - type: array
                    items:
                      $ref: '#/components/schemas/SkuLocationBatchItem'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: skuLocationPost
      tags:
        - Endereços de Estoque
      summary: Cria um ou mais endereços
      description: >-
        Cria endereço(s). O comportamento depende da parametrização da empresa:


        **Modo WMS** (`NewAddressParameter = 1`):

        - Campos obrigatórios: `IDStockKeepingUnitWarehouse`, `IDTypeAddress`, `IDStockKeepingUnitLocationCategory`,
        dimensões (`Height`, `Width`, `Length`, `MaxWeight` — todos `> 0`).

        - Cadastro individual: enviar `Floor`, `Street`, `Module` (numérico), `Column` (alfanumérico), `Level`
        (numérico). O sistema monta `Address = Floor-Street-Module-Column-Level` (separador padrão `-`, customizável via
        `Concatenator`: `-`, `.` ou `|`). Falha se já existe esse mesmo conjunto Floor/Street/Module/Column/Level + CD.

        - **Cadastro em massa** (`BulkLocation = 1`): enviar `Floor`, `Street`, `StartModule`/`EndModule`,
        `StartColumn`/`EndColumn`, `StartLevel`/`EndLevel`. O sistema gera o **produto cartesiano** das faixas (ex.:
        `StartModule=1`, `EndModule=3`, `StartColumn=A`, `EndColumn=C`, `StartLevel=1`, `EndLevel=2` → 18 endereços).
        Falha se qualquer endereço gerado já existe no CD.

        - Validações: armazém ativo da empresa, categoria ativa da empresa, grupo da empresa (se informado), tipo de
        endereço válido. Módulo e nível precisam ser **numéricos**; coluna pode ser alfanumérica (letras viram
        maiúsculas).


        **Modo legado** (`NewAddressParameter = 0`):

        - Campo obrigatório: `Address` (string livre).

        - `IDStockKeepingUnitWarehouse` opcional; quando informado, valida que o armazém pertence à empresa e que não
        existe outro endereço com mesmo nome no CD. Quando `Default = 1`, zera o `Default` dos demais endereços do
        armazém antes de inserir.


        Devolve o detalhe via list (`OnlyLocation=1`) ou — em cadastro em massa WMS — a string `Endereços cadastrados
        com sucesso`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuLocationCreate'
        description: >-
          Dados do endereço físico (posição) a cadastrar. O endereço completo é montado a partir de `Floor`, `Street`,
          `Module`, `Column`, `Level`. `IDTypeAddress` define o uso (Picking, Pulmão, Recebimento).
      responses:
        '200':
          description: Endereço criado (array com 1 item no modo individual) ou string de sucesso (modo em massa).
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/SkuLocationListItem'
                    maxItems: 1
                  - type: string
                    example: Endereços cadastrados com sucesso
        '400':
          description: >-
            Validações WMS: `[BadRequest] - As dimensões do endereço não podem ser negativas ou vazias`; `[BadRequest] -
            As faixas de módulo, coluna e nível iniciais não podem ser nulas, maiores que as finais e módulo e nível
            possuir letras`; `[BadRequest] - Preencha corretamente o armazém, tipo e categoria de armazenamento`;
            `[BadRequest] - Armazém não foi encontrado`; `[BadRequest] - Categoria de armazenamento não encontrada`;
            `[BadRequest] - Grupo endereço não encontrado`; `[BadRequest] - Tipo de endereço não encontrado`;
            `[BadRequest] - Preencha todos os campos do endereço (Andar, Rua, Modulo, Coluna e Nivel)`; `[BadRequest] -
            Preencha módulo e nível com números`; `[BadRequest] - Já existe este endereço para o mesmo centro de
            distribuição`; `[BadRequest] - Endereços repitidos, consulte seus endereços`; `[BadRequest] - Erro ao gerar
            endereços em massa`; `[BadRequest] - Erro ao inserir endereços`. Validações legado: `[BadRequest] - Endereço
            precisa ser informado`; `[BadRequest] - Armazém não localizado`; `[BadRequest] - Já existe este endereço
            para o centro de distribuição`. Gerais: `[BadRequest] - Empresa não existe`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/location/{idstockkeepingunitlocation}:
    parameters:
      - name: idstockkeepingunitlocation
        in: path
        required: true
        schema:
          type: integer
    put:
      operationId: skuLocationPut
      tags:
        - Endereços de Estoque
      summary: Atualiza um endereço
      description: >-
        Atualização parcial. Quando `NewAddressParameter = 1`, aceita todos os campos WMS (dimensões precisam ser
        positivas; módulo e nível precisam ser numéricos quando alterados). Quando o endereço já tem **movimento**
        (`StockKeepingUnitMovement` via lote vinculado), **não pode mudar o armazém** — bloqueio para preservar
        histórico.


        No modo WMS, se o nome do endereço (`Address`) não vier no body, é recalculado automaticamente como
        `Floor-Street-Module-Column-Level` usando o separador detectado no `Address` original (`-`, `.` ou `|`).


        Ao marcar `Default = 1`, zera o `Default` dos demais endereços do mesmo armazém antes de aplicar a alteração.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuLocationUpdate'
        description: Atualiza o endereço físico.
      responses:
        '200':
          description: Endereço atualizado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuLocationListItem'
                maxItems: 1
        '400':
          description: >-
            `[BadRequest] - Localização não existe`; `[BadRequest] - As dimensões do endereço não podem ser negativas`;
            `[BadRequest] - Preencha módulo e nível com números`; `[BadRequest] - Endereço não pode ter armazém
            alterado, pois já possui venda`; `[BadRequest] - Armazém não localizado`; `[BadRequest] - Preencha
            corretamente a categoria de armazenamento`; `[BadRequest] - Preencha corretamente o tipo de endereço`;
            `[BadRequest] - Grupo endereço não encontrado`; `[BadRequest] - Já existe este endereço para o centro de
            distribuição`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: skuLocationDelete
      tags:
        - Endereços de Estoque
      summary: Exclui um endereço
      description: >-
        **Exclusão física**. Bloqueada quando existe pelo menos um lote (`StockKeepingUnitBatch`) vinculado ao endereço
        — neste caso devolve `Endereço possui lote/sku vinculado e não pode ser removido`. Para excluir, primeiro
        transfira o estoque para outro endereço.


        Quando o endereço não tem lote vinculado, remove o registro definitivamente e devolve a string `sucesso`.
      responses:
        '200':
          description: Endereço excluído (string `sucesso`).
          content:
            application/json:
              schema:
                type: string
        '400':
          description: >-
            `[BadRequest] - Endereço não existe`; `[BadRequest] - Endereço possui lote/sku vinculado e não pode ser
            removido`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/location/{idstockkeepingunitlocation}/label:
    parameters:
      - name: idstockkeepingunitlocation
        in: path
        required: true
        schema:
          type: integer
    get:
      operationId: skuLocationLabelGet
      tags:
        - Endereços de Estoque
      summary: Gera a etiqueta ZPL do endereço
      description: >-
        Devolve o conteúdo ZPL pronto para impressão da etiqueta do endereço. Reaproveita o sistema `purchaseLabelGet` —
        o conteúdo é definido pelo template de etiqueta de endereço configurado para a empresa.
      responses:
        '200':
          description: Etiqueta ZPL como string.
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /user/workingday:
    get:
      operationId: userWorkingDayList
      tags:
        - Jornada de Trabalho
      summary: Lista colaboradores
      description: >-
        Lista colaboradores (`UserWorkingDay`) com escala, função atual, funções permitidas, grupos de endereços,
        categorias de endereço, supervisor e última atividade do usuário (`LastActivityTimestamp`).
      parameters:
        - name: IDUserWorkingDay
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo identificador do dia de trabalho do usuário.
        - name: IDUser
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo identificador do usuário.
        - name: IDStockKeepingUnitLocationCategoryList
          in: query
          required: false
          schema:
            type: string
          description: Lista CSV de ids; filtra coincidência exata da string CSV.
        - name: IDUserJobPositionList
          in: query
          required: false
          schema:
            type: integer
          description: Filtra colaboradores que tenham essa função no CSV `IDUserJobPositionList` (`FIND_IN_SET`).
        - name: Status
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
              - 2
          description: >-
            Filtra por status. A semântica e os valores aceitos dependem do endpoint — consulte o `description` da
            operação.
        - name: IDWorkScale
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo identificador da escala de trabalho.
        - name: IDUserUpper
          in: query
          required: false
          schema:
            type: integer
          description: Filtra subordinados de um supervisor.
      responses:
        '200':
          description: Lista de colaboradores.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserWorkingDayListItem'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: userWorkingDayPost
      tags:
        - Jornada de Trabalho
      summary: Cadastra um colaborador
      description: >-
        Cria o registro de colaborador para um `IDUser` existente. Valida em cascata: usuário pertence à empresa, escala
        existe na empresa, cada função informada existe, função atual está dentro da lista de funções, cada
        categoria/grupo de endereço informado pertence à empresa, supervisor (quando informado) existe.


        **Restrição**: cada usuário tem **apenas 1** registro `UserWorkingDay` por empresa — tentativa duplicada devolve
        `[BadRequest] - Colaborador já existe para esse usuário`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserWorkingDayCreate'
        description: >-
          Colaborador a cadastrar. `IDUser`, `IDUserJobPositionList` (CSV de funções) e `IDUserWorkScale` (escala) são
          obrigatórios. Cada usuário só pode ter um cadastro de colaborador por empresa. Categorias/grupos de endereço e
          supervisor são opcionais; todos os ids informados são validados contra a empresa autenticada.
      responses:
        '200':
          description: Colaborador criado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserWorkingDayListItem'
                maxItems: 1
        '400':
          description: >-
            Validações: `[BadRequest] - Preencha os campos corretamente`; `[BadRequest] - Usuário não existe, preencha
            corretamente`; `[BadRequest] - Colaborador já existe para esse usuário`; `[BadRequest] - Função atual não
            atríbuida ao colaborador`; `[BadRequest] - Função não existente, preencha corretamente`; `[BadRequest] -
            Categoria de armazenamento não existe`; `[BadRequest] - Escala não existe, preencha corretamente`;
            `[BadRequest] - Grupo de armazenamento não existe`; `[BadRequest] - Colaborador superior não existe,
            preencha corretamente`; `[BadRequest] - Empresa não existe`; `[BadRequest] - Erro ao cadastrar colaborador`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /user/workingday/{idworkingday}:
    parameters:
      - name: idworkingday
        in: path
        required: true
        schema:
          type: integer
    put:
      operationId: userWorkingDayPut
      tags:
        - Jornada de Trabalho
      summary: Atualiza um colaborador
      description: >-
        **Atualização parcial** — só os campos enviados são alterados (passar string vazia em
        `IDStockKeepingUnitLocationCategoryList`, `IDStockKeepingUnitLocationGroupList` ou `IDUserUpper` limpa o campo
        para NULL). Valida unicidade da escala/função/grupo dentro da empresa e proíbe colaborador ser próprio
        supervisor.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserWorkingDayUpdate'
        description: >-
          Atualização parcial do colaborador — só os campos enviados são alterados. String vazia em
          `IDStockKeepingUnitLocationCategoryList`, `IDStockKeepingUnitLocationGroupList` ou `IDUserUpper` limpa o
          campo. Colaborador não pode ser seu próprio supervisor.
      responses:
        '200':
          description: Colaborador atualizado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserWorkingDayListItem'
                maxItems: 1
        '400':
          description: >-
            Validações do POST + `[BadRequest] - Colaborador não existe`; `[BadRequest] - Colaborador não pode ser seu
            próprio supervisor`; `[BadRequest] - Preencha corretamente o status`; `[BadRequest] - Categoria armazém não
            existe (<id>)`; `[BadRequest] - Grupo endereços não existe`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: userWorkingDayDelete
      tags:
        - Jornada de Trabalho
      summary: Exclui um colaborador
      description: >-
        **Exclusão física**. Bloqueada quando o colaborador é supervisor de outro colaborador (verifica `IDUserUpper =
        ?`).
      responses:
        '200':
          description: Colaborador excluído (string literal `Colaborador excluído com sucesso`).
          content:
            application/json:
              schema:
                type: string
        '400':
          description: >-
            `[BadRequest] - Informe corretamente o colaborador`; `[BadRequest] - Colaborador não existe`; `[BadRequest]
            - Colaborador é supervisor de outros colaboradores e não pode ser excluído`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /carrier/quotation/error:
    get:
      operationId: carrierQuotationErrorList
      tags:
        - Cotação de Frete
      summary: Lista erros de simulação de frete
      description: >-
        Lista os erros de simulação de frete da empresa em páginas de até 3000 registros (avance com `Page`), ordenados
        por `IDCarrierQuotationError` decrescente.
      parameters:
        - name: DateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Filtra erros com `RecordTimestamp` ≥ esta data.
        - name: DateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Filtra erros com `RecordTimestamp` ≤ esta data 23:59:59.
        - name: Page
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          description: >-
            Índice da página para paginação, começando em `0`. Cada página retorna até 3000 erros; informe `1` para os
            próximos 3000, e assim por diante. Quando omitido, assume `0` (primeira página).
      responses:
        '200':
          description: Lista dos erros (até 3000).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CarrierQuotationErrorListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /orders/package:
    get:
      operationId: packageList
      tags:
        - Pedidos
      summary: Lista pacotes (fila do Pré-Romaneio)
      description: >-
        Lista pacotes (`Packages`) com dados do pedido, transportadora, código de rastreio (`ShippingId`), status do
        pedido (`IDStatusOrder` / `StatusOrder`), status do pacote (`IDStatusPackage` / `StatusPackage`), CD
        (`DistributionCenterName`), conta (`AccountName`) e romaneio atual (`IDOrdersCarrierCollectionList`). Restrito
        automaticamente pelos CDs habilitados ao usuário logado. Paginado em blocos de 5000 (`Page` = número; offset =
        `Page * 5000`).
      parameters:
        - name: IDStatusOrder
          in: query
          required: false
          schema:
            type: string
          description: >-
            Status do pedido (CSV — múltiplos valores aceitos). Útil para listar só `6,22` (aguardando
            expedição/romaneio).
        - name: Order
          in: query
          required: false
          schema:
            type: string
          description: Número do pedido (`Order`). Aceita CSV ou separado por espaço.
        - name: IDOrder
          in: query
          required: false
          schema:
            type: string
          description: Código numérico do pedido (`IDOrder`). Aceita CSV ou separado por espaço.
        - name: ShippingId
          in: query
          required: false
          schema:
            type: string
          description: Código de rastreio do pacote.
        - name: IDPackage
          in: query
          required: false
          schema:
            type: integer
            format: int32
          description: Identificador interno do pacote.
        - name: IDOrdersCarrierCollectionList
          in: query
          required: false
          schema:
            type: integer
            format: int32
          description: Filtra pacotes já amarrados a um romaneio específico.
        - name: IDStockKeepingUnitDistributionCenter
          in: query
          required: false
          schema:
            type: string
          description: Filtra por CD (validado contra os CDs habilitados ao usuário; valores fora da lista retornam vazio).
        - name: nullCollection
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` filtra apenas pacotes ainda **sem romaneio** (sem `IDOrdersCarrierCollectionList`).'
        - name: Page
          in: query
          required: false
          schema:
            type: integer
            format: int32
            minimum: 0
          description: Página (blocos de 5000).
      responses:
        '200':
          description: Lista de pacotes (até 5000 por página).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PreCollectionPackageListItem'
  /fulfillment/packing/collection-list/order:
    post:
      operationId: orderFulfillmentCarrierCollectionListOrderPost
      tags:
        - Packing
      summary: Amarra pacote (ou pedido) ao romaneio por bipagem
      description: >-
        Recebe o código de rastreio (`ShippingId`) **ou** a chave de acesso da NF-e (44 dígitos) em `Search`, junto com
        `IDCarrier` (transportadora bipada). Localiza o pacote ou o pedido, valida regras e amarra o item a um romaneio
        em aberto (status `1`) da combinação transportadora + CD (+ operador, conforme parametrização). Se não houver
        romaneio aberto compatível, cria um novo registro em `OrdersCarrierCollectionList`.


        **Modos** controlados por parâmetros de empresa:

        - `PackagesOnOrdersCarrierCollectionList=1` → modo **por pacote** (cada pacote individual é amarrado). Quando
        `Search` é uma chave NF-e (44 dígitos), todos os pacotes do pedido vão para o mesmo romaneio. Suporta
        `AllowMultipleOrdersCarrierCollectionListPerOrder=1` para permitir pacotes do mesmo pedido em romaneios
        distintos.

        - `PackagesOnOrdersCarrierCollectionList=0` → modo **por pedido** (`IDOrdersCarrierCollectionList` é atualizado
        e o pedido inteiro é vinculado).

        - `OneCollectionListPerWorker=1` → romaneio aberto separado por operador.


        **Efeitos** em qualquer modo:

        - Atualiza `IDOrdersCarrierCollectionList` (ou `IDOrdersCarrierCollectionList`).

        - Atualiza `IDStatusOrder = 6` (Aguardando expedição) quando vinha de `22` (Aguardando romaneio).

        - Grava `OrderEvent` com `IDEvent=27` (`Inserido romaneio: <id>`) no histórico do pedido.

        - Retorna o pedido atualizado, exceto quando `NoInvoke=1` (resposta passa a ser literal `"Sucesso"`).
      parameters:
        - name: NoInvoke
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: >-
            `1` (default no fluxo de bipagem comum) retorna `"Sucesso"` sem invocar `OrderGet`. `0` (fluxo do modal de
            edição) invoca `OrderGet` e retorna o pedido completo.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreCollectionPostPayload'
        description: >-
          Bipa um pacote para amarrar ao romaneio em formação. `Search` aceita o **código de rastreio do pacote** ou a
          **chave de acesso da NF-e** (44 dígitos — o sistema detecta o formato via regex). `IDCarrier` precisa
          coincidir com a transportadora do pedido bipado, caso contrário retorna `[BadRequest]`.
      responses:
        '200':
          description: >-
            Sucesso. Quando `NoInvoke=1` retorna o literal `"Sucesso"`; caso contrário retorna o pedido vindo do
            `OrderGet`.
          content:
            application/json:
              schema:
                oneOf:
                  - type: string
                    example: Sucesso
                  - type: object
                    description: Resposta do `OrderGet` (pedido completo).
        '400':
          description: >-
            Mensagens `[BadRequest]` típicas:

            - `Por favor informar o código do pacote`

            - `Por favor informar o código da transportadora`

            - `Pedido não encontrado` / `Pacote não encontrado`

            - `Pedido não possui transportadora`

            - `Transportadora informada divergente do pedido`

            - `Pedido já inserido em romaneio` / `Pacote já inserido em romaneio`

            - `Nota fiscal divergente`

            - `Romaneio divergente, esse pedido já possui pacotes em outros romaneios`

            - `Status do pedido não permite inserir no romaneio, precisa estar aguardando romaneio ou aguardando
            expedição`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /fulfillment/packing/collection-list:
    get:
      operationId: orderFulfillmentCarrierCollectionListList
      tags:
        - Packing
      summary: Lista romaneios com filtros
      description: >-
        Lista os romaneios (`OrdersCarrierCollectionList`) da empresa, opcionalmente filtrados por status,
        transportadora, CD, operador, código do romaneio e intervalo de datas. Limite fixo de 500 registros. Quando o
        usuário tem restrição de CD e o `IDStockKeepingUnitDistributionCenter` solicitado não está na lista permitida,
        retorna array vazio.


        Os campos `FileName1..FileName5` são retornados como URLs pré-assinadas do S3 (validade de 48 h) ou `null`
        quando o anexo correspondente não foi enviado.
      parameters:
        - name: IDOrdersCarrierCollectionListStatus
          in: query
          required: false
          schema:
            type: string
          description: >-
            Lista de status separados por vírgula (ex.: `1,2`). Valores possíveis: `1`=Aberto, `2`=Fechado,
            `3`=Finalizado. Sem este filtro, retorna todos os status.
        - name: RecordTimestamp
          in: query
          required: false
          schema:
            type: string
            format: date
          description: >-
            Data inicial do intervalo (formato `YYYY-MM-DD`). Filtra contra `RecordTimestampEnd` (data de finalização) —
            não contra a data de criação.
        - name: RecordTimestampEnd
          in: query
          required: false
          schema:
            type: string
            format: date
          description: >-
            Data final do intervalo (formato `YYYY-MM-DD`). `23:59:59` é apendado automaticamente para incluir o dia
            inteiro.
        - name: IDOrdersCarrierCollectionList
          in: query
          required: false
          schema:
            type: string
          description: 'Filtro por identificador(es) do romaneio. Aceita vários separados por vírgula (ex.: `33895,398`).'
        - name: IDCarrier
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtro por transportadora (`IDSupplier`).
        - name: IDStockKeepingUnitDistributionCenter
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: >-
            Filtro por centro de distribuição. Submetido à ACL do usuário — quando o usuário tem restrição de CDs e o CD
            solicitado não está na lista, retorna vazio.
        - name: RecordUserCreated
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtro por usuário criador (`IDUser`).
      responses:
        '200':
          description: Lista de romaneios (no máximo 500).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CollectionListListItem'
    post:
      operationId: orderFulfillmentCarrierCollectionListPost
      tags:
        - Packing
      summary: Cria romaneio vazio para uma transportadora
      description: >-
        Cria um romaneio novo (`OrdersCarrierCollectionList`) em status `1` (Aberto), sem pacotes vinculados. O
        `IDCarrier` precisa pertencer a um fornecedor (`Suppliers`) da empresa autenticada.


        Na prática a maioria dos romaneios é criada **automaticamente** pelo endpoint `POST
        /fulfillment/packing/collection-list/order` (Pré-Romaneio) ao amarrar o primeiro pacote — este endpoint cobre o
        caso raro de criação manual antecipada.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CollectionListPostPayload'
        description: >-
          Cria um romaneio vazio para uma transportadora. Após criado, pacotes são amarrados via `POST
          /fulfillment/packing/collection-list/order` (bipagem) e o romaneio segue o fluxo Aberto → Fechado →
          Finalizado.
      responses:
        '200':
          description: Sucesso. O sistema executa o `INSERT` mas não invoca callback — a resposta é vazia/`null`.
        '400':
          description: |-
            Mensagens `[BadRequest]` típicas:
            - `Company não existe` — prefixo do token não resolveu para empresa.
            - `Transportadora não existe` — `IDCarrier` não está em `Suppliers` para esta empresa.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /fulfillment/packing/collection-list/{idorderscarriercollectionlist}:
    get:
      operationId: orderFulfillmentCarrierCollectionListGet
      tags:
        - Packing
      summary: Detalhe do romaneio (com pedidos e pendências)
      description: >-
        Detalhe completo do romaneio. Além dos campos do `List`, inclui `Orders` (todos os pedidos/volumes do romaneio
        com dados do destinatário, NF, rastreio e peso) e `PedingPackages` (volumes do pedido que estão em **outros**
        romaneios — usado para avisar sobre split ao fechar).


        Quando a parametrização **Exibir dados faturador folha romaneio** (`ShowCompanyInvoiceCarrierCollection=1`) está
        habilitada, os campos `CompanyNameCorporateName`/`CompanyCpfCnpj`/`CompanyLogoUrl` no cabeçalho do romaneio são
        substituídos pelos dados do faturador do **primeiro** pedido (quando há múltiplos faturadores).
      parameters:
        - name: idorderscarriercollectionlist
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do romaneio (`IDOrdersCarrierCollectionList`).
      responses:
        '200':
          description: Detalhe do romaneio em array (com 0 ou 1 elemento).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CollectionListDetail'
    put:
      operationId: orderFulfillmentCarrierCollectionListPut
      tags:
        - Packing
      summary: Altera a transportadora do romaneio inteiro
      description: >-
        Substitui a transportadora de **todos os pedidos** do romaneio pela informada em `IDCarrier`. Só permitido
        enquanto o romaneio **ainda não foi assinado** (`FileName1 IS NULL`).


        **Efeitos:**

        - Em cada pedido do romaneio, atualiza `IDCarrier` para a nova transportadora e zera `IntegrationEdiCarrier`
        (reseta integração EDI da transportadora).

        - Grava `OrderEvent` (`IDEvent=31`, `Header=1`) em cada pedido com comentário `"Transportadora alterada de:
        {antiga} para: {nova}"`.

        - Atualiza o `IDCarrier` do próprio romaneio.

        - Retorna o detalhe atualizado (invoca `Get` internamente).


        Para remover apenas alguns pacotes (e não o romaneio inteiro), use `PUT
        /fulfillment/packing/collection-list/{id}/order`.
      parameters:
        - name: idorderscarriercollectionlist
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do romaneio (`IDOrdersCarrierCollectionList`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CollectionListPutPayload'
        description: >-
          Troca a transportadora do romaneio. A nova transportadora precisa estar ativa, pertencer à empresa e ser
          diferente da atual.
      responses:
        '200':
          description: Detalhe do romaneio com a nova transportadora.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CollectionListDetail'
        '400':
          description: |-
            Mensagens `[BadRequest]` típicas:
            - `Precisa enviar nova transportadora` — `IDCarrier` ausente.
            - `Romaneio já possui assinatura e não pode ser alterado` — `FileName1` preenchido.
            - `Nova transportadora precisa ser diferente da anterior`.
            - `Romaneio não existe`.
            - `Transportadora não existe` — fornecedor inativo (`SupplierStatus != 1`) ou de outra empresa.
            - `Pacotes para romaneio não localizados` — romaneio sem pedidos/pacotes amarrados.
            - `Erro ao atualizar romaneio`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /fulfillment/packing/collection-list/{idorderscarriercollectionlist}/close:
    post:
      operationId: orderFulfillmentCarrierCollectionListClosePost
      tags:
        - Packing
      summary: Fecha o romaneio (status 1 → 2)
      description: >-
        Move o romaneio de Aberto (1) para Fechado (2). A partir daí o romaneio aceita conferência por bipagem mas não
        recebe pacotes novos.


        Quando as parametrizações **Considerar pacotes ao inserir no romaneio**
        (`PackagesOnOrdersCarrierCollectionList=1`) **e** **Permitir pacotes do mesmo pedido em diferentes romaneios**
        (`AllowMultipleOrdersCarrierCollectionListPerOrder=0`) estão na combinação restritiva, o endpoint valida que
        **todos os pacotes** dos pedidos do romaneio estão neste romaneio. Se houver pacotes do mesmo pedido em outros
        lugares, retorna 400 e o frontend mostra a tabela de pendências.


        Retorna a **lista** atualizada filtrada por `IDOrdersCarrierCollectionListStatus=1,2` (operação ainda em
        andamento).
      parameters:
        - name: idorderscarriercollectionlist
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do romaneio (`IDOrdersCarrierCollectionList`).
      responses:
        '200':
          description: Lista de romaneios Aberto + Fechado (resposta padrão para refresh do listing).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CollectionListListItem'
        '400':
          description: |-
            Mensagens `[BadRequest]` típicas:
            - `Romaneio não existe`.
            - `Pedidos X,Y,Z possuem pacotes que não estão nesse romaneio` — split detectado no modo restritivo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /fulfillment/packing/collection-list/{idorderscarriercollectionlist}/open:
    post:
      operationId: orderFulfillmentCarrierCollectionListOpenPost
      tags:
        - Packing
      summary: Reabre o romaneio (status 2 → 1)
      description: >-
        Move o romaneio de Fechado (2) de volta para Aberto (1), permitindo amarração de pacotes novos. **Romaneios
        Finalizados (3) não podem ser reabertos** — uma vez despachado o romaneio é definitivo (os pedidos já estão como
        Enviado e os pacotes com data de embarque).
      parameters:
        - name: idorderscarriercollectionlist
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do romaneio (`IDOrdersCarrierCollectionList`).
      responses:
        '200':
          description: Lista de romaneios Aberto + Fechado atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CollectionListListItem'
        '400':
          description: |-
            Mensagens `[BadRequest]` típicas:
            - `Romaneio finalizado não pode ser alterado para aberto` — status atual é `3`.
            - `Romaneio não existe`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /fulfillment/packing/collection-list/{idorderscarriercollectionlist}/finish:
    post:
      operationId: orderFulfillmentCarrierCollectionListFinishPost
      tags:
        - Packing
      summary: Finaliza o romaneio e despacha os pedidos
      description: >-
        Despacha o romaneio. Move o status para `3` (Finalizado), grava `RecordTimestampEnd` com o momento atual e
        aplica em paralelo:


        - **Pedidos com `IDCarrierType IN (30, 32)`** (retirada / canal-marketplace) → `IDStatusOrder = 17` (Retirada) +
        `OrderEvent` `IDEvent=46`.

        - **Demais pedidos** → `IDStatusOrder = 7` (Enviado) + `OrderEvent` `IDEvent=4`.

        - **Volumes** → `IDStatusPackage = 1` e `ShippingDate` com o momento do despacho.

        - **Movimentos de estoque** → `IDStatusSku = 1`, `QuantityNonconformity = NULL`, `IDTypeFulfillmentNonconformity
        = NULL`.


        Retorna o detalhe atualizado (invoca `Get` internamente).
      parameters:
        - name: idorderscarriercollectionlist
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do romaneio (`IDOrdersCarrierCollectionList`).
      responses:
        '200':
          description: Detalhe do romaneio finalizado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CollectionListDetail'
        '400':
          description: |-
            Mensagens `[BadRequest]` típicas:
            - `Romaneio não existe`.
            - `Romaneio não existe (pedidos)` — UNION de pedidos/pacotes vazia.
            - `Erro ao finalizar romaneio`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /fulfillment/packing/collection-list/{idorderscarriercollectionlist}/file:
    post:
      operationId: orderFulfillmentCarrierCollectionListFilePost
      tags:
        - Packing
      summary: Salva assinatura do motorista e PDF final
      description: >-
        Registra a retirada do romaneio pela transportadora: salva os dados do motorista, a imagem da assinatura
        digital, anexos opcionais e o PDF do romaneio. Bloqueia toda edição posterior do romaneio (alterar
        transportadora, remover pacote, merge).


        **Restrições:**

        - Romaneio precisa estar em status `3` (Finalizado).

        - Romaneio não pode estar já assinado (`FileName1 IS NULL`).


        **Efeitos:**

        - Upload no S3 (bucket `OrdersCarrierCollectionListFiles/`): `{id}_Signature.{ext}` (assinatura),
        `{id}_1_DocumentImage.{ext}` / `{id}_2_DocumentImage.{ext}` / `{id}_3_DocumentImage.{ext}` (anexos),
        `{id}_Signaturepdf.pdf` (PDF).

        - No romaneio, grava nome/documento/placa/comentário, os paths dos arquivos enviados e `SigningRecordTimestamp`
        com o momento da assinatura (horário de Brasília).

        - Se **Enviar email automaticamente para transportadora** (`AutoSendEmailToCarrier=1`) estiver habilitado e
        `CarrierCollectionListEmail` estiver preenchido, dispara e-mail (SES ou SMTP configurado em `CompanyIntegration
        IDTypeCompanyIntegration=51`) com assunto `"Romaneio {id} - {empresa}"` e PDF anexado. CC: lista em
        `CCEmailsAutoSendEmailToCarrier`.
      parameters:
        - name: idorderscarriercollectionlist
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do romaneio (`IDOrdersCarrierCollectionList`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CollectionListFilePayload'
        description: >-
          Registra a assinatura do motorista no momento da retirada: documento, nome, placa, comentário e até 5 arquivos
          (`FileName1`..`FileName5`) enviados como **data URIs base64**. `FileName1` (assinatura) e `FileName5` são
          obrigatórios. Após gravada a assinatura, o romaneio fica imutável (não permite reabrir, mesclar nem trocar
          pedidos).
      responses:
        '200':
          description: >-
            Lista contendo o romaneio recém-assinado (`GET
            /fulfillment/packing/collection-list?IDOrdersCarrierCollectionList=<id>`).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CollectionListListItem'
        '400':
          description: >-
            Mensagens `[BadRequest]` típicas:

            - `Preencha corretamente o código do Romaneio`.

            - `Preencha corretamente os campos do motorista e assinatura` — algum dos campos obrigatórios
            (`CarrierDriverDocument`, `CarrierDriverNameCorporateName`, `CarLicensePlate`, `FileName1`, `FileName5`)
            vazio.

            - `Romaneio não encontrado`.

            - `Romaneio já assinado` — `FileName1` já preenchido.

            - `Status não permite assinar romaneio` — status != 3.

            - `erro ao subir assinatura` / `erro ao subir arquivos` / `erro ao subir pdf do romaneio` — falha no S3.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /fulfillment/packing/collection-list/{idorderscarriercollectionlist}/order:
    put:
      operationId: orderFulfillmentCarrierCollectionListOrderPut
      tags:
        - Packing
      summary: Remove pacotes do romaneio e reatribui transportadora
      description: >-
        Remove um subconjunto de pacotes do romaneio e atribui uma nova transportadora aos pedidos afetados. Operação
        típica de correção: pacote foi para o romaneio errado e precisa ir em outra transportadora ou ficar para outro
        dia.


        **Restrições:**

        - Romaneio não pode estar assinado (`FileName1 IS NULL`).

        - Nova transportadora precisa estar ativa e ser diferente da atual.

        - Cada `IDPackage` em `IDPackageArray` precisa pertencer a este romaneio.


        **Efeitos:**

        - Nos pacotes informados, define `IDOrdersCarrierCollectionList = NULL` (desvincula do romaneio).

        - Nos pedidos dos pacotes removidos, define `IDStatusOrder = 22` (Aguardando expedição), `IDCarrier` para o
        novo, `IDOrdersCarrierCollectionList = NULL` e `IntegrationEdiCarrier = NULL`.

        - Grava `OrderEvent` (`IDEvent=31`, `Header=1`) com comentário `"Transportadora alterada de: {antiga} para:
        {nova}, removido do romaneio: {id}"`.

        - Retorna o detalhe do romaneio atualizado (invoca `Get`).


        O romaneio em si **não** é alterado — apenas os pedidos/pacotes saem dele. Para trocar a transportadora do
        romaneio inteiro, use `PUT /fulfillment/packing/collection-list/{id}`.
      parameters:
        - name: idorderscarriercollectionlist
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do romaneio (`IDOrdersCarrierCollectionList`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CollectionListOrderPutPayload'
        description: >-
          Remove pacotes do romaneio e atribui uma nova transportadora aos pedidos correspondentes. Cada `IDPackage`
          precisa pertencer a este romaneio; os pedidos voltam para o status **Aguardando expedição** com a `IDCarrier`
          informada.
      responses:
        '200':
          description: Detalhe do romaneio sem os pacotes removidos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CollectionListDetail'
        '400':
          description: |-
            Mensagens `[BadRequest]` típicas:
            - `Precisa enviar nova transportadora`.
            - `Precisa enviar pacotes para alteração de transportadora`.
            - `Romaneio já possui assinatura e não pode ser alterado`.
            - `Nova transportadora precisa ser diferente da anterior`.
            - `Romaneio não existe`.
            - `Transportadora não existe`.
            - `Pacotes para romaneio não localizados`.
            - `Pacotes não localizados para o romaneio` — algum `IDPackage` não pertence a este romaneio.
            - `Erro ao atualizar romaneio`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /fulfillment/packing/order/{idorder}:
    post:
      operationId: orderFulfillmentPackingIDOrderPost
      tags:
        - Packing
      summary: Finaliza (ou rascunha) o packing de um pedido
      description: >-
        Coração do fluxo de packing. Dois modos:


        **Modo Rascunho** (`Draft=1`): apenas grava o `body` como rascunho temporário sob a chave
        `PickingList:<IDPickingList>` (TTL 4 dias). Não toca em banco. Retorna `"sucesso"`. É chamado **a cada bipagem**
        pelo frontend para preservar o progresso do operador.


        **Modo Final** (sem `Draft`): processa o packing completo:


        1. **Conferência**: compara `Items` enviados com `StockKeepingUnitMovement` do pedido. Em caso de divergência,
        falha com mensagem detalhada (itens não enviados / a maior / a menor). Aceita divergência apenas quando
        `PartialInvoice=1` (com privilégio + parametrização habilitada).

        2. **Faturamento parcial**: quando há `differenceSentLessQty`, ajusta `StockKeepingUnitMovement`
        proporcionalmente, recalcula `PriceSellingTotal` e reescala `Value`. Se
        `AutomaticTransferPartialInvoiceWarehousePacking` configurado, transfere itens removidos para o endereço de
        Quarentena.

        3. **Validação de série**: para SKUs com `SerialNumber=1`, valida e amarra cada serial via
        `StockKeepingUnitSerialNumber`.

        4. **Reconciliação de volumes**: cria/apaga linhas em `Packages` para bater com `QuantityPackages`; salva
        dimensões dos volumes vindas em `Volumes[]`.

        5. **Embalagens**: para cada item em `Packages[]`, insere a linha de embalagem no pedido (com `PriceSelling=0`).

        6. **NF-e**: dispara a emissão da nota fiscal, a menos que `NoInvoke=1`.

        7. **Transição de status**: com transportadora + romaneio habilitado → status `6` + adiciona ao romaneio aberto.
        Com `SetShippedAfterPacking=1` ou `IDOrderStatusTo`, dispara a mudança de status do pedido (geralmente para `7`
        Enviado). Caso contrário → status `22` (Aguardando romaneio).

        8. **Picking-list status**: marca como `5` (Concluído) quando todos os pedidos terminaram, ou `4` (Em packing)
        caso contrário.


        Aplica debounce de 3s (MD5 do body) para evitar disparo duplicado pelo operador.


        Retorna o detalhe atualizado do pedido.


        Quando a parametrização Ignorar itens de serviço no faturamento (IgnoreServiceItemsOnInvoice) está habilitada,
        os itens cujo SKU é do tipo Serviço são desconsiderados da conferência — não precisam ser enviados em Items.
      parameters:
        - name: idorder
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do pedido (`IDOrder`).
        - name: Draft
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: >-
            `1` apenas grava o body como rascunho temporário (TTL 4 dias) sem efeitos colaterais. Usado pelo frontend
            para autosave entre bipagens.
        - name: PartialInvoice
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: >-
            `1` autoriza faturamento parcial (fecha o packing mesmo com itens conferidos a menos). Só tem efeito quando
            a parametrização **Permitir faturamento parcial no packing** está habilitada e o body inclui `TempAuthToken`
            (obtido via `POST /user/{id}/verify` com `PrivilegeAllowPartialInvoice`).
        - name: NoInvoice
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: >-
            `1` pula a emissão de NF-e (não invoca o processo). Também ignora o gate de status fiscal no final. Usado em
            fluxos sem nota.
        - name: IDOrderStatusTo
          in: query
          required: false
          schema:
            type: integer
          description: >-
            Status final desejado para o pedido (override). Quando informado, invoca `orderStatusPut` em vez da lógica
            padrão de romaneio. Tipicamente `7` (Enviado).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PackingOrderPostPayload'
        description: >-
          Finaliza (ou salva rascunho com query `?Draft=1`) o packing de um pedido. Cada bipagem na tela vira uma
          entrada em `Items`; `Volumes` traz peso/dimensões de cada volume. Quando os itens conferidos batem com o
          esperado da picking-list, o sistema cria os pacotes, dispara a emissão da NF-e e avança o status do pedido.
      responses:
        '200':
          description: 'Em modo Rascunho: literal `"sucesso"`. Em modo Final: detalhe do pedido (resultado de `OrderGet`).'
          content:
            application/json:
              schema:
                oneOf:
                  - type: string
                    example: sucesso
                  - type: object
                    description: Resposta do `OrderGet`.
        '400':
          description: >-
            Mensagens `[BadRequest]` típicas:

            - `Processo de faturamento em dupliciade` — disparo duplicado em menos de 3 s.

            - `Pedido esta no status aberto e não pode seguir o processo de packing`.

            - `Pedido esta com nota fiscal emitida e não pode alterar as quantidades dos itens` — `PartialInvoice` com
            NF já emitida.

            - `<itens não enviados: …> | <itens enviados qtde a maior: …> | <itens enviados qtde a menor: …>` —
            divergência sem `PartialInvoice=1`.

            - `Item X controla serial mas não foi enviado no faturamento`.

            - `Item X controla serial e tem quantidade maior que um. Precisa ser enviado de forma individual o serial`.

            - `Serial informado para o item X não existe` / `não está disponível`.

            - `Erro ao selecionar serial IDSku:X` / `Erro ao alterar quantidade IDSku:X`.

            - `Nota Fiscal não emitida` — gate final quando NF não saiu e o estado não está na lista de declaração de
            transporte.

            Além disso, propaga erros do processo de retaguarda de NF-e e do `skuMovementTransferPost`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '404':
          description: '`[NotFound] - Pedido não encontrado`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: orderFulfillmentPackingIDOrderDelete
      tags:
        - Packing
      summary: Cancela o pedido durante o packing
      description: >-
        Cancela o pedido (define `IDStatusOrder = 90`). Apesar do nome do endpoint, não é um "undo" do packing — é
        cancelamento real:


        - Libera reserva de estoque: nas movimentações do pedido, zera `BalanceChange` e `IDBatch`.

        - Cancela contas a receber do pedido: define `IDStatusAccountPayableReceivable = 4` (Cancelada) nos lançamentos
        vinculados.

        - Apaga fisicamente todos os volumes (`Packages`) do pedido.

        - Limpa vínculos: `PickingBasket = NULL`, `IDOrdersCarrierCollectionList = NULL`, `IDPickingList = NULL`.

        - Registra evento `IDEvent=19` (cancelamento) com o motivo em `Comments`.

        - Quando a parametrização **Endereço transferência cancelamento pedido packing** está configurada, dispara
        `skuMovementTransferPost` para mover cada item de estoque ao endereço de Devolução.


        O frontend faz autenticação dupla antes de chamar: primeiro `POST /user/{IDUser}/verify` (com
        `PrivilegeAllowOrderCancelPacking`) para obter o `TempAuthToken`, depois envia o motivo no body.
      parameters:
        - name: idorder
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do pedido (`IDOrder`).
        - name: Comments
          in: query
          required: false
          schema:
            type: string
          description: Motivo do cancelamento (registrado no histórico). Pode também vir no body como `Comments`.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                TempAuthToken:
                  type: string
                  description: >-
                    Token temporário (obrigatório) obtido via `POST /user/{id}/verify` com
                    `PrivilegeAllowOrderCancelPacking`.
                Comments:
                  type: string
                  description: Motivo do cancelamento. Mínimo 15 caracteres (validado pelo frontend).
        description: >-
          Sem corpo. Reverte o packing do pedido: apaga os volumes criados, descarta o rascunho do packing salvo e
          retorna o pedido para o status anterior dentro da picking-list.
      responses:
        '200':
          description: Sucesso. Retorna o literal `"sucesso"`.
        '400':
          description: >-
            Mensagens `[BadRequest]` típicas:

            - `Pedido não encontrado`.

            - `Desvincular nota fiscal antes de alterar status` — `IDStatusInvoice IN (2,3,4,5,7,8)` (Enviada, Emitida,
            Processando, Pendente Conciliação EPEC, Cancelada, Denegada).

            - `Pedido esta em romaneio X, retirar antes de mudar status`.

            - `Pedido já esta cancelado` — `IDStatusOrder IN (90, 100)`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /fulfillment/packing/picking-list/{idpickinglist}:
    get:
      operationId: orderFulfillmentPackingListGet
      tags:
        - Packing
      summary: Detalhe da picking-list pronto para packing
      description: >-
        Retorna os pedidos + itens da picking-list, com os SKUs detalhados (código de barras, endereço, peso, série,
        kit, imagem) para o operador conferir item a item. Cada pedido vem com o `Draft` salvo (último rascunho do
        packing daquele pedido) para o frontend restaurar o progresso.


        Filtra apenas pedidos da empresa corrente e exclui itens cujo SKU é embalagem (`Package = 1`).


        Quando a parametrização Ignorar itens de serviço no picking (IgnoreServiceItemsOnPicking) está habilitada, os
        itens de SKU do tipo Serviço são omitidos da lista de itens a conferir.
      parameters:
        - name: idpickinglist
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da picking-list (`IDPickingList`).
      responses:
        '200':
          description: Array de pedidos da picking-list (vazio quando nada encontrado).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PackingPickingListOrder'
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `Precisa enviar o código da picking list` — `idpickinglist` ausente ou literal `"null"`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /fulfillment/packing/picking-list/{idpickinglist}/merge:
    post:
      operationId: orderFulfillmentPickingListMerge
      tags:
        - Packing
      summary: Mescla picking-lists Pendentes (origem → destino)
      description: >-
        Move todos os pedidos da picking-list **origem** (path param) para a **destino** (`IDPickingList` no body) e
        remove a origem.


        ⚠️ **Atenção ao URL**: a rota começa com `/fulfillment/packing/` (não `/picking/`) — mantido por compatibilidade
        histórica. É o mesmo endpoint da tag **Packing** (`orderFulfillmentPickingListMerge`).


        **Restrições** (ambas validadas):

        - Origem em status `1` (Pendente).

        - Destino em status `1` (Pendente).

        - Origem e destino na mesma empresa.


        **Efeitos**:

        - Reatribui todos os pedidos da origem para o destino (o `IDPickingList` de cada pedido passa a apontar para o
        destino).

        - Reatribui também os movimentos de estoque desses pedidos ao destino, de modo que os agregados do destino
        (`QtyOrder`, `ItemsQuantity`, `SkuQuantity`) passem a refletir o conteúdo combinado das duas listas.

        - Remove a picking-list de origem.

        - Não recalcula a prioridade (`PickingListPriority`) do destino.


        Retorna o item de lista do destino (mesma estrutura de `GET /fulfillment/picking/picking-list`).
      parameters:
        - name: idpickinglist
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da picking-list (`IDPickingList`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PickingListMergePayload'
        description: >-
          Mescla a picking-list origem (path) em uma picking-list destino (`IDPickingList`). Ambas precisam estar
          **pendentes** (status 1). Pedidos da origem são reatribuídos ao destino e a origem é apagada.
      responses:
        '200':
          description: >-
            Item de lista da picking-list destino atualizada, com os agregados (`QtyOrder`, `ItemsQuantity`,
            `SkuQuantity`) já consolidados com os pedidos e movimentos migrados da origem.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PickingListListItem'
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `Picking List não existe` — origem.
            - `Status picking list não permite mesclar` — origem fora de status `1`.
            - `Picking list destino não existe`.
            - `Status picking list destino não permite mesclar` — destino fora de status `1`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /fulfillment/picking:
    post:
      operationId: orderFulfillmentPickingPost
      tags:
        - Picking
      summary: Gera picking-list(s) a partir de pedidos
      description: >-
        Corrigir o rótulo do status 20 no bloco de validação (IDStatusOrder ∈ {1, 4, 20, 93} = Fechado, Finalizado
        picking, Em separação [não 'Em tratativa interna'], Em Produção) e acrescentar que, para listas colméia
        (IDTypePickingList=4) com itens em mais de um grupo de endereço, o sistema cria uma lista pai e uma lista filha
        por grupo de endereço (os movimentos de estoque são atribuídos às filhas).
      parameters:
        - name: IDTypePickingList
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 3
              - 4
          description: 'Tipo de picking-list: `1` Picking, `2` Picking & Packing, `3` Monopedido, `4` Colméia.'
        - name: RecordUserCreatedStartPicking
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Colaborador a ser atribuído como separador.
        - name: PickingListPriority
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 10
          description: Prioridade fixa. Quando ausente, o sistema aplica a lógica baseada em `PickingListConfiguration`.
        - name: IDPickingListConfiguration
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Configuração que disparou a geração — usada com `OrderQtyLimit` para reuso de listas pendentes.
        - name: OrderQtyLimit
          in: query
          required: false
          schema:
            type: integer
          description: >-
            Limite máximo de pedidos por picking-list. Combinado com `IDPickingListConfiguration` +
            `PickingListPriority` para tentar reusar uma lista pendente do mesmo `LocationGroup`.
        - name: bypasssvalidation
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` pula a validação de status do pedido e a unicidade de CD. Use apenas em fluxos automatizados confiáveis.'
        - name: OnlyValidate
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` retorna `{HasBalance, AvailableResupply}` sem criar a picking-list. Usado pelo frontend para preview.'
        - name: debug
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` ecoa respostas internas para troubleshooting.'
        - name: OriginalPickingListPriority
          in: query
          required: false
          schema:
            type: integer
          description: >-
            Prioridade original registrada junto da picking-list; usada também no cálculo de prioridade de
            ressuprimento.
        - name: IgnorePickingPreferenceByAllowResupplyLocation
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: >-
            1 ignora a preferência de coletar em endereços que permitem ressuprimento ao alocar o saldo. Quando ausente,
            herda o valor da configuração de picking aplicável.
        - name: PreferLocationMoreQuantity
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: >-
            1 prefere o endereço com maior quantidade disponível ao alocar o saldo. Quando ausente, herda o valor da
            configuração de picking aplicável.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PickingPostPayload'
        description: >-
          Array de `IDOrder` a serem agrupados em uma ou mais picking-lists. Pedidos são agrupados pela **combinação de
          endereços de coleta** (`IDStockKeepingUnitLocationGroup`); cada combinação distinta vira uma picking-list.
          Apoie-se em querystrings (`OnlyValidate=1`, `IDPickingListConfiguration`, `IDTypePickingList`, etc.) para
          controlar o comportamento — detalhes na descrição da operação.
      responses:
        '200':
          description: >-
            Sucesso. Sem `OnlyValidate=1`, retorna `{ "IDPickingList": <último id>, "Message": "Lista de picking gerada
            com sucesso" }` ou, em caso de pedidos sem estoque, `"Lista de picking gerada incompleta. N pedido(s) sem
            estoque"`. Com `OnlyValidate=1`, retorna `{ "HasBalance": 0|1, "AvailableResupply": 0|1 }`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  IDPickingList:
                    type: integer
                    format: int64
                    description: >-
                      Identificador da picking-list gerada. `0` quando o disparo foi modo `OnlyValidate=1` (validação)
                      ou quando nenhuma lista foi criada.
                  Message:
                    type: string
                    description: Mensagem descrevendo o resultado da operação.
                  HasBalance:
                    type: integer
                    description: >-
                      `1` quando há saldo suficiente para gerar a picking-list dos pedidos enviados; `0` quando há falta
                      total ou parcial.
                  AvailableResupply:
                    type: integer
                    description: >-
                      `1` quando há saldo em pulmão/blocado capaz de cobrir a falta via ressuprimento; `0` quando não
                      há.
        '400':
          description: |-
            Mensagens típicas:
            - `Necessário selecionar pedidos para gerar lista picking` — body vazio.
            - `Processo já esta rodando, favor aguardar` — duplicidade detectada.
            - `Tipo picking list não existe`.
            - `Pedido X não localizado`.
            - `Pedido X esta em status que não permite iniciar picking`.
            - `Pedidos selecionados estão em mais de um CD. A lista de separação só pode conter pedidos de um único CD.`
            - `Problema ao gerar picking list` — nenhum lista criada (ex.: todos sem batch alocável).
            - Propaga erros da integração com produção própria quando ela falha.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /fulfillment/picking/picking-list:
    get:
      operationId: orderFulfillmentPickingListList
      tags:
        - Picking
      summary: Lista picking-lists com filtros
      description: >-
        Lista as picking-lists da empresa (limite fixo de 5 000 por página), ordenadas por PickingListPriority e depois
        IDPickingList; quando nenhum filtro seletivo é enviado (IDPickingList, IDPickingListStatus, cesto, colaborador
        ou qualquer intervalo de datas/ShippingEstimateDate), o sistema restringe automaticamente aos últimos 30 dias
        por RecordTimestamp, e restrições de CD do usuário continuam sendo aplicadas.
      parameters:
        - name: IDPickingListStatus
          in: query
          required: false
          schema:
            type: string
          description: >-
            Lista CSV de status. Ex.: `1,2,6,7`. Valores: `1` Pendente, `2` Iniciado, `3` Coletado, `4` Packing
            Processando, `5` Packing Concluído, `6` Fim 1ª Conf., `7` Iniciado 2ª Conf.
        - name: IDPickingList
          in: query
          required: false
          schema:
            type: string
          description: Filtra por identificador da picking-list. Aceita CSV.
        - name: RecordUserCreatedStartPicking
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pelo colaborador atribuído.
        - name: PickingListBasketExternalId
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo código externo do cesto (basket) associado.
        - name: IDStockKeepingUnitDistributionCenter
          in: query
          required: false
          schema:
            type: string
          description: CDs (CSV). Submetido à ACL de CD do usuário.
        - name: RecordTimestampFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data inicial do intervalo de criação.
        - name: RecordTimestampTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data final do intervalo de criação (apenda `23:59:59`).
        - name: RecordTimestampStartPickingFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Intervalo de início do picking.
        - name: RecordTimestampStartPickingTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Fim do intervalo de data/hora de início da separação no filtro.
        - name: RecordTimestampFinishedPickingFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Intervalo de fim do picking.
        - name: RecordTimestampFinishedPickingTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Fim do intervalo de data/hora de conclusão da separação no filtro.
        - name: RecordTimestampStartPackingFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Intervalo de início do packing.
        - name: RecordTimestampStartPackingTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Fim do intervalo de data/hora de início da embalagem no filtro.
        - name: RecordTimestampEndFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Intervalo de fim do packing.
        - name: RecordTimestampEndTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Fim do intervalo de data/hora de término no filtro (formato `YYYY-MM-DDTHH:MM:SS`).
        - name: ShippingEstimateDateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Intervalo de data prevista de entrega (mín. dos pedidos da lista).
        - name: ShippingEstimateDateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Fim do intervalo da data de previsão de envio no filtro (formato `YYYY-MM-DD`).
        - name: Page
          in: query
          required: false
          schema:
            type: integer
          description: Página da listagem; o deslocamento aplicado é Page × 5000. Ausente = primeira página (deslocamento 0).
      responses:
        '200':
          description: Array de picking-lists (no máximo 5 000).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PickingListListItem'
  /fulfillment/picking/picking-list/{idpickinglist}:
    get:
      operationId: orderFulfillmentPickingListGet
      tags:
        - Picking
      summary: Detalhe da picking-list com rota de coleta otimizada
      description: >-
        Retorna as linhas de coleta da picking-list. Cada linha agrupa `IDSku × IDOrder × IDBatch` (modo padrão) ou
        `IDSku × Address` (modo agrupado, `?Grouped=1`).


        **Ordenação serpentina**: quando todas as linhas têm `Floor`, o sistema aplica uma rota otimizada:

        - `Floor` decrescente (andares superiores primeiro).

        - `Street` ascendente.

        - `Module` ascendente em ruas ímpares; descendente em ruas pares (a menos que
        `ConsiderEndOfStreetBeginningOfAnother=1`).

        - `LocationSide`: rua ímpar começa pelo lado direito; rua par pelo lado esquerdo.

        - `Column` monotônico com a direção; `Level` ascendente.

        Quando alguma linha não tem `Floor`, cai num sort alfabético natural por `Address`.


        **Modo Rascunho** (`?Draft=1`): devolve o rascunho salvo (TTL 4 dias) em vez de consultar o banco. Usado pelo
        aplicativo WMS para recuperar progresso interrompido.


        Quando a parametrização Ignorar itens de serviço no picking (IgnoreServiceItemsOnPicking) está habilitada, as
        linhas de SKU do tipo Serviço são omitidas da folha de coleta.
      parameters:
        - name: idpickinglist
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da picking-list (`IDPickingList`).
        - name: Grouped
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: >-
            `1` agrupa por `IDSku × Address` (folha consolidada). Sem agrupamento (default), agrupa por `IDSku × IDOrder
            × IDBatch`.
        - name: Draft
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` retorna o rascunho salvo em vez de consultar o banco. Sem efeito quando não há rascunho.'
      responses:
        '200':
          description: Array de linhas de coleta.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PickingListMovementItem'
    put:
      operationId: orderFulfillmentPickingListPut
      tags:
        - Picking
      summary: Atualiza colaborador, tipo, prioridade ou move status (4/6/7)
      description: >-
        Incluir Checked entre os campos aceitos: pelo menos um de RecordUserCreatedStartPicking, IDTypePickingList,
        PickingListPriority, IDPickingListStatus ou Checked precisa ser informado. Checked marca a conferência da
        picking-list.
      parameters:
        - name: idpickinglist
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da picking-list (`IDPickingList`).
        - name: Draft
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` apenas grava o body como rascunho temporário (TTL 4 dias), sem persistir.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PickingListPutPayload'
        description: >-
          Atualização parcial da picking-list. Pelo menos um dos campos (`RecordUserCreatedStartPicking`,
          `IDTypePickingList`, `PickingListPriority`, `IDPickingListStatus`) precisa ser enviado. `IDPickingListStatus`
          só aceita 4, 6 ou 7 — para iniciar (`1→2`) ou coletar (`2→3`) use os endpoints `/start` e `/finish`. Com
          `?Draft=1` o body é gravado como rascunho temporário (TTL 4 dias) sem tocar o banco.
      responses:
        '200':
          description: >-
            Sucesso. Sem `Draft`: retorna o item de lista atualizado (single-element array via
            `orderFulfillmentPickingListList`). Com `Draft`: literal `"sucesso"`.
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/PickingListListItem'
                  - type: string
                    example: sucesso
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `Picking-list não existe`.
            - `Status da Picking-list não permite atribuir colaborador` — status atual fora de `{1, 2, 3, 4, 6, 7}`.
            - `Colaborador não existe`.
            - `Colaborador não possui função de separador de pedido`.
            - `Tipo de picking list não existe`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /fulfillment/picking/picking-list/{idpickinglist}/start:
    post:
      operationId: orderFulfillmentPickingListStart
      tags:
        - Picking
      summary: Inicia a coleta (status 1 → 2)
      description: >-
        Acrescentar que, em listas do tipo colméia (IDTypePickingList=4 com lista pai), os pedidos podem estar em
        IDStatusOrder 2, 3 ou 4 (não apenas 3 Pré picking-list) para iniciar a coleta.
      parameters:
        - name: idpickinglist
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da picking-list (`IDPickingList`).
        - name: NoInvoke
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: >-
            `1` retorna apenas `"sucesso"` sem invocar `orderFulfillmentPickingListGet`. Reduz overhead em fluxos
            automatizados.
      responses:
        '200':
          description: Detalhe da picking-list iniciada (linhas de coleta) ou literal `"sucesso"`.
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/PickingListMovementItem'
                  - type: string
                    example: sucesso
        '400':
          description: >-
            Mensagens `[BadRequest]`:

            - `Picking List não existe`.

            - `Essa lista esta vinculada a outro colaborador` — atribuída a outro usuário.

            - `Você precisa finalizar a lista X antes de iniciar uma nova` — regra de uma lista iniciada por
            colaborador.

            - `Pedido (s) X, Y, Z com status errado` — algum pedido fora de status `3` (Pré-picking).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /fulfillment/picking/picking-list/{idpickinglist}/finish:
    post:
      operationId: orderFulfillmentPickingListFinish
      tags:
        - Picking
      summary: Finaliza a coleta (status 2/6/7 → 3)
      description: >-
        Acrescentar que, em listas do tipo colméia (IDTypePickingList=4 com lista pai), o status 3 (Pré picking-list)
        também é aceito na entrada — conjunto {2, 3, 4, 10, 24} — além do conjunto {2, 4, 10, 24} das listas comuns.
      parameters:
        - name: idpickinglist
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da picking-list (`IDPickingList`).
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PickingListFinishPayload'
        description: >-
          Finaliza a coleta da picking-list. Body é opcional: quando enviado como array, cada entrada informa, para um
          pedido da lista, os códigos externos (`PickingListBasketExternalIdList`) dos cestos usados — o sistema
          registra essas vinculações em `PickingListBasket`. Quando vazio ou omitido, só atualiza status e timestamps da
          picking-list.
      responses:
        '200':
          description: Detalhe da picking-list finalizada (linhas de coleta atualizadas).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PickingListMovementItem'
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `Picking list não localizada`.
            - `Pedido (s) X, Y, Z com status errado` — algum pedido fora de `{2, 4, 10, 24}`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /fulfillment/picking/picking-list/{idpickinglist}/order/{idorder}:
    delete:
      operationId: orderFulfillmentPickingListOrderDelete
      tags:
        - Picking
      summary: Remove pedido da picking-list
      description: >-
        Remove o pedido da picking-list, do cesto e do romaneio simultaneamente. **O `{idpickinglist}` no path é
        ignorado** — o sistema resolve a picking-list via `IDPickingList`.


        **Validação**: `IDStatusOrder ≤ 5` (Aberto, Fechado, Iniciado picking, Pré-picking, Finalizado picking ou
        Segurar pedido). Status fora desse range falham com mensagem misleading `"Pedido não esta no status Segurar
        Pedido"`.


        **Transição automática de status** conforme estado atual + presença de não conformidade no pedido:


        | Status atual | Tem NC? | Novo status | `IDEvent` |

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

        | `1` (Fechado) | sim | `10` (Picking NC) | `29` |

        | `2` (Iniciado picking) | sim | `10` (Picking NC) | `29` |

        | `3` (Pré-picking) | sim | `10` (Picking NC) | `29` |

        | `4` (Finalizado picking) | sim | `14` (Packing NC) | `29` |

        | `5` (Segurar pedido) | — | `13` (Tratativa) | `30` |

        | `1–4` | não | `1` (Fechado) | `30` |


        **Efeitos colaterais**:

        - No pedido: novo `IDStatusOrder` conforme tabela, `IDPickingList = NULL`, `PickingBasket = NULL`,
        `IDOrdersCarrierCollectionList = NULL`.

        - Se a picking-list ficar sem pedidos, é removida.

        - Se o romaneio do pedido ficar sem pedidos, é removido.

        - Insere `OrderEvents` com `IDEvent` conforme tabela acima.
      parameters:
        - name: idpickinglist
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da picking-list (`IDPickingList`).
        - name: idorder
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do pedido (`IDOrder`).
      responses:
        '200':
          description: Sucesso. Retorna o literal `"sucesso"`.
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `Pedido não existe`.
            - `Pedido não esta no status Segurar Pedido` — mensagem na verdade significa que `IDStatusOrder > 5`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /fulfillment/picking/picking-list/{idpickinglist}/order/{idorder}/sku/{idskumovement}:
    put:
      operationId: orderFulfillmentSkuNonconformityPut
      tags:
        - Picking
      summary: Registra inconformidade no item da picking
      description: >-
        Marca um movimento de estoque como em inconformidade (falta, vencido ou avariado). Acionado pelo aplicativo WMS
        quando o operador, no chão do CD, encontra um problema no item.


        ⚠️ **`{idpickinglist}` no path é ignorado** — o sistema resolve via `IDSkuMovement`.


        **Validação**: `IDStatusOrder` do pedido não pode ser `7` (Expedido) nem `8` (Entregue).


        **Sem transferência automática** (`TransferIfPossible != 1` ou sem parâmetro de armazém): apenas marca o
        movimento com `IDTypeFulfillmentNonconformity` e `QuantityNonconformity`. Insere `OrderEvents` `IDEvent=28`. Sem
        mudança de status nem de batch.


        **Com transferência automática** (`TransferIfPossible=1` + parâmetro
        `AutomaticTransferNonConformityInPicking{Missing|BestBefore|Damage}Warehouse` setado para o tipo):

        1. Se `QuantityNonconformity < Quantity` do movimento, **divide o movimento em dois** — um com a quantidade ok,
        outro com a quantidade inconforme; todos os totais fiscais são escalonados proporcionalmente.

        2. Marca o movimento NC com `IDBatch = NULL` e os campos NC.

        3. Transfere a quantidade NC para o armazém configurado.

        4. Tenta realocar batch para o pedido.

        5. Conforme o resultado:
           - Tem saldo em pulmão/blocado ≥ `QuantityNonconformity` → pedido vai para `IDStatusOrder = 10` (Picking NC); movimento marca `IDTypeFulfillmentNonconformity = 6` (Ressuprimento).
           - Não tem saldo lugar nenhum → pedido vai para `IDStatusOrder = 10`; movimento mantém o batch novo se houver.
           - Realocação bem-sucedida → limpa `QuantityNonconformity` e `IDTypeFulfillmentNonconformity` (divergência "resolvida").

        **Parâmetros consultados**: `AutomaticTransferNonConformityInPickingMissingWarehouse` (tipo 5 Falta),
        `AutomaticTransferNonConformityInPickingBestBeforeWarehouse` (tipo 2 Vencido),
        `AutomaticTransferNonConformityInPickingDamageWarehouse` (tipo 1 Avariado).


        **Resposta**: por padrão retorna o pedido. Com `?ReturnPickingList=1`, retorna a picking-list.
      parameters:
        - name: idpickinglist
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da picking-list (`IDPickingList`).
        - name: idorder
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do pedido (`IDOrder`).
        - name: idskumovement
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do movimento de estoque (`IDSkuMovement`) que será marcado em inconformidade.
        - name: TransferIfPossible
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: >-
            `1` habilita a transferência automática do item NC para o armazém parametrizado. Requer parâmetro do tipo
            correspondente preenchido.
        - name: ReturnPickingList
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` retorna o detalhe da picking-list. Sem este flag, retorna o detalhe do pedido (via `OrderGet`).'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PickingNonconformityPayload'
        description: >-
          Aponta inconformidade num movimento de coleta (item faltou, está vencido ou avariado).
          `IDTypeFulfillmentNonconformity` define a natureza do problema (`1` Avariado, `2` Vencido, `5` Falta, `6`
          Ressuprimento — atribuído pelo próprio sistema quando há saldo no pulmão). Quando `QuantityNonconformity` é
          menor que a quantidade total e o cliente envia `TransferIfPossible=1` na query, o movimento é dividido em dois
          (um ok, um inconforme).
      responses:
        '200':
          description: Detalhe do pedido ou da picking-list (conforme `ReturnPickingList`).
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    description: Resposta do `OrderGet`.
                  - type: array
                    items:
                      $ref: '#/components/schemas/PickingListMovementItem'
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `Pedido não existe`.
            - `O status atual não permite atualizar` — pedido em status `7` ou `8`.
            Além disso, propaga erros da transferência de estoque e da realocação de batch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /invoice:
    get:
      operationId: companyInvoiceList
      tags:
        - NF-e / NFC-e
      summary: Lista NFs (NF-e modelos 55/65)
      description: >-
        Lista as NFs (`NfCompany`) emitidas pelas empresas do grupo da conta autenticada (`IDCompany = company`), com
        pedido (`Orders`), faturador (`Company`), status (`TypeStatusInvoice`), tipo de operação (`NfTpNf`), tipo de
        emissão (`NfTpEmis`), finalidade (`NfFin`), modelo (`NfModNf`) e processo SEFAZ (`NfProcessCode`) já resolvidos.
        Paginação fixa em **5000 registros por página** (`Page=N` → offset `N*5000`).


        **Modo "com pedidos pendentes"** — quando `IDStatusInvoice` contém `0` (Pendente), o resultado inclui também os
        pedidos que ainda **não têm NF emitida** como entradas adicionais com `IDNfCompany=NULL`, `NfeNumber=NULL`,
        `NfeSerie=NULL` e `StatusInvoice="Pendente"`. Permite que a tela mostre tanto NFs já emitidas quanto pedidos
        aguardando emissão.


        **Busca rápida `Search`** — casa contra `NfeNumber`, `IDOrder` (apenas valores ≥ `IDOrderThreeMonthsAgo` ),
        `Order` e `NfeChaveAcesso` (apenas quando a chave tem mais de 40 dígitos).
      parameters:
        - name: IDNfCompany
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo id da NF.
        - name: IDOrder
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo id interno do pedido.
        - name: Order
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo número do pedido.
        - name: NfeNumber
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo número exato da NF.
        - name: NfeNumberFrom
          in: query
          required: false
          schema:
            type: string
          description: Início da faixa de número de NF (apenas dígitos).
        - name: NfeNumberTo
          in: query
          required: false
          schema:
            type: string
          description: Fim da faixa de número de NF.
        - name: NfeSerie
          in: query
          required: false
          schema:
            type: integer
          description: Série da NF.
        - name: IDStatusInvoice
          in: query
          required: false
          schema:
            type: string
          description: >-
            Status da NF (`IDStatusInvoice`). Aceita CSV. **`0` (Pendente) na lista ativa o modo "pedidos pendentes"**
            descrito na descrição do endpoint.
        - name: IDCompanyInvoice
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo faturador (id da empresa).
        - name: CompanyCpfCnpjInvoice
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo CNPJ do faturador (apenas dígitos).
        - name: NfeChaveAcesso
          in: query
          required: false
          schema:
            type: string
          description: Chave de acesso da NF (44 dígitos).
        - name: NfetpEmis
          in: query
          required: false
          schema:
            type: integer
          description: Tipo de emissão (`NfetpEmis` — normal, contingência, etc.).
        - name: FinNFe
          in: query
          required: false
          schema:
            type: integer
          description: Finalidade da NFe (`FinNFe` — normal, complementar, ajuste, devolução).
        - name: NfTpNf
          in: query
          required: false
          schema:
            type: integer
          description: Tipo da NF (entrada/saída, `NfTpNf`).
        - name: NfedhEmiFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data inicial de emissão da NF.
        - name: NfedhEmiTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data final de emissão da NF (concatenada com ` 23:59:59`).
        - name: ConsumerNameCorporateName
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo nome/razão social do cliente do pedido.
        - name: ConsumerCpfCnpj
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo CPF/CNPJ do cliente.
        - name: ShippingState
          in: query
          required: false
          schema:
            type: string
          description: Filtra pela UF de destino.
        - name: NoOrder
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` filtra apenas NFs sem pedido vinculado (numerações reservadas via `POST /invoice`).'
        - name: Search
          in: query
          required: false
          schema:
            type: string
          description: >-
            Busca rápida — aplica `OR` em `NfeNumber`, `IDOrder`, `Order` e `NfeChaveAcesso` (esta última só quando ≥ 40
            dígitos). Limita pedidos a `IDOrder ≥ IDOrderThreeMonthsAgo`.
        - name: Page
          in: query
          required: false
          schema:
            type: integer
          description: Página (offset = `Page * 5000`).
      responses:
        '200':
          description: Lista combinada de NFs e (quando `IDStatusInvoice` inclui `0`) pedidos sem NF.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyInvoiceListItem'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: companyInvoicePost
      tags:
        - NF-e / NFC-e
      summary: Reserva/registra numeração de NF sem pedido
      description: >-
        Cria um registro `NfCompany` apenas com `IDCompanyInvoice`, `NfeSerie`, `NfeNumber` e `NfeModelo` (sem
        `IDOrder`). Usado pelo botão **Gerar Numeração NF** da tela — quando a empresa precisa **registrar** um número
        manualmente (ex.: número emitido fora do sistema que precisa entrar para manter a sequência) ou **reservar** um
        número futuro. Valida que o `IDCompanyInvoice` pertence ao grupo da empresa (`CompanyMain`) e que a tupla
        (`IDCompanyInvoice`, `NfeSerie`, `NfeNumber`, `NfeModelo`) ainda não existe.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyInvoiceCreate'
        description: >-
          Dados da numeração de NF a registrar. `IDCompanyInvoice`, `NfeSerie` e `NfeNumber` são obrigatórios;
          `NfeModelo` default `55` (use `65` para NFCe). A tupla (`IDCompanyInvoice`, `NfeSerie`, `NfeNumber`,
          `NfeModelo`) precisa ser inédita — não há reaproveitamento de número/série/modelo na mesma empresa emissora.
      responses:
        '200':
          description: 'Numeração registrada. Corpo: string `"sucesso"`.'
          content:
            application/json:
              schema:
                type: string
                example: sucesso
        '400':
          description: >-
            `[BadRequest] - Já existe essa NF e Serie para a empresa emissora`; `[BadRequest] - Erro ao adicionar
            numeração`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /invoice/{idnfcompany}/disable:
    post:
      operationId: invoiceDisablePost
      tags:
        - NF-e / NFC-e
      summary: Inutiliza NF
      description: >-
        Inutiliza na SEFAZ uma NF que **não chegou a ser emitida** (número "queimado" / sequência sem uso), marcando-a
        como `Inutilizada` no status fiscal. Usado pelo modal **Inutilizar NF** da tela. Body coleta justificativa
        (mínimo 15 caracteres pela regra da SEFAZ).
      parameters:
        - name: idnfcompany
          in: path
          required: true
          schema:
            type: integer
          description: Id da NF (`IDNfCompany`) a inutilizar.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                Comments:
                  type: string
                  minLength: 15
                  description: Justificativa/observação da inutilização da NF.
        description: >-
          Justificativa da inutilização. O sistema lê `Comments` (não `Justification`) e o envia como `xJust` ao serviço
          de inutilização da SEFAZ — a regra da SEFAZ exige texto entre 15 e 255 caracteres.
      responses:
        '200':
          description: NF inutilizada.
        '400':
          description: Erros propagados pela SEFAZ ou validação interna do processo de retaguarda. Shape não confirmado.
        '500':
          description: Erro interno.
  /invoice-service:
    get:
      operationId: invoiceServiceList
      tags:
        - NFS-e
      summary: Lista NFS-e (ServiceOrder)
      description: >-
        Lista as NFS-e (`ServiceOrder`) cadastradas pela empresa autenticada, com `StatusInvoice` (de
        `TypeStatusInvoice`), `CityName`/`State` (de `IBGECityCode`), `ServiceDescription` (de `NfsServiceCode` quando
        cadastrado para o município), faturador (`IDCompanyInvoice` + `AccountNameInvoice` +
        `CompanyNameCorporateNameInvoice`), `NfsValue` computado como `NfsServiceQuantity * NfsServiceUnitValue` e
        `ValuePaid` (soma de `Value` em `AccountsPayableReceivable` vinculadas). Paginação fixa em **1000 registros por
        página** (`Page=N` → offset `N*1000`).


        Filtros são opcionais e combinados com `AND`. Janelas de data usam `BETWEEN` com `' 23:59:59'` apendado ao
        limite superior.
      parameters:
        - name: IDServiceOrder
          in: query
          required: false
          schema:
            type: integer
          description: Id interno da NFS-e.
        - name: IDConsumer
          in: query
          required: false
          schema:
            type: integer
          description: Id do cliente vinculado (`IDConsumer`).
        - name: ConsumerNameCorporateName
          in: query
          required: false
          schema:
            type: string
          description: Busca parcial (`LIKE`) por nome/razão social do cliente.
        - name: ConsumerCpfCnpj
          in: query
          required: false
          schema:
            type: string
          description: Busca parcial (`LIKE`) por CPF/CNPJ do cliente. Apenas dígitos.
        - name: NfsNumber
          in: query
          required: false
          schema:
            type: string
          description: Número da NFS-e (apenas dígitos).
        - name: IDStatusInvoice
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo status da NF (`IDStatusInvoice`).
        - name: IDCompanyInvoice
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo faturador (id da empresa).
        - name: DateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data inicial de criação (`RecordTimestamp ≥`).
        - name: DateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data final de criação (com `' 23:59:59'` apendado).
        - name: NfsDateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data inicial de emissão (`NfsDate`).
        - name: NfsDateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data final de emissão.
        - name: Page
          in: query
          required: false
          schema:
            type: integer
          description: Página (offset = `Page * 1000`).
      responses:
        '200':
          description: Lista de NFS-e.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ServiceInvoiceListItem'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: invoiceServicePost
      tags:
        - NFS-e
      summary: Cria NFS-e (modal Nova NF de Serviço)
      description: >-
        Cria uma NFS-e em status **Pendente** (`IDStatusInvoice=0`). Pré-condições verificadas pelo sistema: empresa
        precisa ter `Inscrição Municipal` cadastrada (`CompanyCityInscription`); endereço completo cadastrado
        (`CompanyAddressIbgeCityCode`); o município emite NFS-e (`NfseIssue = 1`). Quando `IDCompanyInvoice` informado,
        valida que pertence à empresa principal (`CompanyMain`).


        Após criar a NFS-e, **não emite** automaticamente — a emissão é uma ação subsequente (`POST
        /invoice-service/{idserviceorder}/invoice`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceInvoiceCreate'
        description: >-
          Dados da NFS-e a cadastrar (status nasce **Pendente**, `IDStatusInvoice=0`). `IDConsumer`, `NfsServiceCode`,
          `NfsServiceQuantity` e `NfsServiceUnitValue` são obrigatórios. `IDCompanyInvoice` (faturador) precisa
          pertencer ao grupo (`CompanyMain`) da empresa autenticada; quando omitido, usa a própria empresa. As retenções
          (`NfsIRRFRetentionValue`, `NfsPISRetentionValue`, `NfsCOFINSRetentionValue`, `NfsCSLLRetentionValue`) ficam
          `null` quando não informadas e os percentuais cadastrados na empresa zeram para o valor total — caso
          contrário, o sistema calcula automaticamente a partir do percentual configurado, gravando `0` quando o cálculo
          resulta em valor abaixo de R$ 10,00.
      responses:
        '200':
          description: NFS-e criada. Devolve o detalhe (formato similar ao GET).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceInvoiceListItem'
        '400':
          description: >-
            `[BadRequest] - Faturador não existe`; `[BadRequest] - Obrigatório preencher a inscrição municipal no
            cadastro da empresa`; `[BadRequest] - Obrigatório preencher o endereço completo no cadastro da empresa`;
            `[BadRequest] - Cliente não existe`; `[BadRequest] - Município não emite NFS-e`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /invoice-service/{idserviceorder}:
    delete:
      operationId: invoiceServiceDelete
      tags:
        - NFS-e
      summary: Exclui NFS-e (ação Deletar da linha)
      description: >-
        Exclui fisicamente uma NFS-e. **Bloqueado** quando o status da NF é diferente de **Pendente** ou **Erro**
        (`IDStatusInvoice > 1` — Enviada/Emitida/Cancelada não podem ser excluídas) ou quando há contas a receber
        **Pagas** ou **Parcialmente Pagas** vinculadas (`IDStatusAccountPayableReceivable IN (2,3)`). Quando liberada,
        remove em cascata `ServiceOrderLog` e `AccountsPayableReceivable` vinculadas, desvincula `ConsumerBankSlip`
        (`IDServiceOrder = NULL`) e deleta o `ServiceOrder`.
      parameters:
        - name: idserviceorder
          in: path
          required: true
          schema:
            type: integer
          description: Id da NFS-e.
      responses:
        '200':
          description: 'NFS-e excluída. Corpo: string `"Sucesso"`.'
          content:
            application/json:
              schema:
                type: string
                example: Sucesso
        '400':
          description: >-
            `[BadRequest] - Status nota fiscal não excluir NFSe`; `[BadRequest] - Nota fiscal já tem pagamento baixado e
            não pode ser excluido`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '404':
          description: '`[NotFound] - NFSe não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    get:
      operationId: invoiceServiceGet
      summary: Detalha uma NFS-e
      description: >-
        Retorna os dados completos de uma NFS-e (cabeçalho fiscal, cliente, endereço, retenções, serviço, status), com o
        histórico de eventos (`Events`), as contas a receber vinculadas (`Payments`) e URLs assinadas para baixar o XML
        e a DANFSE em PDF.
      tags:
        - NFS-e
      parameters:
        - name: idserviceorder
          in: path
          required: true
          schema:
            type: integer
          description: Identificador da NFS-e.
      responses:
        '200':
          description: NFS-e encontrada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InvoiceServiceDetail'
    put:
      operationId: invoiceServicePut
      summary: Atualiza uma NFS-e
      description: >-
        Atualiza os dados de uma NFS-e antes da emissão. A operação só é permitida enquanto o status estiver em Pendente
        ou Erro (`IDStatusInvoice <= 1`). Calcula automaticamente as retenções (IRRF, CSLL, PIS, COFINS) quando o valor
        da retenção é enviado como `null` e a empresa tem percentual configurado, copia dados do cliente e do endereço
        escolhidos para a nota, e registra o histórico de alterações. Exige inscrição municipal e endereço completo
        cadastrados na empresa, e que o município emita NFS-e.
      tags:
        - NFS-e
      parameters:
        - name: idserviceorder
          in: path
          required: true
          schema:
            type: integer
          description: Identificador da NFS-e.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceServiceUpdateBody'
        description: >-
          Atualização parcial da NFS-e enquanto o status estiver em **Pendente** ou **Erro** (`IDStatusInvoice ≤ 1`).
          Apenas os campos enviados são alterados. `IDConsumer` e `IDAddress` aceitam `null` explícito para limpar os
          dados gravados na nota; quando preenchidos, o cliente/endereço é validado e os dados do cadastro são copiados
          para a nota. `IDCompanyInvoice` segue a regra de pertencer ao grupo. `NfsNBS` aceita CNPJ formatado (`.`
          removido automaticamente). `NfsCIndOp` e `NfsCClassTrib`, quando informados, são validados contra `NfsCIndOp`
          e `NfsCstIbsCbs` (campo `NFSe=1`).
      responses:
        '200':
          description: NFS-e atualizada. Retorna o detalhe completo (mesmo schema do `GET`).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InvoiceServiceDetail'
        '400':
          description: >-
            Validação falhou. Mensagens reais: `[BadRequest] - Status nota fiscal não permite edição`, `[BadRequest] -
            Obrigatório preencher a inscrição municipal no cadastro da empresa`, `[BadRequest] - Obrigatório preencher o
            endereço completo no cadastro da empresa`, `[BadRequest] - Município não possui integração de emissão de
            NFSe`, `[BadRequest] - Cliente não existe`, `[BadRequest] - Endereço não existe`, `[BadRequest] - Faturador
            não existe`, `[BadRequest] - Código serviço não existe`, `[BadRequest] - NBS não existe`, `[BadRequest] -
            Código Indicador de Operação não existe`, `[BadRequest] - Código de Classificação tributária não existe`.
        '404':
          description: 'NFS-e não encontrada: `[NotFound] - NFSe não existe`.'
  /invoice-service/{idserviceorder}/invoice:
    post:
      operationId: invoiceServiceInvoicePost
      tags:
        - NFS-e
      summary: Emite a NFS-e na prefeitura (Mais Ações)
      description: >-
        Dispara a emissão da NFS-e identificada por `idserviceorder`: conecta ao webservice da prefeitura, valida e
        devolve o número/protocolo da nota emitida. Mensagens de erro (validação local ou rejeição da prefeitura) são
        prefixadas com `[BadRequest]`.


        Valida que a NFS-e existe e pertence à empresa autenticada antes de emitir.
      parameters:
        - name: idserviceorder
          in: path
          required: true
          schema:
            type: integer
          description: Id da NFS-e a emitir.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: array
              items: {}
              description: Body ignorado — o sistema envia `[]` ao processo.
        description: >-
          Sem corpo de entrada significativo — o sistema valida que a NFS-e existe e pertence à empresa autenticada e
          dispara a emissão, conectando ao webservice da prefeitura. Aceita `application/json` vazio.
      responses:
        '200':
          description: >-
            Retorno do processo de retaguarda (geralmente o objeto da NFS-e atualizado com `NfsNumber`,
            `NfsVerificationCode`, `IDStatusInvoice`).
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                description: Resposta da emissão da NF de serviço. O formato varia por provedor municipal.
        '400':
          description: '`[BadRequest] - <mensagem retornada pelo processo>` (validação ou rejeição da prefeitura).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '404':
          description: '`[NotFound] - NFSe não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno / falha de comunicação com o processo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: invoiceServiceInvoiceDelete
      summary: Cancela uma NFS-e emitida
      description: >-
        Solicita o cancelamento de uma NFS-e já emitida junto à prefeitura. Grava o motivo do cancelamento
        (`NfsCancelDescription`) e consulta o canal fiscal que dispara o evento de cancelamento na prefeitura. Quando
        `RemovePayment=1`, as contas a receber vinculadas à nota também são removidas.
      tags:
        - NFS-e
      parameters:
        - name: idserviceorder
          in: path
          required: true
          schema:
            type: integer
          description: Identificador da NFS-e.
        - name: RemovePayment
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
            default: 0
          description: Quando `1`, remove também as contas a receber vinculadas à NFS-e.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                Comments:
                  type: string
                  description: 'Motivo do cancelamento. Default: `Cancelamento de nota fiscal`.'
        description: >-
          Opcional. Apenas `Comments` é lido — vira o motivo do cancelamento enviado no evento de cancelamento à
          prefeitura. Quando ausente, o sistema usa o texto default `"Cancelamento de nota fiscal"`.
      responses:
        '200':
          description: Cancelamento enviado à prefeitura.
          content:
            application/json:
              schema:
                type: string
                example: sucesso
        '400':
          description: Erro retornado pelo processo fiscal ou pela prefeitura. Prefixo `[BadRequest]`.
        '404':
          description: 'NFS-e não encontrada: `[NotFound] - NFSe não existe`.'
  /invoice-service/feed:
    get:
      operationId: invoiceServiceFeedList
      tags:
        - NFS-e
      summary: Lista NFSe recebidas dos fornecedores
      description: >-
        Lista paginada (500/página, offset `Page * 500`) das NFSe que a empresa recebeu de seus fornecedores. As notas
        são capturadas automaticamente — este endpoint apenas **lê** o feed já populado.


        **Multi-tenant**: token com `accountname[0] == "all"` dispensa filtro; caso contrário resolve pela
        `idcompanylist` do contexto.


        **Filtro fixo `Show = 1`**: notas soft-hidden não aparecem. Notas com `(CityCode, NfsServiceCode)` sem cadastro
        no catálogo de códigos de serviço (`NfsServiceCode`) são descartadas silenciosamente.
      parameters:
        - name: Page
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Página da paginação. `OFFSET = Page * 500`.
        - name: IDNfsEvents
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra por identificador da nota.
        - name: IDCompanyInvoice
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pelo faturador (filial).
        - name: NfeNumber
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo número da NFSe. Apenas dígitos. Match exato contra `NfsNumber`.
        - name: SupplierNameCorporateName
          in: query
          required: false
          schema:
            type: string
          description: '`LIKE %valor%` contra `NfsSupplierNameCorporateName`.'
        - name: SupplierCpfCnpj
          in: query
          required: false
          schema:
            type: string
          description: >-
            Filtra pelo CPF/CNPJ do fornecedor. ⚠️ **Quirk conhecido**: o filtro referencia internamente um campo
            (`SupplierCpfCnpj`) que não existe na origem dos dados (`NfsEvents` — o correto seria `NfsSupplierCpfCnpj`),
            então atualmente este parâmetro nunca retorna resultado.
        - name: DateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data inicial de emissão (`NfsDate ≥ DateFrom`).
        - name: DateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data final de emissão (`NfsDate ≤ DateTo 23:59:59`).
        - name: Tags
          in: query
          required: false
          schema:
            type: string
          description: Filtra notas que tenham essa tag em `Tag`.
      responses:
        '200':
          description: Array de NFSe ordenado por `NfsDate DESC` (máx. 500).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InvoiceServiceFeedItem'
  /invoice-service/feed/invoice-xml:
    get:
      operationId: nfseFeedXmlGet
      tags:
        - NFS-e
      summary: Download XML ou DANFSE PDF de uma NFSe do feed
      description: >-
        Baixa o arquivo da NFSe (XML ou PDF).


        **Autorização**: a empresa do token precisa coincidir com `AccountName` da nota (cadeia `NfsEvents → CompanyMain
        → Company`). Notas de outras empresas retornam erro.


        **Type=XML**: serve o `.xml` original com `Content-Disposition: attachment`. Conteúdo é desescapado (entities
        HTML substituídas).


        **Type=PDF**: renderiza a DANFSE. ADN tem PDF pré-gerado; outras prefeituras renderizam sob demanda.
      parameters:
        - name: File
          in: query
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da NFSe (`IDNfsEvents`). Apenas dígitos.
        - name: Type
          in: query
          required: true
          schema:
            type: string
            enum:
              - XML
              - PDF
          description: '`XML` baixa o XML original. `PDF` retorna a DANFSE renderizada.'
        - name: account
          in: query
          required: false
          schema:
            type: string
          description: Prefixo da conta. Fallback quando o contexto não resolve.
        - name: token
          in: query
          required: false
          schema:
            type: string
          description: Token de autenticação adicional gerado pelo `invoiceServiceFeedList`.
      responses:
        '200':
          description: Arquivo binário do XML (`application/xml`) ou PDF (`application/pdf`).
          content:
            application/xml:
              schema:
                type: string
                format: binary
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          description: |-
            Erros:
            - `Arquivo não encontrado (1)` — `IDNfsEvents` não pertence à empresa do token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /purchase:
    get:
      operationId: purchaseList
      tags:
        - Recebimento
      summary: Lista recebimentos com filtros
      description: >-
        Lista paginada (1 000/página) dos recebimentos da empresa. Aplica restrição por CDs vinculados ao usuário e —
        quando `AllowOnlyUserSupplierCategorySet=1` — restringe por categorias de fornecedor do usuário.
      parameters:
        - name: Page
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: Página da paginação. OFFSET = Page * 1000.
        - name: IDStatusPurchase
          in: query
          required: false
          schema:
            type: string
          description: >-
            Filtra pelo status do recebimento `IDStatusPurchase`. Aceita CSV (ex.: `0,3,4`). Valores: `0` Aberto, `1`
            Finalizado, `2` Cancelada, `3` Em conferência, `4` Conferência realizada, `5` Aguardando validação
            comercial, `6` Aguardando validação operacional, `7` Recebimento autorizado, `8` Recebimento recusado, `9`
            Finalização recebimento autorizada, `10` Aguardando finalização comercial, `11` Finalização recebimento
            recusada, `12` Aguardando finalização operacional.
        - name: IDPurchase
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pelo identificador da compra.
        - name: InvoiceNumber
          in: query
          required: false
          schema:
            type: string
          description: Número da NF. Aceita CSV.
        - name: chNFe
          in: query
          required: false
          schema:
            type: string
          description: Chave de acesso da NF-e (44 dígitos).
        - name: SupplierNameCorporateName
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo nome ou razão social do fornecedor (busca parcial).
        - name: DateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data de criação (RecordTimestamp).
        - name: DateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Fim do intervalo de datas no filtro (formato `YYYY-MM-DD`).
        - name: InvoiceDateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data de emissão da NF (dhEmi).
        - name: InvoiceDateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Fim do intervalo da data da nota fiscal no filtro (formato `YYYY-MM-DD`).
        - name: InvoiceFinishTimestampDateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data de finalização do recebimento.
        - name: InvoiceFinishTimestampDateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Fim do intervalo da data/hora de conclusão da nota fiscal no filtro.
        - name: IDStockKeepingUnitDistributionCenter
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pelo identificador do centro de distribuição do SKU.
        - name: IDCompanyInvoice
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pelo identificador da nota fiscal da empresa.
        - name: Search
          in: query
          required: false
          schema:
            type: string
          description: Busca livre por nome do fornecedor, número da NF, chave de acesso ou IDPurchase.
        - name: ReturnOrder
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` = só recebimentos de devolução (Reversa); `0` = só de fornecedor.'
        - name: SkuView
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` = expande os itens (modo card no frontend).'
        - name: IDOrder
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pelo identificador do pedido `IDOrder` vinculado ao recebimento.
        - name: Order
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo número do pedido `Order` vinculado ao recebimento.
        - name: ConsumerNameCorporateName
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo nome ou razão social do consumidor do pedido vinculado (busca parcial).
        - name: chNFeFrom
          in: query
          required: false
          schema:
            type: string
          description: >-
            Em recebimentos de devolução, filtra pela chave de acesso `chNFeFrom` da nota fiscal de origem (a venda que
            gerou a devolução).
        - name: NfeNumberFrom
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Em recebimentos de devolução, filtra pelo número `NfeNumberFrom` da nota fiscal de origem.
        - name: OrderFrom
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo pedido de origem `OrderFrom` associado ao pedido do recebimento.
        - name: StockKeepingUnitPurchaseScheduleStatus
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 3
              - 4
          description: >-
            Filtra pela situação do agendamento de recebimento: `1` Recebido (há check-in e janela definida), `2`
            Agendado (janela ainda não passou e sem check-in), `3` Atrasado (janela passou sem check-in), `4` Não
            agendado (sem agendamento amarrado).
        - name: StartTimeFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Início do intervalo do horário de agendamento `StartTime` (formato `YYYY-MM-DD`).
        - name: StartTimeTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Fim do intervalo do horário de agendamento `StartTime` (formato `YYYY-MM-DD`; o dia inteiro é considerado).
        - name: SinceRecordTimestamp
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: >-
            Retorna apenas recebimentos criados a partir desta data/hora `RecordTimestamp` (inclusive). Útil para
            sincronização incremental.
        - name: SinceDateLastRecordModification
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: >-
            Retorna apenas recebimentos com última modificação `DateLastRecordModification` a partir desta data/hora
            (inclusive). Útil para sincronização incremental.
      responses:
        '200':
          description: Array de recebimentos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PurchaseListItem'
    post:
      operationId: purchasePost
      tags:
        - Recebimento
      summary: Cria novo recebimento
      description: >-
        Cria um recebimento em status `0` (Aberto). Quando `IDBuyOrder` é informado, vincula o pedido de compra e ajusta
        seu status para `1` (Recebimento iniciado), além de marcar as contas a pagar do pedido com este `IDPurchase`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchasePostPayload'
        description: >-
          Dados do recebimento (compra) a cadastrar. Obrigatório `IDSupplier`. Opcionais: `IDOrder`, `Comments`,
          `IDBuyOrder` (pedido de compra associado), `IDCompanyInvoice` (faturador — quando diferente da empresa,
          precisa estar vinculado a ela) e `IDStockKeepingUnitDistributionCenter` (centro de distribuição que recebe a
          mercadoria).
      responses:
        '200':
          description: Detalhe do recebimento criado (resultado de `purchaseGet`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseDetail'
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `Empresa não existe`
            - `Fornecedor não existe`
            - `Faturador não existe`
            - `IDOrder não existe`
            - `Pedido de compra não existe`
            - `Centro de distribuição não existe`
            - `Empresa não tem centro de distribuição padrão`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /purchase/{idpurchase}:
    get:
      operationId: purchaseGet
      tags:
        - Recebimento
      summary: Detalhe do recebimento (com itens e pagamentos)
      description: >-
        Detalhe completo. Sem `?ItemsInvoice=1`, retorna o objeto com `Items`, `Payments` e — quando há pedido de compra
        vinculado — `ItemsBuyOrder` para conciliação. Com `?ItemsInvoice=1`, retorna apenas os produtos do XML importado
        (`StockKeepingUnitPurchaseXmlProduct`) com descrições de CST/CFOP já resolvidas.
      parameters:
        - name: idpurchase
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do recebimento (`IDPurchase`).
        - name: ItemsInvoice
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` retorna só os produtos do XML, não o detalhe do recebimento.'
      responses:
        '200':
          description: Detalhe do recebimento ou itens do XML (conforme `ItemsInvoice`). Retorna `[]` quando não encontra.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseDetail'
    put:
      operationId: purchasePut
      tags:
        - Recebimento
      summary: Atualiza recebimento (incluindo aprovações)
      description: >-
        Atualiza campos do recebimento. Campos do XML (`dhEmi`/`nNF`/`chNFe`/`natOp`/`NFeType`/`NFeFin`) só editáveis
        quando o XML não tem protocolo SEFAZ.


        **Aprovações** (`PurchaseCheckinApproved` / `PurchaseReceiptApproved`): transitionam status. Exigem privilégio
        Authorize correspondente.


        **Reabertura** (`IDStatusPurchase=0` de recebimento finalizado): só permitida se nenhum produto foi vendido OU
        `InvoiceFinishTimestamp` foi há menos de 8 dias (`TotalDays < 8`). Reverte movimentos de estoque para status
        pendente.


        **Frete** (`ValueShipping`): valor é rateado proporcionalmente ao `ValueCostTotal` em todos os movimentos do
        recebimento.
      parameters:
        - name: idpurchase
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do recebimento (`IDPurchase`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchasePutPayload'
        description: >-
          Campos do recebimento a atualizar — apenas os enviados são aplicados. Aceita `IDSupplier`, `IDOrder`,
          `Comments`, `IDStatusPurchase`, `ValueShipping`, `IDBuyOrder`, `CheckinTimestamp` (não pode ser maior que a
          data atual), `IDCompanyInvoice`, `PurchaseCheckinApproved`, `PurchaseReceiptApproved`,
          `IDStockKeepingUnitDistributionCenter` e os dados fiscais da nota (`dhEmi`, `nNF`, `chNFe`, `natOp`,
          `NFeType`, `NFeFin`).
      responses:
        '200':
          description: Detalhe atualizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseDetail'
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `Recebimento não existe`
            - `Status não existe`
            - `Usuário não tem permissão para aprovar recebimento`
            - `Fornecedor não existe`
            - `Pedido não existe` / `Pedido de compra não existe`
            - `Faturador não existe`
            - `Já existe o mesmo documento para este fornecedor no recebimento: <id>` (duplicidade de NF)
            - `Já existe a mesma chave de acesso no recebimento: <id>`
            - `Data de Recebimento não pode ser maior que data atual`
            - `Já houve venda de produtos desse recebimento e não pode ser aberto`
            - `Centro de distribuição do item é diferente do CD do recebimento`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: purchaseDelete
      tags:
        - Recebimento
      summary: Cancela o recebimento (status → 2)
      description: >-
        Soft-delete: marca o recebimento como **Cancelada** (status 2). Apaga movimentos de estoque, contas a pagar e
        XML importado. Só permitido em status `0` (Aberto). Bloqueado se existe conta a pagar com extrato bancário
        vinculado.
      parameters:
        - name: idpurchase
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do recebimento (`IDPurchase`).
      responses:
        '200':
          description: Sucesso.
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `Recebimento não existe`
            - `Status não permite atualização`
            - `Contas a pagar já foi quitado. Favor remover o pagamento`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /purchase/{idpurchase}/check/start:
    post:
      operationId: purchaseStartCheckPost
      tags:
        - Recebimento
      summary: Inicia a conferência (status → 3)
      description: >-
        Inicia a conferência do recebimento. Status atual precisa ser `0` (Aberto) ou `7` (Recebimento autorizado).
        Quando `PurchaseScheduleRequired=1` e não está aprovado, valida o agendamento (existência, data, janela de
        tolerância) e move o status para `StatusChangePurchase*` caso falhe.


        Sucesso: status → `3` (Em conferência), `CheckinTimestamp` registrado.
      parameters:
        - name: idpurchase
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do recebimento (`IDPurchase`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - CheckinTimestamp
              properties:
                CheckinTimestamp:
                  type: string
                  format: date-time
                  description: Data e hora em que a mercadoria chegou no CD.
        description: >-
          Início da conferência: `CheckinTimestamp` (obrigatório) é a data/hora em que a mercadoria chegou no CD.
          Precisa ser ≤ agora; quando o CD exige agendamento (`PurchaseScheduleRequired=1`), é comparada com a janela do
          agendamento + tolerância.
      responses:
        '200':
          description: Detalhe atualizado.
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `Obrigatório enviar a data de checkin`
            - `Data de Recebimento não pode ser maior que data atual`
            - `Recebimento esta no status X e não pode ser conferido`
            - `Agendamento obrigatório e recebimento não possui agendamento`
            - `Agendamento está para o dia X`
            - `Agendamento esta para ser iniciado X com tolerância de NH`
            - `Agendamento esta para ser finalizado X`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /purchase/{idpurchase}/check:
    get:
      operationId: purchaseCheckGet
      tags:
        - Recebimento
      summary: Retorna a conferência (comparativa com NF)
      description: >-
        Retorna o que foi conferido vs o que deveria ter (agrupado por SKU), com `Status` 1 (conferido OK) ou 0
        (faltando/divergente). Inclui URLs das fotos no S3 público (`Image/Inbound/<filename>`).


        **`?Draft=1`** retorna o rascunho de conferência salvo em `StockKeepingUnitPurchaseItemsCheckTemp` (usado pelo
        mobile para retomar).
      parameters:
        - name: idpurchase
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do recebimento (`IDPurchase`).
        - name: IDStockKeepingUnitPurchaseItemsCheck
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra um item específico.
        - name: Draft
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` retorna draft (mobile).'
      responses:
        '200':
          description: Array de itens conferidos com status e diff.
    post:
      operationId: purchaseCheckPost
      tags:
        - Recebimento
      summary: Salva a conferência (draft ou final)
      description: >-
        Salva os itens conferidos. **Controle de idempotência** por MD5 do body com janela de 60s — chamadas duplicadas
        dentro dessa janela são ignoradas.


        Querystrings:

        - `?Draft=1` salva em `StockKeepingUnitPurchaseItemsCheckTemp` (rascunho).

        - `?Draft=0` (default): apaga o draft e grava em `StockKeepingUnitPurchaseItemsCheck` (definitivo).

        - `?ChangeStatus=1`: ao final, muda status do recebimento para `4` (Conferência realizada).

        - `?NoInvoke=1`: pula o re-invoke de `purchaseCheckGet` (otimização do mobile).
      parameters:
        - name: idpurchase
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do recebimento (`IDPurchase`).
        - name: Draft
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Quando `1`, restringe à versão de rascunho/draft.
        - name: ChangeStatus
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Filtra por mudança de status.
        - name: NoInvoke
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Quando `1`, não dispara o efeito colateral assíncrono normalmente associado à chamada.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/PurchaseCheckItem'
        description: >-
          Lista de itens conferidos fisicamente — um objeto por linha de SKU + lote. Quando `?Draft=1`, é gravada em
          rascunho (`StockKeepingUnitPurchaseItemsCheckTemp`); caso contrário, apaga o rascunho e grava como conferência
          definitiva.
      responses:
        '200':
          description: Sucesso.
        '400':
          description: >-
            `[BadRequest] - Processo de conferência em dupliciade` (operação já em andamento) / `Recebimento não existe`
            / `Erro ao conferir recebimento`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /purchase/{idpurchase}/check/{idstockkeepingunitpurchaseitemscheck}:
    put:
      operationId: purchaseCheckPut
      tags:
        - Recebimento
      summary: Edita um item da conferência
      description: >-
        Atualiza Quantidade, Lote, Validade, Fabricação ou Comentários de uma linha de conferência. Status do
        recebimento precisa ser `0`, `3` ou `4`.
      parameters:
        - name: idpurchase
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do recebimento (`IDPurchase`).
        - name: idstockkeepingunitpurchaseitemscheck
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do registro de conferência.
      requestBody:
        description: Atualiza um item conferido do recebimento (quantidade, lote e datas).
        content:
          application/json:
            schema:
              type: object
              properties:
                Quantity:
                  type: number
                  format: double
                  description: Quantidade conferida do item.
                BestBeforeDate:
                  type: string
                  format: date
                  description: Data de validade do lote (`YYYY-MM-DD`).
                ManufacturingDate:
                  type: string
                  format: date
                  description: Data de fabricação do lote (`YYYY-MM-DD`).
                BatchComments:
                  type: string
                  description: Observações do lote.
                Comments:
                  type: string
                  description: Observações da conferência do item.
      responses:
        '200':
          description: Sucesso.
        '400':
          description: '`[BadRequest] - Status do recebimento não permite editar conferência` / `Item conferência não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: purchaseCheckDelete
      tags:
        - Recebimento
      summary: Remove um item da conferência
      description: Mesmo gate de status (0, 3 ou 4).
      parameters:
        - name: idpurchase
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do recebimento (`IDPurchase`).
        - name: idstockkeepingunitpurchaseitemscheck
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do registro de conferência.
      responses:
        '200':
          description: Sucesso.
  /purchase/{idpurchase}/check/image:
    post:
      operationId: purchaseCheckImagePost
      tags:
        - Recebimento
      summary: Upload de foto da etiqueta (com IA opcional)
      description: >-
        Upload multipart de imagem da etiqueta. Salva em S3 `Image/Inbound/<id>.<ext>` (jpg/jpeg/png/pdf) e cria
        registro em `StockKeepingUnitPurchaseItemsCheckFile`.


        **`?MainImg=1`**: envia a imagem para o **Google Document AI** (processor configurado por parametrização da
        empresa). O OCR extrai automaticamente `Batch`, `BestBeforeDate` e `ManufacturingDate` da etiqueta — útil para
        conferência no celular sem digitação manual.
      parameters:
        - name: idpurchase
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do recebimento (`IDPurchase`).
        - name: MainImg
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` aciona OCR via Google Document AI.'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: Arquivo de imagem da etiqueta (jpg/jpeg/png/pdf), enviado como multipart.
        description: >-
          Upload multipart de imagem da etiqueta/produto. Formatos aceitos: `jpg`, `jpeg`, `png`, `pdf`. Quando enviado
          com `?MainImg=1`, a imagem passa por OCR (Google Document AI) e o sistema devolve os campos extraídos
          (`Batch`, `BestBeforeDate`, `ManufacturingDate`).
      responses:
        '200':
          description: >-
            Sucesso. Retorna `IDStockKeepingUnitPurchaseItemsCheckFile` e, quando `MainImg=1`,
            `BestBeforeDate`/`Batch`/`ManufacturingDate` extraídos.
        '400':
          description: '`Erro ao subir arquivo`.'
        '404':
          description: '`Recebimento não encontrado`.'
  /purchase/{idpurchase}/receipt:
    post:
      operationId: purchaseReceipt
      tags:
        - Recebimento
      summary: Finaliza o recebimento (entra estoque + side effects)
      description: >-
        Divergências para maior (quantidade acima da prevista ou SKU fora do recebimento) são roteadas ao armazém de
        divergência do CD; com `CreateNewPurchaseSentMore=1`, o excedente é destacado para um novo recebimento criado
        automaticamente para o mesmo fornecedor e centro de distribuição, em vez de compor a lista de divergências.
      parameters:
        - name: idpurchase
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do recebimento (`IDPurchase`).
        - name: PartialBuyOrder
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` finaliza apenas o recebimento mantendo o pedido de compra em status Parcial.'
        - name: CreateReturnOrder
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` cria automaticamente um pedido de devolução para itens conferidos a menor.'
        - name: CreateNewPurchaseSentMore
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: >-
            `1` separa as quantidades recebidas a maior (itens acima do previsto, ou SKUs que não constam do
            recebimento) e as lança em um novo recebimento criado automaticamente para o mesmo fornecedor e centro de
            distribuição do recebimento atual; o recebimento atual é finalizado apenas com as quantidades previstas. Sem
            a flag (ou `0`), o excedente entra no cálculo de divergência normal.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseReceiptPayload'
        description: >-
          Opcional. Lista dos itens efetivamente recebidos — um objeto por SKU + lote. Quando o body é omitido, o
          sistema monta a lista a partir da conferência salva (`StockKeepingUnitPurchaseItemsCheck`). Divergências para
          maior vão ao armazém de divergência do CD; divergências para menor reduzem ou apagam os movimentos previstos
          (e, se `?CreateReturnOrder=1`, geram pedido de devolução).
      responses:
        '200':
          description: Detalhe do recebimento finalizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseDetail'
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `Centro de distribuição não possui armazém de divergência cadastrado`
            - `Nenhum SKU pode ter quantidade menor ou igual a zero, verifique antes de finalizar`
            - `<msg composta>` com itens não enviados / a menor / a maior / não existe no recebimento
            - `Armazém (IDStockKeepingUnitWarehouse) X não encontrado`
            - `Endereço SKU X não encontrado`
            - `Lote (IDBatchNumber) X não encontrado para o sku: Y`
            - `Datas de fabricação e validade precisam ser preenchidas para o SKU: X`
            - `Preencha a data de validade, obrigatória para o SKU X`
            - `Preencha o lote, obrigatório para o SKU X`
            - `SKU X vence em N dias e mínimo dias necessários são M dias` (com `MinimumDaysBestBeforePurchase`)
            - `Data de fabricação maior que data de validade para o SKU X`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '404':
          description: '`[NotFound] - Recebimento não encontrado`.'
  /purchase/{idpurchase}/sku:
    post:
      operationId: purchaseSkuPost
      tags:
        - Recebimento
      summary: Adiciona item ao recebimento
      description: >-
        Adiciona um movimento de entrada (`StockKeepingUnitMovement IDTypeMovement=0`). Recebimento precisa estar em
        status `0` (Aberto). Valida obrigatoriedade de lote/validade/fabricação conforme flags do SKU (`RastroControl`,
        `BestBeforeRequired`, `BatchRequired`). Quando o SKU tem `Batch=1` e o endereço já tem lote/validade divergente,
        bloqueia (a menos que `AllowSameItemDifferentBatchSameLocation=1`).
      parameters:
        - name: idpurchase
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do recebimento (`IDPurchase`).
        - name: BypassValidation
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` pula validações de obrigatoriedade de rastreabilidade.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseSkuPostPayload'
        description: >-
          Dados do item a adicionar ao recebimento (SKU, armazém, quantidade, custo, lote, validade, CFOP). O
          recebimento precisa estar em status `0` (Aberto). Quando o SKU exige rastreabilidade, lote, fabricação e
          validade são obrigatórios. `?BypassValidation=1` pula essas validações.
      responses:
        '200':
          description: Detalhe atualizado.
        '400':
          description: >-
            Várias mensagens (`Quantidade > 0`, `Data fab > validade`, `Status não permite`, `Sku não existe`, `Armazém
            não existe`, `Lote SKU não existe`, `Endereço SKU não existe`, `CFOP X não existe`, `Item possui lotes
            divergentes`, etc.).
  /purchase/{idpurchase}/sku/{idskumovement}:
    put:
      operationId: purchaseSkuPut
      tags:
        - Recebimento
      summary: Edita item do recebimento
      description: >-
        Atualiza quantidade, custo, lote, validade, armazém ou endereço do item. Recebimento precisa estar em status
        `0`. **Exceção**: quando o recebimento já está finalizado e a alteração é apenas em `ValueCostTotal`, o sistema
        permite e registra log explícito — útil para corrigir custo sem reverter estoque.
      parameters:
        - name: idpurchase
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do recebimento (`IDPurchase`).
        - name: idskumovement
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do movimento de estoque (`IDSkuMovement`) do item no recebimento.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseSkuPostPayload'
        description: >-
          Campos editáveis do item do recebimento (mesmo schema do `POST`). Atualização parcial. Recebimento precisa
          estar em status `0` (Aberto), exceto quando a alteração é apenas em `ValueCostTotal` — nesse caso, o sistema
          permite ajuste mesmo com recebimento finalizado e registra log explícito.
      responses:
        '200':
          description: Sucesso.
    delete:
      operationId: purchaseSkuDelete
      tags:
        - Recebimento
      summary: Remove item do recebimento
      description: >-
        Recebimento em status `0`. Também apaga o lote (`StockKeepingUnitBatch`) se ele não tem mais movimentos
        vinculados.
      parameters:
        - name: idpurchase
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do recebimento (`IDPurchase`).
        - name: idskumovement
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do movimento de estoque (`IDSkuMovement`) do item no recebimento.
      responses:
        '200':
          description: Sucesso.
  /purchase/{idpurchase}/payment:
    post:
      operationId: purchasePaymentPost
      tags:
        - Recebimento
      summary: Adiciona pagamento (com retenções)
      description: >-
        Cria um título a pagar (`AccountsPayableReceivable IDTypeAccount=1`) vinculado ao recebimento. Quando `Taxes` é
        informado, cria também um título por retenção com `IDAccountPayableReceivableFather` apontando para o título
        principal — útil para PIS/COFINS/IR/CSLL retidos.
      parameters:
        - name: idpurchase
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do recebimento (`IDPurchase`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchasePaymentPostPayload'
        description: >-
          Dados do título a pagar a lançar no recebimento. `Taxes[]` (opcional) gera um título a pagar separado por
          retenção fiscal, vinculado ao título principal via `IDAccountPayableReceivableFather` (útil para
          PIS/COFINS/IR/CSLL retidos).
      responses:
        '200':
          description: Detalhe atualizado.
        '400':
          description: >-
            `Recebimento não existe` / `Fornecedor não existe` / `Type Payment não existe` / `Tipo documento não existe`
            / `Plano de contas não existe` / `Conta bancária não existe` / `Fornecedor retenção é obrigatório` / `Valor
            retenção é obrigatório` / `Data vencimento retenção é obrigatória` / `Fornecedores(s) retenção imposto não
            localizado(s): X`.
  /purchase/{idpurchase}/payment/{idaccountpayablereceivable}:
    put:
      operationId: purchasePaymentPut
      tags:
        - Recebimento
      summary: Edita pagamento
      description: >-
        Edita campos do título a pagar. ⚠️ **Quirk**: o sistema sobrescreve `DateDocument` e `DocumentNumber` com os
        valores do XML do recebimento (quando há XML) — campos passados no body podem ser ignorados.
      parameters:
        - name: idpurchase
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do recebimento (`IDPurchase`).
        - name: idaccountpayablereceivable
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do título a pagar (`IDAccountPayableReceivable`).
      requestBody:
        description: Atualização parcial dos dados de pagamento de uma parcela do recebimento.
        content:
          application/json:
            schema:
              type: object
              properties:
                IDAccountPayableReceivable:
                  type: integer
                  description: Conta a pagar a atualizar. Quando omitido, usa o id do path.
                Comments:
                  type: string
                  description: Observações do pagamento.
                DateCompetence:
                  type: string
                  format: date
                  description: Data de competência (`YYYY-MM-DD`).
                DateDocument:
                  type: string
                  format: date
                  description: Data do documento (`YYYY-MM-DD`).
                DateDue:
                  type: string
                  format: date
                  description: Data de vencimento (`YYYY-MM-DD`).
                DocumentNumber:
                  type: string
                  description: Número do documento.
                IDTypePayment:
                  type: integer
                  description: Tipo de pagamento.
                IDTypeDocument:
                  type: integer
                  description: Tipo de documento.
                IDTypeAccountPayble:
                  type: integer
                  description: Plano de contas (categoria) da conta a pagar.
                Value:
                  type: number
                  format: double
                  description: Valor da parcela em R$.
                BankSlipBarCode:
                  type: string
                  description: Linha digitável / código de barras do boleto.
                IDBankAccountForecast:
                  type: integer
                  description: Conta bancária de previsão.
                ValueDiscount:
                  type: number
                  format: double
                  description: Valor de desconto em R$.
                ValueInterest:
                  type: number
                  format: double
                  description: Valor de juros em R$.
                ValuePenalty:
                  type: number
                  format: double
                  description: Valor de multa em R$.
      responses:
        '200':
          description: Sucesso.
    delete:
      operationId: purchasePaymentDelete
      tags:
        - Recebimento
      summary: Remove pagamento
      description: Recebimento precisa estar em status `0`.
      parameters:
        - name: idpurchase
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do recebimento (`IDPurchase`).
        - name: idaccountpayablereceivable
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do título a pagar (`IDAccountPayableReceivable`).
      responses:
        '200':
          description: Sucesso.
  /purchase/{idpurchase}/invoice:
    post:
      operationId: purchaseInvoicePost
      tags:
        - Recebimento
      summary: Processa XML da NF-e no recebimento
      description: >-
        Recebe XML cru de NF-e (`<NFe>` + `<protNFe>`) e gera o recebimento de compra completo: cabeçalho e itens do
        XML, movimentos de estoque, batches, alocações e o contas a pagar (~50 validações).


        **Matching de SKU**: `ImportType` define a ordem (`1`=código fornecedor, `2`=código de barras, `3`=código de
        referência, `5`=código integração). Sem `ImportType`, tenta em sequência. Quando
        `PurchaseCreateSkuIfNotExists=1`, cria SKU automaticamente para produtos não encontrados.


        **Cálculo de custo**: `vProd + vICMSST + vFCPST + vIPI - vDesc + vFrete + vOutro` menos os impostos configurados
        para subtrair (`PurchaseSubtractPis/Cofins/Icms`). CFOPs em `CFOPCostZero` zeram o custo.


        **Controle de concorrência**: registro em `LogScript` chave `PurchaseInvoicePost_<account>_<idpurchase>` TTL 900
        s — `Processo já esta rodando, aguardar!`.


        **Devolução** (NF com `tpNF=0 + refNFe`): usa custo da NF original (proporcional).
      parameters:
        - name: idpurchase
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do recebimento (`IDPurchase`).
        - name: IDStockKeepingUnitWarehouse
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pelo identificador do depósito do SKU.
        - name: ImportType
          in: query
          required: false
          schema:
            type: string
          description: Critério de matching (CSV).
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Para matching por código do canal de venda.
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              type: string
              format: binary
        description: >-
          XML cru da NF-e a importar (`<NFe>` + `<protNFe>`). O sistema processa: matching de SKU, cálculo de impostos e
          custo, criação de lotes, contas a pagar e movimentos de estoque.
      responses:
        '200':
          description: XML processado.
        '400':
          description: |-
            Mensagens de erro:
            - `XML não é válido` / `XML não esta assinado` / `O arquivo não é um XML de Nota Fiscal válido`
            - `Recebimento não encontrado` / `O status atual não permite inserir XML`
            - `Tipo documento padrão não cadastrado` / `Plano de contas padrão para compras não cadastrado`
            - `XML já importado` / `Recebimento já tem XML importado`
            - `Armazém informado não cadastrado` / `Armazém informado não pertence ao centro de distribuição`
            - `Processo já esta rodando, aguardar!` (operação já em andamento)
            - `SKU(s) não cadastrados: produto código:X EAN:Y` (sem `PurchaseCreateSkuIfNotExists`)
            - `SKU(s) sem alíquota de entrada de PIS/COFINS cadastrada` (com `RequirePisCofinsInboundAliquot=1`)
            - `Certificado digital não encontrado` / `Erro validação SEFAZ: X` (com `ValidadeInboundInvoice=1`)
            - `Erro salvar Xml`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /purchase/{idpurchase}/label:
    get:
      operationId: purchaseLabelGet
      tags:
        - Recebimento
      summary: Gera etiqueta do recebimento (ZPL ou PDF)
      description: Gera etiquetas dos itens via Labelary API (PDF) ou retorna ZPL puro. Modelo da etiqueta vem de `IDCompanyLabel`.
      parameters:
        - name: idpurchase
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do recebimento (`IDPurchase`).
        - name: IDCompanyLabel
          in: query
          required: true
          schema:
            type: integer
            format: int64
          description: Filtra pelo identificador da etiqueta da empresa.
        - name: Download
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` baixa o arquivo `.zpl`.'
        - name: Zpl
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` retorna o ZPL bruto.'
        - name: IDSkuMovement
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra 1 movimento.
        - name: IDCompanySalesPolicy
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pela política de venda da empresa.
      responses:
        '200':
          description: PDF ou ZPL conforme parâmetros.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
            text/plain:
              schema:
                type: string
                description: ZPL.
        '400':
          description: >-
            `Parâmetros inválidos, obrigatório informar account e IDCompanyLabel` / `Recebimento não encontrado` /
            `Problema ao gerar etiqueta`.
  /purchase/{idpurchase}/log:
    get:
      operationId: purchaseLogGet
      tags:
        - Recebimento
      summary: Histórico de alterações do recebimento
      description: >-
        Retorna o log auditoria (`StockKeepingUnitPurchaseLog`) ordenado decrescente — quem fez, quando, o que mudou
        (diff).
      parameters:
        - name: idpurchase
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do recebimento (`IDPurchase`).
      responses:
        '200':
          description: Array de eventos.
  /hub/sales-policy:
    get:
      operationId: hubSalesPolicyList
      tags:
        - Hub — Política Comercial
      summary: Lista mapeamentos DE-PARA
      description: >-
        Lista todos os mapeamentos da empresa autenticada. Sem paginação. Ordenação por `IntegrationName,
        CompanyIntegrationName`.
      parameters:
        - name: IDSalesPolicyTo
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra por política comercial interna.
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra por canal de venda.
      responses:
        '200':
          description: Array de mapeamentos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubSalesPolicyItem'
    post:
      operationId: hubSalesPolicyPost
      tags:
        - Hub — Política Comercial
      summary: Cria mapeamento DE-PARA
      description: >-
        Cria um novo mapeamento. **Sem checagem de unicidade** — duplicatas com mesma combinação podem coexistir.
        Validações:


        - Integração precisa existir e pertencer à empresa autenticada.

        - Política comercial interna precisa existir e pertencer à empresa.

        - Tipo de pedido (se informado) precisa existir e pertencer à empresa.

        - Vtex (`IDTypeCompanyIntegration = 23`): `IDSalesPolicyFrom` obrigatório.

        - Mercado Livre (`IDTypeCompanyIntegration = 10`): `ShippingFree` é aceito e armazenado.

        - Outras integrações: `ShippingFree` é **forçado a `null`** pelo servidor (mesmo se enviado no body).


        Resposta: a lista completa atualizada.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubSalesPolicyPayload'
        description: >-
          Mapeamento de política comercial a cadastrar. `IDCompanyIntegration` e `IDSalesPolicyTo` são obrigatórios.
          `IDSalesPolicyFrom` é obrigatório quando a integração é Vtex (`IDTypeCompanyIntegration = 23`). `ShippingFree`
          só é considerado para Mercado Livre (`IDTypeCompanyIntegration = 10`) — em outras integrações é forçado a
          `null`.
      responses:
        '200':
          description: Lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubSalesPolicyItem'
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `Integração não cadastrada`
            - `Campo política integração é obrigatório para integração Vtex`
            - `Politica comercial não cadastrada`
            - `Tipo pedido não existe`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/sales-policy/{idhubsalespolicy}:
    put:
      operationId: hubSalesPolicyPut
      tags:
        - Hub — Política Comercial
      summary: Edita mapeamento DE-PARA
      description: |-
        Edita um mapeamento existente. Mesmas validações do Post:

        - Registro precisa existir e pertencer à empresa (referência em `CompanyIntegration`).
        - Regras de obrigatoriedade por integração (Vtex exige `IDSalesPolicyFrom`).
        - `ShippingFree` forçado a `null` quando não-Meli.
        - Quando `ShippingFree` não vem no body, mantém o valor anterior.

        Resposta: lista completa atualizada (`hubSalesPolicyList` re-invocado).
      parameters:
        - name: idhubsalespolicy
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do mapeamento (`IDHubSalesPolicy`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubSalesPolicyPayload'
        description: Mesma estrutura do POST. Mantém as mesmas regras por integração; campos não enviados preservam o valor atual.
      responses:
        '200':
          description: Lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubSalesPolicyItem'
        '400':
          description: |-
            Mensagens `[BadRequest]` (Post +):
            - `Hub Politica Comercial não existe`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: hubSalesPolicyDelete
      tags:
        - Hub — Política Comercial
      summary: Remove mapeamento DE-PARA
      description: >-
        Apaga o mapeamento. Sem restrições — qualquer mapeamento pode ser removido a qualquer momento. As validações
        reversas vivem em outras telas (`OrderTypeOrderDelete`, `companySalesPolicyDelete`).
      parameters:
        - name: idhubsalespolicy
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do mapeamento (`IDHubSalesPolicy`).
      responses:
        '200':
          description: Lista atualizada após remoção.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubSalesPolicyItem'
        '400':
          description: '`[BadRequest] - Hub Politica Comercial não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/payment:
    get:
      operationId: hubPaymentList
      tags:
        - Hub — Pagamento
      summary: Lista mapeamentos — Hub Pagamento
      description: Lista os mapeamentos da empresa autenticada. Sem paginação.
      parameters:
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pelo identificador da integração da empresa.
      responses:
        '200':
          description: Array de mapeamentos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PaymentHubItem'
    post:
      operationId: hubPaymentPost
      tags:
        - Hub — Pagamento
      summary: Cria mapeamento — Hub Pagamento
      description: Cria um novo mapeamento. Retorna a lista completa atualizada (re-invoca o List).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentHubPayload'
        description: >-
          Mapeamento de forma de pagamento a cadastrar. `IDCompanyIntegration` e `IDPaymentTo` são obrigatórios.
          `IDPaymentFrom` é o código da forma de pagamento usado pelo canal.
      responses:
        '200':
          description: Lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PaymentHubItem'
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `De/para pagamento já existe`
            - `Pagamento não cadastrado`
            - `Integração não cadastrada`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/payment/{idhubpayment}:
    put:
      operationId: hubPaymentPut
      tags:
        - Hub — Pagamento
      summary: Edita mapeamento — Hub Pagamento
      description: Edita o mapeamento. Retorna a lista atualizada.
      parameters:
        - name: idhubpayment
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da forma de pagamento no hub.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentHubPayload'
        description: >-
          Mesma estrutura do POST. Em integrações cujo tipo NÃO é `23`, `24`, `34`, `45` ou `53`, quando `IDPaymentFrom`
          é enviado vazio o sistema o preenche automaticamente com o `IDSalesChannel` da integração.
      responses:
        '200':
          description: Lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PaymentHubItem'
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `De/para pagamento já existe`
            - `Pagamento não cadastrada`
            - `Integração não cadastrada`
            - `Pagamento Hub não existe`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: hubPaymentDelete
      tags:
        - Hub — Pagamento
      summary: Remove mapeamento — Hub Pagamento
      description: Apaga o mapeamento.
      parameters:
        - name: idhubpayment
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da forma de pagamento no hub.
      responses:
        '200':
          description: Lista atualizada após remoção.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PaymentHubItem'
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `Pagamento Hub não existe`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/brand:
    get:
      operationId: hubBrandList
      tags:
        - Hub — Marcas
      summary: Lista mapeamentos — Hub Marcas
      description: Lista os mapeamentos da empresa autenticada. Sem paginação.
      parameters:
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pelo identificador da integração da empresa.
      responses:
        '200':
          description: Array de mapeamentos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BrandHubItem'
    post:
      operationId: hubBrandPost
      tags:
        - Hub — Marcas
      summary: Cria mapeamento — Hub Marcas
      description: Cria um novo mapeamento. Retorna a lista completa atualizada (re-invoca o List).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrandHubPayload'
        description: >-
          Mapeamento de marca a cadastrar. `IDCompanyIntegration` e `IDBrandTo` são obrigatórios; `IDBrandFrom` é o
          código da marca no canal (texto livre).
      responses:
        '200':
          description: Lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BrandHubItem'
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `Marca não cadastrada`
            - `Integração não cadastrada`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/brand/{idhubbrand}:
    put:
      operationId: hubBrandPut
      tags:
        - Hub — Marcas
      summary: Edita mapeamento — Hub Marcas
      description: Edita o mapeamento. Retorna a lista atualizada.
      parameters:
        - name: idhubbrand
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da marca no hub.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrandHubPayload'
        description: Mesma estrutura do POST. Campos não enviados preservam o valor atual.
      responses:
        '200':
          description: Lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BrandHubItem'
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `Marca não cadastrada`
            - `Integração não cadastrada`
            - `De/Para marca não existe`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: hubBrandDelete
      tags:
        - Hub — Marcas
      summary: Remove mapeamento — Hub Marcas
      description: Apaga o mapeamento.
      parameters:
        - name: idhubbrand
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da marca no hub.
      responses:
        '200':
          description: Lista atualizada após remoção.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BrandHubItem'
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `IDHubBrand não existe`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/brand/{idhubbrand}/update:
    post:
      operationId: hubBrandUpdatePost
      tags:
        - Hub — Marcas
      summary: Reprocessa mapeamento (sincroniza com o canal)
      description: >-
        Reconsulta os dados do mapeamento direto no canal em segundo plano externo. Depende de
        `TypeSalesChannelResource` com `ResourceType=Brand` cadastrado para o tipo da integração — caso contrário falha
        com a mensagem de recurso indisponível.
      parameters:
        - name: idhubbrand
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da marca no hub.
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pelo identificador da integração da empresa.
      responses:
        '200':
          description: Reprocessamento disparado.
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `Integracão não tem recurso`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/category:
    get:
      operationId: hubCategoryList
      tags:
        - Hub — Categorias
      summary: Lista mapeamentos — Hub Categorias
      description: Lista os mapeamentos da empresa autenticada. Sem paginação.
      parameters:
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pelo identificador da integração da empresa.
      responses:
        '200':
          description: Array de mapeamentos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CategoryHubItem'
    post:
      operationId: hubCategoryPost
      tags:
        - Hub — Categorias
      summary: Cria mapeamento — Hub Categorias
      description: Cria um novo mapeamento. Retorna a lista completa atualizada (re-invoca o List).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoryHubPayload'
        description: >-
          Mapeamento de categoria a cadastrar. `IDCompanyIntegration` e `IDCategoryTo` são obrigatórios;
          `IDCategoryFrom` é o código da categoria no canal e `CategoryFromTree` carrega a árvore completa (`Eletrônicos
          > TV > Smart TV`) para facilitar a navegação na tela.
      responses:
        '200':
          description: Lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CategoryHubItem'
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `Categoria não cadastrada`
            - `Integração não cadastrada`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/category/{idhubcategory}:
    put:
      operationId: hubCategoryPut
      tags:
        - Hub — Categorias
      summary: Edita mapeamento — Hub Categorias
      description: Edita o mapeamento. Retorna a lista atualizada.
      parameters:
        - name: idhubcategory
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da categoria no hub.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoryHubPayload'
        description: Mesma estrutura do POST. Campos não enviados preservam o valor atual.
      responses:
        '200':
          description: Lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CategoryHubItem'
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `Categoria não cadastrada`
            - `Integração não cadastrada`
            - `Categoria hub não existe`
            - `Já existe de/para de categoria para mesma categoria e integração`
            - `Erro ao inserir de/para de categoria`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: hubCategoryDelete
      tags:
        - Hub — Categorias
      summary: Remove mapeamento — Hub Categorias
      description: Apaga o mapeamento.
      parameters:
        - name: idhubcategory
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da categoria no hub.
      responses:
        '200':
          description: Lista atualizada após remoção.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CategoryHubItem'
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `IDHubCategory não existe`
            - `Existe de/para de variação para essa categoria e a mesma não pode ser excluida`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/category/{idhubcategory}/update:
    post:
      operationId: hubCategoryUpdatePost
      tags:
        - Hub — Categorias
      summary: Reprocessa mapeamento (sincroniza com o canal)
      description: >-
        Reconsulta os dados do mapeamento direto no canal em segundo plano externo. Depende de
        `TypeSalesChannelResource` com `ResourceType=Category` cadastrado para o tipo da integração — caso contrário
        falha com a mensagem de recurso indisponível.
      parameters:
        - name: idhubcategory
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da categoria no hub.
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pelo identificador da integração da empresa.
      responses:
        '200':
          description: Reprocessamento disparado.
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `Integracão não tem recurso`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/warehouse:
    get:
      operationId: hubWarehouseList
      tags:
        - Hub — Estoque
      summary: Lista mapeamentos — Hub Estoque
      description: Lista os mapeamentos da empresa autenticada. Sem paginação.
      parameters:
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pelo identificador da integração da empresa.
      responses:
        '200':
          description: Array de mapeamentos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WarehouseHubItem'
    post:
      operationId: hubWarehousePost
      tags:
        - Hub — Estoque
      summary: Cria mapeamento — Hub Estoque
      description: Cria um novo mapeamento. Retorna a lista completa atualizada (re-invoca o List).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WarehouseHubPayload'
        description: >-
          Mapeamento de armazém a cadastrar. `IDCompanyIntegration`, `IDStockKeepingUnitWarehouseFrom`,
          `IDStockKeepingUnitWarehouseTo` e `IDOrderType` são obrigatórios. `IDStatusOrder` é opcional e só aceita
          status com `ChangeOnCreate = 1`.
      responses:
        '200':
          description: Lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WarehouseHubItem'
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `DE/PARA de armazém já existe`
            - `Tipo Pedido não cadastrado`
            - `Armazem não cadastrada`
            - `Integração não cadastrada`
            - `Status pedido não existe`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/warehouse/{idhubwarehouse}:
    put:
      operationId: hubWarehousePut
      tags:
        - Hub — Estoque
      summary: Edita mapeamento — Hub Estoque
      description: Edita o mapeamento. Retorna a lista atualizada.
      parameters:
        - name: idhubwarehouse
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do depósito no hub.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WarehouseHubPayload'
        description: Mesma estrutura do POST. Campos não enviados preservam o valor atual.
      responses:
        '200':
          description: Lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WarehouseHubItem'
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `Tipo Pedido não cadastrado`
            - `Armazém não cadastrada`
            - `Integração não cadastrada`
            - `De/para armazém não cadastrado`
            - `Status pedido não existe`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: hubWarehouseDelete
      tags:
        - Hub — Estoque
      summary: Remove mapeamento — Hub Estoque
      description: Apaga o mapeamento. A lista da integração é atualizada.
      parameters:
        - name: idhubwarehouse
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do depósito no hub.
      responses:
        '200':
          description: Lista atualizada após remoção.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WarehouseHubItem'
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `IDHubWarehouse não existe`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/product/question-answer-template:
    get:
      operationId: hubQuestionAnswerTemplateList
      tags:
        - Hub — Anúncios
      summary: Lista templates de mensagem
      description: >-
        Lista os templates de mensagem da empresa. Filtros via querystring por `AnswerType` (`1` Resposta
        pré-cadastrada, `2` Mensagem automática).
      parameters:
        - name: AnswerType
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
              - 2
          description: Filtra pelo tipo de resposta.
      responses:
        '200':
          description: Array de templates.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubMessageItem'
    post:
      operationId: hubQuestionAnswerTemplatePost
      tags:
        - Hub — Anúncios
      summary: Cria template de mensagem
      description: >-
        Cria um novo template. `Title` é obrigatório quando `AnswerType=2` (Mensagem automática). Texto pode conter
        variáveis dinâmicas `{{Variável}}` substituídas no momento do uso.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubMessagePayload'
        description: >-
          Modelo de mensagem a cadastrar. `AnswerType` define se é resposta pré-cadastrada (`1`) ou mensagem automática
          (`2`); `Answer` é o texto e aceita variáveis dinâmicas como `{{Nickname}}`. `Title` é obrigatório para
          `AnswerType=2`.
      responses:
        '200':
          description: Template criado.
  /hub/product/question-answer-template/{idhubproductquestionanswertemplate}:
    put:
      operationId: hubQuestionAnswerTemplatePut
      tags:
        - Hub — Anúncios
      summary: Edita template de mensagem
      parameters:
        - name: idhubproductquestionanswertemplate
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do modelo de pergunta/resposta de produto no hub.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubMessagePayload'
        description: Mesma estrutura do POST. Campos não enviados preservam o valor atual.
      responses:
        '200':
          description: Sucesso.
      description: >-
        Edita um template de mensagem usado para responder perguntas de compradores no canal de venda. Devolve o
        template atualizado.
    delete:
      operationId: hubQuestionAnswerTemplateDelete
      tags:
        - Hub — Anúncios
      summary: Remove template de mensagem
      parameters:
        - name: idhubproductquestionanswertemplate
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do modelo de pergunta/resposta de produto no hub.
      responses:
        '200':
          description: Sucesso.
      description: Remove um template de mensagem de perguntas/respostas do canal de venda.
  /hub/product/question-answer:
    get:
      operationId: hubQuestionAnswerList
      tags:
        - Hub — Anúncios
      summary: Lista perguntas dos compradores
      description: >-
        Lista as perguntas feitas pelos compradores nos anúncios. Filtros opcionais:
        `IDTypeHubProductQuestionAnswerStatus` (`1` Não Respondida, `2` Respondida), `Nickname` (histórico do
        comprador), `IDHubProduct` (anúncio específico).
      parameters:
        - name: IDTypeHubProductQuestionAnswerStatus
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
              - 2
          description: Filtra pelo status da pergunta/resposta de produto no hub.
        - name: Nickname
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo apelido.
        - name: IDHubProduct
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pelo identificador do produto no hub.
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pelo identificador da integração da empresa.
      responses:
        '200':
          description: Array de perguntas.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubQuestionAnswerItem'
  /hub/product/question-answer/{idhubproductquestionanswer}:
    put:
      operationId: hubQuestionAnswerPut
      tags:
        - Hub — Anúncios
      summary: Responde uma pergunta
      description: >-
        Envia a resposta para o canal e marca a pergunta como Respondida (status `2`). Limite de **2000 caracteres**
        imposto pelo canal.
      parameters:
        - name: idhubproductquestionanswer
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da pergunta/resposta de produto no hub.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - Answer
              properties:
                Answer:
                  type: string
                  maxLength: 2000
                  description: Texto da resposta à pergunta do comprador no canal de venda.
        description: >-
          Texto da resposta a ser enviada ao comprador no canal. Único campo aceito é `Answer` (até 2000 caracteres). O
          envio sincroniza a resposta no canal e marca a pergunta como Respondida.
      responses:
        '200':
          description: Resposta enviada.
    delete:
      operationId: hubQuestionAnswerDelete
      tags:
        - Hub — Anúncios
      summary: Remove uma pergunta
      description: Permitido apenas em perguntas **Não Respondidas** (`IDTypeHubProductQuestionAnswerStatus=1`).
      parameters:
        - name: idhubproductquestionanswer
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da pergunta/resposta de produto no hub.
      responses:
        '200':
          description: Sucesso.
  /hub/order/claim:
    get:
      operationId: hubOrderClaimList
      tags:
        - Hub — Pedidos
      summary: Lista reclamações abertas pelos compradores
      description: >-
        Lista as reclamações sincronizadas dos canais. Cada linha tem estágio, tipo e motivo (vindos do canal — listas
        auxiliares em `/type/hub/order/claim/{reason,stage,type,resolution-reason}`).
      responses:
        '200':
          description: Array de reclamações.
  /hub/order/claim/{idhuborderclaim}:
    get:
      operationId: hubOrderClaimGet
      tags:
        - Hub — Pedidos
      summary: Detalhe da reclamação (chat + ações disponíveis)
      description: >-
        Detalhe completo: mensagens trocadas, anexos, dados do pedido, comprador, e — crucialmente — `AvailableActions`
        que o canal indica para o estágio atual (`refund`, `open_dispute`, `allow_return`, `return_review_ok`,
        `return_review_fail`, `send_potential_shipping`, `allow_partial_refund`, `send_message_to_complainant`,
        `send_message_to_mediator`, etc.). Quando `ClaimStatus=1` (Fechado), nenhuma ação é mais possível.
      parameters:
        - name: idhuborderclaim
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da reclamação de pedido no hub.
      responses:
        '200':
          description: Detalhe da reclamação.
  /hub/order/claim/{idhuborderclaim}/action:
    post:
      operationId: hubOrderClaimAction
      tags:
        - Hub — Pedidos
      summary: Executa uma ação na reclamação
      description: |-
        Dispara uma das `AvailableActions` (ver acima). Body varia por tipo de ação:
        - `refund` / `open_dispute` / `allow_return` / `return_review_ok` — sem body adicional.
        - `send_potential_shipping` — `{DateShipping}`.
        - `allow_partial_refund` — `{Percentage}` ou `{Amount}`.
        - `return_review_fail` — `{Reason, Message, FileUUIDs}` (anexo obrigatório para motivos SRF2/SRF4).
        - `send_message_to_complainant` / `send_message_to_mediator` — `{Message}`.
        - `send_only_attachments` / `send_attachments` — `{Message, FileUUIDs}`.
      parameters:
        - name: idhuborderclaim
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da reclamação de pedido no hub.
        - name: Type
          in: query
          required: true
          schema:
            type: string
          description: Tipo da ação (ver `AvailableActions[].Type` retornado por `GET /hub/order/claim/{id}`).
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
        description: >-
          Corpo varia conforme a ação (`Type` na query). Estruturas observadas: ações sem body (`refund`,
          `open_dispute`, `allow_return`, `return_review_ok`); `{DateShipping}` para `send_potential_shipping`;
          `{Percentage}` ou `{Amount}` para `allow_partial_refund`; `{Reason, Message, FileUUIDs}` para
          `return_review_fail` (anexo obrigatório para motivos SRF2/SRF4); `{Message}` para
          `send_message_to_complainant` e `send_message_to_mediator`; `{Message, FileUUIDs}` para
          `send_only_attachments` e `send_attachments`. Os `FileUUIDs` vêm das chamadas anteriores ao endpoint de
          upload.
      responses:
        '200':
          description: Ação executada — `GET claim` é re-invocado e novo estado retornado.
  /hub/order/claim/{idhuborderclaim}/action/file:
    post:
      operationId: hubOrderClaimActionFile
      tags:
        - Hub — Pedidos
      summary: Faz upload de arquivo para anexar a uma ação
      description: >-
        Sobe um arquivo (foto, PDF, vídeo curto) e devolve um `FileUUID` para usar em uma ação subsequente
        (`return_review_fail`, `send_attachments`, etc.). Quando o motivo da recusa é SRF2/SRF4 (return_review_fail), o
        anexo é obrigatório — sistema aceita query `?Return=1`.
      parameters:
        - name: idhuborderclaim
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da reclamação de pedido no hub.
        - name: Return
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Quando `1`, restringe a registros de devolução.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: Arquivo anexado à ação da reclamação (imagem ou documento), enviado como multipart.
        description: >-
          Upload multipart de um arquivo (foto, PDF ou vídeo curto). Resposta inclui o `FileUUID` que deve ser
          referenciado posteriormente no corpo da ação correspondente.
      responses:
        '200':
          description: Retorna `FileUUID` para o anexo.
  /orders/hub:
    get:
      operationId: orderHubList
      tags:
        - Pedidos
      summary: Lista o staging de pedidos integrados
      description: >-
        Lista o staging de pedidos integrados dos canais de venda, com os filtros de canal/cliente/UTM/data, busca
        textual `Search`, modo `OrdersNotCreated=1` (so registros que ainda nao geraram pedido) e paginacao em blocos de
        1000 (`Page` -> deslocamento `Page * 1000`).
      responses:
        '200':
          description: Array de linhas.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubOrderItem'
      parameters:
        - name: ConsumerNameCorporateName
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo primeiro nome do cliente (busca parcial).
        - name: ConsumerCpfCnpj
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo documento do cliente (CPF/CNPJ, busca parcial).
        - name: ConsumerEmail
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo e-mail do cliente (busca parcial).
        - name: Order
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo numero do pedido ja criado (`Order`).
        - name: OrderFrom
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo identificador do pedido na origem (`OrderId` do canal).
        - name: IDStatusOrder
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo status do pedido no canal de venda (`Status`).
        - name: IDSalesChannel
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo canal de venda.
        - name: ShippingId
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo codigo de rastreio/etiqueta do envio.
        - name: PackId
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo identificador de agrupamento de pacotes do canal.
        - name: DateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data inicial de registro do staging (`RecordTimestamp >=`).
        - name: DateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data final de registro (concatenada com ` 23:59:59`).
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pela integracao de origem do pedido.
        - name: IDTypeCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo tipo de integracao/canal.
        - name: IDIntegration
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo identificador interno do registro de staging.
        - name: Coupon
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo cupom aplicado no pedido.
        - name: UtmCampaign
          in: query
          required: false
          schema:
            type: string
          description: Filtra pela campanha de origem (UTM).
        - name: UtmMedium
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo meio de origem (UTM).
        - name: UtmSource
          in: query
          required: false
          schema:
            type: string
          description: Filtra pela fonte de origem (UTM).
        - name: UtmiCampaign
          in: query
          required: false
          schema:
            type: string
          description: Filtra pela campanha interna (UTMi).
        - name: UtmiPage
          in: query
          required: false
          schema:
            type: string
          description: Filtra pela pagina interna (UTMi).
        - name: UtmiPart
          in: query
          required: false
          schema:
            type: string
          description: Filtra pela parte/secao interna (UTMi).
        - name: OrdersNotCreated
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: >-
            Quando `1`, lista apenas registros do staging que ainda nao geraram pedido (`IDOrder` vazio), cujo status do
            canal nao esta cancelado e que estao marcados para criar pedido.
        - name: Search
          in: query
          required: false
          schema:
            type: string
          description: >-
            Busca textual generica. Casa contra `PackId`, identificador interno `IDIntegration`, codigo de rastreio
            `ShippingId`, identificador do pedido na origem `OrderId`, codigo interno `IDOrder`, numero do pedido
            `Order`, primeiro nome do cliente `ConsumerFirstName`, nome do recebedor `ShippingReceiverName`, documento
            `ConsumerDocument` e e-mail `ConsumerEmail`. Espacos viram curinga interno.
        - name: Page
          in: query
          required: false
          schema:
            type: integer
          description: Pagina; o deslocamento e `Page * 1000` (blocos de 1000 registros).
        - name: CreationTimestampFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: >-
            Data inicial de criacao do pedido no canal de origem (CreationTimestamp >=). Diferente de DateFrom, que
            filtra a data de registro do staging.
        - name: CreationTimestampTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data final de criacao do pedido no canal de origem (concatenada com 23:59:59).
    post:
      operationId: orderHubPost
      tags:
        - Pedidos
      summary: Cria pedido manualmente (puxa do canal pelo código origem)
      description: >-
        Quando o canal não enviou o pedido automaticamente, este endpoint faz um **pull explícito** usando o código
        origem informado. Útil para 'puxar' pedidos pontuais. `ShippingId` é obrigatório apenas para Mercado Livre
        OnSite (`IDTypeCompanyIntegration=1`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubOrderPostPayload'
        description: >-
          Solicita ao canal de venda a importação imediata de um pedido específico (atalho para evitar esperar o coletor
          agendado). `IDCompanyIntegration` define a integração e `OrderFrom` é o código do pedido no canal.
      responses:
        '200':
          description: Linha criada (e pedido idworks também, se a integração está configurada para criação automática).
  /hub/order/{idintegration}:
    get:
      operationId: orderHubGet
      tags:
        - Hub — Pedidos
      summary: Detalhe de uma linha de staging
      description: Detalhe completo com todos os campos do canal + status idworks (quando há pedido criado).
      parameters:
        - name: idintegration
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador único da linha de staging.
      responses:
        '200':
          description: Detalhe.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HubOrderItem'
    delete:
      operationId: orderHubDelete
      tags:
        - Hub — Pedidos
      summary: Remove uma linha de staging
      description: >-
        Permitido apenas quando `IDOrder` está vazio (linha ainda não virou pedido idworks). Linhas com `IDOrder`
        preenchido devem ser canceladas pela tela de Pedidos (que reverte estoque, contas a receber, etc.).
      parameters:
        - name: idintegration
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador único da linha de staging.
      responses:
        '200':
          description: Removido.
  /hub/order/create/{idintegration}:
    post:
      operationId: orderHubCreatePost
      tags:
        - Hub — Pedidos
      summary: Cria pedido idworks a partir de linha de staging
      description: >-
        serviço de integração que transforma a linha de staging em pedido efetivo no idworks: cria cliente, endereço,
        itens (SKUs vinculados), pagamentos (tipo via Hub Pagamento), frete (transportadora via Hub Carriers), aplica
        armazém + tipo de pedido (via Hub Estoque) e UTM tracking. Após sucesso, o campo `IDOrder` da linha fica
        preenchido.
      parameters:
        - name: idintegration
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador único da linha de staging.
      responses:
        '200':
          description: Pedido idworks criado.
  /hub/order/update/{idintegration}:
    post:
      operationId: orderHubUpdatePost
      tags:
        - Hub — Pedidos
      summary: Reprocessar — re-pull do canal
      description: >-
        Faz pull novamente do canal usando o código origem e atualiza a linha de staging com os dados frescos. Não
        recria o pedido idworks (se já existir, mantém).
      parameters:
        - name: idintegration
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador único da linha de staging.
      responses:
        '200':
          description: Reprocessamento disparado.
    put:
      operationId: orderHubUpdatePut
      tags:
        - Hub — Pedidos
      summary: Atualiza SKU vinculado a item da linha
      description: >-
        Edita o vínculo SKU local ↔ produto do canal em um item da linha de staging. Usado pela expansão da linha quando
        um item está sem SKU mapeado.
      parameters:
        - name: idintegration
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador único da linha de staging.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                IDSku:
                  type: integer
                  format: int64
                  description: Identificador do SKU no idworks a vincular ao produto do canal.
                IDIntegrationProducts:
                  type: integer
                  format: int64
                  description: Identificador do produto na integração (canal de venda).
        description: >-
          Vincula um SKU local a um item específico da linha de staging que veio sem mapeamento. `IDIntegrationProducts`
          identifica o item dentro do pedido integrado (`IDIntegrationProducts`) e `IDSku` é o SKU interno a ser
          associado (não pode ser kit, tipo `4`).
      responses:
        '200':
          description: Atualizado.
  /hub/order/status/{idorder}:
    get:
      operationId: orderHubStatusGet
      tags:
        - Hub — Pedidos
      summary: Consulta status atualizado do pedido no canal
      description: >-
        Força consulta de status no canal para um pedido idworks específico — útil para sincronizar estado quando o pull
        periódico não atualizou.
      parameters:
        - name: idorder
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do pedido.
      responses:
        '200':
          description: Status do canal.
  /hub/order/invoice/{idorder}:
    post:
      operationId: orderHubInvoicePost
      tags:
        - Hub — Pedidos
      summary: Envia NF do pedido para o canal
      description: >-
        Quando o pedido idworks foi faturado, este endpoint envia o XML da NF para o canal (alguns canais exigem para
        que o pedido siga para o status Enviado).
      parameters:
        - name: idorder
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do pedido.
      responses:
        '200':
          description: NF enviada.
  /hub/order/{idintegration}/action:
    post:
      operationId: orderHubMessagePost
      tags:
        - Hub — Pedidos
      summary: Envia mensagem ao comprador pelo canal
      description: >-
        Dispara uma mensagem ao comprador no canal. Type indica o tipo de mensagem (`send_message`, etc.). Privilégio
        `PrivilegeHubOrderMessageSend`.
      parameters:
        - name: idintegration
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador único da linha de staging.
        - name: Type
          in: query
          required: false
          schema:
            type: string
          description: Filtra por tipo. A semântica depende do endpoint.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
        description: >-
          Mensagem ao comprador. Corpo padrão `{Message}`; o `Type` na query indica o tipo de envio (`send_message` por
          padrão). O conteúdo aceito depende do canal — o sistema proxia o corpo para o processo do canal.
      responses:
        '200':
          description: Mensagem enviada.
  /hub/order/{idintegration}/action/file:
    post:
      operationId: orderHubMessageAttachmentPost
      tags:
        - Hub — Pedidos
      summary: Anexo de arquivo em mensagem do pedido
      description: Faz upload de arquivo para anexar a uma mensagem do pedido.
      parameters:
        - name: idintegration
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador único da linha de staging.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: Arquivo anexado à ação do pedido no canal (imagem ou documento), enviado como multipart.
        description: >-
          Upload multipart de arquivo para anexar a uma mensagem do pedido. Aceita query `Return=1` quando o anexo se
          refere a uma devolução.
      responses:
        '200':
          description: Arquivo anexado.
  /hub/product/size-chart:
    get:
      operationId: hubProductSizeChartList
      tags:
        - Hub — Anúncios
      summary: Lista grades — Hub Grade de Tamanho
      description: Lista as grades de tamanho cadastradas. Retorna apenas grades com `SizeChartStatus` 1 ou 2.
      parameters:
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra por integração.
        - name: ExternalId
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo identificador da grade no canal.
        - name: CatalogDomain
          in: query
          required: false
          schema:
            type: string
          description: 'Filtra pelo domínio de catálogo (ex.: `MLB-FOOTWEAR`).'
      responses:
        '200':
          description: Lista de grades.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubProductSizeChartItem'
    post:
      operationId: hubProductSizeChartPost
      tags:
        - Hub — Anúncios
      summary: Cria grade de tamanho — Hub Grade de Tamanho
      description: >-
        Cria uma nova grade de tamanho com suas linhas (tamanhos) e atributos de medida. A grade nasce em status
        pendente de sincronização — um processo assíncrono envia ao canal. `RowId` precisa ser único dentro da grade.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubProductSizeChartCreate'
        description: >-
          Grade de tamanho a cadastrar com suas linhas iniciais. `IDCompanyIntegration`, `SizeChartName` e `TypeMeasure`
          são obrigatórios. Cada linha em `HubProductSizeChartRow[]` representa um tamanho com seu `RowId` único e a
          lista de atributos de medida (`FieldId` + `FieldValue`).
      responses:
        '200':
          description: Grade criada (mesma estrutura do GET por ID).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubProductSizeChartDetail'
        '400':
          description: '`[BadRequest] - Empresa não existe` · `[BadRequest] - Linha {RowId} duplicada`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/product/size-chart/{idhubproductsizechart}:
    get:
      operationId: hubProductSizeChartGet
      tags:
        - Hub — Anúncios
      summary: Detalha grade — Hub Grade de Tamanho
      description: Retorna a grade com todas as linhas (tamanhos) e atributos de medida.
      parameters:
        - name: idhubproductsizechart
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da tabela de medidas de produto no hub.
      responses:
        '200':
          description: Grade detalhada. Retorna array vazio quando não existe ou pertence a outra empresa.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubProductSizeChartDetail'
    put:
      operationId: hubProductSizeChartPut
      tags:
        - Hub — Anúncios
      summary: Atualiza grade — Hub Grade de Tamanho
      description: >-
        Atualiza nome e tipo de medida da grade. Tipo de medida **não pode** ser alterado depois que a grade foi
        sincronizada com o canal (já tem `ExternalId`).
      parameters:
        - name: idhubproductsizechart
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da tabela de medidas de produto no hub.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubProductSizeChartUpdate'
        description: >-
          Apenas `SizeChartName` e `TypeMeasure` podem ser alterados após a criação. `TypeMeasure` não pode mudar se a
          grade já foi sincronizada com o canal (existe `ExternalId`).
      responses:
        '200':
          description: Grade atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubProductSizeChartDetail'
        '400':
          description: >-
            `[BadRequest] - Grade de tamanho não existe` · `[BadRequest] - Grade de tamanho já foi sincronizada com
            canal e não pode ser alterada`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: hubProductSizeChartRowPost
      tags:
        - Hub — Anúncios
      summary: Adiciona linha à grade — Hub Grade de Tamanho
      description: >-
        Adiciona uma nova linha (tamanho) à grade existente. O `RowId` precisa ser único na grade. Cada combinação
        `FieldId`+`FieldValue` precisa ser única — o sistema rejeita atributos duplicados.
      parameters:
        - name: idhubproductsizechart
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da tabela de medidas de produto no hub.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubProductSizeChartRowPayload'
        description: >-
          Adiciona uma nova linha (tamanho) à grade. `RowId` deve ser único dentro da grade. Atributos com combinação
          `FieldId`+`FieldValue` já existentes na grade são rejeitados.
      responses:
        '200':
          description: Linha adicionada (retorna a grade completa).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubProductSizeChartDetail'
        '400':
          description: >-
            `[BadRequest] - Empresa não existe` · `[BadRequest] - Já existe um tamanho com mesmo código (rowid)` ·
            `[BadRequest] - Já existe o atributo {FieldName} com o mesmo valor {FieldValue}`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: hubProductSizeChartDelete
      tags:
        - Hub — Anúncios
      summary: Exclui grade — Hub Grade de Tamanho
      description: >-
        Exclui a grade. Quando a grade ainda não foi sincronizada com o canal (sem `ExternalId`) a exclusão é imediata.
        Quando já foi sincronizada, dispara um pedido assíncrono ao canal — o status só será atualizado depois de até
        24h.
      parameters:
        - name: idhubproductsizechart
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da tabela de medidas de produto no hub.
      responses:
        '200':
          description: >-
            Mensagem `Sucesso` (quando excluída localmente) ou `Solicitação de exclusão realizada com sucesso. Se houver
            algum problema, a tabela retornará a lista em 24h` (quando dispara processo no canal).
          content:
            application/json:
              schema:
                type: string
        '400':
          description: '`[BadRequest] - Grade de tamanho não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/product/size-chart/{idhubproductsizechart}/{rowid}:
    put:
      operationId: hubProductSizeChartRowPut
      tags:
        - Hub — Anúncios
      summary: Atualiza atributos da linha — Hub Grade de Tamanho
      description: >-
        Atualiza (upsert) os atributos de medida de uma linha existente. Combinações `FieldId` já presentes têm
        `FieldName`, `FieldValue` e `Unit` atualizados; novas combinações são inseridas.
      parameters:
        - name: idhubproductsizechart
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da tabela de medidas de produto no hub.
        - name: rowid
          in: path
          required: true
          schema:
            type: string
          description: Código do tamanho dentro da grade.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubProductSizeChartRowUpdatePayload'
        description: >-
          Atributos de medida a inserir ou atualizar na linha. Combinações `FieldId` já existentes na linha são
          atualizadas; novas são adicionadas.
      responses:
        '200':
          description: Linha atualizada (retorna a grade completa).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubProductSizeChartDetail'
        '400':
          description: '`[BadRequest] - Linha grade de tamanho não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/product/promotion:
    get:
      operationId: hubProductPromotionList
      tags:
        - Hub — Anúncios
      summary: Lista promoções — Hub Promoções
      description: >-
        Lista as promoções do hub. Use `IDProductHub` para verificar se um anúncio específico está em alguma promoção —
        quando informado, cada promoção retornada inclui o objeto `HubProductPromotionItem` com os campos do anúncio
        dentro daquela promoção. Página de até 2000 registros.
      parameters:
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pelo identificador da integração da empresa.
        - name: IDTypeHubProductPromotionStatus
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 3
              - 4
              - 5
              - 6
              - 7
              - 8
          description: Filtra por status (`1`-`8`).
        - name: IDTypeHubProductPromotion
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por tipo. Consulte `/type/hub/product/promotion/type`.
        - name: IDProductHub
          in: query
          required: false
          schema:
            type: string
          description: 'Filtra promoções que contenham o anúncio informado (ex.: `MLB123456789`).'
        - name: IDHubProductPromotion
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pelo identificador da promoção de produto no hub.
        - name: DateFromDateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Filtra promoções com `DateFrom` >= esta data.
        - name: DateFromDateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Filtra promoções com `DateFrom` <= esta data (23:59:59).
        - name: Page
          in: query
          required: false
          schema:
            type: integer
          description: Página (cada página = 2000 registros).
      responses:
        '200':
          description: Promoções.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubProductPromotionItem'
    post:
      operationId: hubProductPromotionPost
      tags:
        - Hub — Anúncios
      summary: Cria promoção — Hub Promoções
      description: >-
        Cria promoção localmente e dispara sincronização assíncrona com o canal. Só funciona para tipos com
        `SellerCreate = 1`. Os demais tipos são gerados no canal e apenas recebidos no idworks. Para `Campanha vendedor`
        (tipo 8) o nome é único entre promoções ativas/programadas da mesma integração.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubProductPromotionCreate'
        description: >-
          Promoção a cadastrar. **Só funciona** para tipos com `SellerCreate = 1` no catálogo (atualmente `Desconto
          individual` e `Campanha vendedor`). Para `Campanha vendedor`, `PromotionName`, `DateFrom` e `DateTo` são
          obrigatórios; `SellerPercent` precisa ficar entre `0.10` e `0.70`; janela máxima de 31 dias.
      responses:
        '200':
          description: Promoção criada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubProductPromotionDetail'
        '400':
          description: >-
            `[BadRequest] - Empresa não existe` · `[BadRequest] - Tipo de promoção não pode ser criada` · `[BadRequest]
            - Obrigatório data de neste tipo de promoção` · `[BadRequest] - Obrigatório data até neste tipo de promoção`
            · `[BadRequest] - Nome da promoção não pode ser maior que 25 caracteres` · `[BadRequest] - Intervalo de data
            tem que ser inferior a 31 dias` · `[BadRequest] - Data até precisa ser maior que hoje` · `[BadRequest] -
            Desconto precisa ser maior que 10%` · `[BadRequest] - Desconto precisa ser menor que 70%` · `[BadRequest] -
            Já existe uma promoção ativa/programada com o mesmo nome`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/product/promotion/{idhubproductpromotion}:
    get:
      operationId: hubProductPromotionGet
      tags:
        - Hub — Anúncios
      summary: Detalha promoção — Hub Promoções
      description: >-
        Retorna a promoção com seus anúncios. A lista de anúncios é paginada em blocos de 5000 — use `Page` para
        navegar. `HasNextPageItems = 1` indica que há mais itens.
      parameters:
        - name: idhubproductpromotion
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da promoção de produto no hub.
        - name: Page
          in: query
          required: false
          schema:
            type: integer
          description: Página de anúncios (cada página = 5000 anúncios).
      responses:
        '200':
          description: Promoção detalhada. Array vazio quando não existe ou pertence a outra empresa.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubProductPromotionDetail'
    put:
      operationId: hubProductPromotionPut
      tags:
        - Hub — Anúncios
      summary: Atualiza promoção — Hub Promoções
      description: >-
        Atualiza dados da promoção e dispara nova sincronização. Para `Campanha vendedor` em status `Iniciado` a
        `DateFrom` não pode ser alterada. Mesmas validações de datas/percentual da criação.
      parameters:
        - name: idhubproductpromotion
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da promoção de produto no hub.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubProductPromotionUpdate'
        description: >-
          Atualização da promoção. Mesmas regras de criação por tipo. Em `Campanha vendedor` já `Iniciado`
          (`IDTypeHubProductPromotionStatus = 2`), `DateFrom` não pode mais ser alterado.
      responses:
        '200':
          description: Promoção atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubProductPromotionDetail'
        '400':
          description: >-
            `[BadRequest] - Promoção não existe` · `[BadRequest] - Data inicio não pode ser alterada em promoção com
            status iniciada` · `[BadRequest] - Data inicio precisa ser maior ou igual a hoje` · `[BadRequest] - Já
            existe uma promoção ativa/programada com o mesmo nome`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: hubProductPromotionDelete
      tags:
        - Hub — Anúncios
      summary: Exclui promoção — Hub Promoções
      description: >-
        Solicita exclusão da promoção no canal (assíncrono). Só funciona para `Campanha vendedor` (tipo 8) — demais
        tipos não permitem exclusão pela API.
      parameters:
        - name: idhubproductpromotion
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da promoção de produto no hub.
      responses:
        '200':
          description: Pedido de exclusão registrado. Promoção retorna em status `Exclusão pendente` enquanto o canal processa.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubProductPromotionDetail'
        '400':
          description: '`[BadRequest] - Promoção não existe` · `[BadRequest] - Tipo de promoção não permite excluir`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/product/promotion/{idhubproductpromotion}/item:
    post:
      operationId: hubProductPromotionItemPost
      tags:
        - Hub — Anúncios
      summary: Adiciona anúncio à promoção — Hub Promoções
      description: >-
        Adiciona um anúncio à promoção e dispara sincronização. Só funciona quando a promoção é `SellerCreate = 1`. Para
        `Desconto individual` (tipo 3) o sistema consulta o anúncio no canal — preço promocional precisa ficar entre 20%
        e 95% do preço anunciado e o anúncio não pode estar em revisão.
      parameters:
        - name: idhubproductpromotion
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da promoção de produto no hub.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubProductPromotionItemCreate'
        description: >-
          Inclui um anúncio na promoção. Só permitido em promoções com `SellerCreate = 1`. Para `Desconto individual` o
          sistema valida que o desconto fica entre 5% e 80% do preço anunciado; `DateFrom` e `DateTo` são obrigatórios e
          o intervalo máximo é de 31 dias.
      responses:
        '200':
          description: Anúncio adicionado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubProductPromotionAdvertisement'
        '400':
          description: >-
            `[BadRequest] - Promoção não localizada` · `[BadRequest] - Promoção não permite adicionar itens` ·
            `[BadRequest] - Este anúncio já esta na promoção e não pode ser adicionado novamente. Editar o mesmo` ·
            `[BadRequest] - Anúncio não encontrado` · `[BadRequest] - Anúncio não localizado no canal` · `[BadRequest] -
            Item esta em revisão e não pode ser incluído promoção` · `[BadRequest] - Desconto precisa ser superior a 5%.
            Preço anúnciado do item no canal é {preço}` · `[BadRequest] - Desconto não pode ser maior que 80%. Preço
            anúnciado do item no canal é {preço}` · `[BadRequest] - Problema ao baixar anúncio no canal. Tentar
            novamente em instantes`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/product/promotion/{idhubproductpromotion}/item/{idhubproductpromotionitem}:
    put:
      operationId: hubProductPromotionItemPut
      tags:
        - Hub — Anúncios
      summary: Atualiza anúncio na promoção — Hub Promoções
      description: >-
        Atualiza um anúncio dentro da promoção e dispara nova sincronização. **Disponível apenas** para integrações de
        promoção (`IDTypeCompanyIntegration = 10`). Os campos aceitos e as validações dependem do tipo da promoção:
        `Tradicional` valida preço acima de 0 e abaixo do original e do mínimo do canal; `Oferta relâmpago` valida preço
        e quantidade dentro dos limites do canal; `Oferta do dia` valida apenas preço; `Desconto individual` valida
        intervalo de datas (máx 31 dias); `Campanha vendedor` aceita só `SellingPrice` quando não há percentual fixo na
        promoção. Quando há `DateDeadline` na promoção, ela precisa estar no futuro.
      parameters:
        - name: idhubproductpromotion
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da promoção de produto no hub.
        - name: idhubproductpromotionitem
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do item da promoção de produto no hub.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubProductPromotionItemUpdate'
        description: >-
          Atualização do anúncio na promoção. Os campos aceitos e as validações variam por tipo: preço, datas,
          quantidade. Valores fora dos limites mínimos/máximos retornados pelo canal são rejeitados.
      responses:
        '200':
          description: Anúncio atualizado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubProductPromotionAdvertisement'
        '400':
          description: >-
            `[BadRequest] - Item promoção não existe` · `[BadRequest] - Integração não tem recurso de promoção` ·
            `[BadRequest] - Data limite para participar da promoção já terminou` · `[BadRequest] - Tipo de promoção não
            pertence a integração` · `[BadRequest] - Valor da oferta precisa ser maior que 0` · `[BadRequest] - Valor
            promocional precisa ser menor que preço base do item` · `[BadRequest] - Valor promocional não pode ser
            inferior ao valor mínimo do item em campanha, {valor}` · `[BadRequest] - Quantidade disponível precisa ser
            maior que 0` · `[BadRequest] - Valor da oferta não pode ser menor que valor mínimo de {valor}` ·
            `[BadRequest] - Valor da oferta não pode ser maior que valor maximo de {valor}` · `[BadRequest] - Quantidade
            de estoque precisa ser maior que {qty}` · `[BadRequest] - Quantidade de estoque precisa ser menor que {qty}`
            · `[BadRequest] - Intervalo de data tem que ser inferior a 31 dias`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: hubProductPromotionItemDelete
      tags:
        - Hub — Anúncios
      summary: Remove anúncio da promoção — Hub Promoções
      description: >-
        Remove o anúncio da promoção e dispara sincronização para retirar do canal. Disponível apenas para integrações
        de promoção (`IDTypeCompanyIntegration = 10`). O item entra em status `Pendente` até o canal confirmar.
      parameters:
        - name: idhubproductpromotion
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da promoção de produto no hub.
        - name: idhubproductpromotionitem
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do item da promoção de produto no hub.
      responses:
        '200':
          description: Anúncio em remoção.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubProductPromotionAdvertisement'
        '400':
          description: '`[BadRequest] - Item promoção não existe` · `[BadRequest] - Integração não tem recurso de promoção`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/hub/product/promotion/status:
    get:
      operationId: typeHubProductPromotionStatusList
      tags:
        - Hub — Tipos de Referência
      summary: Lista status de promoção — Hub Promoções
      description: >-
        Lista os status possíveis de promoção do hub: `1` Ativo · `2` Iniciado · `3` Programada · `4` Candidato · `5`
        Finalizada · `6` Ativação pendente · `7` Exclusão pendente · `8` Excluido.
      parameters:
        - name: IDTypeCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por integração (atualmente todos os status valem para todas as integrações).
      responses:
        '200':
          description: Status.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeHubProductPromotionStatusItem'
  /type/hub/product/promotion/type:
    get:
      operationId: typeHubProductPromotionList
      tags:
        - Hub — Tipos de Referência
      summary: Lista tipos de promoção — Hub Promoções
      description: >-
        Lista os tipos de promoção do hub (`Tradicional`, `Campanha vendedor`, `Oferta relâmpago`, `Oferta do dia`,
        `Desconto individual`, etc.). Use `SellerCreate=1` para listar apenas tipos que o vendedor pode criar
        diretamente pela API.
      parameters:
        - name: IDTypeCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
          description: 'Filtra por integração (ex.: `10` para Mercado Livre).'
        - name: SellerCreate
          in: query
          required: false
          schema:
            type: integer
          description: Filtra tipos que o vendedor pode criar localmente. `1` apenas criáveis · `0` apenas recebidos.
      responses:
        '200':
          description: Tipos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeHubProductPromotionItem'
  /sku/collection:
    get:
      operationId: skuCollectionList
      tags:
        - Coleções
      summary: Lista coleções
      description: >-
        Lista as coleções da empresa, ordenadas por nome (`StockKeepingUnitCollectionName ASC`). Em contexto multi-conta
        (`accountname = all`), traz todas as contas acessíveis.
      parameters:
        - name: StockKeepingUnitCollectionName
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo nome da coleção.
        - name: IDStockKeepingUnitCollection
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo id da coleção.
      responses:
        '200':
          description: Lista de coleções.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuCollectionItem'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: skuCollectionPost
      tags:
        - Coleções
      summary: Cria coleção
      description: >-
        Cria uma coleção para a empresa autenticada. Após inserir, reinvoca `skuCollectionList` e devolve a coleção
        criada (em formato de lista).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuCollectionCreate'
        description: Dados da coleção (grupo de SKUs com finalidade de exibição/agrupamento) a cadastrar.
      responses:
        '200':
          description: Coleção criada (devolve a coleção em formato de lista).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuCollectionItem'
        '400':
          description: '`[BadRequest] - Empresa não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/collection/{idstockkeepingunitcollection}:
    put:
      operationId: skuCollectionPut
      tags:
        - Coleções
      summary: Atualiza coleção
      description: >-
        Renomeia uma coleção da empresa autenticada. Após atualizar, reinvoca `skuCollectionList` e devolve a coleção
        atualizada (em formato de lista).
      parameters:
        - name: idstockkeepingunitcollection
          in: path
          required: true
          schema:
            type: integer
          description: Id da coleção.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuCollectionCreate'
        description: Atualiza a coleção. Mesmo schema do POST.
      responses:
        '200':
          description: Coleção atualizada (devolve a coleção em formato de lista).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuCollectionItem'
        '400':
          description: '`[BadRequest] - Coleção não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: skuCollectionDelete
      tags:
        - Coleções
      summary: Exclui coleção
      description: >-
        Exclui uma coleção da empresa autenticada. **Bloqueado** quando a coleção tem SKUs associados — é preciso
        remover os vínculos antes (endpoints `/sku/{idsku}/collection`).
      parameters:
        - name: idstockkeepingunitcollection
          in: path
          required: true
          schema:
            type: integer
          description: Id da coleção.
      responses:
        '200':
          description: 'Coleção excluída. Corpo: string `"sucesso"`.'
          content:
            application/json:
              schema:
                type: string
                example: sucesso
        '400':
          description: >-
            `[BadRequest] - Coleção não existe`; `[BadRequest] - Coleção esta associada a SKUs, remover o vínculo antes
            de excluir a coleção`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/group:
    get:
      operationId: skuGroupList
      tags:
        - Grupos de SKU
      summary: Lista grupos SKU
      description: >-
        Lista os grupos da empresa, ordenados por nome (`SkuGroupName ASC`), paginados em blocos de 10000. Em contexto
        multi-conta (`accountname = all`), traz todas as contas acessíveis.
      parameters:
        - name: SkuGroupName
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo nome do grupo (igualdade).
        - name: Search
          in: query
          required: false
          schema:
            type: string
          description: Busca parcial (`LIKE`) no nome do grupo.
        - name: IDStockKeepingUnitGroup
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo id do grupo.
        - name: Page
          in: query
          required: false
          schema:
            type: integer
          description: Página (offset = `Page * 10000`).
      responses:
        '200':
          description: Lista de grupos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuGroupItem'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: skuGroupPost
      tags:
        - Grupos de SKU
      summary: Cria grupo SKU
      description: >-
        Cria um grupo para a empresa autenticada. Após inserir, reinvoca `skuGroupList` e devolve o grupo criado (em
        formato de lista).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuGroupCreate'
        description: Dados do grupo de SKUs (agrupamento operacional, distinto da coleção) a cadastrar.
      responses:
        '200':
          description: Grupo criado (devolve o grupo em formato de lista).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuGroupItem'
        '400':
          description: '`[BadRequest] - Empresa não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/group/{idstockkeepingunitgroup}:
    put:
      operationId: skuGroupPut
      tags:
        - Grupos de SKU
      summary: Atualiza grupo SKU
      description: >-
        Renomeia um grupo da empresa autenticada. Após atualizar, reinvoca `skuGroupList` e devolve o grupo atualizado
        (em formato de lista).
      parameters:
        - name: idstockkeepingunitgroup
          in: path
          required: true
          schema:
            type: integer
          description: Id do grupo.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuGroupCreate'
        description: Atualiza o grupo. Mesmo schema do POST.
      responses:
        '200':
          description: Grupo atualizado (em formato de lista).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuGroupItem'
        '400':
          description: '`[BadRequest] - Grupo não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: skuGroupDelete
      tags:
        - Grupos de SKU
      summary: Exclui grupo SKU
      description: >-
        Exclui um grupo da empresa autenticada. **Bloqueado** quando o grupo tem SKUs associados ou códigos similares
        vinculados.
      parameters:
        - name: idstockkeepingunitgroup
          in: path
          required: true
          schema:
            type: integer
          description: Id do grupo.
      responses:
        '200':
          description: 'Grupo excluído. Corpo: string `"sucesso"`.'
          content:
            application/json:
              schema:
                type: string
                example: sucesso
        '400':
          description: >-
            `[BadRequest] - Grupo não existe`; `[BadRequest] - Grupo esta associado a SKUs, remover o vínculo antes de
            excluir o grupo`; `[BadRequest] - Grupo esta associado a códigos similares, remover o vínculo antes de
            excluir o grupo`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/similar-code:
    get:
      operationId: skuSimilarCodeList
      tags:
        - Códigos Similares
      summary: Lista códigos similares
      description: >-
        Lista os códigos similares da empresa autenticada com o grupo (`SkuGroupName`) e a conta (`AccountName`) já
        resolvidos. Em contexto multi-conta (`accountname = all`), traz todas as contas acessíveis. Ordenado por
        `SkuGroupName ASC`, paginado em blocos de 10000.
      parameters:
        - name: SkuGroupName
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo nome exato do grupo SKU (igualdade).
        - name: IDStockKeepingUnitGroup
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo id do grupo SKU.
        - name: SkuSimilarCode
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo código similar (igualdade).
        - name: SkuSimilarCodeTag
          in: query
          required: false
          schema:
            type: string
          description: Filtra pela tag do código similar (igualdade).
        - name: IDStockKeepingUnitSimilarCode
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo id do código similar.
        - name: Page
          in: query
          required: false
          schema:
            type: integer
          description: Página (offset = `Page * 10000`).
      responses:
        '200':
          description: Lista de códigos similares.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuSimilarCodeItem'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: skuSimilarCodePost
      tags:
        - Códigos Similares
      summary: Cria código similar
      description: >-
        Cria um código similar vinculado a um grupo SKU da empresa autenticada. Valida que o grupo existe e pertence à
        empresa, e que `SkuSimilarCode` ainda não existe no grupo. Após inserir, reinvoca `skuSimilarCodeList` e devolve
        o código criado (em formato de lista).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuSimilarCodeCreate'
        description: >-
          Cadastro de código similar — código de referência alternativo que permite localizar o SKU por código de
          fornecedor ou marketplace externo.
      responses:
        '200':
          description: Código criado (devolve o código em formato de lista).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuSimilarCodeItem'
        '400':
          description: '`[BadRequest] - Grupo não existe`; `[BadRequest] - Já existe esse código cadastrado para o grupo`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/similar-code/tag:
    get:
      operationId: skuSimilarCodeTagList
      tags:
        - Códigos Similares
      summary: Lista tags de códigos similares
      description: >-
        Lista as tags (`SkuSimilarCodeTag`) já em uso pelos códigos similares da empresa autenticada, em ordem
        alfabética. Ignora valores nulos e vazios. Usada para popular o autocomplete do campo `SkuSimilarCodeTag` na
        tela.
      responses:
        '200':
          description: Lista de tags distintas.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuSimilarCodeTagItem'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/similar-code/{idstockkeepingunitsimilarcode}:
    put:
      operationId: skuSimilarCodePut
      tags:
        - Códigos Similares
      summary: Atualiza código similar
      description: >-
        Atualiza grupo, código e/ou tag de um código similar da empresa autenticada. Quando `SkuSimilarCode` muda,
        valida que o novo código ainda não existe no grupo. Quando `IDStockKeepingUnitGroup` muda, valida que o novo
        grupo pertence à empresa. Após atualizar, reinvoca `skuSimilarCodeList` e devolve o registro (em formato de
        lista).
      parameters:
        - name: idstockkeepingunitsimilarcode
          in: path
          required: true
          schema:
            type: integer
          description: Id do código similar.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuSimilarCodeCreate'
        description: Atualiza o código similar. Mesmo schema do POST.
      responses:
        '200':
          description: Código atualizado (em formato de lista).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuSimilarCodeItem'
        '400':
          description: >-
            `[BadRequest] - Código similar não existe`; `[BadRequest] - Grupo não existe`; `[BadRequest] - Já existe
            esse código cadastrado para o grupo`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: skuSimilarCodeDelete
      tags:
        - Códigos Similares
      summary: Exclui código similar
      description: >-
        Exclui fisicamente o código similar da empresa autenticada. Sem regras de bloqueio — o vínculo é apenas com o
        grupo SKU, que não trava a exclusão.
      parameters:
        - name: idstockkeepingunitsimilarcode
          in: path
          required: true
          schema:
            type: integer
          description: Id do código similar.
      responses:
        '200':
          description: 'Código excluído. Corpo: string `"Sucesso"`.'
          content:
            application/json:
              schema:
                type: string
                example: Sucesso
        '400':
          description: '`[BadRequest] - Código similar não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/sku/variation:
    get:
      operationId: typeSkuVariationList
      tags:
        - Tipos — SKU
      summary: Lista variações
      description: >-
        Lista as variações Ativas da empresa, ordenadas por `ProductVariationOrder` e `ProductVariation`. Cada item já
        traz a grade de valores no campo `TypeProductVariation`.
      responses:
        '200':
          description: Lista de variações.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeSkuVariationItem'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: typeSkuVariationPost
      tags:
        - Tipos — SKU
      summary: Cria variação
      description: >-
        Cria uma variação para a empresa autenticada. Após inserir, reinvoca `typeSkuVariationList` e devolve a lista
        atualizada.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TypeSkuVariationCreate'
        description: >-
          Dados da variação a cadastrar. `ProductVariation` (nome) e `IDTypeProductVariationType` (tipo padrão — Cor,
          Tamanho, Voltagem…) obrigatórios. `ProductVariationOrder` é a ordem de exibição (única por empresa); quando
          omitida, recebe o próximo número após o maior `ProductVariationOrder` já cadastrado.
      responses:
        '200':
          description: Variação criada (devolve a lista de variações).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeSkuVariationItem'
        '400':
          description: >-
            `[BadRequest] - Empresa não existe`; `[BadRequest] - Variação padrão não existe`; `[BadRequest] - Já existe
            variação com essa ordem <n>`; `[BadRequest] - Problema ao adicionar variação, validar se todos os dados
            obrigatórios foram informados (tipo, nome e ordem)`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/sku/variation/type:
    get:
      operationId: typeProductVariationType
      tags:
        - Tipos — SKU
      summary: Lista tipos padrão de variação
      description: >-
        Lista os **tipos padrão** de variação do sistema (Cor, Tamanho, Voltagem, Material, Sabor…), ordenados por nome.
        Lista fixa, igual para todas as empresas — usada para preencher o campo `IDTypeProductVariationType` ao
        criar/editar uma variação.
      responses:
        '200':
          description: Lista de tipos padrão.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeProductVariationTypeItem'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/sku/variation/{idtypeskuvariation}:
    get:
      operationId: typeSkuVariationGet
      tags:
        - Tipos — SKU
      summary: Detalha uma variação
      description: Retorna a variação da empresa autenticada com a sua grade de valores. Devolve `[]` quando a variação não existe.
      parameters:
        - name: idtypeskuvariation
          in: path
          required: true
          schema:
            type: integer
          description: Id da variação.
      responses:
        '200':
          description: Variação encontrada (lista de 1 item) ou `[]`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeSkuVariationDetail'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    put:
      operationId: typeSkuVariationPut
      tags:
        - Tipos — SKU
      summary: Atualiza variação
      description: >-
        Atualiza nome, tipo e/ou ordem de uma variação (atualização parcial). Após atualizar, reinvoca
        `typeSkuVariationList` e devolve a lista.
      parameters:
        - name: idtypeskuvariation
          in: path
          required: true
          schema:
            type: integer
          description: Id da variação.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TypeSkuVariationCreate'
        description: >-
          Atualização parcial da variação (`ProductVariation`, `IDTypeProductVariationType`, `ProductVariationOrder`).
          `ProductVariationOrder` mantém a regra de unicidade por empresa.
      responses:
        '200':
          description: Variação atualizada (devolve a lista de variações).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeSkuVariationItem'
        '400':
          description: >-
            `[BadRequest] - Variação não existe`; `[BadRequest] - Variação padrão não existe`; `[BadRequest] - Já existe
            variação com essa ordem <n>`; `[BadRequest] - Problema ao atualizar variação, validar se todos os dados
            obrigatórios foram informados (tipo, nome e ordem)`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: typeSkuVariationDelete
      tags:
        - Tipos — SKU
      summary: Exclui variação
      description: >-
        Exclui uma variação da empresa autenticada (a grade é removida em cascata). **Bloqueado** quando há SKU usando a
        variação. Após excluir, reinvoca `typeSkuVariationList` e devolve a lista.
      parameters:
        - name: idtypeskuvariation
          in: path
          required: true
          schema:
            type: integer
          description: Id da variação.
      responses:
        '200':
          description: Variação excluída (devolve a lista de variações).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeSkuVariationItem'
        '400':
          description: >-
            `[BadRequest] - Variação não existe`; `[BadRequest] - Existe SKU com essa variação. Remover do SKU antes de
            excluir`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/sku/variation/{idtypeskuvariation}/value:
    get:
      operationId: skuVariationValueList
      tags:
        - Tipos — SKU
      summary: Lista valores da grade
      description: Lista os valores da grade de uma variação, ordenados por `ProductVariationValueOrder` e nome.
      parameters:
        - name: idtypeskuvariation
          in: path
          required: true
          schema:
            type: integer
          description: Id da variação.
      responses:
        '200':
          description: Lista de valores da grade.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GradeValueItem'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: skuVariationValuePost
      tags:
        - Tipos — SKU
      summary: Cria valor da grade
      description: >-
        Adiciona um valor à grade de uma variação. Após inserir, reinvoca `typeSkuVariationGet` e devolve o detalhe da
        variação.
      parameters:
        - name: idtypeskuvariation
          in: path
          required: true
          schema:
            type: integer
          description: Id da variação.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GradeValueCreate'
        description: >-
          Dados do valor da grade a cadastrar. `TypeProductVariationValue` (nome do valor — ex.: `Azul`, `M`)
          obrigatório. `ProductVariationValueOrder` é a ordem dentro da grade (única por variação). O par
          (`TypeProductVariationValue`, `IDTypeProductVariation`) precisa ser inédito.
      responses:
        '200':
          description: Valor criado (devolve o detalhe da variação).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeSkuVariationDetail'
        '400':
          description: '`[BadRequest] - Variação não existe`; `[BadRequest] - Já existe esta grade para a variação`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/sku/variation/{idtypeskuvariation}/value/{idtypeskuvariationvalue}:
    put:
      operationId: skuVariationValuePut
      tags:
        - Tipos — SKU
      summary: Atualiza valor da grade
      description: >-
        Atualiza nome e ordem de um valor da grade. Após atualizar, reinvoca `typeSkuVariationGet` e devolve o detalhe
        da variação.
      parameters:
        - name: idtypeskuvariation
          in: path
          required: true
          schema:
            type: integer
          description: Id da variação.
        - name: idtypeskuvariationvalue
          in: path
          required: true
          schema:
            type: integer
          description: Id do valor da grade.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GradeValueCreate'
        description: >-
          Atualiza o valor da grade (`TypeProductVariationValue`, `ProductVariationValueOrder`). Mantém a regra de
          unicidade do par (`TypeProductVariationValue`, `IDTypeProductVariation`).
      responses:
        '200':
          description: Valor atualizado (devolve o detalhe da variação).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeSkuVariationDetail'
        '400':
          description: '`[BadRequest] - Variação não existe`; `[BadRequest] - Já existe esta grade para a variação`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: skuVariationValueDelete
      tags:
        - Tipos — SKU
      summary: Exclui valor da grade
      description: >-
        Remove um valor da grade. **Bloqueado** quando há SKU usando o valor. Após excluir, reinvoca
        `typeSkuVariationGet` e devolve o detalhe da variação.
      parameters:
        - name: idtypeskuvariation
          in: path
          required: true
          schema:
            type: integer
          description: Id da variação.
        - name: idtypeskuvariationvalue
          in: path
          required: true
          schema:
            type: integer
          description: Id do valor da grade.
      responses:
        '200':
          description: Valor excluído (devolve o detalhe da variação).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeSkuVariationDetail'
        '400':
          description: >-
            `[BadRequest] - Grade não existe`; `[BadRequest] - Existe SKU com essa grade. Remover do SKU antes de
            excluir`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /category:
    get:
      operationId: categoryList
      tags:
        - Categorias de Produto
      summary: Lista categorias
      description: >-
        Lista as categorias ativas da empresa autenticada. Com `Type=Tree` (modo usado pela tela) retorna a árvore
        aninhada, cada nó com `Children`. Sem `Type=Tree`, retorna uma lista achatada em que cada item traz
        `CategoryTree` — a trilha do caminho da raiz até a categoria (`Pai -> Filho -> Neto`).
      parameters:
        - name: Type
          in: query
          required: false
          schema:
            type: string
          description: >-
            Use `Tree` para receber a árvore aninhada com `Children`. Omitido, retorna a lista achatada com a trilha
            `CategoryTree`.
      responses:
        '200':
          description: Árvore de categorias (modo `Type=Tree`).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CategoryTreeNode'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: categoryPost
      tags:
        - Categorias de Produto
      summary: Cria categoria
      description: >-
        Cria uma categoria para a empresa autenticada. Quando `Description`, `Keywords` ou `Title` não são informados,
        assumem o valor de `Name`. Após inserir, reinvoca `categoryGet` e devolve a categoria criada (em formato de
        lista).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoryCreate'
        description: >-
          Dados da categoria a cadastrar. Apenas `Name` é obrigatório; `Description`, `Keywords` e `Title` herdam o
          valor de `Name` quando ausentes ou vazios. `ShowInStoreFront`, `ShowBrandFilter` e `ActiveStoreFrontLink`
          assumem `1` por default. `IDCategoryFather` cria categoria filha; `null`/ausente cria categoria de topo.
      responses:
        '200':
          description: Categoria criada (em formato de lista).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CategoryDetail'
        '400':
          description: '`[BadRequest] - Company não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /category/{idcategory}:
    get:
      operationId: categoryGet
      tags:
        - Categorias de Produto
      summary: Detalha categoria
      description: >-
        Retorna os dados completos de uma categoria da empresa autenticada, incluindo `CategoryFather` (nome da
        categoria pai). Devolve uma lista vazia quando a categoria não existe.
      parameters:
        - name: idcategory
          in: path
          required: true
          schema:
            type: integer
          description: Id da categoria.
      responses:
        '200':
          description: Dados da categoria (em formato de lista; vazia se não existir).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CategoryDetail'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    put:
      operationId: categoryPut
      tags:
        - Categorias de Produto
      summary: Atualiza categoria
      description: >-
        Atualização parcial: apenas os campos enviados são alterados. Após atualizar, reinvoca `categoryGet` e devolve a
        categoria atualizada (em formato de lista).
      parameters:
        - name: idcategory
          in: path
          required: true
          schema:
            type: integer
          description: Id da categoria.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoryUpdate'
        description: >-
          Campos da categoria a atualizar. Todos opcionais — apenas os enviados são aplicados. `IDCategoryFather` aceita
          `null` explícito para mover a categoria para o topo, e não pode ser igual ao próprio id (categoria não pode
          ser superior dela mesma) nem apontar para categoria de outra empresa.
      responses:
        '200':
          description: Categoria atualizada (em formato de lista).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CategoryDetail'
        '400':
          description: >-
            `[BadRequest] - Categoria não pode ser superior dela mesma`; `[BadRequest] - Categoria pai não localizada`;
            `[BadRequest] - Categoria não existe`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: categoryDelete
      tags:
        - Categorias de Produto
      summary: Exclui categoria
      description: >-
        Exclusão lógica (`Status = 0`) de uma categoria da empresa autenticada. **Bloqueada** quando a categoria tem
        produtos ativos vinculados ou quando possui subcategorias.
      parameters:
        - name: idcategory
          in: path
          required: true
          schema:
            type: integer
          description: Id da categoria.
      responses:
        '200':
          description: 'Categoria excluída. Corpo: string `"sucesso"`.'
          content:
            application/json:
              schema:
                type: string
                example: sucesso
        '400':
          description: >-
            `[BadRequest] - Categoria possui produto ativos. Alterar a categoria no cadastro do item antes de excluir a
            categoria`; `[BadRequest] - Categoria possui filhos (categoria inferior) que precisam ser removidas`;
            `[BadRequest] - Categoria não existe`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /category/{idcategory}/sku-specification:
    get:
      operationId: skuSpecificationFieldList
      tags:
        - Especificações por Categoria
      summary: Lista especificações da categoria
      description: >-
        Lista as especificações (campos) ativas da categoria, **incluindo as herdadas das categorias ancestrais** (a
        herança sobe a árvore). Cada campo traz seus valores em `FieldValue`.
      parameters:
        - name: idcategory
          in: path
          required: true
          schema:
            type: integer
          description: Id da categoria.
      responses:
        '200':
          description: Especificações da categoria e ancestrais.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SpecFieldItem'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: skuSpecificationFieldIdPost
      tags:
        - Especificações por Categoria
      summary: Cria especificação na categoria
      description: >-
        Cria uma especificação (campo) na categoria. Após inserir, reinvoca `skuSpecificationFieldIdGet` e devolve o
        campo criado (em formato de lista).
      parameters:
        - name: idcategory
          in: path
          required: true
          schema:
            type: integer
          description: Id da categoria.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpecFieldCreate'
        description: >-
          Dados da especificação a cadastrar na categoria. `FieldName` e `IDStockKeepingUnitSpecificationsFieldTypes`
          são obrigatórios. `IDFieldExternal`, quando informado, precisa ser único dentro da categoria — o sistema
          rejeita duplicidade com erro de validação.
      responses:
        '200':
          description: Especificação criada (em formato de lista).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SpecFieldDetail'
        '400':
          description: >-
            `[BadRequest] - Já existe outra especificação com mesmo código externo`; `[BadRequest] - Categoria não
            existe`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /category/{idcategory}/sku-specification/{idstockkeepingunitspecificationsfieldid}:
    get:
      operationId: skuSpecificationFieldIdGet
      tags:
        - Especificações por Categoria
      summary: Detalha especificação
      description: >-
        Retorna uma especificação ativa da categoria com seus valores em `FieldValue`. Devolve uma lista vazia quando
        não existe.
      parameters:
        - name: idcategory
          in: path
          required: true
          schema:
            type: integer
          description: Id da categoria.
        - name: idstockkeepingunitspecificationsfieldid
          in: path
          required: true
          schema:
            type: integer
          description: Id da especificação (campo) da categoria.
      responses:
        '200':
          description: Dados da especificação (em formato de lista; vazia se não existir).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SpecFieldDetail'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    put:
      operationId: skuSpecificationFieldIdPut
      tags:
        - Especificações por Categoria
      summary: Atualiza especificação
      description: >-
        Atualização parcial da especificação: apenas os campos enviados são alterados. Após atualizar, reinvoca
        `skuSpecificationFieldIdGet` e devolve o campo (em formato de lista).
      parameters:
        - name: idcategory
          in: path
          required: true
          schema:
            type: integer
          description: Id da categoria.
        - name: idstockkeepingunitspecificationsfieldid
          in: path
          required: true
          schema:
            type: integer
          description: Id da especificação (campo) da categoria.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpecFieldUpdate'
        description: >-
          Campos da especificação a atualizar. Todos opcionais. `IDFieldExternal` mantém a regra de unicidade dentro da
          categoria. As flags (`IsFilter`, `IsActive`, `IsRequired`, etc.) usam `1`/`0`.
      responses:
        '200':
          description: Especificação atualizada (em formato de lista).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SpecFieldDetail'
        '400':
          description: >-
            `[BadRequest] - ID Externo já existe para o campo: <FieldName>`; `[BadRequest] - Sku Specification não
            existe`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: skuSpecificationFieldValuePost
      tags:
        - Especificações por Categoria
      summary: Adiciona valor à especificação
      description: >-
        Adiciona um valor a uma especificação do tipo lista. Após inserir, reinvoca `skuSpecificationFieldIdGet` e
        devolve o campo com seus valores (em formato de lista).
      parameters:
        - name: idcategory
          in: path
          required: true
          schema:
            type: integer
          description: Id da categoria.
        - name: idstockkeepingunitspecificationsfieldid
          in: path
          required: true
          schema:
            type: integer
          description: Id da especificação (campo) da categoria.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpecValueCreate'
        description: >-
          Adiciona um valor à especificação (lista de opções). `Value` obrigatório. `IDFieldValueExternal` e `Position`
          são opcionais e gravados como `null` quando ausentes.
      responses:
        '200':
          description: Valor adicionado; especificação retornada (em formato de lista).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SpecFieldDetail'
        '400':
          description: '`[BadRequest] - Sku Specification não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: skuSpecificationFieldIdDelete
      tags:
        - Especificações por Categoria
      summary: Exclui especificação
      description: Exclusão lógica (`Status = 0`) de uma especificação da categoria.
      parameters:
        - name: idcategory
          in: path
          required: true
          schema:
            type: integer
          description: Id da categoria.
        - name: idstockkeepingunitspecificationsfieldid
          in: path
          required: true
          schema:
            type: integer
          description: Id da especificação (campo) da categoria.
      responses:
        '200':
          description: Especificação excluída.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Message:
                    type: string
                    example: Sucesso
                    description: Mensagem de confirmação da remoção (`"sucesso"` em caso de remoção bem-sucedida).
        '400':
          description: '`[BadRequest] - Sku Specification Field não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /category/{idcategory}/sku-specification/{idstockkeepingunitspecificationsfieldid}/{idstockkeepingunitspecificationsfieldvalues}:
    put:
      operationId: skuSpecificationFieldValuePut
      tags:
        - Especificações por Categoria
      summary: Atualiza valor da especificação
      description: >-
        Atualiza um valor de uma especificação. Após atualizar, reinvoca `skuSpecificationFieldIdGet` e devolve o campo
        (em formato de lista).
      parameters:
        - name: idcategory
          in: path
          required: true
          schema:
            type: integer
          description: Id da categoria.
        - name: idstockkeepingunitspecificationsfieldid
          in: path
          required: true
          schema:
            type: integer
          description: Id da especificação (campo) da categoria.
        - name: idstockkeepingunitspecificationsfieldvalues
          in: path
          required: true
          schema:
            type: integer
          description: Id do valor da especificação.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpecValueUpdate'
        description: Atualiza um valor da especificação. `Value` obrigatório. `IDFieldValueExternal` e `Position` opcionais.
      responses:
        '200':
          description: Valor atualizado; especificação retornada (em formato de lista).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SpecFieldDetail'
        '400':
          description: '`[BadRequest] - Sku Specification Value não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: skuSpecificationFieldValueDelete
      tags:
        - Especificações por Categoria
      summary: Exclui valor da especificação
      description: >-
        Exclui (físico) um valor de uma especificação. Após excluir, reinvoca `skuSpecificationFieldIdGet` e devolve o
        campo (em formato de lista).
      parameters:
        - name: idcategory
          in: path
          required: true
          schema:
            type: integer
          description: Id da categoria.
        - name: idstockkeepingunitspecificationsfieldid
          in: path
          required: true
          schema:
            type: integer
          description: Id da especificação (campo) da categoria.
        - name: idstockkeepingunitspecificationsfieldvalues
          in: path
          required: true
          schema:
            type: integer
          description: Id do valor da especificação.
      responses:
        '200':
          description: Valor excluído; especificação retornada (em formato de lista).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SpecFieldDetail'
        '400':
          description: '`[BadRequest] - Sku Specification Value não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/sku/specification/field-type:
    get:
      operationId: typeSkuSpecificationFieldTypeList
      tags:
        - Tipos — SKU
      summary: Lista tipos de campo de especificação
      description: >-
        Lista os tipos de preenchimento disponíveis para as especificações (texto, número, lista de opções etc.),
        ordenados por nome. Lista padrão do sistema, igual para todas as contas.
      responses:
        '200':
          description: Tipos de campo de especificação.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SpecFieldTypeItem'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/product:
    get:
      operationId: hubProductList
      tags:
        - Hub — Anúncios
      summary: Lista anúncios — Hub Anúncios
      description: >-
        Lista os anúncios (ofertas publicadas nos canais de venda) da empresa autenticada, agrupados por anúncio. Cada
        item traz o produto vinculado, canal, status, qualidade, preços e o array `HubSku` com as variações. Use
        `GroupByHubSku=1` para receber uma linha por variação em vez de uma por anúncio. Página de até 400 registros.
      parameters:
        - name: Page
          in: query
          required: false
          schema:
            type: integer
          description: Página (cada página = 400 registros).
        - name: Search
          in: query
          required: false
          schema:
            type: string
          description: >-
            Busca textual em código/nome do produto, código do anúncio (`IDProductHub`), código de referência
            (`IDSkuCompany`) e código de variação (`IDSkuHub`).
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra por integração (conta de canal) específica.
        - name: IDTypeCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: 'Filtra por tipo de canal (ex.: Mercado Livre, Shopee).'
        - name: IDSalesChannel
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra por canal de vendas.
        - name: IDProduct
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pelo SKU/produto vinculado.
        - name: IDSku
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra anúncios que contenham este SKU em alguma variação.
        - name: IDProductCompany
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo código de referência do produto (`IDSkuCompany`).
        - name: IDSkuCompany
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo código de referência da variação.
        - name: IDHubProduct
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pelo identificador interno do anúncio.
        - name: IDProductHub
          in: query
          required: false
          schema:
            type: string
          description: 'Filtra pelo código do anúncio no canal (ex.: `MLB123456789`).'
        - name: IDSkuHub
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo código da variação no canal.
        - name: SkuName
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo nome do produto (busca parcial).
        - name: BarCode
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo código de barras.
        - name: IDBrand
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pela marca.
        - name: IDTypeSku
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pelo tipo de produto.
        - name: IDStatus
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: >-
            Filtra pelo status do anúncio (`AdvertisementStatus`): `0` Inativo, `1` Ativo, `2` Fechado, `3` Pausado, `4`
            Em revisão, `5` Inabilitado canal.
        - name: HubProductSubStatus
          in: query
          required: false
          schema:
            type: integer
          description: Filtra pelo sub-status (mesma tabela de status).
        - name: Published
          in: query
          required: false
          schema:
            type: integer
          description: '`1` somente publicados no canal (com `IDProductHub`), `0` somente não publicados.'
        - name: HasProduct
          in: query
          required: false
          schema:
            type: integer
          description: '`1` somente anúncios vinculados a um produto, `0` somente sem vínculo.'
        - name: HasSku
          in: query
          required: false
          schema:
            type: integer
          description: '`1` somente anúncios com variação vinculada, `0` somente sem.'
        - name: HasManualPrice
          in: query
          required: false
          schema:
            type: integer
          description: '`1` somente anúncios com preço manual em alguma variação, `0` somente sem.'
        - name: Health
          in: query
          required: false
          schema:
            type: number
          description: Valor de qualidade do anúncio (%) usado com `HealthType`.
        - name: HealthType
          in: query
          required: false
          schema:
            type: string
          description: 'Comparador da qualidade: `greater` (maior que `Health`) ou `smaller` (menor que `Health`).'
        - name: AutopartsPendingCompatibility
          in: query
          required: false
          schema:
            type: integer
          description: 'Autopeças: `1` somente anúncios com compatibilidade pendente.'
        - name: AutopartsRequiredCompatibility
          in: query
          required: false
          schema:
            type: integer
          description: 'Autopeças: `1` somente anúncios que exigem lista de compatibilidade.'
        - name: GroupByHubSku
          in: query
          required: false
          schema:
            type: integer
          description: '`1` retorna uma linha por variação (item) em vez de uma por anúncio.'
      responses:
        '200':
          description: Lista de anúncios (ou de variações quando `GroupByHubSku=1`).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubProductListItem'
    post:
      operationId: hubProductPost
      tags:
        - Hub — Anúncios
      summary: Cria anúncio — Hub Anúncios
      description: >-
        Cria um anúncio para um produto em uma integração (canal). O anúncio nasce pendente de sincronização — um
        processo assíncrono o envia ao canal. As variações (`HubSku`) são geradas automaticamente a partir do produto:
        para um produto com grade de variação, uma variação por componente; caso contrário, uma única variação.


        Os campos disponíveis dependem do canal — itens como `ListingTypeId`, `ShippingMode`, `OfficialStore` e preço
        por quantidade são específicos do Mercado Livre.


        Para **duplicar** um anúncio existente, informe a query string `IDHubProduct` com o anúncio de origem (e
        `IDCompanyIntegration` no corpo com o canal de destino); nesse fluxo os arrays `HubSku`, `Autoparts`,
        `HubProductSpecification` e `HubProductSalesPolicy` são copiados.
      parameters:
        - name: IDHubProduct
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Anúncio de origem a duplicar. Quando informado, o corpo é montado a partir desse anúncio.
        - name: IgnoreHubSku
          in: query
          required: false
          schema:
            type: integer
          description: '`1` não cria automaticamente as variações (`HubSku`).'
        - name: NoInvoke
          in: query
          required: false
          schema:
            type: integer
          description: '`1` retorna apenas a string `"sucesso"` em vez do anúncio criado.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubProductCreate'
        description: >-
          Anúncio (produto no canal) a cadastrar. Estrutura completa em `HubProductCreate` — inclui dados gerais,
          especificações da categoria do canal, política comercial, imagens e (quando o anúncio é de autopeças) o
          vínculo com o catálogo de aplicação.
      responses:
        '200':
          description: Anúncio criado (mesma estrutura do GET por id) ou `"sucesso"` quando `NoInvoke=1`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubProductDetail'
        '400':
          description: >-
            `[BadRequest] - Integração não existe` · `[BadRequest] - Produto não existe` · `[BadRequest] - Produto sem
            componentes de variação` · `[BadRequest] - Já existe um anúncio com o mesmo codigo para essa integração` ·
            `[BadRequest] - Template de mensagem não encontrado` · `[BadRequest] - Anúncio para duplicar não encontrado`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/product/{idhubproduct}:
    get:
      operationId: hubProductGet
      tags:
        - Hub — Anúncios
      summary: Detalha anúncio — Hub Anúncios
      description: >-
        Retorna o detalhe completo de um anúncio: dados do canal, categoria, preços, status, qualidade, experiência de
        compra, avaliação, dados de catálogo, imagens, ficha técnica, variações (`HubSku`) e — para o Mercado Livre —
        preço por quantidade. A resposta é um array com um único objeto.
      parameters:
        - name: idhubproduct
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador interno do anúncio.
      responses:
        '200':
          description: Detalhe do anúncio (array com um objeto; vazio se não existir).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubProductDetail'
    put:
      operationId: hubProductPut
      tags:
        - Hub — Anúncios
      summary: Atualiza anúncio — Hub Anúncios
      description: >-
        Atualiza um anúncio (atualização parcial — só os campos enviados são alterados). A mudança é reenviada ao canal
        de forma assíncrona. Quando a parametrização de atualização automática de preço está ativa e o canal aceita
        preço, alterar `PriceSellSet`/`PriceListSet` dispara o envio do preço.


        Regras: a categoria de um anúncio que já teve vendas no Mercado Livre não pode ser alterada; o preço a nível de
        anúncio fica bloqueado enquanto alguma variação tem preço manual (`PricingSet`).
      parameters:
        - name: idhubproduct
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador interno do anúncio.
        - name: NoInvoke
          in: query
          required: false
          schema:
            type: integer
          description: '`1` retorna apenas `"sucesso"` em vez do anúncio atualizado.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubProductUpdate'
        description: Atualização do anúncio. Mesma estrutura do POST — campos não enviados preservam o valor atual.
      responses:
        '200':
          description: Anúncio atualizado (mesma estrutura do GET por id) ou `"sucesso"` quando `NoInvoke=1`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubProductDetail'
        '400':
          description: >-
            `[BadRequest] - Produto Hub não existe` · `[BadRequest] - Produto/Sku não existe` · `[BadRequest] -
            Integração não existe` · `[BadRequest] - Já existe uma anuncio igual para a mesma integração` ·
            `[BadRequest] - Não pode ser alterada a categoria, pois já houve venda do anúncio` · `[BadRequest] -
            Variação anúncio tem preço manual setado. Remover antes de atualizar o preço a nível de anúncio` ·
            `[BadRequest] - Template de mensagem não encontrado`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: hubProductDelete
      tags:
        - Hub — Anúncios
      summary: Exclui anúncio — Hub Anúncios
      description: >-
        Exclui o anúncio e suas variações do cadastro e comunica a remoção ao canal de forma assíncrona. Dependendo do
        canal e do status, o anúncio pode permanecer no marketplace (encerrado em vez de apagado).
      parameters:
        - name: idhubproduct
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador interno do anúncio.
      responses:
        '200':
          description: Anúncio excluído.
          content:
            application/json:
              schema:
                type: string
                example: sucesso
        '400':
          description: '`[BadRequest] - Anúncio não existe` · `[BadRequest] - Erro ao deletar anúncio`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/product/{idhubproduct}/autoparts:
    get:
      operationId: hubProductAutopartsGet
      tags:
        - Hub — Anúncios
      summary: Lista compatibilidade de autopeças — Hub Anúncios
      description: >-
        Lista os veículos compatíveis associados ao anúncio de autopeças (marca, modelo, ano, versão e demais atributos
        do veículo), as posições de aplicação e eventuais reclamações de compatibilidade registradas pelos compradores.
        Recurso específico de autopeças (principalmente Mercado Livre).
      parameters:
        - name: idhubproduct
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador interno do anúncio.
      responses:
        '200':
          description: Veículos compatíveis (array vazio se não houver).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubProductAutopartsItem'
    post:
      operationId: hubProductAutopartsPost
      tags:
        - Hub — Anúncios
      summary: Adiciona veículo compatível — Hub Anúncios
      description: >-
        Associa um veículo (compatibilidade) ao anúncio de autopeças. Os atributos do veículo (`Brand`, `Model`, `Year`,
        etc.) só são usados para cadastrar o veículo no catálogo do canal quando ele ainda não existe; em geral basta o
        `ProductId` do veículo.
      parameters:
        - name: idhubproduct
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador interno do anúncio.
        - name: NoInvoke
          in: query
          required: false
          schema:
            type: integer
          description: '`1` retorna apenas `"sucesso"` em vez da lista atualizada.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubProductAutopartsCreate'
        description: >-
          Aplicação de autopeça a vincular ao anúncio. Identifica veículo/posição compatível conforme o catálogo do
          canal (ex.: marca/modelo/ano/posição). Estrutura completa em `HubProductAutopartsCreate`.
      responses:
        '200':
          description: Lista de veículos compatíveis atualizada ou `"sucesso"` quando `NoInvoke=1`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubProductAutopartsItem'
        '400':
          description: '`[BadRequest] - Anúncio não existe` · `[BadRequest] - este veículo já existe no anúncio`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/product/{idhubproduct}/autoparts/{idhubproductautoparts}:
    put:
      operationId: hubProductAutopartsPut
      tags:
        - Hub — Anúncios
      summary: Atualiza veículo compatível — Hub Anúncios
      description: Atualiza as observações e as posições de aplicação de um veículo compatível do anúncio de autopeças.
      parameters:
        - name: idhubproduct
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador interno do anúncio.
        - name: idhubproductautoparts
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do veículo compatível.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubProductAutopartsUpdate'
        description: Atualização da aplicação de autopeça vinculada ao anúncio.
      responses:
        '200':
          description: Lista de veículos compatíveis atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubProductAutopartsItem'
        '400':
          description: '`[BadRequest] - Autopartes anúncio não existe`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: hubProductAutopartsDelete
      tags:
        - Hub — Anúncios
      summary: Remove veículo compatível — Hub Anúncios
      description: Remove um veículo compatível (e suas posições) do anúncio de autopeças.
      parameters:
        - name: idhubproduct
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador interno do anúncio.
        - name: idhubproductautoparts
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do veículo compatível.
      responses:
        '200':
          description: Veículo removido.
          content:
            application/json:
              schema:
                type: string
                example: Sucesso
        '400':
          description: '`[BadRequest] - Autopartes anúncio não existe`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/product/{idhubproduct}/offer:
    post:
      operationId: hubProductOfferPost
      tags:
        - Hub — Anúncios
      summary: Adiciona variação ao anúncio — Hub Anúncios
      description: >-
        Adiciona uma variação (item) ao anúncio, vinculando um SKU. Aceita preço manual da variação (`PricingSet`),
        ficha técnica e ordem da variação. O preço da variação não pode coexistir com o preço a nível de anúncio.
      parameters:
        - name: idhubproduct
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador interno do anúncio.
        - name: NoInvoke
          in: query
          required: false
          schema:
            type: integer
          description: '`1` retorna apenas `"sucesso"` em vez do anúncio atualizado.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubProductOfferCreate'
        description: >-
          Oferta (anúncio em variante de canal) a cadastrar para o produto. Cobre dados específicos da oferta —
          modalidade, preço, opções de envio. Estrutura completa em `HubProductOfferCreate`.
      responses:
        '200':
          description: Anúncio atualizado (mesma estrutura do GET por id) ou `"sucesso"` quando `NoInvoke=1`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubProductDetail'
        '400':
          description: >-
            `[BadRequest] - Anúncio não existe` · `[BadRequest] - Sku não existe` · `[BadRequest] - Este anúncio já tem
            este SKU` · `[BadRequest] - Este anúncio já tem este código de variação` · `[BadRequest] - Anúncio tem preço
            manual setado. Remover antes de atualizar o preço a nível de variação` · `[BadRequest] - Problema ao criar
            variação em anúncio`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/product/{idhubproduct}/offer/{idoffer}:
    get:
      operationId: hubProductOfferGet
      tags:
        - Hub — Anúncios
      summary: Detalha variação do anúncio — Hub Anúncios
      description: >-
        Retorna o detalhe de uma variação (item) do anúncio: SKU vinculado, preços calculados, estoque, ficha técnica e
        imagens da variação. A resposta é um array com a variação correspondente.
      parameters:
        - name: idhubproduct
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador interno do anúncio.
        - name: idoffer
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da variação (`IDHubAdvertisement`).
      responses:
        '200':
          description: Variação do anúncio (array com um objeto; vazio se não existir).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubSkuDetail'
    put:
      operationId: hubProductOfferPut
      tags:
        - Hub — Anúncios
      summary: Atualiza variação do anúncio — Hub Anúncios
      description: >-
        Atualiza uma variação (item) do anúncio (atualização parcial). Quando a atualização automática de preço está
        ativa e o canal aceita preço, alterar o preço manual (`PricingSet`) dispara o envio ao canal.
      parameters:
        - name: idhubproduct
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador interno do anúncio.
        - name: idoffer
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da variação (`IDHubAdvertisement`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubProductOfferUpdate'
        description: Atualização da oferta. Mesma estrutura do POST.
      responses:
        '200':
          description: Anúncio atualizado (mesma estrutura do GET por id) ou `"sucesso"` quando `NoInvoke=1`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubProductDetail'
        '400':
          description: >-
            `[BadRequest] - Anúncio não existe` · `[BadRequest] - Sku não existe` · `[BadRequest] - Já existe uma
            variação com este código` · `[BadRequest] - Anúncio tem preço manual setado. Remover antes de atualizar o
            preço a nível de variação`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: hubProductOfferDelete
      tags:
        - Hub — Anúncios
      summary: Remove variação do anúncio — Hub Anúncios
      description: Remove uma variação (item) do anúncio e comunica a remoção ao canal de forma assíncrona.
      parameters:
        - name: idhubproduct
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador interno do anúncio.
        - name: idoffer
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da variação (`IDHubAdvertisement`).
      responses:
        '200':
          description: Anúncio atualizado (mesma estrutura do GET por id).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubProductDetail'
        '400':
          description: '`[BadRequest] - Variação não existe` · `[BadRequest] - Erro ao deletar`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/product/{idhubproduct}/quantity-pricing:
    post:
      operationId: hubProductQuantityPricingPost
      tags:
        - Hub — Anúncios
      summary: Adiciona preço por quantidade — Hub Anúncios
      description: >-
        Adiciona uma faixa de preço por quantidade (desconto por volume) ao anúncio. Recurso do Mercado Livre, limitado
        a 5 faixas por anúncio; cada quantidade só pode aparecer uma vez.
      parameters:
        - name: idhubproduct
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador interno do anúncio.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubProductQuantityPricingPayload'
        description: >-
          Faixa de preço por quantidade a cadastrar para o anúncio. Permite preço escalonado conforme a quantidade
          comprada.
      responses:
        '200':
          description: Faixas de preço por quantidade do anúncio (todas).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubProductQuantityPricingItem'
        '400':
          description: >-
            `[BadRequest] - Anúncio não existe` · `[BadRequest] - Quantidade precisa ser maior que zero` · `[BadRequest]
            - já existe preço para essa quantidade no anúncio` · `[BadRequest] - Anúncio não pode ter mais de 5 preços
            por quantidade`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/product/{idhubproduct}/quantity-pricing/{idhubproductquantitypricing}:
    put:
      operationId: hubProductQuantityPricingPut
      tags:
        - Hub — Anúncios
      summary: Atualiza preço por quantidade — Hub Anúncios
      description: Atualiza uma faixa de preço por quantidade do anúncio.
      parameters:
        - name: idhubproduct
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador interno do anúncio.
        - name: idhubproductquantitypricing
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da faixa de preço por quantidade.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubProductQuantityPricingPayload'
        description: Atualização da faixa de preço por quantidade. Mesma estrutura do POST.
      responses:
        '200':
          description: Faixas de preço por quantidade do anúncio (todas).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubProductQuantityPricingItem'
        '400':
          description: >-
            `[BadRequest] - Preço por quantidade do anúncio não existe` · `[BadRequest] - Quantidade precisa ser maior
            que zero` · `[BadRequest] - já existe preço para essa quantidade no anúncio`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: hubProductQuantityPricingDelete
      tags:
        - Hub — Anúncios
      summary: Remove preço por quantidade — Hub Anúncios
      description: Remove uma faixa de preço por quantidade do anúncio.
      parameters:
        - name: idhubproduct
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador interno do anúncio.
        - name: idhubproductquantitypricing
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da faixa de preço por quantidade.
      responses:
        '200':
          description: Faixa removida.
          content:
            application/json:
              schema:
                type: string
                example: sucesso
        '400':
          description: '`[BadRequest] - Preço por quantidade do anúncio não existe`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/inventory-summary:
    get:
      operationId: skuInventorySummaryList
      tags:
        - Inventário
      summary: Lista inventários
      description: >-
        Lista inventários da empresa, do mais recente para o mais antigo, paginada em blocos de 2000 (use `Page`). Os
        filtros são aplicados via query string. O filtro de **colaborador** considera o usuário em qualquer uma das três
        conferências.
      parameters:
        - name: Page
          in: query
          schema:
            type: integer
            minimum: 0
          description: Número da página (cada página tem 2000 registros). Quando omitido, vale `0`.
        - name: DateFrom
          in: query
          schema:
            type: string
            format: date
          description: Data inicial do intervalo (filtro pela criação do inventário, `RecordTimestamp`).
        - name: DateTo
          in: query
          schema:
            type: string
            format: date
          description: Data final do intervalo. O sistema adiciona `23:59:59` ao valor.
        - name: IDStockKeepingUnitInventorySummary
          in: query
          schema:
            type: integer
          description: Filtra pelo código do inventário.
        - name: IDTypeStatusSkuInventory
          in: query
          schema:
            oneOf:
              - type: integer
              - type: string
          description: Status do inventário. Aceita lista separada por vírgula.
        - name: IDStockKeepingUnitDistributionCenter
          in: query
          schema:
            type: integer
          description: Centro de distribuição.
        - name: IDStockKeepingUnitWarehouse
          in: query
          schema:
            type: integer
          description: Armazém.
        - name: RecordUserStart
          in: query
          schema:
            type: integer
          description: Colaborador atribuído (busca em qualquer uma das três conferências).
      responses:
        '200':
          description: Lista de inventários.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InventorySummaryListItem'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: skuInventorySummaryPost
      tags:
        - Inventário
      summary: Cria inventário
      description: >-
        Cria um novo inventário no status `2` (Aberto). Valida a existência do armazém ativo (deve pertencer à empresa),
        do tipo de inventário e do centro de distribuição. Após o INSERT, invoca internamente o sistema de leitura e
        devolve o inventário completo.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventorySummaryCreate'
        description: >-
          Abertura de um inventário. Informe `IDStockKeepingUnitWarehouse` (depósito a inventariar),
          `IDTypeInventorySummary` (modo: `1` Endereço, `2` SKU, `3` Livre, `4` Auditoria), `IDTypeQuantity` (política
          de fechamento dos saldos) e `InventoryDescription` (identificação livre).
      responses:
        '200':
          description: Inventário criado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InventorySummaryDetail'
        '400':
          description: >-
            `[BadRequest] - Empresa não existe`, `Armazém não localizado`, `Armazém deve ser informado`, `Tipo
            inventário não existe`, `Centro de distribuição não existe`, `Tipo quantidade (contagem) inventário não
            existe`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/inventory-summary/{idstockkeepingunitinventorysummary}:
    parameters:
      - name: idstockkeepingunitinventorysummary
        in: path
        required: true
        schema:
          type: integer
        description: Código do inventário.
    get:
      operationId: skuInventorySummaryGet
      tags:
        - Inventário
      summary: Detalha inventário
      description: >-
        Retorna o inventário completo com os itens contados (`Items`), a fila de SKUs
        (`StockKeepingUnitInventorySummarySkuQueue`) e a fila de endereços
        (`StockKeepingUnitInventorySummaryLocationQueue`). Os itens trazem `QuantityInventoryDiff`/`Second`/`Third`
        calculados em relação ao saldo do lote. Endereços com coordenadas (`Floor`, `Street`, `Module`...) são ordenados
        por trajeto serpentino para otimizar a separação.
      parameters:
        - name: Draft
          in: query
          schema:
            type: integer
            enum:
              - 1
          description: Quando `1`, devolve o **rascunho** salvo (TTL 4 dias) em vez de consultar o banco.
      responses:
        '200':
          description: Inventário ou lista vazia (`[]`) quando não localizado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InventorySummaryDetail'
    put:
      operationId: skuInventorySummaryPut
      tags:
        - Inventário
      summary: Atualiza inventário
      description: >-
        Atualiza o cabeçalho do inventário. Usado para:


        - **Encerrar uma conferência** — `IDTypeStatusSkuInventory = 6` finaliza a 1ª, `7` finaliza a 2ª, `8` finaliza a
        3ª. Cada transição grava o timestamp correspondente. Tentar repetir uma finalização já feita retorna erro.

        - **Atribuir colaborador** — `InventoryStartUser` só é aceito quando o status `< 6`; `InventorySecondUserStart`
        só quando o status `= 6`; `InventoryThirdUserStart` só quando o status `= 7`. O usuário precisa estar ativo
        (`Status = 1`) na empresa.


        Ao finalizar a **1ª conferência** de um inventário do tipo Auditoria (`IDTypeInventorySummary = 4`), o sistema
        inclui automaticamente, com quantidade `0`, todos os lotes do armazém que estavam com saldo e ainda não foram
        contados — opcionalmente compensando saldos negativos quando `IDTypeQuantity = 3`.


        Não é possível atualizar inventários `Finalizados` (`1`) ou `Cancelados` (`4`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventorySummaryUpdate'
        description: Atualiza dados gerais do inventário (descrição, política de quantidade, status).
      responses:
        '200':
          description: Inventário atualizado (mesmo formato de `GET /sku/inventory-summary/{id}`).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InventorySummaryDetail'
        '400':
          description: >-
            `[BadRequest] - Inventário não existe`, `Inventário já esta finalizado`, `Inventário esta cancelado`,
            `Inventário não pode ter a primeira/segunda/terceira conferência finalizada novamente`, `Colaborador
            primeira/segunda/terceira conferência não existe`, `Precisa finalizar a primeira conferência antes de
            definir o colaborador da segunda`, `Precisa finalizar a segunda conferência antes de definir o colaborador
            da terceira`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: skuInventorySummaryDelete
      tags:
        - Inventário
      summary: Cancela inventário
      description: >-
        Marca o inventário como Cancelado (`IDTypeStatusSkuInventory = 4`). Não dispara ajuste de estoque. Inventários
        já Finalizados (`1`) não podem ser cancelados.
      responses:
        '200':
          description: Cancelamento bem-sucedido. Retorna a string `"sucesso"`.
          content:
            application/json:
              schema:
                type: string
                example: sucesso
        '400':
          description: '`[BadRequest] - Inventário não existe`, `Inventário já esta finalizado`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/inventory-summary/{idstockkeepingunitinventorysummary}/finish:
    parameters:
      - name: idstockkeepingunitinventorysummary
        in: path
        required: true
        schema:
          type: integer
        description: Código do inventário.
    post:
      operationId: skuInventorySummaryFinishPost
      tags:
        - Inventário
      summary: Finaliza inventário e gera os ajustes de estoque
      description: >-
        Fecha o inventário gerando os ajustes de saldo: para cada SKU/lote contado, compara a `QuantityInventory` (ou a
        última conferência disponível) com a `QuantityBatch` e cria uma entrada (`IDTypeMovement=0`) ou saída
        (`IDTypeMovement=1`) em `StockKeepingUnitMovement`. Cada movimentação dispara um webhook
        `SkuBalanceInventoryFinish` na fila assíncrona configurada.


        **Inventário do tipo Endereço** — antes do ajuste, o sistema inclui automaticamente, com quantidade `0`, os
        lotes dos endereços que estavam na fila de contagem mas não foram lançados.


        **Custo aplicado** — o custo médio do SKU naquele armazém (`InventoryValue / QtyAvailable`); quando zero, usa
        `CostLastPurchase` do SKU. Quando o parâmetro `UseCostFromCostSet` está ativo na empresa, o sistema usa o
        **Custo Manual** (`CostSet`) cadastrado no SKU.


        Durante o processamento, o status passa a `5` (Processando) e, ao concluir, vai para `1` (Finalizado) gravando
        `InventoryFinishTimestamp` com o momento da finalização.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              description: >-
                Corpo opcional — o sistema aceita `IDStockKeepingUnitWarehouse` e `InventoryDescription` por
                compatibilidade, mas os valores efetivos vêm sempre do cadastro do inventário.
        description: >-
          Finaliza o inventário — efetiva os ajustes de estoque calculados pela contagem (entradas e saídas). O corpo
          geralmente é vazio; o sistema usa o estado das contagens registradas.
      responses:
        '200':
          description: Finalização bem-sucedida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryFinishResult'
        '400':
          description: >-
            `[BadRequest] - inventário não localizado para finalizar`, `inventário não tem itens`, `Status inventário
            não permite finalizar`, `Lote do item {IDSkuCompany} está inativo`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/inventory-summary/{idstockkeepingunitinventorysummary}/sku:
    parameters:
      - name: idstockkeepingunitinventorysummary
        in: path
        required: true
        schema:
          type: integer
        description: Código do inventário.
    post:
      operationId: skuInventorySummarySkuPost
      tags:
        - Inventário
      summary: Adiciona SKU/endereço à fila ou lança contagem
      description: >-
        Endpoint multi-uso, controlado pela query string:


        - `IDTypeQueue=1` — adiciona endereços na **fila de contagem**
        (`StockKeepingUnitInventorySummaryLocationQueue`). Quando `AddAllLocations=1`, inclui automaticamente todos os
        endereços do armazém com saldo de lote diferente de zero.

        - `IDTypeQueue=2` — adiciona SKUs na **fila de contagem** (`StockKeepingUnitInventorySummarySkuQueue`). Quando
        `AddAllSkus=1`, inclui todos os SKUs ativos da empresa com saldo de lote no centro de distribuição.

        - **Sem `IDTypeQueue`** — lança a **quantidade contada** de um SKU. Quando o body é um objeto único contendo
        `IDStockKeepingUnitLocation`, itens não enviados desse endereço são automaticamente zerados (uso pelo WMS de
        coletor).


        `IDTypeQuantity` (query) altera a estratégia de cálculo do saldo de referência. `Draft=1` salva o body como
        rascunho temporário (TTL 4 dias) em vez de persistir.


        Ao receber a primeira contagem, o sistema atribui o usuário autenticado como `InventoryStartUser` e muda o
        status para `3` (Em andamento). Lançamentos de `QuantityInventorySecond` ou `QuantityInventoryThird` mudam o
        status para `9` ou `10` (Processando 2ª/3ª conf.).
      parameters:
        - name: IDTypeQueue
          in: query
          schema:
            $ref: '#/components/schemas/IDTypeQueueEnum'
          description: Tipo de item da fila. Omita para lançamento de contagem.
        - name: AddAllLocations
          in: query
          schema:
            type: integer
            enum:
              - 1
          description: Junto com `IDTypeQueue=1`, adiciona automaticamente todos os endereços do armazém com saldo.
        - name: AddAllSkus
          in: query
          schema:
            type: integer
            enum:
              - 1
          description: Junto com `IDTypeQueue=2`, adiciona automaticamente todos os SKUs ativos da empresa com saldo.
        - name: IDTypeQuantity
          in: query
          schema:
            $ref: '#/components/schemas/TypeInventorySummaryQuantityEnum'
          description: Sobrescreve a estratégia de quantidade do cadastro do inventário.
        - name: IDStockKeepingUnitLocation
          in: query
          schema:
            type: integer
          description: >-
            Quando informado sem `IDTypeQueue`, o sistema considera que a contagem é por endereço e zera os SKUs deste
            endereço que não vieram no body.
        - name: Draft
          in: query
          schema:
            type: integer
            enum:
              - 1
          description: Quando `1`, salva o body como rascunho temporário (TTL 4 dias) em vez de persistir.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventorySkuQueueAdd'
        description: Enfileira um SKU para contagem dentro do inventário (modo `SKU` ou `Livre`).
      responses:
        '200':
          description: >-
            Lista atualizada de itens contados do inventário (mesmo formato dos `Items` do detalhe). Quando o body é
            array e ocorrem erros parciais, devolve a lista de erros.
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/InventoryItemDetail'
                  - type: array
                    items:
                      $ref: '#/components/schemas/InventoryQueueAddError'
        '400':
          description: >-
            `[BadRequest] - Inventário não existe`, `Inventário já esta finalizado`, `Inventário esta cancelado`, `Sku
            não existe`, `Endereço não existe para armazém`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: skuInventorySummaryQueueDelete
      tags:
        - Inventário
      summary: Remove item da fila
      description: >-
        Remove um SKU ou um endereço da fila de contagem. É obrigatório enviar **uma** das duas query strings:


        - `IDStockKeepingUnitInventorySummarySkuQueue` — código do SKU na fila (remove de
        `StockKeepingUnitInventorySummarySkuQueue`).

        - `IDStockKeepingUnitInventorySummaryLocationQueue` — código do endereço na fila (remove de
        `StockKeepingUnitInventorySummaryLocationQueue`).
      parameters:
        - name: IDStockKeepingUnitInventorySummarySkuQueue
          in: query
          schema:
            type: integer
          description: Código do SKU na fila.
        - name: IDStockKeepingUnitInventorySummaryLocationQueue
          in: query
          schema:
            type: integer
          description: Código do endereço na fila.
      responses:
        '200':
          description: Remoção bem-sucedida. Retorna a string `"sucesso"`.
          content:
            application/json:
              schema:
                type: string
                example: sucesso
        '400':
          description: >-
            `[BadRequest] - Inventário não encontrado`, `Inventário já esta finalizado`, `Inventário esta cancelado`,
            `Erro ao deletar item a ser inventariado`, `Erro ao deletar endereço a ser inventariado`, `Precisa ser
            enviado o endereço ou o item a ser inventariado para deletar`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/inventory-summary/{idstockkeepingunitinventorysummary}/sku/{idstockkeepingunitinventoryitems}:
    parameters:
      - name: idstockkeepingunitinventorysummary
        in: path
        required: true
        schema:
          type: integer
        description: Código do inventário.
      - name: idstockkeepingunitinventoryitems
        in: path
        required: true
        schema:
          type: integer
        description: Código do item contado dentro do inventário.
    put:
      operationId: skuInventorySummarySkuPut
      tags:
        - Inventário
      summary: Atualiza a quantidade lançada de um item
      description: >-
        Atualiza a quantidade contada de um item já existente na lista de itens. O sistema escolhe a conferência ativa
        pelo status atual do inventário: status `3` (Em andamento) → grava `QuantityInventory`; status `6` ou `9` →
        grava `QuantityInventorySecond`; status `7` ou `10` → grava `QuantityInventoryThird`. Campos das demais
        conferências são ignorados.


        Quando `QuantityInventorySecond` (ou `Third`) é enviado e a conferência correspondente ainda não foi iniciada
        (sem `Timestamp`), o sistema atribui o usuário autenticado como colaborador da rodada e muda o status do
        inventário para Processando 2ª/3ª.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventoryItemUpdate'
        description: Atualiza a contagem do item do inventário (quantidade contada e observações).
      responses:
        '200':
          description: Item atualizado, com os dados consolidados do SKU + lote + endereço.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InventoryItemDetail'
        '400':
          description: >-
            `[BadRequest] - Sku inventário não encontrado`, `Inventário já esta finalizado`, `Inventário esta
            cancelado`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: skuInventorySummarySkuDelete
      tags:
        - Inventário
      summary: Remove item contado
      description: >-
        Remove uma linha de item já lançada na contagem (`StockKeepingUnitInventoryItems`). Não é possível remover
        quando o inventário está Finalizado (`1`) ou Cancelado (`4`).
      responses:
        '200':
          description: Remoção bem-sucedida. Retorna a string `"sucesso"`.
          content:
            application/json:
              schema:
                type: string
                example: sucesso
        '400':
          description: >-
            `[BadRequest] - Sku inventário não encontrado`, `Inventário já esta finalizado`, `Inventário esta
            cancelado`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/inventory:
    get:
      operationId: skuInventoryList
      tags:
        - Inventário (Legacy)
      summary: Lista histórico de ajustes
      description: >-
        Lista os ajustes de saldo lançados pela tela **Inventário** (`/app/inventory`) — uma linha por ajuste, com SKU,
        lote, armazém, quantidade contada, comentário, usuário e data. Paginada em blocos de 2000 (`Page`).
      parameters:
        - name: Page
          in: query
          schema:
            type: integer
            minimum: 0
          description: Número da página (cada página tem 2000 registros). Default `0`.
        - name: DateFrom
          in: query
          schema:
            type: string
            format: date
          description: Data inicial do intervalo (criação do ajuste).
        - name: DateTo
          in: query
          schema:
            type: string
            format: date
          description: Data final do intervalo. O sistema adiciona `23:59:59` ao valor.
        - name: IDSku
          in: query
          schema:
            type: integer
          description: Filtra pelo código interno do SKU.
        - name: SkuName
          in: query
          schema:
            type: string
          description: Filtra pelo nome do SKU (busca parcial).
        - name: Barcode
          in: query
          schema:
            type: string
          description: Filtra pelo código de barras principal.
        - name: IDSkuCompany
          in: query
          schema:
            type: string
          description: Filtra pelo código de referência do SKU na empresa (busca parcial).
        - name: Search
          in: query
          schema:
            type: string
          description: >-
            Busca rápida — procura simultaneamente em `IDSku`, `SkuName`, `BarCode` e `IDSkuCompany`. Espaços viram `%`
            (LIKE).
      responses:
        '200':
          description: Lista de ajustes.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InventoryHistoryItem'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: skuInventoryPost
      tags:
        - Inventário (Legacy)
      summary: Lança ajustes de saldo
      description: >-
        Lança um array de ajustes de saldo. O sistema processa **item por item**, criando uma movimentação de estoque
        (`StockKeepingUnitMovement`) para cada item válido e um registro de ajuste (`StockKeepingUnitInventory`)
        apontando para ela. Para cada movimentação, dispara uma notificação `SkuBalanceAdjust` para o webhook.


        **Cálculo da diferença**:


        - Quando `IDMovementType = 0` ou `1`, força a direção e usa `QuantityInventory` como `Quantity` da movimentação.

        - Quando `IDMovementType = 3`, compara `QuantityInventory` contra o saldo disponível atual do SKU
        (`QtyAvailable`) e cria movimentação pela diferença.

        - Quando `IDMovementType` é omitido, compara `QuantityInventory` contra o saldo do **lote** (soma das
        movimentações do lote) e cria movimentação pela diferença.


        **Custo aplicado**: `CostSet` (custo manual) quando `UseCostFromCostSet = 1`; caso contrário, `CostAverage`
        apurado pelo balanço; quando o custo médio é zero, `CostLastPurchase` do SKU.


        **Auto-criação de lote**: quando o SKU não tem lote no armazém, o sistema cria automaticamente um lote no
        primeiro endereço (`Default = 1`) — quando não há endereço, cria um endereço `Principal` antes.


        **Erros parciais**: itens inválidos não interrompem o processamento — são acumulados em `tempError` e devolvidos
        no array de resposta.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/InventoryAdjustmentItem'
        description: >-
          Ajuste avulso de estoque (entrada ou saída) sem passar por inventário fechado. Schema não detalhado nesta
          versão — confira o sistema `skuInventoryPost` para o contrato exato.
      responses:
        '200':
          description: >-
            Resposta. Quando todos os itens foram processados com sucesso, devolve um array vazio. Quando há erros
            parciais, devolve a lista de falhas.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InventoryAdjustmentError'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/balance:
    get:
      operationId: skuWareHouseBalanceList
      tags:
        - Saldo de Estoque
      summary: Lista saldo consolidado por armazém + SKU
      description: >-
        Lista o saldo consolidado de cada SKU em cada armazém, com colunas de quantidade nas várias situações
        (disponível, reservada, em produção, em manuseio, em pedido de compra, em recebimento) e valor calculado pelo
        custo médio (ou pelo custo manual, conforme o parâmetro `UseCostFromCostSet`). Paginada em blocos de 400
        (`Page`).


        A chave `IDStockKeepingUnitWarehouseBalance` é uma string composta `{IDStockKeepingUnitWarehouse}-{IDSku}`
        gerada pelo sistema — não existe em banco.


        O filtro `SinceDateLastRecordModification` é útil para integrações: devolve apenas linhas que tiveram
        movimentação após a data informada.
      parameters:
        - name: Page
          in: query
          schema:
            type: integer
            minimum: 0
          description: Número da página (cada página tem 400 registros). Default `0`.
        - name: IDSku
          in: query
          schema:
            oneOf:
              - type: integer
              - type: string
          description: Filtra pelo código interno do SKU. Aceita lista separada por vírgula.
        - name: SkuName
          in: query
          schema:
            type: string
          description: Filtra pelo nome (busca parcial).
        - name: BarCode
          in: query
          schema:
            type: string
          description: Código de barras principal.
        - name: IDSkuCompany
          in: query
          schema:
            type: string
          description: Código de referência do SKU na empresa (busca parcial).
        - name: IDTypeSku
          in: query
          schema:
            oneOf:
              - type: integer
              - type: string
          description: >-
            Tipo de SKU, lista separada por vírgula. Valores: `1` Clube, `2` Kit, `3` Sku, `4` Produto, `5` Serviço, `6`
            Matéria-prima, `7` Uso e consumo, `8` Caixa.
        - name: IDBrand
          in: query
          schema:
            oneOf:
              - type: integer
              - type: string
          description: Marca. Aceita lista separada por vírgula.
        - name: IDSupplier
          in: query
          schema:
            oneOf:
              - type: integer
              - type: string
          description: Fornecedor vinculado ao SKU. Aceita lista separada por vírgula.
        - name: SupplierCode
          in: query
          schema:
            type: string
          description: Código que o fornecedor usa para identificar o produto.
        - name: Package
          in: query
          schema:
            type: string
          description: Embalagem (`Package`) do SKU.
        - name: IDStockKeepingUnitWarehouse
          in: query
          schema:
            type: integer
          description: Armazém específico.
        - name: IDTypeStockKeepingUnitWarehouse
          in: query
          schema:
            $ref: '#/components/schemas/TypeStockKeepingUnitWarehouseEnum'
          description: Tipo de armazém.
        - name: IDStatusSku
          in: query
          schema:
            type: array
            items:
              type: integer
              enum:
                - 0
                - 1
                - 2
                - 3
                - 4
          description: >-
            Status do SKU, lista separada por vírgula: `0` Deletado, `1` Ativo, `2` Compra suspensa, `3` Inativo, `4`
            Venda suspensa. Default `1,2,3,4` (todos exceto deletados).
          style: form
          explode: false
        - name: IDCompanyIntegration
          in: query
          schema:
            type: integer
          description: Filtra SKUs que **têm** anúncio na integração informada.
        - name: IDCompanyIntegrationNot
          in: query
          schema:
            type: integer
          description: >-
            Filtra SKUs que **não têm** anúncio na integração informada — usado para descobrir produtos pendentes de
            anúncio.
        - name: IDTypeCompanyIntegration
          in: query
          schema:
            type: integer
          description: 'Filtra SKUs com anúncio em alguma integração do **tipo** informado (ex.: marketplace, ERP).'
        - name: IDTypeCompanyIntegrationNot
          in: query
          schema:
            type: integer
          description: Filtra SKUs **sem** anúncio em integrações do tipo informado.
        - name: SinceDateLastRecordModification
          in: query
          schema:
            type: string
            format: date-time
          description: Devolve apenas SKUs que tiveram movimentação após a data informada (útil para integrações incrementais).
        - name: Search
          in: query
          schema:
            type: string
          description: Busca rápida — procura simultaneamente em `IDSku`, `SkuName`, `BarCode` e `IDSkuCompany`.
      responses:
        '200':
          description: Saldos consolidados. Lista vazia (`[]`) quando não há resultados.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StockBalanceItem'
        '500':
          description: Erro interno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/supplier:
    get:
      operationId: skuSupplierList
      tags:
        - Fornecedores ↔ SKUs
      summary: Lista vínculos SKU-fornecedor
      description: >-
        Lista a visão consolidada de produtos e seus fornecedores na conta autenticada, com os dados do produto somados
        aos do vínculo. Os filtros são combinados por `AND`; `Search` busca por código do produto, nome, código de
        barras e código de referência (combinados por `OR`). A resposta é paginada em blocos de 5000 registros via
        `Page`.
      parameters:
        - name: Page
          in: query
          required: false
          schema:
            type: integer
          description: Página da listagem (cada página traz até 5000 registros).
        - name: Search
          in: query
          required: false
          schema:
            type: string
          description: Busca textual por código do produto, nome, código de barras e código de referência.
        - name: IDSku
          in: query
          required: false
          schema:
            type: string
          description: Filtra por identificador do produto.
        - name: SkuName
          in: query
          required: false
          schema:
            type: string
          description: Filtra por nome do produto.
        - name: BarCode
          in: query
          required: false
          schema:
            type: string
          description: Filtra por código de barras.
        - name: IDSkuCompany
          in: query
          required: false
          schema:
            type: string
          description: Filtra por código de referência (parcial).
        - name: IDBrand
          in: query
          required: false
          schema:
            type: string
          description: Filtra por marca.
        - name: IDCategory
          in: query
          required: false
          schema:
            type: string
          description: Filtra por categoria.
        - name: SupplierCode
          in: query
          required: false
          schema:
            type: string
          description: Filtra por código do fornecedor (parcial).
        - name: IDSupplier
          in: query
          required: false
          schema:
            type: string
          description: Filtra por fornecedor.
        - name: Package
          in: query
          required: false
          schema:
            type: string
          description: Filtra por indicador de embalagem.
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: string
          description: Filtra produtos anunciados em uma integração específica.
        - name: IDCompanyIntegrationNot
          in: query
          required: false
          schema:
            type: string
          description: Filtra produtos NÃO anunciados em uma integração específica.
        - name: IDTypeCompanyIntegration
          in: query
          required: false
          schema:
            type: string
          description: Filtra produtos anunciados em um tipo de canal de vendas.
        - name: IDTypeCompanyIntegrationNot
          in: query
          required: false
          schema:
            type: string
          description: Filtra produtos NÃO anunciados em um tipo de canal de vendas.
      responses:
        '200':
          description: Lista de vínculos SKU-fornecedor.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuSupplierListItem'
  /sku/supplier/{idsku}:
    get:
      operationId: skuSupplierGet
      tags:
        - Fornecedores ↔ SKUs
      summary: Lista fornecedores de um SKU
      description: >-
        Retorna os fornecedores vinculados a um produto. Informe `IDStockKeepingUnitSuplierCode` para restringir a um
        vínculo específico.
      parameters:
        - name: idsku
          in: path
          required: true
          schema:
            type: integer
          description: Identificador do produto (SKU).
        - name: IDStockKeepingUnitSuplierCode
          in: query
          required: false
          schema:
            type: integer
          description: Restringe a resposta a um vínculo específico.
      responses:
        '200':
          description: Fornecedores do produto.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuSupplierLink'
    post:
      operationId: skuSupplierPost
      tags:
        - Fornecedores ↔ SKUs
      summary: Vincula fornecedor ao SKU
      description: >-
        Cria um vínculo entre o produto e um fornecedor. Após inserir, reinvoca `skuSupplierGet` e devolve a lista de
        fornecedores do produto.
      parameters:
        - name: idsku
          in: path
          required: true
          schema:
            type: integer
          description: Identificador do produto (SKU).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuSupplierCreate'
        description: >-
          Vincula um fornecedor ao SKU com o código do SKU no catálogo do fornecedor, tamanho da embalagem e múltiplo de
          compra.
      responses:
        '200':
          description: Fornecedores do produto após a inclusão.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuSupplierLink'
        '400':
          description: >-
            `[BadRequest] - Sku não existe`, `[BadRequest] - Fornecedor não existe` ou `[BadRequest] - Código e
            fornecedor já estão cadastrados`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku/supplier/{idsku}/{idstockkeepingunitsupliercode}:
    put:
      operationId: skuSupplierPut
      tags:
        - Fornecedores ↔ SKUs
      summary: Atualiza vínculo de fornecedor
      description: >-
        Atualiza um vínculo SKU-fornecedor existente. Após salvar, reinvoca `skuSupplierGet` e devolve a lista de
        fornecedores do produto.
      parameters:
        - name: idsku
          in: path
          required: true
          schema:
            type: integer
          description: Identificador do produto (SKU).
        - name: idstockkeepingunitsupliercode
          in: path
          required: true
          schema:
            type: integer
          description: Identificador do vínculo a atualizar.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuSupplierUpdate'
        description: Atualiza o vínculo SKU↔fornecedor.
      responses:
        '200':
          description: Fornecedores do produto após a atualização.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuSupplierLink'
        '400':
          description: >-
            `[BadRequest] - Fornecedor SKU não existe`, `[BadRequest] - Fornecedor não existe` ou `[BadRequest] - Código
            e fornecedor já estão cadastrados`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: skuSupplierDelete
      tags:
        - Fornecedores ↔ SKUs
      summary: Remove vínculo de fornecedor
      description: >-
        Remove o vínculo entre o produto e o fornecedor. O produto e o fornecedor continuam cadastrados. Após excluir,
        reinvoca `skuSupplierGet` e devolve os fornecedores restantes do produto.
      parameters:
        - name: idsku
          in: path
          required: true
          schema:
            type: integer
          description: Identificador do produto (SKU).
        - name: idstockkeepingunitsupliercode
          in: path
          required: true
          schema:
            type: integer
          description: Identificador do vínculo a remover.
      responses:
        '200':
          description: Fornecedores restantes do produto.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuSupplierLink'
        '400':
          description: '`[BadRequest] - Sku não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /user:
    get:
      operationId: UserList
      tags:
        - Cadastro de Usuários
      summary: Lista os usuários da empresa
      description: >-
        Retorna os usuários vinculados à empresa autenticada, com o(s) perfil(is) de acesso agregados em `Privileges`, o
        último login (`LastLogin`), flags de vendedor e o status do vínculo. Por padrão lista apenas usuários
        **ativos**; use `AllStatus=1` para incluir inativos.


        Quando `Comission=1`, a operação muda de comportamento: em vez da lista de cadastro, calcula e devolve a
        **apuração de comissões** dos vendedores no período (`DateFrom`/`DateTo` por data do pedido, ou
        `InvoiceDateFrom`/`InvoiceDateTo` por data de faturamento), respeitando as regras de cada vendedor.
      parameters:
        - name: AllStatus
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: 1 = inclui usuários inativos na listagem; ausente/0 = só ativos.
        - name: Salesman
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Filtra apenas vendedores (1) ou não-vendedores (0).
        - name: Technician
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Filtra apenas técnicos (1).
        - name: IDUserJobPosition
          in: query
          required: false
          schema:
            type: integer
            format: int32
          description: Filtra por cargo (uma das posições em `UserJobPositionList`).
        - name: Comission
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: 1 = retorna a apuração de comissões dos vendedores no período em vez da lista de cadastro.
        - name: DateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Início do período (data do pedido) — usado com `Comission=1`.
        - name: DateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Fim do período (data do pedido) — usado com `Comission=1`.
        - name: InvoiceDateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Início do período por data de faturamento — usado com `Comission=1`.
        - name: InvoiceDateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Fim do período por data de faturamento — usado com `Comission=1`.
        - name: IDCompanyInvoice
          in: query
          required: false
          schema:
            type: integer
            format: int32
          description: Restringe a apuração de comissão a uma empresa/filial faturadora.
      responses:
        '200':
          description: Lista de usuários da empresa (ou apuração de comissões quando `Comission=1`).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserListItem'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: UserPost
      tags:
        - Cadastro de Usuários
      summary: Cria um usuário
      description: >-
        Cadastra um usuário na empresa autenticada. É obrigatório informar `UserName` e pelo menos um identificador de
        login: `Login` (e-mail) **ou** `UserCpfCnpj`. Quando só o documento é enviado, o sistema gera um login interno
        no formato `<documento>@email.com.br`. Quando um e-mail real é informado, um e-mail de boas-vindas é enviado.


        Se já existir um registro de pessoa com o mesmo `Login`/`UserCpfCnpj` em outra conta (ou desvinculado), o
        cadastro **reaproveita e revincula** esse registro à empresa atual em vez de duplicar. `Login` e `UserCpfCnpj`
        precisam ser únicos dentro da empresa.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreate'
        description: >-
          Usuário a cadastrar na empresa autenticada. `UserName` é obrigatório e pelo menos um de `Login` (email) ou
          `UserCpfCnpj` precisa ser informado. Quando só o documento é enviado, o sistema gera um login interno
          `<documento>@email.com.br`. Se já existe pessoa com o mesmo `Login`/`UserCpfCnpj` desvinculada ou em outra
          empresa, o cadastro reaproveita e revincula em vez de duplicar.
      responses:
        '200':
          description: >-
            Usuário criado. Quando o login foi gerado a partir do documento, retorna a string `"sucesso"`. Quando um
            e-mail real foi informado, retorna o detalhe completo do usuário (mesmo formato de `GET /user/{iduser}`).
          content:
            application/json:
              schema:
                oneOf:
                  - type: string
                    example: sucesso
                  - type: array
                    items:
                      $ref: '#/components/schemas/UserDetail'
                    maxItems: 1
        '400':
          description: |-
            Erros (prefixo `[BadRequest]`):
            - `Cpf / Cnpj inválido, verificar os números digitados`
            - `Email inválido, verificar`
            - `Tipo de MFA inválido`
            - `Tipo de comissão não existe`
            - `Documento obrigatório quando não é informado`
            - `Documento e/ou email obrigatório para cadastrar usuário`
            - `Email já esta vinculado a outro usuário`
            - `Documento já esta vinculado a outro usuário`
            - `Empresa não existe`
            - `Problema ao criar usuário`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /user/{iduser}:
    parameters:
      - name: iduser
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do usuário.
    get:
      operationId: UserGet
      tags:
        - Cadastro de Usuários
      summary: Detalha um usuário
      description: >-
        Retorna o cadastro completo do usuário na empresa: dados pessoais, flags de vendedor e comissão, cargos
        (`UserJobPositionList`), perfis de acesso (`UserPrivilegeGroup`), regras de comissão (`SalesmanComission`),
        vínculos de empresa/filial faturadora (`UserCompanyInvoice`), centros de distribuição
        (`UserCompanyDistributionCenter`), categorias de fornecedor (`UserCompanySupplierCategory`) e a auditoria de
        alterações (`UserLog`) e de acessos (`LoginLog`).


        Por padrão considera apenas o vínculo **ativo** (`status=1`); informe `status` na query para buscar por outro
        status. Quando não há vínculo no status pedido, retorna um array vazio (`[]`) com status 200.
      parameters:
        - name: status
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Status do vínculo a buscar (1 = ativo, padrão; 0 = inativo).
      responses:
        '200':
          description: Detalhe do usuário (array com 1 item) ou `[]` quando não há vínculo no status pedido.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserDetail'
                maxItems: 1
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    put:
      operationId: UserPut
      tags:
        - Cadastro de Usuários
      summary: Atualiza um usuário
      description: >-
        Atualiza os dados do usuário na empresa. A atualização é **parcial** — apenas os campos enviados são alterados.


        Quando `Password` é enviado, a senha é validada contra a política da empresa (comprimento mínimo, complexidade,
        não repetir as 5 últimas senhas e validade). Alterar a senha de **outro** usuário exige o privilégio de
        redefinir senha; alterar a própria, não. Mudanças de campos são registradas em `UserLog` (valores DE/PARA).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdate'
        description: >-
          Atualização parcial do usuário — só os campos enviados são alterados. Quando `Password` é enviado, é validado
          contra a política da empresa (tamanho, complexidade, histórico das 5 últimas e validade). Trocar a senha de
          outro usuário exige privilégio de redefinir senha; trocar a própria, não. Mudanças são registradas em log com
          os valores de antes e depois.
      responses:
        '200':
          description: Usuário atualizado. Retorna o detalhe completo (mesmo formato de `GET /user/{iduser}`).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserDetail'
                maxItems: 1
        '400':
          description: |-
            Erros (prefixo `[BadRequest]`):
            - `A lista de cargos do usuário deve conter apenas IDs separados por vírgula`
            - `Cpf / Cnpj inválido, verificar os números digitados`
            - `Email inválido, verificar`
            - `Tipo de MFA inválido`
            - `Tipo de comissão não existe`
            - `Documento obrigatório quando não é informado`
            - `Documento e/ou email obrigatório para cadastrar usuário`
            - `A senha deve ter no mínimo N caracteres`
            - `A senha deve conter letras maiúsculas, minúsculas, números e caracteres especiais`
            - `Usuário não tem privilégio para resetar senha`
            - `A senha informada deve ser diferente das 5 últimas senhas utilizadas`
            - `Email já esta vinculado a outro usuário`
            - `Documento já esta vinculado a outro usuário`
            - `Usuário não existe`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: UserDelete
      tags:
        - Cadastro de Usuários
      summary: Remove o usuário da empresa
      description: >-
        Remove o vínculo do usuário com a empresa autenticada (apaga o `UserCompany` e os perfis de acesso daquela
        empresa). O registro global da pessoa (`User`) **persiste** se ela ainda estiver vinculada a outra conta — assim
        o histórico e o login em outras empresas são preservados.
      responses:
        '200':
          description: Vínculo removido. Retorna o detalhe do usuário atualizado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserDetail'
                maxItems: 1
        '400':
          description: 'Mensagem: `[BadRequest] - Usuário não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /user/{iduser}/privilege/privilege-group:
    parameters:
      - name: iduser
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do usuário.
    get:
      operationId: iduserPrivilegeGroupGet
      tags:
        - Cadastro de Usuários
      summary: Lista os perfis de acesso do usuário
      description: Retorna os perfis de acesso (grupos de privilégio) atualmente vinculados ao usuário na empresa autenticada.
      responses:
        '200':
          description: Perfis de acesso vinculados ao usuário.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserPrivilegeGroupRef'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: iduserPrivilegeGroupPost
      tags:
        - Cadastro de Usuários
      summary: Substitui os perfis de acesso do usuário
      description: >-
        Redefine, de uma vez, o conjunto de perfis de acesso do usuário: o corpo é a **lista completa** de
        identificadores de perfil (`IDUserPrivilegeGroup`) que o usuário deve passar a ter. Cada identificador é
        validado contra os perfis da empresa; os vínculos anteriores são apagados e os novos inseridos, e a operação é
        registrada em log.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              description: Lista de identificadores de perfil de acesso a vincular ao usuário.
              items:
                type: integer
                format: int32
              example:
                - 12
                - 15
        description: >-
          Array de identificadores de perfil de acesso (`IDUserPrivilegeGroup`) que o usuário deve passar a ter.
          Sobrescreve a lista existente — vínculos anteriores são apagados e os novos inseridos. Cada id é validado
          contra os perfis da empresa.
      responses:
        '200':
          description: Perfis atualizados. Retorna o detalhe completo do usuário.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserDetail'
                maxItems: 1
        '400':
          description: |-
            Erros (prefixo `[BadRequest]`):
            - `Privilegio não encontrado` (um dos IDs não pertence à empresa)
            - `User não existe`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /user/{iduser}/company-invoice:
    parameters:
      - name: iduser
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do usuário.
    post:
      operationId: userCompanyInvoicePost
      tags:
        - Cadastro de Usuários
      summary: Vincula uma empresa/filial faturadora ao usuário
      description: >-
        Adiciona ao usuário o acesso a uma empresa/filial faturadora (`IDCompany`). Define em quais filiais emitentes o
        usuário pode operar.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCompanyInvoiceCreate'
        description: >-
          Vínculo a cadastrar. `IDCompany` (identificador da empresa/filial faturadora) é obrigatório. Define em quais
          filiais emitentes o usuário pode operar.
      responses:
        '200':
          description: Vínculo criado. Retorna o detalhe completo do usuário.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserDetail'
                maxItems: 1
        '400':
          description: |-
            Erros (prefixo `[BadRequest]`):
            - `Empresa não existe`
            - `Usuário não encontrado`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /user/{iduser}/company-invoice/{idusercompanyinvoice}:
    parameters:
      - name: iduser
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do usuário.
      - name: idusercompanyinvoice
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do vínculo de empresa/filial faturadora.
    delete:
      operationId: userCompanyInvoiceDelete
      tags:
        - Cadastro de Usuários
      summary: Remove o vínculo de empresa/filial faturadora
      description: Desfaz o acesso do usuário a uma empresa/filial faturadora. A operação é registrada em log.
      responses:
        '200':
          description: Vínculo removido. Retorna o detalhe completo do usuário.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserDetail'
                maxItems: 1
        '400':
          description: 'Mensagem: `[BadRequest] - Empresa não localizada no cadastro do usuário`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /user/{iduser}/distribution-center:
    parameters:
      - name: iduser
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do usuário.
    post:
      operationId: userCompanyDistributionCenterPost
      tags:
        - Cadastro de Usuários
      summary: Vincula um centro de distribuição ao usuário
      description: >-
        Adiciona ao usuário o acesso a um centro de distribuição (`IDStockKeepingUnitDistributionCenter`). Restringe os
        CDs cujo estoque o usuário pode operar.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserDistributionCenterCreate'
        description: >-
          Vínculo a cadastrar. `IDStockKeepingUnitDistributionCenter` (identificador do centro de distribuição) é
          obrigatório. Restringe os CDs cujo estoque o usuário pode operar.
      responses:
        '200':
          description: Vínculo criado. Retorna o detalhe completo do usuário.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserDetail'
                maxItems: 1
        '400':
          description: |-
            Erros (prefixo `[BadRequest]`):
            - `Centro de distribuição não existe`
            - `Usuário não encontrado`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /user/{iduser}/distribution-center/{idusercompanydistributioncenter}:
    parameters:
      - name: iduser
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do usuário.
      - name: idusercompanydistributioncenter
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do vínculo de centro de distribuição.
    delete:
      operationId: userCompanyDistributionCenterDelete
      tags:
        - Cadastro de Usuários
      summary: Remove o vínculo de centro de distribuição
      description: Desfaz o acesso do usuário a um centro de distribuição. A operação é registrada em log.
      responses:
        '200':
          description: Vínculo removido. Retorna o detalhe completo do usuário.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserDetail'
                maxItems: 1
        '400':
          description: 'Mensagem: `[BadRequest] - Empresa não localizada no cadastro do usuário`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /user/{iduser}/supplier-category:
    parameters:
      - name: iduser
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do usuário.
    post:
      operationId: userSupplierCategoryPost
      tags:
        - Cadastro de Usuários
      summary: Vincula uma categoria de fornecedor ao usuário
      description: >-
        Adiciona ao usuário o acesso a uma categoria de fornecedor (`IDSupplierCategory`). Restringe quais categorias de
        fornecedor o usuário enxerga/opera.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserSupplierCategoryCreate'
        description: >-
          Vínculo a cadastrar. `IDSupplierCategory` (identificador da categoria de fornecedor) é obrigatório. Restringe
          os fornecedores que o usuário pode operar a essa categoria.
      responses:
        '200':
          description: Vínculo criado. Retorna o detalhe completo do usuário.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserDetail'
                maxItems: 1
        '400':
          description: |-
            Erros (prefixo `[BadRequest]`):
            - `Categoria fornecedor não existe`
            - `Usuário não encontrado`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /user/{iduser}/supplier-category/{idusersuppliercategory}:
    parameters:
      - name: iduser
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do usuário.
      - name: idusersuppliercategory
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do vínculo de categoria de fornecedor.
    delete:
      operationId: userSupplierCategoryDelete
      tags:
        - Cadastro de Usuários
      summary: Remove o vínculo de categoria de fornecedor
      description: Desfaz o acesso do usuário a uma categoria de fornecedor. A operação é registrada em log.
      responses:
        '200':
          description: Vínculo removido. Retorna o detalhe completo do usuário.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserDetail'
                maxItems: 1
        '400':
          description: 'Mensagem: `[BadRequest] - Categoria fornecedor não localizada no cadastro do usuário`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /user/{iduser}/image:
    parameters:
      - name: iduser
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do usuário.
    post:
      operationId: userImagePost
      tags:
        - Cadastro de Usuários
      summary: Define a foto do usuário
      description: |-
        Define a imagem de perfil do usuário. Aceita dois formatos:
        - **Upload de arquivo** (`multipart/form-data`, campo `file`) — envia o binário da imagem.
        - **JSON com `Url`** — o sistema baixa a imagem dessa URL e a armazena.

        A imagem é salva no armazenamento público e o endereço final é gravado em `UserImageUrl`.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: Arquivo de imagem a enviar.
          application/json:
            schema:
              type: object
              required:
                - Url
              properties:
                Url:
                  type: string
                  format: uri
                  description: Endereço de onde baixar a imagem.
        description: >-
          Foto do usuário. Aceita dois formatos: `multipart/form-data` com o campo `file` (upload do binário) ou JSON
          `{Url}` (o sistema baixa a imagem desse endereço). A imagem é armazenada no bucket público e o endereço final
          é gravado em `UserImageUrl`.
      responses:
        '200':
          description: Imagem definida com sucesso.
        '400':
          description: 'Falha ao processar/baixar a imagem. Mensagem possível: `[BadRequest] - erro ao baixar imagem`.'
        '404':
          description: Usuário não encontrado na empresa.
  /user/{iduser}/verify:
    parameters:
      - name: iduser
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do usuário.
    post:
      operationId: userVerifyPost
      tags:
        - Cadastro de Usuários
      summary: Confirma a senha do usuário (reautenticação)
      description: >-
        Revalida a senha do usuário para liberar uma ação sensível (reautenticação). Compara a senha enviada com a
        cadastrada e, opcionalmente, verifica se o usuário possui o privilégio informado em `UserPrivilege`. Em caso de
        sucesso, devolve o usuário com um token temporário (`TempAuthToken`) para autorizar a ação seguinte.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserVerifyRequest'
        description: >-
          Reautenticação. `Password` é obrigatória. `UserPrivilege` (opcional) faz o sistema verificar também se o
          usuário tem o privilégio informado antes de liberar a ação. Em caso de sucesso, devolve o usuário com um
          `TempAuthToken` para autorizar a próxima ação sensível.
      responses:
        '200':
          description: Senha confirmada. Retorna o usuário com `TempAuthToken`.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDUser:
                      type: integer
                      format: int32
                      description: Identificador do usuário verificado.
                    Login:
                      type: string
                      description: Login do usuário.
                    UserName:
                      type: string
                      description: Nome de exibição do usuário.
                    TempAuthToken:
                      type: string
                      description: Token temporário para autorizar a ação seguinte.
                  additionalProperties: true
                maxItems: 1
        '400':
          description: |-
            Erros (prefixo `[BadRequest]`):
            - `Usuário não tem senha cadastrada`
            - `Usuário não tem privilégio necessário para essa ação`
            - `Senha incorreta`
            - `Usuário não localizado`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/order/delivery-status:
    get:
      operationId: orderDeliveryStatusList
      tags:
        - Tipos — Pedido
      summary: Lista status de entrega de pedidos
      description: Lista os status de acompanhamento de entrega aplicáveis a pedidos.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDStatusDelivery:
                      type: integer
                      description: Identificador do status de entrega.
                      enum:
                        - 1
                        - 2
                        - 3
                        - 4
                        - 5
                        - 6
                    StatusDelivery:
                      type: string
                      maxLength: 45
                      nullable: true
                      description: Descrição do status de entrega (`No prazo`, `Atrasado`, `Em exceção`).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/tax/cfop:
    get:
      operationId: taxCfopList
      tags:
        - Tipos — Impostos
      summary: Lista CFOPs aplicáveis
      description: >-
        Lista as CFOPs cadastradas. Aceita três filtros opcionais que restringem a lista conforme a operação tributária
        pretendida.
      parameters:
        - name: InState
          in: query
          required: false
          schema:
            type: string
          description: Filtra por operação dentro do estado (`1`) ou fora (`0`).
        - name: TpNf
          in: query
          required: false
          schema:
            type: string
          description: Tipo de nota a que a CFOP se aplica (`0` entrada, `1` saída).
        - name: NFCe
          in: query
          required: false
          schema:
            type: string
          description: Filtra apenas CFOPs aplicáveis a NFC-e (`1`) quando informado.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    Cfop:
                      type: integer
                      description: Código Fiscal de Operações e Prestações (CFOP).
                    CfopDescription:
                      type: string
                      maxLength: 500
                      description: Descrição oficial do CFOP.
                    value:
                      type: string
                      description: Atalho da própria linha (uso interno do frontend).
                    label:
                      type: string
                      description: Atalho da própria linha (uso interno do frontend).
                    InState:
                      type: integer
                      description: '`1` quando é CFOP de operação dentro do estado, `0` quando é interestadual.'
                    TpNf:
                      type: integer
                      description: 'Tipo de NF: `0` entrada, `1` saída.'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/account/bank-slip/status:
    get:
      operationId: typeAccountsBankSlipStatusList
      tags:
        - Tipos — Contas e Pagamento
      summary: Lista status possíveis de boleto
      description: Lista os status possíveis do boleto bancário.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDStatusBankSlip:
                      type: integer
                      description: >-
                        Status do boleto: `1` Aguardando pagamento, `2` Pago, `3` Pendente, `4` Cancelado, `5` Baixa
                        manual, `6` Protesto.
                      enum:
                        - 1
                        - 2
                        - 3
                        - 4
                        - 5
                        - 6
                    StatusBankSlip:
                      type: string
                      maxLength: 45
                      nullable: true
                      description: Descrição do status (`Em aberto`, `Pago`, `Vencido`, `Cancelado`, etc.).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/account/status:
    get:
      operationId: typeAccountsStatusList
      tags:
        - Tipos — Contas e Pagamento
      summary: Lista status de contas a pagar e receber
      description: Lista os status comuns de contas a pagar e contas a receber.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDStatusAccountPayableReceivable:
                      type: integer
                      description: Identificador do status da conta.
                      enum:
                        - 0
                        - 1
                        - 2
                        - 3
                        - 4
                        - 5
                        - 6
                    StatusAccountPayableReceivable:
                      type: string
                      maxLength: 45
                      description: Descrição do status da conta (`Em aberto`, `Pago`, `Cancelado`, etc.).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/account/acquirer/payment:
    get:
      operationId: typeAcquirerPaymentList
      tags:
        - Tipos — Contas e Pagamento
      summary: Lista formas de pagamento de adquirente
      description: >-
        Lista os meios de pagamento exibidos pelas adquirentes. Quando filtrado, devolve apenas os meios suportados pela
        integração informada.
      parameters:
        - name: IDTypeCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
          description: Identificador do tipo de integração da adquirente. Quando ausente, retorna todos os meios cadastrados.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypePaymentFrom:
                      type: integer
                      description: Identificador interno do tipo de pagamento na conciliação do adquirente.
                    TypePaymentFrom:
                      type: string
                      maxLength: 45
                      description: 'Código do tipo de pagamento como o adquirente identifica (ex.: `credito`, `debito`, `pix`).'
                    TypePayment:
                      type: string
                      maxLength: 45
                      description: Tipo de pagamento mapeado no idworks (`TypePaymentDescription`).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/account/acquirer/release:
    get:
      operationId: typeAcquirerReleaseTypeList
      tags:
        - Tipos — Contas e Pagamento
      summary: Lista tipos de liberação de venda
      description: Lista os tipos de liberação de venda usados pelas adquirentes (à vista, parcelado, etc.).
      parameters:
        - name: IDTypeCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
          description: Identificador do tipo de integração da adquirente.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeAcquirerReleaseType:
                      type: integer
                      description: Identificador do tipo de liberação do adquirente.
                    TypeAcquirerReleaseType:
                      type: string
                      maxLength: 200
                      description: Descrição do tipo de liberação (`Pagamento`, `Devolução`, `Chargeback`, etc.).
                    TypeAcquirerReleaseTypeCode:
                      type: string
                      maxLength: 45
                      description: Código do tipo de liberação usado pelo adquirente na conciliação.
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/account/acquirer/status:
    get:
      operationId: typeAcquirerStatusList
      tags:
        - Tipos — Contas e Pagamento
      summary: Lista status de transação das adquirentes
      description: Lista os status de transação devolvidos pelas adquirentes e o status interno equivalente.
      parameters:
        - name: IDTypeCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
          description: Identificador do tipo de integração da adquirente.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeAcquirerStatus:
                      type: integer
                      description: Identificador do status devolvido pelo adquirente.
                    TypeAcquirerStatusFrom:
                      type: string
                      maxLength: 45
                      description: 'Código do status como o adquirente identifica (ex.: `Aprovado`, `Recusado`).'
                    TypeAcquirerStatus:
                      type: string
                      maxLength: 45
                      description: Status mapeado no idworks (descrição amigável).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/account/bank:
    get:
      operationId: typeBankList
      tags:
        - Tipos — Contas e Pagamento
      summary: Lista bancos disponíveis
      description: Lista os bancos cadastrados (código FEBRABAN e nome). Ordenado conforme uso/popularidade.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    BankNumber:
                      type: string
                      maxLength: 3
                      description: Código (3 dígitos) do banco no padrão Febraban.
                    Bank:
                      type: string
                      maxLength: 100
                      nullable: true
                      description: Nome do banco. `null` quando não cadastrado.
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/purchase/buy-order/status:
    get:
      operationId: typeBuyOrderStatusList
      tags:
        - Tipos — Compras
      summary: Lista status possíveis de pedido de compra
      description: Lista os status possíveis de um pedido de compra (rascunho, enviado, recebido, etc.).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDStatusBuyOrder:
                      type: integer
                      description: Identificador do status do pedido de compra.
                      enum:
                        - 0
                        - 1
                        - 2
                        - 3
                        - 5
                        - 6
                        - 7
                    StatusBuyOrder:
                      type: string
                      maxLength: 45
                      description: Descrição do status (`Aberto`, `Enviado`, `Recebido`, `Parcial`, etc.).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/supplier/carrier-gateway:
    get:
      operationId: typeCarrierGatewayList
      tags:
        - Tipos — Fornecedor
      summary: Lista integrações de transportadora
      description: Lista os gateways de transportadora suportados (integrações com Correios, Jadlog, Loggi, etc.).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDCarrierGateway:
                      type: integer
                      description: Identificador do gateway de cotação de frete.
                    CarrierGateway:
                      type: string
                      maxLength: 45
                      description: 'Nome do gateway (ex.: `Interno`, `Intelipost`, `Frete Rápido`).'
                    FileName:
                      type: string
                      maxLength: 45
                      nullable: true
                      description: Caminho/nome do arquivo de logo do gateway, quando configurado.
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/supplier/carrier:
    get:
      operationId: typeCarrierList
      tags:
        - Tipos — Fornecedor
      summary: Lista transportadoras
      description: Lista as transportadoras cadastradas no catálogo público.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeCarrier:
                      type: integer
                      description: Identificador do tipo de transportadora.
                    TypeCarrier:
                      type: string
                      maxLength: 45
                      description: Nome do tipo de transportadora.
                    CarrierLogoUrl:
                      type: string
                      maxLength: 500
                      nullable: true
                      description: URL do logo da transportadora (S3 público), quando preenchida.
                    FileName:
                      type: string
                      maxLength: 45
                      nullable: true
                      description: Nome do arquivo de logo no S3.
                    TrackingByOrder:
                      type: integer
                      nullable: true
                      description: '`1` quando o rastreio é feito por pedido (não por pacote).'
                    TypeCarrierCpfCnpj:
                      type: string
                      maxLength: 45
                      nullable: true
                      description: CPF/CNPJ default associado a esse tipo de transportadora, quando aplicável.
                    MarketplaceLabel:
                      type: integer
                      nullable: true
                      description: '`1` quando a transportadora gera etiqueta via marketplace (não tem etiqueta própria).'
                    EDI:
                      type: integer
                      nullable: true
                      description: '`1` quando a transportadora suporta integração EDI.'
                    IDTypeCompanyIntegration:
                      type: integer
                      nullable: true
                      description: Tipo de integração associado, quando o rastreio é feito via canal de integração.
                    TrackingEnabled:
                      type: integer
                      description: '`1` quando a integração de rastreio está habilitada para a transportadora.'
                    FtpFolder:
                      type: string
                      maxLength: 45
                      nullable: true
                      description: Pasta FTP padrão para arquivos EDI da transportadora, quando aplicável.
                    Show:
                      type: integer
                      nullable: true
                      description: '`1` quando o tipo de transportadora deve aparecer nas listagens da UI.'
                    TypeCarrierExternalId:
                      type: integer
                      nullable: true
                      description: Identificador externo (canal/marketplace) do tipo de transportadora.
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/quotation/action:
    get:
      operationId: typeCarrierQuotationActionList
      tags:
        - Tipos — Cotação
      summary: Lista ações de regra de cotação
      description: Lista as ações disponíveis para regras de cotação de frete (priorizar, descartar, sobrepor preço, etc.).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    TypeCarrierQuotationActionRule:
                      type: string
                      maxLength: 45
                      description: 'Descrição da ação (ex.: `Acrescimo no frete`, `Excluir transportadoras`, `Forçar valor fixo`).'
                    IDTypeCarrierQuotationActionRule:
                      type: integer
                      description: Identificador do tipo de ação aplicada por uma regra de cotação.
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/quotation/condition:
    get:
      operationId: typeCarrierQuotationConditionList
      tags:
        - Tipos — Cotação
      summary: Lista condições de regra de cotação
      description: Lista as condições disponíveis para regras de cotação de frete (peso, valor, CEP, transportadora, etc.).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    TypeCarrierQuotationConditionRule:
                      type: string
                      maxLength: 45
                      description: >-
                        Descrição da condição (`Estado/Região`, `CEP Destino`, `Transportadora`, `Valor do pedido`,
                        etc.).
                    IDTypeCarrierQuotationConditionRule:
                      type: integer
                      description: Identificador do tipo de condição aceito em regras de cotação.
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/tax/cofins-cst:
    get:
      operationId: typeCofinsCstList
      tags:
        - Tipos — Impostos
      summary: Lista CST de COFINS
      description: Lista os Códigos de Situação Tributária (CST) de COFINS.
      parameters:
        - name: TpNf
          in: query
          required: false
          schema:
            type: string
          description: Tipo de nota (`0` entrada, `1` saída). Restringe os CSTs aos da operação.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    NfCstCofins:
                      type: string
                      maxLength: 2
                      description: Código da CST de COFINS (NF-e).
                    NfCstCofinsDescription:
                      type: string
                      maxLength: 200
                      description: Descrição oficial da CST de COFINS.
                    value:
                      type: string
                      description: Atalho da própria linha (uso interno do frontend).
                    label:
                      type: string
                      description: Atalho da própria linha (uso interno do frontend).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/report/custom/category:
    get:
      operationId: typeCompanyReportCustomCategoryList
      tags:
        - Tipos — Relatórios
      summary: Lista categorias de relatórios customizados
      description: Lista as categorias/tipos de relatórios customizados disponíveis.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeCustomReport:
                      type: integer
                      description: Identificador da categoria/tipo de relatório personalizado.
                    CustomReportType:
                      type: string
                      maxLength: 100
                      description: Nome da categoria do relatório.
                    CustomReportBaseTable:
                      type: string
                      maxLength: 100
                      description: Tabela-base usada como fonte para os campos do relatório.
                    RecordTimestamp:
                      type: string
                      format: date-time
                      nullable: true
                      description: Data e hora do cadastro da categoria.
                    DateLastRecordModification:
                      type: string
                      format: date-time
                      nullable: true
                      description: Data e hora da última alteração na categoria.
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/report/custom/fields:
    get:
      operationId: typeCompanyReportCustomFieldsList
      tags:
        - Tipos — Relatórios
      summary: Lista campos disponíveis em um relatório customizado
      description: >-
        Lista os campos selecionáveis em um relatório customizado, agrupados por seção. A resposta é um array com **um
        único objeto** contendo a identificação do relatório e o agrupamento de campos por seção em `FieldList`.
      parameters:
        - name: IDTypeCustomReport
          in: query
          required: true
          schema:
            type: integer
          description: Identificador do tipo de relatório customizado.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                maxItems: 1
                items:
                  type: object
                  properties:
                    IDTypeCustomReport:
                      type: integer
                      description: Identificador do tipo de relatório personalizado.
                    ReportName:
                      type: string
                      description: Nome do relatório (e dos campos disponíveis nele).
                    FieldList:
                      type: object
                      description: Mapa `FieldGroup` → lista de campos. Quando o campo não tem grupo, é agrupado em `"Sem Grupo"`.
                      additionalProperties:
                        type: array
                        items:
                          type: object
                          additionalProperties: true
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/consumer/classification:
    get:
      operationId: typeConsumerClassificationList
      tags:
        - Tipos — Cliente
      summary: Lista classificações de cliente
      description: Lista as classificações usadas para segmentar clientes (atacado, varejo, VIP, etc.).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeConsumerClassification:
                      type: integer
                      description: Identificador da classificação do cliente.
                      enum:
                        - 1
                        - 2
                        - 3
                        - 4
                        - 5
                        - 6
                        - 7
                        - 8
                    TypeConsumerClassification:
                      type: string
                      maxLength: 45
                      description: 'Descrição da classificação (ex.: `VIP`, `Inadimplente`, `Atacado`).'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/consumer/status:
    get:
      operationId: typeConsumerStatusList
      tags:
        - Tipos — Cliente
      summary: Lista status possíveis de cliente
      description: Lista os status que um cliente pode assumir (ativo, bloqueado, etc.).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeStatusConsumer:
                      type: integer
                      description: Identificador do status do cliente.
                      enum:
                        - 0
                        - 1
                        - 2
                        - 3
                    TypeStatusConsumer:
                      type: string
                      maxLength: 45
                      description: Descrição do status (`Ativo`, `Inadimplente`, `Bloqueado`, `Deletado`).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/order/country:
    get:
      operationId: typeCountryList
      tags:
        - Tipos — Pedido
      summary: Lista países
      description: Lista os países cadastrados.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDCountry:
                      type: integer
                      description: Identificador interno do país.
                    Country:
                      type: string
                      maxLength: 200
                      description: Nome do país.
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/cte/sit:
    get:
      operationId: typeCteSitList
      tags:
        - Tipos — CT-e
      summary: Lista situações do CT-e
      description: Lista as situações possíveis do CT-e (autorizado, cancelado, denegado, etc.).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    SitCte:
                      type: integer
                      description: Código da situação do CT-e na SEFAZ.
                    SitCteDescription:
                      type: string
                      maxLength: 45
                      nullable: true
                      description: 'Descrição da situação (ex.: `Autorizado`, `Cancelado`, `Denegado`).'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/cte/toma:
    get:
      operationId: typeCteTomaList
      tags:
        - Tipos — CT-e
      summary: Lista tomadores do CT-e
      description: >-
        Lista os tipos de tomador do serviço de transporte no CT-e (remetente, destinatário, expedidor, recebedor,
        outros).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    CtToma:
                      type: integer
                      description: Código do tomador do CT-e (0 a 4 conforme leiaute SEFAZ).
                    CtTomaDescription:
                      type: string
                      maxLength: 45
                      nullable: true
                      description: Descrição do tomador (`Remetente`, `Expedidor`, `Recebedor`, `Destinatário`, `Outros`).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/cte/type:
    get:
      operationId: typeCteTypelist
      tags:
        - Tipos — CT-e
      summary: Lista tipos de CT-e
      description: Lista os tipos de CT-e (normal, complemento de valores, anulação, substituto).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    CtTpCte:
                      type: integer
                      description: Código do tipo de CT-e na SEFAZ.
                    CtTpCteDescription:
                      type: string
                      maxLength: 45
                      nullable: true
                      description: Descrição do tipo (`Normal`, `Complemento de valores`, `Anulação`, `Substituição`).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/account/file-type:
    get:
      operationId: typeFileTypeList
      tags:
        - Tipos — Contas e Pagamento
      summary: Lista tipos de arquivo
      description: Lista os tipos de arquivo suportados pelo upload (contrato, comprovante, foto, etc.).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeFile:
                      type: integer
                      description: Identificador do tipo de arquivo aceito em contas a pagar/receber.
                      enum:
                        - 1
                        - 2
                        - 3
                        - 4
                        - 5
                        - 6
                        - 7
                        - 8
                    TypeFile:
                      type: string
                      maxLength: 45
                      description: 'Descrição do tipo de arquivo (ex.: `Comprovante`, `Boleto`, `Nota fiscal`).'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/fulfillment/non-conformity:
    get:
      operationId: typeFulfillmentNonconformity
      tags:
        - Tipos — Fulfillment
      summary: Lista tipos de não-conformidade de fulfillment
      description: Lista os tipos de não-conformidade aplicáveis ao processo de fulfillment.
      parameters:
        - name: ShowPicking
          in: query
          required: false
          schema:
            type: string
          description: Quando `1`, retorna apenas tipos visíveis na tela de picking; quando omitido retorna todos.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeFulfillmentNonconformity:
                      type: integer
                      description: Identificador do tipo de não-conformidade no fulfillment.
                      enum:
                        - 1
                        - 2
                        - 4
                        - 5
                        - 6
                    TypeFulfillmentNonconformity:
                      type: string
                      maxLength: 45
                      description: Descrição (`Falta`, `Sobra`, `Avaria`, `Ressuprimento`, etc.).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/goal/type:
    get:
      operationId: typeGoalList
      tags:
        - Tipos — Metas
      summary: Lista tipos de meta
      description: Lista os tipos de meta suportados (faturamento, ticket médio, conversão, etc.).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeGoal:
                      type: integer
                      description: Identificador do tipo de meta.
                      enum:
                        - 1
                        - 2
                        - 3
                        - 4
                    TypeGoal:
                      type: string
                      maxLength: 45
                      description: 'Descrição do tipo de meta (ex.: `Vendas`, `Pedidos`, `Atendimentos`).'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/hub/order/claim/reason:
    get:
      operationId: typeHubOrderClaimReasonList
      tags:
        - Hub — Tipos de Referência
      summary: Lista motivos de reclamação de pedido (Hub)
      description: >-
        Lista os motivos de abertura de reclamações em pedidos do Hub. Quando filtrado por integração, retorna apenas os
        motivos válidos no marketplace correspondente.
      parameters:
        - name: IDTypeCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
          description: Identificador do tipo de integração do marketplace.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeHubOrderClaimReason:
                      type: integer
                      description: Identificador interno do motivo da reclamação/disputa do pedido.
                    IDTypeHubOrderClaimReasonExternalId:
                      type: string
                      maxLength: 45
                      description: Identificador do motivo no canal externo (marketplace).
                    TypeHubOrderClaimReason:
                      type: string
                      maxLength: 500
                      description: Descrição do motivo da reclamação.
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/hub/order/claim/resolution-reason:
    get:
      operationId: typeHubOrderClaimResolutionReasonList
      tags:
        - Hub — Tipos de Referência
      summary: Lista motivos de resolução de reclamação (Hub)
      description: Lista os motivos de resolução de reclamações de pedido do Hub.
      parameters:
        - name: IDTypeCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
          description: Identificador do tipo de integração do marketplace.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeHubOrderClaimResolutionReason:
                      type: integer
                      description: Identificador interno do motivo da resolução da reclamação.
                    IDTypeHubOrderClaimResolutionReasonExternalId:
                      type: string
                      maxLength: 45
                      description: Identificador da resolução no canal externo.
                    TypeHubOrderClaimResolutionReasonDescription:
                      type: string
                      maxLength: 200
                      description: Descrição do motivo da resolução.
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/hub/order/claim/stage:
    get:
      operationId: typeHubOrderClaimStageList
      tags:
        - Hub — Tipos de Referência
      summary: Lista estágios de reclamação (Hub)
      description: Lista os estágios de evolução de uma reclamação de pedido do Hub.
      parameters:
        - name: IDTypeCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
          description: Identificador do tipo de integração do marketplace.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeHubOrderClaimStage:
                      type: integer
                      description: Identificador interno do estágio da reclamação.
                      enum:
                        - 1
                        - 2
                        - 3
                        - 4
                        - 5
                    IDTypeHubOrderClaimStageExternalId:
                      type: string
                      maxLength: 45
                      description: Identificador do estágio no canal externo.
                    TypeHubOrderClaimStageName:
                      type: string
                      maxLength: 45
                      description: Nome do estágio (`Aberto`, `Em andamento`, `Fechado`, etc.).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/hub/order/claim/type:
    get:
      operationId: typeHubOrderClaimTypeList
      tags:
        - Hub — Tipos de Referência
      summary: Lista tipos de reclamação (Hub)
      description: Lista os tipos de reclamação de pedido (devolução, troca, garantia, etc.).
      parameters:
        - name: IDTypeCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
          description: Identificador do tipo de integração do marketplace.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeHubOrderClaimType:
                      type: integer
                      description: Identificador interno do tipo de reclamação.
                      enum:
                        - 1
                        - 2
                        - 3
                        - 4
                        - 5
                        - 6
                        - 7
                        - 8
                    IDTypeHubOrderClaimTypeExternalId:
                      type: string
                      maxLength: 45
                      description: Identificador do tipo no canal externo.
                    TypeHubOrderClaimTypeName:
                      type: string
                      maxLength: 45
                      nullable: true
                      description: Nome do tipo de reclamação (`Devolução`, `Cancelamento`, `Defeito`, etc.).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/order/hub/status:
    get:
      operationId: typeHubOrderStatusList
      tags:
        - Tipos — Pedido
      summary: Lista status de pedidos do Hub
      description: Lista os status de pedidos sincronizados a partir do Hub (marketplaces).
      parameters:
        - name: IDTypeCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
          description: Identificador do tipo de integração do marketplace.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    OrderStatus:
                      type: string
                      maxLength: 45
                      description: Código do status do pedido no canal de venda (externo).
                    Description:
                      type: string
                      maxLength: 45
                      description: Descrição amigável do status no canal.
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/sku/hub/status:
    get:
      operationId: typeHubSkuStatusList
      tags:
        - Tipos — SKU
      summary: Lista status de SKU no Hub
      description: Lista os status de SKU no Hub (pendente, sincronizado, com divergência, etc.).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDStatusHubSku:
                      type: integer
                      description: Identificador do status do SKU no canal de venda.
                      enum:
                        - 0
                        - 1
                        - 2
                        - 3
                        - 4
                        - 5
                    StatusHubSku:
                      type: string
                      maxLength: 45
                      description: Descrição do status (`Ativo`, `Pausado`, `Encerrado`, etc.).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/tax/ibs-cbs:
    get:
      operationId: typeIbsCbsCstList
      tags:
        - Tipos — Impostos
      summary: Lista CST de IBS/CBS
      description: >-
        Lista os Códigos de Situação Tributária (CST) de IBS/CBS. Aceita filtros booleanos para restringir a CSTs
        aplicáveis a cada modelo de documento fiscal.
      parameters:
        - name: NFe
          in: query
          required: false
          schema:
            type: string
          description: Quando `1`, restringe a CSTs válidos em NF-e.
        - name: NFCe
          in: query
          required: false
          schema:
            type: string
          description: Quando `1`, restringe a CSTs válidos em NFC-e.
        - name: NFSe
          in: query
          required: false
          schema:
            type: string
          description: Quando `1`, restringe a CSTs válidos em NFS-e.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDNfCstIbsCbs:
                      type: integer
                      description: Identificador interno da CST de IBS/CBS (Reforma Tributária).
                    NfCstIbsCbsDescription:
                      type: string
                      description: Descrição oficial da CST.
                    cClassTrib:
                      type: string
                      maxLength: 45
                      description: Código de classificação tributária (`cClassTrib`) conforme leiaute SEFAZ.
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/tax/icms-cst:
    get:
      operationId: typeIcmsCstList
      tags:
        - Tipos — Impostos
      summary: Lista CST/CSOSN de ICMS aplicáveis à filial
      description: >-
        Lista os Códigos de Situação Tributária (CST/CSOSN) de ICMS aplicáveis à filial informada. Para cada CST,
        retorna a lista de `Fields` indicando quais campos do regime tributário ficam habilitados (`Disable: false`) ou
        desabilitados (`Disable: true`).
      parameters:
        - name: IDCompanyBranch
          in: query
          required: true
          schema:
            type: integer
          description: Identificador da filial. Determina o regime tributário usado para filtrar os CSTs disponíveis.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    Cst:
                      type: string
                      description: Código da CST de ICMS.
                    CstDescription:
                      type: string
                      description: Descrição oficial da CST.
                    IDNfCstIcms:
                      type: integer
                      description: Identificador interno da CST.
                    value:
                      type: string
                      description: Valor utilizado em componentes de UI de seleção (corresponde ao `Cst`).
                    label:
                      type: string
                      description: Rótulo utilizado em componentes de UI de seleção (corresponde ao `CstDescription`).
                    Fields:
                      type: array
                      description: Lista de campos do regime tributário com indicação se estão habilitados.
                      items:
                        type: object
                        properties:
                          Field:
                            type: string
                            description: 'Nome do campo (ex.: `vBC`, `pICMS`, `vICMS`).'
                          Disable:
                            type: boolean
                            description: '`true` quando o campo deve aparecer desabilitado no formulário para esse CST.'
        '400':
          description: |-
            Erro de validação. Mensagens possíveis:
            - `[BadRequest] - IDCompanyBranch não existe` — A filial informada não pertence à empresa autenticada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/tax/icms-mod-bc:
    get:
      operationId: typeIcmsModBcList
      tags:
        - Tipos — Impostos
      summary: Lista modalidades de base de cálculo de ICMS
      description: Lista as modalidades de determinação da base de cálculo do ICMS.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    NfModBc:
                      type: integer
                      description: Código da modalidade de base de cálculo do ICMS.
                    NfModBcDescription:
                      type: string
                      maxLength: 45
                      description: Descrição da modalidade.
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/tax/icms-mod-bc-st:
    get:
      operationId: typeIcmsModBcStList
      tags:
        - Tipos — Impostos
      summary: Lista modalidades de base de cálculo do ICMS ST
      description: Lista as modalidades de determinação da base de cálculo do ICMS ST.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    NfModBcST:
                      type: integer
                      description: Código da modalidade de base de cálculo do ICMS-ST.
                    NfModBcSTDescription:
                      type: string
                      maxLength: 45
                      description: Descrição da modalidade.
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/company/parameter/type:
    get:
      operationId: typeIntegrationTypeList
      tags:
        - Tipos — Empresa
      summary: Lista tipos de integração disponíveis
      description: >-
        Lista os tipos de integração disponíveis para contratação. Pode ser filtrado por categoria (banco, marketplace,
        transportadora, etc.). Apenas integrações com `Show = 1` são retornadas.
      parameters:
        - name: IDTypeCompanyIntegrationCategory
          in: query
          required: false
          schema:
            type: integer
          description: Identificador da categoria de integração. Quando ausente, retorna todas as integrações visíveis.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeCompanyIntegration:
                      type: integer
                      description: Identificador do tipo de integração.
                    Integration:
                      type: string
                      maxLength: 45
                      description: Nome curto da integração (slug usado em rotas).
                    IntegrationName:
                      type: string
                      maxLength: 45
                      description: Nome amigável da integração (`Mercado Livre`, `idworks`, `Correios`, etc.).
                    IntegrationLogoUrl:
                      type: string
                      maxLength: 200
                      nullable: true
                      description: URL do logo da integração.
                    IDTypeCompanyIntegrationCategory:
                      type: integer
                      description: Categoria da integração.
                    IDSalesChannel:
                      type: integer
                      nullable: true
                      description: Identificador do canal de venda associado, quando aplicável.
                    NfeInfIntermed:
                      type: string
                      maxLength: 45
                      nullable: true
                      description: >-
                        Tipo de informação de intermediador para NF-e (`1` operação sem intermediador, `2` operação em
                        site/marketplace).
                    PathName:
                      type: string
                      maxLength: 45
                      nullable: true
                      description: >-
                        Path name usado para rotear chamadas internas (ex.: `meli`, `magalu`). Vazio para integrações
                        que não precisam.
                    Show:
                      type: integer
                      nullable: true
                      description: '`1` quando a integração deve aparecer nas listagens da UI.'
                    UpdateOrderShipped:
                      type: integer
                      nullable: true
                      description: '`1` quando a integração atualiza automaticamente o status `Enviado` no canal.'
                    UpdateOrderDelivered:
                      type: integer
                      nullable: true
                      description: '`1` quando a integração atualiza automaticamente o status `Entregue` no canal.'
                    UpdateMarketplaceFee:
                      type: integer
                      nullable: true
                      description: '`1` quando a integração importa a taxa do marketplace.'
                    GiftCard:
                      type: integer
                      nullable: true
                      description: '`1` quando a integração suporta vale-presente.'
                    UpdateSkuBalance:
                      type: integer
                      nullable: true
                      description: '`1` quando a integração atualiza saldo de estoque no canal.'
                    AuthUrl:
                      type: integer
                      nullable: true
                      description: '`1` quando a integração tem fluxo de autenticação OAuth.'
                    HubPaymentCustom:
                      type: integer
                      nullable: true
                      description: '`1` quando o canal devolve pagamentos em formato customizado.'
                    UpdateOrderFulfillment:
                      type: integer
                      nullable: true
                      description: '`1` quando a integração atualiza fulfillment no canal.'
                    BankSlipUpdate:
                      type: integer
                      nullable: true
                      description: '`1` quando a integração atualiza boletos.'
                    BankSlipCancel:
                      type: integer
                      nullable: true
                      description: '`1` quando a integração cancela boletos.'
                    UpdateOrderStatus:
                      type: integer
                      nullable: true
                      description: '`1` quando a integração atualiza status genérico do pedido.'
                    UpdateOrderStatusPending:
                      type: integer
                      nullable: true
                      description: '`1` quando a integração atualiza status `Pendente` (especial).'
                    CarrierQuotation:
                      type: integer
                      nullable: true
                      description: '`1` quando a integração é gateway de cotação de frete.'
                    UpdateSkuPricing:
                      type: integer
                      nullable: true
                      description: '`1` quando a integração atualiza preços de SKU no canal.'
                    SkuPricingFile:
                      type: string
                      maxLength: 45
                      nullable: true
                      description: Caminho do template de planilha de preços específico do canal.
                    IntegrationWebsite:
                      type: string
                      maxLength: 300
                      nullable: true
                      description: URL do site oficial da integração.
                    TypeCompanyIntegrationCategory.TypeCompanyIntegrationCategory:
                      type: string
                      description: Nome da categoria a que a integração pertence.
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/tax/di-intermedio:
    get:
      operationId: typeInvoiceDIIntermedio
      tags:
        - Tipos — Impostos
      summary: Lista tipos de intermédio (DI)
      description: Lista os tipos de intermédio em operações de importação para informação na DI (Declaração de Importação).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    NfDITpIntermedio:
                      type: integer
                      description: Código do tipo de intermédio da DI (Declaração de Importação).
                    NfDITpIntermedioDescription:
                      type: string
                      maxLength: 45
                      description: Descrição do tipo de intermédio.
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/tax/di-viatransp:
    get:
      operationId: typeInvoiceDIViaTransp
      tags:
        - Tipos — Impostos
      summary: Lista vias de transporte (DI)
      description: Lista as vias de transporte usadas na DI (marítima, aérea, rodoviária, etc.).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    NftDITpViaTransp:
                      type: integer
                      description: Código da via de transporte na DI.
                    NftDITpViaTranspDescription:
                      type: string
                      maxLength: 45
                      description: Descrição da via (`Marítima`, `Aérea`, `Rodoviária`, etc.).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/invoice/event:
    get:
      operationId: typeInvoiceEventList
      tags:
        - Tipos — Nota Fiscal
      summary: Lista tipos de evento de nota fiscal
      description: >-
        Lista os tipos de evento aplicáveis a notas fiscais (carta de correção, cancelamento, manifestação, etc.). Pode
        filtrar via `Type` por código parcial.
      parameters:
        - name: Type
          in: query
          required: false
          schema:
            type: string
          description: Busca textual parcial pelo código do evento (`NfTpEvent` LIKE `%Type%`).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    NfTpEvent:
                      type: integer
                      description: Código do tipo de evento de NF-e/CT-e na SEFAZ.
                    NfTpEventDescription:
                      type: string
                      maxLength: 100
                      description: Descrição do evento (`Cancelamento`, `Carta de Correção`, `Confirmação da Operação`, etc.).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/invoice/fin:
    get:
      operationId: typeInvoiceFinList
      tags:
        - Tipos — Nota Fiscal
      summary: Lista finalidades de emissão
      description: Lista as finalidades de emissão da NF-e (normal, complementar, ajuste, devolução).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    FinNFe:
                      type: integer
                      description: Código da finalidade da NF-e (`1` normal, `2` complementar, `3` ajuste, `4` devolução).
                    FinNfeDescription:
                      type: string
                      maxLength: 45
                      description: Descrição da finalidade.
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/invoice/sefaz-status:
    get:
      operationId: typeInvoiceSefazStatus
      tags:
        - Tipos — Nota Fiscal
      summary: Lista códigos de status da SEFAZ
      description: >-
        Lista os códigos de status retornados pela SEFAZ ao processar notas fiscais. Útil para identificar e exibir
        mensagens de erro de emissão.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    State:
                      type: string
                      maxLength: 2
                      description: UF do servidor SEFAZ consultado.
                    SefazcStat:
                      type: integer
                      description: Código de status retornado pela SEFAZ no último consulta-status.
                    LastUpdateTimestamp:
                      type: string
                      format: date-time
                      nullable: true
                      description: Data e hora da última verificação do status.
                    SefazverAplic:
                      type: string
                      maxLength: 45
                      nullable: true
                      description: Versão da aplicação SEFAZ na última consulta.
                    EPECMode:
                      type: integer
                      nullable: true
                      description: '`1` quando a SEFAZ está em modo de contingência EPEC.'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/invoice/type-issue:
    get:
      operationId: typeInvoiceTypeIssueList
      tags:
        - Tipos — Nota Fiscal
      summary: Lista tipos de emissão
      description: Lista os tipos de emissão da NF-e (normal, contingência FS-IA, contingência SCAN, etc.).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    NfetpEmis:
                      type: integer
                      description: Código do tipo de emissão da NF-e (`1` normal, `2-9` contingências).
                    NfetpEmisDescription:
                      type: string
                      maxLength: 200
                      nullable: true
                      description: Descrição do tipo de emissão.
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/invoice/type:
    get:
      operationId: typeInvoiceTypeList
      tags:
        - Tipos — Nota Fiscal
      summary: Lista tipos de nota fiscal (entrada/saída)
      description: Lista os tipos de nota fiscal pelo indicador de entrada (`0`) ou saída (`1`).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    NfTpNf:
                      type: integer
                      description: Código do tipo de operação da NF-e (`0` entrada, `1` saída).
                    NfTpNfDescription:
                      type: string
                      maxLength: 45
                      description: Descrição do tipo (`Entrada`, `Saída`).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/tax/ipi-cenq:
    get:
      operationId: typeIpiCEnqList
      tags:
        - Tipos — Impostos
      summary: Lista códigos de enquadramento legal de IPI
      description: >-
        Lista os códigos de enquadramento legal de IPI aplicáveis. O filtro `IpiCst` é interpretado pelo último dígito
        do CST: se for `2`, `4` ou `5`, restringe a códigos válidos para CSTs de imunidade/suspensão; caso contrário,
        retorna todos.
      parameters:
        - name: IpiCst
          in: query
          required: false
          schema:
            type: string
          description: >-
            CST de IPI. Usado apenas pelo último dígito; se for `2`, `4` ou `5`, restringe a códigos de enquadramento
            aplicáveis. Outros valores são ignorados.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    NfIpiCEnq:
                      type: string
                      maxLength: 3
                      description: Código de enquadramento do IPI.
                    NfIpiCEnqDescription:
                      type: string
                      maxLength: 1000
                      nullable: true
                      description: Descrição do código de enquadramento.
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/tax/ipi-cst:
    get:
      operationId: typeIpiCstList
      tags:
        - Tipos — Impostos
      summary: Lista CST de IPI
      description: Lista os Códigos de Situação Tributária (CST) de IPI.
      parameters:
        - name: TpNf
          in: query
          required: false
          schema:
            type: string
          description: Tipo de nota (`0` entrada, `1` saída). Restringe os CSTs aos da operação.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    NfCstIpi:
                      type: string
                      maxLength: 2
                      description: Código da CST de IPI.
                    NfCstIpiDescription:
                      type: string
                      maxLength: 45
                      description: Descrição oficial da CST de IPI.
                    value:
                      type: string
                      description: Atalho da própria linha (uso interno do frontend).
                    label:
                      type: string
                      description: Atalho da própria linha (uso interno do frontend).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/job/type:
    get:
      operationId: typeJobTypeList
      tags:
        - Tipos — Jobs
      summary: Lista tipos de job
      description: >-
        Lista os tipos de job/tarefa executáveis pela conta (exportações, relatórios agendados, etc.) e o relatório
        (`IDTypeCompanyReport`) e `TemplateUrl` associados.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeJob:
                      type: integer
                      description: Identificador do tipo de job de importação.
                    TypeJob:
                      type: string
                      maxLength: 45
                      description: Descrição do tipo (`Criar sku/produto`, `Criar pedido`, `Criar contas`, etc.).
                    IDTypeCompanyReport:
                      type: integer
                      nullable: true
                      description: Identificador do relatório associado ao tipo de job, quando aplicável.
                    TemplateUrl:
                      type: string
                      maxLength: 1000
                      nullable: true
                      description: URL do template de planilha (S3) usado por esse tipo de job.
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/label/category:
    get:
      operationId: typeLabelCategoryList
      tags:
        - Tipos — Etiquetas
      summary: Lista categorias de etiqueta
      description: Lista as categorias de etiqueta (modelos de impressão) — produto, embalagem, transporte, etc.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeLabelCategory:
                      type: integer
                      description: Identificador da categoria do template de etiqueta.
                    TypeLabelCategory:
                      type: string
                      maxLength: 45
                      nullable: true
                      description: Nome da categoria (`Endereço`, `Produto`, `Volume`, etc.).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/label:
    get:
      operationId: typeLabelList
      tags:
        - Tipos — Etiquetas
      summary: Lista etiquetas cadastradas
      description: >-
        Lista as etiquetas (modelos de impressão) cadastradas para a empresa. Inclui automaticamente as etiquetas padrão
        da conta `54`. Pode ser filtrada por categoria.
      parameters:
        - name: IDTypeLabelCategory
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por categoria de etiqueta.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    AccountName:
                      type: string
                      description: Conta (prefixo) a que pertence o template de etiqueta.
                    TypeLabelCategory:
                      type: string
                      description: Categoria da etiqueta.
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/label/{idtypelabelcategory}/variable:
    parameters:
      - name: idtypelabelcategory
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador da categoria de etiqueta (`IDTypeLabelCategory`).
    get:
      operationId: typeLabelVariableList
      tags:
        - Tipos — Etiquetas
      summary: Lista variáveis de uma categoria de etiqueta
      description: Lista as variáveis (placeholders) substituíveis nas etiquetas de uma determinada categoria.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeLabelCategoryVariable:
                      type: integer
                      description: Identificador da variável disponível para a categoria de etiqueta.
                    RecordTimestamp:
                      type: string
                      format: date-time
                      description: Data e hora do cadastro da variável.
                    IDTypeLabelCategory:
                      type: integer
                      description: Identificador da categoria à qual a variável pertence.
                    TypeLabelCategoryVariable:
                      type: string
                      maxLength: 45
                      description: Nome técnico da variável (placeholder usado no template).
                    TypeLabelCategoryVariableDescription:
                      type: string
                      maxLength: 100
                      description: Descrição amigável da variável para exibição na UI.
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/sku/measurement:
    get:
      operationId: typeMeasurementList
      tags:
        - Tipos — SKU
      summary: Lista unidades de medida
      description: Lista as unidades de medida usadas no cadastro de produtos e nas notas fiscais.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    MeasurementUnit:
                      type: string
                      maxLength: 45
                      description: Sigla da unidade de medida (`UN`, `KG`, `M`, `L`, etc.).
                    MeasurementUnitDescription:
                      type: string
                      maxLength: 45
                      description: Nome da unidade de medida.
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/order/event:
    get:
      operationId: typeOrderEvent
      tags:
        - Tipos — Pedido
      summary: Lista eventos de pedido
      description: Lista os eventos registrados em pedidos (criação, alteração de status, anotação, etc.).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDEvent:
                      type: integer
                      description: Identificador do tipo de evento de pedido.
                    EventDescription:
                      type: string
                      maxLength: 100
                      description: Descrição do evento (`Picking iniciado`, `Romaneio fechado`, `Cancelamento`, etc.).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/order/invoice-status:
    get:
      operationId: typeOrderInvoiceStatusList
      tags:
        - Tipos — Pedido
      summary: Lista status de nota fiscal em pedidos
      description: >-
        Lista os status de nota fiscal aplicáveis a pedidos. Quando filtrado, retorna apenas status compatíveis com
        notas de serviço (`ServiceInvoice = 1`) ou de produto (`= 0`).
      parameters:
        - name: ServiceInvoice
          in: query
          required: false
          schema:
            type: string
          description: Restringe a status de NFS-e (`1`) ou NF-e (`0`).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDStatusInvoice:
                      type: integer
                      description: >-
                        Identificador do status da NF (`0` Pendente, `1` Erro, `2` Enviada, `3` Emitida, `4`
                        Processando, `5` Pendente Conciliação EPEC, `6` Erro Conciliação EPEC, `7` Cancelada, `8`
                        Denegada, `9` Inutilizada).
                    StatusInvoice:
                      type: string
                      maxLength: 45
                      description: Descrição do status da NF.
                    ServiceInvoice:
                      type: integer
                      description: '`1` quando o status é de NF de serviço (NFSe); `0` para NF-e/NFC-e.'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/order/resend:
    get:
      operationId: typeOrderResendList
      tags:
        - Tipos — Pedido
      summary: Lista motivos de reenvio de pedido
      description: Lista os motivos disponíveis quando se reenvia (refaz) um pedido.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeOrderResend:
                      type: integer
                      description: Identificador do motivo de reenvio do pedido.
                    TypeOrderResend:
                      type: string
                      maxLength: 45
                      nullable: true
                      description: Descrição do motivo (`Extravio`, `Endereço errado`, `Avaria`, etc.).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/order/return/category:
    get:
      operationId: typeOrderReturnCategoryList
      tags:
        - Tipos — Pedido
      summary: Lista categorias de devolução
      description: Lista as categorias de motivo de devolução de pedido (defeito, arrependimento, divergência, etc.).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeOrderReturnCategory:
                      type: integer
                      description: Identificador da categoria de devolução.
                      enum:
                        - 1
                        - 2
                        - 3
                    TypeOrderReturnCategory:
                      type: string
                      maxLength: 45
                      description: Nome da categoria (`Defeito`, `Arrependimento`, `Troca`, etc.).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/order/return:
    get:
      operationId: typeOrderReturnList
      tags:
        - Tipos — Pedido
      summary: Lista motivos de devolução
      description: Lista os motivos de devolução suportados.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeOrderReturn:
                      type: integer
                      description: Identificador do tipo de devolução.
                    TypeOrderReturn:
                      type: string
                      maxLength: 45
                      description: Descrição do tipo de devolução.
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/tax/pis-cst:
    get:
      operationId: typePisCstList
      tags:
        - Tipos — Impostos
      summary: Lista CST de PIS
      description: Lista os Códigos de Situação Tributária (CST) de PIS.
      parameters:
        - name: TpNf
          in: query
          required: false
          schema:
            type: string
          description: Tipo de nota (`0` entrada, `1` saída). Restringe os CSTs aos da operação.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    NfCstPis:
                      type: string
                      maxLength: 3
                      description: Código da CST de PIS.
                    NfCstPisDescription:
                      type: string
                      maxLength: 300
                      description: Descrição oficial da CST de PIS.
                    value:
                      type: string
                      description: Atalho da própria linha (uso interno do frontend).
                    label:
                      type: string
                      description: Atalho da própria linha (uso interno do frontend).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/purchase/status:
    get:
      operationId: typePurchaseStatusList
      tags:
        - Tipos — Compras
      summary: Lista status de processo de compra
      description: Lista os status possíveis em um processo de compra (rascunho, em análise, aprovado, etc.).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDStatusPurchase:
                      type: integer
                      description: Identificador do status do recebimento.
                    StatusPurchase:
                      type: string
                      maxLength: 45
                      description: Descrição do status (`Aberto`, `Em conferência`, `Conferência realizada`, `Finalizado`, etc.).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/sales-channel/commercial-condition:
    get:
      operationId: typeSalesChannelCommercialConditionList
      tags:
        - Tipos — Canal de Venda
      summary: Lista condições comerciais do canal de venda
      description: >-
        Lista as condições comerciais (B2W, etc.) cadastradas para uma integração de canal de venda específica da
        empresa autenticada.
      parameters:
        - name: IDCompanyIntegration
          in: query
          required: true
          schema:
            type: integer
          description: Identificador da integração da empresa.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeSkuCommercialCondition:
                      type: integer
                      description: Identificador da condição comercial.
                    CommercialCondition:
                      type: string
                      maxLength: 45
                      nullable: true
                      description: 'Descrição da condição comercial (ex.: `Novo`, `Usado`, `Recondicionado`).'
        '400':
          description: |-
            Erro de validação. Mensagens possíveis:
            - `[BadRequest] - IDCompanyIntegration é obrigatório` — Query `IDCompanyIntegration` ausente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/sales-channel/sales-policy:
    get:
      operationId: typeSalesChannelSalesPolicyList
      tags:
        - Tipos — Canal de Venda
      summary: Lista políticas de venda do canal
      description: >-
        Lista as políticas de venda (Sales Policy — VTEX, etc.) cadastradas para uma integração de canal de venda
        específica da empresa autenticada.
      parameters:
        - name: IDCompanyIntegration
          in: query
          required: true
          schema:
            type: integer
          description: Identificador da integração da empresa.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeSkuSalesPolicy:
                      type: integer
                      description: Identificador da política de venda.
                    SalesPolicy:
                      type: string
                      maxLength: 45
                      description: 'Descrição da política (ex.: `Atacado`, `Varejo`, `Distribuidor`).'
                    value:
                      type: string
                      description: Atalho da própria linha (uso interno do frontend).
                    label:
                      type: string
                      description: Atalho da própria linha (uso interno do frontend).
        '400':
          description: |-
            Erro de validação. Mensagens possíveis:
            - `[BadRequest] - IDCompanyIntegration é obrigatório` — Query `IDCompanyIntegration` ausente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/invoice/service/type:
    get:
      operationId: typeServiceCodeList
      tags:
        - Tipos — Nota Fiscal
      summary: Lista códigos de serviço (NFS-e)
      description: >-
        Lista os códigos municipais de serviço aplicáveis. Por padrão usa o município cadastrado na empresa autenticada.
        Hoje só há códigos cadastrados para os municípios de São Paulo (3550308) e Barueri (3505708); demais municípios
        caem em uma lista genérica (CityCode `0`).
      parameters:
        - name: CityCode
          in: query
          required: false
          schema:
            type: string
          description: Código IBGE do município. Quando ausente, usa o município cadastrado na empresa.
        - name: IDCompanyInvoice
          in: query
          required: false
          schema:
            type: integer
          description: Identificador da configuração de NFS-e da empresa (atualmente não usado para filtrar, mas aceito).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDNfsServiceCode:
                      type: integer
                      description: Identificador interno do código de serviço da NFSe.
                    CityCode:
                      type: integer
                      description: Código do município (IBGE).
                    ServiceCode:
                      type: string
                      maxLength: 45
                      description: Código de serviço conforme cadastro municipal.
                    ServiceDescription:
                      type: string
                      maxLength: 1000
                      description: Descrição do serviço.
                    ServiceAliquot:
                      type: number
                      nullable: true
                      description: Alíquota padrão do serviço para o município (em fração `0–1` ou percentual, conforme cadastro).
        '400':
          description: >-
            Erro de validação. Mensagens possíveis:

            - `[BadRequest] - Empresa não esta com endereço preenchido no cadastro` — Empresa não tem
            `CompanyAddressIbgeCityCode` cadastrado.

            - `[BadRequest] - Empresa não existe` — Empresa não localizada pelo `accountname`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: >-
            Erro interno (prefixo `Error:`).


            **Mensagens sem prefixo padrão (podem cair como 500 ou no corpo do default):**

            - `Município não tem emissão de nota fiscal de serviço` — Nenhum código encontrado para o município
            (mensagem sem prefixo padrão).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/sku/action:
    get:
      operationId: typeSkuAction
      tags:
        - Tipos — SKU
      summary: Lista ações de SKU
      description: Lista as ações disponíveis para SKUs (vendas, transferência, ajuste, produção, etc.).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDSkuAction:
                      type: integer
                      description: Identificador do tipo de ação aplicável a SKUs.
                    ActionName:
                      type: string
                      maxLength: 45
                      description: Nome da ação (`Importar custo`, `Ajustar saldo`, `Trocar status`, etc.).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/sku/location/address:
    get:
      operationId: typeSkuAddressList
      tags:
        - Tipos — SKU
      summary: Lista tipos de endereço de armazenagem
      description: >-
        Lista os tipos de endereço de armazenagem (rua, prateleira, posição, etc.) usados no controle de localização de
        SKUs em depósito.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeAddress:
                      type: integer
                      description: 'Tipo de endereço de armazenagem: `1` Picking, `2` Pulmão, `3` Blocado.'
                      enum:
                        - 1
                        - 2
                        - 3
                    RecordTimestamp:
                      type: string
                      format: date-time
                      description: Data e hora do cadastro do tipo.
                    TypeAddress:
                      type: string
                      maxLength: 60
                      description: Nome do tipo de endereço (`Picking`, `Pulmão`, `Bloqueado`, `Quarentena`, etc.).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/sku/inventory-summary/status:
    get:
      operationId: typeSkuInventorySummaryStatusList
      tags:
        - Tipos — SKU
      summary: Lista status do resumo de inventário
      description: Lista os status possíveis do resumo de inventário (agendado, em contagem, conferido, divergente, etc.).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeStatusSkuInventory:
                      type: integer
                      description: Identificador do status do inventário.
                    TypeStatusSkuInventory:
                      type: string
                      maxLength: 45
                      nullable: true
                      description: Descrição do status (`Aberto`, `Em andamento`, `Finalizado`, `Cancelado`, etc.).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/sku/type:
    get:
      operationId: typeSkuTypeList
      tags:
        - Tipos — SKU
      summary: Lista tipos de produto/SKU
      description: Lista os tipos de produto/SKU (produto, kit, variação, etc.).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeProduct:
                      type: integer
                      description: Identificador do tipo de produto.
                      enum:
                        - 1
                        - 2
                        - 3
                        - 4
                        - 5
                        - 6
                        - 7
                        - 8
                    TypeProduct:
                      type: string
                      maxLength: 45
                      description: Nome curto do tipo (`Simples`, `Kit`, `Variação`).
                    TypeProductDescription:
                      type: string
                      maxLength: 45
                      description: Descrição amigável do tipo de produto.
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/sku/status:
    get:
      operationId: typeStatusSkuList
      tags:
        - Tipos — SKU
      summary: Lista status de SKU
      description: Lista os status que um SKU pode assumir.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeStatusSku:
                      type: integer
                      description: Identificador do status do SKU.
                    TypeStatusSku:
                      type: string
                      maxLength: 45
                      description: Descrição do status (`Ativo`, `Inativo`, `Suspenso`, etc.).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/sku/production/status:
    get:
      operationId: typeStatusSkuProductionList
      tags:
        - Tipos — SKU
      summary: Lista status de produção de SKU
      description: Lista os status do processo de produção de SKU.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeStatusSkuProduction:
                      type: integer
                      description: 'Status da etapa de produção: `1` Finalizado, `2` Aberto, `3` Em andamento, `4` Cancelado.'
                      enum:
                        - 1
                        - 2
                        - 3
                        - 4
                    TypeStatusSkuProduction:
                      type: string
                      maxLength: 45
                      description: Descrição do status (`Aberta`, `Em andamento`, `Finalizada`, etc.).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/supplier/type:
    get:
      operationId: typeSupplierTypeList
      tags:
        - Tipos — Fornecedor
      summary: Lista tipos de fornecedor
      description: Lista os tipos de fornecedor (matéria-prima, revenda, serviços, etc.).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeSupplier:
                      type: integer
                      description: Identificador do tipo de fornecedor.
                    TypeSupplier:
                      type: string
                      maxLength: 45
                      description: Descrição (`Fornecedor`, `Transportadora`, `Cliente`, `Fabricante`, etc.).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/tax/cst:
    get:
      operationId: typeTaxCst
      tags:
        - Tipos — Impostos
      summary: Lista códigos de origem da mercadoria
      description: Lista os códigos de origem da mercadoria (0 nacional, 1 estrangeira importação direta, etc.) usados em CSTs.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    NfOrig:
                      type: integer
                      description: Código da origem da mercadoria conforme leiaute SEFAZ (`0` Nacional, `1` Importada, etc.).
                    NfOrigDescription:
                      type: string
                      maxLength: 150
                      description: Descrição da origem da mercadoria.
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/tax/crt:
    get:
      operationId: typeTaxCstList
      tags:
        - Tipos — Impostos
      summary: Lista CRT (regime tributário)
      description: Lista os Códigos de Regime Tributário (CRT) — Simples Nacional, Regime Normal, etc.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    Crt:
                      type: integer
                      description: Código de Regime Tributário (CRT) da empresa.
                    CrtDescription:
                      type: string
                      maxLength: 100
                      description: Descrição do regime (`Simples Nacional`, `Lucro Presumido`, `Lucro Real`, etc.).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/tax/mod-emi:
    get:
      operationId: typeTaxModEmiList
      tags:
        - Tipos — Impostos
      summary: Lista modelos de documento fiscal
      description: Lista os modelos de documento fiscal (NF-e 55, NFC-e 65, NFS-e, etc.).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    NfModNf:
                      type: integer
                      description: Código da modalidade do documento fiscal (`55` NF-e, `65` NFC-e, `57` CT-e, etc.).
                    NfModNfDescription:
                      type: string
                      maxLength: 100
                      description: Descrição da modalidade.
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/invoice/mod-frete:
    get:
      operationId: typeTaxModFreteList
      tags:
        - Tipos — Nota Fiscal
      summary: Lista modalidades de frete
      description: Lista as modalidades de frete da NF-e (CIF, FOB, por conta de terceiros, etc.).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    NfModFrete:
                      type: integer
                      description: Código da modalidade de frete na NF-e.
                    NfModFreteDescription:
                      type: string
                      maxLength: 200
                      nullable: true
                      description: Descrição da modalidade (`Emitente`, `Destinatário`, `Terceiros`, `Sem frete`, etc.).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/tax/mot-des-icms:
    get:
      operationId: typeTaxMotDesIcmsList
      tags:
        - Tipos — Impostos
      summary: Lista motivos de desoneração de ICMS
      description: Lista os motivos válidos para desoneração de ICMS.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    NfMotDesICMS:
                      type: integer
                      description: Código do motivo de desoneração de ICMS.
                    NfMotDesICMSDescription:
                      type: string
                      maxLength: 200
                      description: Descrição do motivo de desoneração.
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/tax/nbs:
    get:
      operationId: typeTaxNbs
      tags:
        - Tipos — Impostos
      summary: Lista códigos NBS
      description: >-
        Lista os códigos NBS (Nomenclatura Brasileira de Serviços). Sem o parâmetro `NBS`, retorna a lista paginada com
        `NBS` e `Description`. Quando `NBS` é informado (pontos opcionais), retorna um único objeto detalhado com os
        `CIndOp` aplicáveis e o `IBSLocation` de cada um.
      parameters:
        - name: NBS
          in: query
          required: false
          schema:
            type: string
          description: >-
            Código NBS exato. Aceita formato com ou sem pontos (ex.: `1.0801.10.00` ou `108011000`). Quando informado,
            retorna o detalhe — caso contrário a lista geral.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    description: 'Quando `NBS` não é informado: lista geral.'
                    items:
                      type: object
                      properties:
                        NBS:
                          type: string
                          description: Código NBS formatado com pontos (`1.0801.10.00`).
                        Description:
                          type: string
                          description: Descrição do serviço (NBS) ou da categoria, conforme o modo de resposta.
                  - type: object
                    description: 'Quando `NBS` é informado: detalhe do código.'
                    properties:
                      NBS:
                        type: string
                        description: Código do serviço na NBS (Nomenclatura Brasileira de Serviços).
                      Description:
                        type: string
                        description: Descrição do serviço (NBS) ou da categoria, conforme o modo de resposta.
                      CIndOp:
                        type: array
                        items:
                          type: object
                          properties:
                            CIndOp:
                              type: string
                              description: Código do indicador de operação (`cIndOp`) conforme leiaute da Reforma Tributária.
                            IBSLocation:
                              type: string
                              description: Código de localização IBS associado ao indicador de operação.
                        description: Lista de códigos de indicador de operação (`CIndOp`) e respectivos códigos de localização IBS.
        '400':
          description: |-
            Erro de validação. Mensagens possíveis:
            - `[BadRequest] - NBS não encontrado` — O código informado não existe na base.
            - `[BadRequest] - Erro ao listar NBS` — Falha ao consultar a base de NBS.
            - `[BadRequest] - Erro ao buscar NBS` — Falha ao consultar o detalhe do NBS informado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/tax/pag-band:
    get:
      operationId: typeTaxPagBandList
      tags:
        - Tipos — Impostos
      summary: Lista bandeiras de cartão (NF-e)
      description: Lista as bandeiras de cartão aceitas no campo de pagamento da NF-e.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    NfTBand:
                      type: string
                      maxLength: 2
                      description: Código da bandeira do cartão na NF-e.
                    NfTBandDescription:
                      type: string
                      maxLength: 100
                      description: Nome da bandeira (`Visa`, `Mastercard`, `Elo`, etc.).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/tax/pag-type:
    get:
      operationId: typeTaxPagTypeList
      tags:
        - Tipos — Impostos
      summary: Lista categorias de pagamento (NF-e)
      description: Lista as categorias de pagamento aceitas no campo de pagamento da NF-e.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypePaymentCategory:
                      type: integer
                      description: Identificador da categoria de pagamento.
                    TypePaymentCategory:
                      type: string
                      maxLength: 100
                      description: Descrição da categoria (`Dinheiro`, `Cartão de crédito`, `Pix`, `Boleto`, etc.).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/order/tracking-status:
    get:
      operationId: typeTrackingStatusList
      tags:
        - Tipos — Pedido
      summary: Lista status de rastreamento
      description: >-
        Lista os status de rastreamento. Quando filtrado, retorna apenas status que possuem template de e-mail
        associado.
      parameters:
        - name: EmailTemplate
          in: query
          required: false
          schema:
            type: string
          description: Quando `1`, retorna apenas status com template de e-mail.
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDStatusTracking:
                      type: integer
                      description: Identificador do status de rastreio.
                    StatusTracking:
                      type: string
                      maxLength: 45
                      description: Descrição do status de rastreio (`Coletado`, `Em trânsito`, `Entregue`, `Devolvido`, etc.).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/sku/warehouse:
    get:
      operationId: typeWarehouseTypeList
      tags:
        - Tipos — SKU
      summary: Lista tipos de depósito
      description: Lista os tipos de depósito disponíveis (próprio, em trânsito, fulfillment, etc.).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeStockKeepingUnitWarehouse:
                      type: integer
                      description: Identificador do tipo de armazém.
                    TypeStockKeepingUnitWarehouse:
                      type: string
                      maxLength: 45
                      nullable: true
                      description: Descrição do tipo (`Padrão`, `Divergência`, `Quarentena`, `Bloqueio`, etc.).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/hub/product/question-answer:
    get:
      operationId: typehubProductQuestionAnswerList
      tags:
        - Hub — Tipos de Referência
      summary: Lista status de pergunta de produto (Hub)
      description: Lista os status possíveis de uma pergunta de produto em marketplaces (pendente, respondida, descartada, etc.).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDTypeHubProductQuestionAnswerStatus:
                      type: integer
                      description: Identificador do status de perguntas/respostas do produto no canal.
                      enum:
                        - 1
                        - 2
                        - 3
                        - 4
                        - 7
                    TypeHubProductQuestionAnswerStatus:
                      type: string
                      maxLength: 45
                      description: Descrição do status (`Não respondida`, `Respondida`, `Excluída`, etc.).
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/user:
    get:
      operationId: userJobPositionList
      tags:
        - Tipos — Usuário
      summary: Lista cargos de usuário
      description: Lista os cargos cadastrados para usuários (vendedor, gestor, etc.).
      responses:
        '200':
          description: Lista retornada.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDUserJobPosition:
                      type: integer
                      description: Identificador da função/cargo do usuário.
                    UserJobPositionName:
                      type: string
                      maxLength: 45
                      description: 'Nome da função/cargo (ex.: `Operador`, `Separador`, `Conferente`, `Gestor`).'
                    UserJobPositionCategory:
                      type: string
                      maxLength: 100
                      nullable: true
                      description: Categoria da função, quando agrupada.
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/order/type/{idordertype}/type-tax:
    parameters:
      - name: idordertype
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do tipo de pedido (`IDTypeOrder`).
    post:
      operationId: orderTypeOrderTaxPost
      tags:
        - Tipos — Pedido
      summary: Vincula uma regra fiscal a um tipo de pedido
      description: >-
        Cadastra uma nova vinculação entre um **tipo de pedido** e uma **regra fiscal** (`TypeTax`). Cada tipo de pedido
        só pode ter **uma vinculação por departamento fiscal** — se já existir uma vinculação para a mesma combinação
        (tipo de pedido × departamento fiscal da regra), a chamada falha.


        A resposta é o detalhe completo do tipo de pedido atualizado (mesmo formato do `GET
        /type/order/type/{idordertype}`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - IDTax
              properties:
                IDTax:
                  type: integer
                  description: >-
                    Identificador da regra fiscal a ser vinculada. Precisa pertencer à mesma empresa e ter `Status = 1`
                    no departamento fiscal correspondente.
        description: >-
          Vincula uma regra fiscal (CFOP) ao tipo de pedido. Apenas `IDTax` no corpo. O sistema valida que a regra
          existe, pertence à empresa autenticada e que ainda não existe outra regra do mesmo departamento fiscal
          vinculada a este tipo de pedido (apenas uma regra por departamento por tipo).
      responses:
        '200':
          description: Vinculação criada. Retorna o detalhe atualizado do tipo de pedido (`OrderTypeOrderGet`).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeOrderDetail'
        '400':
          description: >-
            Erro de validação. Mensagens possíveis:

            - `[BadRequest] - Tipo pedido não existe` — `idordertype` inválido ou de outra empresa.

            - `[BadRequest] - Regra tributária não existe` — `IDTax` inválido, de outra empresa ou inativa.

            - `[BadRequest] - Já existe uma regra tributária para esse tipo de pedido` — já existe vinculação para o
            mesmo departamento fiscal.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /type/order/type/{idordertype}/type-tax/{idtypeordertax}:
    parameters:
      - name: idordertype
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador do tipo de pedido (`IDTypeOrder`).
      - name: idtypeordertax
        in: path
        required: true
        schema:
          type: integer
          format: int32
        description: Identificador da vinculação tipo-pedido × regra fiscal (`IDTypeOrderTax`).
    put:
      operationId: orderTypeOrderTaxPut
      tags:
        - Tipos — Pedido
      summary: Altera a regra fiscal vinculada ao tipo de pedido
      description: >-
        Atualiza a regra fiscal (`IDTax`) de uma vinculação existente entre tipo de pedido e regra fiscal. Como cada
        tipo de pedido só pode ter uma vinculação por departamento fiscal, a chamada falha se a nova regra recair no
        mesmo departamento fiscal de outra vinculação do mesmo tipo de pedido.


        A resposta é o detalhe completo do tipo de pedido atualizado (mesmo formato do `GET
        /type/order/type/{idordertype}`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - IDTax
              properties:
                IDTax:
                  type: integer
                  description: Nova regra fiscal a vincular. Precisa pertencer à mesma empresa e ter `Status = 1`.
        description: >-
          Atualiza a regra fiscal vinculada ao tipo de pedido — apenas o campo `IDTax`. Mesmas validações do POST (regra
          existe na empresa; sem duplicidade de departamento fiscal no mesmo tipo de pedido).
      responses:
        '200':
          description: Vinculação atualizada. Retorna o detalhe atualizado do tipo de pedido.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeOrderDetail'
        '400':
          description: >-
            Erro de validação. Mensagens possíveis:

            - `[BadRequest] - Tipo pedido não existe` — `idordertype` inválido ou de outra empresa.

            - `[BadRequest] - Regra tributária não existe` — `IDTax` inválido, de outra empresa ou inativa.

            - `[BadRequest] - Regra tributário do tipo de pedido não existe` — `idtypeordertax` inválido.

            - `[BadRequest] - Já existe uma regra tributária para esse tipo de pedido` — a nova regra cai no mesmo
            departamento fiscal de outra vinculação do mesmo tipo de pedido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: orderTypeOrderTaxDelete
      tags:
        - Tipos — Pedido
      summary: Remove a regra fiscal vinculada ao tipo de pedido
      description: >-
        Remove uma vinculação existente entre tipo de pedido e regra fiscal.


        A resposta é o detalhe completo do tipo de pedido atualizado (mesmo formato do `GET
        /type/order/type/{idordertype}`).
      responses:
        '200':
          description: Vinculação removida. Retorna o detalhe atualizado do tipo de pedido.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeOrderDetail'
        '400':
          description: 'Vinculação não encontrada. Mensagem: `[BadRequest] - Regra tributário do tipo de pedido não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Erro interno (prefixo `Error:`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /sku:
    get:
      operationId: skuList
      tags:
        - Produtos e SKUs
      summary: Lista SKUs da empresa
      description: >-
        Lista SKUs paginados (lote de 500 por página em ambos os modos; offset = `Page × 500`). Aplica filtros, busca
        textual e variantes de cálculo de preço, estoque e métricas de venda conforme os parâmetros.
      parameters:
        - name: Page
          in: query
          schema:
            type: integer
          description: Página (offset = `Page * 500`).
        - name: Simple
          in: query
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` retorna lista reduzida (resposta `SkuListItemSimple`). `0` retorna o detalhamento padrão.'
        - name: Sales
          in: query
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` inclui métricas históricas de venda no retorno.'
        - name: Search
          in: query
          schema:
            type: string
          description: >-
            Busca textual contra `IDSku`, nome `SkuName`, código de barras `BarCode` e código de referência
            `IDSkuCompany`. Espaços viram curinga interno.
        - name: IDSku
          in: query
          schema:
            type: integer
          description: Filtra pelo identificador do produto/SKU.
        - name: SkuName
          in: query
          schema:
            type: string
          description: Nome do SKU (busca `LIKE`).
        - name: BarCode
          in: query
          schema:
            type: string
          description: >-
            Código de barras exato. Aceita também códigos de balança quando a parametrização de uso de balança está
            ativa.
        - name: IDTypeSku
          in: query
          schema:
            type: integer
          description: Filtra pelo tipo de SKU.
        - name: IDBrand
          in: query
          schema:
            type: integer
          description: Filtra pelo identificador da marca.
        - name: IDCategory
          in: query
          schema:
            type: integer
          description: Filtra pelo identificador da categoria.
        - name: IDStatusSku
          in: query
          schema:
            type: array
            items:
              type: integer
              enum:
                - 0
                - 1
                - 2
                - 3
                - 4
          description: Lista de status separados por vírgula. Default `1,2,3,4`.
          style: form
          explode: false
        - name: IDSkuCompany
          in: query
          schema:
            type: string
          description: Código de referência (busca `LIKE`).
        - name: IDSkuCompanyStrict
          in: query
          schema:
            type: string
          description: Código de referência exato (sem `LIKE`).
        - name: SupplierCode
          in: query
          schema:
            type: string
          description: Código do fornecedor.
        - name: IDSupplier
          in: query
          schema:
            type: integer
          description: Identificador do fornecedor.
        - name: IDSupplierCost
          in: query
          schema:
            type: integer
          description: Quando informado, inclui o `LastValueCost` daquele fornecedor no item retornado (apenas no modo Simple).
        - name: Package
          in: query
          schema:
            type: integer
          description: Filtra pelo tipo de embalagem.
        - name: IDCompanyIntegration
          in: query
          schema:
            type: integer
          description: Filtra SKUs com vínculo à integração.
        - name: IDCompanyIntegrationNot
          in: query
          schema:
            type: integer
          description: Filtra SKUs sem vínculo à integração.
        - name: IDTypeCompanyIntegration
          in: query
          schema:
            type: integer
          description: Filtra pelo tipo de integração da empresa.
        - name: IDTypeCompanyIntegrationNot
          in: query
          schema:
            type: integer
          description: Exclui do resultado o tipo de integração da empresa informado.
        - name: SinceIDSku
          in: query
          schema:
            type: integer
          description: Retorna apenas SKUs com `IDSku` maior ou igual ao informado.
        - name: SinceRecordTimestamp
          in: query
          schema:
            type: string
            format: date-time
          description: Filtra registros criados a partir desta data/hora (formato ISO 8601).
        - name: SinceDateLastRecordModification
          in: query
          schema:
            type: string
            format: date-time
          description: >-
            Filtra registros modificados a partir desta data/hora (formato ISO 8601). Útil para sincronização
            incremental.
        - name: IDCompanyInvoice
          in: query
          schema:
            type: integer
          description: Filtra pelo identificador da nota fiscal da empresa.
        - name: IDTypeBuyOrderMake
          in: query
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 3
          description: Filtra pela sinalização de pedido de compra recomendado. Default `4`.
        - name: IDCompanySalesPolicy
          in: query
          schema:
            type: integer
          description: Política comercial usada para `PriceSell`/`PriceList` no retorno.
        - name: AbcCurve
          in: query
          schema:
            type: string
            enum:
              - A
              - B
              - C
          description: Filtra pela classificação da curva ABC do produto (`A`, `B` ou `C`).
        - name: OwnProduction
          in: query
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Quando `1`, restringe a itens de produção própria.
        - name: HasSupplier
          in: query
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` SKUs com fornecedor cadastrado; `0` sem fornecedor.'
        - name: Tags
          in: query
          schema:
            type: string
          description: Lista de etiquetas (combinadas com `AND`).
        - name: HasNoProduct
          in: query
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` exclui SKUs vinculados a um produto-pai.'
        - name: DateFrom
          in: query
          schema:
            type: string
            format: date-time
          description: Filtra por `RecordTimestamp` a partir desta data.
        - name: DateTo
          in: query
          schema:
            type: string
            format: date
          description: Filtra por `RecordTimestamp` até esta data (inclusiva).
        - name: QtyAvailable
          in: query
          schema:
            type: integer
          description: Quantidade de referência para `HealthType`.
        - name: HealthType
          in: query
          schema:
            type: string
            enum:
              - greater
              - smaller
          description: Filtra SKUs com saldo maior ou menor que `QtyAvailable`.
        - name: SkuSimilarCode
          in: query
          schema:
            type: string
          description: Filtra por SKUs em grupos que contenham este código similar.
        - name: IDStockKeepingUnitCollection
          in: query
          schema:
            type: integer
          description: Filtra por coleção.
        - name: IDStockKeepingUnitLocationCategory
          in: query
          schema:
            type: integer
          description: Filtra pelo identificador da categoria de localização do SKU.
        - name: IDStockKeepingUnitWarehouse
          in: query
          schema:
            type: string
          description: >-
            Lista de armazéns separados por vírgula. Quando informado, as métricas de venda e estoque são restritas a
            esses armazéns.
        - name: IDTypeOrder
          in: query
          schema:
            type: integer
          description: Quando informado, aplica a margem de segurança `SafetyStockPercent` do tipo de pedido sobre `QtyAvailable`.
      responses:
        '200':
          description: Lista de SKUs.
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/SkuListItemSimple'
                  - type: array
                    items:
                      $ref: '#/components/schemas/SkuListItem'
        '400':
          description: Erro de validação dos filtros enviados.
        '500':
          description: Erro interno. Prefixo `Error:`.
    post:
      operationId: skuPost
      tags:
        - Produtos e SKUs
      summary: Cria um SKU
      description: >-
        Cria um SKU com validações de marca, categoria, departamento fiscal, faturador, linha de produção, unidade de
        medida e tipo. Quando `PriceList`/`PriceSell` são enviados, cria um registro inicial de preço. Quando
        `Variations` é enviado, vincula valores de variação. Não permite duplicar `IDSkuCompany` nem `BarCode` para a
        empresa.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuCreateBody'
        description: >-
          Dados do SKU a cadastrar. `IDTypeSku` é obrigatório e define o tipo do SKU (produto normal, kit, variação,
          serviço, etc.). Quando o SKU é uma variação (`IDTypeSku=4` no produto-pai), informe `IDSkuCompanyComposing`
          para vincular a variação ao produto-pai. Preço inicial (`PriceSell`, `PriceList`) e variações iniciais
          (`Variations[]`) podem ser cadastrados na mesma requisição.
      responses:
        '200':
          description: >-
            SKU criado. Retorna um array com o detalhe do SKU recém-criado, incluindo campos de sugestão de compra
            (`StockSafety`, `StockFree`, `StockReference`, `BuyOrderMake`, `IDTypeBuyOrderMake`,
            `BuyOrderMakeQuantity`).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuListItem'
        '400':
          description: >-
            Validação falhou. Prefixo `[BadRequest]`. Mensagens: `Marca não existe`, `Categoria não existe`, `Cód.
            referência já existe na base`, `Código de Barras já existe na base`, `Departamento fiscal não existe`, `Tipo
            sku não existe`, `Origem SKU não existe`, `Faturador não existe`, `Medida SKU não existe`, `Linha de
            produção não existe`, `Politica comercial não existe`, `Variação X e Grade Y não existe`, `Campo Tipo
            variação e Valor variação não enviados`, `Categoria localização não existe`, `Erro ao criar item`.
        '404':
          description: 'Empresa não localizada. Prefixo `[NotFound]`. Mensagem: `Empresa não existe`.'
        '500':
          description: Erro interno. Prefixo `Error:`.
      parameters:
        - name: Composing
          in: query
          required: false
          schema:
            type: integer
          description: >-
            Quando informado (valor verdadeiro), cria o SKU como componente/kit vinculado a um produto-pai: o código de
            referência recebe o sufixo `-KIT<IDSku>` derivado de `IDSkuCompanyComposing`, em vez de ser preenchido
            automaticamente com o `IDSku`.
  /sku/{idsku}:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do SKU.
    get:
      operationId: skuGet
      tags:
        - Produtos e SKUs
      summary: Detalha um SKU
      description: >-
        Retorna o detalhe completo do SKU, com listas relacionadas (fornecedores, códigos de barras adicionais,
        embalagens) e campos calculados (saldo, custos, valor em estoque). Quando `Sales=1`, troca o detalhe pelas
        métricas históricas de venda calculadas a partir dos últimos 150 dias.
      parameters:
        - name: Sales
          in: query
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` para retornar métricas históricas de venda em vez do detalhe completo.'
      responses:
        '200':
          description: SKU encontrado. Lista com um único elemento (ou vazia, se não encontrar).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuDetail'
        '400':
          description: 'Parâmetro de path ausente. Prefixo `[BadRequest]`. Mensagem: `não localizado`.'
        '500':
          description: Erro interno. Prefixo `Error:`.
    put:
      operationId: skuPut
      tags:
        - Produtos e SKUs
      summary: Atualiza um SKU
      description: >-
        Atualiza os campos enviados do SKU. Alterações de `IDTypeSku` exigem que o item não tenha movimentações, lote,
        vínculo com kit, variação nem produto-pai. Alterações em `BarCode` validam unicidade contra códigos principais,
        adicionais e de embalagem da mesma empresa.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuUpdateBody'
        description: >-
          Atualização parcial do SKU — envie apenas os campos que quer alterar; os demais permanecem com o valor atual.
          Alterar `IDTypeSku` é restrito: o SKU não pode ter movimentação, lote, ser componente de kit, ter variação nem
          ser produto-pai (ver erros 400).
      responses:
        '200':
          description: SKU atualizado. Retorna o detalhe atualizado via `skuGet`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuDetail'
        '400':
          description: >-
            Validação falhou. Prefixo `[BadRequest]`. Mensagens: `não localizado`, `NCM EX TIPI precisa ter 2 ou 3
            dígitos`, `Marca não existe`, `Categoria não existe`, `Cod. Referência já existe na base`, `Código de Barras
            já existe no sku: <ref>`, `Departamento fiscal não existe`, `Não pode alterar o tipo de um item criado há
            mais de 30 dias`, `Item já teve movimentação ... não pode ser alterado o tipo`, `Item tem
            lote/composição/grade/sku filho ...`, `Tipo SKU não existe`, e variantes relacionadas a regras de mudança de
            tipo.
        '500':
          description: Erro interno. Prefixo `Error:`.
    delete:
      operationId: skuDelete
      tags:
        - Produtos e SKUs
      summary: Exclui um SKU
      description: >-
        Remove o SKU. Bloqueia a exclusão se houver movimentação cadastrada ou se o SKU estiver anunciado em alguma
        integração — nesses casos a recomendação é alterar o status para inativo.
      responses:
        '200':
          description: SKU excluído.
          content:
            application/json:
              schema:
                type: string
                example: sucesso
        '400':
          description: >-
            Bloqueio. Prefixo `[BadRequest]`. Mensagens: `Sku já teve movimentação e não pode ser excluido. Alterar
            status para inativo`, `Sku tem anúncio e precisa remover antes de excluir o sku`, `Sku não existe`.
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/image/{idsku}:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
    get:
      operationId: skuImageGet
      tags:
        - Imagens de SKU
      summary: Lista as imagens de um SKU
      description: >-
        Retorna as imagens do SKU ordenadas por `ImageOrder`. Quando o SKU está configurado para herdar imagens do
        produto-pai (`ShareProductImage = 1`), inclui também as imagens deste com `ProductImage = 1`.
      responses:
        '200':
          description: Lista de imagens.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuImage'
        '500':
          description: Erro interno. Prefixo `Error:`.
    post:
      operationId: skuImagePost
      tags:
        - Imagens de SKU
      summary: Envia uma imagem para o SKU
      description: >-
        Aceita imagem via upload multipart (campo `file`) ou via URL externa (campo `Url` no JSON do body). A primeira
        imagem cadastrada vira automaticamente a principal. Quando `IDHubProduct` ou `IDHubAdvertisement` é informado, a
        imagem é vinculada ao anúncio correspondente.
      parameters:
        - name: Invoke
          in: query
          schema:
            type: string
          description: Nome da rotina a executar após o upload, para refletir a alteração em uma integração específica.
        - name: IDImage
          in: query
          schema:
            type: integer
          description: Quando informado, atualiza a imagem existente.
        - name: OnlyAdvertisement
          in: query
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` salva a imagem como exclusiva de anúncio (não aparece na ficha do SKU).'
        - name: IDHubProduct
          in: query
          schema:
            type: integer
          description: Vincula a imagem a um anúncio (produto no hub).
        - name: IDHubAdvertisement
          in: query
          schema:
            type: integer
          description: Vincula a imagem a uma variação de anúncio (SKU no hub).
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: Arquivo de imagem.
          application/json:
            schema:
              type: object
              properties:
                Url:
                  type: string
                  description: URL externa da imagem; o serviço baixa e armazena.
        description: >-
          Corpo do `POST /sku/image/{idsku}`: aceita três formatos — arquivo binário em `multipart/form-data` no campo
          `file`; corpo JSON `{ "Url": "<URL externa>" }` para baixar a imagem de uma URL; ou nenhum corpo quando a
          query traz `IDImage` (clonar uma imagem existente para o SKU). Demais opções (clone para anúncio, ordem,
          principal) vêm pela query string.
      responses:
        '200':
          description: Imagem cadastrada.
          content:
            application/json:
              schema:
                type: object
                description: Retorno da rotina executada (varia conforme `Invoke`).
                additionalProperties: true
        '400':
          description: >-
            Anúncio inválido ou arquivo recusado. Mensagens variam: `Anúncio não encontrado`, `Variação anúncio não
            encontrada` (retornadas como `statusCode: 400`).
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/image/{idsku}/{idimage}:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
      - name: idimage
        in: path
        required: true
        schema:
          type: integer
        description: Identificador da imagem.
    put:
      operationId: skuImagePut
      tags:
        - Imagens de SKU
      summary: Atualiza uma imagem do SKU
      description: Atualiza atributos da imagem (principal, ordem, nome, variante de kit, URL).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                IsMain:
                  type: integer
                  description: '`1` define como imagem principal.'
                ImageName:
                  type: string
                  maxLength: 300
                  description: Novo nome de exibição da imagem.
                Kit:
                  type: integer
                  description: Variante do kit (1 a 4) à qual a imagem se aplica.
                Url:
                  type: string
                  maxLength: 400
                  description: Nova URL da imagem.
                ImageOrder:
                  type: integer
                  description: Ordem de exibição.
        description: >-
          Campos da imagem do SKU a atualizar — apenas os enviados são aplicados. Aceita `IsMain` (marca como imagem
          principal), `ImageName`, `Kit`, `Url` e `ImageOrder`.
      responses:
        '200':
          description: Imagem atualizada. Retorna `skuImageGet`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuImage'
        '400':
          description: 'SKU/imagem não encontrada. Prefixo `[BadRequest]`. Mensagem: `Company não existe`.'
        '500':
          description: Erro interno. Prefixo `Error:`.
    delete:
      operationId: skuImageDelete
      tags:
        - Imagens de SKU
      summary: Remove uma imagem do SKU
      description: >-
        Remove a imagem. Quando a imagem ainda está vinculada a um anúncio em hub, em vez de excluir, marca-a como
        exclusiva de anúncio (`OnlyAdvertisement = 1`). Quando a imagem removida era a principal, promove a próxima
        imagem por ordem.
      responses:
        '200':
          description: Imagem removida. Retorna `skuImageGet`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuImage'
        '400':
          description: 'Imagem não pertence ao SKU/empresa. Prefixo `[BadRequest]`. Mensagem: `Sku não existe`.'
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/kit/summary/{idsku}:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
    get:
      operationId: kitSummaryGet
      tags:
        - Kits
      summary: Resumo dos kits (variantes) de um SKU
      description: >-
        Retorna o resumo de cada variante de kit do SKU (até 4 variantes), com quantidade montável, soma de preço/custo
        dos componentes e markup.
      responses:
        '200':
          description: Resumo das variantes.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/KitSummary'
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/kit/summary/{idsku}/{idstockkeepingunitkit}:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
      - name: idstockkeepingunitkit
        in: path
        required: true
        schema:
          type: integer
        description: Identificador da variante de kit.
    put:
      operationId: kitSummaryPut
      tags:
        - Kits
      summary: Atualiza prioridade de uma variante de kit
      description: Ajusta a prioridade de uma variante de kit do SKU. Aceita apenas para SKUs do tipo 1 ou 2.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - Priority
              properties:
                Priority:
                  type: integer
                  description: Ordem de prioridade da variante.
        description: >-
          Corpo do `PUT /sku/kit/summary/{idsku}/{idstockkeepingunitkit}`: atualiza a prioridade do agrupamento do kit.
          Campos: `Priority` (obrigatório) e `IDStockKeepingUnitKit` (opcional — se omitido, usa o identificador do
          path).
      responses:
        '200':
          description: Prioridade atualizada. Retorna `kitGet`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/KitItem'
        '400':
          description: 'SKU não localizado ou não suporta kit. Prefixo `[BadRequest]`. Mensagem: `Sku não existe`.'
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/kit/{idsku}:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
    get:
      operationId: kitGet
      tags:
        - Kits
      summary: Lista os componentes de um kit
      description: >-
        Lista os componentes do kit selecionado (`kit=1..4`). Quando `Type=KitsRelated`, inverte a perspectiva e lista
        os kits em que este SKU aparece como componente.
      parameters:
        - name: kit
          in: query
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 3
              - 4
          description: Variante do kit. Default `1`.
        - name: Type
          in: query
          schema:
            type: string
            enum:
              - Components
              - KitsRelated
          description: >-
            `Components` lista componentes do kit do SKU; `KitsRelated` lista kits que usam este SKU como componente.
            Default `Components`.
      responses:
        '200':
          description: Lista de componentes (ou kits relacionados).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/KitItem'
        '500':
          description: Erro interno. Prefixo `Error:`.
    post:
      operationId: kitPost
      tags:
        - Kits
      summary: Adiciona um componente ao kit
      description: >-
        Adiciona um SKU componente à variante de kit do SKU pai. Quando a empresa usa atualização automática de medidas
        de kit, recalcula peso e dimensões do SKU pai a partir dos componentes.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - IDSkuComponent
                - Quantity
              properties:
                IDSkuComponent:
                  type: integer
                  description: >-
                    SKU usado como componente. Precisa ser do tipo Sku, Matéria-prima ou Uso e consumo (`IDTypeSku` em
                    3, 6 ou 7).
                Quantity:
                  type: number
                  description: Quantidade do componente. Precisa ser maior que zero.
                Kit:
                  type: integer
                  enum:
                    - 1
                    - 2
                    - 3
                    - 4
                  description: Variante do kit. Default `1`.
        description: >-
          Dados do item componente do kit a adicionar. Obrigatórios: `IDSkuComponent` (SKU componente — precisa ser do
          tipo normal) e `Quantity` (maior que zero). Opcional: `Kit` (número do agrupamento dentro do kit; padrão 1).
      responses:
        '200':
          description: Componente adicionado. Retorna `kitGet`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/KitItem'
        '400':
          description: >-
            Validação falhou. Prefixo `[BadRequest]`. Mensagens: `Quantidade precisa ser maior que 0`, `Sku não existe`,
            `Sku Componente não existe`, `Componente não é do tipo normal`.
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/kit/{idsku}/{idstockkeepingunitkititems}:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
      - name: idstockkeepingunitkititems
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do componente dentro do kit.
    put:
      operationId: kitPut
      tags:
        - Kits
      summary: Atualiza um componente do kit
      description: >-
        Troca o SKU componente, quantidade ou variante de kit do item. Recalcula medidas do SKU pai quando a atualização
        automática está habilitada.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - IDSkuComponent
                - Quantity
              properties:
                IDSkuComponent:
                  type: integer
                  description: Identificador do SKU componente do kit.
                Quantity:
                  type: number
                  description: Quantidade do componente no kit.
                Kit:
                  type: integer
                  enum:
                    - 1
                    - 2
                    - 3
                    - 4
                  description: 'Tipo de composição do kit: `1` Kit fixo, `2` Kit dinâmico, `3` Combo, `4` Grade.'
        description: >-
          Campos do item componente do kit a atualizar. Aceita `IDSkuComponent` (componente — precisa ser do tipo
          normal), `Quantity` (maior que zero) e `Kit` (número do agrupamento; padrão 1).
      responses:
        '200':
          description: Componente atualizado. Retorna `kitGet`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/KitItem'
        '400':
          description: >-
            Prefixo `[BadRequest]`. Mensagens: `Quantidade precisa ser maior que 0`, `Sku não existe`, `Sku Componente
            não existe`, `Componente não é do tipo normal`, `Erro ao processar a solicitação`.
        '500':
          description: Erro interno. Prefixo `Error:`.
    delete:
      operationId: kitDelete
      tags:
        - Kits
      summary: Remove um componente do kit
      description: Remove o componente do kit. Recalcula medidas do SKU pai quando a atualização automática está habilitada.
      responses:
        '200':
          description: Componente removido. Retorna `kitGet`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/KitItem'
        '400':
          description: 'Prefixo `[BadRequest]`. Mensagens: `Sku não existe`, `Falha ao deletar item kit`.'
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/log:
    get:
      operationId: skuLogList
      tags:
        - Log de SKU
      summary: Lista logs de integração de SKU
      description: >-
        Lista o histórico de integração dos SKUs (envios para hubs, alterações registradas). Paginação fixa de 4000
        registros por página em ordem decrescente de id.
      parameters:
        - name: Page
          in: query
          schema:
            type: integer
          description: Página (offset = `Page * 5000`).
        - name: IDSku
          in: query
          schema:
            type: integer
          description: Filtra pelo identificador do produto/SKU.
        - name: IDSkuCompany
          in: query
          schema:
            type: string
          description: Código de referência (busca `LIKE`).
        - name: SkuName
          in: query
          schema:
            type: string
          description: Nome do SKU (busca `LIKE`).
        - name: IDCompanyIntegration
          in: query
          schema:
            type: integer
          description: Filtra pelo identificador da integração da empresa.
        - name: IDHubProduct
          in: query
          schema:
            type: integer
          description: Filtra pelo identificador do produto no hub.
        - name: IDAction
          in: query
          schema:
            type: integer
          description: Tipo de ação (`IDSkuAction`).
        - name: Status
          in: query
          schema:
            type: integer
          description: 'Filtra por `Header`: `1` sucesso, `2` inativo, outros = erro.'
        - name: DateFrom
          in: query
          schema:
            type: string
            format: date-time
          description: Início do intervalo de datas no filtro (formato `YYYY-MM-DD`).
        - name: DateTo
          in: query
          schema:
            type: string
            format: date
          description: Fim do intervalo de datas no filtro (formato `YYYY-MM-DD`).
        - name: IDStockKeepingUnitIntegrationLog
          in: query
          schema:
            type: integer
          description: Filtra pelo identificador do log de integração do SKU.
      responses:
        '200':
          description: Lista de logs.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuLogItem'
        '400':
          description: Erro de configuração da empresa. Prefixo `[BadRequest]`.
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/package:
    get:
      operationId: skuPackageList
      tags:
        - Tipos de Embalagem
      summary: Lista SKUs embalagem compartilhados
      description: >-
        Lista os SKUs marcados como embalagem (`Package=1`) ativos. Inclui também SKUs de empresas relacionadas via
        integração quando essas empresas habilitam o compartilhamento de embalagens.
      parameters:
        - name: Page
          in: query
          schema:
            type: integer
          description: Página (offset = `Page * 400`).
      responses:
        '200':
          description: Lista de SKUs embalagem.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuPackageItem'
        '400':
          description: Erro de configuração da empresa. Prefixo `[BadRequest]`.
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/pricing:
    get:
      operationId: skuPricingList
      tags:
        - Preços
      summary: Lista preços de SKUs
      description: >-
        Lista os preços cadastrados em cada política comercial. Paginação fixa de 2000 registros. Os filtros permitem
        cruzar por SKU, política, integração e janela de modificação.
      parameters:
        - name: Page
          in: query
          schema:
            type: integer
          description: Página (offset = `Page * 2000`).
        - name: IDSku
          in: query
          schema:
            type: integer
          description: Filtra pelo identificador do produto/SKU.
        - name: SkuName
          in: query
          schema:
            type: string
          description: Filtra pelo nome do produto (busca parcial).
        - name: BarCode
          in: query
          schema:
            type: string
          description: Filtra pelo código de barras do produto.
        - name: IDTypeSku
          in: query
          schema:
            type: integer
          description: Filtra pelo tipo de SKU.
        - name: IDBrand
          in: query
          schema:
            type: integer
          description: Filtra pelo identificador da marca.
        - name: IDCategory
          in: query
          schema:
            type: integer
          description: Filtra pelo identificador da categoria.
        - name: SupplierCode
          in: query
          schema:
            type: string
          description: Filtra pelo código interno do fornecedor.
        - name: IDSupplier
          in: query
          schema:
            type: integer
          description: Filtra pelo identificador do fornecedor.
        - name: Package
          in: query
          schema:
            type: integer
          description: Filtra pelo tipo de embalagem.
        - name: IDSkuCompany
          in: query
          schema:
            type: string
          description: Filtra pelo identificador do vínculo SKU-empresa.
        - name: IDStockKeepingUnitPricing
          in: query
          schema:
            type: integer
          description: Filtra pelo identificador da regra de precificação do SKU.
        - name: IDCompanySalesPolicy
          in: query
          schema:
            type: integer
          description: Filtra pela política de venda da empresa.
        - name: IDTypeCompanyIntegration
          in: query
          schema:
            type: integer
          description: Filtra políticas que estão vinculadas a alguma integração deste tipo.
        - name: SinceDateLastRecordModification
          in: query
          schema:
            type: string
            format: date-time
          description: >-
            Filtra registros modificados a partir desta data/hora (formato ISO 8601). Útil para sincronização
            incremental.
        - name: SinceDateLastRecordModificationFrom
          in: query
          schema:
            type: string
            format: date-time
          description: Início do intervalo da data da última modificação (formato ISO 8601).
        - name: SinceDateLastRecordModificationTo
          in: query
          schema:
            type: string
            format: date
          description: Fim do intervalo da data da última modificação (formato ISO 8601).
      responses:
        '200':
          description: Lista de preços.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuPricing'
        '400':
          description: Erro de configuração da empresa. Prefixo `[BadRequest]`.
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/pricing/{idsku}:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
    post:
      operationId: skuPricingPost
      tags:
        - Preços
      summary: Cria um preço para o SKU
      description: >-
        Cria um preço para o SKU numa política comercial (quando omitida, usa a política padrão da empresa). Com
        `UpdateIfPossible=1`, atualiza o preço já existente do SKU nessa política em vez de criar outro. Numa política
        do tipo Relativa à outra política, o preço é derivado do preço da política base; ao criar preço numa política
        Normal, os preços das políticas relativas derivadas dela são recalculados automaticamente. Preço de venda zerado
        é rejeitado quando a empresa não permite.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuPricingCreateBody'
        description: >-
          Dados da faixa de preço a cadastrar para o SKU. Obrigatórios: `PriceList` (preço de tabela), `PriceSell`
          (preço de venda), `DateFrom` e `DateTo` (datas válidas — vigência). Opcional: `IDCompanySalesPolicy` (política
          comercial associada — quando omitido, usa a política padrão da empresa).
      responses:
        '200':
          description: Preço criado. Retorna `skuPricingList` filtrado pelo SKU.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuPricing'
        '400':
          description: >-
            Validação falhou. Prefixo `[BadRequest]`. Mensagens: `Data DE ou ATÉ inválida`, `Sku não existe`, `Politica
            comercial não existe`, `Empresa não tem politica comercial padrão`, `Já existe um preço para essa política
            comercial e não pode ser criado outro (parametrização)`, `Não foi localizado preço da política comercial
            base: <nome>`, `Não é permitido inserir preço de venda zerado. Validar configuração da empresa`.
        '500':
          description: Erro interno. Prefixo `Error:`.
      parameters:
        - name: UpdateIfPossible
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
          description: >-
            Quando `1`, faz upsert: se já existe preço do SKU para a política, atualiza esse preço (valores e vigência)
            em vez de criar outro, e ignora o bloqueio de preço duplicado por política. Ausente ou diferente de `1`:
            sempre cria um novo preço.
  /sku/pricing/{idsku}/{idstockkeepingunitpricing}:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
      - name: idstockkeepingunitpricing
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do preço.
    put:
      operationId: skuPricingPut
      tags:
        - Preços
      summary: Atualiza um preço do SKU
      description: Atualiza um preço cadastrado. Aplica as mesmas validações de política e preço-zero da criação.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuPricingCreateBody'
        description: >-
          Campos da faixa de preço a atualizar. Aceita `PriceList`, `PriceSell`, `DateFrom`, `DateTo` (datas precisam
          ser válidas), `IDCompanySalesPolicy` e `IDStockKeepingUnitPricing` (alternativa ao path).
      responses:
        '200':
          description: Preço atualizado. Retorna `skuPricingList` filtrado pelo SKU.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuPricing'
        '400':
          description: >-
            Prefixo `[BadRequest]`. Mensagens: `Data DE ou ATÉ inválida`, `Preço SKU não existe`, `Politica comercial
            não existe`, `Empresa não tem politica comercial padrão`, `Já existe um preço para essa política comercial e
            não pode ser criado outro (parametrização)`, `Não foi localizado preço da política comercial base`, `Não é
            permitido inserir preço de venda zerado. Validar configuração da empresa`.
        '500':
          description: Erro interno. Prefixo `Error:`.
    delete:
      operationId: skuPricingDelete
      tags:
        - Preços
      summary: Remove um preço do SKU
      description: Remove um preço. Notifica webhooks da empresa e devolve a lista atualizada.
      responses:
        '200':
          description: Preço removido. Retorna `skuPricingList` filtrado pelo SKU.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuPricing'
        '400':
          description: >-
            Prefixo `[BadRequest]`. Mensagens: `Precisa enviar os parametros corretos para excluir o preço`, `Preço Sku
            não existe`.
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/similarcategory/{idsku}:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
    get:
      operationId: skuSimilarCategoryGet
      tags:
        - Categorias Similares
      summary: Lista categorias similares do SKU
      description: >-
        Lista as categorias adicionais associadas ao SKU para fins de classificação cruzada (recomendação, navegação
        alternativa).
      responses:
        '200':
          description: Lista de categorias similares.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuSimilarCategory'
        '500':
          description: Erro interno. Prefixo `Error:`.
    post:
      operationId: skuSimilarCategoryPost
      tags:
        - Categorias Similares
      summary: Adiciona uma categoria similar ao SKU
      description: Vincula uma categoria adicional ao SKU.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - IDCategory
              properties:
                IDCategory:
                  type: integer
                  description: Identificador da categoria a vincular.
        description: >-
          Corpo do `POST /sku/similarcategory/{idsku}`: associa uma categoria de produtos similares ao SKU. Campo
          obrigatório: `IDCategory` (categoria — precisa existir na empresa).
      responses:
        '200':
          description: Categoria adicionada. Retorna a lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuSimilarCategory'
        '400':
          description: 'Prefixo `[BadRequest]`. Mensagens: `Sku não existe`, `IDCategory não existe`.'
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/similarcategory/{idsku}/{idstockkeepinunitsimilarcategory}:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
      - name: idstockkeepinunitsimilarcategory
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do vínculo SKU/categoria similar.
    delete:
      operationId: skuSimilarCategoryDelete
      tags:
        - Categorias Similares
      summary: Remove uma categoria similar do SKU
      description: Remove o vínculo entre o SKU e a categoria similar.
      responses:
        '200':
          description: Vínculo removido. Retorna a lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuSimilarCategory'
        '400':
          description: 'Prefixo `[BadRequest]`. Mensagem: `Sku não existe`.'
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/specification/{idsku}:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
    get:
      operationId: skuSpecificationGet
      tags:
        - Especificações de SKU
      summary: Lista as especificações técnicas aplicáveis ao SKU
      description: >-
        Retorna os campos de especificação configurados para a categoria do SKU (incluindo categorias-pai por herança),
        com o valor atual de cada um quando preenchido. Para campos de seleção, `FieldValue` traz a lista de valores
        escolhidos.
      responses:
        '200':
          description: Lista de campos de especificação.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuSpecificationField'
        '500':
          description: Erro interno. Prefixo `Error:`.
    post:
      operationId: skuSpecificationPost
      tags:
        - Especificações de SKU
      summary: Define as especificações técnicas do SKU
      description: >-
        Substitui completamente o conjunto de valores de especificação do SKU. Cada item do array referencia um campo
        cadastrado (`IDStockKeepingUnitSpecificationsFieldId`); o valor é literal para texto/número/data e um array de
        objetos com `IDStockKeepingUnitSpecificationsFieldValues` para campos de seleção.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                required:
                  - IDStockKeepingUnitSpecificationsFieldId
                properties:
                  IDStockKeepingUnitSpecificationsFieldId:
                    type: integer
                    description: Identificador do campo de especificação a vincular ao SKU.
                  FieldValue:
                    description: >-
                      Valor literal (string/number/date) ou array de objetos `{
                      IDStockKeepingUnitSpecificationsFieldValues }` para campos combo/radio.
        description: >-
          Lista das especificações do SKU (array que substitui as especificações atuais). Cada item traz
          `IDStockKeepingUnitSpecificationsFieldId` (campo de especificação) e `FieldValue` (valor texto, ou — quando o
          campo é checkbox/combo/radio — array de objetos com `IDStockKeepingUnitSpecificationsFieldValues`
          referenciando os valores cadastrados).
      responses:
        '200':
          description: Especificações gravadas. Retorna `skuSpecificationGet`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuSpecificationField'
        '404':
          description: >-
            Prefixo `[NotFound]`. Mensagens: `Sku não encontrado`, `Especificação ID <id> não encontrada`, `Valor
            especificação ID <id> não encontrada`.
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/tag:
    get:
      operationId: skuTagList
      tags:
        - Tags de SKU
      summary: Lista etiquetas livres usadas em SKUs
      description: Lista as etiquetas cadastradas em SKUs da empresa, ordenadas alfabeticamente. Filtro opcional por SKU.
      parameters:
        - name: IDSku
          in: query
          schema:
            type: integer
          description: Restringe as etiquetas a um SKU específico.
      responses:
        '200':
          description: Lista de etiquetas.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuTag'
        '400':
          description: Erro de configuração da empresa. Prefixo `[BadRequest]`.
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/template:
    get:
      operationId: skuFileTemplateExport
      tags:
        - Templates de Importação
      summary: Exporta planilha modelo para importação de SKUs
      description: Gera e devolve a planilha modelo (arquivo) usada para importar SKUs em lote.
      responses:
        '200':
          description: Planilha gerada. Resposta tipicamente como URL de download ou conteúdo binário.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '500':
          description: Erro interno.
    post:
      operationId: skuFileTemplateImport
      tags:
        - Templates de Importação
      summary: Importa planilha de SKUs (job assíncrono)
      description: >-
        Recebe uma planilha multipart e dispara o job de importação correspondente. O job é executado de forma
        assíncrona — a resposta confirma o agendamento. O tipo de planilha é definido pelo query `Type` (`sku`, `spec`,
        `carrier`, `correios`, `carrierIntelipost`).
      parameters:
        - name: Type
          in: query
          schema:
            type: string
            enum:
              - sku
              - spec
              - carrier
              - correios
              - carrierIntelipost
          description: Tipo de planilha a importar.
        - name: IDSupplier
          in: query
          schema:
            type: integer
          description: Obrigatório para `correios` e `carrierIntelipost`.
        - name: IDTypeJob
          in: query
          schema:
            type: integer
          description: Quando informado, usa um job personalizado registrado em `TypeJob`.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: Planilha (XLSX/CSV).
        description: >-
          Corpo do `POST /sku/template`: planilha/arquivo a processar de forma assíncrona, enviado como
          `multipart/form-data`. O tipo de importação (SKU, especificação, transportadora, Correios, Intelipost) é
          determinado pela query `Type`; alguns tipos (ex.: `correios`) não exigem arquivo e usam metadados da query.
      responses:
        '200':
          description: Job agendado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobScheduledResponse'
        '400':
          description: 'Prefixo `[BadRequest]`. Mensagens: `Ação não encontrada`, `Erro ao processar ação em massa`.'
        '404':
          description: 'Recurso/rota não localizada (`statusCode: 404`).'
        '500':
          description: Erro interno.
  /sku/variation:
    get:
      operationId: skuProductVariationList
      tags:
        - Variações (Grade)
      summary: Lista produtos-pai com suas variações
      description: >-
        Lista pares (produto-pai, SKU variação) com a grade aplicada. Pode filtrar por SKU, marca, fornecedor, código de
        barras e tipo. Exclui SKUs com status zero (excluídos lógicos).
      parameters:
        - name: IDSku
          in: query
          schema:
            type: integer
          description: Filtra pelo identificador do produto/SKU.
        - name: SkuName
          in: query
          schema:
            type: string
          description: Filtra pelo nome do produto (busca parcial).
        - name: BarCode
          in: query
          schema:
            type: string
          description: Filtra pelo código de barras do produto.
        - name: SkuType
          in: query
          schema:
            type: string
          description: Filtra pelo tipo de SKU.
        - name: Brand
          in: query
          schema:
            type: string
          description: Filtra pela marca (busca pelo nome).
        - name: SupplierCode
          in: query
          schema:
            type: string
          description: Filtra pelo código interno do fornecedor.
        - name: Supplier
          in: query
          schema:
            type: string
          description: Filtra pelo fornecedor (busca pelo nome).
        - name: IDSkuCompany
          in: query
          schema:
            type: string
          description: Filtra pelo identificador do vínculo SKU-empresa.
      responses:
        '200':
          description: Lista resumida de variações.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDProduct:
                      type: integer
                      description: Identificador do produto-pai a que a variação pertence.
                    IDSku:
                      type: integer
                      description: Identificador do SKU desta variação.
                    SkuName:
                      type: string
                      nullable: true
                      description: Nome do SKU (descrição da variação).
                    ProductVariation:
                      type: string
                      nullable: true
                      description: 'Nome do atributo de variação (ex.: `Cor`, `Tamanho`, `Sabor`).'
                    TypeProductVariationValue:
                      type: string
                      nullable: true
                      description: 'Valor do atributo de variação (ex.: `Azul`, `M`, `Morango`).'
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/variation/{idsku}:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do SKU produto-pai.
    get:
      operationId: skuProductVariationGet
      tags:
        - Variações (Grade)
      summary: Lista as variações de um produto-pai
      description: Retorna os SKUs variações filhos do produto-pai, com preço, saldo, status e a grade aplicada em cada um.
      parameters:
        - name: IDCompanySalesPolicy
          in: query
          schema:
            type: integer
          description: 'Política comercial usada para `PriceSell`/`PriceList`. Default: política padrão da empresa.'
        - name: IDStockKeepingUnitWarehouse
          in: query
          schema:
            type: integer
          description: Quando informado, retorna saldo apenas deste armazém.
      responses:
        '200':
          description: Lista de variações.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuProductVariation'
        '400':
          description: 'Política comercial inválida. Prefixo `[BadRequest]`. Mensagem: `Política comercial não existe`.'
        '500':
          description: Erro interno. Prefixo `Error:`.
    post:
      operationId: skuProductVariationPost
      tags:
        - Variações (Grade)
      summary: Vincula um SKU variação a um produto-pai
      description: >-
        Vincula um SKU filho a um produto-pai. Bloqueia quando o filho já está vinculado a outro produto, quando há
        outra variação com a mesma grade no produto-pai ou quando o `IDSku` é o próprio produto-pai.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - IDSku
              properties:
                IDSku:
                  type: integer
                  description: SKU filho a vincular como variação.
        description: >-
          Corpo do `POST /sku/variation/{idsku}`: associa um SKU filho a este produto pai. Campo obrigatório: `IDSku`
          (SKU filho, precisa ser diferente do produto, existir na empresa, não estar vinculado a outro produto e ter
          grade diferente dos demais filhos).
      responses:
        '200':
          description: Vínculo criado. Retorna `skuProductVariationGet`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuProductVariation'
        '400':
          description: >-
            Prefixo `[BadRequest]`. Mensagens: `Produto e SKU são iguais`, `Sku já existe em outro Produto`, `Produto já
            possui SKU com a mesma grade`, `Sku não existe`.
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/variation/{idsku}/{idstockkeepingunitproductvariation}:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do produto-pai.
      - name: idstockkeepingunitproductvariation
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do vínculo produto/variação.
    delete:
      operationId: skuProductVariationDelete
      tags:
        - Variações (Grade)
      summary: Remove um SKU variação do produto-pai
      description: Desvincula o SKU variação do produto-pai.
      responses:
        '200':
          description: Vínculo removido. Retorna `skuProductVariationGet`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuProductVariation'
        '400':
          description: 'Prefixo `[BadRequest]`. Mensagem: `Product Variation não existe`.'
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/{idsku}/barcode:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
    post:
      operationId: barCodePost
      tags:
        - Códigos de Barras
      summary: Adiciona um código de barras adicional ao SKU
      description: >-
        Cadastra um código de barras adicional (além do principal). Bloqueia se o código já existe como principal,
        adicional ou de embalagem em qualquer SKU da empresa.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - BarCode
              properties:
                BarCode:
                  type: string
                  maxLength: 20
                  description: Código de barras adicional.
        description: >-
          Corpo do `POST /sku/{idsku}/barcode`: cadastra um código de barras alternativo para o SKU. Campo obrigatório:
          `BarCode` (precisa ser único na empresa — não pode existir em outro SKU, embalagem ou código alternativo).
      responses:
        '200':
          description: Código cadastrado. Retorna o detalhe do SKU.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuDetail'
        '400':
          description: >-
            Prefixo `[BadRequest]`. Mensagens: `Sku não existe`, `Código de Barras precisa ser preenchido`, `Código de
            barras embalagem precisa ser preenchido`, `Código de Barras já existe no sku: <ref>`, `Código de barras já
            existe no sku: <ref>`.
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/{idsku}/barcode/{idstockkeepingunitbarcode}:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
      - name: idstockkeepingunitbarcode
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do código de barras adicional.
    delete:
      operationId: barCodeDelete
      tags:
        - Códigos de Barras
      summary: Remove um código de barras adicional do SKU
      description: Remove o código de barras adicional. Notifica webhooks da empresa.
      responses:
        '200':
          description: Código removido. Retorna o detalhe do SKU.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuDetail'
        '400':
          description: 'Prefixo `[BadRequest]`. Mensagem: `Código de barras não existe`.'
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/{idsku}/barcodepackage:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
    post:
      operationId: barCodePackagePost
      tags:
        - Códigos de Barras (Embalagem)
      summary: Adiciona um código de barras de embalagem ao SKU
      description: >-
        Cadastra um código de barras de embalagem (caixa, fardo, master) para o SKU, com o fator de conversão para
        unidades. Valida unicidade contra os demais códigos da empresa.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - BarCodePackage
              properties:
                BarCodePackage:
                  type: string
                  maxLength: 20
                  description: Código de barras da embalagem.
                PackageFactor:
                  type: integer
                  description: Quantidade de unidades por embalagem. Default `1`.
        description: >-
          Dados do código de barras de embalagem a cadastrar para o SKU. Obrigatório: `BarCodePackage` (precisa ser
          único na empresa). Opcional: `PackageFactor` (quantidade de unidades por embalagem; padrão 1).
      responses:
        '200':
          description: Código cadastrado. Retorna o detalhe do SKU.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuDetail'
        '400':
          description: >-
            Prefixo `[BadRequest]`. Mensagens: `Sku não existe`, `Código de barras embalagem precisa ser preenchido`,
            `Código de barras já existe no sku: <ref>`, `Código de Barras já existe no sku: <ref>`.
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/{idsku}/barcodepackage/{idstockkeepingunitbarcodepackage}:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
      - name: idstockkeepingunitbarcodepackage
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do código de barras de embalagem.
    put:
      operationId: barCodePackagePut
      tags:
        - Códigos de Barras (Embalagem)
      summary: Atualiza um código de barras de embalagem
      description: Atualiza o código de embalagem ou o fator. Reaplica as validações de unicidade.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                BarCodePackage:
                  type: string
                  maxLength: 20
                  description: Código de barras da embalagem do SKU.
                PackageFactor:
                  type: integer
                  description: Default `1`.
        description: >-
          Campos do código de barras de embalagem a atualizar. Aceita `BarCodePackage` (precisa permanecer único na
          empresa) e `PackageFactor` (padrão 1 quando vazio).
      responses:
        '200':
          description: Código atualizado. Retorna o detalhe do SKU.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuDetail'
        '400':
          description: >-
            Prefixo `[BadRequest]`. Mensagens: `Código de Barras Embalagem não existe`, `Código de Barras embalagem
            precisa ser preenchido`, `Código de Barras Embalagem já existe`, `Código de barras já existe no sku: <ref>`,
            `Código de Barras já existe no sku: <ref>`.
        '500':
          description: Erro interno. Prefixo `Error:`.
    delete:
      operationId: barCodePackageDelete
      tags:
        - Códigos de Barras (Embalagem)
      summary: Remove um código de barras de embalagem
      description: Remove o código de barras de embalagem.
      responses:
        '200':
          description: Código removido. Retorna o detalhe do SKU.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuDetail'
        '400':
          description: 'Prefixo `[BadRequest]`. Mensagem: `Código de Barras Embalagem não existe`.'
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/{idsku}/collection:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
    get:
      operationId: skuCollectionAssociationGet
      tags:
        - Coleções
      summary: Lista coleções associadas ao SKU
      description: Lista as coleções a que o SKU está vinculado.
      responses:
        '200':
          description: Lista de associações.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuCollectionAssociation'
        '500':
          description: Erro interno. Prefixo `Error:`.
    post:
      operationId: skuCollectionAssociationPost
      tags:
        - Coleções
      summary: Associa o SKU a uma coleção
      description: Vincula o SKU à coleção informada. Cada par SKU/coleção é único.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - IDStockKeepingUnitCollection
              properties:
                IDStockKeepingUnitCollection:
                  type: integer
                  description: Identificador da coleção.
        description: >-
          Corpo do `POST /sku/{idsku}/collection`: associa uma coleção ao SKU. Campo obrigatório:
          `IDStockKeepingUnitCollection` (coleção — precisa existir na empresa e ainda não estar associada ao SKU).
      responses:
        '200':
          description: Associação criada. Retorna a lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuCollectionAssociation'
        '400':
          description: 'Prefixo `[BadRequest]`. Mensagens: `Sku não existe`, `Sku já possui essa coleção`, `Coleção não existe`.'
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/{idsku}/collection/{idstockkeepingunitcollectionassociation}:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
      - name: idstockkeepingunitcollectionassociation
        in: path
        required: true
        schema:
          type: integer
        description: Identificador da associação SKU/coleção.
    put:
      operationId: skuCollectionAssociationPut
      tags:
        - Coleções
      summary: Troca a coleção de uma associação existente
      description: Atualiza a coleção associada a um vínculo já existente.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - IDStockKeepingUnitCollection
              properties:
                IDStockKeepingUnitCollection:
                  type: integer
                  description: Identificador da coleção à qual o SKU será associado.
        description: >-
          Corpo do `PUT /sku/{idsku}/collection/{idstockkeepingunitcollectionassociation}`: troca a coleção da
          associação. Campo obrigatório: `IDStockKeepingUnitCollection` (nova coleção — precisa existir na empresa e não
          estar duplicada para o SKU).
      responses:
        '200':
          description: Associação atualizada. Retorna a lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuCollectionAssociation'
        '400':
          description: >-
            Prefixo `[BadRequest]`. Mensagens: `Coleção Sku não existe`, `Sku já possui essa coleção`, `Coleção não
            existe`.
        '500':
          description: Erro interno. Prefixo `Error:`.
    delete:
      operationId: skuCollectionAssociationDelete
      tags:
        - Coleções
      summary: Remove a associação SKU/coleção
      description: Desvincula o SKU da coleção.
      responses:
        '200':
          description: Associação removida.
          content:
            application/json:
              schema:
                type: string
                example: sucesso
        '400':
          description: 'Prefixo `[BadRequest]`. Mensagem: `Coleção Sku não existe`.'
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/{idsku}/group:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
    get:
      operationId: skuGroupAssociationGet
      tags:
        - Grupos de SKU
      summary: Lista grupos associados ao SKU
      description: Lista os grupos de SKU a que o SKU pertence, com os códigos similares cadastrados em cada grupo.
      responses:
        '200':
          description: Lista de associações.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuGroupAssociation'
        '500':
          description: Erro interno. Prefixo `Error:`.
    post:
      operationId: skuGroupAssociationPost
      tags:
        - Grupos de SKU
      summary: Associa o SKU a um grupo
      description: Vincula o SKU ao grupo informado. Cada par SKU/grupo é único.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - IDStockKeepingUnitGroup
              properties:
                IDStockKeepingUnitGroup:
                  type: integer
                  description: Identificador do grupo ao qual o SKU será associado.
        description: >-
          Corpo do `POST /sku/{idsku}/group`: associa um grupo de SKUs ao SKU. Campo obrigatório:
          `IDStockKeepingUnitGroup` (grupo — precisa existir na empresa e ainda não estar associado ao SKU).
      responses:
        '200':
          description: Associação criada. Retorna a lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuGroupAssociation'
        '400':
          description: 'Prefixo `[BadRequest]`. Mensagens: `Sku não existe`, `Sku já possui esse grupo`, `Grupo Sku não existe`.'
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/{idsku}/group/{idstockkeepingunitgroupassociation}:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
      - name: idstockkeepingunitgroupassociation
        in: path
        required: true
        schema:
          type: integer
        description: Identificador da associação SKU/grupo.
    put:
      operationId: skuGroupAssociationPut
      tags:
        - Grupos de SKU
      summary: Troca o grupo de uma associação existente
      description: Atualiza o grupo associado a um vínculo já existente.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - IDStockKeepingUnitGroup
              properties:
                IDStockKeepingUnitGroup:
                  type: integer
                  description: Novo identificador do grupo ao qual o SKU será associado.
        description: >-
          Corpo do `PUT /sku/{idsku}/group/{idstockkeepingunitgroupassociation}`: troca o grupo da associação. Campo
          obrigatório: `IDStockKeepingUnitGroup` (novo grupo — precisa existir na empresa e não estar duplicado para o
          SKU).
      responses:
        '200':
          description: Associação atualizada. Retorna a lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuGroupAssociation'
        '400':
          description: 'Prefixo `[BadRequest]`. Mensagens: `Grupo Sku não existe`, `Sku já possui esse grupo`.'
        '500':
          description: Erro interno. Prefixo `Error:`.
    delete:
      operationId: skuGroupAssociationDelete
      tags:
        - Grupos de SKU
      summary: Remove a associação SKU/grupo
      description: Desvincula o SKU do grupo.
      responses:
        '200':
          description: Associação removida.
          content:
            application/json:
              schema:
                type: string
                example: sucesso
        '400':
          description: 'Prefixo `[BadRequest]`. Mensagem: `Grupo Sku não existe`.'
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/{idsku}/label:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
    get:
      operationId: skuLabelGet
      tags:
        - SKU — Etiqueta
      summary: Gera etiqueta de SKU para impressão
      description: Gera a etiqueta ZPL/PDF do SKU usando o modelo de etiqueta da empresa.
      responses:
        '200':
          description: Etiqueta gerada. Tipicamente retorna a etiqueta como ZPL/PDF ou URL para download.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                description: Confirmação do job agendado.
        '500':
          description: Erro interno.
  /sku/{idsku}/serial:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
    get:
      operationId: skuSerialGet
      tags:
        - Números de Série
      summary: Lista números de série do SKU
      description: >-
        Lista os números de série cadastrados para o SKU. Filtros opcionais permitem isolar livres, vinculados a uma
        entrada ou a uma saída.
      parameters:
        - name: Free
          in: query
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` retorna apenas seriais não consumidos por venda (sem `IDSkuMovementOutbound`).'
        - name: IDSkuMovementInbound
          in: query
          schema:
            type: integer
          description: Restringe seriais a uma entrada específica.
        - name: IDSkuMovementOutbound
          in: query
          schema:
            type: integer
          description: Restringe seriais a uma saída específica.
        - name: IDTypeStatusSkuSerialNumber
          in: query
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 3
          description: Filtra por status do serial.
      responses:
        '200':
          description: Lista de seriais.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuSerial'
        '400':
          description: Erro de configuração da empresa. Prefixo `[BadRequest]`.
        '500':
          description: Erro interno. Prefixo `Error:`.
    post:
      operationId: skuSerialPost
      tags:
        - Números de Série
      summary: Cadastra números de série
      description: >-
        Insere uma lista de números de série para o SKU. Quando `IDSkuMovementInbound` é informado, os seriais ficam
        vinculados a essa entrada (status `2` recebido); caso contrário, ficam livres (status `1`). Bloqueia se algum
        serial já existe para o SKU.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - SerialNumber
              properties:
                SerialNumber:
                  type: array
                  items:
                    type: string
                    maxLength: 45
                  description: Lista de seriais a cadastrar.
                IDSkuMovementInbound:
                  type: integer
                  nullable: true
                  description: Entrada associada (recebimento).
        description: >-
          Dados dos números de série a cadastrar para o SKU. Obrigatório: `SerialNumber` (array dos seriais — não podem
          existir para o mesmo SKU). Opcional: `IDSkuMovementInbound` (movimentação de entrada — quando informada,
          valida que existe, remove os seriais já vinculados a ela e marca os novos como `IDTypeStatusSkuSerialNumber =
          2`; sem ela usa o status 1).
      responses:
        '200':
          description: Seriais inseridos. Retorna `skuSerialGet` filtrado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuSerial'
        '400':
          description: >-
            Prefixo `[BadRequest]`. Mensagens: `Sku não existe`, `Serial precisa ser preenchido`, `Serial <numero> já
            existe`, `Movimentação entrada não localizada`.
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/{idsku}/serial/{idstockkeepingunitserialnumber}:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
      - name: idstockkeepingunitserialnumber
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do serial.
    put:
      operationId: skuSerialPut
      tags:
        - Números de Série
      summary: Atualiza o número de série
      description: Altera o conteúdo do número de série. Bloqueia quando o serial já saiu em uma venda.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - SerialNumber
              properties:
                SerialNumber:
                  type: string
                  maxLength: 45
                  description: Número de série do SKU.
        description: >-
          Corpo do `PUT /sku/{idsku}/serial/{idstockkeepingunitserialnumber}`: atualiza o número de série. Campo
          obrigatório: `SerialNumber` (novo serial; não é permitido alterar um serial já enviado em venda).
      responses:
        '200':
          description: Serial atualizado.
          content:
            application/json:
              schema:
                type: string
                example: sucesso
        '400':
          description: >-
            Prefixo `[BadRequest]`. Mensagens: `Serial não existe`, `Serial já foi enviado em uma venda e não pode ser
            deletado`.
        '500':
          description: Erro interno. Prefixo `Error:`.
    delete:
      operationId: skuSerialDelete
      tags:
        - Números de Série
      summary: Remove um número de série
      description: Remove o serial. Bloqueia quando o serial já saiu em uma venda.
      responses:
        '200':
          description: Serial removido.
          content:
            application/json:
              schema:
                type: string
                example: sucesso
        '400':
          description: >-
            Prefixo `[BadRequest]`. Mensagens: `Serial não existe`, `Serial já foi enviado em uma venda e não pode ser
            deletado`.
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/{idsku}/variation:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
    get:
      operationId: skuVariationGet
      tags:
        - Variações (Grade)
      summary: Lista os valores de variação do SKU
      description: 'Lista os pares (tipo de variação, valor) cadastrados para o SKU. Ex.: `Cor: Azul`, `Tamanho: M`.'
      responses:
        '200':
          description: Lista de valores de variação.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuVariationValue'
        '500':
          description: Erro interno. Prefixo `Error:`.
    post:
      operationId: skuVariationPost
      tags:
        - Variações (Grade)
      summary: Adiciona um valor de variação ao SKU
      description: 'Vincula um valor de variação (ex.: `Cor: Azul`) ao SKU. Cada tipo de variação só pode aparecer uma vez por SKU.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - IDTypeProductVariation
                - IDTypeProductVariationValue
              properties:
                IDTypeProductVariation:
                  type: integer
                  description: 'Tipo de variação (ex.: cor, tamanho).'
                IDTypeProductVariationValue:
                  type: integer
                  description: 'Valor da variação (ex.: azul, M).'
        description: >-
          Dados da variação (grade) a associar ao SKU. Obrigatórios: `IDTypeProductVariation` (tipo de variação — ex.:
          cor, tamanho — único por SKU) e `IDTypeProductVariationValue` (valor da variação).
      responses:
        '200':
          description: Valor de variação cadastrado. Retorna `skuVariationGet`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuVariationValue'
        '400':
          description: 'Prefixo `[BadRequest]`. Mensagens: `Sku não existe`, `Sku já tem esse tipo de variação`.'
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/{idsku}/variation/{idstockkeepingunitvariation}:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
      - name: idstockkeepingunitvariation
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do valor de variação.
    delete:
      operationId: skuVariationDelete
      tags:
        - Variações (Grade)
      summary: Remove um valor de variação do SKU
      description: Remove o vínculo entre o SKU e o valor de variação. Notifica webhooks da empresa.
      responses:
        '200':
          description: Valor removido. Retorna `skuVariationGet`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuVariationValue'
        '400':
          description: 'Prefixo `[BadRequest]`. Mensagem: `Variação não existe`.'
        '500':
          description: Erro interno. Prefixo `Error:`.
  /sku/{idsku}/warehouse:
    parameters:
      - name: idsku
        in: path
        required: true
        schema:
          type: integer
    get:
      operationId: skuWarehouseIDSkuGet
      tags:
        - Armazéns
      summary: Lista saldos do SKU por armazém
      description: >-
        Lista o saldo do SKU em cada armazém ativo, com detalhamento de pedidos reservados, em separação, em produção,
        em recebimento, em pedido de compra e em ressuprimento. Respeita os centros de distribuição autorizados para o
        usuário e o ajuste de margem de segurança do tipo de pedido informado.
      parameters:
        - name: IDTypeOrder
          in: query
          schema:
            type: integer
          description: Quando informado, aplica a margem `SafetyStockPercent` do tipo de pedido sobre as quantidades retornadas.
        - name: IDStockKeepingUnitDistributionCenter
          in: query
          schema:
            type: string
          description: Lista de centros de distribuição separados por vírgula. Restringe os armazéns retornados.
      responses:
        '200':
          description: Lista de armazéns com saldo do SKU.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuWarehouseBalance'
        '400':
          description: Erro de validação dos parâmetros enviados.
        '500':
          description: Erro interno. Prefixo `Error:`.
  /orders/{idorder}:
    parameters:
      - name: idorder
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do pedido.
    get:
      operationId: OrderGet
      tags:
        - Pedidos
      summary: Detalhe completo do pedido
      description: >-
        Retorna o pedido com itens, parcelas, pacotes, histórico, arquivos da nota fiscal e totalizadores. Use
        `?Economics=1` para receber, em vez disso, os indicadores econômicos (receitas, custos e margem) e
        `?ItemsInvoice=1` para receber apenas a lista de itens enriquecida com classificações tributárias para emissão
        fiscal. Quando a parametrização `Mostrar apenas nome do produto` está ligada, o nome do produto retornado nos
        itens não traz o prefixo da variação.
      parameters:
        - name: Economics
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Quando `1`, retorna `OrderEconomics` em vez de `OrderDetail`.
        - name: ItemsInvoice
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Quando `1`, retorna a lista de itens enriquecida com CFOP e CSTs (`OrderItemFiscal`).
      responses:
        '200':
          description: Detalhe do pedido. O shape varia conforme as flags `Economics` e `ItemsInvoice`.
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/OrderDetail'
                    description: >-
                      Default (sem flags) — array com um único `OrderDetail`. Array vazio quando o pedido não existe na
                      empresa.
                  - type: array
                    items:
                      $ref: '#/components/schemas/OrderEconomics'
                    description: Com `Economics=1`.
                  - type: array
                    items:
                      $ref: '#/components/schemas/OrderItemFiscal'
                    description: Com `ItemsInvoice=1`.
        '400':
          description: 'Pedido inexistente ou identificador inválido. Mensagem possível: `[BadRequest] - não localizado`.'
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro interno. Resposta com prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
    put:
      operationId: OrderPut
      tags:
        - Pedidos
      summary: Atualiza o pedido
      description: >-
        Alem da atualizacao do pedido, aceita o modo de reenvio de notificacao: com Resend=1 (e TypeMessage), o endpoint
        apenas reenvia a mensagem do pedido do tipo indicado e devolve a resposta desse envio, sem alterar o pedido.
      parameters:
        - name: ValueAdjust
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Quando `1`, ativa o fluxo de ajuste de valor (desconto/acréscimo rateado).
        - name: Resend
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: >-
            Quando 1, o endpoint entra no modo de reenvio de notificacao do pedido: nao atualiza o pedido, apenas
            reenvia a mensagem do tipo TypeMessage e retorna a resposta do envio. Exige TypeMessage.
        - name: TypeMessage
          in: query
          required: false
          schema:
            type: string
          description: >-
            Tipo da mensagem/notificacao a reenviar. Obrigatorio quando Resend=1; ausente retorna 400 com [BadRequest] -
            Precisa informar o parametro TypeMessage.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderUpdateBody'
        description: >-
          Atualização parcial do pedido. Apenas campos enviados são alterados. Quando o query param `ValueAdjust=1` está
          presente, o body é interpretado como ajuste de valor
          (`ValueAddOrDiscount`/`PercentAddOrDiscount`/`IncludeShipping`) — os demais campos são ignorados nesse modo.
      responses:
        '200':
          description: >-
            Pedido atualizado. Geralmente retorna o `OrderDetail` recalculado (igual a `OrderGet`). Em alguns sub-fluxos
            (troca de armazém) retorna a string `"sucesso"`.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/OrderDetail'
                  - type: array
                    items:
                      $ref: '#/components/schemas/OrderDetail'
                  - type: string
                    example: sucesso
        '400':
          description: >-
            Erros de validação (`[BadRequest]`): `Fator nota fiscal precisa ser entre 1 e zero`, `Prioridade pedido
            precisa ser entre 0 e 10`, `O status atual não permite atualização`, `Precisa enviar o valor ou percentual
            do desconto`, `Armazém pertence a um centro de distribuição diferente do pedido`, `Pedido já foi enviado e
            não pode ter o armazém alterado`, `Armazém não existe`, `Tipo pedido não existe`, `Integração não existe`,
            `Cliente não existe`, `Endereço não existe`, `Endereço entrega não existe`, `Vendedor não existe`,
            `Faturador não existe`, `Remova o pedido/pacotes do romaneio antes de alterar transportadora`,
            `Transportadora não existe`, `Romaneio percente a centro de distribuição diferente do pedido`, `Status
            romaneio não permite inclusão/remoção de novos pedidos`, `Romaneio não existe`, `Status Picking List não
            permite inclusão de novos pedidos`, `Picking List não existe`, `Centro de distribuição não existe`, `Empresa
            não tem centro de distribuição padrão`, `Pedido esta em mais de um centro de distribuição. Remover os itens
            de armazéns divergentes`, `Novo centro de distribuição diverge dos armazém dos itens já inseridos no
            pedido`, `Pedido não existe`, `Precisa informar o parametro TypeMessage`.
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro interno. Resposta com prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
    delete:
      operationId: OrderDelete
      tags:
        - Pedidos
      summary: Exclui o pedido (status 100)
      description: >-
        Marca o pedido como excluído (status `100`), zera o frete e limpa picking/romaneio. Antes da exclusão, remove as
        movimentações de estoque, contas a receber, pacotes, origens, referências de NF, tags, nota fiscal vinculada (se
        houver) e o rastreamento da transportadora. Registra um evento de exclusão.


        Bloqueado quando a nota fiscal associada está em status que impede mudança (enviada, emitida, processando,
        pendente conciliação EPEC, cancelada ou denegada — nesse caso desvincule a nota primeiro), quando o pedido está
        em romaneio ou em picking list (retire antes), ou quando o status atual não permite transição para `100`.


        Após excluir, retorna o `OrderDetail` atualizado (via invocação interna do `OrderGet`). Envie `?NoInvoke=1` para
        receber apenas a string `"sucesso"`.
      parameters:
        - name: NoInvoke
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Quando `1`, evita o reload do pedido e retorna apenas a string `"sucesso"`.
      responses:
        '200':
          description: Pedido excluído.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/OrderDetail'
                  - type: string
                    example: sucesso
        '400':
          description: >-
            Erros possíveis (`[BadRequest]`): `Desvincular nota fiscal antes de alterar status`, `Pedido esta em
            romaneio <id>, retirar antes de mudar status`, `Pedido esta na Picking List <id>, retirar antes de mudar
            status`, `Status não permite atualização`, `Order não existe`.
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro interno. Resposta com prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
  /orders/{idorder}/sku:
    parameters:
      - name: idorder
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do pedido.
    post:
      operationId: orderSkuPost
      tags:
        - Pedidos
      summary: Adiciona um item ao pedido
      description: >-
        Inclui um produto no pedido. A criação propriamente dita (movimentação de estoque, cálculo de tributos com base
        no produto, política e UF) é delegada a um processo fiscal interno — o sistema valida regras de negócio antes
        (coerência de sinal de quantidade com itens existentes, bloqueio de produto com valor zero conforme o tipo de
        pedido e a parametrização `Permitir gratificação de produtos com valor zero`) e em seguida monta a linha
        consolidada do item para retorno, incluindo cálculo de comissão quando o pedido tem vendedor com regra vigente.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderSkuPostBody'
        description: >-
          Item a adicionar ao pedido. `IDSku` e `Quantity` são obrigatórios; demais campos passam pelo motor fiscal a
          partir do produto e da política de vendas.
      responses:
        '200':
          description: >-
            Item adicionado. Retorna um array com o item criado. Quando o processo fiscal devolve resposta vazia,
            retorna a string `"ok"`.
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/OrderSkuMovement'
                  - type: string
                    example: ok
        '400':
          description: >-
            Erros possíveis (`[BadRequest]`): `Pedido não encontrado`, `Pedido tem itens com quantidade negativa e item
            com quantidade positiva não pode ser adicionado`, `Pedido tem itens com quantidade positiva e item com
            quantidade negativa não pode ser adicionado`, `Não é permitido adicionar produtos com valor zero ao pedido
            (configuração no tipo de pedido)`, `Erro ao adicionar item em pedido`. Mensagens retornadas pelo processo
            fiscal (ex.: validações de estoque, preço, CFOP) também aparecem aqui com seu texto original.
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro interno. Resposta com prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
  /orders/{idorder}/sku/{idskumovement}:
    parameters:
      - name: idorder
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do pedido.
      - name: idskumovement
        in: path
        required: true
        schema:
          type: integer
        description: Identificador da movimentação do item no pedido.
    put:
      operationId: orderSkuPut
      tags:
        - Pedidos
      summary: Atualiza um item do pedido
      description: >-
        Atualiza quantidade, preço, armazém, classificação fiscal ou descontos de um item já existente. Quando
        quantidade/preço mudam, o motor fiscal recalcula tributos do item e atualiza os totais da nota; quando o armazém
        muda, valida que o novo armazém pertence ao mesmo centro de distribuição do pedido. Descontos acima do limite
        configurado para o vendedor são recusados — a mensagem traz o percentual aplicado e o limite. Em status finais
        (cancelado/excluído) e em estados intermediários incompatíveis a atualização é bloqueada. Após o sucesso,
        retorna o `OrderDetail` recalculado.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderSkuPutBody'
        description: >-
          Campos do item do pedido a atualizar — apenas os enviados são aplicados. Inclui dados comerciais (`IDSku`,
          `Quantity`, `PriceList`, `PriceSelling`, `PriceSellingTotal`, `ValueDiscount`, `ValueShipping`,
          `Gratification`, `IDStockKeepingUnitWarehouse`, `QuantityNonconformity`, `IDTypeFulfillmentNonconformity`,
          `Comments`, `NfeNItemPed`) e os campos fiscais da NF-e do item (CFOP, ICMS/PIS/COFINS/IPI/II/ISS, FCP,
          ICMS-ST, importação, combustível e demais grupos de tributos).
      responses:
        '200':
          description: Item atualizado. Retorna o `OrderDetail` recalculado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDetail'
        '400':
          description: >-
            Erros possíveis (`[BadRequest]`): `Pedido não existe`, `Sku não existe`, `Armazem não existe`, `Centro de
            distribuição do item é diferente do CD do pedido`, `O status atual não permite atualizar`, `Pedido tem itens
            com quantidade negativa e item com quantidade positiva não pode ser adicionado`, `Pedido tem itens com
            quantidade positiva e item com quantidade negativa não pode ser adicionado`, `Desconto aplicado maior que o
            permitido. Aplicado: <X>% e desconto limite: <Y>%`.
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro interno. Resposta com prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
    delete:
      operationId: orderSkuDelete
      tags:
        - Pedidos
      summary: Remove um item do pedido
      description: >-
        Exclui a movimentação do item, registra um evento no histórico do pedido e, quando havia outras movimentações
        posteriores do mesmo produto/armazém com marcação para reprocessar saldo, enfileira recálculo de custo médio
        (fila assíncrona `skuCostRecalculate`). Operação bloqueada quando o status do pedido não permite ajustes
        (somente status iniciais ou os ligados a atendimento — `50` a `56`, `70` a `74` — aceitam exclusão de item).
        Após remover, retorna o `OrderDetail` atualizado.
      responses:
        '200':
          description: Item removido. Retorna o `OrderDetail` recalculado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDetail'
        '400':
          description: 'Erros possíveis (`[BadRequest]`): `Pedido não existe`, `O status atual não permite atualização`.'
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro interno. Resposta com prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
  /orders/{idorder}/payment:
    parameters:
      - name: idorder
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do pedido.
    post:
      operationId: orderPaymentPost
      tags:
        - Pedidos
      summary: Lança um pagamento (conta a receber) no pedido
      description: >-
        Cria parcela(s) de recebimento para o pedido. A criação efetiva — incluindo geração de boleto/link de pagamento
        junto ao gateway quando o tipo de pagamento exige, e rateio de parcelas quando `SplitInstallment` é maior que 1
        — é executada por um processo financeiro interno. Após o sucesso, retorna o `OrderDetail` recalculado.
      parameters:
        - name: SplitInstallment
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Quando maior que 1, divide o valor enviado nesse número de parcelas (vencimentos consecutivos).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/OrderPaymentPostBody'
                - type: array
                  items:
                    $ref: '#/components/schemas/OrderPaymentPostBody'
        description: >-
          Pagamento ou lista de pagamentos a lançar no pedido. Cada item gera um título financeiro
          (`AccountsPayableReceivable`) e dispara a aplicação adequada (parcelamento, boleto, link de pagamento).
      responses:
        '200':
          description: Pagamento lançado. Retorna o `OrderDetail` recalculado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDetail'
        '400':
          description: >-
            Erros possíveis (`[BadRequest]`): mensagens do processo financeiro (validações de tipo de pagamento, banco,
            integração, etc.).
          content:
            application/json:
              schema:
                type: string
        '404':
          description: 'Pedido não encontrado (prefixo `[NotFound]`): `[NotFound] - Pedido não encontrado`.'
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro interno. Resposta com prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
  /orders/{idorder}/payment/{idaccountpayablereceivable}:
    parameters:
      - name: idorder
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do pedido.
      - name: idaccountpayablereceivable
        in: path
        required: true
        schema:
          type: integer
        description: Identificador da conta a receber (parcela) do pedido.
    put:
      operationId: orderPaymentPut
      tags:
        - Pedidos
      summary: Atualiza uma parcela do pedido
      description: >-
        Atualiza os dados de uma conta a receber lançada no pedido (valor, vencimento, tipo de pagamento, plano de
        contas, cliente/fornecedor, integração, descontos, juros e multas). Quando o título tem boleto/link de pagamento
        em aberto, a alteração de `Value`/`DateDue` dispara reemissão junto ao gateway; com boleto/link já pago, a
        alteração é bloqueada. Após o sucesso, retorna o `OrderDetail` recalculado.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountsPayableReceivableUpdateBody'
        description: >-
          Atualização parcial de um título financeiro do pedido. `IDConsumer` e `IDSupplier` são mutuamente exclusivos.
          Quando `Value`/`DateDue` mudam e o título já tem boleto/link emitido, o gateway é acionado para reemissão
          (boletos pagos são bloqueados).
      responses:
        '200':
          description: Título atualizado. Retorna o `OrderDetail` recalculado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDetail'
        '400':
          description: >-
            Erros possíveis (`[BadRequest]`): `Fornecedor ou cliente precisa ser preenchido (apenas um dos dois)`,
            `Fornecedor não existe`, `Cliente não existe`, `Faturador não existe`, `Pagamento não existe`, `Banco não
            existe`, `Integração não existe`, `Boleto / link pagamento já esta pago e não pode ser alterado`, `Plano de
            contas não existe`, `Tipo documento não existe`, `Conta a receber não existe`.
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro interno. Resposta com prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
    delete:
      operationId: orderPaymentDelete
      tags:
        - Pedidos
      summary: Exclui uma parcela do pedido
      description: >-
        Remove a conta a receber vinculada ao pedido. Bloqueada quando o título já está agendado, quando tem pagamento
        conciliado, ou — para contas a pagar de recebimento — quando a parametrização `Bloquear exclusão de contas a
        pagar atreladas a recebimento` está ativa. Quando havia GNRE vinculada, o link é desfeito. Registra um evento de
        exclusão no histórico do pedido e retorna o `OrderDetail` recalculado.
      parameters:
        - name: ChangeNextRepeat
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: >-
            Aplicável apenas a títulos avulsos (sem pedido). Quando `1`, apaga também as próximas ocorrências da série
            de repetição (vencimentos futuros).
      responses:
        '200':
          description: Título excluído. Retorna o `OrderDetail` recalculado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDetail'
        '400':
          description: >-
            Erros possíveis (`[BadRequest]`): `Pagamento não existe`, `Título esta agendado e não pode ser excluído`,
            `Não é possível excluir um contas a pagar atrelado a um recebimento`, `Contas a pagar já tem pagamento`.
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro interno. Resposta com prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
  /orders/{idorder}/packages:
    parameters:
      - name: idorder
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do pedido.
    post:
      operationId: orderPackagesPost
      tags:
        - Pedidos
      summary: Cria pacotes para o pedido
      description: >-
        Adiciona pacote(s) ao pedido. Quando `PackageQuantityTotal` é enviado, o sistema ajusta o total de pacotes do
        pedido para esse número (criando pacotes vazios numerados em sequência ou apagando os excedentes — pacotes com
        numeração mais alta primeiro). Quando `PackageQuantityTotal` é omitido, cria um único pacote com as dimensões
        informadas, no próximo `PackageNumber` disponível. Quando `IDSku` é enviado, adiciona uma movimentação do
        produto no pedido (quantidade 1, preço 0, armazém padrão da empresa) — usado para registrar embalagem/brinde.
        Bloqueado quando o pedido está em status `7` ou `8` (cancelado pelo cliente / cancelado). Retorna o
        `OrderDetail` recalculado.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderPackagePostBody'
        description: >-
          Cria um pacote único (informando dimensões) ou garante uma quantidade total de pacotes para o pedido via
          `PackageQuantityTotal`.
      responses:
        '200':
          description: Pacote(s) criado(s). Retorna o `OrderDetail` recalculado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDetail'
        '400':
          description: 'Erros possíveis (`[BadRequest]`): `Pedido não existe`, `O status atual não permite atualizar`.'
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro interno. Resposta com prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
  /orders/{idorder}/packages/{idpackage}:
    parameters:
      - name: idorder
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do pedido.
      - name: idpackage
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do pacote dentro do pedido.
    put:
      operationId: orderPackagesPut
      tags:
        - Pedidos
      summary: Atualiza um pacote do pedido
      description: >-
        Atualiza o código de rastreio do pacote e/ou o vínculo com romaneio. O pedido precisa ter transportadora
        definida; sem ela, a operação é recusada. O código de rastreio precisa ser único dentro da transportadora. Ao
        alterar o romaneio, o sistema valida que ele pertence à mesma transportadora e ao mesmo centro de distribuição
        do pedido, e que seu status permite alteração; pacotes já enviados (`IDStatusPackage=1`) não podem trocar de
        romaneio. Quando os valores enviados coincidem com os atuais, retorna a string `"sucesso"` sem reprocessar —
        caso contrário, retorna o `OrderDetail` recalculado.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderPackagePutBody'
        description: >-
          Campos do volume (pacote) do pedido a atualizar. Aceita `ShippingId` (código de rastreio — precisa ser único
          na transportadora) e `IDOrdersCarrierCollectionList` (romaneio — precisa ser da mesma transportadora e centro
          de distribuição do pedido, estar em status que permite alteração e o pacote ainda não pode ter sido enviado).
          Atribuir o pacote a um novo romaneio limpa o `ShippingPlp` anterior.
      responses:
        '200':
          description: Pacote atualizado.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/OrderDetail'
                  - type: string
                    example: sucesso
        '400':
          description: >-
            Erros possíveis (`[BadRequest]`): `Volume/Pedido não existe`, `Pedido não possui transportadora`, `Código
            Rastreio já existe`, `Pacote já enviado`, `Romaneio pertence a transportadora divergente do pedido`,
            `Romaneio pertece a outro centro de distribuição`, `Status do romaneio não permite alterar pacote`,
            `Romaneio não existe`.
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro interno. Resposta com prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
    delete:
      operationId: orderPackagesDelete
      tags:
        - Pedidos
      summary: Remove um pacote do pedido
      description: >-
        Remove o pacote e renumera os restantes em sequência. Por padrão, `idpackage` refere-se ao identificador interno
        do pacote. Use `?Type=ShippingId` para resolver por código de rastreio em vez do identificador. Bloqueado quando
        o pedido está em status que impede ajuste de pacotes (`6` separado, `7`/`8` cancelado, `17`/`19` finalizados).
        Retorna o `OrderDetail` recalculado.
      parameters:
        - name: Type
          in: query
          required: false
          schema:
            type: string
            enum:
              - ShippingId
          description: >-
            Quando `ShippingId`, o `idpackage` do path é tratado como código de rastreio (não como identificador do
            pacote).
      responses:
        '200':
          description: Pacote removido. Retorna o `OrderDetail` recalculado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDetail'
        '400':
          description: >-
            Erros possíveis (`[BadRequest]`): `Pedido não existe`, `O status atual não permite atualização`, `Volume não
            existe`.
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro interno. Resposta com prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
  /orders/{idorder}/file:
    parameters:
      - name: idorder
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do pedido.
    get:
      operationId: orderFileGet
      tags:
        - Pedidos
      summary: Lista arquivos customizados do pedido
      description: >-
        Retorna os arquivos customizados anexados ao pedido (assinatura digital de entrega, fotos de comprovante de
        entrega/devolução, etc.) com URLs pré-assinadas do S3 (validade de 2 dias) para download direto. Use
        `?IDTypeOrderFile` para filtrar por um tipo específico.
      parameters:
        - name: IDTypeOrderFile
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 3
          description: Filtra pelo tipo do arquivo customizado.
      responses:
        '200':
          description: Lista de arquivos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderCustomFile'
        '500':
          description: Erro interno. Resposta com prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
    post:
      operationId: orderFilePost
      tags:
        - Pedidos
      summary: Anexa um arquivo customizado ao pedido
      description: >-
        Cria um registro de arquivo customizado para o pedido (assinatura digital, fotos de comprovante) e envia os
        anexos para o S3. Quando `?ChangeStatus=1` (ou quando o tipo do arquivo é `1` e a query não foi enviada), o
        pedido é avançado para entregue/devolvido (status `7` ou `8`, conforme o tipo da transportadora), todos os
        pacotes do pedido são marcados como enviados, as movimentações de estoque viram saída consolidada e é registrado
        um evento no histórico. Caso o status final seja enviado via `IDStatusOrder`, esse valor é usado em vez do
        default. Retorna a lista atualizada de arquivos (mesmo formato de `orderFileGet`).
      parameters:
        - name: IDTypeOrderFile
          in: query
          required: false
          schema:
            type: integer
            default: 1
            enum:
              - 1
              - 2
              - 3
          description: Tipo do arquivo (default `1` — comprovante de entrega).
        - name: ChangeStatus
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: >-
            Quando `1`, avança o status do pedido e dos pacotes. Default `1` quando `IDTypeOrderFile=1`, `0` caso
            contrário.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderFilePostBody'
        description: >-
          Arquivos customizados a anexar ao pedido — pelo menos um entre `Signature`, `DocumentImage`, `DocumentImage2`
          ou `DocumentImage3` precisa vir preenchido (data URL base64).
      responses:
        '200':
          description: Arquivo(s) anexado(s). Retorna a lista atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderCustomFile'
        '400':
          description: >-
            Erros possíveis (`[BadRequest]`): `Pedido não existe`, `Não foi enviado um arquivo válido`. Também pode
            retornar `erro ao subir arquivo` (sem prefixo) quando o upload no S3 falha — o registro inserido é desfeito
            antes.
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro interno. Resposta com prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
  /orders/{idorder}/file/{idorderscustomfile}:
    parameters:
      - name: idorder
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do pedido.
      - name: idorderscustomfile
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do arquivo customizado.
    get:
      operationId: orderFileDownloadGet
      tags:
        - Pedidos
      summary: Baixa o conteúdo de um arquivo customizado
      description: >-
        Faz o download do arquivo anexado ao pedido. O `idorderscustomfile` é resolvido a partir do path; o nome real do
        arquivo dentro do registro (assinatura, primeiro anexo etc.) é informado em `?FileName`. Quando `?View=1`,
        devolve o conteúdo bruto para visualização inline; caso contrário, devolve com `Content-Disposition: attachment`
        para download.
      parameters:
        - name: FileName
          in: query
          required: true
          schema:
            type: string
          description: Nome do arquivo a baixar — precisa coincidir com `File1Name` ou `File2Name` do registro.
        - name: View
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Quando `1`, devolve o conteúdo bruto para visualização inline em vez de anexo.
      responses:
        '200':
          description: Conteúdo do arquivo (bytes).
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          description: 'Mensagens possíveis (prefixo `[NotFound]`): `Arquivo não encontrado`, `Arquivo não encontrado S3`.'
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro interno. Resposta com prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
    delete:
      operationId: orderFileDelete
      tags:
        - Pedidos
      summary: Remove um arquivo customizado do pedido
      description: >-
        Apaga o registro do arquivo customizado do pedido. Não remove os blobs do S3 (ficam como órfãos até limpeza
        periódica). Retorna a string `"sucesso"`.
      responses:
        '200':
          description: Operação concluída com sucesso.
          content:
            application/json:
              schema:
                type: string
                example: sucesso
        '404':
          description: 'Arquivo não encontrado. Mensagem (sem prefixo): `Arquivo Não encontrado`.'
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro interno. Resposta com prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
  /orders/{idorder}/invoice:
    parameters:
      - name: idorder
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do pedido.
    post:
      operationId: orderInvoicePost
      tags:
        - Pedidos
      summary: Emite a nota fiscal do pedido
      description: >-
        Aciona a emissão fiscal do pedido. O contrato do corpo é o XML/JSON aceito pelo processo fiscal interno — campos
        como cabeçalho, itens, totais, transporte e meios de pagamento — e a resposta repete o retorno do processo. Em
        sucesso, devolve os dados da nota emitida (chave de acesso, número, protocolo, status SEFAZ); em erro de SEFAZ,
        a resposta traz o `errorMessage` original retornado pelo emissor, sem prefixo.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              description: Payload aceito pelo processo fiscal (contrato definido fora deste sistema).
          application/xml:
            schema:
              type: string
              description: Payload XML aceito pelo processo fiscal.
        description: >-
          XML da NF-e a emitir/assinar. O conteúdo é assinado, transmitido à SEFAZ e o cadastro fiscal da empresa é
          atualizado. Content-Type deve ser `application/xml`.
      responses:
        '200':
          description: Nota processada — retorno do processo fiscal (chave de acesso, protocolo, status etc.).
          content:
            application/json:
              schema:
                type: object
                description: Resposta do processo fiscal. Shape não confirmado nesta operação — depende do corpo enviado.
        '400':
          description: >-
            Erros possíveis (`[BadRequest]`): `não localizado`, `erro ao emitir nota fiscal`. Também pode retornar um
            JSON com `errorMessage` vindo do processo fiscal (mensagens da SEFAZ, validações de cadastro, etc.).
          content:
            application/json:
              schema:
                type: string
        '404':
          description: Pedido não encontrado. Retorna JSON com `errorMessage` prefixado por `[NotFound]`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorMessage:
                    type: string
                  errorCode:
                    type: integer
                  errorHelp:
                    type: string
        '500':
          description: Erro interno. Resposta com prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
    delete:
      operationId: orderInvoiceRemove
      tags:
        - Pedidos
      summary: Desvincula a nota fiscal do pedido
      description: >-
        Desvincula a nota fiscal principal do pedido. Quando a nota está pendente (`0`) ou em erro (`1`), zera os dados
        de emissão (chave, dh emi, protocolo, recibo, status SEFAZ) e remove a marcação de nota principal — o registro
        fica disponível para retentativa. Quando a nota já foi cancelada/denegada/EPEC, mantém os dados emitidos mas
        remove a marcação de principal — o pedido fica livre para uma nova emissão. Bloqueado quando a nota está enviada
        (`2`) ou emitida (`3`). Registra um evento de desvinculação e retorna o `OrderDetail` recalculado.
      responses:
        '200':
          description: Nota fiscal desvinculada. Retorna o `OrderDetail` recalculado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDetail'
        '400':
          description: 'Erros possíveis (`[BadRequest]`): `Pedido não existe`, `O status atual não permite desvincular nota fiscal`.'
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro interno. Resposta com prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
  /orders/{idorder}/invoice/check:
    parameters:
      - name: idorder
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do pedido.
    get:
      operationId: orderInvoiceValidateGet
      tags:
        - Pedidos
      summary: Consulta o status da nota fiscal junto à SEFAZ
      description: >-
        Faz consulta na SEFAZ pela chave de acesso da nota fiscal emitida do pedido. Útil para sincronizar eventos que
        aconteceram fora do idworks:


        - `cStat=100` (autorizada): se a SEFAZ devolver procEventos com cartas de correção (`tpEvento=110110`) ainda não
        importadas, salva os XMLs como arquivos do tipo `6` no S3 e registra o evento de consulta. Retorna o `xMotivo`
        da SEFAZ no corpo.

        - `cStat=101/135/155` (cancelamento aceito): importa o XML de cancelamento (`tpEvento=110111/110112`) como
        arquivo do tipo `8`, atualiza a nota para cancelada e registra evento.

        - Outros: retorna erro com o `xMotivo` da SEFAZ.


        Funciona apenas quando a nota está emitida.
      responses:
        '200':
          description: >-
            Consulta processada. Quando há carta(s) de correção nova(s), retorna o `xMotivo` da SEFAZ; quando o
            cancelamento foi importado, devolve resposta vazia.
          content:
            text/plain:
              schema:
                type: string
        '400':
          description: >-
            Erros possíveis (`[BadRequest]`): `Nota Fiscal não esta no status emitida`, `Certificado digital não
            encontrado`, e mensagens da SEFAZ (texto do `xMotivo`).
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro interno. Resposta com prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
  /orders/{idorder}/invoice/simulation:
    parameters:
      - name: idorder
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do pedido.
    get:
      operationId: orderInvoiceSimulationGet
      tags:
        - Pedidos
      summary: Simula a emissão fiscal do pedido (DANFE/XML de pré-visualização)
      description: >-
        Renderiza a simulação fiscal do pedido — útil para validar o cálculo de tributos e o conteúdo da DANFE antes de
        transmitir à SEFAZ. Usa `?Type=pdf` para retornar a DANFE em PDF; sem `Type`, retorna o XML simulado. A
        simulação roda o cálculo fiscal sem transmitir à SEFAZ.
      parameters:
        - name: Type
          in: query
          required: false
          schema:
            type: string
            enum:
              - pdf
          description: Quando `pdf`, retorna a DANFE em PDF. Omitido retorna XML.
      responses:
        '200':
          description: Documento simulado.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
            application/xml:
              schema:
                type: string
        '400':
          description: Erro vindo do processo fiscal. Resposta repete o corpo retornado pelo processo.
          content:
            application/json:
              schema:
                type: string
        '404':
          description: 'Pedido não encontrado. Mensagem com prefixo `[NotFound]`: `Pedido não encontrar`.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorMessage:
                    type: string
        '500':
          description: Erro interno. Resposta com prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
  /orders/{idorder}/invoice/upload:
    parameters:
      - name: idorder
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do pedido.
    post:
      operationId: orderInvoiceUploadPost
      tags:
        - Pedidos
      summary: Importa um XML de nota fiscal já emitida para o pedido
      description: >-
        Importa um XML de NF-e/NFC-e autorizado para vincular ao pedido (cenário em que a nota foi emitida fora do
        idworks ou em sistema integrado). Validações:


        - XML precisa estar assinado (com `protNFe`).

        - CNPJ do emitente precisa bater com a empresa do pedido ou com uma empresa faturadora relacionada.

        - Quando a parametrização `ValidadeOrderInvoice` está ligada, valida o XML contra o schema da SEFAZ usando o
        certificado digital da faturadora.

        - Bloqueia XML já importado, pedido cancelado/excluído, pedido que já tenha nota vinculada (desvincular antes) e
        (a menos que `IgnoreTotalInvoiceValueImportOrder` esteja ligado) valor total da nota divergente do pedido.

        - Valida CPF/CNPJ do cliente.


        Em sucesso, atualiza o cabeçalho do pedido com os dados extraídos do XML, cria o registro da nota com a
        chave/protocolo/status, importa os impostos calculados nos itens (quando o item importado bate
        `IDSku`/`Quantity`/`PriceSelling` com a movimentação), salva o XML, importa as chaves referenciadas e registra
        um evento.
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              type: string
              description: XML de NF-e/NFC-e assinado (com `protNFe`).
        description: >-
          XML já autorizado da NF-e a importar/vincular ao pedido. O sistema valida assinatura (`protNFe` presente),
          conferência do CNPJ do emitente (precisa pertencer ao mesmo grupo da empresa) e bloqueia importação em pedidos
          cancelados/deletados.
      responses:
        '200':
          description: XML importado e nota vinculada ao pedido.
          content:
            application/json:
              schema:
                type: object
        '400':
          description: >-
            Erros possíveis: `É necessário selecionar a conta`, `XML não é válido`, `XML não esta assinado`, `O arquivo
            não é um XML de Nota Fiscal válido`, `NF fiscal não pode ser importada em pedido com status
            cancelado/deletado`, `Empresa faturadora CNPJ: <cnpj> não localizada`, `Empresa faturadora não encontrada`,
            `Certificado digital não encontrado`, `XML já importado`, `Pedido já tem nota fiscal. Desvincular antes de
            importar uma nova`, `Número de série e NF informados já estão cadastrados para o IDOrder <id> e faturador
            <faturador>`, `Valor da NF diverge do valor do pedido. Valor total NF: <valor>`, `CPF/CNPJ do cliente é
            diferente do pedido`, e mensagens da SEFAZ (quando a validação contra schema falha).
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro interno. Resposta com prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
  /orders/{idorder}/invoice/{nfenumber}:
    parameters:
      - name: idorder
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do pedido.
      - name: nfenumber
        in: path
        required: true
        schema:
          type: string
        description: Número da nota fiscal (mantido no path por convenção — o sistema resolve a nota pelo `idorder`).
    put:
      operationId: orderInvoicePut
      tags:
        - Pedidos
      summary: Emite carta de correção (CC-e) na nota fiscal do pedido
      description: >-
        Envia carta de correção à SEFAZ usando o motivo informado em `Comments`. Funciona apenas quando a nota está
        emitida. O número sequencial da CC-e é calculado pela quantidade de cartas já existentes (tipo de arquivo `6`).
        Em sucesso (`cStat=135` ou `136`), salva o XML protocolado como arquivo do tipo `6` e retorna as URLs do XML e
        da DANFE da carta. Em erro, retorna o `xMotivo` da SEFAZ.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - Comments
              properties:
                Comments:
                  type: string
                  description: Motivo da correção (texto exibido na CC-e). Aceita URL-encoded.
        description: >-
          Carta de Correção Eletrônica (CCe) para a NF-e do pedido. `Comments` é o motivo/correção que vai para a SEFAZ.
          Só funciona com nota no status emitida (`IDStatusInvoice=3`).
      responses:
        '200':
          description: CC-e aceita. Retorna o arquivo criado.
          content:
            application/json:
              schema:
                type: object
                properties:
                  IDFile:
                    type: integer
                    description: Identificador do arquivo no idworks (extraído do nome do arquivo gerado).
                  IDTypeFile:
                    type: integer
                    enum:
                      - 6
                    description: Tipo do arquivo gerado — sempre `6` (Carta de Correção XML), já que este endpoint emite a CC-e.
                  UrlFileXml:
                    type: string
                    description: URL para baixar o XML da CC-e.
                  UrlFileDanfe:
                    type: string
                    description: URL para baixar a DANFE da CC-e em PDF.
        '400':
          description: >-
            Erros possíveis (`[BadRequest]`): `Nota Fiscal não esta no status emitida`, `Certificado digital não
            encontrado`, e mensagens da SEFAZ (texto do `xMotivo` vindo do retorno do evento).
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorMessage:
                    type: string
        '500':
          description: Erro interno. Resposta com prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
    delete:
      operationId: orderInvoiceDelete
      tags:
        - Pedidos
      summary: Cancela a nota fiscal do pedido na SEFAZ
      description: >-
        Cancela a nota fiscal emitida do pedido junto à SEFAZ. Funciona apenas com nota no status emitida. Quando o
        pedido tem notas referenciadas (retorno simbólico de importação), o cancelamento é replicado para cada uma
        delas. Quando a parametrização `Bloquear cancelamento de NF 24h após emissão` está ligada, recusa cancelamento
        de notas emitidas há mais de 24h. Em sucesso (`cStat=101/135/155`), grava o XML protocolado, atualiza a nota
        para cancelada e salva o XML do cancelamento como arquivo tipo `8`. Em erro, registra o evento e devolve o
        `xMotivo`.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                Comments:
                  type: string
                  description: Motivo do cancelamento. Default `Cancelamento de nota fiscal`.
        description: >-
          Cancelamento da NF-e do pedido. `Comments` é o motivo do cancelamento enviado à SEFAZ (padrão `Cancelamento de
          nota fiscal` quando omitido). Só permite cancelar notas no status emitida.
      responses:
        '200':
          description: Cancelamento aceito pela SEFAZ.
          content:
            application/json:
              schema:
                type: object
        '400':
          description: >-
            Erros possíveis: `Nota Fiscal não esta no status emitida`, `Cancelamento de nota fiscal bloqueado por
            parametrização 24 horas após a emissão, NF emitida: <data>`, `Certificado digital não encontrado`, e
            mensagens da SEFAZ (texto do `xMotivo` quando o cancelamento é recusado).
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro interno. Resposta com prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
  /orders/{idorder}/carrier/edi:
    post:
      operationId: carrierEdiPost
      tags:
        - Pedidos
      summary: Envia EDI do pedido para a transportadora
      description: >-
        Aciona a integração EDI configurada na transportadora do pedido — repassa os dados ao processo correspondente
        (Intelipost ou arquivo de EDI específico). Retorna a resposta do processo.
      parameters:
        - name: idorder
          in: path
          required: true
          schema:
            type: integer
          description: Identificador do pedido.
      responses:
        '200':
          description: Retorno do processo EDI da transportadora.
          content:
            application/json:
              schema:
                type: object
                description: Conteúdo livre devolvido pelo processo EDI — formato depende da transportadora.
        '400':
          description: >-
            Pedido inexistente ou transportadora sem EDI configurado. Mensagens: `[BadRequest] - Pedido não encontrado`,
            `[BadRequest] - Transportadora não tem EDI configurado`.
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro retornado pelo processo EDI.
          content:
            application/json:
              schema:
                type: string
  /orders/{idorder}/carrier/quotation:
    get:
      operationId: orderCarrierQuotationGet
      tags:
        - Pedidos
      summary: Consulta a disputa de frete vinculada a um pedido
      description: >-
        Retorna a disputa de frete mais recente registrada para o pedido com a lista de transportadoras que responderam.
        Já vem com os totais calculados (subtotal, total com ICMS, valor exibido) e ordenada por atendimento, prazo e
        valor.
      parameters:
        - name: idorder
          in: path
          required: true
          schema:
            type: integer
          description: Identificador do pedido.
      responses:
        '200':
          description: Disputa encontrada (array de um único item) ou lista vazia se nunca houve disputa.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CarrierQuotation'
        '500':
          description: Erro interno. Prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
    post:
      operationId: carrierAuctionPost
      tags:
        - Pedidos
      summary: Dispara nova disputa de frete para o pedido
      description: >-
        Soma o peso e o valor dos itens do pedido e dispara a consulta de cotação contra as transportadoras
        configuradas. Ao final, devolve o mesmo conteúdo de `GET /orders/{idorder}/carrier/quotation` com a disputa
        recém-criada.
      parameters:
        - name: idorder
          in: path
          required: true
          schema:
            type: integer
          description: Identificador do pedido.
      responses:
        '200':
          description: Disputa criada e respondida pelas transportadoras.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CarrierQuotation'
        '400':
          description: >-
            Pré-condições para a disputa não satisfeitas. Mensagens: `[BadRequest] - Pedido não encontrado`,
            `[BadRequest] - Pedido não tem CEP`, `[BadRequest] - Itens pedido não tem peso`.
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro reportado pelo processo de cotação.
          content:
            application/json:
              schema:
                type: string
  /orders/hub/{idorder}:
    get:
      operationId: orderHubGetByOrder
      tags:
        - Pedidos
      summary: Detalha um pedido integrado do hub
      description: >-
        Retorna o pedido no marketplace junto com itens, pagamentos, mensagens, reclamações e ações disponíveis. Quando
        o pedido tem mensagens não lidas no Mercado Livre, marca-as como lidas via API antes de responder.
      parameters:
        - name: idorder
          in: path
          required: true
          schema:
            type: integer
          description: >-
            Identificador do pedido no hub (`IDIntegration`). O endpoint aceita também o `IDOrder` do idworks quando
            consultado por essa chave pela mesma rota.
      responses:
        '200':
          description: Pedido localizado (array de um item) ou lista vazia se não houver correspondência.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubOrderDetail'
        '500':
          description: Erro interno. Prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
  /orders/hub/{idorder}/message:
    post:
      operationId: orderHubMessageByOrderPost
      tags:
        - Pedidos
      summary: Envia uma mensagem ao comprador do marketplace
      description: >-
        Encaminha o conteúdo enviado ao canal de mensagens da integração do marketplace (mensagem normal do pedido ou
        mensagem de uma reclamação). Ao final retorna o detalhe atualizado do pedido no hub.
      parameters:
        - name: idorder
          in: path
          required: true
          schema:
            type: integer
          description: >-
            Identificador do pedido idworks. A rota aceita também `idintegration` ou `idhuborderclaim` quando
            configurada com esses params alternativos.
        - name: Type
          in: query
          required: false
          schema:
            type: string
          description: >-
            Tipo de operação a executar na integração — `send_message` (padrão) ou outro valor suportado pelo processo
            para o marketplace específico.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: >-
                Conteúdo da mensagem. O shape depende do marketplace (texto, anexos, opções de envio). Encaminhado
                integralmente ao processo da integração.
        description: >-
          Mensagem para a central de mensagens do canal (Mercado Livre, B2W etc.). O conteúdo é repassado ao canal; a
          estrutura específica varia por canal — ver documentação do canal correspondente.
      responses:
        '200':
          description: Pedido no hub recarregado com a nova mensagem.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubOrderDetail'
        '400':
          description: >-
            Pré-condições não satisfeitas. Mensagens: `[BadRequest] - Pedido não encontrado no hub`, `[BadRequest] -
            Integracão não tem envio de mensagem`, `[BadRequest] - Integracão não tem consulta de status` (quando o
            processo responde 404).
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro retornado pelo processo da integração.
          content:
            application/json:
              schema:
                type: string
  /orders/tracking/{idorder}:
    get:
      operationId: orderTrackingGet
      tags:
        - Pedidos
      summary: Consulta os eventos de rastreio já registrados para o pedido
      description: >-
        Devolve os volumes do pedido e seus eventos de tracking já armazenados pelo idworks, junto com indicadores de
        cumprimento de prazo (consumidor e transportadora). Não dispara consulta nova à transportadora — para isso use
        `GET /orders/tracking/{idorder}/check`.
      parameters:
        - name: idorder
          in: path
          required: true
          schema:
            type: integer
          description: Identificador do pedido.
      responses:
        '200':
          description: Pedido encontrado (array com um item) ou vazio quando o pedido não tem rastreio.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderTrackingDetail'
        '500':
          description: Erro interno. Prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
  /orders/tracking/{idorder}/check:
    get:
      operationId: checkTrackingStatusGet
      tags:
        - Pedidos
      summary: Força a atualização do rastreio junto à transportadora
      description: >-
        Dispara a consulta dos eventos mais recentes diretamente na transportadora do pedido (ou nos Correios quando o
        tipo é compatível) e devolve, ao final, a mesma estrutura de `GET /orders/tracking/{idorder}` já atualizada.
      parameters:
        - name: idorder
          in: path
          required: true
          schema:
            type: integer
          description: Identificador do pedido.
      responses:
        '200':
          description: Rastreio atualizado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderTrackingDetail'
        '400':
          description: >-
            Pré-condições não satisfeitas. Mensagens: `[BadRequest] - Pedido não existe`, `[BadRequest] - Tipo
            Transportadora não existe`, `[BadRequest] - Pacote não tem código de rastreio`, e erros do processo
            prefixados com `[BadRequest] -`.
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro interno. Prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
  /orders/{idorder}/return:
    post:
      operationId: orderReturn
      tags:
        - Pedidos
      summary: Gera o pedido de devolução a partir de um pedido existente
      description: >-
        Recalcula o rateio de frete/despesas acessórias do pedido original, monta os itens (com quantidades negativas) e
        os pagamentos espelhados, e cria um pedido do tipo devolução. Pode opcionalmente reverter estoque, gerar
        recebimento, emitir nota fiscal de devolução e abrir voucher para o cliente. Ao final invoca `GET
        /orders/{idorder}` no pedido criado e devolve o detalhe.
      parameters:
        - name: idorder
          in: path
          required: true
          schema:
            type: integer
          description: Identificador do pedido original que está sendo devolvido.
        - name: idtypeorderreturn
          in: query
          required: false
          schema:
            type: integer
          description: Tipo de devolução (alternativa para chamadas só com query).
        - name: idtypeorderreturncategory
          in: query
          required: false
          schema:
            type: integer
          description: Categoria do tipo de devolução.
        - name: comments
          in: query
          required: false
          schema:
            type: string
          description: Observações.
        - name: balancechange
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Afeta estoque (`1`/`0`). Padrão `1`.
        - name: withvalue
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Mantém valores do pedido original (`1`/`0`). Padrão `1`.
        - name: idstockkeepingunitwarehouse
          in: query
          required: false
          schema:
            type: integer
          description: Armazém destino.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderReturnBody'
        description: >-
          Parâmetros da devolução. Os mesmos campos podem ser passados em query string (snake_case). Sem `Items`,
          devolve todas as movimentações do pedido.
      responses:
        '200':
          description: Pedido de devolução criado — devolve a estrutura completa do pedido criado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDetail'
        '400':
          description: >-
            Validações de cadastro. Mensagens: `[BadRequest] - Tipo devolução não existe`, `[BadRequest] - Tipo pedido
            de devolução não existe ou não está configurado corretamente. Precisa cadastrar`, `[BadRequest] - Armazém
            não existe`, `[BadRequest] - Tipo categoria devolução não existe`, `[BadRequest] - Cliente não existe`,
            `[BadRequest] - Endereço não existe`. Erros vindos da criação de pedido também chegam com a mensagem
            original.
          content:
            application/json:
              schema:
                type: string
        '404':
          description: 'Pedido original inexistente. Mensagem: `[NotFound] - Pedido não encontrado`.'
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro interno. Prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
  /orders/invoice-xml:
    post:
      operationId: OrderInvoiceXmlGet
      tags:
        - Pedidos
      summary: Solicita o pacote ZIP com os XMLs de NFe dos pedidos
      description: >-
        Gera de forma assíncrona um arquivo ZIP com os XMLs (autorização, cancelamento, inutilização, carta de correção)
        dos pedidos ou arquivos informados, sobe o ZIP em armazenamento temporário e envia o link de download por e-mail
        ao usuário que disparou a requisição. A resposta imediata é a URL pré-assinada de download (válida por 2 dias).
        Os filtros recebidos por query string entram no nome do arquivo gerado.
      parameters:
        - name: Key
          in: query
          required: false
          schema:
            type: string
            enum:
              - IDFile
              - IDOrder
          description: >-
            Define se o conteúdo enviado no body é uma lista de identificadores de arquivos (`IDFile`) ou de pedidos
            (`IDOrder`, padrão).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              description: Lista de identificadores a empacotar (pedidos ou arquivos, conforme `Key`).
              items:
                type: integer
        description: >-
          Array de IDs (de `IDFile`, `IDOrder` ou `IDNfCompany` conforme `?Key=`) cujos XMLs serão zipados e enviados
          por e-mail ao usuário solicitante.
      responses:
        '200':
          description: URL temporária do ZIP gerado. O link também é enviado por e-mail.
          content:
            application/json:
              schema:
                type: string
                description: URL pré-assinada do ZIP.
        '400':
          description: Erro de validação — XML ausente, inválido ou não corresponde a uma NF-e processável.
          content:
            application/json:
              schema:
                type: string
        '500':
          description: >-
            Erro de upload do ZIP, falha de envio de e-mail ou erro interno. Prefixos `zipFile.upload error ...`,
            `catched error: ...` ou `Error:`.
          content:
            application/json:
              schema:
                type: string
  /orders/invoice-xml/import:
    post:
      operationId: orderImportXml
      tags:
        - Pedidos
      summary: Importa um pedido a partir do XML de uma NF-e
      description: >-
        Recebe o XML autorizado de uma NF-e e cria o pedido no idworks com itens, impostos, cliente, endereços e
        pagamentos extraídos. Quando os SKUs não estão cadastrados, a importação falha — exceto se a parametrização
        **Criar SKU automaticamente quando não existir** estiver ativa. Quando configurado, valida a assinatura junto à
        SEFAZ antes de importar.
      parameters:
        - name: IDCompanyIntegration
          in: query
          required: true
          schema:
            type: integer
          description: Integração que recebe o pedido importado.
        - name: importtype
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 3
              - 5
          description: >-
            Como localizar o SKU: `1` código do fornecedor, `2` código de barras (cEAN), `3` `IDSkuCompany` excluindo
            produto, `5` anúncio do hub. Quando omitido, tenta a sequência completa.
        - name: IDStockKeepingUnitWarehouse
          in: query
          required: false
          schema:
            type: integer
          description: Armazém origem dos itens.
        - name: BalanceChange
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Se a importação deve afetar o saldo de estoque.
        - name: IDOrderType
          in: query
          required: false
          schema:
            type: integer
          description: Tipo do pedido que será criado.
        - name: IDStatusOrder
          in: query
          required: false
          schema:
            type: integer
          description: Status inicial do pedido criado.
        - name: IDCompanyInvoice
          in: query
          required: false
          schema:
            type: integer
          description: Empresa faturadora. Quando omitida, usa a própria empresa autenticada.
        - name: CreateInbound
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Se deve criar um recebimento atrelado.
        - name: IDStockKeepingUnitWarehouseInbound
          in: query
          required: false
          schema:
            type: integer
          description: Armazém de recebimento (quando `CreateInbound=1`).
        - name: FinishInbound
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Se deve já finalizar o recebimento.
        - name: OrderFrom
          in: query
          required: false
          schema:
            type: string
          description: Número de origem do pedido (sobrescreve `xPed` do XML).
        - name: IDOrderFrom
          in: query
          required: false
          schema:
            type: integer
          description: Pedido idworks de origem (para casos de devolução vinculada).
        - name: Negative
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Quando `1`, sinais de frete/despesas/pagamentos são invertidos (devolução).
        - name: AnyVariationIfProduct
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Quando `1`, aceita uma variação qualquer caso o código bata com um produto-pai.
        - name: SalesmanUserExtenalId
          in: query
          required: false
          schema:
            type: string
          description: Vendedor identificado pelo identificador externo do usuário.
        - name: SalesmanUserId
          in: query
          required: false
          schema:
            type: integer
          description: Vendedor identificado por `IDUser`.
        - name: IDStoreFrontCashier
          in: query
          required: false
          schema:
            type: integer
          description: Caixa do PDV vinculado ao pedido.
        - name: Payments
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
          description: >-
            Pagamentos a aplicar — cada item no formato `IDTypePayment,Value,InstallmentTotal,TID,NSU`. A soma precisa
            bater com o valor da NF.
        - name: IDNfCompany
          in: query
          required: false
          schema:
            type: integer
          description: NF previamente armazenada no idworks que deve receber esse pedido.
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              type: string
              description: Conteúdo do XML autorizado (com `protNFe`).
          application/json:
            schema:
              type: string
              description: XML serializado como string JSON, alternativo ao `application/xml`.
        description: >-
          XML de NF-e a importar como pedido. O sistema cria pedido, cliente, itens e movimentações de estoque conforme
          parametrização (`importtype`, `BalanceChange`, `IDStockKeepingUnitWarehouse` em query).
      responses:
        '200':
          description: Pedido criado.
          content:
            application/json:
              schema:
                type: object
                description: Resultado do processamento — geralmente o pedido criado.
        '400':
          description: >-
            Validações da NF/SEFAZ ou de pré-cadastro. Mensagens conhecidas: `Precisar enviar o XML no body da
            requisição`, `Erro ao converter XML`, `É necessário selecionar a conta`, `Precisa informar a integração`,
            `XML não esta assinado`, `XML já importado`, `Emissor da NF diferente da empresa no sistema idworks`, `Nota
            fiscal emitida em homologação`, `Número de série e NF informados já estão cadastrados para o pedido <id>`,
            `Empresa faturadora não encontrada`, `NF não encontrada`, `NF já vinculada ao pedido <id>`, `Certificado
            digital não encontrado`, `Erro validação SEFAZ`, `Armazém recebimento não cadastrado`, `SKU(s) não
            cadastrados: ...`, `SKU(s) sem codigo de barras cadastrados na nota fiscal`, `Tipo pagamento não
            cadastrado`, `Valor total do pagamento diverge do valor total da NF`.
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro interno do processo de retaguarda. Prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
  /orders/template:
    get:
      operationId: orderFileTemplateExportGet
      tags:
        - Pedidos
      summary: Baixa o template de planilha para importação ou edição em lote
      description: >-
        Devolve a planilha modelo correspondente ao tipo informado: pedidos (padrão), atualização de status de pedido,
        contas a pagar/receber, impostos de marketplace e ordens de serviço.
      parameters:
        - name: Type
          in: query
          required: false
          schema:
            type: string
            enum:
              - Order
              - OrderStatus
              - AccountsPayable
              - AccountsReceivable
              - MarketplaceTaxes
              - ServiceOrder
          description: Tipo de planilha. Padrão `Order`.
      responses:
        '200':
          description: Arquivo XLSX retornado (planilha modelo).
          content:
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                type: string
                format: binary
        '400':
          description: 'Tipo inválido. Mensagem: `tipo de template não informado`.'
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro interno. Prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
    post:
      operationId: orderFileTemplateImport
      tags:
        - Pedidos
      summary: Importa planilha de pedidos / contas a pagar / contas a receber em lote
      description: >-
        Recebe o arquivo enviado via multipart, salva no armazenamento temporário, cria um job e dispara o processamento
        assíncrono. A resposta retorna imediatamente o identificador do job — o resultado é enviado posteriormente por
        e-mail. Se já existe um job em andamento com o mesmo hash de arquivo, devolve o job existente.
      parameters:
        - name: Type
          in: query
          required: false
          schema:
            type: string
            enum:
              - AccountsPayable
              - AccountsReceivable
          description: >-
            Tipo de importação: omitido importa pedidos (padrão), `AccountsPayable` importa contas a pagar,
            `AccountsReceivable` importa contas a receber.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: Planilha a importar.
        description: >-
          Disparo assíncrono do gerador de template — a chamada retorna imediatamente sem bloquear o cliente. Body
          opcional; quando enviado, é repassado integralmente para o gerador.
      responses:
        '200':
          description: Job criado ou já em andamento. O resultado da importação chega por e-mail quando o processamento terminar.
          content:
            application/json:
              schema:
                type: object
                properties:
                  IDJob:
                    type: integer
                    description: Identificador do job em processamento.
                  Message:
                    type: string
                    description: Mensagem amigável (geralmente `Arquivo em processamento, aguardar resposta por email`).
        '400':
          description: Quando o body está vazio, o sistema responde com status `400` (sem `errorMessage`).
          content:
            application/json: {}
        '404':
          description: Empresa não encontrada para o `accountname` do contexto.
          content:
            application/json: {}
        '500':
          description: Erro interno. Prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
    put:
      operationId: orderFileTemplateExportPut
      tags:
        - Pedidos
      summary: Aplica atualizações em lote a partir do template
      description: >-
        Recebe os dados editados na planilha de template e aciona a rotina de atualização correspondente (ex.: alteração
        de status em massa pelo `Type=OrderStatus`). Consulte a tela do frontend que monta a planilha para o layout
        exato das colunas.
      parameters:
        - name: Type
          in: query
          required: false
          schema:
            type: string
            enum:
              - Order
              - OrderStatus
              - AccountsPayable
              - AccountsReceivable
              - MarketplaceTaxes
              - ServiceOrder
          description: Tipo de atualização. Padrão `Order`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Conteúdo da planilha já estruturado.
        description: >-
          Conteúdo da planilha já estruturado para importação de pedidos — o layout das colunas segue a planilha modelo
          exportada por `GET /orders/template`.
      responses:
        '200':
          description: Atualização aplicada. Conteúdo retornado depende do tipo.
          content:
            application/json:
              schema:
                type: object
        '400':
          description: 'Validações. Mensagem: `tipo de template não informado`.'
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro interno. Prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
  /orders/tag:
    get:
      operationId: ordersTagList
      tags:
        - Pedidos
      summary: Lista as etiquetas (tags) dos pedidos
      description: >-
        Retorna o conjunto distinto de tags aplicadas aos pedidos da empresa, em ordem alfabética. Quando um `IDOrder` é
        informado, restringe à(s) tag(s) daquele pedido.
      parameters:
        - name: IDOrder
          in: query
          required: false
          schema:
            type: integer
          description: Restringe a busca às tags de um pedido específico.
      responses:
        '200':
          description: Lista de tags.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    Tag:
                      type: string
                      description: Texto da etiqueta.
                    AccountName:
                      type: string
                      description: Conta dona da etiqueta.
        '500':
          description: Erro interno. Prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
  /orders/{idorder}/duplicate:
    post:
      operationId: orderDuplicate
      tags:
        - Pedidos
      summary: Duplica um pedido existente
      description: >-
        Cria uma cópia do pedido (com a opção de classificá-lo como reenvio, manter ou zerar valores e usar valor médio
        dos itens). Ao terminar, devolve o detalhe completo do pedido recém-criado.
      parameters:
        - name: idorder
          in: path
          required: true
          schema:
            type: integer
          description: Identificador do pedido a duplicar.
        - name: IDTypeOrderResend
          in: query
          required: false
          schema:
            type: integer
          description: Motivo do reenvio quando o duplicado representa uma reentrega.
        - name: Comments
          in: query
          required: false
          schema:
            type: string
          description: Observações a registrar no novo pedido.
        - name: BalanceChange
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Se a duplicação afeta saldo de estoque. Padrão `1`.
        - name: WithValue
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Mantém os valores do pedido original (`1`) ou zera (`0`).
        - name: WithBatch
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Mantém os lotes do pedido original.
        - name: AverageValue
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Quando `1`, usa o valor médio dos itens em vez do valor original.
      responses:
        '200':
          description: Pedido duplicado — devolve a estrutura completa do pedido criado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDetail'
        '404':
          description: 'Pedido original não encontrado. Mensagem: `[NotFound] - Pedido não encontrado`.'
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro na duplicação ou erro interno. Prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
  /orders/{idorder}/label:
    get:
      operationId: orderLabelGet
      tags:
        - Pedidos
      summary: Gera a etiqueta de envio do pedido
      description: >-
        Monta a etiqueta de envio do pedido conforme a transportadora — pode usar layout customizado da empresa,
        etiqueta manual cadastrada no pedido, integração com marketplace/transportadora (Mercado Envios, Magalu
        Entregas, Shopee, Olist, Loggi, Total Express, Smartenvios, etc.) ou um dos templates padrão (Correios, padrão
        genérico, etiqueta de inconformidade). Retorna PDF (padrão) ou ZPL conforme os parâmetros e, dependendo da
        parametrização **Status do pedido após gerar etiqueta**, atualiza o status do pedido.
      parameters:
        - name: idorder
          in: path
          required: true
          schema:
            type: integer
          description: Identificador do pedido.
        - name: Download
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: >-
            Quando `1`, força download do arquivo ZPL. Quando `0` e o canal retorna ZPL, devolve em texto puro. Sem o
            parâmetro, devolve um PDF gerado a partir do ZPL pelo serviço Labelary.
        - name: PackageNumber
          in: query
          required: false
          schema:
            type: integer
          description: Número do volume específico a imprimir. Sem o parâmetro, imprime todos.
        - name: Zpl
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Marca que a saída deve ser tratada como ZPL.
        - name: OnlyLabel
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Quando `1`, devolve só a etiqueta — não inclui a DANFE.
        - name: OnlyInvoice
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Quando `1`, devolve só a nota fiscal/DANFE. Permite gerar mesmo sem transportadora cadastrada.
        - name: IDCompanyLabel
          in: query
          required: false
          schema:
            type: integer
          description: Layout de etiqueta customizado da empresa a aplicar.
        - name: OnlyCheck
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Quando `1`, não atualiza o status do pedido após gerar a etiqueta.
        - name: Type
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 2
          description: Quando `2`, imprime a etiqueta de inconformidade em vez da etiqueta de envio.
        - name: debug
          in: query
          required: false
          schema:
            type: string
          description: Sinalizador interno repassado para os workers de integração.
      responses:
        '200':
          description: Etiqueta gerada — formato depende dos parâmetros.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
            application/epl2:
              schema:
                type: string
                description: Conteúdo ZPL (download direto).
            text/plain:
              schema:
                type: string
                description: Conteúdo ZPL em texto.
            application/json:
              schema:
                type: object
                description: 'Resposta JSON quando o canal retorna apenas um link para a etiqueta (ex.: `LabelUrl`).'
        '400':
          description: >-
            Pré-condições não satisfeitas. Mensagens conhecidas: `Pedido não encontrado`, `Pedido sem transportadora`,
            `Nota fiscal não emitida`, `Etiqueta manual não localizada`, `Problema ao gerar etiqueta`, `Erro ao gerar
            etiqueta`, `Erro ao gerar PDF. Por favor clicar no botao de imprimir.` e a mensagem `errorMessage` do
            processo da transportadora quando aplicável.
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro interno. Prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
  /orders/{idorder}/promotion:
    get:
      operationId: orderPromotionGet
      tags:
        - Pedidos
      summary: Lista as promoções/benefícios aplicados ao pedido
      description: >-
        Retorna em uma só estrutura as promoções de PDV vinculadas ao pedido e os benefícios oriundos do marketplace
        (quando o pedido vem do hub).
      parameters:
        - name: idorder
          in: path
          required: true
          schema:
            type: integer
          description: Identificador do pedido.
      responses:
        '200':
          description: Sempre retorna um array de um item — listas vazias quando não há promoção/benefício.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderPromotion'
        '500':
          description: Erro interno. Prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
  /orders/{idorder}/start-handling:
    post:
      operationId: orderStartHandling
      tags:
        - Pedidos
      summary: Inicia o processamento (handling) de um pedido
      description: >-
        Marca o pedido como em separação/processamento. Quando `NoInvoke=1`, devolve apenas a string `"sucesso"`; caso
        contrário, retorna o detalhe completo do pedido após a mudança.
      parameters:
        - name: idorder
          in: path
          required: true
          schema:
            type: integer
          description: Identificador do pedido.
        - name: NoInvoke
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Quando `1`, evita a chamada de `OrderGet` ao final — retorna apenas a string `sucesso`.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                StatusComment:
                  type: string
                  description: Observação registrada na mudança de status.
        description: >-
          Inicia o manuseio (handling) do pedido — usado pela tela de Outbound. `StatusComment` opcional registra
          observação no histórico de status.
      responses:
        '200':
          description: Pedido em processamento. Estrutura varia conforme `NoInvoke`.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/OrderDetail'
                  - type: string
                    description: Quando `NoInvoke=1`, devolve `"sucesso"`.
        '400':
          description: >-
            Pedido inexistente. Mensagem: `[BadRequest] - Pedido não encontrado`. Erros do processamento são repassados
            como JSON na string.
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Erro interno. Prefixo `Error:`.
          content:
            application/json:
              schema:
                type: string
  /hub/carrier:
    get:
      operationId: hubCarrierList
      tags:
        - Hub — DE-PARA Transportadora
      summary: Lista mapeamentos — DE-PARA Transportadora
      description: Retorna todos os DE-PARA cadastrados, ordenados por integração e nome.
      parameters:
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pelos DE-PARA de uma integração específica.
        - name: IDCarrierFrom
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo identificador da transportadora no canal.
        - name: IDCarrierTo
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pela transportadora interna mapeada.
      responses:
        '200':
          description: Array de mapeamentos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubCarrierMapping'
    post:
      operationId: hubCarrierPost
      tags:
        - Hub — DE-PARA Transportadora
      summary: Cria mapeamento — DE-PARA Transportadora
      description: >-
        Cria um novo DE-PARA e devolve a lista completa atualizada (re-invoca o List). Quando `CarrierAuctionByModal=1`,
        o sistema força `IDCarrierTo` para `null` — a transportadora final será escolhida em runtime pelo leilão por
        modal.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubCarrierCreateBody'
        description: >-
          Mapeamento de transportadora a cadastrar. `IDCompanyIntegration` e `IDCarrierFrom` são obrigatórios. Quando
          `CarrierAuctionByModal = 1`, `IDCarrierTo` é forçado a `null` pelo servidor — a transportadora é escolhida em
          tempo de roteirização via leilão entre transportadoras do modal indicado em `IDCarrierModal`.
      responses:
        '200':
          description: Lista atualizada após a criação.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubCarrierMapping'
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `Integração não cadastrada`
            - `Transportadora não cadastrada`
            - `Status pedido não existe`
            - `Modal não existe`
            - `Armazém não existe`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/carrier/{idhubcarrier}:
    put:
      operationId: hubCarrierPut
      tags:
        - Hub — DE-PARA Transportadora
      summary: Atualiza mapeamento — DE-PARA Transportadora
      description: Atualiza um DE-PARA existente e devolve a lista completa atualizada. Mesmas validações do POST.
      parameters:
        - name: idhubcarrier
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do mapeamento.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubCarrierUpdateBody'
        description: Mesma estrutura do POST. Todos os campos são revalidados.
      responses:
        '200':
          description: Lista atualizada após a edição.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubCarrierMapping'
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `de/para transportadora não existe`
            - `Integração não cadastrada`
            - `Transportadora não cadastrada`
            - `Status pedido não existe`
            - `Modal não existe`
            - `Armazém não existe`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: hubCarrierDelete
      tags:
        - Hub — DE-PARA Transportadora
      summary: Remove mapeamento — DE-PARA Transportadora
      description: Apaga o DE-PARA e devolve a lista completa atualizada.
      parameters:
        - name: idhubcarrier
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do mapeamento.
      responses:
        '200':
          description: Lista atualizada após remoção.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubCarrierMapping'
        '400':
          description: '`[BadRequest] - IDHubCarrier não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/carrier/auction:
    get:
      operationId: hubCarrierAuctionGet
      tags:
        - Hub — DE-PARA Transportadora
      summary: Cotação de frete — leilão entre transportadoras
      description: >-
        Dispara o motor de cotação de frete (leilão) entre as transportadoras cadastradas. `GET` e `POST` da mesma rota
        têm o mesmo comportamento. Retorna a lista de transportadoras com `ShippingShowValue`, `TotalShowDaysTime`,
        `Attended` e os componentes de preço (ICMS, GRIS, advalorem, pedágio etc.).
      parameters:
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Quando informado, identifica a integração de origem da cotação (canal externo).
        - name: IDTypeCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: >-
            Tipo de integração — usado para entregar o response no formato esperado pelo canal (Tray, Meli, Convertize,
            etc.).
        - name: debug
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Quando `1`, imprime o trace de cada regra avaliada.
        - name: online
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: >-
            Quando `1`, persiste a cotação temporariamente sob a chave `CarrierQuotation:<uuid>` (permitindo respostas
            subsequentes via `If-None-Match`). Default `0`.
      responses:
        '200':
          description: Resultado da cotação.
          content:
            application/json:
              schema:
                type: object
                description: Payload do motor de cotação — campos exatos não confirmados.
        '304':
          description: Resposta condicional — o `If-None-Match` enviado ainda é válido para o canal e a cotação anterior não mudou.
        '400':
          description: >-
            Erros de negócio. Exemplos: `Empresa não localizada`, `Precisa enviar corpo`, `Precisa enviar o CEP
            destino`, `Peso precisa ser maior que zero`, `CEP destino XXXXX não existe`, `Dados para cotação não
            enviados`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    post:
      operationId: hubCarrierAuctionPost
      tags:
        - Hub — DE-PARA Transportadora
      summary: Cotação de frete — leilão entre transportadoras
      description: >-
        Mesma função de `GET /hub/carrier/auction`, porém recebe os dados da cotação no corpo da requisição. O corpo tem
        ao menos `ShippingPostalCode` (CEP destino) e um array `Quotations[]` com `Weight`, `Height`, `Length`, `Width`,
        `ValueInvoice` por volume; aceita também `OriginPostalCode`, `Description`, `IDOrder`, `IDCompanyIntegration`,
        `IDSkuHub`, `IDSkuCompany`, `IDTypeCompanyIntegration`, `RecordUserCreated`.
      parameters:
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pelo identificador da integração da empresa.
        - name: IDTypeCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pelo tipo de integração da empresa.
        - name: debug
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Quando `1`, inclui informações adicionais de depuração na resposta.
        - name: online
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Quando `1`, restringe a integrações ou canais online.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Dados da cotação.
              properties:
                ShippingPostalCode:
                  type: string
                  description: CEP destino (somente números, padding à esquerda em 8 dígitos).
                OriginPostalCode:
                  type: string
                  nullable: true
                  description: CEP origem. Quando omitido, usa o CEP da empresa.
                ValueInvoice:
                  type: number
                  nullable: true
                  description: Valor total da nota — referência para advalorem, GRIS e regras por faixa de valor.
                IDOrder:
                  type: integer
                  format: int64
                  nullable: true
                  description: Pedido associado, quando a cotação está vinculada a um pedido existente.
                Description:
                  type: string
                  nullable: true
                  description: Descrição opcional da cotação (rótulo livre).
                RecordUserCreated:
                  type: integer
                  format: int64
                  nullable: true
                  description: Identificador do usuário que originou a cotação.
                Quotations:
                  type: array
                  description: Volumes a cotar.
                  items:
                    type: object
                    properties:
                      Weight:
                        type: number
                        description: Peso bruto (kg).
                      Height:
                        type: number
                        description: Altura (cm).
                      Length:
                        type: number
                        description: Comprimento (cm).
                      Width:
                        type: number
                        description: Largura (cm).
                      ValueInvoice:
                        type: number
                        description: Valor da nota do volume.
        description: >-
          Dados da cotação de frete. Mínimo: `ShippingPostalCode` (CEP destino) e um array `Quotations[]` com `Weight`,
          `Height`, `Length`, `Width` e `ValueInvoice` por volume. Campos opcionais: `OriginPostalCode`, `Description`,
          `IDOrder`, `RecordUserCreated`.
      responses:
        '200':
          description: Resultado da cotação.
          content:
            application/json:
              schema:
                type: object
                description: Payload do motor de cotação — campos exatos não confirmados.
        '400':
          description: >-
            Erros de negócio: `Precisa enviar corpo`, `Precisa enviar o CEP destino`, `Peso precisa ser maior que zero`,
            `CEP destino XXXXX não existe`, `Empresa não localizada`, `Dados para cotação não enviados`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/carrier/auction/{idcompanyintegration}:
    get:
      operationId: hubCarrierAuctionByIntegrationGet
      tags:
        - Hub — DE-PARA Transportadora
      summary: Cotação de frete a partir de uma integração específica
      description: >-
        Mesma função das rotas `/hub/carrier/auction`, porém a integração de origem da cotação vem como parâmetro de
        path em vez de query.
      parameters:
        - name: idcompanyintegration
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Integração de origem da cotação.
      responses:
        '200':
          description: Resultado da cotação.
          content:
            application/json:
              schema:
                type: object
                description: Payload do motor de cotação — campos exatos não confirmados.
        '400':
          description: Erros de negócio.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/acquirer:
    get:
      operationId: hubAcquirerList
      tags:
        - Hub — DE-PARA Adquirentes
      summary: Lista mapeamentos — DE-PARA Adquirentes
      description: Retorna todos os DE-PARA de adquirente cadastrados, ordenados pela integração.
      parameters:
        - name: IDAcquirerFrom
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo identificador da adquirente no canal.
        - name: IDAcquirerTo
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pela adquirente cadastrada no idworks (`CompanyIntegration` do tipo adquirente).
      responses:
        '200':
          description: Array de mapeamentos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubAcquirerMapping'
    post:
      operationId: hubAcquirerPost
      tags:
        - Hub — DE-PARA Adquirentes
      summary: Cria mapeamento — DE-PARA Adquirentes
      description: >-
        Cria um DE-PARA e devolve a lista atualizada (re-invoca o List). O sistema rejeita duplicidade exata (mesma
        integração, mesma adquirente do canal e mesma adquirente interna).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubAcquirerCreateBody'
        description: >-
          Mapeamento de adquirente a cadastrar. `IDAcquirerFrom` é o código da adquirente no canal (texto livre);
          `IDAcquirerTo` referencia outra `CompanyIntegration` da mesma empresa, do tipo adquirente.
      responses:
        '200':
          description: Lista atualizada após criação.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubAcquirerMapping'
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `Integração não cadastrada`
            - `Integração adquirente não cadastrada`
            - `Já existe um de/para igual criado`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/acquirer/{idhubacquirer}:
    put:
      operationId: hubAcquirerPut
      tags:
        - Hub — DE-PARA Adquirentes
      summary: Atualiza mapeamento — DE-PARA Adquirentes
      description: >-
        Atualiza um DE-PARA e devolve a lista atualizada. Mesmo body do POST. O sistema rejeita duplicidade contra
        outros registros existentes.
      parameters:
        - name: idhubacquirer
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do mapeamento.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubAcquirerCreateBody'
        description: Mesma estrutura do POST. Todos os campos são revalidados.
      responses:
        '200':
          description: Lista atualizada após edição.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubAcquirerMapping'
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `De/Para adquirente não existe`
            - `Integração adquirente não cadastrada`
            - `Já existe um de/para igual criado`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: hubAcquirerDelete
      tags:
        - Hub — DE-PARA Adquirentes
      summary: Remove mapeamento — DE-PARA Adquirentes
      description: Apaga o DE-PARA.
      parameters:
        - name: idhubacquirer
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do mapeamento.
      responses:
        '200':
          description: Texto literal `sucesso` quando a remoção é concluída.
          content:
            application/json:
              schema:
                type: string
                example: sucesso
        '400':
          description: '`[BadRequest] - De/Para adquirente não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/variation:
    get:
      operationId: hubVariationList
      tags:
        - Hub — DE-PARA Variações
      summary: Lista mapeamentos — DE-PARA Variações
      description: Retorna os DE-PARA de variação cadastrados, ordenados por integração.
      parameters:
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pela integração.
        - name: IDVariationTo
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Filtra pela variação interna (`IDTypeProductVariation`).
        - name: VariationName
          in: query
          required: false
          schema:
            type: string
          description: Busca textual no nome da variação interna (`ProductVariation`) via `LIKE`.
      responses:
        '200':
          description: Array de mapeamentos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubVariationMapping'
    post:
      operationId: hubVariationPost
      tags:
        - Hub — DE-PARA Variações
      summary: Cria mapeamento — DE-PARA Variações
      description: >-
        Cria um DE-PARA e devolve a lista atualizada (re-invoca o List). O sistema valida unicidade do trio (variação
        interna, integração, DE-PARA de categoria).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubVariationCreateBody'
        description: >-
          Mapeamento de variação a cadastrar. A categoria do canal (`IDHubCategory`) intermedeia o mapeamento porque os
          atributos de variação disponíveis dependem da categoria do produto.
      responses:
        '200':
          description: Lista atualizada após criação.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubVariationMapping'
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `Integração não cadastrada`
            - `Variação não cadastrada`
            - `Hub Categoria não existe`
            - `Já existe um de/para igual criado`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/variation/{idhubvariation}:
    put:
      operationId: hubVariationPut
      tags:
        - Hub — DE-PARA Variações
      summary: Atualiza mapeamento — DE-PARA Variações
      description: >-
        Atualiza um DE-PARA e devolve a lista atualizada. Mesmas validações do POST mais a verificação de existência do
        registro.
      parameters:
        - name: idhubvariation
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do mapeamento.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubVariationCreateBody'
        description: Mesma estrutura do POST. Todos os campos são revalidados.
      responses:
        '200':
          description: Lista atualizada após edição.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubVariationMapping'
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `De/Para variação não existe`
            - `Variação não cadastrada`
            - `Hub Categoria não existe`
            - `Já existe um de/para igual criado`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
    delete:
      operationId: hubVariationDelete
      tags:
        - Hub — DE-PARA Variações
      summary: Remove mapeamento — DE-PARA Variações
      description: Apaga o DE-PARA e devolve a lista atualizada.
      parameters:
        - name: idhubvariation
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do mapeamento.
      responses:
        '200':
          description: Lista atualizada após remoção.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubVariationMapping'
        '400':
          description: '`[BadRequest] - IDHubVariation não existe`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/resource/auth:
    get:
      operationId: hubResourceAuthGet
      tags:
        - Hub — Recursos
      summary: Callback de autenticação OAuth do canal
      description: >-
        Endpoint de **callback** chamado pelos canais de venda após o usuário autorizar o idworks. Resolve a integração
        a partir de `state`/`reference`/`IDCompanyIntegration` (ou de credenciais específicas em `code`/`store`) e
        despacha para o fluxo de autenticação do tipo de integração — Bling, Cielo, Mercado Livre, Shopee, Olist,
        Amazon, Shopify, Mercado Pago, Tray, Magalu, Melhor Envio, Shein, Nuvemshop, TikTok, R3Express, Temu, Integra.
        Cada provedor tem seu próprio formato de corpo e resposta (HTML de redirect, JSON).
      parameters:
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: >-
            Integração da empresa para a qual o callback se aplica. Quando ausente, o sistema tenta resolver via
            `state`, `reference`, `store` ou credenciais do canal.
        - name: IDTypeCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: >-
            Tipo de integração. Usado para rotear o callback (ex.: `IDTYPECOMPANYINTEGRATION_INTEGRA`,
            `IDTYPECOMPANYINTEGRATION_NUVEMSHOP`).
        - name: state
          in: query
          required: false
          schema:
            type: string
          description: >-
            Token de estado OAuth (`Token`) usado para correlacionar o callback com a integração originalmente
            disparada.
        - name: reference
          in: query
          required: false
          schema:
            type: string
          description: Alias de `state` para provedores que repassam o token como `reference`.
        - name: code
          in: query
          required: false
          schema:
            type: string
          description: Código de autorização devolvido pelo canal — usado nos fluxos OAuth padrão para trocar por token.
        - name: store
          in: query
          required: false
          schema:
            type: string
          description: Identificador da loja no canal (`store_id`) — usado pelo Tray para localizar a integração.
        - name: an
          in: query
          required: false
          schema:
            type: string
          description: Subdomínio da conta — usado quando não há `requestContext` (chamadas externas diretas).
        - name: shop_id
          in: query
          required: false
          schema:
            type: string
          description: Identificador da loja no Shopee, repassado no callback de autorizacao do canal.
        - name: main_account_id
          in: query
          required: false
          schema:
            type: string
          description: >-
            Identificador da conta principal no Shopee, repassado no callback quando a loja pertence a uma conta
            principal.
        - name: selling_partner_id
          in: query
          required: false
          schema:
            type: string
          description: Identificador do vendedor (selling partner) devolvido pela Amazon no callback de autorizacao.
        - name: spapi_oauth_code
          in: query
          required: false
          schema:
            type: string
          description: Codigo de autorizacao OAuth da Amazon SP-API, usado no lugar de code no callback da Amazon.
        - name: api_address
          in: query
          required: false
          schema:
            type: string
          description: Endereco base da API da loja, repassado pela Tray no callback do canal.
        - name: url
          in: query
          required: false
          schema:
            type: string
          description: URL da loja, repassada pela Tray no callback do canal.
        - name: tempToken
          in: query
          required: false
          schema:
            type: string
          description: Token temporario de autorizacao devolvido pela Shein no callback, trocado em seguida por token de acesso.
        - name: token
          in: query
          required: false
          schema:
            type: string
          description: Token de autorizacao devolvido pela R3Express no callback.
        - name: shop
          in: query
          required: false
          schema:
            type: string
          description: Dominio da loja Shopify devolvido no callback de instalacao do aplicativo.
      responses:
        '200':
          description: Resposta específica do canal — HTML de redirect, JSON com tokens ou texto plano.
        '400':
          description: >-
            Erros de negócio:

            - `Precisa a query string IDCompanyIntegration ou state`

            - `Integração não encontrada. Verificar se a integração já esta cadastrada na idworks e os dados preenchidos
            (clicar na engrenagem)`

            - `Integração não tem autenticação por URL`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
  /hub/resource/{idtypecompanyintegration}:
    get:
      operationId: companyIntegrationResourceList
      tags:
        - Hub — Recursos
      summary: Lista recursos disponíveis do tipo de integração
      description: >-
        Retorna os recursos (`TypeSalesChannelResource`) cadastrados para o tipo de integração e o `ResourceType`
        indicado. Para `ResourceType=Autoparts`, o sistema ainda valida que a categoria `CategoryId` está na lista de
        categorias suportadas — se não estiver, devolve `[]` em vez da lista completa.
      parameters:
        - name: idtypecompanyintegration
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Tipo de integração (canal).
        - name: ResourceType
          in: query
          required: true
          schema:
            type: string
          description: >-
            Tipo de recurso a listar (ex.: `Autoparts`, `Category`, `CategoryAttribute`, `SkuCondition`, `TypeOffer`,
            `ModeShipping`, `OfficialStore`).
        - name: CategoryId
          in: query
          required: false
          schema:
            type: string
          description: >-
            Identificador de categoria do canal. Obrigatório quando `ResourceType=Autoparts` para filtrar pela lista
            oficial do canal.
      responses:
        '200':
          description: >-
            Array de recursos disponíveis (vazio quando nenhum recurso casa com o filtro, ou quando a categoria não
            suporta `Autoparts`).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubIntegrationResource'
    post:
      operationId: companyIntegrationResourcePost
      tags:
        - Hub — Recursos
      summary: Consulta valores do recurso no canal
      description: >-
        Atua como proxy para o serviço externo que consulta o canal de venda. Resolve o recurso cadastrado (identificado
        por IDTypeSalesChannelResource) e dispara um GET ao processo do canal enviando o conjunto de query params
        relevante para aquele recurso (categoria, marca, gênero, grade de tamanho, dados do anúncio, custos, restrições
        por veículo, etiqueta/coleta, etc.). O comportamento de cache da resposta é definido pelo cadastro do recurso,
        não por campo enviado pelo cliente: sem cache (sempre consulta o canal), com cache (busca a resposta armazenada
        e, em miss, consulta o canal e armazena por 3 dias) ou só-leitura de cache (usa a resposta armazenada,
        alimentada por outro processo).
      parameters:
        - name: idtypecompanyintegration
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Tipo de integração (canal).
        - name: IDTypeSalesChannelResource
          in: query
          required: true
          schema:
            type: integer
            format: int64
          description: >-
            Identificador do recurso cadastrado em `TypeSalesChannelResource` (vem do `GET
            /hub/resource/{idtypecompanyintegration}`).
        - name: IDHubProduct
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Produto Hub interno a que a consulta se refere (quando o recurso depende do produto).
        - name: IDHubAdvertisement
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Anúncio Hub interno (quando aplicável).
        - name: IDCompanyIntegration
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Integração específica da empresa a usar como credencial no canal.
        - name: CategoryId
          in: query
          required: false
          schema:
            type: string
          description: Identificador da categoria no canal — chave da lista para vários `ResourceType`.
        - name: CategoryName
          in: query
          required: false
          schema:
            type: string
          description: Nome da categoria no canal.
        - name: CatalogDomain
          in: query
          required: false
          schema:
            type: string
          description: Domínio de catálogo (Mercado Livre).
        - name: Brand
          in: query
          required: false
          schema:
            type: string
          description: Marca.
        - name: Gender
          in: query
          required: false
          schema:
            type: string
          description: Gênero (vestuário).
        - name: SizeChart
          in: query
          required: false
          schema:
            type: string
          description: Identificador da grade de tamanho.
        - name: GenderId
          in: query
          required: false
          schema:
            type: string
          description: Identificador do gênero no canal.
        - name: GridExternalId
          in: query
          required: false
          schema:
            type: string
          description: Identificador externo da grade.
        - name: IDHubProductSizeChart
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Grade de tamanho do produto Hub.
        - name: ProfitMargin
          in: query
          required: false
          schema:
            type: number
          description: Margem de lucro (cálculos de preço sugerido).
        - name: FixedProfit
          in: query
          required: false
          schema:
            type: number
          description: Lucro fixo (cálculos de preço sugerido).
        - name: OtherExpenses
          in: query
          required: false
          schema:
            type: number
          description: Outras despesas (cálculos de preço sugerido).
        - name: Cost
          in: query
          required: false
          schema:
            type: number
          description: Custo do produto (cálculos de preço sugerido).
        - name: Name
          in: query
          required: false
          schema:
            type: string
          description: Nome do produto/anúncio para sugestões.
        - name: Type
          in: query
          required: false
          schema:
            type: string
          description: Tipo (filtro genérico — depende do recurso).
        - name: BrandId
          in: query
          required: false
          schema:
            type: string
          description: Identificador da marca no canal (autopeças).
        - name: ModelId
          in: query
          required: false
          schema:
            type: string
          description: Identificador do modelo (autopeças).
        - name: YearId
          in: query
          required: false
          schema:
            type: string
          description: Ano (autopeças).
        - name: Filter
          in: query
          required: false
          schema:
            type: string
          description: Filtro textual (autopeças).
        - name: PowerId
          in: query
          required: false
          schema:
            type: string
          description: Potência (autopeças).
        - name: ShortVersionId
          in: query
          required: false
          schema:
            type: string
          description: Versão curta (autopeças).
        - name: EngineId
          in: query
          required: false
          schema:
            type: string
          description: Motor (autopeças).
        - name: FuelId
          in: query
          required: false
          schema:
            type: string
          description: Combustível (autopeças).
        - name: BodyTypeId
          in: query
          required: false
          schema:
            type: string
          description: Carroceria (autopeças).
        - name: TransmissionId
          in: query
          required: false
          schema:
            type: string
          description: Transmissão (autopeças).
        - name: GearId
          in: query
          required: false
          schema:
            type: string
          description: Câmbio (autopeças).
        - name: DoorsId
          in: query
          required: false
          schema:
            type: string
          description: Quantidade de portas (autopeças).
        - name: SteeringId
          in: query
          required: false
          schema:
            type: string
          description: Direção (autopeças).
        - name: TractionId
          in: query
          required: false
          schema:
            type: string
          description: Tração (autopeças).
        - name: ValvesId
          in: query
          required: false
          schema:
            type: string
          description: Quantidade de válvulas (autopeças).
        - name: Version
          in: query
          required: false
          schema:
            type: string
          description: Versão (autopeças).
        - name: Quantity
          in: query
          required: false
          schema:
            type: number
          description: Quantidade (recursos que dependem da quantidade — `ModeShipping`).
        - name: State
          in: query
          required: false
          schema:
            type: string
          description: UF (frete por região).
        - name: BuyerId
          in: query
          required: false
          schema:
            type: string
          description: Comprador (lista de modos de envio personalizados por comprador).
        - name: IDOrdersCarrierCollectionList
          in: query
          required: false
          schema:
            type: string
          description: >-
            Lista de romaneios de coleta (CSV de identificadores) repassada ao processo do canal — usada por recursos de
            etiqueta/coleta.
        - name: LabelFormat
          in: query
          required: false
          schema:
            type: string
          description: >-
            Formato da etiqueta solicitada ao canal (repassado como format ao processo) — aplicável a recursos de
            geração de etiqueta.
        - name: token
          in: query
          required: false
          schema:
            type: string
          description: >-
            Token de autorização repassado ao processo do canal. Normalmente vem do contexto autenticado; aceito também
            via query como fallback.
      responses:
        '200':
          description: >-
            Resposta opaca devolvida pelo processo do canal. Estrutura varia por `ResourceType`/canal — não há schema
            único.
          content:
            application/json:
              schema:
                type: object
                description: Payload opaco do processo — formato definido pelo canal.
        '400':
          description: |-
            Mensagens `[BadRequest]`:
            - `Integração não encontrada`
            - `Integracão não tem recurso`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Falha repassada pelo processo do canal. Corpo JSON traz `errorMessage` e `errorCode` originados do canal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorMessage:
                    type: string
                  errorCode:
                    type: string
                    nullable: true
                  errorHelp:
                    type: string
                    nullable: true
  /hub/notification:
    get:
      operationId: hubIntegrationNotificationList
      tags:
        - Hub — Notificações
      summary: Lista notificações de integração
      description: >-
        Retorna o feed de problemas de integração detectados (pedidos com falha de importação, SKUs com erro de
        sincronização, etc.), com paginação fixa de 5.000 registros por página. Só lista tipos com `Show=1` (problemas
        que devem aparecer para o operador). Ordem por `IDHubNotification` crescente.
      parameters:
        - name: Page
          in: query
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
          description: Página solicitada (0-indexada). Cada página tem 5.000 registros — o offset aplicado é `Page * 5000`.
      responses:
        '200':
          description: Array de notificações.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HubNotification'
  /hub/notification/{idhubnotification}:
    delete:
      operationId: hubIntegrationNotificationDelete
      tags:
        - Hub — Notificações
      summary: Marca notificação como resolvida (remove do feed)
      description: >-
        Apaga a notificação do feed da empresa. O sistema valida que a notificação pertence à empresa autenticada via
        `AccountName`.
      parameters:
        - name: idhubnotification
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador da notificação.
      responses:
        '200':
          description: >-
            Texto literal `sucesso` quando a remoção é concluída (também devolvido quando o id não existe — o `DELETE` é
            idempotente).
          content:
            application/json:
              schema:
                type: string
                example: sucesso
  /consumer/{idconsumer}/address:
    get:
      operationId: consumerAddressList
      summary: Lista os endereços do cliente
      description: Retorna todos os endereços ativos (`StatusAddress=1`) cadastrados para o cliente.
      tags:
        - Cadastro de Clientes
      parameters:
        - name: idconsumer
          in: path
          required: true
          schema:
            type: integer
            format: int32
          description: Identificador do cliente.
      responses:
        '200':
          description: Lista de endereços ativos. Pode vir vazia.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsumerAddress'
        '500':
          description: Erro interno. Prefixo `Error:`.
    post:
      operationId: consumerAddressPost
      summary: Cadastra um endereço para o cliente
      description: >-
        Cria um novo endereço. Para `IDCountry=1` (Brasil), o sistema consulta a base de CEP para resolver o código IBGE
        do município; sem retorno da consulta, o cadastro falha. Para `IDCountry` diferente de `1`, valida o país e
        força `ShippingState=EX` e `ShippingCity=EXTERIOR`. Inscrição estadual em Minas Gerais é normalizada com zeros à
        esquerda até 13 dígitos (exceto `ISENTO`). Atualiza `DateLastRecordModification` do cliente.
      tags:
        - Cadastro de Clientes
      parameters:
        - name: idconsumer
          in: path
          required: true
          schema:
            type: integer
            format: int32
          description: Identificador do cliente.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsumerAddressCreateBody'
        description: >-
          Endereço a cadastrar. Para Brasil (`IDCountry=1` ou omitido), `ShippingPostalCode`, `ShippingState`,
          `ShippingCity` e `ShippingStreet` são obrigatórios e o sistema resolve o código IBGE do município a partir do
          CEP. Para outros países, `ShippingState` e `ShippingCity` são forçados a `EX`/`EXTERIOR` e a consulta de CEP é
          pulada. Quando `ShippingState=MG` e `ConsumerStateInscription` não for `ISENTO`, o sistema preenche a
          inscrição estadual com zeros à esquerda até 13 dígitos.
      responses:
        '200':
          description: Endereço criado. Retorna o detalhe completo do cliente (mesmo shape de `GET /consumer/{idconsumer}`).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsumerDetail'
        '400':
          description: >-
            Validações: `[BadRequest] - Consumidor não existe` (cliente não pertence à empresa autenticada);
            `[BadRequest] - IDCountry não existe` (país informado não está cadastrado em `TypeCountry`).
        '500':
          description: >-
            `erro consultar cep` quando a consulta de CEP não retorna resultado. Demais erros internos com prefixo
            `Error:`.
  /consumer/{idconsumer}/address/{idaddress}:
    get:
      operationId: consumerAddressGet
      summary: Detalha um endereço do cliente
      description: Retorna os dados de um endereço específico. Só retorna endereços ativos (`StatusAddress=1`).
      tags:
        - Cadastro de Clientes
      parameters:
        - name: idconsumer
          in: path
          required: true
          schema:
            type: integer
            format: int32
          description: Identificador do cliente.
        - name: idaddress
          in: path
          required: true
          schema:
            type: integer
            format: int32
          description: Identificador do endereço.
      responses:
        '200':
          description: Endereço encontrado. Vem vazio quando não há endereço ativo com o id informado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsumerAddress'
        '500':
          description: Erro interno. Prefixo `Error:`.
    put:
      operationId: consumerAddressPut
      summary: Atualiza um endereço do cliente
      description: >-
        Atualização parcial — apenas os campos enviados são gravados. Quando `IDCountry` muda para um valor diferente de
        `1`, o sistema valida o país e força `ShippingState=EX` e `ShippingCity=EXTERIOR`. Para `IDCountry=1` (default
        quando omitido), dispara consulta de CEP para recalcular o código IBGE. Inscrição estadual em Minas Gerais é
        normalizada com zeros à esquerda até 13 dígitos. Atualiza `DateLastRecordModification` do cliente.
      tags:
        - Cadastro de Clientes
      parameters:
        - name: idconsumer
          in: path
          required: true
          schema:
            type: integer
            format: int32
          description: Identificador do cliente.
        - name: idaddress
          in: path
          required: true
          schema:
            type: integer
            format: int32
          description: Identificador do endereço.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsumerAddressUpdateBody'
        description: >-
          Atualização do endereço. Atualização parcial — só os campos enviados são alterados. Aceita também
          `ConsumerEmail` e `ConsumerTelephone` específicos do endereço. Mesmas regras de país, CEP e inscrição estadual
          do POST.
      responses:
        '200':
          description: Endereço atualizado. Retorna o detalhe completo do cliente.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsumerDetail'
        '400':
          description: >-
            Validações: `[BadRequest] - Endereço não existe` (endereço não pertence ao cliente ou à empresa
            autenticada); `[BadRequest] - País não existe`.
        '500':
          description: Mensagem retornada pela consulta de CEP quando ela falha. Demais erros com prefixo `Error:`.
    delete:
      operationId: consumerAddressDelete
      summary: Remove um endereço do cliente
      description: Marca o endereço como inativo (`StatusAddress=0`). O registro fica preservado para histórico de pedidos antigos.
      tags:
        - Cadastro de Clientes
      parameters:
        - name: idconsumer
          in: path
          required: true
          schema:
            type: integer
            format: int32
          description: Identificador do cliente.
        - name: idaddress
          in: path
          required: true
          schema:
            type: integer
            format: int32
          description: Identificador do endereço.
      responses:
        '200':
          description: >-
            Endereço removido. Retorna a lista atualizada de endereços ativos do cliente (mesmo shape de `GET
            /consumer/{idconsumer}/address`).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsumerAddress'
        '400':
          description: >-
            `[BadRequest] - Consumer Address não existe` quando o endereço não pertence ao cliente ou à empresa
            autenticada.
        '500':
          description: Erro interno. Prefixo `Error:`.
  /consumer/{idconsumer}/contact:
    post:
      operationId: consumerContactPost
      summary: Cadastra um contato para o cliente
      description: >-
        Cria um contato vinculado ao cliente. Aceita também a chave `ContactTelephon` (typo histórico) como fallback
        para `ContactTelephone`. Se `LegalRepresentative` não for enviado, é gravado como `0`.
      tags:
        - Cadastro de Clientes
      parameters:
        - name: idconsumer
          in: path
          required: true
          schema:
            type: integer
            format: int32
          description: Identificador do cliente.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsumerContactCreateBody'
        description: >-
          Contato a cadastrar. `ContactName` é obrigatório; demais campos (`ContactEmail`, `ContactTelephone`,
          `ContactResponsability`, `LegalRepresentative`) são opcionais. Por compatibilidade histórica, o campo
          `ContactTelephon` (sem o último `e`) também é aceito como fallback para `ContactTelephone`.
      responses:
        '200':
          description: Contato criado. Retorna o detalhe completo do cliente.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsumerDetail'
        '400':
          description: '`[BadRequest] - Consumidor não existe` quando o cliente não pertence à empresa autenticada.'
        '500':
          description: Erro interno. Prefixo `Error:`.
  /consumer/{idconsumer}/contact/{idconsumercontact}:
    put:
      operationId: consumerContactPut
      summary: Atualiza um contato do cliente
      description: Atualização parcial — apenas os campos enviados são gravados no banco.
      tags:
        - Cadastro de Clientes
      parameters:
        - name: idconsumer
          in: path
          required: true
          schema:
            type: integer
            format: int32
          description: Identificador do cliente.
        - name: idconsumercontact
          in: path
          required: true
          schema:
            type: integer
            format: int32
          description: Identificador do contato.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsumerContactUpdateBody'
        description: Atualização do contato. Atualização parcial — só os campos enviados são alterados.
      responses:
        '200':
          description: Contato atualizado. Retorna o detalhe completo do cliente.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsumerDetail'
        '400':
          description: '`[BadRequest] - Cliente não existe` quando o contato não pertence ao cliente ou à empresa autenticada.'
        '500':
          description: Erro interno. Prefixo `Error:`.
    delete:
      operationId: consumerContactDelete
      summary: Remove um contato do cliente
      description: Exclui fisicamente o contato.
      tags:
        - Cadastro de Clientes
      parameters:
        - name: idconsumer
          in: path
          required: true
          schema:
            type: integer
            format: int32
          description: Identificador do cliente.
        - name: idconsumercontact
          in: path
          required: true
          schema:
            type: integer
            format: int32
          description: Identificador do contato.
      responses:
        '200':
          description: Contato removido. Retorna o detalhe completo do cliente.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsumerDetail'
        '400':
          description: '`[BadRequest] - Consumidor não existe` quando o cliente não pertence à empresa autenticada.'
        '500':
          description: Erro interno. Prefixo `Error:`.
  /consumer/{idconsumer}/credit:
    post:
      operationId: consumerCreditPost
      summary: Cadastra um limite de crédito para o cliente
      description: >-
        Cria um limite de crédito vinculado a uma forma de pagamento. Cada cliente pode ter no máximo um crédito por
        forma de pagamento — tentar cadastrar uma segunda entrada na mesma forma é rejeitado. A operação é registrada no
        histórico de alterações do cliente (`ConsumerLog`).
      tags:
        - Cadastro de Clientes
      parameters:
        - name: idconsumer
          in: path
          required: true
          schema:
            type: integer
            format: int32
          description: Identificador do cliente.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsumerCreditBody'
        description: >-
          Limite de crédito a cadastrar. `IDTypePayment` e `CreditValue` são obrigatórios. Um cliente não pode ter dois
          créditos para a mesma forma de pagamento — o sistema bloqueia a duplicidade.
      responses:
        '200':
          description: Crédito cadastrado. Retorna o detalhe completo do cliente.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsumerDetail'
        '400':
          description: >-
            Validações: `[BadRequest] - Cliente não encontrado`; `[BadRequest] - Tipo Pagamento não cadastrado` (forma
            de pagamento não existe ou não pertence à empresa); `[BadRequest] - Já existe essa forma de crédito
            cadastrada para o cliente`.
        '500':
          description: Erro interno. Prefixo `Error:`.
  /consumer/{idconsumer}/credit/{idconsumercredit}:
    put:
      operationId: consumerCreditPut
      summary: Atualiza um limite de crédito do cliente
      description: >-
        Atualiza valor, forma de pagamento e condições comerciais do crédito. Não pode trocar `IDTypePayment` para uma
        forma já usada em outro crédito do mesmo cliente. A operação é registrada no histórico de alterações do cliente.
      tags:
        - Cadastro de Clientes
      parameters:
        - name: idconsumer
          in: path
          required: true
          schema:
            type: integer
            format: int32
          description: Identificador do cliente.
        - name: idconsumercredit
          in: path
          required: true
          schema:
            type: integer
            format: int32
          description: Identificador do registro de crédito.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsumerCreditBody'
        description: >-
          Atualização do crédito. Mesma estrutura do POST. `IDTypePayment` e `CreditValue` continuam obrigatórios;
          `CommercialConditions` é opcional.
      responses:
        '200':
          description: Crédito atualizado. Retorna o detalhe completo do cliente.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsumerDetail'
        '400':
          description: >-
            Validações: `[BadRequest] - Cliente não encontrado` (crédito não pertence ao cliente ou à empresa);
            `[BadRequest] - Tipo Pagamento não cadastrado`; `[BadRequest] - Já existe essa forma de crédito cadastrada
            para o cliente`.
        '500':
          description: Erro interno. Prefixo `Error:`.
    delete:
      operationId: consumerCreditDelete
      summary: Remove um limite de crédito do cliente
      description: >-
        Exclui o registro de crédito. A exclusão é registrada no histórico de alterações do cliente com o valor e a
        forma de pagamento removidos.
      tags:
        - Cadastro de Clientes
      parameters:
        - name: idconsumer
          in: path
          required: true
          schema:
            type: integer
            format: int32
          description: Identificador do cliente.
        - name: idconsumercredit
          in: path
          required: true
          schema:
            type: integer
            format: int32
          description: Identificador do registro de crédito.
      responses:
        '200':
          description: Crédito removido. Retorna o detalhe completo do cliente.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsumerDetail'
        '400':
          description: >-
            `[BadRequest] - Crédito cliente não encontrado` quando o crédito não pertence ao cliente ou à empresa
            autenticada.
        '500':
          description: Erro interno. Prefixo `Error:`.
  /consumer/{idconsumer}/voucher:
    get:
      operationId: consumerVoucherGet
      summary: Lista os movimentos de vale do cliente
      description: >-
        Retorna todos os movimentos de vale (entradas e saídas) do cliente, ordenados por data de gravação decrescente.
        Inclui o saldo acumulado por cliente + faturador (`BalanceValue`) calculado em janela ordenada.
      tags:
        - Cadastro de Clientes
      parameters:
        - name: idconsumer
          in: path
          required: true
          schema:
            type: integer
            format: int32
          description: Identificador do cliente.
        - name: IDCompanyInvoice
          in: query
          required: false
          schema:
            type: integer
            format: int32
          description: >-
            Filtra os movimentos pelo faturador (empresa que detém o saldo). Quando ausente, retorna movimentos de todos
            os faturadores do cliente.
      responses:
        '200':
          description: Lista de movimentos de vale.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsumerVoucher'
        '500':
          description: Erro interno. Prefixo `Error:`.
    post:
      operationId: consumerVoucherPost
      summary: Gera um vale para o cliente
      description: >-
        Registra um movimento de entrada (`IDTypeAccount=0`) — credita um vale a favor do cliente. O valor precisa ser
        numérico e estritamente positivo. Quando `IDCompanyInvoice` é informado e difere da empresa do cliente, o
        faturador é validado como faturador filho (`CompanyMain`); ausente, o vale é vinculado à própria empresa do
        cliente. A operação é registrada no histórico de alterações do cliente (`ConsumerLog`).
      tags:
        - Cadastro de Clientes
      parameters:
        - name: idconsumer
          in: path
          required: true
          schema:
            type: integer
            format: int32
          description: Identificador do cliente.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsumerVoucherCreateBody'
        description: >-
          Vale (movimento de entrada) a cadastrar. `Value` é obrigatório, numérico e estritamente positivo.
          `IDCompanyInvoice` é opcional — se omitido, o vale é creditado na empresa do cliente; se informado, precisa
          ser um faturador filho da empresa principal (`CompanyMain`). `Comments` é livre.
      responses:
        '200':
          description: >-
            Vale criado. Retorna a lista atualizada de movimentos de vale do cliente (mesmo shape de `GET
            /consumer/{idconsumer}/voucher`).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsumerVoucher'
        '400':
          description: >-
            Validações: `[BadRequest] - precisa informar um valor válido para gerar vale` (valor não numérico);
            `[BadRequest] - precisa informar um valor positivo para gerar vale`; `[BadRequest] - Cliente não existe`;
            `[BadRequest] - Faturador não existe`.
        '500':
          description: Erro interno. Prefixo `Error:`.
  /consumer/{idconsumer}/voucher/{idconsumervoucher}:
    delete:
      operationId: consumerVoucherDelete
      summary: Remove um vale do cliente
      description: >-
        Exclui um movimento de vale. **Não permite exclusão** quando o valor do vale já foi (parcial ou totalmente)
        utilizado — o saldo disponível do cliente precisa cobrir o valor a remover, considerando todos os movimentos
        (entradas menos saídas). A exclusão é registrada no histórico de alterações do cliente; o `Comments` enviado
        entra no log.
      tags:
        - Cadastro de Clientes
      parameters:
        - name: idconsumer
          in: path
          required: true
          schema:
            type: integer
            format: int32
          description: Identificador do cliente.
        - name: idconsumervoucher
          in: path
          required: true
          schema:
            type: integer
            format: int32
          description: Identificador do movimento de vale.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsumerVoucherDeleteBody'
        description: Corpo opcional com `Comments` — texto livre registrado no log de exclusão do vale.
      responses:
        '200':
          description: Vale removido. Retorna a lista atualizada de movimentos de vale do cliente.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsumerVoucher'
        '400':
          description: >-
            Validações: `[BadRequest] - Vale cliente não existe`; `[BadRequest] - Vale não pode ser excluido pois já
            teve seu valor (parcial ou total) utilizado`.
        '500':
          description: Erro interno. Prefixo `Error:`.
  /consumer/{idconsumer}/salesman:
    post:
      operationId: consumerSalesmanPost
      summary: Vincula um vendedor ao cliente
      description: >-
        Associa um vendedor (`IDAcess` ativo da mesma empresa do cliente) ao cliente. A combinação cliente + vendedor é
        única; um vínculo já existente é atualizado em vez de duplicado (upsert). A operação é registrada no histórico
        de alterações do cliente.
      tags:
        - Cadastro de Clientes
      parameters:
        - name: idconsumer
          in: path
          required: true
          schema:
            type: integer
            format: int32
          description: Identificador do cliente.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsumerSalesmanBody'
        description: >-
          Vínculo cliente–vendedor a cadastrar. `IDAcess` é obrigatório e identifica o vínculo usuário–empresa
          (`IDAcess`) do vendedor — precisa estar ativo e pertencer à mesma empresa do cliente. A combinação `IDConsumer
          + IDAcess` é única; um vínculo já existente é preservado/atualizado (upsert).
      responses:
        '200':
          description: Vínculo registrado. Retorna o detalhe completo do cliente.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsumerDetail'
        '400':
          description: >-
            Validações: `[BadRequest] - Cliente não existe`; `[BadRequest] - Vendedor não existe` (`IDAcess` não
            pertence à empresa do cliente ou o vínculo `UserCompany` está inativo).
        '500':
          description: Erro interno. Prefixo `Error:`.
  /consumer/{idconsumer}/salesman/{idconsumersalesman}:
    delete:
      operationId: consumerSalesmanDelete
      summary: Remove o vínculo de vendedor do cliente
      description: >-
        Exclui o vínculo cliente-vendedor. A operação é registrada no histórico de alterações do cliente, incluindo o
        login do vendedor removido.
      tags:
        - Cadastro de Clientes
      parameters:
        - name: idconsumer
          in: path
          required: true
          schema:
            type: integer
            format: int32
          description: Identificador do cliente.
        - name: idconsumersalesman
          in: path
          required: true
          schema:
            type: integer
            format: int32
          description: Identificador do vínculo cliente-vendedor.
      responses:
        '200':
          description: Vínculo removido. Retorna o detalhe completo do cliente.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsumerDetail'
        '400':
          description: >-
            `[BadRequest] - Vendedor associado ao cliente não existe` quando o vínculo não pertence ao cliente ou à
            empresa autenticada.
        '500':
          description: Erro interno. Prefixo `Error:`.
  /user/signin/local:
    post:
      operationId: UserSigninLocal
      tags:
        - Autenticação
      summary: Login por email/CPF/CNPJ e senha
      description: >-
        Endpoint público. Autentica o usuário na conta identificada pelo subdomínio. Aceita login por email ou por
        CPF/CNPJ no mesmo campo `email`. Aplica regras de expiração de senha (parametrização `Validade da Senha
        (Dias)`), bloqueio temporário após 3 tentativas falhas (10 minutos) e MFA quando habilitado para o usuário
        (`MFAEnabled`). Em MFA `email`, dispara o envio de um código de 6 dígitos (válido por 5 minutos); em MFA `totp`,
        valida o código informado em `mfacode` ou retorna a URL de cadastro `OtpAuthUrl` quando o segredo ainda não foi
        gerado. Email com domínio `@idworks.com.br` tem acesso a todas as contas (exceto a conta `idw`).
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserSigninLocalBody'
        description: >-
          Endpoint público. `email` (aceita `Login` email ou CPF/CNPJ — o sistema detecta o formato) e `password` são
          obrigatórios. `mfacode` é obrigatório apenas quando o usuário tem MFA habilitado (6 dígitos por email ou
          código atual do Google Authenticator). `expireinhour` (ex.: `12h`, `7d`) define a expiração do JWT — default
          `14h`.
      responses:
        '200':
          description: >-
            Login concluído ou desafio de MFA emitido. Conforme o estado, o corpo é um `UserSigninResponse` (sucesso,
            com `token` JWT) ou um `UserSigninMFAChallenge` (cadastro/desafio de MFA pendente).
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/UserSigninResponse'
                  - $ref: '#/components/schemas/UserSigninMFAChallenge'
        '400':
          description: |-
            Requisição inválida. Mensagens conhecidas:
            - `[BadRequest] - Login informado não é um email válido nem documento`
            - `[BadRequest] - Erro ao enviar código por email`
            - `[BadRequest] - Erro ao validar expiração de senha`
            - `[BadRequest] - Retornar em instantes` (sistema temporariamente travado).
        '404':
          description: '`[NotFound] Verificar usuário, senha e subdomíno (url)` — usuário sem senha cadastrada.'
  /user/workingday/workscale:
    get:
      operationId: userWorkScaleList
      tags:
        - Jornada de Trabalho
      summary: Lista as escalas de trabalho da empresa
      description: >-
        Retorna as escalas de trabalho cadastradas, cada uma com a lista de turnos (`WorkShift`) — dia da semana,
        horário de início e fim. Aceita filtro opcional por uma escala específica.
      parameters:
        - name: IDUserWorkScale
          in: query
          required: false
          schema:
            type: integer
            format: int32
          description: Identificador da escala. Quando informado, restringe a resposta a essa escala.
      responses:
        '200':
          description: Lista de escalas. Retorna `[]` quando não houver registros.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserWorkScale'
    post:
      operationId: userWorkScalePost
      tags:
        - Jornada de Trabalho
      summary: Cadastra uma nova escala de trabalho
      description: >-
        Cria uma escala vinculada à empresa autenticada. O nome precisa ser único dentro da empresa. Após a criação,
        devolve a escala recém-cadastrada já enriquecida com a lista de turnos (vazia neste momento).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserWorkScaleCreateBody'
        description: >-
          Escala a cadastrar. Apenas `UserWorkScaleName` é obrigatório — o nome precisa ser único dentro da empresa. A
          escala nasce sem turnos; use `POST /user/workingday/workscale/shift` para defini-los.
      responses:
        '200':
          description: Escala cadastrada. Retorna a escala recém-criada conforme o formato de `GET /user/workingday/workscale`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserWorkScale'
        '400':
          description: |-
            Mensagens conhecidas:
            - `[BadRequest] - Escala já existe`
            - `[BadRequest] - Erro ao adicionar escala`
            - `[BadRequest] - Empresa não existe`.
  /user/workingday/workscale/shift:
    post:
      operationId: userWorkShiftPost
      tags:
        - Jornada de Trabalho
      summary: Substitui os turnos de uma escala
      description: >-
        Apaga todos os turnos atuais da escala informada e insere os turnos enviados em `shifts` no lugar — operação de
        substituição em bloco, não incremental. Cada turno define dia da semana `WeekDay` (0=domingo a 6=sábado),
        horário de início `StartTime` e horário de fim `FinishTime`. Após a gravação, devolve a escala atualizada com os
        novos turnos.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserWorkShiftCreateBody'
        description: >-
          Substituição em bloco dos turnos da escala. `IDUserWorkScale` identifica a escala; `shifts` é a lista completa
          dos turnos novos — o sistema apaga os turnos atuais e insere estes no lugar. Cada turno informa `WeekDay` (0
          domingo a 6 sábado), `StartTime` e `FinishTime` (`HH:mm:ss`).
      responses:
        '200':
          description: Turnos gravados. Retorna a escala atualizada conforme o formato de `GET /user/workingday/workscale`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserWorkScale'
        '400':
          description: |-
            Mensagens conhecidas:
            - `[BadRequest] - Escala não existe`
            - `[BadRequest] - Preencha corretamente os campos Dia da semana, horário de início/fim e escala`
            - `[BadRequest] - Preencha corretamente o dia da semana`.
  /user/workingday/workscale/{iduserworkscale}:
    put:
      operationId: userWorkScalePut
      tags:
        - Jornada de Trabalho
      summary: Renomeia uma escala de trabalho
      description: Altera o nome da escala. O novo nome precisa ser único na empresa.
      parameters:
        - name: iduserworkscale
          in: path
          required: true
          schema:
            type: integer
            format: int32
          description: Identificador da escala a renomear.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserWorkScaleUpdateBody'
        description: Renomeia a escala. `UserWorkScaleName` é obrigatório e precisa ser único dentro da empresa.
      responses:
        '200':
          description: Escala atualizada. Retorna a escala conforme o formato de `GET /user/workingday/workscale`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserWorkScale'
        '400':
          description: |-
            Mensagens conhecidas:
            - `[BadRequest] - Preencha corretamente o nome da escala`
            - `[BadRequest] - Escala já existente com esse nome`
            - `[BadRequest] - Escala não existe`
            - `[BadRequest] - Escala não atualizada`.
    delete:
      operationId: userWorkScaleDelete
      tags:
        - Jornada de Trabalho
      summary: Exclui uma escala de trabalho
      description: Remove a escala e seus turnos. Só é permitido excluir escalas que não estejam vinculadas a nenhum colaborador.
      parameters:
        - name: iduserworkscale
          in: path
          required: true
          schema:
            type: integer
            format: int32
          description: Identificador da escala a excluir.
      responses:
        '200':
          description: Escala excluída.
          content:
            application/json:
              schema:
                type: string
                example: Escala excluída com sucesso
        '400':
          description: |-
            Mensagens conhecidas:
            - `[BadRequest] - Informe corretamente a escala`
            - `[BadRequest] - Há colaboradores com essa escala, altere antes de excluir`
            - `[BadRequest] - Escala não existe`.
  /user/notification:
    get:
      operationId: userNotificationGet
      tags:
        - Notificações de Versão
      summary: Lista as novidades da versão atual do sistema
      description: >-
        Retorna a versão `Current = 1` do sistema com as novidades publicadas (`Updates`). Cada item traz se já foi
        confirmado pelo usuário autenticado (campo `Confirm`).
      responses:
        '200':
          description: Versão atual e suas novidades. Retorna `[]` quando não houver versão marcada como atual.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserNotification'
  /user/notification/{idsystemversionupdate}:
    delete:
      operationId: userNotificationDelete
      tags:
        - Notificações de Versão
      summary: Marca uma novidade como vista pelo usuário
      description: >-
        Registra a confirmação de leitura de uma novidade pelo usuário autenticado (não apaga a novidade em si). Em
        chamadas seguintes ao `GET /user/notification`, o item passa a vir com `Confirm = 1`.
      parameters:
        - name: idsystemversionupdate
          in: path
          required: true
          schema:
            type: integer
            format: int32
          description: Identificador da novidade a confirmar.
      responses:
        '200':
          description: Confirmação registrada.
          content:
            application/json:
              schema:
                type: string
                example: sucesso
  /user/company:
    get:
      operationId: userCompanyGet
      tags:
        - Cadastro de Usuários
      summary: Lista as empresas vinculadas ao usuário autenticado
      description: >-
        Retorna as empresas (vínculo `UserCompany`) às quais o usuário autenticado tem acesso, ordenadas por
        `AccountName`.
      responses:
        '200':
          description: Lista de vínculos do usuário com empresas.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserCompany'
        '400':
          description: '`[BadRequest] - não encontrado` — nenhum vínculo localizado.'
  /user/company-invoice:
    get:
      operationId: userCompanyInvoiceGet
      tags:
        - Cadastro de Usuários
      summary: Lista as empresas faturadoras vinculadas ao usuário
      description: >-
        Retorna as empresas faturadoras (`UserCompanyInvoice`) às quais o usuário autenticado tem acesso, dentro do
        grupo da empresa identificada pelo subdomínio.
      responses:
        '200':
          description: Lista de empresas faturadoras. Retorna `[]` quando não houver vínculos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserCompanyInvoice'
  /user/menu:
    get:
      operationId: userMenuGet
      tags:
        - Cadastro de Usuários
      summary: Monta o menu lateral do usuário
      description: >-
        Retorna os grupos de módulos visíveis ao usuário autenticado, considerando os privilégios do perfil de acesso
        atribuído. Cada grupo traz seus módulos e, em `Version = 2`, também submódulos aninhados (estrutura hierárquica
        `Module` dentro de `Module`). Quando `Version` é diferente de `2`, devolve apenas o primeiro nível.
      parameters:
        - name: Version
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
              - 2
          description: >-
            Versão do formato. `2` inclui submódulos aninhados em cada item; qualquer outro valor retorna apenas o
            primeiro nível.
      responses:
        '200':
          description: Lista de grupos de módulos com seus módulos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserMenuGroup'
        '400':
          description: '`[BadRequest] - Usuário não encontrado`.'
  /user/privilege:
    get:
      operationId: userPrivilegeGet
      tags:
        - Cadastro de Usuários
      summary: Retorna os privilégios do usuário ou recria os dados de login
      description: >-
        Por padrão (`LoginData` ausente ou diferente de `1`), devolve a lista de perfis de acesso (`UserPrivilegeGroup`)
        da empresa com os módulos e privilégios de cada um, restritos ao que o usuário enxerga. Quando `LoginData=1`,
        recria o corpo de login do usuário autenticado — útil para o frontend reidratar a sessão com dados frescos
        (informações da empresa, tokens de helpdesk, parâmetros da integração de notificações).
      parameters:
        - name: LoginData
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Quando `1`, retorna o corpo de login (`UserLoginPayload`) em vez da lista de perfis. Default `0`.
      responses:
        '200':
          description: 'Conforme `LoginData`: lista de perfis (`UserPrivilegeGroup[]`) ou objeto `UserLoginPayload`.'
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/UserPrivilegeGroup'
                  - $ref: '#/components/schemas/UserLoginPayload'
        '400':
          description: |-
            Mensagens conhecidas:
            - `[BadRequest] - Usuário precisa estar logado`
            - `[BadRequest] - Usuário não encontrado`.
  /tax:
    get:
      operationId: taxList
      summary: Lista os departamentos fiscais ativos
      description: >-
        Retorna os departamentos fiscais (cadastro hierárquico que agrupa as regras tributárias dos SKUs) com filtros
        opcionais por identificador, nome e empresa. Limite máximo de 2000 registros por chamada.


        Quando o contexto autenticado indica `accountname=all`, a lista cobre todas as empresas relacionadas; caso
        contrário, restringe à empresa do subdomínio.
      tags:
        - Departamentos Tributários
      parameters:
        - name: IDTaxDepartment
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por identificador do departamento fiscal.
        - name: TaxDepartmentDescription
          in: query
          required: false
          schema:
            type: string
          description: Filtra por nome exato do departamento fiscal.
        - name: Status
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
            default: 1
          description: Filtra por situação. `1` (default) retorna apenas departamentos ativos.
      responses:
        '200':
          description: Lista de departamentos fiscais.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TaxDepartmentSummary'
    post:
      operationId: taxPost
      summary: Cria um departamento fiscal
      description: >-
        Cria um novo departamento fiscal associado à empresa autenticada e retorna o registro completo já com o array de
        regras `Cfop` (vazio neste momento), usando a mesma estrutura do detalhe.


        O nome `TaxDepartmentDescription` deve ser único entre os departamentos ativos da empresa.
      tags:
        - Departamentos Tributários
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaxDepartmentCreateBody'
        description: >-
          Dados do departamento fiscal a cadastrar. Apenas `TaxDepartmentDescription` (máx. 100) — o nome precisa ser
          único entre os departamentos ativos da empresa.
      responses:
        '200':
          description: Departamento fiscal criado. Retorna o detalhe completo, no mesmo shape de `GET /tax/{idtaxdepartment}`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TaxDepartmentDetail'
        '400':
          description: >-
            Validação ou conflito. Mensagens (prefixo `[BadRequest]`): `Empresa não existe`; `Já existe um departamento
            fiscal com este nome`.
  /tax/{idtaxdepartment}:
    parameters:
      - name: idtaxdepartment
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do departamento fiscal.
    get:
      operationId: taxGet
      summary: Retorna o detalhe de um departamento fiscal
      description: >-
        Retorna o departamento fiscal junto do array `Cfop[]` com todas as regras fiscais federais já configuradas
        (PIS/COFINS, IPI saída e entrada, IBS/CBS, CFOPs por direção e estado, switches da regra). As regras ICMS por
        estado de cada CFOP devem ser obtidas via `GET /tax/{idtaxdepartment}/cfop/{idtax}`.


        Filtro opcional `IDCompany` restringe os CFOPs aos da filial informada (cenário multi-CNPJ).
      tags:
        - Departamentos Tributários
      parameters:
        - name: IDCompany
          in: query
          required: false
          schema:
            type: integer
          description: Restringe os CFOPs retornados aos cadastrados na filial informada.
      responses:
        '200':
          description: Detalhe do departamento fiscal.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TaxDepartmentDetail'
    put:
      operationId: taxPut
      summary: Atualiza o nome de um departamento fiscal
      description: >-
        Altera o nome do departamento fiscal. Mantém a unicidade do nome entre os departamentos ativos da empresa. Após
        a atualização, retorna a lista completa de departamentos ativos (mesmo shape de `GET /tax`).
      tags:
        - Departamentos Tributários
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaxDepartmentUpdateBody'
        description: >-
          Novo nome do departamento. Mesma regra de unicidade do POST: `TaxDepartmentDescription` único entre os
          departamentos ativos da empresa autenticada.
      responses:
        '200':
          description: Departamento atualizado. Retorna a lista de departamentos da empresa.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TaxDepartmentSummary'
        '400':
          description: >-
            Validação ou conflito. Mensagens (prefixo `[BadRequest]`): `Departamento fiscal não existe`; `Já existe um
            departamento fiscal com este nome`.
    delete:
      operationId: taxDelete
      summary: Inativa um departamento fiscal
      description: >-
        Inativa o departamento fiscal (soft delete via `Status=0`). A exclusão é bloqueada quando o departamento está em
        uso: vinculado a algum SKU ou referenciado pela regra fiscal de um Tipo de Pedido.


        Retorna a lista atualizada de departamentos ativos da empresa.
      tags:
        - Departamentos Tributários
      responses:
        '200':
          description: Departamento inativado. Retorna a lista de departamentos ativos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TaxDepartmentSummary'
        '400':
          description: >-
            Bloqueado por uso ou departamento inexistente. Mensagens (prefixo `[BadRequest]`): `Departamento fiscal não
            existe`; `Departamento fiscal esta em alguns SKUs, remover o departamento do SKU antes de deletar`;
            `Depatarmento fiscal esta na regra fiscal do tipo de pedido: "<TipoPedido>" (<id>)`.
  /tax/{idtaxdepartment}/cfop:
    parameters:
      - name: idtaxdepartment
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do departamento fiscal.
    post:
      operationId: taxCfopPost
      summary: Cria uma regra fiscal (CFOP) dentro de um departamento
      description: >-
        Cria uma regra fiscal federal dentro do departamento. A regra agrupa PIS/COFINS de saída e entrada, IPI
        (saída/entrada), IBS/CBS, os quatro CFOPs por direção e estado (dentro/fora do estado) e diversos switches que
        reconfiguram o cálculo (consumidor final `NfeindFinal`, contribuinte `NfeTaxPayer`, bonificação `Gratification`,
        cálculo reverso `ReverseTaxCalculation`, exportação `NfeExport`, emissão de NFCe `IssueNFCe`).


        Validações principais: alíquotas de PIS e COFINS limitadas a 50%; os CSTs de PIS e COFINS são obrigatórios; cada
        CFOP é validado contra o cadastro `NfCfop` e quanto ao primeiro dígito (saída no estado começa com 5 ou 7; saída
        fora do estado com 6; entrada no estado com 1 ou 3; entrada fora do estado com 2); enquadramento de IPI
        `IpiCEnq` é exigido em faixas específicas para CSTs `02/52` (300–399), `04/54` (0–99) e `05/55` (100–199);
        quando `IDNfCstIbsCbs` é informado, a classificação IBS/CBS precisa existir.


        Retorna o detalhe da regra recém-criada (mesmo shape de `GET /tax/{idtaxdepartment}/cfop/{idtax}`), com o array
        `Icms[]` ainda vazio.
      tags:
        - Departamentos Tributários
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaxCfopCreateBody'
        description: >-
          Regra fiscal (CFOP) federal a cadastrar no departamento. `PisCst`, `CofinsCst` e `IDCompanyBranch` (filial
          emissora) são obrigatórios; alíquotas de PIS/COFINS são limitadas a 50%. Os 4 CFOPs (saída no estado/fora do
          estado, entrada no estado/fora do estado) são opcionais; quando informados, o primeiro dígito tem que casar
          com a direção (saída no estado: `5`/`7`, saída fora: `6`, entrada no estado: `1`/`3`, entrada fora: `2`) e o
          CFOP precisa existir em `NfCfop`. `IpiCst` exige enquadramento `IpiCEnq` coerente com o CST (`02`/`52` entre
          300–399, `04`/`54` entre 0–99, `05`/`55` entre 100–199); sem `IpiCst`, `IpiAliquot` e `IpiCEnq` ficam nulos.
          `IDNfCstIbsCbs` quando informado é validado contra `NfCstIbsCbs`.
      responses:
        '200':
          description: Regra fiscal criada. Retorna o detalhe completo.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TaxCfopDetail'
        '400':
          description: >-
            Validação ou conflito. Mensagens (prefixo `[BadRequest]`): `Alíquota de PIS não pode ser maior que 50%`;
            `Alíquota de COFINS não pode ser maior que 50%`; `Precisa informa o CST PIS`; `Precisa informa o CST
            COFINS`; `CFOP de saída dentro do estado <Cfop> não incia com 5`; `CFOP de saída fora do estado <Cfop> não
            incia com 6`; `CFOP de entrada dentro do estado <Cfop> não incia com 1`; `CFOP de entrada fora do estado
            <Cfop> não incia com 2`; `CFOP de <direção> <Cfop> não existe`; `IPI CST 02 e 52 deve ter o enquadramento
            entre 300 e 399`; `IPI CST 04 e 54 deve ter o enquadramento entre 0 e 99`; `IPI CST 05 e 55 deve ter o
            enquadramento entre 100 e 199`; `Classificação IBS/CBS não encontrada`; `Departamento fiscal não existe`.
  /tax/{idtaxdepartment}/cfop/{idtax}:
    parameters:
      - name: idtaxdepartment
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do departamento fiscal.
      - name: idtax
        in: path
        required: true
        schema:
          type: integer
        description: Identificador da regra fiscal (CFOP) dentro do departamento.
    get:
      operationId: taxCfopGet
      summary: Retorna o detalhe de uma regra fiscal (CFOP) com suas regras ICMS por estado
      description: >-
        Retorna a regra fiscal completa: campos federais (PIS/COFINS saída e entrada, IPI saída e entrada, IBS/CBS), os
        quatro CFOPs por direção/estado com descrição resolvida e o array `Icms[]` com todas as regras ICMS por estado
        destino já configuradas para essa regra (cada item traz CST ICMS, alíquota, base de cálculo, ICMS ST, FCP, DIFAL
        e os campos de override por estado).
      tags:
        - Departamentos Tributários
      responses:
        '200':
          description: Detalhe da regra fiscal.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TaxCfopDetail'
    put:
      operationId: taxCfopPut
      summary: Atualiza uma regra fiscal (CFOP)
      description: >-
        Atualiza os campos federais da regra fiscal. Aceita atualização parcial — campos não enviados ficam inalterados,
        e strings vazias em `PisCstInbound` / `CofinsCstInbound` são interpretadas como remoção do CST de entrada.


        Aplica as mesmas validações do `POST` (limite de 50% em PIS/COFINS, validade do CFOP por dígito inicial e
        cadastro, faixas do enquadramento IPI, classificação IBS/CBS existente).


        Quando a regra é marcada como `Standard=1` em conjunto com `NfeindFinal`, `NfeTaxPayer`, `IssueNFCe` e
        `Gratification`, o sistema bloqueia a alteração se já houver outra regra padrão no mesmo departamento cobrindo
        estado destino igual a uma das regras ICMS deste CFOP (impede duplicidade de regra principal por estado).


        Retorna o detalhe atualizado (mesmo shape do `GET`).
      tags:
        - Departamentos Tributários
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaxCfopUpdateBody'
        description: >-
          Atualização parcial da regra fiscal — mesmos campos do POST, todos opcionais; os ausentes mantêm o valor
          atual. Mantém as mesmas validações de PIS/COFINS (≤ 50%), de coerência IPI CST/Enq, dígito inicial dos CFOPs
          por direção e existência do CFOP em `NfCfop`. `IDNfCstIbsCbs` segue validado contra `NfCstIbsCbs`.
      responses:
        '200':
          description: Regra fiscal atualizada. Retorna o detalhe completo.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TaxCfopDetail'
        '400':
          description: >-
            Validação ou conflito. Mensagens (prefixo `[BadRequest]`): mesmas do `POST`, mais `Departamento fiscal não
            existe`; `O estado <UF> já tem regra configurada em outro departamento PRINCIPAL: <Nome> e não pode
            duplicar.`.
    delete:
      operationId: taxCfopDelete
      summary: Remove uma regra fiscal (CFOP)
      description: >-
        Remove a regra fiscal do departamento. A exclusão é bloqueada quando a regra está atrelada à regra fiscal de
        algum Tipo de Pedido.


        Retorna o detalhe do departamento pai após a exclusão (mesmo shape de `GET /tax/{idtaxdepartment}`).
      tags:
        - Departamentos Tributários
      responses:
        '200':
          description: Regra fiscal removida. Retorna o detalhe atualizado do departamento.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TaxDepartmentDetail'
        '400':
          description: >-
            Bloqueado por uso ou registro inexistente. Mensagens (prefixo `[BadRequest]`): `Tipo imposto não existe`;
            `Regra fiscal esta atrelada ao tipo de pedido <TipoPedido> e não pode ser excluida`.
  /tax/{idtaxdepartment}/cfop/{idtax}/interstate:
    parameters:
      - name: idtaxdepartment
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do departamento fiscal.
      - name: idtax
        in: path
        required: true
        schema:
          type: integer
        description: Identificador da regra fiscal (CFOP).
    post:
      operationId: taxInterstatePost
      summary: Cria uma regra ICMS por estado destino
      description: >-
        Cria uma regra ICMS para um estado destino dentro de uma regra fiscal (CFOP). A regra define ICMS próprio, ICMS
        ST, FCP (Fundo de Combate à Pobreza), DIFAL e overrides de CFOP/comentários para o estado em questão.


        O CST ICMS controla quais campos são obrigatórios; o sistema aplica regras específicas por CST:

        - `00` (Tributada integralmente): exige `IcmsModBC`, `IcmsAliquot`, `FecpAliquot`; limpa campos de ST e
        diferimento.

        - `10` (Tributada com ST): exige também `IcmsModBCST`; se `IcmsSTAliquot` não vier, copia `IcmsAliquot`.

        - `20` (Redução de base): exige `IcmsPRedBC` maior que zero; limpa ST e diferimento.

        - `30` (Isenta com ST): exige `IcmsModBCST` e `FecpAliquot`; limpa redução e modalidade BC.

        - `40`, `41`, `50`, `60` (isenções e ICMS recolhido por ST): zera os demais campos de ICMS, redução, ST e DIFAL.

        - `51` (Diferimento): exige `IcmsModBC`, `IcmsAliquot` e `FecpAliquot`; limpa campos de ST.

        - `70` (Redução com ST): exige `IcmsPRedBC` maior que zero, `IcmsModBC` e `IcmsModBCST` válidos.


        Validações comuns: alíquotas (`IcmsAliquot`, `FecpAliquot`, `IcmsDifalPRedBC`) devem ficar entre 0 e 100%
        (`0`–`1` em decimal). O CST informado precisa existir em `NfCstIcms` para o regime tributário da empresa. Não
        pode haver outra regra para o mesmo `StateTo` dentro da mesma regra fiscal. Quando o CFOP é `Standard=1`, o
        estado destino não pode coincidir com um estado já configurado em outro CFOP padrão do mesmo departamento
        (impede duplicidade da regra principal por estado).


        Retorna o registro criado já com descrições resolvidas (modalidades de BC, CST, UF).
      tags:
        - Departamentos Tributários
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaxInterstateCreateBody'
        description: >-
          Regra de ICMS por estado destino vinculada a uma regra fiscal (CFOP). `StateTo` obrigatório e único por regra
          (não é permitido duplicar a UF). O conjunto de campos exigidos depende do `IcmsCst`: `00`/`10`/`20`/`51`/`70`
          exigem `IcmsModBC` (0–3) e `IcmsAliquot` (0–100%); `10`/`30`/`70` exigem ainda `IcmsModBCST` (0–6); `20`/`70`
          exigem `IcmsPRedBC`. CSTs `40`/`41`/`50`/`60` zeram automaticamente os campos de cálculo. `FecpAliquot` (≤
          100%) é obrigatória sempre que houver tributação. `IcmsDifalPRedBC` ≤ 100%. `IcmsSTAliquot` herda de
          `IcmsAliquot` quando não informado.
      responses:
        '200':
          description: Regra ICMS criada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TaxInterstate'
        '400':
          description: >-
            Validação. Mensagens (prefixo `[BadRequest]`): `Precisa selecionar o Mod Base Cal ICMS válido`; `Precisa
            informar alíquota ICMS`; `Alíquota ICMS precisa ser entre 0 e 100%`; `Precisa informar alíquota ICMS Fundo
            Pobreza`; `Alíquota ICMS Fundo Pobreza precisa ser entre 0 e 100%`; `Redução BC ICMS DIFAL precisa ser entre
            0 e 100%`; `Redução BC ICMS precisa ser entre 0 e 100%`; `Precisa selecionar o Mod Base Cal ICMS ST válido
            (0,1,2,3,4,5,6)`; `Precisa selecionar o Mod Base Cal ICMS ST válido`; `ICMS CST é inválido. Verificar regime
            tributário da empresa`; `Configuração ja preenchida para estado: <UF>`; `Departamento fiscal não existe`; `O
            estado <UF> já tem regra configurada em outro departamento PRINCIPAL: <Nome> e não pode duplicar.`.
  /tax/{idtaxdepartment}/cfop/{idtax}/interstate/{idtaxinterstate}:
    parameters:
      - name: idtaxdepartment
        in: path
        required: true
        schema:
          type: integer
        description: Identificador do departamento fiscal.
      - name: idtax
        in: path
        required: true
        schema:
          type: integer
        description: Identificador da regra fiscal (CFOP).
      - name: idtaxinterstate
        in: path
        required: true
        schema:
          type: integer
        description: Identificador da regra ICMS por estado.
    put:
      operationId: taxInterstatePut
      summary: Atualiza uma regra ICMS por estado destino
      description: >-
        Atualiza a regra ICMS por estado destino. Mesmas validações por CST, alíquotas e limites do `POST`. Ao trocar o
        `StateTo`, o sistema verifica novamente se não há duplicidade contra outras regras (do mesmo CFOP e, quando o
        CFOP é `Standard=1`, contra outros CFOPs padrão do departamento).


        Campos textuais como `ItemCommentsInvoice` e `IcmsPMVAST*` mantêm o valor anterior quando omitidos no body.


        Retorna o registro atualizado com descrições resolvidas (modalidades de BC, CST, UF).
      tags:
        - Departamentos Tributários
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaxInterstateUpdateBody'
        description: >-
          Atualização parcial da regra de ICMS por estado — mesmos campos do POST, todos opcionais. Mantém as mesmas
          validações por `IcmsCst` (campos obrigatórios variam com o CST informado) e os mesmos limites de 0–100% para
          alíquotas e reduções de base de cálculo.
      responses:
        '200':
          description: Regra ICMS atualizada.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TaxInterstate'
        '400':
          description: Validação. Mesmas mensagens do `POST` (prefixo `[BadRequest]`).
    delete:
      operationId: taxInterstateDelete
      summary: Remove uma regra ICMS por estado destino
      description: >-
        Remove a regra ICMS de um estado destino dentro de uma regra fiscal (CFOP). Retorna o detalhe do departamento
        pai (mesmo shape de `GET /tax/{idtaxdepartment}`).
      tags:
        - Departamentos Tributários
      responses:
        '200':
          description: Regra ICMS removida. Retorna o detalhe atualizado do departamento.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TaxDepartmentDetail'
        '400':
          description: 'Registro não localizado. Mensagem (prefixo `[BadRequest]`): `IDTaxDepartment não existe`.'
  /invoice/danfe:
    get:
      operationId: orderInvoiceGet
      summary: Gera o DANFE (PDF) ou retorna o XML de uma nota fiscal
      description: >-
        Gera dinamicamente o documento auxiliar da nota fiscal (DANFE em PDF) a partir do XML da nota, ou devolve o
        próprio XML quando `Type=XML`. O endpoint cobre vários cenários — NF-e modelo 55, NFCe modelo 65, CFe-SAT modelo
        59, e eventos de NF-e (carta de correção, inutilização e cancelamento), escolhendo o renderizador adequado
        conforme o modelo fiscal do documento e o tipo do arquivo.


        A origem do XML é controlada por `Folder`: `Invoice` (notas emitidas pela empresa, localizadas por `File` =
        `IDFile` ou por `IDOrder`), `Inbound` com `Origin=Purchase` (XML recebido em pedido de compra) ou `Inbound` com
        `Origin=Feed` (XML capturado pelo monitor de notas). O PDF inclui o logotipo da empresa quando configurado.


        A resposta é binária (`application/pdf` ou `application/xml`), não JSON.
      tags:
        - NF-e / NFC-e
      parameters:
        - name: Folder
          in: query
          required: true
          schema:
            type: string
            enum:
              - Invoice
              - Inbound
          description: >-
            Origem do XML. `Invoice` para notas emitidas pela empresa; `Inbound` para XMLs recebidos (combinar com
            `Origin`).
        - name: File
          in: query
          required: false
          schema:
            type: string
          description: >-
            Quando `Folder=Invoice`, identifica o arquivo pelo `IDFile`. Quando `Folder=Inbound`, identifica pela chave
            de acesso da NF-e. Pelo menos um entre `File` e `IDOrder` é obrigatório.
        - name: IDOrder
          in: query
          required: false
          schema:
            type: string
          description: Identificador do pedido cuja nota fiscal será impressa (alternativa a `File`).
        - name: Origin
          in: query
          required: false
          schema:
            type: string
            enum:
              - Purchase
              - Feed
          description: >-
            Quando `Folder=Inbound`, define a origem do XML: `Purchase` (recebido em pedido de compra) ou `Feed`
            (monitor de notas).
        - name: Type
          in: query
          required: false
          schema:
            type: string
            enum:
              - XML
          description: Quando `XML`, devolve o arquivo XML cru em vez do PDF do DANFE.
      responses:
        '200':
          description: >-
            PDF do DANFE (Content-Type `application/pdf`) ou arquivo XML (Content-Type herdado, `Content-Disposition:
            attachment`).
          content:
            application/pdf:
              schema:
                type: string
                format: binary
            application/xml:
              schema:
                type: string
        '400':
          description: >-
            Validação ou arquivo não localizado. Mensagens: `Precisa enviar o querystring Folder`; `Precisa enviar o
            querystring File ou IDOrder`; `Arquivo não encontrado`; `Arquivo não encontrado S3`; `Pedido não localizado`
            (no fluxo público de tracking).
    post:
      operationId: orderInvoiceDanfeBulkPost
      summary: Gera DANFEs em lote
      description: >-
        Recebe uma lista de pedidos/notas e dispara a geração em lote dos DANFEs, gerando um único PDF com todas as
        notas. Útil para imprimir várias notas de uma vez a partir da listagem de pedidos.


        A empresa autenticada (resolvida pelo subdomínio) é expandida para todas as filiais relacionadas — o lote pode
        percorrer notas de qualquer empresa do grupo.


        O corpo é um array de `IDOrder`. A resposta é binária — um único `application/pdf` com as DANFEs das notas
        principais (`Main=1`) dos pedidos, concatenadas.
      tags:
        - NF-e / NFC-e
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              description: >-
                Lista de pedidos/notas a imprimir. Shape interno não confirmado (depende de
                `ServiceInvoice::DanfeBulk`).
              items:
                type: object
                description: >-
                  Item da lista de impressão. Campos não confirmados no sistema — costumam carregar identificador do
                  pedido e/ou da nota.
        description: >-
          Lista dos `IDOrder` a imprimir em lote. O sistema busca a NF principal de cada pedido entre as filiais
          relacionadas à empresa autenticada e gera um único PDF com todas as DANFEs.
      responses:
        '200':
          description: >-
            Lote processado. Conteúdo retornado depende do processo `ServiceInvoice::DanfeBulk` (contrato não
            confirmado).
        '400':
          description: 'Validação. Mensagens: `Precisa enviar os pedidos no corpo`; `Empresa não localizada`.'
  /invoice/danfe65:
    get:
      operationId: orderInvoice65Get
      summary: Gera o DANFE NFCe (modelo 65), recibo não fiscal ou via TEF
      description: >-
        Gera o documento auxiliar do consumidor (DANFE NFCe modelo 65) para um pedido. O comportamento muda conforme os
        parâmetros:

        - Sem `OnlyTEFReceipt` e com `InvoiceType=1` (default): emite o cupom fiscal NFCe.

        - Com `InvoiceType=2`: emite um recibo não fiscal correspondente ao pedido.

        - Com `InvoiceType=3`: emite o cupom de troca/devolução (não fiscal) do pedido.

        - Com `OnlyTEFReceipt=1`: concatena os recibos de TEF (loja e/ou comprador) registrados na intenção de venda
        informada — útil para reimprimir comprovantes de cartão.


        A resposta é binária (PDF do cupom/recibo) ou texto bruto (recibos TEF).
      tags:
        - NF-e / NFC-e
      parameters:
        - name: IDOrder
          in: query
          required: true
          schema:
            type: string
          description: Identificador do pedido a imprimir.
        - name: InvoiceType
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 3
            default: 1
          description: >-
            `1` (default) imprime o cupom fiscal NFCe; `2` imprime o recibo não fiscal; `3` imprime o cupom de
            troca/devolução (não fiscal).
        - name: OrderGift
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Quando `1`, gera o cupom em modo presente (sem valores).
        - name: IDOrderIntention
          in: query
          required: false
          schema:
            type: integer
          description: >-
            Identificador da intenção de venda (PDV). Usado para localizar pagamentos TEF e para vincular o cupom à
            intenção.
        - name: OnlyTEFReceipt
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Quando `1`, devolve apenas os recibos TEF da intenção informada — não emite cupom fiscal.
        - name: TEFReceiptStore
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Quando `OnlyTEFReceipt=1`, inclui o recibo do estabelecimento (via loja).
        - name: TEFReceiptBuyer
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Quando `OnlyTEFReceipt=1`, inclui o recibo do comprador (via cliente).
      responses:
        '200':
          description: >-
            Cupom fiscal NFCe (PDF), recibo/cupom não fiscal, ou texto concatenado dos recibos TEF, dependendo dos
            parâmetros.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
            text/plain:
              schema:
                type: string
        '400':
          description: 'Validação ou pedido não localizado. Mensagens: `necessário selecionar um pedido`; `Pedido não encontrado`.'
  /invoice-service/{idserviceorder}/invoice/invoice-xml:
    get:
      operationId: invoiceServiceXmlGet
      summary: Baixa XML ou DANFSE em PDF da NFS-e
      description: >-
        Devolve o arquivo da NFS-e emitida — XML (`Type=XML`) ou DANFSE em PDF (`Type=PDF`). O parâmetro `File` traz o
        nome base do arquivo (geralmente o `IDServiceOrder` da NFS-e).
      tags:
        - NFS-e
      parameters:
        - name: idserviceorder
          in: path
          required: true
          schema:
            type: integer
          description: Identificador da NFS-e.
        - name: Type
          in: query
          required: true
          schema:
            type: string
            enum:
              - XML
              - PDF
          description: 'Formato do arquivo: `XML` baixa o XML; `PDF` gera e baixa a DANFSE.'
        - name: File
          in: query
          required: true
          schema:
            type: string
          description: Nome base do arquivo a baixar. Aceita apenas dígitos; demais caracteres são removidos.
        - name: token
          in: query
          required: true
          schema:
            type: string
          description: Token de autenticação repassado na URL (usada como link direto).
      responses:
        '200':
          description: 'Arquivo entregue como download (`Content-Disposition: attachment`).'
          content:
            application/xml:
              schema:
                type: string
                format: binary
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          description: 'Arquivo não encontrado em S3 ou na NFS-e: `Arquivo não encontrado (2)`.'
  /invoice-service/{idserviceorder}/payment:
    post:
      operationId: invoiceServicePaymentPost
      summary: Lança um pagamento da NFS-e
      description: >-
        Cria uma ou mais contas a receber vinculadas à NFS-e. Quando `SplitInstallment=1`, gera uma conta por parcela
        (cada uma com `Value`); quando `0`, gera uma única conta consolidando o valor. Valida tipo de pagamento, tipo de
        documento, plano de contas, banco de recebimento, integração e empresa faturadora. Calcula a data de vencimento
        a partir do `DaysDue` do tipo de pagamento quando não enviada.
      tags:
        - NFS-e
      parameters:
        - name: idserviceorder
          in: path
          required: true
          schema:
            type: integer
          description: Identificador da NFS-e.
        - name: SplitInstallment
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
            default: 1
          description: Quando `1`, cada parcela vira uma conta a receber separada; quando `0`, uma única conta consolida o valor.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceServicePaymentCreateBody'
        description: >-
          Pagamento(s) a baixar contra a NFS-e. O sistema valida que a NFS-e pertence à empresa autenticada e aplica as
          regras do fluxo de pagamento (parcelamento via querystring `SplitInstallment`, atualização de status).
          Resposta devolve o detalhe da NFS-e atualizado (mesmo schema do `GET /invoice-service/{idserviceorder}`).
      responses:
        '200':
          description: Pagamento lançado. Retorna o detalhe atualizado da NFS-e.
        '400':
          description: >-
            Validação falhou. Mensagens reais: `Tipo pagamento padrão não cadastrado para a empresa`, `Tipo pagamento
            não cadastrado`, `Tipo documento padrão não cadastrado para a empresa`, `Tipo registro padrão não cadastrado
            para a empresa`, `Banco de recebimento não cadastrado`, `Integração não cadastrada`, `Empresa faturadora não
            encontrada`.
        '404':
          description: 'NFS-e não encontrada: `[NotFound] - Pedido não encontrado`.'
  /invoice-service/{idserviceorder}/payment/{idaccountpayablereceivable}:
    put:
      operationId: invoiceServicePaymentPut
      summary: Atualiza um pagamento da NFS-e
      description: >-
        Atualiza uma conta a receber lançada para a NFS-e. Valida tipo de pagamento, tipo de documento, plano de contas,
        banco e integração quando enviados, e recalcula `DaysDue` quando `DateDue` muda. Registra o que foi alterado no
        histórico da conta e no histórico da NFS-e.
      tags:
        - NFS-e
      parameters:
        - name: idserviceorder
          in: path
          required: true
          schema:
            type: integer
          description: Identificador da NFS-e.
        - name: idaccountpayablereceivable
          in: path
          required: true
          schema:
            type: integer
          description: Identificador da conta a receber a ser atualizada.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceServicePaymentUpdateBody'
        description: >-
          Atualização do título de pagamento vinculado à NFS-e — reutiliza o sistema de **conta a receber**
          (`accountsReceivablePut`). O corpo aceita os campos do título (valor, vencimento, plano de contas, observações
          etc.); apenas os enviados são alterados.
      responses:
        '200':
          description: Pagamento atualizado. Retorna o detalhe atualizado da conta a receber.
        '400':
          description: >-
            Validação falhou. Mensagens reais: `[BadRequest] - Fornecedor ou cliente precisa ser preenchido (apenas um
            dos dois)`, `[BadRequest] - Conta a receber não existe`, `[BadRequest] - Fornecedor não existe`,
            `[BadRequest] - Cliente não existe`, `[BadRequest] - Faturador não existe`, `[BadRequest] - Pagamento não
            existe`, `[BadRequest] - Banco não existe`, `[BadRequest] - Integração não existe`, `[BadRequest] - Plano de
            contas não existe`, `[BadRequest] - Tipo documento não existe`, `[BadRequest] - Boleto / link pagamento já
            esta pago e não pode ser alterado`.
    delete:
      operationId: invoiceServicePaymentDelete
      summary: Remove um pagamento da NFS-e
      description: >-
        Exclui uma conta a receber lançada para a NFS-e. Bloqueada quando a conta já tem pagamento conciliado ou está
        agendada (`Scheduled=1`). Quando a conta tem origem em recebimento, a exclusão respeita a parametrização
        **Bloquear exclusão de contas vinculadas a recebimento**.
      tags:
        - NFS-e
      parameters:
        - name: idserviceorder
          in: path
          required: true
          schema:
            type: integer
          description: Identificador da NFS-e.
        - name: idaccountpayablereceivable
          in: path
          required: true
          schema:
            type: integer
          description: Identificador da conta a receber a remover.
      responses:
        '200':
          description: Pagamento removido. Retorna o detalhe atualizado da NFS-e.
        '400':
          description: >-
            Validação falhou. Mensagens reais: `[BadRequest] - Pagamento não existe`, `[BadRequest] - Título esta
            agendado e não pode ser excluído`, `[BadRequest] - Contas a pagar já tem pagamento`, `[BadRequest] - Não é
            possível excluir um contas a pagar atrelado a um recebimento`.
  /purchase/buy-order/{idbuyorder}/log:
    get:
      operationId: buyOrderLogGet
      summary: Histórico do pedido de compra
      description: >-
        Retorna o histórico de eventos do pedido de compra (inclusões/remoções de itens, alterações de status,
        lançamentos de pagamento, mesclagem com outro pedido). Cada linha traz o autor (`Login`) e a descrição da ação.
      tags:
        - Pedido de Compra
      parameters:
        - name: idbuyorder
          in: path
          required: true
          schema:
            type: integer
          description: Identificador do pedido de compra.
      responses:
        '200':
          description: Histórico do pedido de compra (ordem decrescente).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BuyOrderLog'
  /purchase/buy-order/{idbuyorder}/merge:
    post:
      operationId: buyOrderMergePost
      summary: Mescla dois pedidos de compra
      description: >-
        Move todos os itens do pedido de compra da URL para o pedido informado no body (`IDBuyOrder`). O pedido de
        origem passa a status `7 Mesclado` e fica vazio. Ambos os pedidos precisam estar em status que permita edição
        (`0` Aberto, `1` Aguardando recebimento, `3` Perdido confirmado ou `6` Recebido parcialmente) e ter o **mesmo
        fornecedor**.
      tags:
        - Pedido de Compra
      parameters:
        - name: idbuyorder
          in: path
          required: true
          schema:
            type: integer
          description: Identificador do pedido de compra de origem (o que será mesclado e ficará vazio).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuyOrderMergeBody'
        description: >-
          Pedido de compra de destino. Precisa estar em status que permita edição (`0`, `1`, `3` ou `6`) e ter o mesmo
          fornecedor do pedido de origem. Todos os itens do pedido da URL são movidos para este pedido; o pedido de
          origem passa a status `7 Mesclado` e fica vazio.
      responses:
        '200':
          description: Pedidos mesclados. Retorna o detalhe atualizado do pedido de origem.
        '400':
          description: >-
            Validação falhou. Mensagens reais: `[BadRequest] - Pedido de compra não existe`, `[BadRequest] - Status
            pedido de compra não permite mesclar`, `[BadRequest] - Pedido de compra destino não existe`, `[BadRequest] -
            Status pedido de compra destino não permite mesclar`, `[BadRequest] - Fornecedor divergente nos pedidos de
            compra`.
  /purchase/buy-order/{idbuyorder}/payment:
    post:
      operationId: buyOrderPaymentPost
      summary: Lança um pagamento do pedido de compra
      description: >-
        Cria uma conta a pagar (`IDTypeAccount=1`, `Forecast=1`) vinculada ao pedido de compra. Usa o fornecedor e a
        empresa faturadora do próprio pedido. Valida tipo de pagamento, tipo de documento e plano de contas (exigindo
        que o plano seja de último nível). Registra a inclusão no histórico do pedido.
      tags:
        - Pedido de Compra
      parameters:
        - name: idbuyorder
          in: path
          required: true
          schema:
            type: integer
          description: Identificador do pedido de compra.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuyOrderPaymentCreateBody'
        description: >-
          Dados do título a pagar a lançar no pedido de compra. O fornecedor e a empresa faturadora são herdados do
          próprio pedido. O plano de contas (`IDTypeAccountPayble`) precisa ser de último nível (folha do plano de
          contas).
      responses:
        '200':
          description: Pagamento lançado. Retorna o detalhe atualizado do pedido de compra.
        '400':
          description: >-
            Validação falhou. Mensagens reais: `[BadRequest] - Pedido de compra não existe`, `[BadRequest] - Tipo
            pagamento não existe`, `[BadRequest] - Tipo documento não existe`, `[BadRequest] - Plano de contas não
            existe`, `[BadRequest] - Plano de contas não é último nível`.
  /purchase/buy-order/{idbuyorder}/payment/{idaccountpayablereceivable}:
    put:
      operationId: buyOrderPaymentPut
      summary: Atualiza um pagamento do pedido de compra
      description: >-
        Atualiza uma conta a pagar vinculada ao pedido de compra. Mantém o fornecedor original do pedido. Valida tipo de
        pagamento, tipo de documento e plano de contas (exigindo último nível) quando enviados. Registra o diff de
        campos no histórico do pedido.
      tags:
        - Pedido de Compra
      parameters:
        - name: idbuyorder
          in: path
          required: true
          schema:
            type: integer
          description: Identificador do pedido de compra.
        - name: idaccountpayablereceivable
          in: path
          required: true
          schema:
            type: integer
          description: Identificador da conta a pagar a ser atualizada.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuyOrderPaymentCreateBody'
        description: >-
          Campos editáveis do título a pagar (atualização parcial). O fornecedor original do pedido é mantido.
          Validações de tipo de pagamento, tipo de documento e plano de contas valem quando os campos são enviados.
      responses:
        '200':
          description: Pagamento atualizado. Retorna o detalhe atualizado do pedido de compra.
        '400':
          description: >-
            Validação falhou. Mensagens reais: `[BadRequest] - Pagamento pedido de compra não existe`, `[BadRequest] -
            Tipo pagamento não existe`, `[BadRequest] - Tipo documento não existe`, `[BadRequest] - Plano de contas não
            existe`, `[BadRequest] - Plano de contas não é último nível`.
    delete:
      operationId: buyOrderPaymentDelete
      summary: Remove um pagamento do pedido de compra
      description: >-
        Exclui uma conta a pagar vinculada ao pedido de compra. Bloqueada quando o pedido está em status que não permite
        atualização (recebimentos com `IDStatusPurchase` `2`, `3` ou `7`). Registra a remoção no histórico do pedido.
      tags:
        - Pedido de Compra
      parameters:
        - name: idbuyorder
          in: path
          required: true
          schema:
            type: integer
          description: Identificador do pedido de compra.
        - name: idaccountpayablereceivable
          in: path
          required: true
          schema:
            type: integer
          description: Identificador da conta a pagar a remover.
      responses:
        '200':
          description: Pagamento removido.
          content:
            application/json:
              schema:
                type: string
                example: sucesso
        '400':
          description: >-
            Validação falhou. Mensagens reais: `[BadRequest] - Pedido de compra não existe`, `[BadRequest] - Status não
            permite atualização`.
  /purchase/buy-order/{idbuyorder}/sku:
    post:
      operationId: buyOrderSkuPost
      summary: Adiciona item ao pedido de compra
      description: >-
        Adiciona um SKU como item do pedido de compra. Só é permitido enquanto o pedido está em status `0 Aberto`.
        Valida que o SKU existe, está ativo (`IDStatusSku=1`) e é de um tipo comprável (`IDTypeSku` em `3`, `5`, `6` ou
        `7`). Resolve o armazém: se `IDStockKeepingUnitWarehouse` não vier, usa o armazém padrão da empresa; o centro de
        distribuição do item precisa bater com o do pedido (definido ou herdado do armazém).
      tags:
        - Pedido de Compra
      parameters:
        - name: idbuyorder
          in: path
          required: true
          schema:
            type: integer
          description: Identificador do pedido de compra.
      requestBody:
        description: Adiciona um item (SKU) ao pedido de compra.
        content:
          application/json:
            schema:
              type: object
              properties:
                IDSku:
                  type: integer
                  description: SKU a adicionar ao pedido de compra.
                IDStockKeepingUnitWarehouse:
                  type: integer
                  description: Armazém de destino do item.
                Quantity:
                  type: number
                  format: double
                  description: Quantidade a comprar.
                ValueCostUnit:
                  type: number
                  format: double
                  description: Custo unitário de compra em R$.
              required:
                - IDSku
                - Quantity
      responses:
        '200':
          description: Item adicionado. Retorna o detalhe atualizado do pedido de compra.
        '400':
          description: >-
            Validação falhou. Mensagens reais: `[BadRequest] - O status atual não permite atualização`, `[BadRequest] -
            SKU não cadastrado: <id>`, `[BadRequest] - SKU não esta ativo`, `[BadRequest] - Warehouse não cadastrada:
            SKU -> <id>`, `[BadRequest] - Centro de distribuição do item é diferente do pedido de compra`, `[BadRequest]
            - Erro ao inserir sku`.
        '404':
          description: 'Pedido de compra não encontrado: `[NotFound] - Buy Order Not Found`.'
  /purchase/buy-order/{idbuyorder}/sku/{idstockkeepingunitbuyorder}:
    put:
      operationId: buyOrderSkuPut
      summary: Atualiza item do pedido de compra
      description: >-
        Atualiza um item do pedido de compra (SKU, armazém, quantidade, custo unitário, validade, observações, data
        prevista de entrega). Só é permitido enquanto o pedido está em status `0 Aberto`. O centro de distribuição do
        novo armazém precisa bater com o do pedido. Registra o diff de campos no histórico.
      tags:
        - Pedido de Compra
      parameters:
        - name: idbuyorder
          in: path
          required: true
          schema:
            type: integer
          description: Identificador do pedido de compra.
        - name: idstockkeepingunitbuyorder
          in: path
          required: true
          schema:
            type: integer
          description: Identificador do item dentro do pedido de compra.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuyOrderSkuUpdateBody'
        description: >-
          Campos editáveis do item do pedido de compra (atualização parcial): SKU, armazém, quantidade, custo unitário,
          validade, observações, data prevista de entrega. Pedido precisa estar em status `0 Aberto`. O centro de
          distribuição do novo armazém precisa bater com o do pedido.
      responses:
        '200':
          description: Item atualizado. Retorna o detalhe atualizado do pedido de compra.
        '400':
          description: >-
            Validação falhou. Mensagens reais: `[BadRequest] - Pedido de compra não existe`, `[BadRequest] - O status
            atual não permite atualizar`, `[BadRequest] - Sku não existe`, `[BadRequest] - Armazém não existe`,
            `[BadRequest] - Centro de distribuição do item é diferente do CD do pedido de compra`.
    delete:
      operationId: buyOrderSkuDelete
      summary: Remove item do pedido de compra
      description: >-
        Remove um item do pedido de compra. Só é permitido enquanto o pedido está em status `0 Aberto`. Registra a
        remoção no histórico.
      tags:
        - Pedido de Compra
      parameters:
        - name: idbuyorder
          in: path
          required: true
          schema:
            type: integer
          description: Identificador do pedido de compra.
        - name: idstockkeepingunitbuyorder
          in: path
          required: true
          schema:
            type: integer
          description: Identificador do item dentro do pedido de compra.
      responses:
        '200':
          description: Item removido. Retorna o detalhe atualizado do pedido de compra.
        '400':
          description: 'Validação falhou: `[BadRequest] - O status atual não permite atualizar`.'
        '404':
          description: 'Pedido de compra não encontrado: `[NotFound] - Pedido de compra não localizado`.'
  /charge/bank-slip/{idbankslip}/order:
    post:
      operationId: chargeBankSlipOrderPost
      summary: Cria um pedido a partir de boleto pago
      description: >-
        Gera um pedido (`Orders`) a partir de um boleto bancário pago avulso. O boleto precisa estar em status Pago
        (`IDStatusBankSlip=2`) e ainda não ter pedido vinculado. O pedido nasce com o cliente do boleto, o tipo de
        pedido padrão da empresa, a integração do tipo Stark (`IDTypeCompanyIntegration=16`) e um pagamento de categoria
        boleto (`Category=2`) já lançado com o `TID`/`NSU` e o valor do boleto. Ao final, o boleto fica vinculado ao
        novo pedido.
      tags:
        - Boleto Bancário
      parameters:
        - name: idbankslip
          in: path
          required: true
          schema:
            type: integer
          description: Identificador do boleto bancário.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChargeBankSlipOrderBody'
        description: >-
          Corpo opcional — o sistema resolve cliente do boleto, integração padrão Stark, tipo de pedido padrão da
          empresa e tipo de pagamento de boleto a partir da configuração da empresa, sem necessidade de campos no body.
      responses:
        '200':
          description: Pedido criado. Retorna o detalhe completo do pedido novo.
        '400':
          description: >-
            Configuração da empresa incompleta. Mensagens reais: `[BadRequest] - IDTypeOrder não existe` (tipo de pedido
            padrão não cadastrado), `[BadRequest] - IDCompanyIntegration não existe` (integração Stark não cadastrada),
            `[BadRequest] - IDTypePayment não existe` (tipo de pagamento de boleto ativo não cadastrado).
        '404':
          description: >-
            Boleto inválido para criação de pedido. Mensagens reais: `[NotFound] - Boleto não existe`, `[NotFound] -
            Boleto não esta pago`, `[NotFound] - Boleto já tem pedido criado`.
  /company/bill:
    get:
      operationId: companyBillingGet
      summary: Lista as faturas mensais de cobrança da empresa
      description: >-
        Retorna o histórico de faturas geradas, com vencimento, valor total, nota fiscal de serviço associada e boleto.
        Cada fatura traz o detalhamento das regras de cobrança aplicadas no mês.
      tags:
        - Cobrança
      responses:
        '200':
          description: Faturas encontradas.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyBill'
        '500':
          description: Erro interno.
  /company/bill/{idcompanybilling}/report:
    post:
      operationId: companyBillingReportPost
      summary: Gera o relatório detalhado de uma fatura e envia por e-mail
      description: >-
        Gera a planilha com o detalhamento de uma fatura e a envia por e-mail ao usuário autenticado; a resposta HTTP
        não traz o arquivo (que chega por e-mail) e a planilha é montada e enviada durante a própria requisição, sem
        processamento em segundo plano.
      tags:
        - Cobrança
      parameters:
        - name: idcompanybilling
          in: path
          required: true
          schema:
            type: integer
          description: Identificador da fatura.
      responses:
        '200':
          description: Relatório gerado e enviado por e-mail ao usuário durante a requisição. Sem corpo na resposta.
        '400':
          description: >-
            Empresa ou fatura não localizada. Corpo JSON com `errorMessage` no formato `[BadRequest] - <mensagem>`:
            `[BadRequest] - Empresa não localizada`, `[BadRequest] - Fatura não localizada`.
        '500':
          description: 'Erro interno ao gerar o relatório (ex.: fatura sem itens detalhados). Corpo vazio.'
  /company/dashboard:
    get:
      operationId: companyDashboardGet
      summary: Retorna indicadores do painel inicial por categoria
      description: >-
        Devolve os blocos de KPIs do painel inicial conforme a categoria solicitada. As categorias `8` e `9` têm
        comportamento próprio: financeiro consolida vencimentos do mês corrente; rastreio agrega entregas no prazo e
        atrasadas. As demais categorias retornam a lista de cartões configurados para a empresa.


        Quando `IDTypeCompanyDashboardCategory=8`, os filtros adicionais por data de vencimento, fornecedor, faturador e
        conta bancária da previsão se aplicam. Quando `IDTypeCompanyDashboardCategory=9`, vale a janela de embarque
        `ShippingDate*` e de criação do pedido `RecordTimestamp` via `DateFrom`/`DateTo` — sem datas, considera os
        últimos 7 dias.
      tags:
        - Dashboards
      parameters:
        - name: IDTypeCompanyDashboardCategory
          in: query
          required: false
          schema:
            type: integer
          description: >-
            Categoria do painel a ser retornado. Valores especiais: `8` = financeiro (vencimentos); `9` = rastreio
            (entregas).
        - name: DateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data inicial de criação do pedido (apenas categoria rastreio).
        - name: DateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data final de criação do pedido (apenas categoria rastreio). O sistema concatena `23:59:59` ao filtrar.
        - name: ShippingDateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data inicial do embarque (apenas categoria rastreio).
        - name: ShippingDateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data final do embarque (apenas categoria rastreio).
        - name: DateDueFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: 'Data inicial de vencimento (apenas categoria financeiro). Default: `1900-01-01`.'
        - name: DateDueTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: 'Data final de vencimento (apenas categoria financeiro). Default: `4000-01-01`.'
        - name: IDTypeAccount
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: 'Tipo da conta: `0` = entrada (receber); `1` = saída (pagar).'
        - name: IDTypeAccountPayableReceivable
          in: query
          required: false
          schema:
            type: integer
          description: Tipo do título financeiro.
        - name: IDStatusAccountPayableReceivable
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
              - 2
              - 3
              - 4
              - 5
              - 6
          description: Status do título financeiro.
        - name: IDSupplier
          in: query
          required: false
          schema:
            type: integer
          description: Identificador do fornecedor.
        - name: IDCompanyInvoice
          in: query
          required: false
          schema:
            type: integer
          description: Identificador do faturador.
        - name: IDBankAccountForecast
          in: query
          required: false
          schema:
            type: integer
          description: Identificador da conta bancária de previsão.
      responses:
        '200':
          description: Indicadores retornados.
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/CompanyDashboardSummary'
                  - type: object
                    properties:
                      trackings:
                        type: array
                        items:
                          type: object
                        description: Coleção de rastreios resumidos exibidos no dashboard.
                      otdacount:
                        type: object
                        properties:
                          onTime:
                            type: integer
                            description: Quantidade de entregas no prazo.
                          afterTime:
                            type: integer
                            description: Quantidade de entregas atrasadas.
                          exceptions:
                            type: integer
                            description: Quantidade de entregas com exceção (não entregue, devolvida ou em problema).
                        description: Agregado de pontualidade de entrega (OTDA = On-Time Delivery Accuracy).
  /company/dashboard/order/status:
    get:
      operationId: companyDashboardOrderStatusGet
      summary: Contagem de pedidos por status para o painel
      description: >-
        Retorna o total de pedidos agrupado por status para o painel inicial. Respeita os centros de distribuição
        liberados ao usuário autenticado. Quando `Budget=1`, considera o conjunto de status reservados ao fluxo de
        orçamento; caso contrário, considera os status de pedido padrão (exclui o status `7`).
      tags:
        - Dashboards
      parameters:
        - name: Budget
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: Quando `1`, contabiliza apenas status do fluxo de orçamento.
      responses:
        '200':
          description: Contagem por status.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyDashboardOrderStatus'
  /company/module:
    get:
      operationId: companyModuleGet
      summary: Lista os módulos contratados pela empresa com seus privilégios
      description: >-
        Retorna os grupos de módulos disponíveis, cada um com a lista de módulos contratados pela empresa e os
        privilégios associados a cada módulo. Usado para montar a árvore de permissões do perfil de acesso.
      tags:
        - Módulos Contratados
      responses:
        '200':
          description: Módulos retornados.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyModule'
  /company/report/custom:
    get:
      operationId: companyReportCustomList
      summary: Lista os relatórios personalizados da empresa
      description: >-
        Retorna os relatórios dinâmicos cadastrados pela empresa, incluindo a estrutura `ReportStructure` (campos
        selecionados, filtros, agrupamentos, ordenação), o tipo de relatório personalizado e a lista de campos
        referenciados.
      tags:
        - Relatórios Customizados
      parameters:
        - name: IDTypeCompanyReport
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por um relatório específico.
      responses:
        '200':
          description: Lista de relatórios.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyReportCustom'
    post:
      operationId: companyReportCustomPost
      summary: Cria um relatório personalizado
      description: >-
        Monta um relatório dinâmico a partir da seleção de campos, filtros, agrupamentos e ordenação. O sistema monta a
        consulta correspondente a partir do tipo de relatório e dos relacionamentos disponíveis. Após salvar, é
        disparada a execução para gerar o conteúdo.
      tags:
        - Relatórios Customizados
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyReportCustomCreateBody'
        description: >-
          Configuração do relatório personalizado: nome, tipo base (`ReportType` → `TypeCustomReport`), campos
          selecionados (`Select`), filtros (`Where` com `FieldID` + `Value`), agrupamentos (`GroupBy`) e ordenação
          (`OrderBy`). O sistema monta a query para cada destino disponível (banco transacional e BigQuery, quando
          aplicável) e grava em `MySQLQuery1/2` e `BigQueryQuery1/2`.
      responses:
        '200':
          description: Relatório criado e executado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyReportCustom'
        '400':
          description: >-
            Empresa não localizada, tipo de relatório não informado, base não suportada ou nenhum campo selecionado.
            Mensagem em texto puro.
  /company/report/custom/{idtypecompanyreport}:
    put:
      operationId: companyReportCustomPut
      summary: Atualiza um relatório personalizado
      description: >-
        Substitui a estrutura do relatório personalizado existente (campos, filtros, agrupamento, ordenação) e
        re-executa para regenerar o conteúdo.
      tags:
        - Relatórios Customizados
      parameters:
        - name: idtypecompanyreport
          in: path
          required: true
          schema:
            type: integer
          description: Identificador do relatório personalizado.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyReportCustomCreateBody'
        description: >-
          Atualização total da configuração do relatório personalizado — todos os campos do corpo são gravados. A SQL é
          regerada a partir da nova estrutura.
      responses:
        '200':
          description: Relatório atualizado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CompanyReportCustom'
        '400':
          description: >-
            Relatório não localizado, tipo de relatório não informado ou nenhum campo selecionado. Mensagem em texto
            puro.
    delete:
      operationId: companyReportCustomDelete
      summary: Remove um relatório personalizado
      description: >-
        Remove o vínculo do relatório com a empresa. O relatório só pode ser removido se pertencer à empresa
        autenticada.
      tags:
        - Relatórios Customizados
      parameters:
        - name: idtypecompanyreport
          in: path
          required: true
          schema:
            type: integer
          description: Identificador do relatório personalizado.
      responses:
        '200':
          description: Relatório removido. Retorna o literal `"sucesso"`.
          content:
            application/json:
              schema:
                type: string
                example: sucesso
        '400':
          description: >-
            Nenhum relatório encontrado para deletar, falha na operação ou erro de configuração da empresa. Prefixo
            `[BadRequest]`.
  /company/status/order:
    get:
      operationId: typeOrderStatusRuleList
      summary: Lista as transições permitidas a partir de um status de pedido
      description: >-
        Retorna os status de destino válidos para o status de origem informado, conforme as regras de transição
        configuradas. Cada destino indica se exige comentário e se exige data ao mover o pedido.
      tags:
        - Transições de Status
      parameters:
        - name: IDStatusOrder
          in: query
          required: true
          schema:
            type: integer
          description: Status de origem do pedido.
      responses:
        '200':
          description: Transições permitidas.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    IDStatusOrder:
                      type: integer
                      description: Status de origem.
                    StatusOrder:
                      type: string
                      nullable: true
                      description: Descrição do status de origem para a empresa.
                    IDStatusOrderTo:
                      type: integer
                      description: Status de destino permitido.
                    StatusOrderTo:
                      type: string
                      description: Descrição do status de destino para a empresa.
                    CommentsRequired:
                      type: integer
                      description: '`1` quando o destino exige comentário.'
                    DateRequired:
                      type: integer
                      description: '`1` quando o destino exige data.'
        '400':
          description: '`IDStatusOrder` é obrigatório. Prefixo `[BadRequest]`.'
  /goal:
    get:
      operationId: goalList
      summary: Lista as metas cadastradas para a empresa
      description: >-
        Retorna até 5.000 metas ordenadas pela data inicial decrescente. Aceita filtros por tipo de meta, identificador
        da meta e janela de início. Cada meta traz o tipo amigável.
      tags:
        - Metas
      parameters:
        - name: IDTypeGoal
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 3
              - 4
          description: 'Tipo da meta: `1` vendedor, `2` faturador, `3` tipo de pedido, `4` integração.'
        - name: IDCompanyGoal
          in: query
          required: false
          schema:
            type: integer
          description: Identificador da meta.
        - name: DateFromFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data inicial mínima de vigência.
        - name: DateFromTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data inicial máxima de vigência. O sistema concatena `23:59:59`.
      responses:
        '200':
          description: Metas retornadas.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Goal'
    post:
      operationId: goalPost
      summary: Cria uma meta para a empresa
      description: >-
        Cria a meta principal e, conforme o `IDTypeGoal`, persiste o desdobramento por vendedor (`GoalSalesmans`),
        faturador (`GoalCompanyInvoices`), tipo de pedido (`GoalTypeOrders`) ou integração (`GoalCompanyIntegrations`).
        Bloqueia a criação quando já existe meta do mesmo tipo dentro do intervalo `DateFrom`–`DateTo`. Valida que
        `DateFrom` não seja maior que `DateTo` e que cada item do desdobramento pertença à empresa.
      tags:
        - Metas
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoalCreateBody'
        description: >-
          Meta a cadastrar. `IDTypeGoal`, `GoalName`, `DateFrom` e `DateTo` são obrigatórios. O desdobramento por item
          (`GoalSalesmans`, `GoalCompanyInvoices`, `GoalTypeOrders`, `GoalCompanyIntegrations`) precisa ser informado de
          acordo com o `IDTypeGoal` (1 vendedor, 2 faturador, 3 tipo de pedido, 4 integração). O sistema bloqueia quando
          já existe meta do mesmo tipo dentro do intervalo `DateFrom`–`DateTo` e valida que cada item pertença à empresa
          autenticada.
      responses:
        '200':
          description: Meta criada. Retorna a representação completa da meta (delegado ao `goalGet`).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Goal'
        '400':
          description: >-
            Possíveis causas: tipo de meta inexistente, empresa não localizada, sobreposição com meta já cadastrada,
            `DateFrom` maior que `DateTo`, ou vendedor/faturador/tipo de pedido/integração inexistentes. Prefixo
            `[BadRequest]`.
  /goal/{idcompanygoal}:
    get:
      operationId: goalGet
      summary: Retorna uma meta com o desdobramento por item
      description: >-
        Retorna a meta principal e, conforme o tipo, popula `GoalSalesmans`, `GoalCompanyInvoices`, `GoalTypeOrders` ou
        `GoalCompanyIntegrations` com os valores configurados para cada vendedor, faturador, tipo de pedido ou
        integração.
      tags:
        - Metas
      parameters:
        - name: idcompanygoal
          in: path
          required: true
          schema:
            type: integer
          description: Identificador da meta.
      responses:
        '200':
          description: Meta retornada. Quando inexistente, retorna lista vazia.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Goal'
    put:
      operationId: goalPut
      summary: Atualiza uma meta e seu desdobramento
      description: >-
        Altera os dados principais da meta e substitui o desdobramento por vendedor, faturador, tipo de pedido ou
        integração de acordo com o `IDTypeGoal`. Aplica as mesmas validações do POST: bloqueia sobreposição com outras
        metas do mesmo tipo e exige `DateFrom` menor ou igual a `DateTo`.
      tags:
        - Metas
      parameters:
        - name: idcompanygoal
          in: path
          required: true
          schema:
            type: integer
          description: Identificador da meta.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoalUpdateBody'
        description: >-
          Mesmo contrato do POST. Os itens do desdobramento informados substituem os existentes — itens omitidos
          preservam os atuais. Mesmas validações de sobreposição, intervalo de datas e existência dos itens na empresa.
      responses:
        '200':
          description: Meta atualizada. Retorna a representação completa (delegado ao `goalGet`).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Goal'
        '400':
          description: Mesmos cenários do POST. Prefixo `[BadRequest]`.
    delete:
      operationId: goalDelete
      summary: Remove uma meta
      description: Remove a meta e, em cascata, todos os desdobramentos por vendedor, faturador, tipo de pedido e integração.
      tags:
        - Metas
      parameters:
        - name: idcompanygoal
          in: path
          required: true
          schema:
            type: integer
          description: Identificador da meta.
      responses:
        '200':
          description: Meta removida. Retorna o literal `"sucesso"`.
          content:
            application/json:
              schema:
                type: string
                example: sucesso
        '400':
          description: Meta não existe. Prefixo `[BadRequest]`.
  /correios/reversa:
    get:
      operationId: trackReverseList
      summary: Lista as solicitações de logística reversa Correios
      description: >-
        Retorna as coletas reversas abertas para os pedidos da empresa, com identificador da coleta, prazo,
        transportadora associada e origens do pedido. Pagina por blocos de 3.000 registros (`Page`) limitando 1.000 por
        página.
      tags:
        - Logística Reversa Correios
      parameters:
        - name: Order
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo número do pedido (busca parcial via `LIKE`).
        - name: OrderFrom
          in: query
          required: false
          schema:
            type: string
          description: Filtra por uma origem associada ao pedido.
        - name: IDColeta
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo código da coleta Correios (busca parcial via `LIKE`).
        - name: DateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data inicial de criação da coleta reversa.
        - name: DateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data final de criação da coleta reversa. O sistema concatena `23:59:59`.
        - name: DateReverseDeadlineFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data inicial do prazo da coleta.
        - name: DateReverseDeadlineTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data final do prazo da coleta. O sistema concatena `23:59:59`.
        - name: Page
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: Número da página. Cada página retorna até 1.000 registros, com offset de 3.000 por página.
      responses:
        '200':
          description: Coletas retornadas.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CorreiosReversa'
    post:
      operationId: reversaCorreiosPost
      summary: Solicita uma coleta reversa Correios
      description: >-
        Encaminha a solicitação de postagem reversa ao processo dos Correios. Aceita coleta domiciliar (`TipoColeta`
        informado) ou postagem em agência (`TipoColeta=0`, valor padrão quando omitido).
      tags:
        - Logística Reversa Correios
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CorreiosReversaCreateBody'
        description: >-
          Solicitação de logística reversa Correios. `IDOrder` e `IDCarrier` são obrigatórios. `TipoColeta` define a
          modalidade — `0` (default, omitido) para postagem em agência, `1`/`2` para coleta domiciliar; quando
          domiciliar, `Schedule` carrega o agendamento (data e janela de horário). O corpo é encaminhado ao serviço de
          logística reversa dos Correios.
      responses:
        '200':
          description: Solicitação aceita. Retorna o literal `"sucesso"`.
          content:
            application/json:
              schema:
                type: string
                example: sucesso
        '500':
          description: Erro retornado pelo processo dos Correios. Mensagem propagada do serviço externo.
  /correios/generaterange:
    post:
      operationId: correiosGenerateRange
      summary: Gera uma faixa de etiquetas Correios para a transportadora
      description: >-
        Dispara a rotina que solicita uma nova faixa de códigos de rastreio (etiquetas) aos Correios para a
        transportadora informada. A transportadora precisa pertencer à empresa autenticada e ter tipo Correios.
      tags:
        - Faixa de Etiquetas Correios
      parameters:
        - name: IDCarrier
          in: query
          required: false
          schema:
            type: integer
          description: Identificador da transportadora Correios. Enviado como query string.
      responses:
        '200':
          description: Geração disparada. Retorna o literal `"sucesso"`.
          content:
            application/json:
              schema:
                type: string
                example: sucesso
        '400':
          description: Transportadora inexistente para a empresa ou não é do tipo Correios. Prefixo `[BadRequest]`.
        '500':
          description: Erro retornado pelo processo. Mensagem propagada do serviço externo.
  /correios/pi:
    get:
      operationId: correiosPIList
      summary: Lista as Postagens Imediatas Correios
      description: >-
        Retorna as PIs (Postagens Imediatas) Correios abertas para os pacotes da empresa, com identificador da PI,
        status, datas de abertura e postagem, prazo máximo de entrega, motivo da reclamação e última mensagem de
        retorno. Pagina por blocos de 3.000 registros (`Page`) limitando 1.000 por página.
      tags:
        - Correios — PI
      parameters:
        - name: Order
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo número do pedido (busca parcial via `LIKE`).
        - name: OrderFrom
          in: query
          required: false
          schema:
            type: string
          description: Filtra por uma origem associada ao pedido.
        - name: ShippingDateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data inicial do embarque do pacote.
        - name: ShippingDateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data final do embarque do pacote. O sistema concatena `23:59:59`.
        - name: DateOpeningPIFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data inicial de abertura da PI.
        - name: DateOpeningPITo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Data final de abertura da PI. O sistema concatena `23:59:59`.
        - name: StatusPI
          in: query
          required: false
          schema:
            type: string
          description: Filtra pelo status da PI (busca parcial via `LIKE`).
        - name: Page
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: Número da página. Cada página retorna até 1.000 registros, com offset de 3.000 por página.
      responses:
        '200':
          description: PIs retornadas.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CorreiosPI'
  /file:
    post:
      operationId: filePost
      tags:
        - Arquivos
      summary: Anexa arquivo a um consumidor
      description: >-
        Faz upload de um arquivo `multipart/form-data` e vincula ao consumidor informado em `IDConsumer`. O arquivo é
        armazenado em bucket privado e o sistema responde com o registro criado, a chave interna `Key` e uma URL
        pré-assinada `UrlFile` (validade 48h). Limite de 3 arquivos por consumidor — quando atingido, é preciso remover
        um arquivo antes de adicionar outro.
      parameters:
        - name: FileSource
          in: query
          required: true
          schema:
            type: string
            enum:
              - Consumer
          description: Origem do arquivo. Hoje só `Consumer` é aceito; outros valores resultam em `[BadRequest]`.
        - name: IDConsumer
          in: query
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do consumidor que receberá o arquivo. Validado contra a empresa autenticada (subdomínio).
        - name: IDTypeFile
          in: query
          required: true
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 3
              - 4
              - 5
              - 6
              - 7
              - 8
          description: >-
            Tipo do arquivo: `1`=Documento Fiscal PDF, `2`=Documento Fiscal XML, `3`=Boleto Bancário, `4`=Comprovante
            Pagamento, `5`=Carta de Correção PDF, `6`=Carta de Correção XML, `7`=Inutilização NF XML, `8`=Cancelamento
            NF XML.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: >-
                    Conteúdo binário do arquivo. O nome original (incluindo extensão) é preservado para inferir a
                    extensão usada na chave do bucket.
        description: >-
          Upload `multipart/form-data` com o campo `file` contendo o binário. O nome original (com extensão) é
          preservado para inferir a extensão usada na chave do bucket. Os metadados do arquivo (`FileSource`,
          `IDConsumer`, `IDTypeFile`) vão pela query.
      responses:
        '200':
          description: Arquivo armazenado com sucesso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileUploadResponse'
        '400':
          description: >-
            Falha de validação. Mensagens possíveis: `[BadRequest] - Empresa não identificada no contexto da
            requisição.`, `[BadRequest] - IDConsumer é obrigatório.`, `[BadRequest] - IDTypeFile é obrigatório.`,
            `[BadRequest] - Consumidor não existe`, `[BadRequest] - Tipo de arquivo não existe`, `[BadRequest] - O
            consumidor já possui 3 arquivos vinculados. Remova um arquivo para adicionar outro.`, `[BadRequest] -
            Arquivo não enviado`, `[BadRequest] - Arquivo sem extensão`, `[BadRequest] - FileSource inválido`.
        '500':
          description: Erro interno. Falha ao gravar no bucket ou no banco.
    delete:
      operationId: fileDelete
      tags:
        - Arquivos
      summary: Remove arquivo vinculado a um consumidor
      description: >-
        Remove o vínculo de um arquivo de consumidor a partir do identificador `IDFile`. O registro é apagado mesmo que
        o objeto correspondente no bucket ainda exista (limpeza do bucket está atualmente desativada no sistema).
      parameters:
        - name: FileSource
          in: query
          required: true
          schema:
            type: string
            enum:
              - Consumer
          description: Origem do arquivo. Hoje só `Consumer` é aceito.
        - name: IDConsumer
          in: query
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do consumidor dono do arquivo.
        - name: IDFile
          in: query
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do arquivo a remover (`IDConsumerFile`).
      responses:
        '200':
          description: Arquivo removido com sucesso. Retorna a string literal `"sucesso"`.
          content:
            application/json:
              schema:
                type: string
                example: sucesso
        '400':
          description: >-
            Falha de validação. Mensagens possíveis: `[BadRequest] - ID do arquivo não informado`, `[BadRequest] -
            Arquivo não informado`, `[BadRequest] - Arquivo não existe`, `[BadRequest] - FileSource inválido`.
        '500':
          description: Erro interno na execução da exclusão.
  /supplier/{idsupplier}/label:
    get:
      operationId: supplierLabelGet
      tags:
        - Cadastro de Fornecedores
      summary: Gera etiqueta personalizada do fornecedor (ZPL ou PDF)
      description: >-
        Gera a etiqueta de identificação do fornecedor conforme o modelo configurado em `IDCompanyLabel`. Retorna PDF
        (convertido via Labelary) por padrão, ou ZPL bruto quando `Zpl=1` / arquivo `.zpl` quando `Download=1`.
      parameters:
        - name: idsupplier
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do fornecedor.
        - name: IDCompanyLabel
          in: query
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do modelo de etiqueta cadastrado para a empresa.
        - name: Download
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` baixa o arquivo `.zpl` direto.'
        - name: Zpl
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
          description: '`1` retorna o ZPL bruto (válido quando `Download=0`).'
      responses:
        '200':
          description: >-
            Etiqueta gerada. Tipo do conteúdo varia conforme `Download`/`Zpl`: `application/pdf` (padrão),
            `application/epl2` (`Download=1`) ou ZPL puro como texto (`Download=0` + `Zpl=1`).
          content:
            application/pdf:
              schema:
                type: string
                format: binary
            application/epl2:
              schema:
                type: string
                format: binary
            text/plain:
              schema:
                type: string
                description: ZPL bruto.
        '400':
          description: >-
            Falha de validação. Mensagens possíveis: `Parâmetros inválidos, obrigatório informar account e
            IDCompanyLabel`, `Fornecedor não encontrado`, `Problema ao gerar etiqueta`.
        '500':
          description: Erro interno na geração da etiqueta.
  /supplier/{idsupplier}/template:
    get:
      operationId: carrierRateFileTemplateImport
      tags:
        - Cadastro de Fornecedores
      summary: Baixa o arquivo de tabela de frete do transportador
      description: >-
        Devolve, como anexo `.xlsx`, o arquivo de tabela de frete (`CarrierTableUpload`) anteriormente importado para o
        transportador (fornecedor com perfil de carrier). O `idsupplier` no path identifica o transportador e `IDFile`
        aponta o registro específico do upload a recuperar.
      parameters:
        - name: idsupplier
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do fornecedor (transportador).
        - name: IDFile
          in: query
          required: true
          schema:
            type: integer
            format: int64
          description: Identificador do upload da tabela (`IDCarrierTableUpload`).
      responses:
        '200':
          description: Arquivo `.xlsx` da tabela de frete pronto para download.
          content:
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                type: string
                format: binary
        '404':
          description: >-
            Arquivo não encontrado. Mensagens possíveis: `[BadRequest] - Arquivo não encontrado`, `[NotFound] - Arquivo
            não encontrado S3`.
        '500':
          description: Erro interno ao recuperar o arquivo do bucket.
components:
  securitySchemes:
    JWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Token JWT obtido via `POST /auth/token`. Enviado no header `Authorization: Bearer <token>`.'
  schemas:
    ApiErrorMessage:
      type: object
      description: >-
        Formato de resposta de erro. O campo `errorMessage` traz o prefixo (`[BadRequest]` ou `Error:`) seguido da
        descrição.
      properties:
        errorMessage:
          type: string
          example: '[BadRequest] - Fornecedor ou cliente precisa ser preenchido (apenas um dos dois)'
          description: >-
            Texto do erro, sempre começando com o prefixo que define o status (`[BadRequest] - ...` para 400, `Error:
            ...` para 500). O conteúdo após o prefixo é a mensagem específica do sistema.
    CompanyInvoiceListItem:
      type: object
      description: >-
        Linha da lista de NFs (`companyInvoiceList`). Vem de `NfCompany` (`N.*`) mais campos derivados de JOINs com
        `Orders`, `Company` (faturador), `TypeStatusInvoice`, `NfProcessCode`, `NfTpEmis`, `NfFin`, `NfTpNf`, `NfModNf`,
        `OrdersFile`. **Em modo "pedidos pendentes"** (quando `IDStatusInvoice` inclui `0`), a lista também devolve
        linhas vindas de `Orders` sem NF — nessas, todos os campos específicos da NF (`IDNfCompany`, `NfeNumber`,
        `NfeSerie`, `NfeChaveAcesso`, `NfedhEmi`, datas, valores, descrições de tipo) vêm como `null` e o
        `StatusInvoice` literal é `"Pendente"`.
      properties:
        IDNfCompany:
          type: integer
          nullable: true
          description: Id da NF. `null` em linhas de pedido sem NF (modo pendente).
        IDCompany:
          type: integer
          description: Id da empresa dona do pedido (`IDCompany`).
        AccountName:
          type: string
          description: Conta dona do pedido.
        IDCompanyInvoice:
          type: integer
          nullable: true
          description: Id do faturador. `0`/`null` em pedidos pendentes.
        AccountNameInvoice:
          type: string
          nullable: true
          description: Conta do faturador (`AccountName`).
        CompanyNameCorporateNameInvoice:
          type: string
          nullable: true
          description: Razão social do faturador.
        CompanyCpfCnpjInvoice:
          type: string
          nullable: true
          description: CNPJ do faturador.
        IDOrder:
          type: integer
          nullable: true
          description: Id do pedido vinculado (`null` para numerações reservadas via `POST /invoice`).
        Order:
          type: string
          nullable: true
          description: Número do pedido visível ao cliente.
        ConsumerNameCorporateName:
          type: string
          nullable: true
          description: Cliente do pedido.
        ConsumerCpfCnpj:
          type: string
          nullable: true
          description: CPF/CNPJ do cliente.
        NfeNumber:
          type: integer
          nullable: true
          description: Número da NF.
        NfeSerie:
          type: integer
          nullable: true
          description: Série da NF.
        NfeModelo:
          type: integer
          nullable: true
          description: Modelo da NF (`55` NF-e, `65` NFC-e).
        NfModNfDescription:
          type: string
          nullable: true
          description: Descrição do modelo da NF.
        NfeChaveAcesso:
          type: string
          nullable: true
          description: Chave de acesso (44 dígitos).
        NfedhEmi:
          type: string
          format: date-time
          nullable: true
          description: Data/hora de emissão da NF.
        NfecStat:
          type: integer
          nullable: true
          description: Código de status do processo na SEFAZ.
        NfProcessDescription:
          type: string
          nullable: true
          description: Descrição do processo SEFAZ (`NfProcessDescription`).
        NfetpEmis:
          type: integer
          nullable: true
          description: Tipo de emissão.
        NfetpEmisDescription:
          type: string
          nullable: true
          description: Descrição do tipo de emissão (`NfetpEmisDescription`).
        FinNfeDescription:
          type: string
          nullable: true
          description: Descrição da finalidade da NF (`FinNfeDescription`).
        NfTpNfDescription:
          type: string
          nullable: true
          description: Descrição do tipo da NF (`NfTpNfDescription` — Entrada/Saída).
        IDStatusInvoice:
          type: integer
          description: >-
            Status da NF: `0` Pendente, `1` Erro, `2` Enviada, `3` Emitida, `4` Processando, `5` Pendente Conciliação
            EPEC, `6` Erro Conciliação EPEC, `7` Cancelada, `8` Denegada, `9` Inutilizada.
        StatusInvoice:
          type: string
          description: Status textual (`StatusInvoice`); em linhas de pedido sem NF vem literal `"Pendente"`.
        ValueNF:
          type: number
          nullable: true
          description: Valor total da NF (`NfeTotalValue`).
        IDFile:
          type: integer
          nullable: true
          description: Id do arquivo (`IDFile` com `IDTypeFile=2`) — base do download de XML/DANFE.
    CompanyInvoiceCreate:
      type: object
      description: Corpo do `POST /invoice` (botão Gerar Numeração NF).
      required:
        - IDCompanyInvoice
        - NfeSerie
        - NfeNumber
      properties:
        IDCompanyInvoice:
          type: integer
          description: Id do faturador. Precisa ser uma empresa do grupo (`CompanyMain`) da conta autenticada.
        NfeSerie:
          type: integer
          description: Série da NF a registrar.
        NfeNumber:
          type: integer
          description: Número da NF a registrar.
        NfeModelo:
          type: integer
          default: 55
          description: 'Modelo da NF (`55` ou `65`). Default: `55`.'
    ServiceInvoiceListItem:
      type: object
      description: >-
        Linha da lista de NFS-e (`invoiceServiceList`). Vem de `ServiceOrder` com `TypeStatusInvoice`, `IBGECityCode`
        (cidade/UF), `NfsServiceCode` (descrição do código de serviço, quando cadastrado), conta e faturador já
        resolvidos. `NfsValue` e `ValuePaid` são calculados pelo servidor.
      properties:
        IDServiceOrder:
          type: integer
          description: Id interno da NFS-e.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data/hora de criação da NFS-e.
        IDCompany:
          type: integer
          description: Id da empresa dona da NFS-e.
        AccountName:
          type: string
          description: Conta dona da NFS-e.
        IDCompanyInvoice:
          type: integer
          nullable: true
          description: Id do faturador (`IDCompany` quando a NFS-e é faturada pela própria empresa).
        AccountNameInvoice:
          type: string
          nullable: true
          description: Conta do faturador.
        CompanyNameCorporateNameInvoice:
          type: string
          nullable: true
          description: Razão social do faturador.
        CityCode:
          type: integer
          description: Código IBGE da cidade de prestação do serviço.
        CityName:
          type: string
          description: Nome da cidade (`CityName`).
        State:
          type: string
          description: UF da cidade (`State`).
        IDConsumer:
          type: integer
          description: Id do cliente.
        ConsumerNameCorporateName:
          type: string
          nullable: true
          description: Nome/razão social do cliente (gravado na NFS-e).
        ConsumerCpfCnpj:
          type: string
          nullable: true
          description: CPF/CNPJ do cliente (apenas dígitos).
        IDAddress:
          type: integer
          nullable: true
          description: Id do endereço de prestação do serviço.
        NfsDate:
          type: string
          format: date-time
          nullable: true
          description: Data de emissão da NFS-e (preenchida após emissão).
        NfsServiceCode:
          type: string
          nullable: true
          description: Código de serviço municipal aplicado à NFS-e.
        ServiceDescription:
          type: string
          nullable: true
          description: >-
            Descrição do código de serviço (`ServiceDescription`); `null` quando o município não tem o código
            cadastrado.
        IDStatusInvoice:
          type: integer
          description: Status numérico da NFS-e.
        StatusInvoice:
          type: string
          description: Status textual (`StatusInvoice` — Pendente, Erro, Enviada, Emitida, Cancelada…).
        NfsNumber:
          type: integer
          nullable: true
          description: Número da NFS-e atribuído pela prefeitura (após emissão).
        NfsVerificationCode:
          type: string
          nullable: true
          description: Código de verificação da NFS-e na prefeitura.
        NfsValue:
          type: number
          description: 'Valor total: `NfsServiceQuantity * NfsServiceUnitValue`.'
        ValuePaid:
          type: number
          nullable: true
          description: Soma de `Value` das `AccountsPayableReceivable` vinculadas. `null` quando não há contas.
    ServiceInvoiceCreate:
      type: object
      description: Corpo do `POST /invoice-service` (modal Nova NF de Serviço).
      required:
        - IDConsumer
        - NfsServiceCode
        - NfsServiceQuantity
        - NfsServiceUnitValue
      properties:
        IDConsumer:
          type: integer
          description: Id do cliente. Precisa pertencer à empresa autenticada.
        IDAddress:
          type: integer
          nullable: true
          description: Id do endereço de prestação do serviço (do cliente).
        IDOrder:
          type: integer
          nullable: true
          description: Id do pedido de mercadoria vinculado, quando a NFS-e nasce a partir de um pedido.
        IDCompanyInvoice:
          type: integer
          nullable: true
          description: Id do faturador. Quando omitido, usa a própria conta (`IDCompany` resolvido pelo prefix).
        NfsComments:
          type: string
          nullable: true
          description: Comentários/observações da NFS-e.
        NfsServiceCode:
          type: string
          description: Código de serviço municipal.
        NfsServiceQuantity:
          type: integer
          description: Quantidade do serviço prestado.
        NfsServiceUnitValue:
          type: number
          description: Valor unitário do serviço.
        NfsIRRFRetentionValue:
          type: number
          nullable: true
          description: Valor de retenção de IRRF.
        NfsPISRetentionValue:
          type: number
          nullable: true
          description: Valor de retenção de PIS.
        NfsCOFINSRetentionValue:
          type: number
          nullable: true
          description: Valor de retenção de COFINS.
        NfsCSLLRetentionValue:
          type: number
          nullable: true
          description: Valor de retenção de CSLL.
        NfsISSAliquot:
          type: number
          nullable: true
          description: Alíquota do ISS.
    GnreListItem:
      type: object
      description: >-
        Linha da lista de guias GNRE (`orderGnreList`, modo padrão). Vem de `Gnre` com `TypeStatusGnre`,
        `GnreStateCode`, `Orders`, `NfCompany` principal, `Suppliers` (transportadora) e `Company`. Valores numéricos
        chegam como `decimal` e são convertidos para `Number` no sistema; quando `NaN`, vira `0`.
      properties:
        IDGnre:
          type: integer
          description: Id da guia GNRE.
        IDOrder:
          type: integer
          description: Id do pedido amarrado à guia.
        Order:
          type: string
          description: Número do pedido visível ao cliente.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data/hora de criação da guia.
        DueDate:
          type: string
          format: date
          description: Vencimento da guia.
        BarCode:
          type: string
          maxLength: 60
          nullable: true
          description: Código de barras da guia (`BarCode`).
        ReceiptNumber:
          type: string
          maxLength: 45
          nullable: true
          description: Número do protocolo após emissão (`ReceiptNumber`).
        RevenueCode:
          type: integer
          description: Código de receita da UF (`RevenueCode`).
        Description:
          type: string
          nullable: true
          description: Descrição do código de receita (`Description`) para o estado de envio.
        StatusProcessCode:
          type: integer
          nullable: true
          description: Código do status atual do processamento da guia (`StatusCode`).
        StatusDescription:
          type: string
          nullable: true
          description: Descrição do status atual (`StatusDescription`).
        GnreValue:
          type: number
          description: Valor principal da guia.
        GnreInterest:
          type: number
          description: Juros.
        GnreRestatement:
          type: number
          description: Correção/atualização monetária.
        GnrePenalty:
          type: number
          description: Multa.
        GnreTotalValue:
          type: number
          description: '`GnreValue + GnreInterest + GnreRestatement + GnrePenalty` (computado no servidor).'
        Comments:
          type: string
          nullable: true
          description: Comentários livres da guia.
        ShippingState:
          type: string
          description: UF de destino do pedido.
        NfeNumber:
          type: string
          nullable: true
          description: Número da NF principal vinculada (`NfeNumber`).
        NfeSerie:
          type: string
          nullable: true
          description: Série da NF principal.
        NfedhEmi:
          type: string
          format: date-time
          nullable: true
          description: Data de emissão da NF principal.
        IDStatusInvoice:
          type: integer
          nullable: true
          description: Status numérico da NF principal.
        StatusInvoice:
          type: string
          description: Status textual da NF (`StatusInvoice`); `"Pendente"` quando o pedido ainda não tem status atribuído.
        IDStatusOrder:
          type: integer
          description: Status numérico do pedido.
        StatusOrder:
          type: string
          description: Status do pedido para a empresa (`StatusOrder`).
        IDCarrier:
          type: integer
          nullable: true
          description: Id da transportadora do pedido.
        SupplierNameCorporateName:
          type: string
          nullable: true
          description: Razão social da transportadora (`SupplierNameCorporateName`).
        AccountName:
          type: string
          description: Conta dona do pedido.
        AccountNameInvoice:
          type: string
          description: Conta do faturador (`IDCompanyInvoice`).
        CompanyCpfCnpjInvoice:
          type: string
          description: CNPJ do faturador.
        OrderFrom:
          type: string
          nullable: true
          description: Canais de origem do pedido. Quando o pedido vem de mais de um canal, vem como lista separada por vírgula.
        ValueOrder:
          type: number
          description: 'Valor total do pedido: soma de `PriceSellingTotal` + `ValueShipping` + `NfeAccessoryExpenses`.'
    DifalSummaryItem:
      type: object
      description: >-
        Linha da apuração DIFAL (`orderGnreList` com `Summary=1`). Uma linha por pedido com NF principal modelo 55. O
        sinal de `ValueOrder`, `NfeValueIcmsUfDest` e `NfeValueFcpUfDest` segue `NfeType` (positivo para `NfeType=1`
        saída, negativo para `NfeType=0` entrada).
      properties:
        IDOrder:
          type: integer
          description: Id do pedido.
        Order:
          type: string
          description: Número do pedido.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data/hora de criação do pedido.
        ConsumerNameCorporateName:
          type: string
          description: Nome/razão social do cliente.
        ShippingState:
          type: string
          description: UF de destino.
        NfeType:
          type: integer
          enum:
            - 0
            - 1
          description: 'Tipo da NF: `0` entrada, `1` saída. Define o sinal dos valores monetários.'
        NfeNumber:
          type: string
          nullable: true
          description: Número da NF principal.
        NfeSerie:
          type: string
          nullable: true
          description: Série da NF principal.
        NfedhEmi:
          type: string
          format: date-time
          nullable: true
          description: Emissão da NF.
        NfeChaveAcesso:
          type: string
          nullable: true
          description: Chave de acesso da NF (44 dígitos).
        IDStatusInvoice:
          type: integer
          nullable: true
          description: Status numérico da NF.
        StatusInvoice:
          type: string
          nullable: true
          description: Status textual da NF.
        GnreStatusDescription:
          type: string
          nullable: true
          description: Status atual da guia GNRE deste pedido (`StatusDescription`); `null` quando ainda não há guia gerada.
        CompanyIntegrationName:
          type: string
          description: Nome da integração de origem (`CompanyIntegrationName`).
        IDStatusOrder:
          type: integer
          description: Status numérico do pedido.
        StatusOrder:
          type: string
          description: Status textual do pedido para a empresa.
        TypeOrder:
          type: string
          description: Nome do tipo de pedido.
        AccountName:
          type: string
          description: Conta dona do pedido.
        AccountNameInvoice:
          type: string
          description: Conta do faturador.
        CompanyCpfCnpjInvoice:
          type: string
          description: CNPJ do faturador.
        ShippingDate:
          type: string
          format: date-time
          nullable: true
          description: Data de envio (máximo de `ShippingDate` do pedido).
        OrderFrom:
          type: string
          nullable: true
          description: Canais de origem do pedido (concatenados).
        ValueOrder:
          type: number
          description: Valor total do pedido (com sinal por `NfeType`).
        NfeValueIcmsUfDest:
          type: number
          description: Soma de `NfeIcmsUfDestValue` (DIFAL ICMS) dos itens do pedido. Sinal por `NfeType`.
        NfeValueFcpUfDest:
          type: number
          description: Soma de `NfeFcpUfDestValue` (FCP) dos itens do pedido. Sinal por `NfeType`.
        NfTpNfDescription:
          type: string
          description: Descrição do tipo da NFe (`NfTpNfDescription`).
    OrderEventLogItem:
      type: object
      description: >-
        Linha do log de pedidos (`ordersLogList`). Cada item traz o evento (`EventDescription`), o usuário que executou
        (`User`), o pedido (`Order`) e a conta (`Company`) já resolvidos.
      properties:
        IDOrderEvents:
          type: integer
          description: Id único do registro do log.
        IDOrder:
          type: integer
          description: Código interno do pedido (`IDOrder`).
        Order:
          type: string
          description: Número do pedido visível ao cliente (`Order`).
        IDEvent:
          type: integer
          description: >-
            Id do tipo de ação (`IDEvent`). Ex.: `0` Pedido criado, `2` Finalizar pedido, `19` Cancelar pedido, `35`
            Alteração status. Catálogo em `support data/TypeOrderEvents.csv`.
        EventDescription:
          type: string
          description: 'Texto do tipo da ação (ex.: "Pedido criado", "Cancelar pedido").'
        Header:
          type: integer
          enum:
            - 0
            - 1
            - 2
          description: 'Resultado: `0` Erro/Problema, `1` Sucesso, `2` Inativo.'
        Status:
          type: string
          enum:
            - Erro
            - Sucesso
            - Inativo
          description: >-
            Texto correspondente ao `Header` — computado pelo `SELECT` (`Header=1 → Sucesso, 2 → Inativo, demais →
            Erro`).
        RecordTimestamp:
          type: string
          format: date-time
          description: Momento em que o evento foi gravado.
        RecordUserCreated:
          type: integer
          description: Id do usuário que disparou a ação (`IDUser`).
        Login:
          type: string
          description: 'Identificação do usuário: `UserName - Login`; quando `UserName` é nulo/vazio, vem só `Login`.'
        Comments:
          type: string
          nullable: true
          description: Texto livre gravado pela operação de origem (pode trazer corpo de erro / detalhe da ação).
        AccountName:
          type: string
          description: Identificador da conta da empresa dona do pedido.
    BankAccount:
      type: object
      description: Conta bancária da empresa.
      properties:
        IDBankAccount:
          type: integer
          format: int32
          description: Identificador da conta bancária.
        Bank:
          type: string
          maxLength: 100
          description: Nome do banco.
        BankNumber:
          type: string
          maxLength: 3
          description: Código Febraban do banco.
        BankRouting:
          type: string
          maxLength: 45
          nullable: true
          description: Agência.
        AccountNumber:
          type: string
          maxLength: 45
          nullable: true
          description: Número da conta.
        MainIncome:
          type: integer
          format: int32
          description: Indica se é a conta principal de recebimento (0/1).
        MainPayment:
          type: integer
          format: int32
          description: Indica se é a conta principal de pagamento (0/1).
        IDCompany:
          type: integer
          format: int32
          description: Identificador da empresa dona da conta.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora de cadastro.
        AccountNumberDigit:
          type: string
          maxLength: 1
          nullable: true
          description: Dígito verificador do número da conta.
        Status:
          type: integer
          format: int32
          description: 'Situação da conta: 0=inativa, 1=ativa.'
        IDCompanyInvoice:
          type: integer
          format: int32
          description: Identificador da empresa faturadora.
        IDCompanyIntegration:
          type: integer
          format: int32
          nullable: true
          description: Identificador da integração bancária, quando houver.
        TefTerminal:
          type: string
          maxLength: 45
          nullable: true
          description: Terminal TEF associado.
        IDTypeOrder:
          type: integer
          format: int32
          nullable: true
          description: Identificador do tipo de pedido associado.
        IDCompanyIntegrationPix:
          type: integer
          format: int32
          nullable: true
          description: Identificador da integração de Pix vinculada à conta.
    BankAccountListItem:
      allOf:
        - $ref: '#/components/schemas/BankAccount'
        - type: object
          description: >-
            Item retornado por `GET /accounts/bank-account` — campos da conta bancária acrescidos de nomes resolvidos e
            saldos calculados.
          properties:
            AccountName:
              type: string
              description: Subdomínio (identificador) da empresa dona da conta.
            AccountNameInvoice:
              type: string
              nullable: true
              description: Subdomínio do faturador, quando houver.
            CompanyNameCorporateNameInvoice:
              type: string
              nullable: true
              description: Razão social do faturador.
            CompanyIntegrationName:
              type: string
              nullable: true
              description: Nome da integração bancária, quando houver.
            TypeOrder:
              type: string
              nullable: true
              description: Descrição do tipo de pedido associado, quando houver.
            CompanyIntegration:
              type: string
              nullable: true
              description: Texto formatado com o tipo e nome da integração bancária.
            Balance:
              type: number
              description: >-
                Saldo atual da conta: soma de entradas menos saídas até o momento da consulta. Sempre numérico (zero
                quando não há lançamentos).
            BalanceForecast:
              type: number
              description: >-
                Saldo previsto até `DateForecast`: saldo atual mais os lançamentos previstos cuja conta de previsão é
                esta.
            CompanyIntegrationPix:
              type: string
              nullable: true
              description: Texto formatado com o tipo e nome da integração de Pix vinculada à conta, quando houver.
    AccountsPayableBase:
      type: object
      description: Campos comuns de uma conta a pagar.
      properties:
        Comments:
          type: string
          maxLength: 2000
          nullable: true
          description: Observações.
        DateCompetence:
          type: string
          format: date
          nullable: true
          description: Data de competência. Quando enviada como string vazia, é tratada como ausente.
        DateDocument:
          type: string
          format: date
          nullable: true
          description: Data do documento. Quando enviada como string vazia, é tratada como ausente.
        DateDue:
          type: string
          format: date
          description: Data de vencimento. Obrigatório.
        DocumentNumber:
          type: string
          maxLength: 200
          nullable: true
          description: Número do documento.
        IDSupplier:
          type: integer
          format: int32
          nullable: true
          description: Identificador do fornecedor. Não pode vir junto com `IDConsumer`.
        IDConsumer:
          type: integer
          format: int32
          nullable: true
          description: Identificador do cliente. Não pode vir junto com `IDSupplier`.
        IDTypePayment:
          type: integer
          format: int32
          nullable: true
          description: Identificador do tipo de pagamento.
        IDTypeDocument:
          type: integer
          format: int32
          nullable: true
          description: Identificador do tipo de documento.
        IDTypeAccountPayableReceivable:
          type: integer
          format: int32
          nullable: true
          description: Identificador do plano de contas.
        Scheduled:
          type: integer
          format: int32
          nullable: true
          description: Indica se a conta está agendada para pagamento automático (0/1). Padrão 0.
        Value:
          type: number
          description: >-
            Valor do título, com duas casas decimais. Pode chegar como string em alguns clientes — confirme o parse no
            consumidor.
        IDBankAccountForecast:
          type: integer
          format: int32
          nullable: true
          description: Identificador da conta bancária prevista para o pagamento.
        BankSlipBarCode:
          type: string
          maxLength: 2000
          nullable: true
          description: Código de barras do boleto.
        ValueDiscount:
          type: number
          nullable: true
          description: Valor de desconto, com duas casas decimais.
        ValueInterest:
          type: number
          nullable: true
          description: Valor de juros, com duas casas decimais.
        ValuePenalty:
          type: number
          nullable: true
          description: Valor de multa, com duas casas decimais.
        IDCompanyInvoice:
          type: integer
          format: int32
          nullable: true
          description: Identificador da empresa faturadora. Quando omitido, assume a empresa autenticada.
        Forecast:
          type: integer
          format: int32
          description: Indica se o título é uma previsão (0/1). Padrão 0.
    TaxRetentionItem:
      type: object
      description: Item de retenção de imposto. Cada retenção gera uma conta a pagar filha vinculada à conta principal.
      required:
        - IDSupplier
        - Value
        - DateDue
      properties:
        IDSupplier:
          type: integer
          format: int32
          description: Identificador do fornecedor da retenção.
        Value:
          type: number
          description: Valor da retenção. A soma de todas as retenções é abatida do `Value` da conta principal.
        DateDue:
          type: string
          format: date
          description: Data de vencimento da retenção.
    AccountsPayableCreate:
      allOf:
        - $ref: '#/components/schemas/AccountsPayableBase'
        - type: object
          description: >-
            Corpo do `POST /accounts/payable`. `DateDue`, `Value`, `IDTypeDocument` e `IDTypeAccountPayableReceivable`
            são obrigatórios na prática — quando ausentes, a criação falha.
          required:
            - DateDue
            - Value
            - IDTypeDocument
            - IDTypeAccountPayableReceivable
          properties:
            IDOrder:
              type: integer
              format: int32
              nullable: true
              description: Identificador do pedido associado, quando houver.
            Taxes:
              type: array
              description: Retenções de imposto.
              items:
                $ref: '#/components/schemas/TaxRetentionItem'
            Holiday:
              type: integer
              enum:
                - 1
                - 2
              nullable: true
              description: >-
                Como tratar feriado e fim de semana nas datas da recorrência: 1=antecipar, 2=postergar; quando omitido,
                não ajusta.
            PeriodType:
              type: integer
              enum:
                - 1
                - 2
                - 3
              nullable: true
              description: 'Tipo de recorrência: 1=mensal, 2=semanal, 3=personalizado.'
            QuantityRepeat:
              type: integer
              nullable: true
              description: Número total de ocorrências (incluindo a inicial).
            PeriodTypeValue:
              type: integer
              nullable: true
              description: >-
                Quando `PeriodType=1`: dia do mês (1-31). Quando `2`: dia da semana (0-6). Quando `3`: intervalo em dias
                entre ocorrências.
    AccountsPayableUpdate:
      type: object
      description: >-
        Corpo do `PUT /accounts/payable/{idaccountpayable}`. Todos os campos são opcionais; apenas os enviados são
        atualizados (comportamento de atualização parcial).
      properties:
        Comments:
          type: string
          maxLength: 2000
          nullable: true
          description: Observações.
        DateCompetence:
          type: string
          format: date
          nullable: true
          description: Data de competência.
        DateDocument:
          type: string
          format: date
          nullable: true
          description: Data do documento.
        DateDue:
          type: string
          format: date
          description: Data de vencimento.
        DocumentNumber:
          type: string
          maxLength: 200
          nullable: true
          description: Número do documento.
        IDSupplier:
          type: integer
          format: int32
          nullable: true
          description: Identificador do fornecedor. Não pode vir junto com `IDConsumer`.
        IDConsumer:
          type: integer
          format: int32
          nullable: true
          description: Identificador do cliente. Não pode vir junto com `IDSupplier`.
        IDTypePayment:
          type: integer
          format: int32
          nullable: true
          description: Identificador do tipo de pagamento.
        IDTypeDocument:
          type: integer
          format: int32
          nullable: true
          description: Identificador do tipo de documento.
        IDTypeAccountPayableReceivable:
          type: integer
          format: int32
          nullable: true
          description: Identificador do plano de contas.
        Scheduled:
          type: integer
          format: int32
          nullable: true
          description: Indica se a conta está agendada (0/1).
        Value:
          type: number
          description: Valor do título.
        IDBankAccountForecast:
          type: integer
          format: int32
          nullable: true
          description: Identificador da conta bancária prevista para o pagamento. O valor `"0"` é ignorado.
        BankSlipBarCode:
          type: string
          maxLength: 2000
          nullable: true
          description: Código de barras do boleto.
        ValueDiscount:
          type: number
          nullable: true
          description: Valor de desconto.
        ValueInterest:
          type: number
          nullable: true
          description: Valor de juros.
        ValuePenalty:
          type: number
          nullable: true
          description: Valor de multa.
        Forecast:
          type: integer
          format: int32
          description: Indica se o título é uma previsão (0/1).
        IDCompanyInvoice:
          type: integer
          format: int32
          nullable: true
          description: Identificador da empresa faturadora.
    CashFlowSummaryItem:
      type: object
      description: >-
        Item do modo Resumo de `GET /accounts/cash-flow`. Cada linha consolida um plano de contas em um mês (ou dia,
        quando `GroupBy=day`) com o total previsto (`TotalValue`), o total realizado (`ValuePaid`) e a quantidade de
        lançamentos. Considera o ano inteiro definido em `Year` e exclui contas com status **Não lançado**.
      properties:
        Month:
          type: integer
          description: Mês do agrupamento (1–12), extraído do vencimento.
        Year:
          type: integer
          description: Ano do agrupamento, extraído do vencimento.
        Date:
          type: string
          format: date-time
          description: >-
            Data sintética do início do mês do agrupamento, no fuso da API. Usada pela UI para ordenar e formatar como
            `MMM/yyyy`.
        TotalValue:
          type: number
          description: >-
            Total **previsto** no agrupamento. Já vem assinado: contas a pagar entram negativas, contas a receber
            positivas.
        TotalQty:
          type: integer
          description: Quantidade de títulos no agrupamento.
        ValuePaid:
          type: number
          description: >-
            Total **realizado** no agrupamento — soma dos lançamentos do extrato dos títulos do grupo. Assinado do mesmo
            modo que `TotalValue`.
        IDTypeAccount:
          type: integer
          enum:
            - 0
            - 1
          description: 'Tipo do lançamento: `0` entrada (a receber), `1` saída (a pagar).'
        IDTypeAccountPayableReceivable:
          type: integer
          nullable: true
          description: Identificador do plano de contas do agrupamento.
        IDTypeAccountPaybleFather:
          type: integer
          nullable: true
          description: Identificador do plano de contas pai (quando o agrupamento é uma sub-categoria).
        TypeAccountPaybleDescription:
          type: string
          nullable: true
          description: Descrição do plano de contas do agrupamento.
        CategoryTree:
          type: array
          nullable: true
          items:
            type: string
          description: >-
            Caminho completo do plano de contas, da raiz até a folha (ex.: `["Despesas", "Operacionais", "Aluguel"]`).
            Usado pela UI como níveis do pivot.
        IDCompanyInvoice:
          type: integer
          nullable: true
          description: Identificador da empresa faturadora (filial) do agrupamento.
    CashFlowDetailItem:
      type: object
      description: >-
        Item do modo Detalhe de `GET /accounts/cash-flow?Type=Detail`. Cada linha é um título individual
        (`AccountsPayableReceivable`) que compõe a célula do resumo. Distinto e ordenado por vencimento.
      properties:
        AccountName:
          type: string
          description: Subdomínio (`accountname`) da empresa dona do título.
        IDAccountPayableReceivable:
          type: integer
          description: Identificador do título.
        IDStatusAccountPayableReceivable:
          type: integer
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
          description: >-
            Status do título: 0=Aberto, 1=Vencido, 2=Pago, 3=Pago Parcialmente, 4=Não lançado, 5=Pago com acréscimo,
            6=Vence hoje.
        StatusAccountPayableReceivable:
          type: string
          description: Descrição amigável do status (correspondente ao `IDStatusAccountPayableReceivable`).
        DateCompetence:
          type: string
          format: date
          nullable: true
          description: Data de competência do título.
        DateDue:
          type: string
          format: date
          description: Data de vencimento do título.
        IDTypeAccount:
          type: integer
          enum:
            - 0
            - 1
          description: 'Tipo do lançamento: `0` entrada (a receber), `1` saída (a pagar).'
        IDTypeAccountPayableReceivable:
          type: integer
          nullable: true
          description: Identificador do plano de contas do título.
        TypeAccountPaybleDescription:
          type: string
          nullable: true
          description: Descrição do plano de contas do título.
        CategoryTree:
          type: string
          nullable: true
          description: >-
            Caminho completo do plano de contas em texto, separado por ` -> ` (ex.: `Despesas -> Operacionais ->
            Aluguel`).
        IDTypePayment:
          type: integer
          nullable: true
          description: Identificador do tipo de pagamento (Boleto, PIX, etc.).
        TypePaymentDescription:
          type: string
          nullable: true
          description: Descrição do tipo de pagamento.
        Value:
          type: number
          description: 'Valor **previsto** do título. Já vem assinado: a pagar entra negativo, a receber positivo.'
        ValuePaid:
          type: number
          description: Valor **realizado** do título — soma dos lançamentos do extrato. Assinado do mesmo modo que `Value`.
        SupplierNameCorporateName:
          type: string
          nullable: true
          description: Nome ou razão social do fornecedor (ou cliente, quando o título é a receber).
    AccountsPayableListItem:
      type: object
      description: >-
        Item retornado por `GET /accounts/payable` e `POST /accounts/payable`. Inclui campos próprios da conta,
        descrições resolvidas dos relacionamentos, totais já calculados em `Number` (`ValueTotal`, `ValuePaid`,
        `ValuePaymentPending`) e dados resumidos do banco de pagamento.
      properties:
        AccountName:
          type: string
          description: Subdomínio da empresa dona da conta.
        IDAccountPayableReceivable:
          type: integer
          format: int32
          description: Identificador do título.
        IDAccountPayableReceivableMain:
          type: integer
          format: int32
          nullable: true
          description: Identificador da conta-raiz da série de recorrência.
        IDStatusAccountPayableReceivable:
          type: integer
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
          nullable: true
          description: >-
            Status do título: 0=Aberto, 1=Vencido, 2=Pago, 3=Pago Parcialmente, 4=Não lançado, 5=Pago com acréscimo,
            6=Vence hoje.
        StatusAccountPayableReceivable:
          type: string
          nullable: true
          description: Descrição textual do status correspondente a `IDStatusAccountPayableReceivable`.
        Comments:
          type: string
          maxLength: 2000
          nullable: true
          description: Observações.
        DateCompetence:
          type: string
          format: date
          nullable: true
          description: Data de competência.
        DateDocument:
          type: string
          format: date
          nullable: true
          description: Data do documento.
        DateDue:
          type: string
          format: date
          description: Data de vencimento.
        DocumentNumber:
          type: string
          maxLength: 200
          nullable: true
          description: Número do documento.
        RecordTimestamp:
          type: string
          format: date-time
          nullable: true
          description: Data e hora de criação do título.
        IDSupplier:
          type: integer
          format: int32
          nullable: true
          description: Identificador do fornecedor.
        IDConsumer:
          type: integer
          format: int32
          nullable: true
          description: Identificador do cliente (quando o título nasce de uma devolução/estorno).
        SupplierNameCorporateName:
          type: string
          nullable: true
          description: Razão social ou nome do fornecedor ou cliente vinculado (a coluna serve aos dois conforme `IDConsumer`).
        IDTypeAccount:
          type: integer
          enum:
            - 0
            - 1
          description: 'Tipo de conta: 0=entrada (a receber), 1=saída (a pagar).'
        IDTypeAccountPayableReceivable:
          type: integer
          format: int32
          nullable: true
          description: Identificador do plano de contas.
        TypeAccountPaybleDescription:
          type: string
          nullable: true
          description: Descrição do plano de contas.
        IDTypeDocument:
          type: integer
          format: int32
          nullable: true
          description: Identificador do tipo de documento.
        TypeDocument:
          type: string
          nullable: true
          description: Descrição do tipo de documento.
        IDTypePayment:
          type: integer
          format: int32
          nullable: true
          description: Identificador do tipo de pagamento.
        TypePaymentDescription:
          type: string
          nullable: true
          description: Descrição do tipo de pagamento.
        IDPurchase:
          type: integer
          format: int32
          nullable: true
          description: Identificador da compra (recebimento) associada.
        IDStatusPurchase:
          type: integer
          format: int32
          nullable: true
          description: Status da compra associada.
        IDOrder:
          type: integer
          format: int32
          nullable: true
          description: Identificador interno do pedido vinculado.
        Scheduled:
          type: integer
          format: int32
          nullable: true
          description: Indica se o título está agendado para pagamento automático (0/1).
        Forecast:
          type: integer
          format: int32
          description: Indica se o título é uma previsão (1) ou um lançamento real (0).
        BankSlipBarCode:
          type: string
          maxLength: 2000
          nullable: true
          description: Código de barras do boleto.
        IDBankAccountForecast:
          type: integer
          format: int32
          nullable: true
          description: Identificador da conta bancária prevista para o pagamento.
        BankForecast:
          type: string
          nullable: true
          description: Nome do banco da conta prevista, eventualmente concatenado com o número da conta.
        BankForecastAccountNumber:
          type: string
          nullable: true
          description: Número da conta bancária prevista.
        BankPayment:
          type: string
          nullable: true
          description: Bancos onde os pagamentos foram lançados (lista concatenada quando há múltiplos).
        DateLastPayment:
          type: string
          format: date-time
          nullable: true
          description: Data e hora do último pagamento lançado.
        Value:
          type: number
          description: Valor base do título (já convertido para número; zero quando inválido).
        ValueDiscount:
          type: number
          description: Valor de desconto (zero quando inválido).
        ValueInterest:
          type: number
          description: Valor de juros (zero quando inválido).
        ValuePenalty:
          type: number
          description: Valor de multa (zero quando inválido).
        ValueTotal:
          type: number
          description: 'Valor total efetivo: `Value + ValuePenalty + ValueInterest - ValueDiscount`.'
        ValuePaid:
          type: number
          description: Soma dos pagamentos já lançados.
        ValuePaymentPending:
          type: number
          description: 'Saldo devedor: `ValueTotal - ValuePaid`.'
        TotalvNF:
          type: number
          nullable: true
          description: Valor total da nota fiscal de origem, quando a conta está vinculada a uma compra.
        DocumentPdf:
          type: integer
          enum:
            - 0
            - 1
          description: Indica se há arquivo PDF anexado.
        DocumentXml:
          type: integer
          enum:
            - 0
            - 1
          description: Indica se há arquivo XML anexado.
        DocumentBankSlip:
          type: integer
          enum:
            - 0
            - 1
          description: Indica se há boleto anexado.
        DocumentPayment:
          type: integer
          enum:
            - 0
            - 1
          description: Indica se há comprovante de pagamento anexado.
        IDCompanyInvoice:
          type: integer
          format: int32
          nullable: true
          description: Identificador da empresa faturadora.
        AccountNameInvoice:
          type: string
          nullable: true
          description: Subdomínio da empresa faturadora.
        CompanyNameCorporateNameInvoice:
          type: string
          nullable: true
          description: Razão social da empresa faturadora.
        CompanyIntegration:
          type: string
          nullable: true
          description: Texto formatado com o tipo e nome da integração.
        AccountsPayableReceivableCostCenter:
          type: string
          nullable: true
          description: >-
            Descrições dos centros de custo vinculados ao título, concatenadas e separadas por vírgula (ex.:
            "Administrativo, Marketing"). `null` quando o título não tem centro de custo vinculado.
    AccountsPayableDetail:
      type: object
      description: >-
        Resposta detalhada do `GET /accounts/payable/{idaccountpayable}` (também o corpo do `PUT` após atualização).
        Inclui campos próprios da conta, descrições resolvidas dos relacionamentos (fornecedor, cliente, tipo de
        documento, tipo de pagamento, plano de contas) e listas auxiliares de arquivos, pagamentos, histórico e centros
        de custo. Campos vindos de relacionamentos opcionais podem ser nulos quando não há vínculo.
      properties:
        Comments:
          type: string
          maxLength: 2000
          nullable: true
          description: Observações.
        DateCompetence:
          type: string
          format: date
          nullable: true
          description: Data de competência.
        DateDocument:
          type: string
          format: date
          nullable: true
          description: Data do documento.
        DateDue:
          type: string
          format: date
          description: Data de vencimento.
        DocumentNumber:
          type: string
          maxLength: 200
          nullable: true
          description: Número do documento.
        IDAccountPayableReceivable:
          type: integer
          format: int32
          description: Identificador da conta a pagar.
        IDStatusAccountPayableReceivable:
          type: integer
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
          nullable: true
          description: >-
            Status do título: 0=Aberto, 1=Vencido, 2=Pago, 3=Pago Parcialmente, 4=Não lançado, 5=Pago com acréscimo,
            6=Vence hoje. Padrão 0.
        IDSupplier:
          type: integer
          format: int32
          nullable: true
          description: Identificador do fornecedor.
        IDTypeAccount:
          type: integer
          enum:
            - 0
            - 1
          description: 'Tipo de conta: 0=entrada (a receber), 1=saída (a pagar).'
        IDTypeAccountPayableReceivable:
          type: integer
          format: int32
          nullable: true
          description: Identificador do plano de contas.
        IDTypeDocument:
          type: integer
          format: int32
          nullable: true
          description: Identificador do tipo de documento.
        IDTypePayment:
          type: integer
          format: int32
          nullable: true
          description: Identificador do tipo de pagamento.
        RecordTimestamp:
          type: string
          format: date-time
          nullable: true
          description: Data e hora de criação.
        Scheduled:
          type: integer
          format: int32
          nullable: true
          description: Indica se a conta está agendada (0/1).
        Value:
          type: number
          description: Valor do título, já convertido para número (zero quando inválido).
        IDBankAccountForecast:
          type: integer
          format: int32
          nullable: true
          description: Identificador da conta bancária prevista.
        IDOrder:
          type: integer
          format: int32
          nullable: true
          description: Identificador do pedido associado.
        IDCompanyInvoice:
          type: integer
          format: int32
          nullable: true
          description: Identificador da empresa faturadora.
        IDAccountPayableReceivableMain:
          type: integer
          format: int32
          nullable: true
          description: Identificador da conta-raiz da série de recorrência.
        StatusAccountPayableReceivable:
          type: string
          nullable: true
          description: Descrição textual do status.
        BankSlipBarCode:
          type: string
          maxLength: 2000
          nullable: true
          description: Código de barras do boleto.
        Forecast:
          type: integer
          format: int32
          description: Indica se o título é uma previsão (0/1).
        ValueDiscount:
          type: number
          description: Valor de desconto (zero quando inválido).
        ValueInterest:
          type: number
          description: Valor de juros (zero quando inválido).
        ValuePenalty:
          type: number
          description: Valor de multa (zero quando inválido).
        ValueTotal:
          type: number
          description: 'Valor total efetivo: `Value + ValuePenalty + ValueInterest - ValueDiscount`.'
        TypeAccountPaybleDescription:
          type: string
          nullable: true
          description: Descrição do plano de contas.
        TypeDocument:
          type: string
          nullable: true
          description: Descrição do tipo de documento.
        TypePaymentDescription:
          type: string
          nullable: true
          description: Descrição do tipo de pagamento.
        SupplierNameCorporateName:
          type: string
          nullable: true
          description: Razão social ou nome do fornecedor.
        IDConsumer:
          type: integer
          format: int32
          nullable: true
          description: Identificador do cliente.
        ConsumerNameCorporateName:
          type: string
          nullable: true
          description: Razão social ou nome do cliente.
        DocumentPdf:
          type: integer
          enum:
            - 0
            - 1
          description: Indica se há arquivo PDF anexado.
        DocumentXml:
          type: integer
          enum:
            - 0
            - 1
          description: Indica se há arquivo XML anexado.
        DocumentBankSlip:
          type: integer
          enum:
            - 0
            - 1
          description: Indica se há boleto anexado.
        DocumentPayment:
          type: integer
          enum:
            - 0
            - 1
          description: Indica se há comprovante de pagamento anexado.
        TotalvNF:
          type: number
          nullable: true
          description: Valor total da nota fiscal de origem, quando a conta está vinculada a uma compra.
        Bank:
          type: string
          nullable: true
          description: Nome do banco da conta de previsão, podendo vir concatenado com o número da conta.
        BankForecastAccountNumber:
          type: string
          nullable: true
          description: Número da conta bancária de previsão.
        AccountNameInvoice:
          type: string
          nullable: true
          description: Subdomínio da empresa faturadora.
        CompanyNameCorporateNameInvoice:
          type: string
          nullable: true
          description: Razão social da empresa faturadora.
        CompanyIntegration:
          type: string
          nullable: true
          description: Texto formatado com o tipo e nome da integração.
        Files:
          type: array
          description: Arquivos anexados à conta. Inclui GNREs (quando houver) e demais arquivos (PDF, XML, boleto, comprovante).
          items:
            $ref: '#/components/schemas/FileAttachment'
        Payments:
          type: array
          description: Lançamentos do extrato bancário vinculados a esta conta.
          items:
            $ref: '#/components/schemas/BankStatementPayment'
        AccountsPayableReceivableLog:
          type: array
          description: Histórico de alterações da conta, em ordem decrescente de data.
          items:
            $ref: '#/components/schemas/AccountsPayableLogEntry'
        AccountsPayableReceivableCostCenter:
          type: array
          description: Centros de custo com o valor rateado a partir do total da conta.
          items:
            $ref: '#/components/schemas/AccountsPayableCostCenter'
        RelatedAccountsPayableReceivable:
          type: array
          nullable: true
          description: Contas filhas geradas por retenção de impostos, com totais já calculados.
          items:
            $ref: '#/components/schemas/RelatedAccountsPayable'
    FileAttachment:
      type: object
      description: >-
        Arquivo anexado a uma conta a pagar. Pode representar uma GNRE ou um arquivo comum (PDF, XML, boleto,
        comprovante de pagamento). As ramificações compartilham as chaves abaixo, com algumas variações nos
        identificadores.
      properties:
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora do anexo.
        IDFile:
          type: integer
          format: int32
          description: Identificador do arquivo. Para GNREs, é igual ao `IDGnre`.
        IDTypeFile:
          type: string
          description: >-
            Identificador do tipo de arquivo, como string. Para GNRE, vem fixado como `"1"`; para os demais, corresponde
            ao tipo cadastrado.
        TypeFile:
          type: string
          description: Descrição do tipo de arquivo. `"GNRE"` para guia GNRE; para os demais, o nome do tipo cadastrado.
        FileUrl:
          type: string
          description: URL completa para baixar o arquivo, já com token de acesso embutido.
        IDGnre:
          type: integer
          format: int32
          description: Identificador da GNRE. Presente apenas em itens do tipo GNRE.
        IDAccountPayableReceivable:
          type: integer
          format: int32
          description: Identificador da conta a pagar dona do arquivo. Presente apenas em itens que não são GNRE.
    BankStatementPayment:
      type: object
      description: Lançamento do extrato bancário vinculado a uma conta a pagar.
      properties:
        DateTransactionTimestamp:
          type: string
          format: date-time
          description: Data e hora da transação (formato ISO 8601 com sufixo Z).
        IDBankAccount:
          type: integer
          format: int32
          description: Identificador da conta bancária onde o lançamento foi registrado.
        IDBankStatement:
          type: integer
          format: int32
          description: Identificador do lançamento no extrato.
        TransactionDescription:
          type: string
          maxLength: 100
          nullable: true
          description: Descrição da transação.
        TransactionDocument:
          type: string
          maxLength: 45
          nullable: true
          description: Documento da transação (TID, NSU ou similar).
        Value:
          type: number
          description: Valor lançado, com duas casas decimais.
        Bank:
          type: string
          description: Nome do banco da conta onde a transação foi registrada.
    AccountsPayableLogEntry:
      type: object
      description: Entrada do histórico de alterações de uma conta a pagar.
      properties:
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora da alteração (formato ISO 8601 com sufixo Z).
        IDAccountsPayableReceivableLog:
          type: integer
          format: int32
          description: Identificador da entrada do histórico.
        RecordUserCreated:
          type: integer
          format: int32
          description: Identificador do usuário responsável pela alteração.
        Data:
          type: string
          maxLength: 500
          nullable: true
          description: >-
            Resumo da alteração em formato `chave: "DE: <valor> PARA: <valor>"` (string JSON serializada com os campos
            modificados).
        Login:
          type: string
          description: Login do usuário que fez a alteração.
    AccountsPayableCostCenter:
      type: object
      description: Centro de custo associado a uma conta a pagar, com a fração rateada do valor total.
      properties:
        IDTypeCostCenter:
          type: integer
          format: int32
          description: Identificador do tipo de centro de custo.
        ValueRatio:
          type: number
          description: 'Fração do valor total alocada a este centro de custo (decimal com 4 casas, ex.: `0.3500` = 35%).'
        TypeCostCenter:
          type: string
          maxLength: 100
          description: Nome do centro de custo.
        ExternalCode:
          type: string
          maxLength: 45
          nullable: true
          description: Código externo do centro de custo, quando integrado a um sistema contábil.
        Value:
          type: number
          description: 'Valor alocado a este centro: `ValueTotal × ValueRatio`, arredondado para 2 casas decimais.'
    RelatedAccountsPayable:
      type: object
      description: Conta filha gerada por retenção de impostos. Resume os campos da conta filha já com totais calculados.
      properties:
        IDAccountPayableReceivable:
          type: integer
          format: int32
          description: Identificador da conta filha.
        DateDue:
          type: string
          format: date
          description: Data de vencimento.
        DateDocument:
          type: string
          format: date
          nullable: true
          description: Data do documento.
        DocumentNumber:
          type: string
          maxLength: 200
          nullable: true
          description: Número do documento.
        IDStatusAccountPayableReceivable:
          type: integer
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
          nullable: true
          description: >-
            Status do título: 0=Aberto, 1=Vencido, 2=Pago, 3=Pago Parcialmente, 4=Não lançado, 5=Pago com acréscimo,
            6=Vence hoje.
        StatusAccountPayableReceivable:
          type: string
          nullable: true
          description: Descrição textual do status.
        IDConsumer:
          type: integer
          format: int32
          nullable: true
          description: Identificador do cliente, quando aplicável.
        ConsumerNameCorporateName:
          type: string
          nullable: true
          description: Razão social ou nome do cliente.
        IDSupplier:
          type: integer
          format: int32
          nullable: true
          description: Identificador do fornecedor, quando aplicável.
        SupplierNameCorporateName:
          type: string
          nullable: true
          description: Razão social ou nome do fornecedor.
        IDTypeAccount:
          type: integer
          enum:
            - 0
            - 1
          description: 'Tipo de conta: 0=entrada (a receber), 1=saída (a pagar).'
        TypeAccountPaybleDescription:
          type: string
          nullable: true
          description: Descrição do plano de contas.
        Value:
          type: number
          description: Valor base do título (zero quando inválido).
        ValueDiscount:
          type: number
          description: Valor de desconto (zero quando inválido).
        ValueInterest:
          type: number
          description: Valor de juros (zero quando inválido).
        ValuePenalty:
          type: number
          description: Valor de multa (zero quando inválido).
        ValueTotal:
          type: number
          description: 'Valor total efetivo: `Value + ValuePenalty + ValueInterest - ValueDiscount`.'
    BankAccountCreate:
      type: object
      description: Corpo do `POST /accounts/bank-account`.
      required:
        - Bank
        - BankNumber
      properties:
        Bank:
          type: string
          maxLength: 100
          description: Nome do banco.
        BankNumber:
          type: string
          maxLength: 3
          description: Código Febraban.
        BankRouting:
          type: string
          maxLength: 45
          nullable: true
          description: Agência.
        AccountNumber:
          type: string
          maxLength: 45
          nullable: true
          description: Número da conta.
        AccountNumberDigit:
          type: string
          maxLength: 1
          nullable: true
          description: Dígito verificador do número da conta.
        MainIncome:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            Conta principal de recebimento (0/1). Padrão 0. Quando 1, qualquer outra conta da mesma empresa/faturador é
            automaticamente desmarcada.
        MainPayment:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            Conta principal de pagamento (0/1). Padrão 0. Quando 1, qualquer outra conta da mesma empresa/faturador é
            automaticamente desmarcada.
        IDCompanyInvoice:
          type: integer
          format: int32
          nullable: true
          description: Identificador da empresa faturadora. Quando omitido, assume a empresa autenticada.
        IDCompanyIntegration:
          type: integer
          format: int32
          nullable: true
          description: Identificador da integração bancária. Validado contra os cadastros da empresa.
        IDCompanyIntegrationPix:
          type: integer
          format: int32
          nullable: true
          description: Identificador da integração de Pix vinculada à conta. Validado contra os cadastros da empresa.
        IDTypeOrder:
          type: integer
          format: int32
          nullable: true
          description: >-
            Identificador do tipo de pedido. Só faz sentido quando o tipo está habilitado para frente de caixa e
            pertence ao mesmo faturador da conta.
        TefTerminal:
          type: string
          maxLength: 45
          nullable: true
          description: Terminal TEF associado.
    BankAccountUpdate:
      type: object
      description: >-
        Corpo do `PUT /accounts/bank-account/{idbankaccount}`. Todos os campos são opcionais — só os enviados são
        atualizados. Para ativar o modo de **ajuste de saldo inicial**, envie `InitialBalance` e `InitialBalanceDate`;
        nesse modo, os campos de cadastro são ignorados.
      properties:
        Bank:
          type: string
          maxLength: 100
          description: Nome do banco.
        BankNumber:
          type: string
          maxLength: 3
          description: >-
            Código Febraban. Não pode ser alterado quando a conta atual é interna (`000`) e existe caixa aberto
            vinculado.
        BankRouting:
          type: string
          maxLength: 45
          nullable: true
          description: Agência.
        AccountNumber:
          type: string
          maxLength: 45
          nullable: true
          description: Número da conta.
        AccountNumberDigit:
          type: string
          maxLength: 1
          nullable: true
          description: Dígito verificador do número da conta.
        MainIncome:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            Conta principal de recebimento (0/1). Quando 1, qualquer outra conta da mesma empresa/faturador é
            automaticamente desmarcada.
        MainPayment:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            Conta principal de pagamento (0/1). Quando 1, qualquer outra conta da mesma empresa/faturador é
            automaticamente desmarcada.
        IDCompanyInvoice:
          type: integer
          format: int32
          description: Identificador da empresa faturadora. Quando omitido, assume a empresa autenticada.
        IDCompanyIntegration:
          type: integer
          format: int32
          nullable: true
          description: Identificador da integração bancária. Validado contra os cadastros da empresa.
        IDCompanyIntegrationPix:
          type: integer
          format: int32
          nullable: true
          description: Identificador da integração de Pix vinculada à conta. Validado contra os cadastros da empresa.
        IDTypeOrder:
          type: integer
          format: int32
          nullable: true
          description: >-
            Identificador do tipo de pedido. Só faz sentido quando o tipo está habilitado para frente de caixa e
            pertence ao mesmo faturador da conta.
        TefTerminal:
          type: string
          maxLength: 45
          nullable: true
          description: Terminal TEF associado.
        InitialBalance:
          type: number
          description: >-
            Saldo final desejado para a conta na data informada. Quando enviado junto com `InitialBalanceDate`, ativa o
            modo de ajuste de saldo (os demais campos são ignorados).
        InitialBalanceDate:
          type: string
          format: date
          description: Data de referência para o ajuste de saldo. O lançamento de ajuste é gravado no dia anterior, às 23:59:59.
    Brand:
      type: object
      description: Cadastro de marca.
      properties:
        IDBrand:
          type: integer
          format: int32
          description: Identificador da marca.
        Name:
          type: string
          maxLength: 300
          description: Nome da marca.
        Description:
          type: string
          maxLength: 300
          nullable: true
          description: Descrição. Quando ausente no POST, herda o `Name`.
        Keywords:
          type: string
          maxLength: 500
          nullable: true
          description: Palavras-chave para busca. Quando ausente no POST, herda o `Name`.
        Title:
          type: string
          maxLength: 300
          nullable: true
          description: Título para exibição. Quando ausente no POST, herda o `Name`.
        IsActive:
          type: integer
          enum:
            - 0
            - 1
          description: Indica se a marca está ativa para uso em produtos. Padrão 1.
        MenuHome:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: Indica se aparece em destaque no menu inicial. Padrão 0.
        Score:
          type: integer
          nullable: true
          description: Pontuação manual para ordenação ou destaque.
        RecordTimestamp:
          type: string
          format: date-time
          nullable: true
          description: Data e hora de cadastro.
        Status:
          type: integer
          enum:
            - 0
            - 1
          description: 'Situação: 0=inativa (excluída logicamente), 1=ativa.'
    BrandListItem:
      type: object
      description: >-
        Item de `GET /brand`. Versão resumida do cadastro de marca, com a empresa dona e um campo textual de status
        pronto para exibição.
      properties:
        AccountName:
          type: string
          description: Subdomínio da empresa dona da marca.
        IDBrand:
          type: integer
          format: int32
          description: Identificador da marca.
        Name:
          type: string
          maxLength: 300
          description: Nome da marca.
        IsActive:
          type: integer
          enum:
            - 0
            - 1
          description: Indica se a marca está ativa para uso em produtos.
        Status:
          type: string
          enum:
            - Ativo
            - Inativo
          description: Texto pronto para exibição derivado de `IsActive`.
    BrandCreate:
      type: object
      description: >-
        Corpo do `POST /brand`. Apenas `Name` é efetivamente exigido — os demais campos textuais herdam `Name` quando
        ausentes ou vazios.
      required:
        - Name
      properties:
        Name:
          type: string
          maxLength: 300
          description: Nome da marca.
        Description:
          type: string
          maxLength: 300
          nullable: true
          description: Descrição da marca (rich text na UI). Quando ausente ou vazio, herda o valor de `Name`.
        Keywords:
          type: string
          maxLength: 500
          nullable: true
          description: Palavras-chave para busca/SEO da marca. Quando ausente ou vazio, herda o valor de `Name`.
        Title:
          type: string
          maxLength: 300
          nullable: true
          description: Título exibido em cabeçalho de página/SEO da marca. Quando ausente ou vazio, herda o valor de `Name`.
        IsActive:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: Indica se a marca está ativa para uso em produtos (0/1). Padrão 1.
        MenuHome:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: Indica se aparece em destaque no menu inicial (0/1). Padrão 0.
        Score:
          type: integer
          nullable: true
          description: Pontuação manual para ordenação ou destaque (tinyint -128..127). Quando ausente ou vazio, fica `null`.
    BrandUpdate:
      type: object
      description: Corpo do `PUT /brand/{idbrand}`. Todos os campos são opcionais — apenas os enviados são atualizados.
      properties:
        Name:
          type: string
          maxLength: 300
          description: Nome da marca.
        Description:
          type: string
          maxLength: 300
          nullable: true
          description: Descrição da marca.
        Keywords:
          type: string
          maxLength: 500
          nullable: true
          description: Palavras-chave para busca.
        Title:
          type: string
          maxLength: 300
          nullable: true
          description: Título para exibição.
        IsActive:
          type: integer
          enum:
            - 0
            - 1
          description: Indica se a marca está ativa para uso em produtos (0/1).
        MenuHome:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: Indica se aparece em destaque no menu inicial (0/1).
        Score:
          type: integer
          nullable: true
          description: Pontuação manual para ordenação ou destaque.
    BankStatementInternalResponse:
      type: object
      description: >-
        Resposta do `GET /accounts/bank-statement` no modo `Source=1` (extrato interno). Apresenta saldo anterior,
        lançamentos linha a linha com saldo corrente, totais por tipo e saldo final.
      properties:
        IDBankAccount:
          type: integer
          format: int32
          nullable: true
          description: Identificador da conta consultada (eco do filtro).
        PeriodStart:
          type: string
          nullable: true
          description: Início do período (ISO 8601 com hora, eco normalizado de `DateFrom`).
        PeriodEnd:
          type: string
          nullable: true
          description: Fim do período (ISO 8601 com hora, eco normalizado de `DateTo`).
        AccountName:
          type: string
          nullable: true
          description: Subdomínio da empresa dona da conta. Nulo quando não há lançamentos.
        PreviousBalance:
          type: number
          description: Saldo acumulado antes do início do período.
        Entries:
          type: array
          items:
            $ref: '#/components/schemas/BankStatementInternalEntry'
          description: Lançamentos do período, em ordem cronológica, com saldo corrente.
        Receivables:
          type: number
          description: Total de entradas no período.
        Payables:
          type: number
          description: Total de saídas no período.
        FinalBalance:
          type: number
          description: 'Saldo final: `PreviousBalance + Receivables - Payables`.'
    BankStatementInternalEntry:
      type: object
      description: Lançamento do extrato interno, com saldo corrente após o lançamento.
      properties:
        AccountName:
          type: string
          description: Subdomínio da empresa dona da conta bancária.
        IDBankAccount:
          type: integer
          format: int32
          description: Conta bancária em que o lançamento interno foi registrado.
        IDBankStatement:
          type: integer
          format: int32
          description: Identificador do lançamento.
        TransactionDate:
          type: string
          format: date
          nullable: true
          description: Data da transação (`YYYY-MM-DD`).
        Document:
          type: string
          nullable: true
          description: 'Documento: número do título, quando conciliado; senão, `TransactionDocument`.'
        Description:
          type: string
          nullable: true
          description: 'Descrição: observação do título, quando conciliado; senão, `TransactionDescription`.'
        IDTypeAccount:
          type: integer
          enum:
            - 0
            - 1
          description: 'Tipo do lançamento: 0=entrada, 1=saída.'
        Value:
          type: number
          description: 'Valor com sinal aplicado: positivo para entrada, negativo para saída.'
        IDSupplier:
          type: integer
          format: int32
          nullable: true
          description: Fornecedor da conta a pagar baixada. Vazio quando o lançamento se refere a conta a receber.
        SupplierNameCorporateName:
          type: string
          nullable: true
          description: Razão social ou nome do fornecedor. Vazio quando não é conta a pagar.
        IDConsumer:
          type: integer
          format: int32
          nullable: true
          description: Cliente da conta a receber baixada. Vazio quando o lançamento se refere a conta a pagar.
        ConsumerNameCorporateName:
          type: string
          nullable: true
          description: Razão social ou nome do cliente. Vazio quando não é conta a receber.
        BankName:
          type: string
          nullable: true
          description: Bancos onde o lançamento foi registrado (lista concatenada por `|`).
        Balance:
          type: number
          description: Saldo corrente após este lançamento.
        IDAccountPayableReceivable:
          type: integer
          format: int32
          nullable: true
          description: Identificador do título conciliado, quando houver.
    BankStatementConciliationEntry:
      type: object
      description: >-
        Item da resposta do `GET /accounts/bank-statement` no modo `Source=2` (extrato bancário). Cada item é uma
        conciliação bancária com a lista de contas internas que a casam.
      properties:
        IDBankStatementConciliation:
          type: integer
          format: int32
          description: Identificador da conciliação bancária (linha do extrato importado que está sendo conciliada).
        IDBankAccount:
          type: integer
          format: int32
          description: Conta bancária do extrato.
        TransactionDate:
          type: string
          nullable: true
          description: Data da transação no banco.
          format: date
        BankTransactionID:
          type: string
          nullable: true
          description: Identificador da transação no banco (quando o banco fornece).
        Comments:
          type: string
          nullable: true
          description: Descrição da transação no banco.
        BankValue:
          type: number
          description: Valor da transação no banco.
        BankName:
          type: string
          description: Banco e número da conta, concatenados.
        IDTypeStatusConciliation:
          type: integer
          format: int32
          nullable: true
          description: Identificador do status de conciliação.
          enum:
            - 1
            - 2
            - 3
            - 4
        StatusDescription:
          type: string
          nullable: true
          description: Descrição do status de conciliação.
        IDTypeAccount:
          type: integer
          enum:
            - 0
            - 1
          description: 'Tipo do lançamento: 0=entrada, 1=saída.'
        InternalAccounts:
          type: array
          items:
            $ref: '#/components/schemas/BankStatementConciliationInternal'
          description: Lançamentos internos vinculados a esta conciliação.
        ERPValueTotal:
          type: number
          description: Soma dos valores dos lançamentos internos vinculados.
        Difference:
          type: number
          description: '`ERPValueTotal - BankValue`. Zero indica conciliação exata.'
        IDCompany:
          type: integer
          format: int32
          description: Empresa dona da conta bancária.
        IDCompanyInvoice:
          type: integer
          format: int32
          nullable: true
          description: >-
            Filial faturadora vinculada quando o lançamento é segregado por empresa faturadora (ambientes
            multi-empresa). Vazio quando não se aplica.
        CompanyNameCorporateNameInvoice:
          type: string
          nullable: true
          description: Razão social do faturador da conta bancária.
        AccountName:
          type: string
          description: Subdomínio da empresa dona da conta.
    BankStatementConciliationInternal:
      type: object
      description: >-
        Lançamento interno do idworks vinculado a uma conciliação bancária. Este schema mescla dois formatos do sistema
        `bankStatementList`:


        - **Modo `Source=2`** (item de `InternalAccounts[]` em `BankStatementConciliationEntry`) — devolve apenas
        `IDBankStatement`, `IDAccountPayableReceivable`, `Description`, `Document`, `Value`, `IDTypeAccount` (6 campos).

        - **Modo `Source=1` com `IDBankStatementConciliation`** — devolve `IDBankStatement`, `DateDue`, `IDSupplier`,
        `SupplierNameCorporateName`, `IDConsumer`, `ConsumerNameCorporateName`, `ValueTotal`, `TypePaymentDescription`,
        `TypeAccountPaybleDescription`, `BankForecast`, `BankPayment`, `StatusAccountPayableReceivable`,
        `IDAccountPayableReceivable`, `AccountName`, `IDTypeAccount`.


        Cada description de campo abaixo indica em qual modo o campo é retornado.
      properties:
        IDBankStatement:
          type: integer
          format: int32
          description: >-
            Identificador do lançamento interno (`AccountsPayableReceivableBankStatement`) — a baixa de uma conta a
            pagar ou receber registrada no sistema, candidata a casar com a linha do extrato bancário.
        IDAccountPayableReceivable:
          type: integer
          format: int32
          nullable: true
          description: Título a pagar ou receber associado, quando houver.
        Description:
          type: string
          nullable: true
          description: >-
            Descrição da transação interna. Presente apenas no modo `Source=2` (`InternalAccounts[]` dentro de
            `BankStatementConciliationEntry`).
        Document:
          type: string
          nullable: true
          description: Documento da transação interna. Presente apenas no modo `Source=2`.
        Value:
          type: number
          description: >-
            Valor do lançamento interno (sempre positivo). Presente apenas no modo `Source=2` — no modo `Source=1` use
            `ValueTotal`.
        IDTypeAccount:
          type: integer
          enum:
            - 0
            - 1
          description: 'Tipo do lançamento: 0=entrada, 1=saída.'
        DateDue:
          type: string
          format: date
          nullable: true
          description: Vencimento do título. Presente apenas no modo `Source=1` com `IDBankStatementConciliation`.
        IDSupplier:
          type: integer
          format: int32
          nullable: true
          description: >-
            Fornecedor da conta a pagar associada. Vazio quando a baixa é de uma conta a receber. Presente apenas no
            modo `Source=1` com `IDBankStatementConciliation`.
        SupplierNameCorporateName:
          type: string
          nullable: true
          description: >-
            Razão social ou nome do fornecedor. Vazio quando não é conta a pagar. Presente apenas no modo `Source=1` com
            `IDBankStatementConciliation`.
        IDConsumer:
          type: integer
          format: int32
          nullable: true
          description: >-
            Cliente da conta a receber associada. Vazio quando a baixa é de uma conta a pagar. Presente apenas no modo
            `Source=1` com `IDBankStatementConciliation`.
        ConsumerNameCorporateName:
          type: string
          nullable: true
          description: >-
            Razão social ou nome do cliente. Vazio quando não é conta a receber. Presente apenas no modo `Source=1` com
            `IDBankStatementConciliation`.
        ValueTotal:
          type: number
          description: >-
            Valor com sinal aplicado. Positivo para entrada, negativo para saída. Presente apenas no modo `Source=1` com
            `IDBankStatementConciliation`.
        TypePaymentDescription:
          type: string
          nullable: true
          description: >-
            Descrição da forma de pagamento (ex.: `Boleto`, `Pix`, `Cartão de crédito`, `Transferência`). Presente
            apenas no modo `Source=1` com `IDBankStatementConciliation`.
        TypeAccountPaybleDescription:
          type: string
          nullable: true
          description: >-
            Descrição do plano de contas (categoria contábil). Presente apenas no modo `Source=1` com
            `IDBankStatementConciliation`.
        BankForecast:
          type: string
          nullable: true
          description: Banco da conta prevista do título. Presente apenas no modo `Source=1` com `IDBankStatementConciliation`.
        BankPayment:
          type: string
          nullable: true
          description: Banco do lançamento de pagamento. Presente apenas no modo `Source=1` com `IDBankStatementConciliation`.
        StatusAccountPayableReceivable:
          type: string
          nullable: true
          description: >-
            Descrição do status atual (ex.: `Aberto`, `Pago`, `Recebido`, `Cancelado`, `Parcialmente baixado`). Presente
            apenas no modo `Source=1` com `IDBankStatementConciliation`.
        AccountName:
          type: string
          nullable: true
          description: >-
            Subdomínio (conta) da empresa dona da baixa. Útil em ambiente multi-empresa. Presente apenas no modo
            `Source=1` com `IDBankStatementConciliation`.
    SupplierDetail:
      type: object
      description: >-
        Cadastro completo de um fornecedor ou transportadora. Inclui os campos próprios do cadastro, descrições
        resolvidas dos relacionamentos, campos calculados (`SupplierType`, `CarrierRateUploadStatusDescription`) e
        listas auxiliares de contatos, faixas SRO dos Correios, uploads de tabela de frete e centros de custo. Campos
        com prefixo `Carrier*` ou que envolvem `CorreiosSRO` são preenchidos apenas quando o fornecedor opera como
        transportadora.
      properties:
        IDSupplier:
          type: integer
          format: int32
          description: Identificador do fornecedor.
        SupplierNameCorporateName:
          type: string
          maxLength: 100
          description: Nome ou razão social.
        SupplierTradeName:
          type: string
          maxLength: 60
          nullable: true
          description: Nome fantasia.
        SupplierCpfCnpj:
          type: string
          maxLength: 14
          nullable: true
          description: CPF (11 dígitos) ou CNPJ (14 dígitos), somente números.
        SupplierType:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 7
            - 8
            - 9
          description: >-
            Tipo do fornecedor: `1` Produto, `2` Transportadora, `3` Pessoal, `4` Serviço, `5` Insumo, `6` Governo, `7`
            Transportadora p/ Devoluções, `8` Operador logístico, `9` Outros.
        SupplierStateInscription:
          type: string
          maxLength: 14
          nullable: true
          description: Inscrição estadual.
        SupplierCityInscription:
          type: string
          maxLength: 14
          nullable: true
          description: Inscrição municipal.
        SupplierIdentityNumber:
          type: string
          maxLength: 45
          nullable: true
          description: Documento de identidade (pessoa física).
        SupplierBirthDate:
          type: string
          format: date
          nullable: true
          description: Data de nascimento (pessoa física).
        IDSupplierCivilStatus:
          type: integer
          format: int32
          nullable: true
          description: >-
            Estado civil do fornecedor pessoa física: `1` Solteiro(a), `2` Casado(a), `3` Divorciado(a), `4` Viúvo(a),
            `5` União Estável, `6` Outros.
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
        TypeCivilStatusName:
          type: string
          nullable: true
          description: Descrição do estado civil.
        SupplierTelephone:
          type: string
          maxLength: 50
          nullable: true
          description: Telefone principal.
        SupplierEmail:
          type: string
          maxLength: 45
          nullable: true
          description: E-mail principal.
        SupplierLogoUrl:
          type: string
          maxLength: 500
          nullable: true
          description: URL do logotipo.
        ShippingPostalCode:
          type: string
          maxLength: 10
          nullable: true
          description: CEP.
        ShippingStreet:
          type: string
          maxLength: 45
          nullable: true
          description: Logradouro.
        ShippingNumber:
          type: string
          maxLength: 60
          nullable: true
          description: Número.
        ShippingComplement:
          type: string
          maxLength: 60
          nullable: true
          description: Complemento.
        ShippingNeighborhood:
          type: string
          maxLength: 60
          nullable: true
          description: Bairro.
        ShippingCity:
          type: string
          maxLength: 60
          nullable: true
          description: Cidade.
        ShippingState:
          type: string
          maxLength: 2
          nullable: true
          description: Sigla da unidade federativa.
        IDSupplierCategory:
          type: integer
          format: int32
          description: Identificador da categoria do fornecedor.
        CategoryDescription:
          type: string
          nullable: true
          description: Descrição da categoria.
        IDTypeSupplier:
          type: integer
          format: int32
          nullable: true
          description: Identificador do tipo de fornecedor (vinculado à categoria).
        TypeSupplier:
          type: string
          nullable: true
          description: Descrição do tipo de fornecedor.
        IDTypeAccountPayableReceivable:
          type: integer
          format: int32
          nullable: true
          description: Plano de contas padrão para títulos gerados deste fornecedor.
        TypeAccountPaybleDescription:
          type: string
          nullable: true
          description: Descrição do plano de contas padrão.
        BankCode:
          type: string
          maxLength: 3
          nullable: true
          description: Código Febraban do banco do fornecedor.
        Bank:
          type: string
          nullable: true
          description: Nome do banco correspondente ao `BankCode`.
        BankAgency:
          type: string
          maxLength: 45
          nullable: true
          description: Agência.
        BankCheckingAccount:
          type: string
          maxLength: 45
          nullable: true
          description: Conta corrente.
        BankCheckingAccountType:
          type: integer
          format: int32
          nullable: true
          description: Tipo de conta bancária.
        PixKey:
          type: string
          maxLength: 300
          nullable: true
          description: Chave Pix.
        SupplierPIS:
          type: string
          maxLength: 45
          nullable: true
          description: PIS do fornecedor (pessoa física).
        Comments:
          type: string
          maxLength: 5000
          nullable: true
          description: Observações.
        DefaultPurchase:
          type: integer
          format: int32
          nullable: true
          description: Marca o fornecedor como padrão para novas compras.
        SupplierProductLeadTimeDays:
          type: integer
          format: int32
          nullable: true
          description: Lead time padrão de entrega de produtos, em dias.
        SupplierProductReliability:
          type: integer
          format: int32
          nullable: true
          description: Avaliação de confiabilidade do fornecedor.
        IDCompanyIntegration:
          type: integer
          format: int32
          nullable: true
          description: Identificador da integração da empresa associada.
        CompanyIntegration:
          type: string
          nullable: true
          description: Texto formatado com o tipo e nome da integração.
        IDCompanyLabel:
          type: integer
          format: int32
          nullable: true
          description: Identificador do template de etiqueta usado pelo fornecedor.
        LabelName:
          type: string
          nullable: true
          description: Nome do template de etiqueta.
        AccountName:
          type: string
          description: Subdomínio da empresa dona do cadastro.
        SupplierStatus:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            Situação do cadastro: 1=ativo. (Apenas registros ativos são retornados — campo presente por
            compatibilidade.)
        IDCarrierType:
          type: integer
          format: int32
          nullable: true
          description: Identificador do tipo de transportadora (quando o fornecedor opera como transportadora).
        TypeCarrier:
          type: string
          nullable: true
          description: Descrição do tipo de transportadora.
        CarrierLogoUrl:
          type: string
          nullable: true
          description: URL do logotipo da transportadora.
        IDTypeCompanyIntegration:
          type: integer
          format: int32
          nullable: true
          description: Identificador do tipo de integração da transportadora.
        IDCarrierGateway:
          type: integer
          format: int32
          nullable: true
          description: Identificador do gateway de cotação.
        CarrierGateway:
          type: string
          nullable: true
          description: Descrição do gateway de cotação.
        IDCarrierModal:
          type: integer
          format: int32
          nullable: true
          description: Identificador do modal de transporte.
        CarrierModal:
          type: string
          nullable: true
          description: Descrição do modal de transporte.
        CarrierLabelType:
          type: integer
          format: int32
          nullable: true
          description: Tipo da etiqueta da transportadora.
        CarrierShippingIdRule:
          type: string
          maxLength: 200
          nullable: true
          description: Regra para o identificador de envio.
        CarrierAuction:
          type: integer
          format: int32
          nullable: true
          description: Indica se a transportadora participa de leilão de cotação.
        CarrierAuctionPenalty:
          type: number
          nullable: true
          description: Penalidade aplicada à transportadora no leilão.
        CarrierAdditionalBusinessDays:
          type: integer
          format: int32
          nullable: true
          description: Dias úteis adicionais aplicados ao prazo.
        CarrierShippingCutTime:
          type: string
          nullable: true
          description: Horário de corte para envio no mesmo dia (formato `HH:MM:SS`).
        CarrierICMSIncluded:
          type: integer
          format: int32
          nullable: true
          description: Indica se o ICMS já está incluído no frete cotado.
        CarrierCubageKmM:
          type: integer
          format: int32
          nullable: true
          description: Fator de cubagem em quilos por metro cúbico.
        CarrierCubageFreeWeight:
          type: number
          nullable: true
          description: Peso livre considerado antes de aplicar cubagem.
        CarrierPriceRounding:
          type: number
          nullable: true
          description: Arredondamento aplicado ao preço final do frete.
        CarrierOrdersLimitPerCollection:
          type: integer
          format: int32
          nullable: true
          description: Limite de pedidos por coleta.
        CarrierCollectionListEmail:
          type: string
          maxLength: 500
          nullable: true
          description: E-mails que recebem a lista de coleta (separados por vírgula).
        CarrierQuotationExternalId:
          type: integer
          format: int32
          nullable: true
          description: Identificador externo usado na cotação.
        CarrierRateUploadStatus:
          type: integer
          enum:
            - 0
            - 1
            - 2
            - 3
          nullable: true
          description: 'Situação do último upload de tabela de frete: 0=pendente, 1=sucesso, 2=erro, 3=processando.'
        CarrierRateUploadStatusDescription:
          type: string
          enum:
            - Sucesso
            - Erro
            - Processando
          nullable: true
          description: Texto pronto para exibição derivado de `CarrierRateUploadStatus`. Nulo quando o status é pendente.
        ContentDeclarationStates:
          type: array
          items:
            type: string
            maxLength: 2
          description: >-
            Siglas das unidades federativas em que a transportadora exige declaração de conteúdo. Array vazio quando não
            exige em nenhuma.
        PrintDanfe:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: Indica se a transportadora imprime DANFE junto com a etiqueta.
        PrintDanfeA4:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: Indica se a impressão da DANFE é em A4.
        ManualLabel:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: Indica se a etiqueta é gerada manualmente.
        IgnoreCollectionList:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: Indica se a transportadora deve ser excluída da lista de coleta.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora de cadastro.
        Contacts:
          type: array
          items:
            $ref: '#/components/schemas/SupplierContact'
          description: Contatos cadastrados para o fornecedor.
        CorreiosSRO:
          type: array
          items:
            $ref: '#/components/schemas/SupplierCorreiosSroRange'
          description: Faixas de números de SRO dos Correios disponíveis para a transportadora.
        CarrierTableUpload:
          type: array
          items:
            $ref: '#/components/schemas/SupplierCarrierTableUpload'
          description: >-
            Uploads de tabela de frete, do mais recente para o mais antigo. O primeiro item é marcado como `Main = 1`
            (vigente).
        SuppliersCostCenter:
          type: array
          items:
            $ref: '#/components/schemas/SupplierCostCenterAllocation'
          description: Rateio padrão por centro de custo aplicado aos títulos gerados.
        LabelAndDanfeSamePage:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` inclui os dados fiscais na mesma página da etiqueta; `0` não inclui.'
    SupplierContact:
      type: object
      description: Contato do fornecedor.
      properties:
        IDSuppliersContact:
          type: integer
          format: int32
          description: Identificador do contato cadastrado para o fornecedor (uma linha por pessoa/telefone/e-mail no cadastro).
        ContactName:
          type: string
          nullable: true
          description: Nome do contato.
        ContactEmail:
          type: string
          nullable: true
          description: E-mail.
        ContactTelephone:
          type: string
          nullable: true
          description: Telefone.
        ContactResponsability:
          type: string
          nullable: true
          description: Cargo ou área de responsabilidade.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora de cadastro do contato.
    SupplierCorreiosSroRange:
      type: object
      description: Faixa de números de SRO (rastreio) dos Correios disponível para a transportadora.
      properties:
        IDCorreiosSroRange:
          type: integer
          format: int32
          description: >-
            Identificador da faixa de etiquetas SRO (Sistema de Rastreamento de Objetos) dos Correios alocada ao
            fornecedor — usada para emissão de rastreios em contratos de postagem.
        Status:
          type: integer
          enum:
            - 0
            - 1
          description: 1=faixa ativa.
        Prefix:
          type: string
          nullable: true
          description: 'Prefixo do código SRO (ex.: `AA`, `BR`).'
        RangeInitial:
          type: integer
          nullable: true
          description: Primeiro número da faixa.
        RangeFinal:
          type: integer
          nullable: true
          description: Último número da faixa.
        CurrentRange:
          type: integer
          nullable: true
          description: Próximo número a ser usado.
        DiffRange:
          type: integer
          description: Quantidade de números ainda disponíveis na faixa quando ativa. Zero quando inativa ou sem `CurrentRange`.
    SupplierCarrierTableUpload:
      type: object
      description: Upload de tabela de frete da transportadora.
      properties:
        IDCarrierTableUpload:
          type: integer
          format: int32
          description: >-
            Identificador do upload de tabela de frete vinculado ao fornecedor (quando o fornecedor é uma
            transportadora). Cada upload corresponde a uma planilha de tabela de frete importada.
        FileName:
          type: string
          nullable: true
          description: Nome do arquivo enviado.
        UrlFile:
          type: string
          description: URL completa para download do arquivo, já com token de acesso embutido.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora do upload (formato ISO 8601 com sufixo Z).
        Main:
          type: integer
          enum:
            - 0
            - 1
          description: 'Indica a tabela vigente: `1` no upload mais recente, `0` nos demais.'
    SupplierCostCenterAllocation:
      type: object
      description: Rateio padrão de centro de custo para títulos gerados a partir do fornecedor.
      properties:
        IDTypeCostCenter:
          type: integer
          format: int32
          description: >-
            Centro de custo padrão associado ao fornecedor (uma linha por nível da árvore de centros de custos quando a
            empresa usa hierarquia).
        TypeCostCenter:
          type: string
          maxLength: 100
          description: Nome do centro de custo.
        ExternalCode:
          type: string
          maxLength: 45
          nullable: true
          description: Código externo para integração contábil.
        ValueRatio:
          type: number
          description: 'Fração do total (decimal com 4 casas, ex.: `0.3500` = 35%).'
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora do cadastro do rateio.
    SupplierCategoryListItem:
      type: object
      description: >-
        Item de `GET /supplier/category`. Representa uma categoria de fornecedor da empresa, com o tipo de fornecedor já
        resolvido.
      properties:
        AccountName:
          type: string
          description: Subdomínio da empresa dona da categoria.
        IDSupplierCategory:
          type: integer
          format: int32
          description: Identificador da categoria.
        CategoryDescription:
          type: string
          maxLength: 45
          description: Nome (descrição) da categoria.
        IDCompany:
          type: integer
          format: int32
          description: Identificador da empresa dona da categoria.
        IDTypeSupplier:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 7
            - 8
            - 9
          description: >-
            Tipo de fornecedor. Valores: 1=Produto, 2=Transportadora, 3=Pessoal, 4=Serviço, 5=Insumo, 6=Governo,
            7=Transportadora P/ Devoluções, 8=Operador logístico, 9=Outros.
        TypeSupplier:
          type: string
          enum:
            - Produto
            - Transportadora
            - Pessoal
            - Serviço
            - Insumo
            - Governo
            - Transportadora P/ Devoluções
            - Operador logístico
            - Outros
          description: Texto pronto para exibição do tipo de fornecedor, resolvido a partir de `IDTypeSupplier`.
        SuppliersCategoryStatus:
          type: integer
          enum:
            - 0
            - 1
          description: 'Situação da categoria: 0=inativa (excluída logicamente), 1=ativa. A listagem só devolve `1`.'
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora de cadastro.
    SupplierCategoryCreate:
      type: object
      description: Corpo do `POST /supplier/category`. Ambos os campos são obrigatórios.
      required:
        - CategoryDescription
        - IDTypeSupplier
      properties:
        CategoryDescription:
          type: string
          maxLength: 45
          description: Nome (descrição) da categoria.
        IDTypeSupplier:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 7
            - 8
            - 9
          description: >-
            Tipo de fornecedor. Valores: 1=Produto, 2=Transportadora, 3=Pessoal, 4=Serviço, 5=Insumo, 6=Governo,
            7=Transportadora P/ Devoluções, 8=Operador logístico, 9=Outros.
    SupplierCategoryUpdate:
      type: object
      description: >-
        Corpo do `PUT /supplier/category/{idsuppliercategory}`. Os dois campos são sobrescritos a cada chamada (não é
        atualização parcial).
      required:
        - CategoryDescription
        - IDTypeSupplier
      properties:
        CategoryDescription:
          type: string
          maxLength: 45
          description: Nome (descrição) da categoria.
        IDTypeSupplier:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 7
            - 8
            - 9
          description: >-
            Tipo de fornecedor. Valores: 1=Produto, 2=Transportadora, 3=Pessoal, 4=Serviço, 5=Insumo, 6=Governo,
            7=Transportadora P/ Devoluções, 8=Operador logístico, 9=Outros.
    AccountsPayablePaymentCreate:
      type: object
      required:
        - IDBankAccount
        - DateTransactionTimestamp
      properties:
        IDBankAccount:
          type: integer
          format: int32
          description: Conta bancária onde o pagamento foi efetuado.
        DateTransactionTimestamp:
          type: string
          format: date-time
          description: Data e hora da transação.
        Value:
          type: number
          nullable: true
          description: Valor pago. Quando omitido, usa o saldo devedor total (`ValueTotal` - `ValuePaid`).
        TransactionDescription:
          type: string
          default: ''
          description: Descrição da transação.
        TransactionDocument:
          type: string
          default: ''
          description: Documento da transação.
        IDAccountsPayableReceivableConciliation:
          type: integer
          format: int32
          nullable: true
          description: Identificador da conciliação bancária à qual este pagamento pertence.
        IDAccountsPayableReceivableConciliationMarketplace:
          type: integer
          nullable: true
          description: Conciliação de marketplace vinculada ao pagamento.
    AccountsPayableCostCenterSetItem:
      type: object
      required:
        - IDTypeCostCenter
        - ValueRatio
      properties:
        IDTypeCostCenter:
          type: integer
          format: int32
          description: Identificador do centro de custo.
        ValueRatio:
          type: number
          description: 'Proporção do rateio (ex.: `0.5` = 50%). A soma de todos os itens deve ser exatamente `1`.'
    AccountsReceivableCreate:
      type: object
      description: >-
        Corpo do `POST /accounts/receivable`. `DateDue` e `Value` são obrigatórios na prática (sem eles a criação falha
        no INSERT). `IDTypeDocument` e `IDTypeAccountPayableReceivable` também são exigidos pelo frontend e validados —
        quando omitidos, a criação cai em `[BadRequest] - Tipo documento não existe` ou `[BadRequest] - Plano de contas
        não existe`.
      required:
        - DateDue
        - Value
        - IDTypeDocument
        - IDTypeAccountPayableReceivable
      properties:
        DateDue:
          type: string
          format: date
          description: Data de vencimento.
        Value:
          type: number
          description: Valor do título, com duas casas decimais.
        IDTypeDocument:
          type: integer
          format: int32
          description: Identificador do tipo de documento. Validado contra os cadastrados da empresa.
        IDTypeAccountPayableReceivable:
          type: integer
          format: int32
          description: Identificador do plano de contas. Validado contra os cadastrados da empresa.
        IDTypePayment:
          type: integer
          format: int32
          description: Identificador do tipo de pagamento. Validado contra os cadastrados da empresa.
        IDConsumer:
          type: integer
          format: int32
          nullable: true
          description: Identificador do cliente. Não pode vir junto com `IDSupplier`.
        IDSupplier:
          type: integer
          format: int32
          nullable: true
          description: Identificador do fornecedor (casos de devolução/estorno). Não pode vir junto com `IDConsumer`.
        DateCompetence:
          type: string
          format: date
          nullable: true
          description: Data de competência.
        DateDocument:
          type: string
          format: date
          nullable: true
          description: Data de emissão do documento.
        DocumentNumber:
          type: string
          maxLength: 200
          nullable: true
          description: Número do documento (nota fiscal, recibo, etc.).
        Comments:
          type: string
          maxLength: 2000
          nullable: true
          description: Observações livres sobre o título.
        TID:
          type: string
          maxLength: 45
          nullable: true
          description: TID — identificador da transação no adquirente, quando o título nasce de uma venda em cartão.
        NSU:
          type: string
          maxLength: 45
          nullable: true
          description: NSU — número sequencial único do adquirente, quando o título nasce de uma venda em cartão.
        Installment:
          type: integer
          nullable: true
          description: 'Número da parcela deste título (ex.: 2 para a 2ª parcela).'
        InstallmentTotal:
          type: integer
          nullable: true
          description: Total de parcelas do plano de pagamento original.
        IDBankAccountForecast:
          type: integer
          format: int32
          nullable: true
          description: >-
            Identificador da conta bancária prevista para o recebimento. Validado contra as contas cadastradas na
            empresa.
        IDCompanyInvoice:
          type: integer
          format: int32
          nullable: true
          description: >-
            Identificador da empresa faturadora. Quando omitido, assume a empresa autenticada. Quando informada e
            diferente, precisa estar vinculada como filial (`CompanyMain`) da empresa autenticada.
        ValueDiscount:
          type: number
          nullable: true
          description: Valor de desconto, com duas casas decimais.
        ValueInterest:
          type: number
          nullable: true
          description: Valor de juros, com duas casas decimais.
        ValuePenalty:
          type: number
          nullable: true
          description: Valor de multa, com duas casas decimais.
    AccountsReceivableUpdate:
      type: object
      description: >-
        Corpo do `PUT /accounts/receivable/{idaccountreceivable}`. Todos os campos são opcionais; apenas os enviados são
        atualizados (comportamento de atualização parcial). Quando o título tem boleto/link de pagamento associado,
        alterações de `Value` ou `DateDue` podem ser bloqueadas ou propagadas para o gateway.
      properties:
        Comments:
          type: string
          maxLength: 2000
          nullable: true
          description: Observações.
        DateCompetence:
          type: string
          format: date
          nullable: true
          description: Data de competência.
        DateDocument:
          type: string
          format: date
          nullable: true
          description: Data do documento.
        DateDue:
          type: string
          format: date
          description: Data de vencimento.
        DocumentNumber:
          type: string
          maxLength: 200
          nullable: true
          description: Número do documento.
        IDConsumer:
          type: integer
          format: int32
          nullable: true
          description: Identificador do cliente. Quando enviado, zera `IDSupplier` automaticamente.
        IDSupplier:
          type: integer
          format: int32
          nullable: true
          description: Identificador do fornecedor. Quando enviado, zera `IDConsumer` automaticamente.
        IDTypePayment:
          type: integer
          format: int32
          description: Identificador do tipo de pagamento.
        IDTypeDocument:
          type: integer
          format: int32
          description: Identificador do tipo de documento.
        IDTypeAccountPayableReceivable:
          type: integer
          format: int32
          description: Identificador do plano de contas.
        Value:
          type: number
          description: Valor do título. Quando há boleto pago, a alteração é bloqueada.
        Installment:
          type: integer
          nullable: true
          description: 'Número da parcela deste título (ex.: 2 para a 2ª parcela).'
        InstallmentTotal:
          type: integer
          nullable: true
          description: Total de parcelas do plano de pagamento original.
        TID:
          type: string
          maxLength: 45
          nullable: true
          description: TID — identificador da transação no adquirente, quando o título nasce de uma venda em cartão.
        NSU:
          type: string
          maxLength: 45
          nullable: true
          description: NSU — número sequencial único do adquirente, quando o título nasce de uma venda em cartão.
        IDBankAccountForecast:
          type: integer
          format: int32
          description: Identificador da conta bancária prevista para o recebimento. O valor `"0"` é ignorado.
        ValueDiscount:
          type: number
          nullable: true
          description: Valor de desconto.
        ValueInterest:
          type: number
          nullable: true
          description: Valor de juros.
        ValuePenalty:
          type: number
          nullable: true
          description: Valor de multa.
        IDCompanyIntegration:
          type: integer
          format: int32
          nullable: true
          description: Identificador da integração originadora do título.
        IDCompanyInvoice:
          type: integer
          format: int32
          description: Identificador da empresa faturadora.
        Forecast:
          type: integer
          enum:
            - 0
            - 1
          description: Indica se o título é uma previsão (1) ou um lançamento real (0).
    AccountsReceivableListItem:
      type: object
      description: >-
        Item retornado por `GET /accounts/receivable`. Inclui campos próprios da conta, descrições resolvidas dos
        relacionamentos (cliente/fornecedor, plano de contas, tipo de documento, tipo de pagamento), dados do pedido
        associado, da nota fiscal de origem (quando há) e da integração; totais já calculados em `Number` (`ValueTotal`,
        `ValuePaid`, `ValuePaymentPending`).
      properties:
        AccountName:
          type: string
          description: Subdomínio da empresa dona da conta.
        IDAccountPayableReceivable:
          type: integer
          format: int32
          description: Identificador do título.
        IDStatusAccountPayableReceivable:
          type: integer
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
          nullable: true
          description: >-
            Status do título: 0=Aberto, 1=Vencido, 2=Pago, 3=Pago Parcialmente, 4=Não lançado, 5=Pago com acréscimo,
            6=Vence hoje.
        StatusAccountPayableReceivable:
          type: string
          nullable: true
          description: Descrição textual do status.
        Comments:
          type: string
          maxLength: 2000
          nullable: true
          description: Observações.
        DateCompetence:
          type: string
          format: date
          nullable: true
          description: Data de competência.
        DateDocument:
          type: string
          format: date
          nullable: true
          description: Data do documento.
        DateDue:
          type: string
          format: date
          description: Data de vencimento.
        DateLastPayment:
          type: string
          format: date-time
          nullable: true
          description: Data e hora do último pagamento lançado.
        DocumentNumber:
          type: string
          maxLength: 200
          nullable: true
          description: Número do documento.
        RecordTimestamp:
          type: string
          format: date-time
          nullable: true
          description: Data e hora de criação do título.
        IDConsumer:
          type: integer
          format: int32
          nullable: true
          description: Identificador do cliente.
        IDSupplier:
          type: integer
          format: int32
          nullable: true
          description: Identificador do fornecedor (quando o título é uma devolução/estorno).
        ConsumerNameCorporateName:
          type: string
          nullable: true
          description: >-
            Razão social ou nome do cliente ou do fornecedor associado (a coluna serve aos dois conforme
            `IDConsumer`/`IDSupplier`).
        IDTypeAccount:
          type: integer
          enum:
            - 0
          description: Tipo de conta. Sempre `0` (entrada / a receber) nesta listagem.
        IDTypeAccountPayableReceivable:
          type: integer
          format: int32
          nullable: true
          description: Identificador do plano de contas.
        TypeAccountPaybleDescription:
          type: string
          nullable: true
          description: Descrição do plano de contas.
        IDTypeDocument:
          type: integer
          format: int32
          nullable: true
          description: Identificador do tipo de documento.
        TypeDocument:
          type: string
          nullable: true
          description: Descrição do tipo de documento.
        IDTypePayment:
          type: integer
          format: int32
          nullable: true
          description: Identificador do tipo de pagamento.
        TypePaymentDescription:
          type: string
          nullable: true
          description: Descrição do tipo de pagamento.
        TypePaymentCategory:
          type: string
          nullable: true
          description: Categoria do tipo de pagamento (Dinheiro, Boleto, Cartão de Crédito, etc.).
        IDOrder:
          type: integer
          format: int32
          nullable: true
          description: Identificador interno do pedido vinculado.
        Order:
          type: string
          nullable: true
          description: 'Número externo do pedido (ex.: `OT-1234`, `ML-5678`).'
        OrderFrom:
          type: string
          nullable: true
          description: Pedidos de origem do canal de venda, concatenados quando houver múltiplos.
        IDStatusOrder:
          type: integer
          format: int32
          nullable: true
          description: Status do pedido vinculado.
        OrderFinishConfirmation:
          type: integer
          format: int32
          nullable: true
          description: Indica se o tipo de pedido exige confirmação para finalização (vem do `TypeOrder`).
        ValueOrder:
          type: number
          nullable: true
          description: >-
            Valor total do pedido associado: soma de `PriceSellingTotal` dos itens + `ValueShipping` +
            `NfeAccessoryExpenses`.
        Installment:
          type: integer
          nullable: true
          description: Número da parcela deste título.
        InstallmentTotal:
          type: integer
          nullable: true
          description: Total de parcelas do plano original.
        TID:
          type: string
          maxLength: 45
          nullable: true
          description: TID — identificador da transação no adquirente, quando o título nasce de uma venda em cartão.
        NSU:
          type: string
          maxLength: 45
          nullable: true
          description: NSU — número sequencial único do adquirente, quando o título nasce de uma venda em cartão.
        NfeNumber:
          type: integer
          format: int32
          nullable: true
          description: Número da nota fiscal principal de origem.
        NfeChaveAcesso:
          type: string
          nullable: true
          description: Chave de acesso da nota fiscal principal de origem.
        NfeDhEmi:
          type: string
          format: date-time
          nullable: true
          description: Data e hora de emissão da nota fiscal principal de origem.
        IDBankAccountForecast:
          type: integer
          format: int32
          nullable: true
          description: Identificador da conta bancária prevista para o recebimento.
        BankForecast:
          type: string
          nullable: true
          description: Nome do banco da conta prevista, eventualmente concatenado com o número da conta.
        BankForecastAccountNumber:
          type: string
          nullable: true
          description: Número da conta bancária prevista.
        BankPayment:
          type: string
          nullable: true
          description: Bancos onde os pagamentos foram lançados (lista concatenada quando há múltiplos).
        DaysDue:
          type: integer
          format: int32
          nullable: true
          description: Diferença em dias entre a data atual e o vencimento.
        Value:
          type: number
          description: >-
            Valor base do título (já convertido para número; quando o valor não é numérico, vira a posição do item
            (comportamento defensivo do legado)).
        ValueDiscount:
          type: number
          description: Valor de desconto (zero quando inválido).
        ValueInterest:
          type: number
          description: Valor de juros (zero quando inválido).
        ValuePenalty:
          type: number
          description: Valor de multa (zero quando inválido).
        ValueTotal:
          type: number
          description: 'Valor total efetivo: `Value + ValuePenalty + ValueInterest - ValueDiscount` (arredondado para 2 casas).'
        ValuePaid:
          type: number
          description: Soma dos pagamentos lançados.
        ValuePaymentPending:
          type: number
          description: 'Saldo pendente de recebimento: `ValueTotal - ValuePaid` (arredondado para 2 casas).'
        IDCompanyInvoice:
          type: integer
          format: int32
          nullable: true
          description: Identificador da empresa faturadora.
        AccountNameInvoice:
          type: string
          nullable: true
          description: Subdomínio da empresa faturadora.
        CompanyNameCorporateNameInvoice:
          type: string
          nullable: true
          description: Razão social da empresa faturadora.
        CompanyIntegration:
          type: string
          nullable: true
          description: Texto formatado com o tipo e nome da integração originadora.
    AccountsReceivableDetail:
      type: object
      description: >-
        Resposta detalhada do `GET /accounts/receivable/{idaccountreceivable}` (também o corpo do `POST` e `PUT` após a
        operação). Inclui dados próprios da conta, descrições resolvidas dos relacionamentos, listas auxiliares
        (arquivos, pagamentos, histórico, centros de custo) e as contas filhas geradas por conciliação adquirente ou
        marketplace.
      properties:
        AccountName:
          type: string
          description: Subdomínio da empresa dona da conta.
        IDAccountPayableReceivable:
          type: integer
          format: int32
          description: Identificador da conta a receber.
        IDStatusAccountPayableReceivable:
          type: integer
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
          nullable: true
          description: >-
            Status do título: 0=Aberto, 1=Vencido, 2=Pago, 3=Pago Parcialmente, 4=Não lançado, 5=Pago com acréscimo,
            6=Vence hoje.
        StatusAccountPayableReceivable:
          type: string
          nullable: true
          description: Descrição textual do status.
        Comments:
          type: string
          maxLength: 2000
          nullable: true
          description: Observações.
        DateCompetence:
          type: string
          format: date
          nullable: true
          description: Data de competência.
        DateDocument:
          type: string
          format: date
          nullable: true
          description: Data do documento.
        DateDue:
          type: string
          format: date
          description: Data de vencimento.
        DaysDue:
          type: integer
          format: int32
          nullable: true
          description: Diferença em dias entre a data atual e o vencimento.
        DocumentNumber:
          type: string
          maxLength: 200
          nullable: true
          description: Número do documento.
        RecordTimestamp:
          type: string
          format: date-time
          nullable: true
          description: Data e hora de criação do título.
        IDConsumer:
          type: integer
          format: int32
          nullable: true
          description: Identificador do cliente.
        IDSupplier:
          type: integer
          format: int32
          nullable: true
          description: Identificador do fornecedor.
        ConsumerNameCorporateName:
          type: string
          nullable: true
          description: Razão social ou nome do cliente (ou fornecedor, quando `IDConsumer` é nulo).
        SupplierNameCorporateName:
          type: string
          nullable: true
          description: Razão social ou nome do fornecedor.
        IDTypeAccount:
          type: integer
          enum:
            - 0
          description: Tipo de conta. Sempre `0` (entrada) — o sistema filtra por `IDTypeAccount=0`.
        IDTypeAccountPayableReceivable:
          type: integer
          format: int32
          nullable: true
          description: Identificador do plano de contas.
        TypeAccountPaybleDescription:
          type: string
          nullable: true
          description: Descrição do plano de contas.
        IDTypeDocument:
          type: integer
          format: int32
          nullable: true
          description: Identificador do tipo de documento.
        TypeDocument:
          type: string
          nullable: true
          description: Descrição do tipo de documento.
        IDTypePayment:
          type: integer
          format: int32
          nullable: true
          description: Identificador do tipo de pagamento.
        TypePaymentDescription:
          type: string
          nullable: true
          description: Descrição do tipo de pagamento.
        IDOrder:
          type: integer
          format: int32
          nullable: true
          description: Identificador interno do pedido vinculado.
        Order:
          type: string
          nullable: true
          description: Número externo do pedido.
        IDStatusOrder:
          type: integer
          format: int32
          nullable: true
          description: Status do pedido vinculado.
        OrderFinishConfirmation:
          type: integer
          format: int32
          nullable: true
          description: Indica se o tipo de pedido vinculado exige confirmação para finalização (herdado do `TypeOrder`).
        IDServiceOrder:
          type: integer
          format: int32
          nullable: true
          description: Identificador da ordem de serviço vinculada, quando o título nasce de uma OS.
        Installment:
          type: integer
          nullable: true
          description: 'Número da parcela deste título (ex.: 2 para a 2ª parcela).'
        InstallmentTotal:
          type: integer
          nullable: true
          description: Total de parcelas do plano de pagamento original.
        TID:
          type: string
          maxLength: 45
          nullable: true
          description: TID — identificador da transação no adquirente, quando o título nasce de uma venda em cartão.
        NSU:
          type: string
          maxLength: 45
          nullable: true
          description: NSU — número sequencial único do adquirente, quando o título nasce de uma venda em cartão.
        IDCompanyInvoice:
          type: integer
          format: int32
          nullable: true
          description: Identificador da empresa faturadora.
        AccountNameInvoice:
          type: string
          nullable: true
          description: Subdomínio da empresa faturadora.
        CompanyNameCorporateNameInvoice:
          type: string
          nullable: true
          description: Razão social da empresa faturadora.
        IDCompanyIntegration:
          type: integer
          format: int32
          nullable: true
          description: Identificador da integração originadora.
        CompanyIntegration:
          type: string
          nullable: true
          description: Texto formatado com o tipo e nome da integração.
        IDBankAccountForecast:
          type: integer
          format: int32
          nullable: true
          description: Identificador da conta bancária prevista para o recebimento.
        Bank:
          type: string
          nullable: true
          description: Nome do banco da conta prevista, eventualmente concatenado com o número da conta.
        BankForecastAccountNumber:
          type: string
          nullable: true
          description: Número da conta bancária prevista.
        Forecast:
          type: integer
          enum:
            - 0
            - 1
          description: Indica se o título é uma previsão (1) ou um lançamento real (0).
        Value:
          type: number
          description: Valor base do título, já convertido para número (zero quando inválido).
        ValueDiscount:
          type: number
          description: Valor de desconto (zero quando inválido).
        ValueInterest:
          type: number
          description: Valor de juros (zero quando inválido).
        ValuePenalty:
          type: number
          description: Valor de multa (zero quando inválido).
        ValueTotal:
          type: number
          description: 'Valor total efetivo: `Value + ValuePenalty + ValueInterest - ValueDiscount`.'
        Files:
          type: array
          description: Arquivos anexados à conta (PDF, XML, boleto, comprovante de recebimento).
          items:
            $ref: '#/components/schemas/FileAttachment'
        Payments:
          type: array
          description: Lançamentos do extrato bancário vinculados a esta conta.
          items:
            $ref: '#/components/schemas/BankStatementPayment'
        AccountsPayableReceivableLog:
          type: array
          description: Histórico de alterações da conta, em ordem decrescente de data.
          items:
            $ref: '#/components/schemas/AccountsPayableLogEntry'
        AccountsPayableReceivableCostCenter:
          type: array
          description: Centros de custo com o valor rateado a partir do total da conta.
          items:
            $ref: '#/components/schemas/AccountsPayableCostCenter'
        RelatedAccountsPayableReceivable:
          type: array
          nullable: true
          description: >-
            Contas filhas geradas por conciliação (taxa adquirente, comissão de marketplace, antecipação, frete, cupom,
            impostos do marketplace).
          items:
            $ref: '#/components/schemas/RelatedAccountsPayable'
    AccountsReceivablePaymentCreate:
      type: object
      description: Corpo do `POST /accounts/receivable/{idaccountreceivable}/payment`.
      required:
        - IDBankAccount
        - DateTransactionTimestamp
      properties:
        IDBankAccount:
          type: integer
          format: int32
          description: >-
            Conta bancária onde o recebimento foi lançado. Quando a conta tinha `IDBankAccountForecast` nulo, esse valor
            passa a ser a previsão.
        DateTransactionTimestamp:
          type: string
          format: date-time
          description: Data e hora do recebimento.
        Value:
          type: number
          nullable: true
          description: Valor recebido. Quando omitido, o sistema assume `null` (sem valor).
        TransactionDescription:
          type: string
          default: ''
          maxLength: 100
          description: Descrição livre do lançamento.
        TransactionDocument:
          type: string
          default: ''
          maxLength: 45
          description: Documento associado ao lançamento (comprovante, TID, etc.).
        IDAccountsPayableReceivableConciliation:
          type: integer
          format: int32
          nullable: true
          description: >-
            Identificador da conciliação adquirente à qual este lançamento se refere. Quando informado e o valor difere
            do título, dispara a redistribuição automática entre lançamentos relacionados e a criação do lançamento de
            taxa do adquirente.
        IDAccountsPayableReceivableConciliationMarketplace:
          type: integer
          format: int32
          nullable: true
          description: >-
            Identificador da conciliação de marketplace. Quando informado, gera automaticamente as contas filhas para
            comissão, antecipação, frete, cupom e impostos do marketplace conforme a parametrização da integração.
    AccountsReceivableConciliationUpdate:
      type: object
      description: >-
        Corpo do `PUT /accounts/receivable/conciliation/{idaccountspayablereceivableconciliation}`. Apenas `Comments` é
        alterável.
      properties:
        Comments:
          type: string
          maxLength: 255
          nullable: true
          description: Observações sobre a conciliação.
    AccountsReceivableConciliationListItem:
      type: object
      description: >-
        Item da resposta default de `GET /accounts/receivable/conciliation`. Cada item agrega os vínculos a contas a
        receber e a lançamentos do extrato bancário em `IDAccountPayableReceivable` (lista concatenada) e `IDOrder`
        (lista concatenada).
      properties:
        IDAccountsPayableReceivableConciliation:
          type: integer
          format: int32
          description: Identificador único da conciliação.
        AccountName:
          type: string
          description: Subdomínio da empresa dona da conciliação.
        CompanyIntegration:
          type: string
          description: Texto formatado com o tipo e nome da integração adquirente.
        IDCompanyIntegration:
          type: integer
          format: int32
          description: Identificador da integração adquirente.
        TID:
          type: string
          maxLength: 45
          nullable: true
          description: TID da transação no adquirente.
        NSU:
          type: string
          maxLength: 45
          nullable: true
          description: NSU — número sequencial único da transação no adquirente.
        ExternalIDOrderReference:
          type: string
          maxLength: 45
          nullable: true
          description: Referência externa do pedido enviada pelo adquirente.
        Installment:
          type: integer
          description: Número da parcela.
        InstallmentTotal:
          type: integer
          description: Total de parcelas.
        SaleDate:
          type: string
          format: date
          nullable: true
          description: Data da venda.
        ReceivedDate:
          type: string
          format: date
          description: Data de recebimento.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora de cadastro da conciliação.
        TotalValue:
          type: number
          description: Valor total declarado pelo adquirente (negativo em estornos).
        ReceivedValue:
          type: number
          description: Valor efetivamente recebido após taxas.
        MerchantDiscountRateEffectiveValue:
          type: number
          description: Valor efetivo da taxa MDR (Merchant Discount Rate) cobrada pelo adquirente.
        MerchantDiscountRateEffectiveValueRate:
          type: number
          description: 'Percentual efetivo da MDR: `MerchantDiscountRateEffectiveValue / TotalValue` (4 casas decimais).'
        AnticipationRateEffectiveValue:
          type: number
          description: Valor efetivo da taxa de antecipação cobrada pelo adquirente.
        AnticipationRateEffectiveValueRate:
          type: number
          description: 'Percentual efetivo da antecipação: `AnticipationRateEffectiveValue / TotalValue` (4 casas decimais).'
        IDTypePaymentFrom:
          type: integer
          format: int32
          description: Identificador do tipo de pagamento do adquirente.
        TypePayment:
          type: string
          description: Descrição do tipo de pagamento do adquirente.
        IDTypePayment:
          type: integer
          format: int32
          nullable: true
          description: Sugestão de tipo de pagamento interno, baseada na categoria do adquirente e parametrização.
        IDTypeAcquirerReleaseType:
          type: integer
          format: int32
          nullable: true
          description: Identificador do tipo de liberação do adquirente.
        ReceivableIDBankAccount:
          type: integer
          format: int32
          nullable: true
          description: Conta bancária declarada pelo adquirente para o recebimento.
        Bank:
          type: string
          nullable: true
          description: Nome do banco da conta declarada pelo adquirente.
        Status:
          type: integer
          format: int32
          description: Status retornado pelo adquirente (`IDTypeAcquirerStatus`).
        TypeAcquirerStatus:
          type: string
          description: Descrição do status do adquirente.
        ConciliationStatus:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
          description: >-
            Status interno de conciliação: 1=Não conciliado, 2=Conciliação automática, 3=Conciliação manual,
            4=Conciliação parcial.
        AutomaticReceivableAnticipation:
          type: integer
          format: int32
          nullable: true
          description: Indica se a antecipação automática foi acionada pelo adquirente.
        Comments:
          type: string
          maxLength: 255
          nullable: true
          description: Observações sobre a conciliação.
        IDAccountPayableReceivable:
          type: string
          nullable: true
          description: Lista concatenada (por vírgula) dos identificadores de contas a receber vinculadas à conciliação.
        IDOrder:
          type: string
          nullable: true
          description: Lista concatenada (por vírgula) dos identificadores de pedidos vinculados (via contas a receber).
    AccountsReceivableConciliationAuditItem:
      type: object
      description: >-
        Item da resposta de `GET /accounts/receivable/conciliation` quando `AuditRate=1`. Compara as taxas efetivas
        pagas com as taxas configuradas em `TypePaymentRate` e calcula o impacto financeiro da diferença.
      properties:
        IDAccountsPayableReceivableConciliation:
          type: integer
          format: int32
          description: >-
            Identificador interno do lançamento de conciliação de cartão/marketplace (linha da prévia enviada pela
            adquirente).
        IntegrationName:
          type: string
          description: Texto formatado com o tipo e nome da integração adquirente.
        TID:
          type: string
          maxLength: 45
          nullable: true
          description: >-
            TID (Transaction ID) da venda na adquirente. Identificador único da transação atribuído pelo
            gateway/adquirente.
        NSU:
          type: string
          maxLength: 45
          nullable: true
          description: NSU (Número Sequencial Único) da transação na adquirente.
        ExternalIDOrderReference:
          type: string
          maxLength: 45
          nullable: true
          description: >-
            Identificador externo do pedido na adquirente/marketplace (referência usada para casar a transação com o
            pedido na loja).
        SaleDate:
          type: string
          format: date
          nullable: true
          description: >-
            Data da venda original no formato `YYYY-MM-DD` (data em que a transação foi capturada pela adquirente). Pode
            vir vazia quando a adquirente não informa.
        ReceivedDate:
          type: string
          format: date
          description: >-
            Data prevista de recebimento do valor pela conta da loja, no formato `YYYY-MM-DD` (após o prazo D+N da
            adquirente).
        Installment:
          type: integer
          description: Número da parcela desta transação (1, 2, 3...).
        InstallmentTotal:
          type: integer
          description: 'Total de parcelas da transação original (ex.: 6 quando é venda em 6x).'
        TotalValue:
          type: number
          description: Valor total declarado pelo adquirente.
        ReceivedValue:
          type: number
          description: Valor efetivamente recebido.
        StatusAcquirer:
          type: integer
          format: int32
          description: Status retornado pelo adquirente.
        TypePayment:
          type: string
          description: Tipo de pagamento do adquirente.
        IDTypePayment:
          type: integer
          format: int32
          nullable: true
          description: Identificador do tipo de pagamento associado em `TypePaymentRate`.
        AutomaticReceivableAnticipation:
          type: integer
          format: int32
          nullable: true
          description: >-
            `1` quando a parcela foi antecipada automaticamente pela adquirente (programa de antecipação automática
            contratado); `0`/`null` caso contrário.
        IDOrder:
          type: integer
          format: int32
          nullable: true
          description: Pedido vinculado à conciliação (quando há vínculo via conta a receber).
        IDAccountPayableReceivable:
          type: integer
          format: int32
          nullable: true
          description: Conta a receber vinculada à conciliação.
        AppliedMDRValue:
          type: number
          nullable: true
          description: Valor da MDR efetivamente cobrada.
        AppliedMDRPercent:
          type: number
          description: Percentual efetivo da MDR aplicada (4 casas decimais).
        ConfigMDRPercent:
          type: number
          nullable: true
          description: Percentual da MDR configurado em `TypePaymentRate`.
        ConfigMDRValue:
          type: number
          nullable: true
          description: 'Valor esperado da MDR: `TotalValue × ConfigMDRPercent + ConfigFixedRate`.'
        AppliedAntValue:
          type: number
          nullable: true
          description: Valor da taxa de antecipação efetivamente cobrada.
        AppliedAntPercent:
          type: number
          description: Percentual efetivo da antecipação aplicada (4 casas decimais).
        ConfigAntPercent:
          type: number
          nullable: true
          description: Percentual da antecipação configurado em `TypePaymentRate`.
        ConfigAntValue:
          type: number
          nullable: true
          description: 'Valor esperado da antecipação: `TotalValue × ConfigAntPercent`.'
        ConfigFixedRate:
          type: number
          description: Taxa fixa adicional configurada para o tipo de pagamento.
        DiffMDRPercent:
          type: number
          description: 'Diferença em percentual da MDR: efetivo - configurado (4 casas decimais).'
        DiffAntPercent:
          type: number
          description: 'Diferença em percentual da antecipação: efetiva - configurada (4 casas decimais).'
        DiffValue:
          type: number
          description: >-
            Diferença em valor entre o total efetivo cobrado e o esperado pela configuração: `(MDRAplicada +
            AntAplicada) - (MDREsperada + AntEsperada)`.
        ValueDifferenceAllow:
          type: number
          description: Tolerância em valor configurada na empresa (`Key='ValueDifferenceAllow'`); zero quando não configurada.
        IDAuditStatus:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
          description: >-
            Classificação calculada da auditoria: 1=Verde (diferença mínima, OK), 2=Azul (estorno ou diferença sem
            prejuízo), 3=Amarelo (sem configuração de MDR e antecipação), 4=Laranja (taxa configurada > 0 mas não
            aplicada), 5=Vermelho (diferença acima da tolerância e com prejuízo).
    AccountsReceivableMarketplaceConciliationItem:
      type: object
      description: >-
        Item agrupado de `GET /accounts/receivable/marketplace-conciliation`. Cada item corresponde a uma conciliação de
        marketplace, com a decomposição dos valores liberados (comissão, frete, antecipação, cupom, impostos) e a lista
        de contas a receber internas vinculadas.
      properties:
        IDAccountsPayableReceivableConciliationMarketplace:
          type: integer
          format: int32
          description: Identificador único da conciliação de marketplace.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora de cadastro da conciliação.
        IDCompanyIntegration:
          type: integer
          format: int32
          description: Identificador da integração de marketplace.
        CompanyIntegration:
          type: string
          description: Texto formatado com o tipo e nome da integração.
        AccountName:
          type: string
          description: Subdomínio da empresa dona.
        TID:
          type: string
          maxLength: 40
          description: TID da conciliação.
        OrderId:
          type: string
          maxLength: 45
          nullable: true
          description: Identificador externo do pedido no marketplace.
        IDOrder:
          type: integer
          format: int32
          nullable: true
          description: Identificador interno do pedido vinculado (resolvido via `HubOrder`).
        ShippingId:
          type: string
          maxLength: 40
          nullable: true
          description: Identificador do envio no marketplace.
        Installment:
          type: integer
          description: Número da parcela declarada pelo marketplace.
        InstallmentTotal:
          type: integer
          description: Total de parcelas declarado pelo marketplace.
        SaleDate:
          type: string
          format: date
          nullable: true
          description: Data da venda informada pelo marketplace.
        ReceivedDate:
          type: string
          format: date
          nullable: true
          description: Data prevista (ou efetiva) de recebimento do valor liberado pelo marketplace.
        Comments:
          type: string
          maxLength: 500
          nullable: true
          description: Observações da conciliação.
        TotalValue:
          type: number
          nullable: true
          description: Valor bruto declarado pelo marketplace.
        ReceivedValue:
          type: number
          nullable: true
          description: Valor líquido recebido após deduções.
        MarketplaceFeeValue:
          type: number
          nullable: true
          description: Valor de comissão cobrado pelo marketplace.
        MarketplaceFeePct:
          type: number
          nullable: true
          description: Percentual da comissão sobre o `TotalValue`.
        MarketplaceShippingFeeValue:
          type: number
          nullable: true
          description: Valor de frete cobrado pelo marketplace.
        MarketplaceShippingFeePct:
          type: number
          nullable: true
          description: Percentual do frete sobre o `TotalValue`.
        MarketplaceFinancingFeeValue:
          type: number
          nullable: true
          description: Valor de antecipação/financiamento cobrado pelo marketplace.
        MarketplaceFinancingFeePct:
          type: number
          nullable: true
          description: Percentual da taxa de antecipação/financiamento sobre o `TotalValue`.
        MarketplaceTaxesValue:
          type: number
          nullable: true
          description: Valor de tributos descontados pelo marketplace.
        MarketplaceTaxesPct:
          type: number
          nullable: true
          description: Percentual dos tributos descontados pelo marketplace sobre o `TotalValue`.
        MarketplaceCouponValue:
          type: number
          nullable: true
          description: Valor de cupom de desconto aplicado pelo marketplace.
        MarketplaceCouponPct:
          type: number
          nullable: true
          description: Percentual do cupom de desconto aplicado pelo marketplace sobre o `TotalValue`.
        IDTypeAcquirerStatus:
          type: integer
          format: int32
          description: Identificador do status do marketplace.
        TypeAcquirerStatus:
          type: string
          description: Descrição do status do marketplace.
        IDTypeStatusConciliation:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
          description: >-
            Status de conciliação: `1` Não conciliado, `2` Conciliado automaticamente, `3` Conciliado manualmente, `4`
            Conciliado parcialmente.
        IDBankAccount:
          type: string
          nullable: true
          description: Conta bancária configurada para a integração (vinda de `Key='IDBankAccount'`).
        InternalAccounts:
          type: array
          description: >-
            Contas a receber e a pagar internas vinculadas a esta conciliação (resultado do vínculo via
            `AccountsPayableReceivableBankStatement`).
          items:
            type: object
            properties:
              IDBankStatement:
                type: integer
                format: int32
                description: Identificador do lançamento no extrato bancário.
              IDAccountPayableReceivable:
                type: integer
                format: int32
                description: Identificador da conta a receber/pagar vinculada.
              Document:
                type: string
                nullable: true
                description: Número do documento da conta.
              Description:
                type: string
                nullable: true
                description: Observações da conta.
              Value:
                type: number
                description: >-
                  Valor líquido da conta — positivo quando é a receber (`IDTypeAccount=0`), negativo quando é a pagar
                  (`IDTypeAccount=1`).
              IDTypeAccount:
                type: integer
                enum:
                  - 0
                  - 1
                description: 'Tipo da conta vinculada: 0=entrada (a receber), 1=saída (a pagar).'
        ERPValueTotal:
          type: number
          description: >-
            Soma dos valores líquidos das `InternalAccounts` (a receber positivo, a pagar negativo). Permite bater com
            `ReceivedValue` do marketplace.
        MarketplaceOtherFeeValue:
          type: number
          nullable: true
          description: Valor de outras taxas cobradas pelo marketplace.
        MarketplaceOtherFeePct:
          type: number
          nullable: true
          description: Percentual das outras taxas do marketplace sobre o `TotalValue`.
    BankStatementConciliationCreate:
      type: object
      description: >-
        Corpo do `POST /accounts/bank-statement`. Identifique **exatamente uma** conciliação
        (`IDBankStatementConciliation` ou `IDAccountsPayableReceivableConciliation`) e **exatamente uma** das listas
        (`Accounts` ou `Transfers`).
      required:
        - IDBankAccount
      properties:
        IDBankStatementConciliation:
          type: integer
          format: int32
          description: Identificador da conciliação bancária. Mutuamente exclusivo com `IDAccountsPayableReceivableConciliation`.
        IDAccountsPayableReceivableConciliation:
          type: integer
          format: int32
          description: Identificador da conciliação de adquirente. Mutuamente exclusivo com `IDBankStatementConciliation`.
        IDBankAccount:
          type: integer
          format: int32
          description: Conta bancária em que os lançamentos serão registrados.
        Accounts:
          type: array
          description: Lista de títulos a pagar/receber a serem conciliados. Mutuamente exclusivo com `Transfers`.
          items:
            type: object
            required:
              - IDAccountPayableReceivable
            properties:
              IDAccountPayableReceivable:
                type: integer
                format: int32
                description: Identificador do título a pagar/receber.
        Transfers:
          type: array
          description: >-
            Lista de transferências entre contas (lançamentos do extrato sem título associado) a serem conciliadas.
            Mutuamente exclusivo com `Accounts`.
          items:
            type: object
            required:
              - IDBankStatement
            properties:
              IDBankStatement:
                type: integer
                format: int32
                description: Identificador do lançamento de transferência no extrato interno.
    BankStatementConciliationCreateResponse:
      type: object
      description: >-
        Resultado de `POST /accounts/bank-statement`. Espelha a estrutura de um item de `GET
        /accounts/bank-statement?Source=2` (conciliação bancária com a lista de contas internas vinculadas).
      properties:
        IDBankStatementConciliation:
          type: integer
          format: int32
          nullable: true
          description: Identificador da conciliação bancária. Nulo quando o vínculo é com uma conciliação de adquirente.
        IDAccountsPayableReceivableConciliation:
          type: integer
          format: int32
          nullable: true
          description: Identificador da conciliação de adquirente. Nulo quando o vínculo é com uma conciliação bancária.
        IDBankAccount:
          type: integer
          format: int32
          description: Conta bancária onde os lançamentos da conciliação foram registrados.
        TransactionDate:
          type: string
          nullable: true
          description: Data do lançamento de conciliação reaproveitada para os lançamentos vinculados.
          format: date
        BankTransactionID:
          type: string
          nullable: true
          description: >-
            Identificador externo do lançamento — `BankTransactionID` no caso bancário, `TID`/`NSU` no caso de
            adquirente.
        Comments:
          type: string
          nullable: true
          description: Descrição reaproveitada do lançamento de conciliação. Para adquirente, vem como `Conciliação de adquirente`.
        BankValue:
          type: number
          description: Valor do lançamento de conciliação (origem do vínculo).
        BankName:
          type: string
          nullable: true
          description: Nome amigável do lançamento — banco no caso bancário, integração no caso de adquirente.
        IDTypeStatusConciliation:
          type: integer
          enum:
            - 1
            - 3
            - 4
          description: >-
            Status final aplicado: 1=Não conciliado, 3=Conciliação manual (valores batem), 4=Conciliação parcial (ainda
            falta reconciliar). Em conciliação de adquirente, sempre `3`.
        StatusDescription:
          type: string
          description: 'Descrição do status: `Não Conciliado`, `Concil. Manualmente`, `Concil. Parcialmente`.'
        IDTypeAccount:
          type: integer
          enum:
            - 0
            - 1
          description: 'Tipo do lançamento: 0=entrada, 1=saída. Em conciliação de adquirente, sempre `0`.'
        InternalAccounts:
          type: array
          description: Lançamentos do extrato interno criados (ou reaproveitados) e vinculados à conciliação.
          items:
            type: object
            properties:
              IDBankStatement:
                type: integer
                format: int32
                description: Identificador do lançamento criado (ou reaproveitado) no extrato interno.
              IDAccountPayableReceivable:
                type: integer
                format: int32
                nullable: true
                description: Título vinculado (vazio quando o vínculo é com uma transferência).
              Description:
                type: string
                nullable: true
                description: Descrição do lançamento (herdada do título conciliado).
              Document:
                type: string
                nullable: true
                description: Número do documento do lançamento (herdado do título conciliado).
              Value:
                type: number
                description: Valor do lançamento — positivo quando entrada (a receber), negativo quando saída (a pagar).
              IDTypeAccount:
                type: integer
                enum:
                  - 0
                  - 1
                description: 'Tipo do lançamento: 0=entrada (a receber), 1=saída (a pagar).'
        ERPValueTotal:
          type: number
          description: Soma dos valores dos títulos conciliados nesta chamada.
        AccountName:
          type: string
          nullable: true
          description: Subdomínio da empresa dona da conciliação.
        Difference:
          type: number
          description: Diferença `BankValue - ERPValueTotal` — quanto ainda falta reconciliar para fechar o lançamento.
    BankStatementTransferCreate:
      type: object
      description: >-
        Corpo do `POST /accounts/bank-statement/transfer`. A descrição informada é concatenada com o banco e o número da
        conta do outro lado nos dois lançamentos gerados.
      required:
        - IDBankFrom
        - IDBankTo
        - Value
      properties:
        IDBankFrom:
          type: integer
          format: int32
          description: Conta bancária de origem (debitada).
        IDBankTo:
          type: integer
          format: int32
          description: Conta bancária de destino (creditada). Tem que ser diferente de `IDBankFrom`.
        Value:
          type: number
          description: Valor da transferência. Deve ser maior que zero.
        Date:
          type: string
          format: date
          description: 'Data da transação (`YYYY-MM-DD`). Default: hoje.'
        Description:
          type: string
          description: 'Descrição base aplicada aos dois lançamentos. Default: `Transferência entre contas`.'
        Document:
          type: string
          nullable: true
          description: Número do documento da transferência (eco em `TransactionDocument` nos dois lançamentos).
    BankStatementTransferCreateResponse:
      type: object
      description: >-
        Resultado de `POST /accounts/bank-statement/transfer`. Inclui a referência da transferência e os dois
        lançamentos do extrato (débito e crédito).
      properties:
        message:
          type: string
          description: Mensagem fixa de sucesso (`Transferência entre contas realizada com sucesso`).
        IDAccountsPayableReceivableBankStatementTransfer:
          type: integer
          format: int32
          nullable: true
          description: >-
            Identificador da referência da transferência. Pode ser nulo quando o registro de referência falha após os
            lançamentos terem sido gravados.
        Transfer:
          type: object
          description: Detalhes consolidados da transferência.
          properties:
            From:
              type: object
              description: Conta debitada (origem).
              properties:
                IDBankAccount:
                  type: integer
                  format: int32
                  description: Identificador da conta bancária debitada (origem).
                Bank:
                  type: string
                  nullable: true
                  description: Nome do banco da conta debitada.
                AccountNumber:
                  type: string
                  nullable: true
                  description: Número da conta debitada.
                IDBankStatement:
                  type: integer
                  format: int32
                  description: Identificador do lançamento de débito no extrato.
            To:
              type: object
              description: Conta creditada (destino).
              properties:
                IDBankAccount:
                  type: integer
                  format: int32
                  description: Identificador da conta bancária creditada (destino).
                Bank:
                  type: string
                  nullable: true
                  description: Nome do banco da conta creditada.
                AccountNumber:
                  type: string
                  nullable: true
                  description: Número da conta creditada.
                IDBankStatement:
                  type: integer
                  format: int32
                  description: Identificador do lançamento de crédito no extrato.
            Value:
              type: string
              description: Valor da transferência com 2 casas decimais (eco normalizado de `Value`).
            TransactionDate:
              type: string
              format: date
              description: Data da transação aplicada aos dois lançamentos (formato `YYYY-MM-DD`).
            Description:
              type: string
              description: Descrição base informada na requisição (antes da concatenação com o banco/conta do outro lado).
            Document:
              type: string
              nullable: true
              description: Número do documento informado na requisição, ecoado nos dois lançamentos.
        InsertedTransactions:
          type: array
          description: Os dois lançamentos criados — primeiro o de débito (origem), depois o de crédito (destino).
          items:
            type: object
            properties:
              IDBankStatement:
                type: integer
                format: int32
                description: Identificador do lançamento criado no extrato.
              IDBankAccount:
                type: integer
                format: int32
                description: Identificador da conta bancária onde o lançamento foi registrado.
              IDTypeAccount:
                type: integer
                enum:
                  - 0
                  - 1
                description: 0=crédito (entrada), 1=débito (saída).
              Value:
                type: string
                description: Valor com 2 casas decimais.
              Description:
                type: string
                description: >-
                  Descrição final do lançamento — a base informada concatenada com o banco e número da conta do outro
                  lado.
              Type:
                type: string
                enum:
                  - Debit
                  - Credit
                description: >-
                  Sinal do lançamento: `Debit` para o débito na conta de origem, `Credit` para o crédito na conta de
                  destino.
    BankStatementTransferDeleteResponse:
      type: object
      description: >-
        Resultado de `DELETE /accounts/bank-statement/transfer/{idbankstatement}`. Traz a referência removida e os dois
        lançamentos apagados.
      properties:
        Message:
          type: string
          description: Mensagem fixa de sucesso (`Transferência excluída com sucesso`).
        DeletedTransfer:
          type: object
          properties:
            IDAccountsPayableReceivableBankStatementTransfer:
              type: integer
              format: int32
              description: Identificador da referência da transferência removida.
            Debit:
              type: object
              description: Lançamento de débito (saída) removido.
              properties:
                IDBankStatement:
                  type: integer
                  format: int32
                  description: Identificador do lançamento de débito removido.
                IDBankAccount:
                  type: integer
                  format: int32
                  description: Identificador da conta bancária debitada (origem da transferência).
                Value:
                  type: number
                  description: Valor do lançamento de débito removido.
                Description:
                  type: string
                  nullable: true
                  description: Descrição final do lançamento de débito removido.
            Credit:
              type: object
              description: Lançamento de crédito (entrada) removido.
              properties:
                IDBankStatement:
                  type: integer
                  format: int32
                  description: Identificador do lançamento de crédito removido.
                IDBankAccount:
                  type: integer
                  format: int32
                  description: Identificador da conta bancária creditada (destino da transferência).
                Value:
                  type: number
                  description: Valor do lançamento de crédito removido.
                Description:
                  type: string
                  nullable: true
                  description: Descrição final do lançamento de crédito removido.
          description: Detalhamento da transferência removida (referência e os dois lançamentos apagados).
    BankStatementConciliationRuleListItem:
      type: object
      description: >-
        Item de `GET /accounts/bank-statement/conciliation-rule`. Inclui os campos da regra, a descrição amigável do
        tipo de regra (`TypeBankStatementConciliationRule`) e o nome resolvido das entidades referenciadas (conta
        bancária, plano de contas, fornecedor, cliente, etc.).
      properties:
        IDBankStatementConciliationRule:
          type: integer
          format: int32
          description: Identificador da regra.
        AccountName:
          type: string
          description: Subdomínio da empresa dona da regra.
        IDBankAccount:
          type: integer
          format: int32
          description: Conta bancária à qual a regra se aplica.
        Bank:
          type: string
          description: >-
            Nome do banco da `IDBankAccount`, concatenado com o número da conta quando disponível (formato `Banco -
            Número`).
        IDTypeAccount:
          type: integer
          enum:
            - 0
            - 1
          description: 'Tipo de transação à qual a regra se aplica: `0` crédito (entrada), `1` débito (saída).'
        TypeAccount:
          type: string
          enum:
            - Crédito
            - Débito
          description: Descrição amigável de `IDTypeAccount` (`Crédito` ou `Débito`).
        Description:
          type: string
          description: Descrição livre da regra. Única por conta bancária.
        IDTypeRule:
          type: integer
          enum:
            - 1
            - 2
          description: 'Tipo da regra: `1` casa contra contas a pagar/receber, `2` casa contra transferências entre contas.'
        TypeBankStatementConciliationRule:
          type: string
          enum:
            - Contas pagar/receber
            - Transferência
          description: Descrição amigável de `IDTypeRule`.
        IDTypeAccountPayableReceivable:
          type: integer
          format: int32
          nullable: true
          description: (Tipo 1) Filtra pelo plano de contas. Ignorado quando `IDTypeRule=2`.
        TypeAccountPaybleDescription:
          type: string
          nullable: true
          description: Descrição do plano de contas (quando aplicável).
        IDTypeDocument:
          type: integer
          format: int32
          nullable: true
          description: (Tipo 1) Filtra pelo tipo de documento.
        TypeDocument:
          type: string
          nullable: true
          description: Descrição do tipo de documento.
        IDTypePayment:
          type: integer
          format: int32
          nullable: true
          description: (Tipo 1) Filtra pelo tipo de pagamento.
        TypePaymentDescription:
          type: string
          nullable: true
          description: Descrição do tipo de pagamento.
        IDSupplier:
          type: integer
          format: int32
          nullable: true
          description: (Tipo 1) Filtra pelo fornecedor.
        SupplierNameCorporateName:
          type: string
          nullable: true
          description: Nome/razão social do fornecedor.
        IDConsumer:
          type: integer
          format: int32
          nullable: true
          description: (Tipo 1) Filtra pelo cliente.
        ConsumerNameCorporateName:
          type: string
          nullable: true
          description: Nome/razão social do cliente.
        IDBankAccountTo:
          type: integer
          format: int32
          nullable: true
          description: (Tipo 2) Conta bancária de destino da transferência.
        BankTo:
          type: string
          nullable: true
          description: Nome do banco de destino (mesmo formato de `Bank`).
        BankStatementConciliationRuleStatus:
          type: integer
          description: Status interno da regra (1 = ativa).
        RecordTimestamp:
          type: string
          format: date-time
          description: Data de criação da regra.
    BankStatementConciliationRuleCreate:
      type: object
      description: >-
        Corpo de `POST /accounts/bank-statement/conciliation-rule` e `PUT
        /accounts/bank-statement/conciliation-rule/{idbankstatementconciliationrule}`. Para `IDTypeRule=1`, os campos de
        filtro (plano de contas, tipo documento, tipo pagamento, fornecedor, cliente) são opcionais e usados como
        predicado adicional; `IDBankAccountTo` é ignorado. Para `IDTypeRule=2`, `IDBankAccountTo` é obrigatório e os
        filtros são ignorados.
      required:
        - IDBankAccount
        - IDTypeRule
      properties:
        IDBankAccount:
          type: integer
          format: int32
          description: Conta bancária à qual a regra se aplica.
        IDTypeAccount:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: 'Tipo de transação: `0` crédito (entrada), `1` débito (saída).'
        Description:
          type: string
          nullable: true
          description: Descrição livre da regra. Não pode repetir para a mesma conta bancária.
        IDTypeRule:
          type: integer
          enum:
            - 1
            - 2
          description: '`1` contas a pagar/receber, `2` transferência.'
        IDTypeAccountPayableReceivable:
          type: integer
          format: int32
          nullable: true
          description: (Tipo 1) Plano de contas usado como filtro adicional.
        IDTypeDocument:
          type: integer
          format: int32
          nullable: true
          description: (Tipo 1) Tipo de documento usado como filtro adicional.
        IDTypePayment:
          type: integer
          format: int32
          nullable: true
          description: (Tipo 1) Tipo de pagamento usado como filtro adicional.
        IDSupplier:
          type: integer
          format: int32
          nullable: true
          description: (Tipo 1) Fornecedor usado como filtro adicional.
        IDConsumer:
          type: integer
          format: int32
          nullable: true
          description: (Tipo 1) Cliente usado como filtro adicional.
        IDBankAccountTo:
          type: integer
          format: int32
          nullable: true
          description: (Tipo 2) Conta bancária de destino. Obrigatório quando `IDTypeRule=2`. Não pode ser igual a `IDBankAccount`.
    TypeAccountTreeNode:
      type: object
      description: >-
        Nó da árvore de planos de contas (`GET /type/account/type?Type=Tree`). Cada nó traz seus descendentes em
        `Children[]`. A descrição é prefixada com o `ExternalCode` quando ele existe (formato `<código>-<descrição>`).
        Filhos herdam a categoria do pai.
      properties:
        IDTypeAccountPayble:
          type: integer
          format: int32
          description: Identificador do plano de contas.
        AccountName:
          type: string
          description: Subdomínio da empresa dona do plano.
        TypeAccountPaybleDescription:
          type: string
          description: Descrição do plano. Quando `ExternalCode` está preenchido, vem como `<ExternalCode>-<Descrição>`.
        IDTypeAccountPaybleFather:
          type: integer
          format: int32
          description: Identificador do plano pai. Vem `0` quando o plano é raiz (não-nulo via `IFNULL`).
        TypeAccountPaybleFatherDescription:
          type: string
          nullable: true
          description: Descrição do plano pai (preenchida apenas em nós filhos, propagada pelo sistema).
        Status:
          type: integer
          enum:
            - 1
          description: Sempre `1` (apenas planos ativos são retornados).
        IDTypeAccount:
          type: integer
          enum:
            - 0
            - 1
          description: 'Tipo do lançamento: `0` entrada (a receber), `1` saída (a pagar).'
        IDTypeCategoryAccountPayble:
          type: integer
          nullable: true
          description: Categoria do plano (ver `GET /type/account/type/category`). Filhos herdam do pai.
        TypeCategoryAccountPaybleDescription:
          type: string
          nullable: true
          description: Descrição da categoria (resolvida do JOIN).
        ExternalCode:
          type: string
          nullable: true
          description: Código de referência externo do plano. Único entre planos ativos da empresa.
        InternalCode:
          type: string
          nullable: true
          description: Código de referência interno do plano. Único entre planos ativos da empresa.
        InternalCodeShort:
          type: string
          nullable: true
          description: Versão reduzida do código interno.
        DefaultOrder:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` quando este é o plano padrão para pedidos da empresa. Apenas um plano por empresa pode estar marcado.'
        DefaultPurchase:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` quando este é o plano padrão para compras da empresa. Apenas um plano por empresa pode estar marcado.'
        Children:
          type: array
          description: Descendentes diretos do nó, ordenados por descrição. Vazio para nós folha.
          items:
            type: object
            description: (referência recursiva a `TypeAccountTreeNode` — não expandida)
    TypeAccountFlatItem:
      type: object
      description: >-
        Item da lista plana do plano de contas (`GET /type/account/type` sem `Type`). Mesmos campos do nó da árvore, com
        algumas diferenças: a descrição **não** é prefixada com `ExternalCode`, não vem `Children`, e o caminho
        hierárquico completo é exposto em `CategoryTree`.
      properties:
        IDTypeAccountPayble:
          type: integer
          format: int32
          description: Identificador do plano de contas.
        AccountName:
          type: string
          description: Subdomínio (identificador) da empresa dona do plano.
        TypeAccountPaybleDescription:
          type: string
          description: Descrição do plano (sem o prefixo de `ExternalCode`).
        CategoryTree:
          type: string
          description: 'Caminho hierárquico do plano em texto, separado por ` -> ` (ex.: `Despesas -> Operacionais -> Aluguel`).'
        IDTypeAccountPaybleFather:
          type: integer
          format: int32
          nullable: true
          description: Identificador do plano pai. `null` quando o plano é de topo (raiz).
        Status:
          type: integer
          enum:
            - 1
          description: Situação do plano. Sempre `1` (apenas ativos são listados).
        IDTypeCategoryAccountPayble:
          type: integer
          nullable: true
          description: Categoria do plano. Filhos herdam do pai.
        TypeCategoryAccountPaybleDescription:
          type: string
          nullable: true
          description: >-
            Descrição amigável da categoria do plano (`TypeAccountPaybleCategory`). `null` quando o plano não tem
            categoria associada.
        ExternalCode:
          type: string
          nullable: true
          description: Código de referência externo, usado para amarrar o plano a um sistema terceiro (ERP, integração contábil).
        InternalCode:
          type: string
          nullable: true
          description: Código de referência interno completo do plano.
        InternalCodeShort:
          type: string
          nullable: true
          description: Forma abreviada do código de referência interno.
        DefaultOrder:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: >-
            Quando `1`, este é o plano padrão usado em pedidos de venda (contas a receber). Apenas um plano por empresa
            pode ter `1`.
        DefaultPurchase:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: >-
            Quando `1`, este é o plano padrão usado em pedidos de compra (contas a pagar). Apenas um plano por empresa
            pode ter `1`.
    TypeAccountCreate:
      type: object
      description: >-
        Corpo do `POST /type/account/type` e `PUT /type/account/type/{idtypeaccount}`. Quando
        `IDTypeAccountPaybleFather` é informado, a `IDTypeCategoryAccountPayble` enviada é **descartada** (filho herda
        do pai). Marcar `DefaultOrder=1` ou `DefaultPurchase=1` desmarca o plano anteriormente marcado como padrão da
        empresa.
      required:
        - TypeAccountPaybleDescription
      properties:
        TypeAccountPaybleDescription:
          type: string
          description: Descrição do plano. Não pode ser igual à descrição do plano pai.
        IDTypeAccountPaybleFather:
          type: integer
          format: int32
          nullable: true
          description: Identificador do plano pai (omita para criar um plano raiz).
        IDTypeCategoryAccountPayble:
          type: integer
          nullable: true
          description: >-
            Categoria do plano (ver `GET /type/account/type/category`). Ignorado quando `IDTypeAccountPaybleFather` é
            informado.
        IDTypeAccount:
          type: integer
          enum:
            - 0
            - 1
          default: 1
          description: 'Tipo do lançamento: `0` entrada (a receber), `1` saída (a pagar). Default `1`.'
        ExternalCode:
          type: string
          nullable: true
          description: Código de referência externo. Único entre planos ativos da empresa.
        InternalCode:
          type: string
          nullable: true
          description: Código de referência interno. Único entre planos ativos da empresa.
        InternalCodeShort:
          type: string
          nullable: true
          description: Versão reduzida do código interno.
        DefaultOrder:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para marcar este plano como padrão para pedidos da empresa.'
        DefaultPurchase:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para marcar este plano como padrão para compras da empresa.'
    TypeAccountCategoryListItem:
      type: object
      description: Item de `GET /type/account/type/category`.
      properties:
        IDTypeCategoryAccountPayble:
          type: string
          description: Identificador da categoria (devolvido como string).
        TypeCategoryAccountPaybleDescription:
          type: string
          description: Descrição da categoria.
    SupplierListItem:
      type: object
      description: >-
        Item da resposta de `GET /supplier`. Traz os campos do cadastro (`Suppliers.*`) e algumas descrições resolvidas.
        Para o detalhe completo com `Contacts`, `SuppliersCostCenter` e demais relacionamentos, use `GET
        /supplier/{idsupplier}`.
      properties:
        IDSupplier:
          type: integer
          format: int32
          description: Identificador interno do fornecedor.
        SupplierNameCorporateName:
          type: string
          description: Nome ou razão social.
        SupplierTradeName:
          type: string
          nullable: true
          description: Nome fantasia.
        SupplierCpfCnpj:
          type: string
          nullable: true
          description: CPF (11 dígitos) ou CNPJ (14 dígitos), somente números.
        SupplierType:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 7
            - 8
            - 9
          description: >-
            Tipo do fornecedor: `1` Produto, `2` Transportadora, `3` Pessoal, `4` Serviço, `5` Insumo, `6` Governo, `7`
            Transportadora p/ Devoluções, `8` Operador logístico, `9` Outros.
        SupplierEmail:
          type: string
          nullable: true
          description: E-mail do fornecedor.
        SupplierTelephone:
          type: string
          nullable: true
          description: Telefone do fornecedor (somente números).
        SupplierLogoUrl:
          type: string
          nullable: true
          description: >-
            Para transportadoras, quando o fornecedor não tem logotipo próprio, é preenchido com o logotipo do tipo de
            transportadora.
        IDSupplierCategory:
          type: integer
          format: int32
          description: Identificador da categoria do fornecedor.
        CategoryDescription:
          type: string
          nullable: true
          description: Nome da categoria do fornecedor.
        IDTypeSupplier:
          type: integer
          format: int32
          nullable: true
          description: Identificador do tipo de fornecedor (vinculado à categoria).
        ShippingPostalCode:
          type: string
          nullable: true
          description: CEP do endereço.
        ShippingStreet:
          type: string
          nullable: true
          description: Logradouro do endereço.
        ShippingNumber:
          type: string
          nullable: true
          description: Número do endereço.
        ShippingComplement:
          type: string
          nullable: true
          description: Complemento do endereço.
        ShippingNeighborhood:
          type: string
          nullable: true
          description: Bairro.
        ShippingCity:
          type: string
          nullable: true
          description: Cidade.
        ShippingState:
          type: string
          nullable: true
          description: Sigla da UF.
        BankCode:
          type: string
          nullable: true
          description: Código Febraban do banco.
        BankAgency:
          type: string
          nullable: true
          description: Agência bancária.
        BankCheckingAccount:
          type: string
          nullable: true
          description: Número da conta bancária.
        BankCheckingAccountType:
          type: integer
          nullable: true
          description: 'Tipo da conta bancária (ex.: corrente, poupança).'
        PixKey:
          type: string
          nullable: true
          description: Chave Pix do fornecedor para repasse/pagamento.
        IDTypeAccountPayableReceivable:
          type: integer
          format: int32
          nullable: true
          description: Plano de contas padrão para títulos gerados deste fornecedor.
        TypeAccountPaybleDescription:
          type: string
          nullable: true
          description: Nome do plano de contas padrão para títulos a pagar deste fornecedor.
        IDCarrierType:
          type: integer
          format: int32
          nullable: true
          description: Tipo de transportadora (apenas transportadoras).
        TypeCarrier:
          type: string
          nullable: true
          description: Nome do tipo de transportadora (apenas transportadoras).
        CarrierLogoUrl:
          type: string
          nullable: true
          description: URL do logotipo do tipo de transportadora (apenas transportadoras).
        IDCarrierGateway:
          type: integer
          format: int32
          nullable: true
          description: Identificador do gateway de transporte (apenas transportadoras).
        CarrierGateway:
          type: string
          nullable: true
          description: Nome do gateway de transporte (apenas transportadoras).
        IDCarrierModal:
          type: integer
          format: int32
          nullable: true
          description: Identificador da modalidade de transporte (apenas transportadoras).
        CarrierModal:
          type: string
          nullable: true
          description: Nome da modalidade de transporte (apenas transportadoras).
        CarrierAuction:
          type: integer
          nullable: true
          description: Quando 1, a transportadora participa do leilão de frete.
        CarrierRateUploadStatusDescription:
          type: string
          nullable: true
          description: 'Status do último upload de tabela de frete: `Sucesso`, `Erro`, `Processando` ou nulo.'
        AccountName:
          type: string
          description: Subdomínio da empresa dona do cadastro.
        SupplierStatus:
          type: integer
          enum:
            - 1
          description: Sempre 1 (apenas ativos são listados).
    SupplierCreate:
      type: object
      description: >-
        Corpo do `POST /supplier`. Quando `SupplierCpfCnpj` for um CNPJ válido, os campos de endereço, contato, razão
        social, nome fantasia, inscrição estadual e data de nascimento (início de atividade) são **sobrescritos** com os
        dados da Receita Federal — só são lidos do corpo quando a consulta a `publica.cnpj.ws` falha.
      required:
        - IDSupplierCategory
        - SupplierNameCorporateName
      properties:
        IDSupplierCategory:
          type: integer
          format: int32
          description: Categoria do fornecedor. Precisa pertencer à empresa autenticada.
        SupplierNameCorporateName:
          type: string
          description: Nome ou razão social. Para CNPJ, é sobrescrito com a razão social da Receita.
        SupplierCpfCnpj:
          type: string
          description: CPF (11 dígitos) ou CNPJ (14 dígitos). Aceita máscara — o sistema mantém apenas os dígitos.
        SupplierTradeName:
          type: string
          nullable: true
          description: Nome fantasia (sobrescrito para CNPJ).
        SupplierStateInscription:
          type: string
          nullable: true
          description: Inscrição estadual (sobrescrita para CNPJ).
        SupplierCityInscription:
          type: string
          nullable: true
          description: Inscrição municipal.
        SupplierIdentityNumber:
          type: string
          nullable: true
          description: Documento de identidade (pessoa física).
        SupplierBirthDate:
          type: string
          format: date
          nullable: true
          description: Data de nascimento (PF) ou início de atividade (PJ — sobrescrito da Receita).
        IDSupplierCivilStatus:
          type: integer
          nullable: true
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
          description: >-
            Estado civil do fornecedor pessoa física. Valores: 1=Solteiro(a), 2=Casado(a), 3=Divorciado(a), 4=Viúvo(a),
            5=União Estável, 6=Outros.
        SupplierTelephone:
          type: string
          nullable: true
          description: Telefone (sobrescrito para CNPJ).
        SupplierEmail:
          type: string
          nullable: true
          description: E-mail (sobrescrito para CNPJ).
        SupplierPIS:
          type: string
          nullable: true
          description: PIS do fornecedor pessoa física.
        ShippingPostalCode:
          type: string
          nullable: true
          description: CEP (sobrescrito para CNPJ).
        ShippingStreet:
          type: string
          nullable: true
          description: Logradouro do endereço (sobrescrito para CNPJ a partir da Receita).
        ShippingNumber:
          type: string
          nullable: true
          description: Número do endereço (sobrescrito para CNPJ a partir da Receita).
        ShippingComplement:
          type: string
          nullable: true
          description: Complemento do endereço (sobrescrito para CNPJ a partir da Receita).
        ShippingNeighborhood:
          type: string
          nullable: true
          description: Bairro (sobrescrito para CNPJ a partir da Receita).
        ShippingCity:
          type: string
          nullable: true
          description: Cidade (sobrescrita para CNPJ a partir da Receita).
        ShippingState:
          type: string
          nullable: true
          description: Sigla da UF.
        BankCode:
          type: string
          nullable: true
          description: Código Febraban do banco.
        BankAgency:
          type: string
          nullable: true
          description: Agência bancária.
        BankCheckingAccount:
          type: string
          nullable: true
          description: Número da conta bancária.
        BankCheckingAccountType:
          type: integer
          nullable: true
          description: 'Tipo da conta bancária (ex.: corrente, poupança).'
        PixKey:
          type: string
          nullable: true
          description: Chave Pix do fornecedor para repasse/pagamento.
        Comments:
          type: string
          nullable: true
          description: Observações livres sobre o fornecedor.
        SupplierProductLeadTimeDays:
          type: integer
          nullable: true
          description: Lead time padrão de entrega de produtos, em dias.
        SupplierProductReliability:
          type: integer
          nullable: true
          description: Avaliação de confiabilidade do fornecedor.
        CarrierAuction:
          type: integer
          nullable: true
          description: 'Apenas para transportadoras: 1 para participar do leilão de frete.'
        CarrierAuctionPenalty:
          type: integer
          nullable: true
          description: >-
            Apenas para transportadoras. Percentual de acréscimo aplicado ao preço da cotação durante o leilão de frete
            (ex.: 15 significa +15% sobre o valor de tabela).
        IDCarrierGateway:
          type: integer
          nullable: true
          description: Apenas para transportadoras. Identificador do gateway de transporte usado para integrar com a operadora.
        IDCarrierType:
          type: integer
          nullable: true
          description: >-
            Apenas para transportadoras. Identificador do tipo de transportadora (Correios, JadLog, Total Express,
            etc.), conforme a tabela de tipos de transportadora.
        CarrierAdditionalBusinessDays:
          type: integer
          nullable: true
          description: Apenas para transportadoras. Dias úteis adicionais somados ao prazo de entrega da transportadora.
        CarrierShippingCutTime:
          type: string
          nullable: true
          description: Hora-limite de corte para coleta (formato `HH:mm:ss`).
        CarrierICMSIncluded:
          type: integer
          nullable: true
          description: >-
            Apenas para transportadoras. Indica se os valores da tabela de frete já incluem ICMS. 1=incluso (o imposto
            não é adicionado), 0=não incluso (o imposto é somado aos valores da tabela).
        CarrierCubageKmM:
          type: number
          nullable: true
          description: Apenas para transportadoras. Fator de cubagem em KG/m³ usado para converter volume em peso cubado.
        CarrierCubageFreeWeight:
          type: number
          nullable: true
          description: Apenas para transportadoras. Peso mínimo (em KG) abaixo do qual a cubagem não é aplicada.
        PrintDanfeA4:
          type: integer
          nullable: true
          description: Imprime a Nota Fiscal em A4 de forma automática. 1=imprime, 0=não imprime.
        LabelAndDanfeSamePage:
          type: integer
          nullable: true
          description: >-
            Inclui os dados fiscais da nota (número, chave de acesso e código de barras) na parte inferior da etiqueta
            de transporte, sem imprimir a DANFE em folha avulsa. 1=inclui na etiqueta, 0=não inclui. Só tem efeito
            quando a impressão da DANFE simplificada (`PrintDanfe`) está ativa.
        CarrierCollectionListEmail:
          type: string
          nullable: true
          description: E-mail destinatário para o envio do romaneio (coleta).
    SupplierUpdate:
      type: object
      description: Corpo do `PUT /supplier/{idsupplier}`. Atualização parcial — apenas campos enviados são alterados.
      required: []
      properties:
        IDSupplierCategory:
          type: integer
          format: int32
          description: Categoria do fornecedor. Precisa pertencer à empresa autenticada.
        SupplierNameCorporateName:
          type: string
          description: Nome ou razão social.
        SupplierTradeName:
          type: string
          nullable: true
          description: Nome fantasia.
        SupplierCpfCnpj:
          type: string
          description: Quando muda, dispara a checagem de duplicidade se `BlockDuplicateSupplier=1`.
        SupplierStateInscription:
          type: string
          nullable: true
          description: Inscrição estadual. Aceita o literal `ISENTO`; caso contrário o banco normaliza mantendo apenas os dígitos.
        SupplierCityInscription:
          type: string
          nullable: true
          description: Inscrição municipal.
        SupplierIdentityNumber:
          type: string
          nullable: true
          description: Documento de identidade (pessoa física).
        SupplierBirthDate:
          type: string
          format: date
          nullable: true
          description: Data de nascimento (PF) ou data de abertura (PJ). Envie no formato `YYYY-MM-DD`.
        SupplierTelephone:
          type: string
          nullable: true
          description: Telefone. O banco normaliza mantendo apenas os dígitos.
        SupplierEmail:
          type: string
          nullable: true
          description: E-mail do fornecedor.
        SupplierPIS:
          type: string
          nullable: true
          description: PIS do fornecedor pessoa física.
        ShippingPostalCode:
          type: string
          nullable: true
          description: CEP. O banco normaliza mantendo apenas os dígitos.
        ShippingStreet:
          type: string
          nullable: true
          description: Logradouro do endereço.
        ShippingNumber:
          type: string
          nullable: true
          description: Número do endereço.
        ShippingComplement:
          type: string
          nullable: true
          description: Complemento do endereço.
        ShippingNeighborhood:
          type: string
          nullable: true
          description: Bairro.
        ShippingCity:
          type: string
          nullable: true
          description: Cidade.
        ShippingState:
          type: string
          nullable: true
          description: Sigla da UF.
        BankCode:
          type: string
          nullable: true
          description: Código Febraban do banco.
        BankAgency:
          type: string
          nullable: true
          description: Agência bancária.
        BankCheckingAccount:
          type: string
          nullable: true
          description: Número da conta bancária.
        BankCheckingAccountType:
          type: integer
          nullable: true
          description: 'Tipo da conta bancária (ex.: corrente, poupança).'
        PixKey:
          type: string
          nullable: true
          description: Chave Pix do fornecedor para repasse/pagamento.
        Comments:
          type: string
          nullable: true
          description: Observações livres sobre o fornecedor.
        DefaultPurchase:
          type: integer
          nullable: true
          description: 1 marca o fornecedor como padrão para novas compras.
        PrintDanfe:
          type: integer
          nullable: true
          description: >-
            Imprime a DANFE simplificada (ou declaração de conteúdo) ao finalizar o packing. 1=imprime, 0=imprime só a
            etiqueta de transporte.
        PrintDanfeA4:
          type: integer
          nullable: true
          description: Imprime a Nota Fiscal em A4 de forma automática. 1=imprime, 0=não imprime.
        LabelAndDanfeSamePage:
          type: integer
          nullable: true
          description: >-
            Inclui os dados fiscais da nota (número, chave de acesso e código de barras) na parte inferior da etiqueta
            de transporte, sem imprimir a DANFE em folha avulsa. 1=inclui na etiqueta, 0=não inclui. Só tem efeito
            quando a impressão da DANFE simplificada (`PrintDanfe`) está ativa.
        ManualLabel:
          type: integer
          nullable: true
          description: Quando 1, permite anexar manualmente o arquivo de etiqueta na ficha do pedido.
        IDCompanyIntegration:
          type: integer
          nullable: true
          description: Integração da empresa associada.
        IDCompanyLabel:
          type: integer
          nullable: true
          description: >-
            Template de etiqueta. Precisa pertencer à empresa ou à empresa-padrão (54) e ser do tipo etiqueta de
            transportadora.
        IDTypeAccountPayableReceivable:
          type: integer
          nullable: true
          description: Plano de contas padrão para títulos gerados deste fornecedor.
        SupplierProductLeadTimeDays:
          type: integer
          nullable: true
          description: Lead time padrão de entrega de produtos, em dias.
        SupplierProductReliability:
          type: integer
          nullable: true
          description: 'Avaliação de confiabilidade do fornecedor. Valores: 1=Alto, 2=Médio, 3=Baixo.'
        CarrierAuction:
          type: integer
          nullable: true
          description: Quando passa para 1 sem `CarrierQuotationExternalId` anterior, o sistema atribui o próximo id sequencial.
        CarrierAuctionPenalty:
          type: integer
          nullable: true
          description: >-
            Apenas para transportadoras. Percentual de acréscimo aplicado ao preço da cotação durante o leilão de frete
            (ex.: 15 significa +15% sobre o valor de tabela).
        IDCarrierGateway:
          type: integer
          nullable: true
          description: Apenas para transportadoras. Identificador do gateway de transporte usado para integrar com a operadora.
        IDCarrierType:
          type: integer
          nullable: true
          description: >-
            Apenas para transportadoras. Identificador do tipo de transportadora (Correios, JadLog, Total Express,
            etc.), conforme a tabela de tipos de transportadora.
        IDCarrierModal:
          type: integer
          nullable: true
          description: Apenas para transportadoras. Modalidade de transporte (rodoviário, aéreo, etc.).
        CarrierShippingIdRule:
          type: integer
          nullable: true
          description: Regra de roteamento usada quando esta transportadora vence o leilão de frete.
        CarrierAdditionalBusinessDays:
          type: integer
          nullable: true
          description: Apenas para transportadoras. Dias úteis adicionais somados ao prazo de entrega da transportadora.
        CarrierShippingCutTime:
          type: string
          nullable: true
          description: 'Apenas para transportadoras. Horário-limite de corte para coleta no dia, no formato `HH:mm` (ex.: `17:00`).'
        CarrierICMSIncluded:
          type: integer
          nullable: true
          description: >-
            Apenas para transportadoras. Indica se os valores da tabela de frete já incluem ICMS. 1=incluso (o imposto
            não é adicionado), 0=não incluso (o imposto é somado aos valores da tabela).
        CarrierCubageKmM:
          type: number
          nullable: true
          description: Apenas para transportadoras. Fator de cubagem em KG/m³ usado para converter volume em peso cubado.
        CarrierCubageFreeWeight:
          type: number
          nullable: true
          description: Apenas para transportadoras. Peso mínimo (em KG) abaixo do qual a cubagem não é aplicada.
        CarrierPriceRounding:
          type: number
          nullable: true
          description: >-
            Apenas para transportadoras. Centavos de arredondamento do preço do frete cotado. Valor entre 0,00 e 0,99; o
            arredondamento é feito por aproximação para o valor desejado.
        CarrierOrdersLimitPerCollection:
          type: integer
          nullable: true
          description: Limite de pedidos por romaneio (coleta) desta transportadora.
        CarrierCollectionListEmail:
          type: string
          nullable: true
          description: >-
            Apenas para transportadoras. E-mails (separados por vírgula) que recebem o romaneio digital assim que ele é
            assinado.
        IgnoreCollectionList:
          type: integer
          nullable: true
          description: Quando 1, a transportadora é ignorada na geração automática de romaneio.
        ContentDeclarationStates:
          type: array
          items:
            type: string
          nullable: true
          description: >-
            Lista de UFs em que a transportadora exige declaração de conteúdo. O sistema grava como string separada por
            vírgula.
    SupplierContactCreate:
      type: object
      description: Corpo do `POST /supplier/{idsupplier}/contact`. Cria um contato (pessoa física) vinculado ao fornecedor.
      properties:
        ContactName:
          type: string
          description: Nome do contato.
        ContactEmail:
          type: string
          nullable: true
          description: E-mail do contato.
        ContactTelephone:
          type: string
          nullable: true
          description: Telefone do contato.
        ContactResponsability:
          type: string
          nullable: true
          description: Cargo ou responsabilidade.
    SupplierContactUpdate:
      type: object
      description: >-
        Corpo do `PUT /supplier/{idsupplier}/contact/{idsupplierscontact}`. Atualização parcial — apenas campos enviados
        são alterados.
      properties:
        ContactName:
          type: string
          description: Nome do contato.
        ContactEmail:
          type: string
          nullable: true
          description: E-mail do contato.
        ContactTelephone:
          type: string
          nullable: true
          description: Telefone do contato.
        ContactResponsability:
          type: string
          nullable: true
          description: Cargo ou responsabilidade.
    SupplierCostCenterRatio:
      type: object
      description: >-
        Item do array de rateio em `POST /supplier/{idsupplier}/cost-center`. A soma de `ValueRatio` de todos os itens
        precisa fechar em 1.
      required:
        - IDTypeCostCenter
        - ValueRatio
      properties:
        IDTypeCostCenter:
          type: integer
          format: int32
          description: Centro de custo. Precisa existir na empresa e estar ativo.
        ValueRatio:
          type: number
          format: float
          description: Fração do total alocada a este centro (0..1). A soma de todos os itens precisa fechar em 1.
    TypeDocumentListItem:
      type: object
      description: >-
        Item de `GET /type/account/document`. Tipo de documento da empresa, com flags indicando se é padrão para pedidos
        (vendas) e/ou para compras.
      properties:
        AccountName:
          type: string
          description: Subdomínio da empresa dona do tipo de documento.
        IDTypeDocument:
          type: string
          description: Identificador do tipo de documento. **Vem como string** na resposta (preserva zeros à esquerda).
        TypeDocument:
          type: string
          maxLength: 45
          description: Descrição do tipo de documento.
        DefaultOrder:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: >-
            Marca este tipo como padrão para pedidos de venda. Usado para sinalizar visualmente na lista de seleção em
            contas a receber e pedidos.
        DefaultPurchase:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: >-
            Marca este tipo como padrão para compras. Usado para sinalizar visualmente na lista de seleção em contas a
            pagar, pedido de compra e recebimento.
    TypeDocumentCreate:
      type: object
      description: >-
        Corpo do `POST /type/account/document`. Apenas `TypeDocument` é exigido — os dois flags assumem `null` quando
        ausentes.
      required:
        - TypeDocument
      properties:
        TypeDocument:
          type: string
          maxLength: 45
          description: Descrição do tipo de documento.
        DefaultOrder:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para marcar como padrão para pedidos de venda; `0` ou ausente para não marcar.'
        DefaultPurchase:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para marcar como padrão para compras; `0` ou ausente para não marcar.'
    TypeDocumentUpdate:
      type: object
      description: >-
        Corpo do `PUT /type/account/document/{idtypedocument}`. Os três campos são sobrescritos a cada chamada (não é
        atualização parcial).
      required:
        - TypeDocument
      properties:
        TypeDocument:
          type: string
          maxLength: 45
          description: Descrição do tipo de documento.
        DefaultOrder:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para marcar como padrão para pedidos de venda; `0` ou nulo para desmarcar.'
        DefaultPurchase:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para marcar como padrão para compras; `0` ou nulo para desmarcar.'
    TypePaymentListItem:
      type: object
      description: >-
        Item da resposta de `GET /type/order/payment`. Cada tipo de pagamento pertence a uma categoria fixa (cartão de
        crédito, débito, Pix, boleto, dinheiro, vale-alimentação, vale-refeição, etc.). Categorias `1` (Cartão de
        Crédito) e `6` (Cartão de Débito) sempre vêm acompanhadas de uma bandeira (`NfTBand`).
      properties:
        IDTypePayment:
          type: string
          description: Identificador do tipo de pagamento, devolvido como string.
        TypePaymentDescription:
          type: string
          description: 'Descrição livre escolhida pela empresa (ex.: ''PIX recebimento'', ''Cartão Cielo Crédito'').'
        Category:
          type: integer
          description: >-
            Categoria do tipo de pagamento (`TypePaymentCategory`). Valores comuns: 1=Cartão de Crédito, 2=Boleto
            Bancário, 3=MarketPlace E-Commerce, 4=Transferência Bancária, 5=PIX, 6=Cartão de Débito, 7=Dinheiro,
            12=Outros, 13=Cheque, 14=Crédito loja, 15-18=Vales.
        TypePaymentCategory:
          type: string
          description: Descrição da categoria (`Cartão de Crédito`, `PIX`, `Dinheiro`, etc.).
        TypePaymentCategoryLogoUrl:
          type: string
          nullable: true
          description: URL do ícone da categoria.
        NfTBand:
          type: string
          nullable: true
          description: 'Bandeira (`NfTBand`) quando a categoria é cartão. Exemplos: 01=Visa, 02=Mastercard, 03=Amex, 06=Elo.'
        NfTBandDescription:
          type: string
          nullable: true
          description: Descrição da bandeira.
        NfTBandLogoUrl:
          type: string
          nullable: true
          description: URL do logo da bandeira.
        DaysDue:
          type: integer
          nullable: true
          description: Prazo padrão de vencimento (em dias) usado na geração de contas a pagar/receber a partir deste tipo.
        DefaultOrder:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: Quando 1, este tipo é o padrão sugerido em novas vendas.
        DefaultPurchase:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: Quando 1, este tipo é o padrão sugerido em novas compras.
        EnableFrenteCaixa:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: Quando 1, o tipo aparece como opção na tela do PDV (frente de caixa).
        IncludeComission:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: Quando 1, vendas pagas com este tipo entram no relatório de comissão do vendedor.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data/hora do cadastro.
        AccountName:
          type: string
          description: Subdomínio da empresa dona do cadastro.
    TypePaymentCreate:
      type: object
      description: >-
        Corpo de `POST /type/order/payment` e `PUT /type/order/payment/{idtypepayment}` (atualização total). Quando
        `Category` for `1` ou `6`, `NfTBand` é obrigatório.
      required:
        - TypePaymentDescription
        - Category
      properties:
        TypePaymentDescription:
          type: string
          description: 'Descrição livre (ex.: ''PIX recebimento'', ''Cartão Cielo Crédito'').'
        Category:
          type: integer
          description: >-
            Categoria do tipo (`IDTypePaymentCategory`). Quando `1` (Cartão de Crédito) ou `6` (Cartão de Débito),
            `NfTBand` passa a ser obrigatório.
        NfTBand:
          type: string
          nullable: true
          description: Bandeira do cartão. Obrigatório para categorias 1 e 6.
        DaysDue:
          type: integer
          nullable: true
          description: Prazo padrão de vencimento em dias.
        DefaultOrder:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: Marca como padrão para novas vendas.
        DefaultPurchase:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: Marca como padrão para novas compras.
        EnableFrenteCaixa:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: Habilita uso no PDV.
        IncludeComission:
          type: integer
          enum:
            - 0
            - 1
          description: Inclui vendas no relatório de comissão. Default `1` quando omitido.
    TypePaymentRateItem:
      type: object
      description: >-
        Taxa adquirente vinculada a um tipo de pagamento. Cada item combina uma integração adquirente, um método de
        pagamento da integração (`TypePayment`), uma faixa de parcelas e uma vigência, com a taxa cobrada nesse cenário
        (MDR + AR ou taxa fixa).
      properties:
        IDTypePaymentRate:
          type: integer
          format: int32
          description: Identificador da taxa.
        IDTypePayment:
          type: integer
          format: int32
          description: Tipo de pagamento ao qual a taxa pertence.
        IDCompanyIntegration:
          type: integer
          format: int32
          description: Integração adquirente (Cielo, Rede, MercadoPago, etc.).
        CompanyIntegrationName:
          type: string
          description: Nome amigável da integração adquirente configurado pela empresa.
        IntegrationName:
          type: string
          description: Nome do tipo de integração (categoria do adquirente).
        IntegrationLogoUrl:
          type: string
          nullable: true
          description: URL do logotipo da integração adquirente (quando cadastrado).
        IDTypeCompanyIntegration:
          type: integer
          format: int32
          description: Identificador do tipo de integração (categoria do adquirente — gateway, banco, ERP, etc.).
        IDTypePaymentFrom:
          type: integer
          format: int32
          description: Método de pagamento na nomenclatura do adquirente (`IDTypePaymentFrom`).
        TypePayment:
          type: string
          description: Descrição do método de pagamento do adquirente (bandeira + modalidade).
        MinInstallment:
          type: integer
          description: Quantidade mínima de parcelas para a taxa valer.
        MaxInstallment:
          type: integer
          description: Quantidade máxima de parcelas para a taxa valer.
        DaysDue:
          type: integer
          nullable: true
          description: Prazo de liberação do adquirente, em dias.
        MerchantDiscountRate:
          type: number
          nullable: true
          description: Taxa MDR (Merchant Discount Rate) como fração (0.0299 = 2,99%).
        AnticipationRate:
          type: number
          nullable: true
          description: Taxa de antecipação como fração.
        FixedRate:
          type: number
          nullable: true
          description: Taxa fixa em R$ (alternativa a MDR + AR — quando `> 0`, MDR e AR ficam ignorados).
        DateFrom:
          type: string
          format: date
          description: Início da vigência.
        DateTo:
          type: string
          format: date
          description: Fim da vigência.
    TypePaymentRateCreate:
      type: object
      description: >-
        Corpo de `POST /type/order/payment/{idtypepayment}/rate`. Cria uma combinação integração + método + faixa de
        parcelas + vigência com a taxa correspondente. A taxa pode ser **MDR + AR** (deixe `FixedRate=0`) ou **fixa**
        (deixe `MerchantDiscountRate=0` e `AnticipationRate=0`). Taxas negativas são rejeitadas.
      required:
        - IDCompanyIntegration
        - IDTypePaymentFrom
        - MinInstallment
        - MaxInstallment
        - DateFrom
        - DateTo
      properties:
        IDCompanyIntegration:
          type: integer
          format: int32
          description: Integração adquirente.
        IDTypePaymentFrom:
          type: integer
          format: int32
          description: Método de pagamento do adquirente (bandeira + modalidade).
        MinInstallment:
          type: integer
          description: Quantidade mínima de parcelas. Tem que ser menor ou igual a `MaxInstallment`.
        MaxInstallment:
          type: integer
          description: Quantidade máxima de parcelas.
        DaysDue:
          type: integer
          nullable: true
          description: Prazo de liberação do adquirente em dias.
        MerchantDiscountRate:
          type: number
          description: Taxa MDR como fração (0.0299 = 2,99%). Não pode ser negativo.
        AnticipationRate:
          type: number
          description: Taxa de antecipação como fração. Não pode ser negativo.
        FixedRate:
          type: number
          description: Taxa fixa em R$. Não pode ser negativo.
        DateFrom:
          type: string
          format: date
          description: Início da vigência.
        DateTo:
          type: string
          format: date
          description: Fim da vigência. Não pode sobrepor com outras taxas da mesma integração e faixa de parcelas.
    TypePaymentRateUpdate:
      type: object
      description: >-
        Corpo de `PUT /type/order/payment/{idtypepayment}/rate/{idtypepaymentrate}`. Atualização parcial — apenas campos
        enviados são alterados. Mesmas regras de sobreposição e taxas negativas do `POST`.
      properties:
        IDCompanyIntegration:
          type: integer
          format: int32
          description: Integração adquirente (Cielo, Rede, MercadoPago, etc.) à qual a taxa se aplica.
        IDTypePaymentFrom:
          type: integer
          format: int32
          description: Método de pagamento na nomenclatura do adquirente (`IDTypePaymentFrom` — combinação bandeira + modalidade).
        MinInstallment:
          type: integer
          description: Quantidade mínima de parcelas para a taxa valer. Tem que ser ≤ `MaxInstallment`.
        MaxInstallment:
          type: integer
          description: Quantidade máxima de parcelas para a taxa valer.
        DaysDue:
          type: integer
          nullable: true
          description: Prazo de liberação do adquirente, em dias.
        MerchantDiscountRate:
          type: number
          description: Taxa MDR (Merchant Discount Rate) como fração decimal (`0.0299` = 2,99%). Não pode ser negativa.
        AnticipationRate:
          type: number
          description: Taxa de antecipação como fração decimal. Não pode ser negativa.
        FixedRate:
          type: number
          description: Taxa fixa em R$ — alternativa a MDR + AR. Não pode ser negativa.
        DateFrom:
          type: string
          format: date
          description: Início da vigência da taxa (formato `YYYY-MM-DD`).
        DateTo:
          type: string
          format: date
          description: >-
            Fim da vigência da taxa (formato `YYYY-MM-DD`). Não pode sobrepor com outras taxas da mesma integração e
            faixa de parcelas.
    TypeCostCenterListItem:
      type: object
      description: >-
        Item da resposta de `GET /type/account/cost-center`. Centros de custo são usados para ratear o valor de uma
        conta a pagar/receber entre departamentos, projetos ou filiais.
      properties:
        IDTypeCostCenter:
          type: integer
          format: int32
          description: Identificador do centro de custo.
        TypeCostCenter:
          type: string
          description: 'Descrição do centro de custo (ex.: ''Marketing'', ''TI - Infraestrutura'').'
        ExternalCode:
          type: string
          nullable: true
          description: Código externo opcional, usado para casar com sistemas terceiros (ERP, integração contábil).
        IDCompany:
          type: integer
          format: int32
          description: Identificador da empresa dona do centro de custo.
        AccountName:
          type: string
          description: Subdomínio da empresa dona do cadastro.
        Status:
          type: integer
          enum:
            - 1
          description: Sempre `1` (apenas ativos são listados).
        RecordTimestamp:
          type: string
          format: date-time
          description: Data/hora do cadastro.
    TypeCostCenterCreate:
      type: object
      description: >-
        Corpo de `POST /type/account/cost-center` e `PUT /type/account/cost-center/{idtypecostcenter}`. Quando
        `ExternalCode` for informado, precisa ser único dentro da empresa entre os centros ativos.
      required:
        - TypeCostCenter
      properties:
        TypeCostCenter:
          type: string
          description: Descrição do centro de custo.
        ExternalCode:
          type: string
          nullable: true
          description: Código externo opcional. Quando informado, precisa ser único na empresa.
    TypeOrderListItem:
      type: object
      description: >-
        Item de `GET /type/order/type`. Inclui descrições de política comercial, faturador, armazém padrão e de
        devolução, tipo de retorno simbólico e devolução, plano de contas, centro de custo e finalidade NFe.
      properties:
        IDTypeOrder:
          type: string
          description: Identificador do tipo de pedido (devolvido como string).
        AccountName:
          type: string
          description: Subdomínio da empresa dona do tipo de pedido.
        IDCompany:
          type: integer
          format: int32
          description: Identificador da empresa dona do tipo de pedido.
        TypeOrder:
          type: string
          description: Descrição do tipo de pedido.
        OrderPrefix:
          type: string
          description: Prefixo (sigla) dos pedidos deste tipo.
        IDCompanySalesPolicy:
          type: integer
          format: int32
          description: Política comercial vinculada.
        CompanySalesPolicy:
          type: string
          description: Descrição da política comercial.
        Default:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` quando este é o tipo padrão da empresa. Apenas um pode estar marcado.'
        Resend:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` quando este é o tipo padrão para reenvio. Apenas um por empresa.'
        Return:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` quando este é o tipo padrão para devolução. Apenas um por empresa.'
        SymbolicReturn:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` quando este é o tipo padrão para retorno simbólico. Apenas um por empresa.'
        IncludeValueDashboard:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` quando o valor dos pedidos deste tipo entra nos indicadores do dashboard.'
        CreateBankSlipAfterInvoice:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para gerar boleto automaticamente após a emissão da nota fiscal.'
        RecalculateAccountsDueDateAfterInvoice:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para recalcular a data de vencimento das contas a receber a partir da emissão da nota fiscal.'
        BlockInvoiceToCompanySameDocument:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para bloquear NF quando o CNPJ do cliente é o mesmo do faturador.'
        BalanceChange:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` (padrão) movimenta o estoque; `0` não movimenta.'
        IssueNFCe:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para emitir NFCe (modelo 65) em vez de NFe.'
        MinimumMarkup:
          type: number
          nullable: true
          description: Markup mínimo exigido para finalizar pedidos. Abaixo só com privilégio.
        InvoiceIntermedCNPJ:
          type: string
          nullable: true
          description: CNPJ que sobrescreve o intermediador da NFe (`infIntermed`).
        BlockSkuZeroValue:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para bloquear finalização do pedido quando há itens com valor de venda zero.'
        TypeOrderNfeindFinal:
          type: integer
          nullable: true
          description: Indicador `indFinal` padrão (`0` Normal, `1` Consumidor final).
        IndFinalDescription:
          type: string
          nullable: true
          description: Descrição amigável do `TypeOrderNfeindFinal`.
        TypeOrderNfeComments:
          type: string
          nullable: true
          description: Texto fixo de comentário da NFe.
        NfeFactorPercent:
          type: number
          description: Fator multiplicador do valor a faturar na NFe de produto e de serviço. Padrão `1.0000`.
        EnableFrenteCaixa:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para exibir no módulo Frente de Caixa (PDV).'
        CarrierQuotation:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` para realizar cotação automática de frete na finalização.'
        ConsumerVoucherDefault:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para gerar vale (crédito) por padrão na devolução.'
        OrderFinishConfirmation:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para pedir confirmação de finalização do pedido ao baixar o último título do contas a receber.'
        IsTransfer:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` quando o tipo é **transferência** entre filiais.'
        ServiceRequest:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` quando o tipo representa **ordem de serviço**.'
        IDCompanyInvoice:
          type: integer
          format: int32
          nullable: true
          description: Faturador (filial) padrão para emissão de NF.
        AccountNameInvoice:
          type: string
          nullable: true
          description: Subdomínio do faturador.
        CompanyNameCorporateNameInvoice:
          type: string
          nullable: true
          description: Razão social do faturador.
        IDStockKeepingUnitWarehouse:
          type: integer
          format: int32
          nullable: true
          description: Armazém padrão para pedidos deste tipo.
        WarehouseName:
          type: string
          nullable: true
          description: Nome do armazém padrão.
        IDStockKeepingUnitDistributionCenter:
          type: integer
          format: int32
          nullable: true
          description: Centro de distribuição vinculado ao armazém padrão.
        IDStockKeepingUnitWarehouseReturn:
          type: integer
          format: int32
          nullable: true
          description: Armazém padrão para devolução.
        WarehouseNameReturn:
          type: string
          nullable: true
          description: Nome do armazém de devolução padrão (`IDStockKeepingUnitWarehouseReturn`).
        MaximumDiscountPerItem:
          type: number
          nullable: true
          description: Percentual máximo de desconto por item (fração decimal entre 0 e 1).
        SafetyStockPercent:
          type: number
          nullable: true
          description: Percentual de estoque de segurança não exibido em pedidos manuais.
        AutomaticCancelOpenOrderAfterHour:
          type: integer
          nullable: true
          description: Horas para cancelamento automático de pedido em aberto.
        IDTypeOrderSymbolicStorageReturn:
          type: integer
          format: int32
          nullable: true
          description: Tipo de pedido usado para gerar NF de retorno simbólico de armazenagem.
        TypeOrderSymbolicStorageReturn:
          type: string
          nullable: true
          description: Descrição amigável do `IDTypeOrderSymbolicStorageReturn`.
        IncludeInboundInvoiceReferenceKey:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para referenciar a chave da NF de entrada na NF de saída.'
        CfopConsiderSymbolicStorageReturn:
          type: string
          nullable: true
          description: CFOPs (separados por vírgula) a considerar como retorno simbólico.
        NFeFinReturn:
          type: integer
          nullable: true
          description: Finalidade da NFe de retorno (`finNFe`).
        FinNfeDescription:
          type: string
          nullable: true
          description: Descrição da finalidade.
        IDTypeOrderDefaultReturn:
          type: integer
          format: int32
          nullable: true
          description: Tipo de pedido usado como devolução padrão a partir deste tipo.
        TypeOrderDefaultReturn:
          type: string
          nullable: true
          description: Descrição amigável do `IDTypeOrderDefaultReturn`.
        TypeOrderOrderPriority:
          type: integer
          nullable: true
          description: Prioridade no WMS (`0` mais alta, `10` mais baixa).
        IDTypeAccountPayableReceivable:
          type: integer
          format: int32
          nullable: true
          description: Plano de contas padrão para contas a receber geradas pelos pedidos.
        TypeAccountPaybleDescription:
          type: string
          nullable: true
          description: Descrição do plano de contas.
        IDTypeCostCenter:
          type: integer
          format: int32
          nullable: true
          description: Centro de custo padrão.
        TypeCostCenter:
          type: string
          nullable: true
          description: Descrição do centro de custo.
        HandlingDays:
          type: integer
          nullable: true
          description: Dias de manuseio considerados no cálculo da data limite de expedição.
        ShippingCutTime:
          type: string
          nullable: true
          description: Horário de corte para expedição (`HH:mm:ss`).
    TypeOrderDetail:
      type: object
      description: >-
        Resposta de `GET /type/order/type/{idordertype}`. Mesmos campos de `TypeOrderListItem` mais a lista de regras
        fiscais `TypeOrderTax[]`.
      allOf:
        - $ref: '#/components/schemas/TypeOrderListItem'
        - type: object
          properties:
            TypeOrderTax:
              type: array
              description: >-
                Regras fiscais aplicáveis a este tipo de pedido — uma entrada por departamento fiscal cadastrado nos
                SKUs da empresa. `IDTax` vem nulo quando ainda não há regra associada.
              items:
                type: object
                properties:
                  IDTaxDepartment:
                    type: integer
                    format: int32
                    description: Identificador do departamento fiscal vinculado ao tipo de pedido.
                  TaxDepartmentDescription:
                    type: string
                    description: Nome do departamento fiscal.
                  IDCompany:
                    type: integer
                    format: int32
                    description: Identificador da empresa dona do tipo de pedido.
                  AccountName:
                    type: string
                    description: Conta (prefixo) da empresa.
                  CompanyNameCorporateName:
                    type: string
                    description: Razão social da empresa.
                  CompanyTradeName:
                    type: string
                    nullable: true
                    description: Nome fantasia da empresa.
                  IDTypeOrderTax:
                    type: integer
                    format: int32
                    nullable: true
                    description: Identificador da regra fiscal padrão do tipo de pedido, quando configurada.
                  IDTax:
                    type: integer
                    format: int32
                    nullable: true
                    description: Regra fiscal aplicada a este par tipo de pedido + departamento.
                  TypeTaxName:
                    type: string
                    nullable: true
                    description: Nome da regra fiscal padrão.
                  RecordTimestamp:
                    type: string
                    format: date-time
                    nullable: true
                    description: Data e hora do cadastro do tipo de pedido.
    TypeOrderCreate:
      type: object
      description: >-
        Corpo de `POST /type/order/type` e `PUT /type/order/type/{idordertype}`. **Apenas um tipo por empresa pode estar
        marcado** como `Default`, `Resend`, `Return` ou `SymbolicReturn` — marcar qualquer um destes em `1` desmarca o
        anterior automaticamente.
      required:
        - TypeOrder
        - OrderPrefix
        - IDCompanySalesPolicy
      properties:
        TypeOrder:
          type: string
          description: Descrição do tipo de pedido.
        OrderPrefix:
          type: string
          description: Prefixo (sigla) usado para identificar os pedidos deste tipo.
        IDCompanySalesPolicy:
          type: integer
          format: int32
          description: Política comercial vinculada (obrigatória).
        Default:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para marcar como tipo padrão da empresa (desmarca o anterior).'
        Resend:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para marcar como padrão de reenvio (desmarca o anterior).'
        Return:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para marcar como padrão de devolução (desmarca o anterior).'
        SymbolicReturn:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para marcar como padrão de retorno simbólico (desmarca o anterior).'
        IncludeValueDashboard:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para incluir o valor dos pedidos no dashboard. Default `0` no POST.'
        CreateBankSlipAfterInvoice:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para gerar boleto automaticamente após a emissão da NFe. Default `0`.'
        RecalculateAccountsDueDateAfterInvoice:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para recalcular o vencimento das contas a receber a partir da emissão da NFe. Default `0`.'
        BlockInvoiceToCompanySameDocument:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para bloquear NFe quando o CNPJ do cliente é o do faturador. Default `0`.'
        BalanceChange:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` (default) movimenta estoque; `0` não.'
        IssueNFCe:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para emitir NFCe. Default `0`.'
        MinimumMarkup:
          type: number
          nullable: true
          description: Markup mínimo exigido.
        InvoiceIntermedCNPJ:
          type: string
          nullable: true
          description: CNPJ a usar como intermediador da NFe.
        BlockSkuZeroValue:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para bloquear item com valor zero. Default `1` no POST.'
        TypeOrderNfeindFinal:
          type: integer
          nullable: true
          description: '`indFinal` padrão (`0` Normal, `1` Consumidor final).'
        TypeOrderNfeComments:
          type: string
          nullable: true
          description: Texto fixo de comentário da NFe.
        EnableFrenteCaixa:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para exibir este tipo no Frente de Caixa.'
        IDCompanyInvoice:
          type: integer
          format: int32
          nullable: true
          description: Faturador (filial). Precisa ser filial da própria empresa.
        IDStockKeepingUnitWarehouse:
          type: integer
          format: int32
          nullable: true
          description: Armazém padrão para pedidos deste tipo. Precisa estar ativo.
        IDStockKeepingUnitWarehouseReturn:
          type: integer
          format: int32
          nullable: true
          description: Armazém padrão para devoluções.
        CarrierQuotation:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para cotar frete automaticamente.'
        MaximumDiscountPerItem:
          type: number
          nullable: true
          description: Percentual máximo de desconto por item.
        SafetyStockPercent:
          type: number
          nullable: true
          description: Percentual de estoque de segurança.
        AutomaticCancelOpenOrderAfterHour:
          type: integer
          nullable: true
          description: Horas para cancelamento automático de pedido em aberto.
        IDTypeOrderSymbolicStorageReturn:
          type: integer
          format: int32
          nullable: true
          description: Tipo de pedido para gerar NF de retorno simbólico.
        IncludeInboundInvoiceReferenceKey:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para referenciar chave da NF de entrada.'
        CfopConsiderSymbolicStorageReturn:
          type: string
          nullable: true
          description: CFOPs (separados por vírgula) a considerar como retorno simbólico.
        ConsumerVoucherDefault:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para gerar vale por padrão na devolução.'
        NFeFinReturn:
          type: integer
          nullable: true
          description: Finalidade da NFe de retorno.
        TypeOrderOrderPriority:
          type: integer
          minimum: 0
          maximum: 10
          nullable: true
          description: Prioridade no WMS (0–10).
        IDTypeAccountPayableReceivable:
          type: integer
          format: int32
          nullable: true
          description: Plano de contas padrão.
        IDTypeCostCenter:
          type: integer
          format: int32
          nullable: true
          description: Centro de custo padrão.
        OrderFinishConfirmation:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` para confirmar finalização no último pagamento.'
        HandlingDays:
          type: integer
          nullable: true
          description: Dias de manuseio.
        ShippingCutTime:
          type: string
          nullable: true
          description: Horário de corte (`HH:mm:ss`).
        IsTransfer:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` quando o tipo é transferência entre filiais. Default `0`.'
        ServiceRequest:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: '`1` quando o tipo representa ordem de serviço. Default `0`.'
        IDTypeOrderDefaultReturn:
          type: integer
          format: int32
          nullable: true
          description: Tipo de pedido usado como devolução padrão.
    PurchaseCfopInboundListItem:
      type: object
      description: >-
        Item de `GET /purchase/cfop-inbound`. Cada par `CfopFrom → CfopTo` define uma reescrita de CFOP aplicada ao
        receber NF-e: quando o CFOP do item da NF-e bate com `CfopFrom`, o movimento de estoque é gravado com `CfopTo`.
      properties:
        AccountName:
          type: string
          description: Subdomínio da empresa dona da regra.
        IDStockKeepingUnitPurchaseCfopInbound:
          type: integer
          format: int32
          description: Identificador da regra.
        IDCompany:
          type: integer
          format: int32
          description: Identificador da empresa dona da regra.
        CfopFrom:
          type: integer
          description: CFOP de origem (o que vem na NF-e do fornecedor). Inteiro de 4 dígitos.
        CfopFromDescription:
          type: string
          description: Descrição oficial do CFOP de origem (catálogo nacional).
        CfopTo:
          type: integer
          description: CFOP de destino (o que substituirá `CfopFrom` no movimento de estoque). Inteiro de 4 dígitos.
        CfopToDescription:
          type: string
          description: Descrição oficial do CFOP de destino (catálogo nacional).
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora de cadastro.
    PurchaseCfopInboundCreate:
      type: object
      description: >-
        Corpo do `POST /purchase/cfop-inbound`. Ambos os campos são obrigatórios e precisam corresponder a CFOPs
        existentes no catálogo nacional.
      required:
        - CfopFrom
        - CfopTo
      properties:
        CfopFrom:
          type: integer
          description: CFOP de origem. Inteiro de 4 dígitos. Precisa existir no catálogo nacional de CFOPs.
        CfopTo:
          type: integer
          description: CFOP de destino. Inteiro de 4 dígitos. Precisa existir no catálogo nacional de CFOPs.
    PurchaseCfopInboundUpdate:
      type: object
      description: >-
        Corpo do `PUT /purchase/cfop-inbound/{idstockkeepingunitpurchasecfopinbound}`. Os dois campos são sobrescritos a
        cada chamada (não é atualização parcial).
      required:
        - CfopFrom
        - CfopTo
      properties:
        CfopFrom:
          type: integer
          description: CFOP de origem. Inteiro de 4 dígitos. Precisa existir no catálogo nacional de CFOPs.
        CfopTo:
          type: integer
          description: CFOP de destino. Inteiro de 4 dígitos. Precisa existir no catálogo nacional de CFOPs.
    CompanyLabelListItem:
      type: object
      description: >-
        Modelo de etiqueta cadastrado pela empresa. Cada modelo combina uma categoria de uso (`TypeLabelCategory`), as
        dimensões em centímetros e o conteúdo — código ZPL bruto (modo 2) ou layout de canvas com variáveis (modo 1,
        gerado pelo editor visual).
      properties:
        IDCompanyLabel:
          type: integer
          format: int32
          description: Identificador do modelo de etiqueta.
        IDCompany:
          type: integer
          format: int32
          description: Identificador da empresa dona do modelo.
        AccountName:
          type: string
          description: Subdomínio da empresa dona do cadastro.
        LabelName:
          type: string
          description: 'Nome livre do modelo (ex.: ''Etiqueta Embarque Correios 10x10'').'
        IDTypeLabelCategory:
          type: integer
          format: int32
          description: Categoria do uso da etiqueta.
        TypeLabelCategory:
          type: string
          description: Descrição da categoria (`Embarque (adicional transportadora)`, `Itens (recebimento)`, `Endereços`, etc.).
        HeightCm:
          type: number
          description: Altura da etiqueta em centímetros. Limitada a 20 cm pelo front.
        WidthCm:
          type: number
          description: Largura da etiqueta em centímetros. Limitada a 20 cm pelo front.
        Columns:
          type: integer
          nullable: true
          description: Quantidade de colunas (por linha) quando a etiqueta é impressa em layout multi-coluna.
        BetweenColumnsCm:
          type: number
          nullable: true
          description: Espaçamento horizontal entre colunas, em centímetros.
        EditorMode:
          type: integer
          enum:
            - 1
            - 2
          description: 'Modo de edição: 1=Canvas (layout visual com variáveis e elementos), 2=ZPL (código bruto).'
        LabelZpl:
          type: string
          nullable: true
          description: >-
            Código ZPL da etiqueta. No modo 2 é o código informado direto pelo usuário; no modo 1 o front gera o ZPL a
            partir do layout. Pode ser nulo enquanto a etiqueta ainda está sendo desenhada.
        LogoWidth:
          type: number
          nullable: true
          description: Largura do logo dentro da etiqueta (modo Canvas).
        LogoHeight:
          type: number
          nullable: true
          description: Altura do logo dentro da etiqueta (modo Canvas).
        WordCountLimit:
          type: integer
          nullable: true
          description: Limite de caracteres usado em textos com truncagem (modo Canvas).
    CompanyLabelCreate:
      type: object
      description: Corpo de `POST /company/label`. Cria um modelo de etiqueta para a empresa autenticada.
      required:
        - LabelName
        - IDTypeLabelCategory
        - HeightCm
        - WidthCm
      properties:
        LabelName:
          type: string
          description: Nome livre do modelo.
        IDTypeLabelCategory:
          type: integer
          format: int32
          description: Categoria do uso (precisa existir em `TypeLabelCategory`).
        HeightCm:
          type: number
          description: Altura em cm. Front limita a 20 cm.
        WidthCm:
          type: number
          description: Largura em cm. Front limita a 20 cm.
        Columns:
          type: integer
          nullable: true
          description: Quantidade de etiquetas por linha quando a folha tem layout multi-coluna (modo Canvas). Default 1.
        BetweenColumnsCm:
          type: number
          nullable: true
          description: Espaçamento horizontal entre colunas, em centímetros (modo Canvas).
        EditorMode:
          type: integer
          enum:
            - 1
            - 2
          description: 1=Canvas (default quando omitido), 2=ZPL.
        LabelZpl:
          type: string
          nullable: true
          description: >-
            Código ZPL bruto. Obrigatório quando `EditorMode=2`; no modo Canvas (1) é gerado pelo front a partir do
            layout.
        LogoWidth:
          type: number
          nullable: true
          description: Largura do logotipo dentro da etiqueta, em pixels (modo Canvas).
        LogoHeight:
          type: number
          nullable: true
          description: Altura do logotipo dentro da etiqueta, em pixels (modo Canvas).
        WordCountLimit:
          type: integer
          nullable: true
          description: Limite de caracteres aplicado a textos com truncagem na etiqueta (modo Canvas).
    CompanyLabelUpdate:
      type: object
      description: Corpo de `PUT /company/label/{idcompanylabel}`. Atualização parcial — apenas campos enviados são alterados.
      properties:
        LabelName:
          type: string
          description: Nome livre do modelo.
        IDTypeLabelCategory:
          type: integer
          format: int32
          description: Categoria do uso (precisa existir em `TypeLabelCategory`).
        HeightCm:
          type: number
          description: Altura em cm. Front limita a 20 cm.
        WidthCm:
          type: number
          description: Largura em cm. Front limita a 20 cm.
        Columns:
          type: integer
          nullable: true
          description: Quantidade de etiquetas por linha quando a folha tem layout multi-coluna (modo Canvas).
        BetweenColumnsCm:
          type: number
          nullable: true
          description: Espaçamento horizontal entre colunas, em centímetros (modo Canvas).
        EditorMode:
          type: integer
          enum:
            - 1
            - 2
          description: 1=Canvas (layout visual com variáveis), 2=ZPL (código bruto).
        LabelZpl:
          type: string
          nullable: true
          description: >-
            Código ZPL bruto. Obrigatório quando `EditorMode=2`; no modo Canvas (1) é gerado pelo front a partir do
            layout.
        LogoWidth:
          type: number
          nullable: true
          description: Largura do logotipo dentro da etiqueta, em pixels (modo Canvas).
        LogoHeight:
          type: number
          nullable: true
          description: Altura do logotipo dentro da etiqueta, em pixels (modo Canvas).
        WordCountLimit:
          type: integer
          nullable: true
          description: Limite de caracteres aplicado a textos com truncagem na etiqueta (modo Canvas).
    TypeOrderStatusListItem:
      type: object
      description: >-
        Item da resposta de `GET /type/order/status`. Cada item representa o vínculo de um status fixo do sistema
        (`IDStatusOrder`) com a empresa, contendo o **nome local** (`StatusOrder`, editável), a **cor**
        (`StatusColorCode`) e a **descrição padrão** (`StatusOrderDescription`, do sistema — não editável).
      properties:
        IDStatusOrder:
          type: string
          description: >-
            Identificador do status (devolvido como string via `CAST AS CHAR`). Lista fixa do sistema — valores comuns:
            0=Aberto, 1=Fechado, 2=Iniciado picking, 3=Pré picking-list, 4=Finalizado picking, 5=Segurar pedido,
            6=Aguardando expedição, 7=Enviado, 8=Entregue com sucesso, 9=Em espera, 10=Picking não conformidade,
            11=Falta produto, 12=Falta produto a chegar, 13=Em tratativa, 14=Packing não conformidade, 15=Aguardando
            etiqueta, 16=Nota Fiscal, 17=Aguardando retirada, 19=Aguardando transportadora, 20=Em separação, 21=A
            faturar, 22=Aguardando romaneio, 23=Em espera etiqueta, 31=Aguardando aprovação crédito, 50-56=Orçamento e
            fluxos de aprovação, 70-79=Ordem de Serviço (OS), 89=Pagamento pendente canal, 90=Cancelado, 91=Extraviado,
            92=Extraviado parcialmente, 93=Em Produção, 94=Devolvido, 95=Em devolução, 96=Fulfillment, 97=Reversa
            finalizada, 100=Deletado.
        TypeStatusOrderCompany:
          type: integer
          format: int32
          description: Chave primária do vínculo do status com a empresa (`IDTypeStatusOrderCompany`).
        StatusOrder:
          type: string
          description: >-
            Nome **local** do status, editável pela empresa nesta tela. Inicia com o nome padrão do sistema
            (`StatusOrderDescription`).
        StatusColorCode:
          type: string
          nullable: true
          description: Cor (geralmente um hexadecimal `#RRGGBB`) usada para destacar o status em listas e gráficos. Pode ser nula.
        StatusOrderDescription:
          type: string
          nullable: true
          description: >-
            Descrição padrão do status no sistema (`StatusOrderDescription`) — não editável. Explica o que o status
            significa no fluxo.
        Order:
          type: number
          nullable: true
          description: >-
            Posição numérica do status no fluxo (`Order`). Usada para ordenar a lista e desenhar a linha do tempo do
            pedido.
        AccountName:
          type: string
          description: Subdomínio da empresa.
    TypeOrderStatusUpdate:
      type: object
      description: >-
        Corpo de `PUT /type/order/status/{idstatusorder}`. **Apenas dois campos podem ser alterados** — nome local e
        cor.
      properties:
        StatusOrder:
          type: string
          description: Novo nome local do status (apresentado no idworks para os usuários da empresa). Obrigatório no front.
        StatusColorCode:
          type: string
          nullable: true
          description: Cor que destaca o status em listas e gráficos. Geralmente um hexadecimal `#RRGGBB`. Pode ser nulo.
    CompanySalesPolicyListItem:
      type: object
      description: >-
        Política comercial (tabela de preço) da empresa. Cada política agrupa os preços dos produtos para um cenário de
        venda — atacado, varejo, e-commerce, lojas específicas, distribuidores. Os campos relacionados à política base
        (`IDCompanySalesPolicyFrom`, `IDTypeCompanySalesPolicyOperation`, `OperationValue`, `PriceRounding`) só são
        preenchidos quando o tipo é Relativa (3).
      properties:
        IDCompanySalesPolicy:
          type: integer
          format: int32
          description: Identificador da política comercial.
        IDCompany:
          type: integer
          format: int32
          description: Identificador da empresa dona da política.
        AccountName:
          type: string
          description: Subdomínio da empresa.
        CompanySalesPolicy:
          type: string
          description: 'Nome da política comercial (ex.: ''Tabela Atacado'', ''Site E-commerce'', ''Loja Centro'').'
        Default:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            1 quando esta é a política padrão da empresa (usada em vendas que não apontam para uma política específica).
            Apenas uma política por empresa pode ser padrão.
        IDTypeCompanySalesPolicy:
          type: integer
          enum:
            - 1
            - 2
            - 3
          description: >-
            Tipo da política: 1=Normal (preço cadastrado manualmente), 2=Custo médio (acompanha o custo médio do
            produto), 3=Relativa (calculada a partir de outra política).
        TypeCompanySalesPolicy:
          type: string
          description: Descrição do tipo (`Normal`, `Custo médio`, `Relativa à outra política`).
        Markup:
          type: number
          nullable: true
          description: >-
            Markup médio aplicado a esta política. Usado no recebimento de mercadoria para auxiliar na atualização do
            preço de venda. Aplicável a políticas Normal e Custo médio.
        CostAverage:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: >-
            Flag legada — `1` quando a política historicamente seguia o custo médio. Hoje a indicação correta é
            `IDTypeCompanySalesPolicy=2`.
        IDCompanySalesPolicyFrom:
          type: integer
          format: int32
          nullable: true
          description: >-
            (Tipo Relativa) Identificador da política comercial base usada como referência. A política base precisa ser
            do tipo Normal ou Custo médio.
        CompanySalesPolicyFrom:
          type: string
          nullable: true
          description: (Tipo Relativa) Nome da política comercial base.
        IDTypeCompanySalesPolicyOperation:
          type: integer
          enum:
            - 1
            - 2
          nullable: true
          description: >-
            (Tipo Relativa) Operação aplicada sobre a política base: 1=Multiplicação (ex.: base × 1.5), 2=Soma (ex.:
            base + 10,00). Valores negativos em `OperationValue` permitem reduzir o preço da base.
        TypeCompanySalesPolicyOperation:
          type: string
          nullable: true
          description: (Tipo Relativa) Descrição da operação (`Multiplicação` ou `Soma`).
        OperationValue:
          type: number
          nullable: true
          description: >-
            (Tipo Relativa) Valor da operação. Para Multiplicação, é o fator multiplicador (ex.: 1.5 = +50%); para Soma,
            é o valor somado/subtraído (negativo reduz o preço da base).
        PriceRounding:
          type: number
          nullable: true
          description: >-
            (Tipo Relativa) Valor entre 0 e 0,99 usado para arredondar o preço calculado (ex.: 0,99 faz o preço terminar
            sempre em ,99).
    CompanySalesPolicyCreate:
      type: object
      description: >-
        Corpo de `POST /company/sales-policy`. Quando `IDTypeCompanySalesPolicy=3` (Relativa), os campos
        `IDCompanySalesPolicyFrom`, `IDTypeCompanySalesPolicyOperation` e `OperationValue` são obrigatórios.
      required:
        - CompanySalesPolicy
      properties:
        CompanySalesPolicy:
          type: string
          description: Nome da política comercial.
        Default:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: Quando 1, marca esta política como padrão (desmarca a anterior automaticamente).
        IDTypeCompanySalesPolicy:
          type: integer
          enum:
            - 1
            - 2
            - 3
          description: 'Tipo: 1=Normal, 2=Custo médio, 3=Relativa. Default `1` quando omitido.'
        Markup:
          type: number
          nullable: true
          description: Markup médio (apenas tipos Normal e Custo médio).
        IDCompanySalesPolicyFrom:
          type: integer
          format: int32
          nullable: true
          description: >-
            (Tipo Relativa, obrigatório) Política base. Precisa ser Normal ou Custo médio — não aceita outra política
            Relativa.
        IDTypeCompanySalesPolicyOperation:
          type: integer
          enum:
            - 1
            - 2
          nullable: true
          description: (Tipo Relativa, obrigatório) 1=Multiplicação, 2=Soma.
        OperationValue:
          type: number
          nullable: true
          description: (Tipo Relativa, obrigatório) Valor da operação. Negativos são aceitos para reduzir o preço da base.
        PriceRounding:
          type: number
          nullable: true
          description: '(Tipo Relativa) Arredondamento entre 0 e 0,99 (ex.: 0,99 faz o preço terminar em ,99).'
        CostAverage:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: Flag legada. Default `0`. Prefira usar `IDTypeCompanySalesPolicy=2` para Custo médio.
    CompanySalesPolicyUpdate:
      type: object
      description: >-
        Corpo de `PUT /company/sales-policy/{idcompanysalespolicy}`. Somente o nome `CompanySalesPolicy` e a marca
        padrão `Default` são aplicados de forma parcial (só mudam se enviados). Os demais campos são sempre regravados:
        quando omitidos voltam ao padrão (`IDTypeCompanySalesPolicy`→1 Normal, `CostAverage`→0,
        `Markup`/`IDCompanySalesPolicyFrom`/`IDTypeCompanySalesPolicyOperation`/`OperationValue`/`PriceRounding`→nulo),
        zerando a configuração de política Relativa. Envie a configuração completa a cada atualização. Quando
        `IDTypeCompanySalesPolicy=3` (Relativa), `IDCompanySalesPolicyFrom`, `IDTypeCompanySalesPolicyOperation` e
        `OperationValue` são obrigatórios.
      properties:
        CompanySalesPolicy:
          type: string
          description: >-
            Nome da política comercial (ex.: 'Tabela Atacado', 'E-commerce', 'Distribuidor SP'). Aplicado de forma
            parcial — só muda se enviado.
        Default:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            Aplicado de forma parcial — só muda se enviado. Quando 1, marca como padrão (desmarca a anterior). Quando 0,
            o sistema bloqueia se essa for a única padrão da empresa.
        IDTypeCompanySalesPolicy:
          type: integer
          enum:
            - 1
            - 2
            - 3
          description: >-
            Tipo da política: 1=Normal (preço cadastrado manualmente), 2=Custo médio (acompanha o custo médio do
            produto), 3=Relativa (calculada a partir de outra política). Quando omitido, volta para 1=Normal.
        Markup:
          type: number
          nullable: true
          description: >-
            Markup médio aplicado a esta política. Usado no recebimento de mercadoria para auxiliar na atualização do
            preço de venda. Aplicável a políticas Normal e Custo médio. Quando omitido, é limpo (nulo).
        IDCompanySalesPolicyFrom:
          type: integer
          format: int32
          nullable: true
          description: >-
            (Tipo Relativa) Identificador da política base usada como referência. A política base precisa ser do tipo
            Normal ou Custo médio. Quando omitido, é limpo (nulo).
        IDTypeCompanySalesPolicyOperation:
          type: integer
          enum:
            - 1
            - 2
          nullable: true
          description: >-
            (Tipo Relativa) Operação aplicada sobre a política base: 1=Multiplicação (ex.: base × 1,5), 2=Soma (ex.:
            base + 10,00). Valores negativos em `OperationValue` permitem reduzir o preço da base. Quando omitido, é
            limpo (nulo).
        OperationValue:
          type: number
          nullable: true
          description: >-
            (Tipo Relativa) Valor da operação. Para Multiplicação, é o fator multiplicador; para Soma, é o valor
            somado/subtraído (negativo reduz o preço). Quando omitido, é limpo (nulo).
        PriceRounding:
          type: number
          nullable: true
          description: >-
            (Tipo Relativa) Valor entre 0 e 0,99 usado para arredondar o preço calculado (ex.: 0,99 faz o preço terminar
            sempre em ,99). Quando omitido, é limpo (nulo).
        CostAverage:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            Flag legada — `1` quando a política historicamente seguia o custo médio. Hoje a indicação correta é
            `IDTypeCompanySalesPolicy=2`. Quando omitido, volta para 0.
    CarrierModalListItem:
      type: object
      description: >-
        Modalidade de transportadora da empresa. Cada modalidade descreve a forma de operação logística — exemplos
        comuns: Rodoviário, Aéreo, Marítimo, Fluvial, Próprio, Motoboy, Drone, Bicicleta.
      properties:
        IDCarrierModal:
          type: integer
          format: int32
          description: Identificador da modalidade de transportadora.
        IDCompany:
          type: integer
          format: int32
          description: Identificador interno da empresa dona da modalidade.
        AccountName:
          type: string
          description: Subdomínio da empresa.
        CarrierModal:
          type: string
          description: Nome da modalidade.
    CarrierModalCreate:
      type: object
      description: >-
        Corpo de `POST /carrier/modal` e `PUT /carrier/modal/{idcarriermodal}`. Apenas um campo — o nome da modalidade.
        Precisa ser único dentro da empresa.
      required:
        - CarrierModal
      properties:
        CarrierModal:
          type: string
          description: 'Nome da modalidade (ex.: ''Rodoviário'', ''Aéreo'', ''Motoboy''). Precisa ser único na empresa.'
    CompanyDetail:
      type: object
      description: >-
        Cadastro completo da empresa autenticada — todos os campos do cadastro da empresa mais agregados de inscrições
        estaduais, créditos do Simples e descrições resolvidas. A senha do certificado (`CertificadoPassword`) é sempre
        devolvida como `null` por segurança.
      properties:
        IDCompany:
          type: integer
          format: int32
          description: Identificador da empresa.
        AccountName:
          type: string
          description: 'Subdomínio único da empresa no idworks (ex.: ''minhaempresa'' → minhaempresa.idworks.com.br).'
        CompanyStatus:
          type: integer
          description: Status do cadastro (ativo/inativo).
        CompanyNameCorporateName:
          type: string
          description: Razão social.
        CompanyTradeName:
          type: string
          nullable: true
          description: Nome fantasia.
        CompanyCpfCnpj:
          type: string
          description: CNPJ ou CPF da empresa (somente dígitos).
        CompanyAddressPostalCode:
          type: string
          nullable: true
          description: CEP.
        CompanyAddressStreet:
          type: string
          nullable: true
          description: Logradouro.
        CompanyAddressNumber:
          type: string
          nullable: true
          description: Número do endereço.
        CompanyAddressComplement:
          type: string
          nullable: true
          description: Complemento do endereço.
        CompanyAddressNeighborhood:
          type: string
          nullable: true
          description: Bairro.
        CompanyAddressCity:
          type: string
          nullable: true
          description: Cidade.
        CompanyAddressState:
          type: string
          nullable: true
          description: Sigla da UF.
        CompanyAddressIbgeCityCode:
          type: string
          nullable: true
          description: Código IBGE da cidade — atualizado automaticamente quando o CEP muda.
        CompanyTelephone:
          type: string
          nullable: true
          description: Telefone de contato.
        CompanyCityInscription:
          type: string
          nullable: true
          description: Inscrição municipal.
        WebSiteUrl:
          type: string
          nullable: true
          description: URL do site da empresa, exibida em documentos fiscais e na frente de loja.
        CompanyLogoUrl:
          type: string
          nullable: true
          description: URL do logotipo no bucket público do idworks.
        CompanyLogoUrlThumbnail:
          type: string
          nullable: true
          description: URL do logotipo com sufixo `-thumbnail` (versão pequena gerada pelo CDN).
        NfeRegimeTributario:
          type: integer
          nullable: true
          description: 'Regime tributário (CRT): 1=Simples Nacional, 2=Simples Nacional excesso sublimite, 3=Regime Normal, 4=MEI.'
        CrtDescription:
          type: string
          nullable: true
          description: Descrição do regime tributário.
        NfeSerie:
          type: string
          nullable: true
          description: Série atual da NFe modelo 55. Máximo 999.
        NfeUltima:
          type: integer
          nullable: true
          description: Número da última NFe modelo 55 emitida.
        NfeFeedStatus:
          type: integer
          nullable: true
          description: 1 quando a empresa tem feed NFe ativo.
        SefazAmbienteNF:
          type: integer
          nullable: true
          description: 'Ambiente de emissão NFe: 1=Produção, 2=Homologação.'
        NfceSerie:
          type: string
          nullable: true
          description: Série atual da NFCe (modelo 65).
        NfceUltima:
          type: integer
          nullable: true
          description: Número da última NFCe emitida.
        NfceCSC:
          type: string
          nullable: true
          description: Código de Segurança do Contribuinte (CSC) da NFCe.
        NfceCSCid:
          type: string
          nullable: true
          description: Identificador do CSC.
        SefazAmbienteNFC:
          type: integer
          nullable: true
          description: 'Ambiente NFCe: 1=Produção, 2=Homologação.'
        SefazAmbienteServiceInvoice:
          type: integer
          nullable: true
          description: 'Ambiente NFSe: 1=Produção, 2=Homologação.'
        ServiceInvoiceUltima:
          type: integer
          nullable: true
          description: Número da última NFSe emitida.
        NfseFeedStatus:
          type: integer
          nullable: true
          description: 1 quando a empresa tem feed NFSe ativo.
        CteFeedStatus:
          type: integer
          nullable: true
          description: 1 quando a empresa tem feed CTe ativo. Mesma empresa (CNPJ) não pode ter CTe ativo em duas contas.
        CertificadoBestBeforeDate:
          type: string
          format: date-time
          nullable: true
          description: Data de validade do certificado digital.
        CertificadoIssuer1:
          type: string
          nullable: true
          description: Emissor do certificado (campo 1 do subject).
        CertificadoIssuer2:
          type: string
          nullable: true
          description: Emissor do certificado (campo 2 do subject).
        CertificadoPassword:
          type: string
          nullable: true
          description: Sempre `null` — a senha do certificado nunca é exposta pela API.
        IDCompanyIntegration:
          type: integer
          nullable: true
          description: Identificador da integração NFe/NFSe principal (`IDTypeCompanyIntegration=16`).
        NfModNfDescription:
          type: string
          description: 'Texto fixo: ''NF-e emitida em substituição ao modelo 1 ou 1A''.'
        StateInscription:
          type: array
          items:
            $ref: '#/components/schemas/CompanyStateInscription'
          description: Inscrições estaduais cadastradas (uma por UF).
        CompanySimplesCred:
          type: array
          items:
            $ref: '#/components/schemas/CompanySimplesCredItem'
          description: Créditos do Simples Nacional registrados por período (mês/ano).
    CompanyStateInscription:
      type: object
      description: Inscrição estadual da empresa em uma UF específica.
      properties:
        IDCompanyStateInscription:
          type: integer
          format: int32
          description: Identificador da inscrição estadual cadastrada para a empresa (uma inscrição por UF de atuação).
        State:
          type: string
          description: 'Sigla da UF (ex.: ''SP'', ''RJ'', ''MG'').'
        StateName:
          type: string
          nullable: true
          description: Nome do estado (resolvido via `TypePostalCode`).
        StateInscription:
          type: string
          description: Número da inscrição estadual (somente dígitos).
        NFeComments:
          type: string
          nullable: true
          description: Observações fiscais que aparecem na NFe emitida para destinatários deste estado.
        NfeDifalIndFinal:
          type: integer
          nullable: true
          description: Flag de DIFAL — indicador de consumidor final para vendas interestaduais.
        GNRE:
          type: integer
          nullable: true
          description: Flag indicando se a empresa precisa emitir GNRE para vendas para este estado.
        CompanyStateInscriptionDueDay:
          type: integer
          nullable: true
          description: Dia do mês em que a GNRE vence para vendas a este estado.
    CompanyStateInscriptionCreate:
      type: object
      description: >-
        Corpo de `POST /company/state-inscription` e `PUT /company/state-inscription/{idstateinscription}`. A inscrição
        é validada com o algoritmo oficial por UF.
      required:
        - State
        - StateInscription
      properties:
        State:
          type: string
          description: 'Sigla da UF (ex.: ''SP'', ''RJ'', ''MG''). Apenas uma inscrição por estado.'
        StateInscription:
          type: string
          description: >-
            Número da inscrição estadual. Pode ter máscara — o sistema remove caracteres não numéricos. Para MG, faz
            padding com zeros à esquerda até 13 dígitos.
        NFeComments:
          type: string
          nullable: true
          description: >-
            Texto livre acrescentado às informações complementares da NFe quando a venda ocorre nesta UF (máx. 255
            caracteres).
        NfeDifalIndFinal:
          type: integer
          nullable: true
          description: 'Indicador de consumidor final para cálculo de DIFAL nas operações para esta UF: 0=Não, 1=Sim. Default 1.'
        GNRE:
          type: integer
          nullable: true
          description: Quando 1, esta UF emite GNRE (Guia Nacional de Recolhimento) para a empresa. Default 0.
        CompanyStateInscriptionDueDay:
          type: integer
          nullable: true
          description: Dia do mês de vencimento da guia GNRE/ICMS-ST para esta UF (1–31).
    CompanySimplesCredItem:
      type: object
      description: >-
        Crédito do Simples Nacional registrado para um período (mês/ano). Usado pelo idworks para calcular o crédito de
        PIS/COFINS em vendas de empresas no regime do Simples Nacional.
      properties:
        IDCompanySimplesCred:
          type: integer
          format: int32
          description: >-
            Identificador do crédito Simples Nacional cadastrado para a empresa (uma alíquota efetiva por anexo do
            Simples para cálculo de crédito a clientes).
        MonthYear:
          type: string
          format: date-time
          description: Primeiro dia do mês de competência (início da vigência do crédito).
        PCred:
          type: number
          description: Percentual de crédito do PIS/COFINS aplicado a este período.
        TotalEffectiveTax:
          type: number
          nullable: true
          description: Alíquota efetiva total dos tributos do Simples no período.
    CompanySimplesCredCreate:
      type: object
      description: >-
        Corpo de `POST /company/simples-cred` e `PUT /company/simples-cred/{idcompanysimplescred}`. O sistema converte
        `MonthYear` para o primeiro dia do mês automaticamente.
      required:
        - MonthYear
        - PCred
      properties:
        MonthYear:
          type: string
          format: date
          description: Mês/ano de competência (qualquer dia do mês — o sistema usa o primeiro/último dia automaticamente).
        PCred:
          type: number
          description: 'Percentual de crédito do PIS/COFINS (ex.: 1.25 para 1,25%).'
        TotalEffectiveTax:
          type: number
          nullable: true
          description: Alíquota efetiva total dos tributos do Simples no período (opcional).
    CompanyUpdate:
      type: object
      description: Corpo de `PUT /company`. Atualização parcial — apenas campos enviados são alterados.
      properties:
        CompanyNameCorporateName:
          type: string
          description: Razão social.
        CompanyTradeName:
          type: string
          nullable: true
          description: Nome fantasia.
        CompanyCpfCnpj:
          type: string
          description: CNPJ ou CPF (somente dígitos).
        CompanyAddressPostalCode:
          type: string
          nullable: true
          description: CEP. Quando muda, o sistema consulta o CEP novo e atualiza `CompanyAddressIbgeCityCode`.
        CompanyAddressStreet:
          type: string
          nullable: true
          description: Logradouro.
        CompanyAddressNumber:
          type: string
          nullable: true
          description: Número do endereço.
        CompanyAddressComplement:
          type: string
          nullable: true
          description: Complemento.
        CompanyAddressNeighborhood:
          type: string
          nullable: true
          description: Bairro.
        CompanyAddressCity:
          type: string
          nullable: true
          description: Cidade.
        CompanyAddressState:
          type: string
          nullable: true
          description: Sigla da UF.
        CompanyAddressIbgeCityCode:
          type: string
          nullable: true
          description: Código IBGE da cidade. Atualizado automaticamente quando `CompanyAddressPostalCode` muda.
        CompanyTelephone:
          type: string
          nullable: true
          description: Telefone de contato.
        CompanyCityInscription:
          type: string
          nullable: true
          description: Inscrição municipal.
        WebSiteUrl:
          type: string
          nullable: true
          description: URL do site da empresa.
        NfeRegimeTributario:
          type: integer
          nullable: true
          enum:
            - 1
            - 2
            - 3
            - 4
          description: 'Regime tributário (CRT): 1=Simples Nacional, 2=Simples Nacional excesso sublimite, 3=Regime Normal, 4=MEI.'
        NfeSerie:
          type: string
          nullable: true
          description: Série da NFe modelo 55. Máximo 999.
        NfeUltima:
          type: integer
          nullable: true
          description: Número da última NFe modelo 55 — usado para sincronizar o contador quando a empresa migra de outro sistema.
        SefazAmbienteNF:
          type: integer
          nullable: true
          description: 1=Produção, 2=Homologação.
        NfeFeedStatus:
          type: integer
          nullable: true
          description: >-
            Quando 1, ativa o feed de NFe (recebimento de XMLs de fornecedores). Apenas uma empresa por CNPJ pode manter
            o feed ativo.
        NfceUltima:
          type: integer
          nullable: true
          description: Número da última NFCe emitida — usado para sincronizar o contador quando a empresa migra de outro sistema.
        NfceSerie:
          type: string
          nullable: true
          description: Série da NFCe modelo 65. Máximo 999.
        NfceCSC:
          type: string
          nullable: true
          description: Código de Segurança do Contribuinte (CSC) da NFCe.
        NfceCSCid:
          type: string
          nullable: true
          description: Identificador do CSC da NFCe.
        SefazAmbienteNFC:
          type: integer
          nullable: true
          description: 'Ambiente de emissão NFCe: 1=Produção, 2=Homologação.'
        SefazAmbienteServiceInvoice:
          type: integer
          nullable: true
          description: 'Ambiente de emissão NFSe: 1=Produção, 2=Homologação.'
        ServiceInvoiceUltima:
          type: integer
          nullable: true
          description: Número da última NFSe emitida — usado para sincronizar o contador quando a empresa migra de outro sistema.
        CteFeedStatus:
          type: integer
          nullable: true
          description: Quando 1, o sistema bloqueia se outra empresa com mesmo CNPJ já tem CTe ativo.
        CompanyStatus:
          type: integer
          nullable: true
          description: Status do cadastro (ativo/inativo).
    CompanyBranchResponse:
      type: object
      description: Resposta de `GET /company/branch` — empresa-matriz com a lista de filiais agregada em `Branch[]`.
      properties:
        IDCompany:
          type: integer
          format: int32
          description: Identificador da empresa-matriz.
        AccountName:
          type: string
          description: Subdomínio da empresa-matriz.
        CompanyCpfCnpj:
          type: string
          description: CNPJ ou CPF da matriz (somente dígitos).
        CompanyTradeName:
          type: string
          nullable: true
          description: Nome fantasia da matriz.
        CompanyNameCorporateName:
          type: string
          description: Razão social da matriz.
        CompanyLogoUrl:
          type: string
          nullable: true
          description: URL do logotipo da matriz.
        CertificadoBestBeforeDate:
          type: string
          format: date-time
          nullable: true
          description: Data de validade do certificado digital da matriz.
        NfeSerie:
          type: string
          nullable: true
          description: Série atual da NFe modelo 55 da matriz.
        NfeUltima:
          type: integer
          nullable: true
          description: Número da última NFe modelo 55 emitida pela matriz.
        NfceSerie:
          type: string
          nullable: true
          description: Série atual da NFCe (modelo 65) da matriz.
        NfceUltima:
          type: integer
          nullable: true
          description: Número da última NFCe emitida pela matriz.
        CompanyStatus:
          type: integer
          description: Status do cadastro da matriz (ativo/inativo).
        CrtDescription:
          type: string
          nullable: true
          description: Descrição do regime tributário da matriz.
        Branch:
          type: array
          description: Filiais da empresa-matriz (vinculadas via `CompanyMain`).
          items:
            type: object
            properties:
              IDCompany:
                type: integer
                format: int32
                description: Identificador da filial.
              AccountName:
                type: string
                description: Subdomínio da filial.
              CompanyCpfCnpj:
                type: string
                description: CNPJ ou CPF da filial (somente dígitos).
              CompanyTradeName:
                type: string
                nullable: true
                description: Nome fantasia da filial.
              CompanyNameCorporateName:
                type: string
                description: Razão social da filial.
              CompanyLogoUrl:
                type: string
                nullable: true
                description: URL do logotipo da filial.
              CertificadoBestBeforeDate:
                type: string
                format: date-time
                nullable: true
                description: Data de validade do certificado digital da filial.
              NfeSerie:
                type: string
                nullable: true
                description: Série atual da NFe modelo 55 da filial.
              NfeUltima:
                type: integer
                nullable: true
                description: Número da última NFe modelo 55 emitida pela filial.
              NfceSerie:
                type: string
                nullable: true
                description: Série atual da NFCe (modelo 65) da filial.
              NfceUltima:
                type: integer
                nullable: true
                description: Número da última NFCe emitida pela filial.
              CompanyStatus:
                type: integer
                description: Status do cadastro da filial (ativo/inativo).
              CrtDescription:
                type: string
                nullable: true
                description: Descrição do regime tributário da filial.
    CompanyReportGroup:
      type: object
      description: >-
        Grupo de relatórios disponíveis para a empresa. Cada grupo agrupa relatórios da mesma categoria (Vendas,
        Financeiro, Fiscal, Estoque, WMS, TMS, Anúncios, Integração, Customizado, etc.). A resposta de `GET
        /company/report` é um array de grupos, e cada grupo tem um array `CompanyReport[]` — cuja chave interna
        `TypeCompanyReport` é por sua vez um array de relatórios individuais com seus filtros.
      properties:
        CompanyReport:
          type: array
          description: Grupos de relatórios da empresa.
          items:
            type: object
            properties:
              TypeCompanyReportGroup:
                type: string
                description: >-
                  Nome do grupo (ex.: 'Vendas', 'Financeiro', 'Fiscal', 'Estoque', 'WMS', 'TMS', 'Anúncios',
                  'Integração', 'Customizado').
              IDTypeCompanyReportGroup:
                type: integer
                format: int32
                description: Identificador do grupo de relatórios.
              TypeCompanyReport:
                type: array
                description: Relatórios individuais do grupo.
                items:
                  type: object
                  properties:
                    IDTypeCompanyReport:
                      type: integer
                      format: int32
                      description: >-
                        Identificador do tipo de relatório — usado em `POST /user/report` no campo
                        `IDTypeCompanyReport`.
                    TypeCompanyReport:
                      type: string
                      description: 'Nome do relatório (ex.: ''Pedidos por período'', ''Conciliação de Estoque'').'
                    TypeCompanyReportQuery:
                      type: array
                      description: Filtros aceitos pelo relatório.
                      items:
                        type: object
                        properties:
                          Type:
                            type: string
                            enum:
                              - RangerPicker
                              - InputGroup
                              - Select
                              - Input
                            description: >-
                              Tipo do componente de filtro: `RangerPicker` para intervalo de datas (dois campos),
                              `InputGroup` para par de valores numéricos, `Select` para lista pré-carregada, `Input`
                              para texto livre.
                          Label:
                            type: string
                            description: Legenda exibida no formulário.
                          Param:
                            type: array
                            items:
                              type: string
                            description: >-
                              Lista de nomes de query string que o front envia ao gerar o relatório.
                              RangerPicker/InputGroup têm 2 itens (`From`, `To`); Select tem até 3 (`nameValue`,
                              `nameLabel`, `nameList`); Input tem 1.
    UserReportListItem:
      type: object
      description: Relatório gerado pelo usuário autenticado, com status atual e (quando pronto) o link de download.
      properties:
        IDUserReport:
          type: integer
          format: int32
          description: Identificador interno do relatório gerado.
        IDCompany:
          type: integer
          format: int32
          description: Identificador interno da empresa dona do relatório.
        IDTypeCompanyReport:
          type: integer
          format: int32
          description: Tipo do relatório gerado.
        TypeCompanyReport:
          type: string
          description: Nome do relatório (resolvido).
        AccountName:
          type: string
          description: Subdomínio da empresa.
        IDTypeStatusUserReport:
          type: integer
          description: Status numérico interno.
          enum:
            - 1
            - 2
            - 3
        Status:
          type: string
          description: 'Nome do status atual: `Processando`, `Gerado` ou `Sem dados`.'
        Query:
          type: string
          description: 'Query string com os filtros usados na geração (ex.: `DateFrom=2026-01-01&DateTo=2026-01-31`).'
        SendEmail:
          type: integer
          enum:
            - 0
            - 1
          description: 1 = enviar o link por e-mail ao usuário quando terminar; 0 = só disponibilizar pela tela.
        Link:
          type: string
          nullable: true
          description: URL de download do arquivo. Vazio enquanto o relatório está sendo processado.
        Comments:
          type: string
          nullable: true
          description: 'Comentários adicionais (ex.: número de linhas, mensagem de erro).'
        RecordTimestamp:
          type: string
          format: date-time
          description: Data/hora da geração.
        RecordUserCreated:
          type: integer
          format: int32
          description: Identificador do usuário que pediu o relatório.
    UserReportCreate:
      type: object
      description: Corpo de `POST /user/report`. Enfileira a geração de um relatório novo.
      required:
        - IDTypeCompanyReport
        - Query
      properties:
        IDTypeCompanyReport:
          type: integer
          format: int32
          description: >-
            Identificador do tipo de relatório. Escolha um dos tipos disponíveis para a empresa, retornados em
            `IDTypeCompanyReport` por `GET /company/report`.
        Query:
          type: string
          description: >-
            Query string com os filtros do relatório, no formato `chave1=valor1&chave2=valor2` (ex.:
            `DateFrom=2026-06-23&DateTo=2026-06-23`). As chaves dependem do tipo de relatório. Precisa ser uma
            querystring: se vier um objeto JSON, a requisição é rejeitada com `[BadRequest]`.
        SendEmail:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            1 = enviar o link do arquivo por e-mail ao usuário quando o processamento terminar; 0 = só disponibilizar
            pela tela. Opcional.
    UserComissionCreate:
      type: object
      description: >-
        Corpo de `POST /user/{iduser}/comission` e `PUT /user/{iduser}/comission/{idsalesmancomission}`. Define uma
        regra de comissão para o vendedor.
      required:
        - DateFrom
        - DateTo
        - ComissionPercent
      properties:
        DateFrom:
          type: string
          format: date
          description: Início da vigência da regra (`YYYY-MM-DD`).
        DateTo:
          type: string
          format: date
          description: 'Fim da vigência da regra (`YYYY-MM-DD`). Para regra sem prazo, use uma data distante (ex.: `2099-12-31`).'
        ComissionPercent:
          type: number
          description: Percentual de comissão como fração (0.05 = 5%).
        DiscountPercentLimit:
          type: number
          nullable: true
          description: >-
            Percentual máximo de desconto permitido como fração (0.10 = 10%). Vendas com desconto acima desse limite
            **não pagam** essa comissão.
        IDCategory:
          type: integer
          format: int32
          nullable: true
          description: >-
            Identificador da categoria de SKU (`StockKeepingUnitCategory`). Quando informado, a regra só vale para
            vendas de produtos dessa categoria. Quando nulo, vale para qualquer produto.
    UserComissionDetail:
      type: object
      description: >-
        Detalhe do usuário com a lista atualizada de regras de comissão. Resposta de `POST/PUT/DELETE
        /user/{iduser}/comission*`.
      properties:
        IDUser:
          type: integer
          format: int32
          description: Identificador do usuário (vendedor).
        UserName:
          type: string
          description: Nome do usuário.
        Login:
          type: string
          description: Login (email) do usuário.
        Salesman:
          type: integer
          enum:
            - 0
            - 1
          description: 1 quando o usuário é vendedor (acumula comissão em vendas).
        DiscountPercentLimit:
          type: number
          nullable: true
          description: Limite **padrão** de desconto para vendas do vendedor (aplicado quando nenhuma regra específica casa).
        IDTypeSalesmanCommission:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
          nullable: true
          description: >-
            Flux de liberação da comissão: 1=parcial vinculada às parcelas, 2=integral no faturamento, 3=integral após
            pagamento da 1ª parcela, 4=integral após pagamento da última parcela.
        ExcludeCanceledOrdersCommission:
          type: integer
          enum:
            - 0
            - 1
          description: 1 = pedidos cancelados não entram no cálculo da comissão.
        ExcludeReturnedOrdersCommission:
          type: integer
          enum:
            - 0
            - 1
          description: 1 = pedidos devolvidos não entram no cálculo da comissão.
        SalesmanComission:
          type: array
          description: Regras de comissão vinculadas ao usuário.
          items:
            type: object
            properties:
              IDSalesmanComission:
                type: integer
                format: int32
                description: Identificador da regra de comissão.
              IDAcess:
                type: integer
                format: int32
                description: Vínculo do usuário com a empresa (`IDAcess`).
              DateFrom:
                type: string
                format: date
                description: Início da vigência da regra (`YYYY-MM-DD`).
              DateTo:
                type: string
                format: date
                description: Fim da vigência da regra (`YYYY-MM-DD`).
              DiscountPercentLimit:
                type: number
                nullable: true
                description: >-
                  Limite máximo de desconto da regra como fração (0.10 = 10%). Vendas com desconto acima desse limite
                  não pagam essa comissão.
              ComissionPercent:
                type: number
                description: Percentual de comissão da regra como fração (0.05 = 5%).
              IDCategory:
                type: integer
                format: int32
                nullable: true
                description: Categoria de SKU à qual a regra se aplica. `null` quando a regra vale para qualquer categoria.
              Category:
                type: string
                nullable: true
                description: Descrição da categoria (resolvida).
              RecordTimestamp:
                type: string
                format: date-time
                description: Data/hora em que a regra foi cadastrada.
    StoreFrontCashierHistoryListItem:
      type: object
      description: Item de `GET /store-front/cashier/history`. Cada linha é uma abertura de caixa (`StoreFrontCashier`).
      properties:
        IDCompany:
          type: integer
          format: int32
          description: Identificador da empresa dona da conta bancária do caixa.
        AccountName:
          type: string
          description: Subdomínio da empresa.
        IDBankAccount:
          type: integer
          format: int32
          description: Identificador da conta bancária (caixa).
        Bank:
          type: string
          description: Nome do caixa (campo `Bank` da `BankAccount`).
        IDCompanyInvoice:
          type: integer
          format: int32
          nullable: true
          description: Faturador associado ao caixa.
        IDStoreFrontCashier:
          type: integer
          format: int32
          description: Identificador único da sessão de caixa.
        RecordUserCreated:
          type: integer
          format: int32
          description: Identificador do usuário que abriu o caixa.
        Login:
          type: string
          description: Login do operador.
        UserName:
          type: string
          description: Nome do operador.
        RecordTimestampOpen:
          type: string
          format: date-time
          description: Data e hora da abertura do caixa.
        RecordTimestampClose:
          type: string
          format: date-time
          nullable: true
          description: Data e hora do fechamento. `null` enquanto o caixa segue aberto.
        CommentsOpen:
          type: string
          nullable: true
          description: Comentários da abertura (saldo inicial declarado, observações).
        CommentsClose:
          type: string
          nullable: true
          description: Comentários do fechamento (sobras/quebras, observações).
    StoreFrontCashierHistoryDetail:
      type: object
      description: >-
        Resposta de `GET /store-front/cashier/history/{idstorefrontcashier}` e de `PUT
        /store-front/cashier/history/{idstorefrontcashier}/adjust/{idaccountpayablereceivable}`. Cabeçalho da sessão
        acompanhado das listas agregadas de pedidos, lançamentos bancários e totais por tipo de pagamento.
      properties:
        IDCompany:
          type: integer
          format: int32
          description: Identificador interno da empresa dona do caixa.
        AccountName:
          type: string
          description: Subdomínio da empresa dona do caixa.
        IDBankAccount:
          type: integer
          format: int32
          description: Conta bancária (caixa) da sessão.
        Bank:
          type: string
          description: 'Nome do caixa (ex.: `Caixa 1`, `Maquininha Cielo`).'
        IDStoreFrontCashier:
          type: integer
          format: int32
          description: Identificador da sessão de caixa.
        RecordUserCreated:
          type: integer
          format: int32
          description: Identificador do usuário operador que abriu a sessão.
        Login:
          type: string
          description: Login do operador que abriu a sessão.
        UserName:
          type: string
          description: Nome do operador que abriu a sessão.
        RecordTimestampOpen:
          type: string
          format: date-time
          description: Data/hora de abertura da sessão.
        RecordTimestampClose:
          type: string
          format: date-time
          nullable: true
          description: Data/hora de fechamento. `null` enquanto a sessão estiver aberta.
        CommentsOpen:
          type: string
          nullable: true
          description: Observações registradas pelo operador na abertura.
        CommentsClose:
          type: string
          nullable: true
          description: >-
            Observações registradas pelo operador no fechamento (geralmente preenchidas quando há diferença entre o
            saldo apurado e o contado).
        TotalOrderValue:
          type: number
          description: Soma dos valores em `OrderList` (todos os pedidos da sessão, inclusive cancelados).
        TotalTransactionValue:
          type: number
          description: Soma dos valores em `TransactionList` (lançamentos bancários da sessão, considerando sinal original).
        OrderList:
          type: array
          description: >-
            Pedidos atendidos no caixa, uma linha por recebimento (`AccountsPayableReceivable`). Agrupado pelo par
            (`IDOrder`, `IDTypePayment`).
          items:
            type: object
            properties:
              IDOrder:
                type: integer
                format: int32
                description: Pedido vinculado ao recebimento.
              IDAccountPayableReceivable:
                type: integer
                format: int32
                description: >-
                  Identificador do recebimento — passar para `PUT
                  /store-front/cashier/history/{idstorefrontcashier}/adjust/{idaccountpayablereceivable}` ao editar.
              RecordTimestamp:
                type: string
                format: date-time
                description: Carimbo de data/hora do pedido (campo `RecordTimestamp` de `StoreFrontCashierOrder`).
              Value:
                type: number
                description: Soma das parcelas do recebimento agrupado.
              IDTypePayment:
                type: integer
                format: int32
                nullable: true
                description: >-
                  Forma de pagamento do recebimento. `null` quando o pedido foi cancelado sem ter forma de pagamento
                  atribuída.
              TypePaymentDescription:
                type: string
                nullable: true
                description: Descrição amigável da forma de pagamento.
              InstallmentTotal:
                type: integer
                nullable: true
                description: Quantidade de parcelas do recebimento.
              TID:
                type: string
                nullable: true
                description: TID da maquininha (quando aplicável).
              NSU:
                type: string
                nullable: true
                description: NSU da maquininha (quando aplicável).
              ConsumerNameCorporateName:
                type: string
                nullable: true
                description: Nome/Razão social do consumidor do pedido.
              SalesmanLogin:
                type: string
                nullable: true
                description: Login do vendedor (`IDSalesMan`).
              SalesmanUsername:
                type: string
                nullable: true
                description: Nome do vendedor.
              IDStatusOrder:
                type: integer
                format: int32
                description: Status do pedido. `90` indica venda cancelada.
              StatusOrder:
                type: string
                description: Descrição do status.
              OrderComments:
                type: string
                nullable: true
                description: Comentários do pedido (especialmente úteis para vendas canceladas).
        TransactionList:
          type: array
          description: >-
            Lançamentos bancários vinculados à sessão (`AccountsPayableReceivableBankStatement`): sangrias, suprimentos,
            recebimentos baixados, etc.
          items:
            type: object
            properties:
              DateTransactionTimestamp:
                type: string
                format: date-time
                description: Data/hora do lançamento bancário.
              TransactionDescription:
                type: string
                description: >-
                  Texto livre do lançamento. Sangrias contêm a palavra `sangria` (a tela do extrato isola esses itens em
                  uma seção separada).
              Value:
                type: number
                description: Valor absoluto. A tela aplica sinal negativo quando `IDTypeAccount = 1` (débito).
              IDTypeAccount:
                type: integer
                format: int32
                description: '`1` = débito (saída), demais = crédito (entrada).'
              IDAccountPayableReceivable:
                type: integer
                format: int32
                nullable: true
                description: Identificador do recebimento conciliado por esse extrato (quando aplicável).
              IDBankStatement:
                type: integer
                format: int32
                nullable: true
                description: Identificador do extrato bancário de origem (quando o lançamento foi importado de OFX).
              IDOrder:
                type: integer
                format: int32
                nullable: true
                description: Pedido vinculado ao recebimento (quando aplicável).
              IDStatusOrder:
                type: integer
                format: int32
                nullable: true
                description: >-
                  Status do pedido vinculado ao lançamento (quando há). `null` para lançamentos que não vieram de pedido
                  (reforço/sangria/ajustes).
              StatusOrder:
                type: string
                nullable: true
                description: Descrição amigável do status do pedido.
              OrderComments:
                type: string
                nullable: true
                description: Comentários do pedido (útil principalmente em pedidos cancelados).
        PaymentSummary:
          type: array
          description: >-
            Total de recebimentos **válidos** (pedidos não cancelados) por tipo de pagamento. A lista parte dos tipos de
            pagamento ativos com `EnableFrenteCaixa = 1`, zerados, e é incrementada conforme `OrderList` é processada —
            tipos inativos aparecem apenas se houve recebimento neles.
          items:
            type: object
            properties:
              IDTypePayment:
                type: integer
                format: int32
                nullable: true
                description: Forma de pagamento. `null` em linhas agregadas que não casaram com um tipo cadastrado.
              TypePaymentDescription:
                type: string
                nullable: true
                description: Descrição amigável da forma de pagamento.
              TotalValue:
                type: number
                description: Soma arredondada em 2 casas.
    StoreFrontCashierHistoryAdjust:
      type: object
      description: >-
        Corpo de `PUT /store-front/cashier/history/{idstorefrontcashier}/adjust/{idaccountpayablereceivable}`. Todos os
        campos são opcionais — somente os enviados são alterados, exceto `InstallmentTotal`, que quando difere do valor
        atual dispara recálculo de parcelamento.
      properties:
        IDTypePayment:
          type: integer
          format: int32
          nullable: true
          description: Novo tipo de pagamento. Precisa pertencer à mesma empresa do recebimento (`IDCompany`).
        TID:
          type: string
          nullable: true
          description: TID da maquininha (envie `null` para limpar).
        NSU:
          type: string
          nullable: true
          description: NSU da maquininha (envie `null` para limpar).
        InstallmentTotal:
          type: integer
          nullable: true
          description: >-
            Nova quantidade de parcelas. **Quando diferente do valor atual**, o sistema apaga os recebimentos do
            agrupamento `(IDOrder, IDTypePayment, IDTypeAccount, NSU, TID)` atual e recria o parcelamento com o valor
            total dividido em `InstallmentTotal` parcelas.
    SkuPromotionListItem:
      type: object
      description: >-
        Item de `GET /sku/promotion`. Cabeçalho da promoção, sem as listas vinculadas (use o `GET /sku/promotion/{id}`
        para o detalhe).
      properties:
        IDStockKeepingUnitPromotion:
          type: integer
          format: int32
          description: Identificador da promoção.
        IDCompany:
          type: integer
          format: int32
          description: Identificador da empresa dona da promoção.
        AccountName:
          type: string
          description: Subdomínio da empresa.
        IDTypeSkuPromotion:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
          description: 'Tipo: 1=Regular, 2=Compre e Ganhe, 3=Desconto Progressivo, 4=Compre Junto.'
        TypeSkuPromotion:
          type: string
          description: Descrição do tipo (resolvida).
        IDTypeSkuPromotionStatus:
          type: integer
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
          description: 'Status: 0=Excluída, 1=Ativo, 2=Programada, 3=Finalizada, 4=Inativa.'
        TypeSkuPromotionStatus:
          type: string
          description: 'Status textual: `Ativo`, `Programada`, `Finalizada`, `Inativa` (`Excluída` quando o registro foi removido).'
        StockKeepingUnitPromotionName:
          type: string
          description: Nome da promoção.
        StockKeepingUnitPromotionDescription:
          type: string
          nullable: true
          description: Descrição livre da promoção.
        DateFrom:
          type: string
          format: date-time
          description: Início da vigência. `1900-01-01` indica "para sempre".
        DateTo:
          type: string
          format: date-time
          description: Fim da vigência. `4000-01-01` indica "para sempre".
        PercentualDiscountValue:
          type: number
          nullable: true
          description: Fração 0–1 (0.10 = 10%). Usado em Regular, Compre Junto (lista principal).
        NominalDiscountValue:
          type: number
          nullable: true
          description: Valor em R$. Usado em Regular.
        MinOrderValue:
          type: number
          nullable: true
          description: Valor mínimo do pedido para a promoção valer (Regular).
        MaxOrderValue:
          type: number
          nullable: true
          description: Valor máximo do pedido para a promoção valer (Regular).
        MinimumQuantityBuyTogether:
          type: number
          nullable: true
          description: Quantidade mínima de unidades para ativar a promoção (Compre e Ganhe / Compre Junto).
        PercentualDiscountValueBuyTogether:
          type: number
          nullable: true
          description: Fração 0–1 do desconto na lista complementar do Compre Junto.
        Cumulative:
          type: integer
          enum:
            - 0
            - 1
          description: 1 = pode acumular com outras promoções.
        CumulativeManualPrice:
          type: integer
          enum:
            - 0
            - 1
          description: 1 = aplica mesmo se houver preço manual no item.
        AllowDifferentItemQuantitySum:
          type: integer
          enum:
            - 0
            - 1
          description: 1 = soma quantidades de SKUs diferentes para atingir a quantidade mínima.
        ExactlyQuantity:
          type: integer
          enum:
            - 0
            - 1
          description: 1 = aplica só em quantidades múltiplas exatas (Progressivo).
        OnlyRegisteredConsumer:
          type: integer
          enum:
            - 0
            - 1
          description: 1 = aplica somente quando o pedido tem cliente cadastrado.
        BrandsIncluded:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            Default 1. 1 = aplicar em SKUs cujas marcas estão na lista; 0 = aplicar em SKUs cujas marcas NÃO estão na
            lista.
        CategoriesIncluded:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            Default 1. 1 = aplicar em SKUs cujas categorias estão na lista; 0 = aplicar em SKUs cujas categorias NÃO
            estão na lista.
        ProductsIncluded:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            Default 1. 1 = aplicar em SKUs cujos produtos-pai estão na lista; 0 = aplicar em SKUs cujos produtos-pai NÃO
            estão na lista.
        SkusIncluded:
          type: integer
          enum:
            - 0
            - 1
          description: Default 1. 1 = aplicar nos SKUs que estão na lista; 0 = aplicar nos SKUs que NÃO estão na lista.
    SkuPromotionRestrictionRef:
      type: object
      description: >-
        Referência a um vínculo da promoção. Usado no body de POST/PUT (com apenas o id) e na resposta do GET (com id +
        nome resolvido).
      properties:
        IDBrand:
          type: integer
          format: int32
          description: Marca à qual a restrição/aplicação da promoção se aplica.
        IDCategory:
          type: integer
          format: int32
          description: Categoria à qual a restrição/aplicação da promoção se aplica.
        IDProduct:
          type: integer
          format: int32
          description: '`IDSku` com `IDTypeSku = 4` (produto pai).'
        IDSku:
          type: integer
          format: int32
          description: '`IDSku` com `IDTypeSku ∈ {2,3,6,7,8}` (kit, sku, matéria-prima, uso e consumo, caixa).'
        IDTypeOrder:
          type: integer
          format: int32
          description: Tipo de pedido (venda, atacado, varejo, etc.) ao qual a promoção é restrita.
        IDCompanySalesPolicy:
          type: integer
          format: int32
          description: Política comercial à qual a promoção é restrita.
        BrandName:
          type: string
          description: Apenas na resposta.
        CategoryName:
          type: string
          description: Apenas na resposta.
        ProductName:
          type: string
          description: Apenas na resposta — formato `IDSkuCompany | SkuName`.
        IDProductCompany:
          type: string
          description: Apenas na resposta.
        SkuName:
          type: string
          description: Apenas na resposta — formato `IDSkuCompany | SkuName`.
        IDSkuCompany:
          type: string
          description: Apenas na resposta.
        BarCode:
          type: string
          description: Apenas na resposta (somente para SKU/SkusBuyTogether).
        MainImageURL:
          type: string
          nullable: true
          description: Apenas na resposta (somente para SkusBuyTogether) — URL da imagem principal do SKU.
        TypeOrder:
          type: string
          description: Descrição amigável do tipo de pedido.
        CompanySalesPolicy:
          type: string
          description: Nome da política comercial.
    SkuPromotionProgressiveTier:
      type: object
      description: >-
        Faixa de uma promoção de Desconto Progressivo. Cada faixa tem `Quantity` (gatilho — a partir de quantas unidades
        vale) e `DiscountPercent` **ou** `FixedPrice` (mutualmente exclusivos). `Quantity` precisa ser único entre as
        faixas. No `POST`/`PUT`, envie apenas `Quantity` + um dos dois campos de valor. No `GET`, vêm os 3 (o não usado
        vem `null`) + o id.
      properties:
        IDStockKeepingUnitPromotionProgressive:
          type: integer
          format: int32
          description: Apenas na resposta.
        Quantity:
          type: number
          description: Quantidade mínima de unidades para entrar nesta faixa.
        DiscountPercent:
          type: number
          nullable: true
          description: Fração 0–1 do desconto. `null` quando se usa `FixedPrice`.
        FixedPrice:
          type: number
          nullable: true
          description: Preço unitário fixo em R$ aplicado quando a faixa é ativada. `null` quando se usa `DiscountPercent`.
    SkuPromotionCreate:
      type: object
      description: >-
        Corpo de `POST /sku/promotion`. Os campos exigidos variam por tipo — veja a descrição do POST para regras
        detalhadas.
      required:
        - IDTypeSkuPromotion
        - StockKeepingUnitPromotionName
        - DateFrom
        - DateTo
      properties:
        IDTypeSkuPromotion:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
          description: 1=Regular, 2=Compre e Ganhe, 3=Desconto Progressivo, 4=Compre Junto.
        StockKeepingUnitPromotionName:
          type: string
          description: Nome — gravado sem acentos (normalização NFD).
        StockKeepingUnitPromotionDescription:
          type: string
          nullable: true
          description: Descrição livre da promoção (opcional).
        DateFrom:
          type: string
          format: date-time
          description: Início da vigência. Use `1900-01-01` para "para sempre".
        DateTo:
          type: string
          format: date-time
          description: Fim da vigência. Use `4000-01-01` para "para sempre".
        Enabled:
          type: integer
          enum:
            - 0
            - 1
          description: 1=Ativo.
        Cumulative:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` permite cumular com outras promoções no mesmo pedido; `0` (padrão) torna a promoção exclusiva.'
        CumulativeManualPrice:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` aplica a promoção mesmo quando o operador edita o preço manualmente no PDV; `0` (padrão) desabilita.'
        AllowDifferentItemQuantitySum:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            `1` permite somar quantidades de SKUs diferentes da mesma promoção para atingir o gatilho de quantidade —
            útil em `Compre junto` quando o cliente pode misturar variações.
        ExactlyQuantity:
          type: integer
          enum:
            - 0
            - 1
          description: Só relevante para tipo 3.
        OnlyRegisteredConsumer:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            `1` restringe a promoção a consumidores identificados (cadastrados no pedido); `0` (padrão) aceita venda
            anônima.
        PercentualDiscountValue:
          type: number
          nullable: true
          description: >-
            Fração 0–1. Usado em **tipo 1** (Regular, opcional — escolher entre % ou R$) e **tipo 4** (Compre Junto,
            obrigatório — desconto da lista principal).
        NominalDiscountValue:
          type: number
          nullable: true
          description: Valor em R$. Usado em **tipo 1** (Regular, opcional — alternativa ao %).
        MinOrderValue:
          type: number
          nullable: true
          description: Apenas tipo 1.
        MaxOrderValue:
          type: number
          nullable: true
          description: Apenas tipo 1.
        MinimumQuantityBuyTogether:
          type: number
          nullable: true
          description: Obrigatório nos tipos 2 e 4. Quantidade mínima de unidades (da lista principal no tipo 4).
        PercentualDiscountValueBuyTogether:
          type: number
          nullable: true
          description: Obrigatório no tipo 4. Fração 0–1 do desconto da lista complementar.
        BrandsIncluded:
          type: integer
          enum:
            - 0
            - 1
          description: Default 1. Apenas tipo 1.
        CategoriesIncluded:
          type: integer
          enum:
            - 0
            - 1
          description: Default 1. Apenas tipo 1.
        ProductsIncluded:
          type: integer
          enum:
            - 0
            - 1
          description: Default 1. Apenas tipo 1.
        SkusIncluded:
          type: integer
          enum:
            - 0
            - 1
          description: Default 1. Apenas tipo 1.
        StockKeepingUnitPromotionBrands:
          type: array
          items:
            type: object
            required:
              - IDBrand
            properties:
              IDBrand:
                type: integer
                description: Identificador da marca participante (a promoção vale para todos os SKUs da marca).
          description: Apenas tipo 1.
        StockKeepingUnitPromotionCategories:
          type: array
          items:
            type: object
            required:
              - IDCategory
            properties:
              IDCategory:
                type: integer
                description: Identificador da categoria participante.
          description: Apenas tipo 1.
        StockKeepingUnitPromotionProducts:
          type: array
          items:
            type: object
            required:
              - IDProduct
            properties:
              IDProduct:
                type: integer
                description: Identificador do produto-pai (SKU `IDTypeSku=4`) participante.
          description: Tipos 1 e 3. Cada `IDProduct` é um `IDSku` com `IDTypeSku = 4` (produto pai).
        StockKeepingUnitPromotionSkus:
          type: array
          items:
            type: object
            required:
              - IDSku
            properties:
              IDSku:
                type: integer
                description: Identificador do SKU participante.
          description: >-
            Tipos 1, 2, 3 e 4. Itens elegíveis (`IDTypeSku ∈ {2,3,6,7,8}`). Para tipo 2/4 é a lista de itens **que devem
            ser comprados** (lista principal).
        StockKeepingUnitPromotionSkusBuyTogether:
          type: array
          items:
            type: object
            required:
              - IDSku
            properties:
              IDSku:
                type: integer
                description: >-
                  Identificador do SKU do grupo `Compre junto` (lista alternativa específica do tipo 4 — promoção
                  `Compre junto`).
          description: >-
            Tipos 2 e 4. No tipo 2 é a lista de **itens de brinde** (ganham com `PriceSellingTotal=0`); no tipo 4 é a
            **lista complementar** (recebem `PercentualDiscountValueBuyTogether`).
        StockKeepingUnitPromotionProgressive:
          type: array
          items:
            $ref: '#/components/schemas/SkuPromotionProgressiveTier'
          description: Apenas tipo 3. Cada faixa precisa ter `Quantity` único.
        StockKeepingUnitPromotionTypeOrders:
          type: array
          items:
            type: object
            required:
              - IDTypeOrder
            properties:
              IDTypeOrder:
                type: integer
                description: 'Identificador do tipo de pedido em que a promoção vale (ex.: somente vendas no PDV).'
          description: Tipos de pedido aceitos. Vazio = todos.
        StockKeepingUnitPromotionSalesPolicies:
          type: array
          items:
            type: object
            required:
              - IDCompanySalesPolicy
            properties:
              IDCompanySalesPolicy:
                type: integer
                description: 'Identificador da política comercial em que a promoção vale (ex.: tabela de preço varejo).'
          description: Políticas comerciais aceitas. Vazio = todas.
    SkuPromotionUpdate:
      description: >-
        Corpo de `PUT /sku/promotion/{idstockkeepingunitpromotion}`. Mesmos campos do `POST` (exceto
        `IDTypeSkuPromotion`, que vem da promoção existente). Listas omitidas **não são tocadas**; listas enviadas
        (mesmo vazias) **substituem** os vínculos atuais. Inclui também `Enabled` para alternar ativo/inativo.
      allOf:
        - $ref: '#/components/schemas/SkuPromotionCreate'
    SkuPromotionDetail:
      type: object
      description: >-
        Resposta de `GET /sku/promotion/{id}`, `POST /sku/promotion` e `PUT /sku/promotion/{id}`. Inclui o cabeçalho +
        todas as listas vinculadas com nomes resolvidos.
      allOf:
        - $ref: '#/components/schemas/SkuPromotionListItem'
        - type: object
          properties:
            Enabled:
              type: integer
              enum:
                - 0
                - 1
              description: '`1` quando a promoção está vigente e ativa; `0` quando inativa.'
            StockKeepingUnitPromotionBrands:
              type: array
              items:
                $ref: '#/components/schemas/SkuPromotionRestrictionRef'
              description: Marcas incluídas/excluídas na restrição da promoção.
            StockKeepingUnitPromotionCategories:
              type: array
              items:
                $ref: '#/components/schemas/SkuPromotionRestrictionRef'
              description: Categorias incluídas/excluídas na restrição da promoção.
            StockKeepingUnitPromotionProducts:
              type: array
              items:
                $ref: '#/components/schemas/SkuPromotionRestrictionRef'
              description: Produtos (pai) incluídos/excluídos na restrição da promoção.
            StockKeepingUnitPromotionSkus:
              type: array
              items:
                $ref: '#/components/schemas/SkuPromotionRestrictionRef'
              description: SKUs incluídos/excluídos na restrição da promoção.
            StockKeepingUnitPromotionTypeOrders:
              type: array
              items:
                $ref: '#/components/schemas/SkuPromotionRestrictionRef'
              description: Tipos de pedido em que a promoção é válida (vazio = todos).
            StockKeepingUnitPromotionSkusBuyTogether:
              type: array
              items:
                $ref: '#/components/schemas/SkuPromotionRestrictionRef'
              description: SKUs da lista de brinde/complementar (Compre e Ganhe / Compre Junto).
            StockKeepingUnitPromotionProgressive:
              type: array
              items:
                $ref: '#/components/schemas/SkuPromotionProgressiveTier'
              description: Faixas de desconto progressivo (quantidade × desconto ou preço fixo).
            StockKeepingUnitPromotionSalesPolicies:
              type: array
              items:
                $ref: '#/components/schemas/SkuPromotionRestrictionRef'
              description: Políticas comerciais em que a promoção é válida (vazio = todas).
    SkuPromotionSkuItem:
      type: object
      description: >-
        Item de `GET /sku/promotion/sku/{idsku}`. Promoção vigente que casa com o SKU informado, com flags de inclusão
        por restrição.
      properties:
        IDStockKeepingUnitPromotion:
          type: integer
          format: int32
          description: Identificador da promoção.
        IDTypeSkuPromotion:
          type: integer
          description: 'Tipo da promoção: `1` Regular, `2` Compre e ganhe, `3` Desconto progressivo, `4` Compre junto.'
          enum:
            - 1
            - 2
            - 3
            - 4
        TypeSkuPromotion:
          type: string
          description: Descrição textual do tipo da promoção.
        StockKeepingUnitPromotionName:
          type: string
          description: Nome da promoção.
        StockKeepingUnitPromotionDescription:
          type: string
          nullable: true
          description: Descrição livre da promoção.
        AccountName:
          type: string
          description: Conta (subdomínio) da empresa.
        DateFrom:
          type: string
          format: date-time
          description: Data e hora de início da vigência.
        DateTo:
          type: string
          format: date-time
          description: Data e hora de término da vigência.
        IDTypeSkuPromotionStatus:
          type: integer
          description: 'Status: `1` Ativo, `2` Programada, `3` Finalizada, `4` Inativa (`0` Excluída).'
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
        TypeSkuPromotionStatus:
          type: string
          description: Descrição textual do status.
        PercentualDiscountValue:
          type: number
          nullable: true
          description: 'Desconto percentual aplicado (ex.: `0.10` = 10%).'
        NominalDiscountValue:
          type: number
          nullable: true
          description: Desconto nominal em valor monetário.
        MinOrderValue:
          type: number
          nullable: true
          description: Valor mínimo do pedido para a promoção ser aplicada.
        MaxOrderValue:
          type: number
          nullable: true
          description: Valor máximo do pedido a partir do qual a promoção deixa de valer.
        Cumulative:
          type: integer
          description: '`1` permite cumular com outras promoções no mesmo pedido; `0` é exclusiva.'
        MinimumQuantityBuyTogether:
          type: number
          nullable: true
          description: Quantidade mínima do conjunto na promoção `Compre junto` para o desconto se aplicar.
        PercentualDiscountValueBuyTogether:
          type: number
          nullable: true
          description: Desconto percentual aplicado na promoção `Compre junto`.
        IncludeBrand:
          type: integer
          enum:
            - 0
            - 1
          description: 1 = SKU passa na restrição de marca.
        IncludeBrandType:
          type: integer
          nullable: true
          enum:
            - 1
            - 2
            - 3
            - null
          description: 1 = `BrandsIncluded=1` casou; 2 = lista vazia; 3 = `BrandsIncluded=0` casou (NÃO está).
        IncludeCategory:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` quando há categorias vinculadas à promoção.'
        IncludeCategoryType:
          type: integer
          nullable: true
          description: >-
            Modo de inclusão das categorias: `1` inclui apenas as categorias vinculadas; `2` exclui as categorias
            vinculadas (todas as outras participam).
        IncludeProd:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` quando há produtos-pai vinculados à promoção.'
        IncludeProdType:
          type: integer
          nullable: true
          description: 'Modo de inclusão dos produtos: `1` inclui apenas os listados; `2` exclui os listados.'
        IncludeSku:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` quando há SKUs vinculados à promoção.'
        IncludeSkuType:
          type: integer
          nullable: true
          description: 'Modo de inclusão dos SKUs: `1` inclui apenas os listados; `2` exclui os listados.'
        IncludeSkuTogether:
          type: integer
          nullable: true
          enum:
            - 0
            - 1
            - null
          description: 1 = SKU está na lista de brindes/lista complementar da promoção (tipo 2/4).
    SkuPromotionOrderValidateItem:
      type: object
      description: >-
        Item do carrinho enviado em `POST /sku/promotion/order/validate`. O sistema agrupa por (`IDSku`,
        `IDStockKeepingUnitWarehouse`) somando quantidades antes de aplicar promoções.
      required:
        - IDSku
        - Quantity
        - PriceSelling
      properties:
        IDSku:
          type: integer
          format: int32
          description: SKU do item do pedido a validar contra as promoções ativas.
        Quantity:
          type: number
          description: Quantidade do SKU no item do pedido.
        PriceSelling:
          type: number
          description: Preço unitário de venda corrente.
        PriceList:
          type: number
          nullable: true
          description: Preço de tabela (de lista) — usado para detectar preço manual.
        ValueDiscount:
          type: number
          nullable: true
          description: Valor de desconto já aplicado ao item (informativo — entra no cálculo de promoções acumuladas).
        IDCompanySalesPolicy:
          type: integer
          format: int32
          nullable: true
          description: Política comercial do item — passa no filtro `StockKeepingUnitPromotionSalesPolicies`.
        IDStockKeepingUnitWarehouse:
          type: integer
          format: int32
          nullable: true
          description: Armazém de origem do item (algumas promoções são restritas a armazéns específicos).
        IDStockKeepingUnitPromotion:
          type: array
          items:
            type: integer
          description: Lista de promoções já aplicadas ao item — se vazia, o sistema recalcula.
        SkuName:
          type: string
          nullable: true
          description: Nome do SKU (informativo para retorno).
        BarCode:
          type: string
          nullable: true
          description: Código de barras principal do SKU (informativo).
        IDSkuCompany:
          type: string
          nullable: true
          description: Código de referência interno do SKU, definido pela empresa (informativo).
    SkuPromotionOrderValidateBody:
      type: object
      description: Corpo de `POST /sku/promotion/order/validate`.
      required:
        - Items
      properties:
        Items:
          type: array
          items:
            $ref: '#/components/schemas/SkuPromotionOrderValidateItem'
          description: >-
            Lista de itens a validar contra as promoções da empresa. Cada item descreve um SKU, quantidade e preço; o
            sistema aplica as promoções vigentes e devolve descontos e ajustes calculados.
        IDOrderType:
          type: integer
          format: int32
          description: Tipo de pedido sendo montado — usado para filtrar promoções por `StockKeepingUnitPromotionTypeOrders`.
        IDConsumer:
          type: integer
          format: int32
          nullable: true
          description: Cliente do pedido — quando vazio, descarta promoções com `OnlyRegisteredConsumer=1`.
        IDStoreFrontCashier:
          type: integer
          format: int32
          nullable: true
          description: Caixa do PDV aberto — necessário para persistir o carrinho em `StoreFrontCashierOrderTemp`.
        IDStoreFrontCashierOrderTemp:
          type: integer
          format: int32
          nullable: true
          description: >-
            Quando informado, atualiza o registro existente em `StoreFrontCashierOrderTemp`. Quando omitido, cria um
            novo e devolve o id gerado na resposta.
    SkuPromotionOrderValidateResponse:
      type: object
      description: >-
        Resposta de `POST /sku/promotion/order/validate`. Espelha o body com os preços recalculados e a lista de
        promoções avaliadas por item.
      properties:
        Items:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/SkuPromotionOrderValidateItem'
              - type: object
                properties:
                  PriceSellingTotal:
                    type: number
                    description: Total recalculado após promoções (`PriceSelling × Quantity` no agrupamento).
                  OriginalPriceSellingTotal:
                    type: number
                    description: Total antes das promoções.
                  ValueDiscountTotal:
                    type: number
                    description: '`OriginalPriceSellingTotal - PriceSellingTotal`.'
                  OriginalPriceSelling:
                    type: number
                    description: Preço de venda original do item, antes da promoção.
                  PromotionDiscountPercent:
                    type: number
                    description: '`1 - PriceSellingTotal / OriginalPriceSellingTotal`.'
                  StockKeepingUnitPromotionName:
                    type: array
                    items:
                      type: string
                    description: Nomes das promoções aplicadas (formato `TipoPromocao - Nome`).
                  Promotions:
                    type: array
                    description: >-
                      Lista completa das promoções **avaliadas** para o item (não apenas as aplicadas), com flags de
                      inclusão para diagnóstico.
                    items:
                      type: object
                      properties:
                        IDStockKeepingUnitPromotion:
                          type: integer
                          description: Identificador da promoção aplicada.
                        IDTypeSkuPromotion:
                          type: integer
                          description: Tipo da promoção aplicada.
                          enum:
                            - 1
                            - 2
                            - 3
                            - 4
                        TypeSkuPromotion:
                          type: string
                          description: Descrição do tipo de promoção.
                        StockKeepingUnitPromotionName:
                          type: string
                          description: Nome da promoção aplicada.
                        PercentualDiscountValue:
                          type: number
                          nullable: true
                          description: Desconto percentual aplicado (fração `0–1`). `null` quando a promoção é por valor nominal.
                        NominalDiscountValue:
                          type: number
                          nullable: true
                          description: Desconto nominal aplicado em R$. `null` quando a promoção é percentual.
                        MinOrderValue:
                          type: number
                          nullable: true
                          description: Valor mínimo do pedido para a promoção valer. `null` quando não há mínimo.
                        MaxOrderValue:
                          type: number
                          nullable: true
                          description: Valor máximo do pedido para a promoção valer. `null` quando não há máximo.
                        Cumulative:
                          type: integer
                          description: '`1` quando a promoção pode acumular com outras de tipos diferentes.'
                        AllowDifferentItemQuantitySum:
                          type: integer
                          description: '`1` quando a quantidade mínima considera a soma de SKUs diferentes.'
                        ExactlyQuantity:
                          type: integer
                          description: '`1` quando a faixa progressiva só vale em múltiplos exatos da quantidade.'
                        MinimumQuantityBuyTogether:
                          type: number
                          nullable: true
                          description: Quantidade mínima a comprar (Compre e Ganhe / Compre Junto). `null` nos demais tipos.
                        PercentualDiscountValueBuyTogether:
                          type: number
                          nullable: true
                          description: Desconto percentual da lista complementar (Compre Junto). `null` nos demais tipos.
                        GroupedQuantity:
                          type: number
                          description: >-
                            Quantidade considerada para o gatilho — soma de SKUs diferentes quando
                            `AllowDifferentItemQuantitySum=1`.
                        PrePriceSellingTotal:
                          type: number
                          description: Preço total antes desta promoção (auxiliar de cálculo).
                        PreValueDiscountTotal:
                          type: number
                          description: Valor estimado do desconto da promoção — usado no desempate (maior desconto primeiro).
                        StockKeepingUnitPromotionSkusBuyTogether:
                          type: array
                          items:
                            $ref: '#/components/schemas/SkuPromotionRestrictionRef'
                          description: Apenas tipo 2/4.
                        StockKeepingUnitPromotionProgressive:
                          type: array
                          items:
                            $ref: '#/components/schemas/SkuPromotionProgressiveTier'
                          description: Apenas tipo 3 — vem ordenado desc por `Quantity`.
          description: >-
            Lista de itens com os campos calculados das promoções aplicáveis (preço pré-desconto, valor do desconto,
            identificador da promoção, etc.).
        IDStoreFrontCashierOrderTemp:
          type: integer
          format: int32
          description: >-
            Id do registro persistido/atualizado em `StoreFrontCashierOrderTemp` — devolvido também quando o request
            veio sem ele (insert).
        IDOrderType:
          type: integer
          format: int32
          description: Tipo do pedido considerado na validação (algumas promoções valem só para tipos específicos).
        IDConsumer:
          type: integer
          format: int32
          nullable: true
          description: Identificador do consumidor considerado (promoções com `OnlyRegisteredConsumer=1` exigem este campo).
        IDStoreFrontCashier:
          type: integer
          format: int32
          nullable: true
          description: Identificador do caixa do PDV, quando a validação é feita no contexto da frente de loja.
    StoreFrontPaymentListItem:
      type: object
      description: >-
        Item de `GET /store-front/payment`. Cada linha é uma tentativa de cobrança feita no PDV (cartão via PayGo, Pix
        via StarkBank ou Pagar.me).
      properties:
        IDStoreFrontCashierPayment:
          type: integer
          format: int32
          description: Identificador único da transação.
        IDCompany:
          type: integer
          format: int32
          description: Identificador interno da empresa dona do caixa.
        AccountName:
          type: string
          description: Subdomínio da empresa dona da conta bancária.
        IDCompanyInvoice:
          type: integer
          format: int32
          nullable: true
          description: Faturador (empresa de emissão da NFC-e) — pode ser diferente da empresa dona do caixa.
        AccountNameInvoice:
          type: string
          nullable: true
          description: >-
            Subdomínio do faturador (empresa configurada para emitir a NFC-e da venda). Pode ser diferente do
            `AccountName`.
        CompanyNameCorporateNameInvoice:
          type: string
          nullable: true
          description: Nome/Razão social do faturador.
        IDBankAccount:
          type: integer
          format: int32
          description: Conta bancária (caixa) onde a transação foi originada.
        Bank:
          type: string
          description: 'Nome do caixa (ex.: "Caixa 1", "Maquininha Cielo").'
        IDCompanyIntegration:
          type: integer
          format: int32
          nullable: true
          description: >-
            Integração configurada na conta bancária (`IDCompanyIntegration`) — determina se foi PayGo, StarkBank ou
            Pagar.me.
        IDTypePayment:
          type: integer
          format: int32
          description: >-
            Forma de pagamento (`IDTypePayment`). Para esta rota, sempre crédito (`Category=22`), débito (`Category=23`)
            ou Pix (`Category=24`).
        TypePaymentDescription:
          type: string
          description: 'Descrição amigável da forma de pagamento (ex.: `Crédito Visa 1x`, `Pix StarkBank`).'
        RecordTimestamp:
          type: string
          format: date-time
          description: Data/hora da criação da transação.
        RecordTimestampCancel:
          type: string
          format: date-time
          nullable: true
          description: Data/hora do cancelamento (preenchido apenas em transações canceladas).
        IDUserCancel:
          type: integer
          format: int32
          nullable: true
          description: Identificador do usuário que iniciou o cancelamento.
        Value:
          type: number
          description: Valor total da transação em R$.
        InstallmentTotal:
          type: integer
          description: Quantidade de parcelas (1 para Pix e débito).
        IDOrderIntention:
          type: string
          description: UUID que liga a tentativa de pagamento ao pedido fechado no PDV.
        IDOrder:
          type: integer
          format: int32
          nullable: true
          description: Pedido vinculado (resolvido via `IDOrderIntention`). `null` quando a transação ainda não virou pedido.
        IDTypeStatusStoreFrontCashierPayment:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 7
            - 8
          description: >-
            1=Pendente, 2=Em pagamento, 3=Creditado, 4=Expirado, 5=Cancelamento iniciado, 6=Em cancelamento,
            7=Cancelado, 8=Pagamento recusado.
        TypeStatusStoreFrontCashierPayment:
          type: string
          description: Descrição do status.
        TefTerminal:
          type: string
          nullable: true
          description: Código do terminal TEF (id PayGo da maquininha física). `0` quando integração não é PayGo.
        TID:
          type: string
          nullable: true
          description: TID/NSU retornado pelo adquirente.
        AuthId:
          type: string
          nullable: true
          description: Código de autorização do adquirente.
        Acquirer:
          type: string
          nullable: true
          description: Adquirente (Cielo, Rede, Stone etc.) — vem do adquirente real, não do gateway.
        PaymentSystemName:
          type: string
          nullable: true
          description: Bandeira do cartão (Visa, Master, Elo etc.) ou "Pix".
        ReturnCode:
          type: string
          nullable: true
          description: Código de resposta do adquirente.
        ReturnMessage:
          type: string
          nullable: true
          description: Mensagem de resposta do adquirente (usada em falhas).
        CardLastDigits:
          type: string
          nullable: true
          description: Últimos 4 dígitos do cartão.
        Receipt:
          type: string
          nullable: true
          description: ZPL do comprovante via estabelecimento, com sufixo `\r\n VA` apendado para impressão direta.
        ReceiptBuyer:
          type: string
          nullable: true
          description: ZPL do comprovante via cliente, com sufixo `\r\n VA` apendado.
    StoreFrontPaymentPostBody:
      type: object
      description: >-
        Body de `POST /store-front/cashier/{idbankaccount}/payment`. Os campos exigidos são `IDTypePayment` e `Value`; o
        restante varia por integração.
      required:
        - IDTypePayment
        - Value
      properties:
        IDTypePayment:
          type: integer
          format: int32
          description: >-
            Tipo de pagamento (`IDTypePayment`). Precisa pertencer à empresa e ter `Category ∈ {22, 23, 24}` (crédito,
            débito, Pix).
        Value:
          type: number
          description: Valor total da cobrança em R$.
        InstallmentTotal:
          type: integer
          default: 1
          description: >-
            Quantidade de parcelas. `1` para débito/Pix. Para crédito segue a configuração do tipo de pagamento e do
            parâmetro `parcelamentoAdmin` da integração.
        IDOrderIntention:
          type: string
          description: >-
            UUID opcional para ligar a tentativa ao pedido. Quando omitido, o sistema gera um UUID novo e devolve no
            body.
    StoreFrontPaymentPostResponse:
      type: object
      description: Resposta de `POST /store-front/cashier/{idbankaccount}/payment`. Campos variam por integração.
      properties:
        IDStoreFrontCashierPayment:
          type: integer
          format: int32
          description: Identificador da transação criada — usar nas chamadas seguintes de `GET` e `DELETE`.
        IDOrderIntention:
          type: string
          description: UUID que liga a tentativa ao pedido. Gerado pelo sistema quando omitido no body.
        IDTypeStatusStoreFrontCashierPayment:
          type: integer
          enum:
            - 2
          description: >-
            Status inicial da transação logo após iniciada: `2` Em pagamento. O ciclo completo (Pendente, Creditado,
            Expirado, Cancelado, etc.) é acompanhado via `GET` da transação.
        ExternalId:
          type: string
          nullable: true
          description: >-
            Id da transação no gateway externo. PayGo: `intencaoVenda.id`. StarkBank: `uuid` do BR Code. Pagar.me: id do
            pedido.
        PixCopiaCola:
          type: string
          nullable: true
          description: 'String Pix copia-cola (StarkBank: `id` do BR Code; Pagar.me: corpo do QR Code). Ausente para PayGo.'
        QrCodeImageUrl:
          type: string
          format: uri
          nullable: true
          description: 'URL da imagem do QR Code (StarkBank: `pictureUrl`; Pagar.me: URL do gateway). Ausente para PayGo.'
        QrcodeExpirationTimeInSeconds:
          type: integer
          nullable: true
          description: Tempo de expiração do QR Code em segundos. Default 3600. Ausente para PayGo.
        TID:
          type: string
          nullable: true
          description: TID do Pagar.me (já devolvido no POST). PayGo e StarkBank só preenchem no `GET`.
    StoreFrontPaymentGetResponse:
      type: object
      description: >-
        Resposta de `GET /store-front/cashier/{idbankaccount}/payment/{idstorefrontcashierpayment}`. Combina campos
        atualizados na transação + indicador `Success`.
      properties:
        IDStoreFrontCashierPayment:
          type: integer
          format: int32
          description: Identificador da transação consultada.
        IDTypeStatusStoreFrontCashierPayment:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 7
            - 8
          description: >-
            Status final da transação após o polling do gateway. `1` Pendente, `2` Em pagamento, `3` Creditado, `4`
            Expirado, `5` Cancelamento iniciado, `6` Em cancelamento, `7` Cancelado, `8` Pagamento recusado.
        TypeStatusStoreFrontCashierPayment:
          type: string
          description: >-
            Descrição do status. Aparece quando o polling chegou a um veredicto (Creditado, Cancelado, Pagamento
            recusado, Expirado).
        Success:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            `1` = transação finalizada com sucesso (Creditado ou Cancelado bem sucedido). `0` = falha (Expirado,
            Pagamento recusado, casos especiais PayGo `-2596`).
        TID:
          type: string
          nullable: true
          description: TID/NSU retornado pelo adquirente. Para PayGo, vem em `nsuTid` da resposta do terminal.
        AuthId:
          type: string
          nullable: true
          description: Código de autorização do adquirente.
        Acquirer:
          type: string
          nullable: true
          description: >-
            Nome do adquirente real que processou (Cielo, Rede, Stone etc.) — vem da resposta do gateway, não do
            cadastro da conta.
        PaymentSystemName:
          type: string
          nullable: true
          description: Bandeira do cartão (`Visa`, `Master`, `Elo` etc.) ou `Pix`.
        ReturnCode:
          type: string
          nullable: true
          description: Código de resposta do adquirente (cancelamentos e recusas trazem o motivo aqui).
        ReturnMessage:
          type: string
          nullable: true
          description: Mensagem textual do adquirente, geralmente preenchida em falhas e cancelamentos.
        CardLastDigits:
          type: string
          nullable: true
          description: Últimos 4 dígitos do cartão. Extraído de `CARTAO:` ou `PWINFO_CARDPARCPAN` da resposta PayGo.
        Receipt:
          type: string
          nullable: true
          description: ZPL via estabelecimento — extraído entre `PWINFO_RCPTMERCH =` e `PWINFO_RCPTCHOLDER` da resposta PayGo.
        ReceiptBuyer:
          type: string
          nullable: true
          description: >-
            ZPL via cliente — extraído entre `PWINFO_RCPTCHOLDER =` e
            `PWINFO_RCPTCHSHORT`/`PWINFO_TRNORIGDATE`/`PWINFO_LANGUAGE` (na ordem).
        ExternalId:
          type: string
          nullable: true
          description: Apenas em respostas Pix (StarkBank/Pagar.me).
        PixCopiaCola:
          type: string
          nullable: true
          description: Apenas Pix.
        QrCodeImageUrl:
          type: string
          format: uri
          nullable: true
          description: Apenas Pix.
        QrcodeExpirationTimeInSeconds:
          type: integer
          nullable: true
          description: Apenas Pix.
    StoreFrontCashierListItem:
      type: object
      description: >-
        Item de `GET /store-front/cashier`. Cada caixa do PDV (`BankAccount` do tipo caixinha) com status, operador e
        saldo atuais.
      properties:
        IDBankAccount:
          type: integer
          format: int32
          description: Conta bancária (caixa).
        Bank:
          type: string
          description: 'Nome do caixa (ex.: "Caixa 1", "Maquininha Cielo").'
        AccountName:
          type: string
          description: Subdomínio da empresa dona do caixa.
        IDCompanyInvoice:
          type: integer
          format: int32
          nullable: true
          description: Faturador (empresa de emissão da NFC-e). Quando vazio, o caixa não tem faturador configurado.
        AccountNameInvoice:
          type: string
          nullable: true
          description: Subdomínio do faturador (empresa configurada para emitir a NFC-e da venda).
        CompanyNameCorporateNameInvoice:
          type: string
          nullable: true
          description: Razão social do faturador, exibida no cabeçalho dos recibos.
        CompanyCpfCnpjInvoice:
          type: string
          nullable: true
          description: CNPJ do faturador (sem máscara), usado no cabeçalho dos recibos.
        IDCompanyIntegration:
          type: integer
          format: int32
          nullable: true
          description: Integração de pagamento (PayGo / StarkBank / Pagar.me) — usada quando a venda for processada via TEF/Pix.
        StoreFrontCashierStatus:
          type: integer
          enum:
            - 1
            - 2
          description: 'Status calculado: `1`=Fechado, `2`=Aberto.'
        StoreFrontCashierStatusDescription:
          type: string
          enum:
            - Aberto
            - Fechado
          description: >-
            Descrição amigável do status calculado em tempo real. `Aberto` quando há sessão (`RecordTimestampClose`
            nulo); `Fechado` caso contrário.
        IDStoreFrontCashier:
          type: integer
          format: int32
          nullable: true
          description: Id da sessão aberta. Null quando o caixa está fechado.
        RecordTimestampOpen:
          type: string
          format: date-time
          nullable: true
          description: Data/hora de abertura da sessão atual. Null quando fechado.
        Login:
          type: string
          nullable: true
          description: Login do operador que abriu o caixa. Null quando fechado.
        Balance:
          type: number
          description: >-
            Saldo corrente do caixa em R$ (soma de todos os lançamentos em `AccountsPayableReceivableBankStatement` até
            agora).
    StoreFrontCashierDetail:
      type: object
      description: >-
        Resposta de `GET /store-front/cashier/{idbankaccount}`. Snapshot do caixa aberto com totais financeiros, listas
        agregadas e ZPLs prontos para impressão.
      properties:
        IDBankAccount:
          type: integer
          format: int32
          description: Conta bancária (caixa).
        IDCompany:
          type: integer
          format: int32
          description: Identificador interno da empresa dona do caixa.
        BankNumber:
          type: string
          example: '000'
          description: Sempre `'000'` (caixinha do PDV).
        IDStoreFrontCashier:
          type: integer
          format: int32
          nullable: true
          description: Identificador da sessão aberta. `null` quando o caixa está fechado.
        RecordTimestampOpen:
          type: string
          format: date-time
          nullable: true
          description: Data/hora de abertura da sessão atual. `null` quando fechado.
        RecordUserCreated:
          type: integer
          format: int32
          nullable: true
          description: Identificador do operador que abriu a sessão. `null` quando fechado.
        Login:
          type: string
          nullable: true
          description: Login do operador que abriu a sessão. `null` quando fechado.
        UserName:
          type: string
          nullable: true
          description: Nome do operador que abriu a sessão. `null` quando fechado.
        IDTypeOrder:
          type: integer
          format: int32
          description: >-
            Tipo de pedido padrão do caixa. Quando a `BankAccount` não tem, o sistema usa o `DefaultFrenteCaixa=1` da
            empresa.
        TypeOrder:
          type: string
          description: Nome do tipo de pedido padrão (`TypeOrder`).
        IDCompanySalesPolicy:
          type: integer
          format: int32
          description: Política comercial herdada do tipo de pedido.
        CompanySalesPolicy:
          type: string
          description: Política comercial aplicada (lista de preços e condições).
        CompanyCpfCnpjInvoice:
          type: string
          description: CNPJ do faturador (sem máscara) — usado no cabeçalho dos recibos.
        CompanyNameCorporateNameInvoice:
          type: string
          description: Razão social do faturador.
        IDOrderStoreFrontCashierOrderList:
          type: string
          nullable: true
          description: Lista CSV de `IDOrder` dos pedidos fechados nesta sessão.
        Balance:
          type: number
          description: Saldo total do caixa em R$.
        Income:
          type: number
          description: >-
            Créditos desde a abertura — descontada a parcela já contabilizada pelos pagamentos em dinheiro nos pedidos
            (para evitar dupla contagem).
        Outcome:
          type: number
          description: Débitos desde a abertura.
        AdjustIn:
          type: number
          description: Reforços (créditos sem `IDAccountPayableReceivable`).
        AdjustOut:
          type: number
          description: Sangrias (débitos sem `IDAccountPayableReceivable`).
        TotalValueCancelled:
          type: number
          description: >-
            Diferença entre `Income` original e a soma dos pagamentos em dinheiro — útil para identificar discrepâncias
            com vendas canceladas.
        PaymentSummary:
          type: array
          description: >-
            Total vendido por **tipo de pagamento** específico (descrição). Inclui tipos zerados habilitados no PDV
            (`EnableFrenteCaixa=1`) para o operador conferir.
          items:
            type: object
            properties:
              IDTypePayment:
                type: integer
                format: int32
                nullable: true
                description: Forma de pagamento. `null` em linhas agregadas que não casaram com um tipo cadastrado.
              TypePaymentDescription:
                type: string
                nullable: true
                description: Descrição amigável da forma de pagamento.
              Category:
                type: integer
                nullable: true
                description: >-
                  Categoria do tipo de pagamento (`Category`). Determina o agrupamento em `PaymentCategorySummary`. Ex.:
                  `1` Dinheiro, `22` Crédito, `23` Débito, `24` Pix.
              TypePaymentCategory:
                type: string
                nullable: true
                description: Descrição amigável da categoria de pagamento (`Dinheiro`, `Crédito`, `Débito`, `Pix`, `Vale`, etc.).
              EnableFrenteCaixa:
                type: integer
                enum:
                  - 0
                  - 1
                description: >-
                  `1` quando a forma de pagamento está habilitada para uso no PDV (aparece no menu de cobrança); `0`
                  quando o tipo só recebeu vendas históricas.
              TotalValue:
                type: number
                description: Total recebido no caixa nesta forma de pagamento em R$.
        PaymentCategorySummary:
          type: array
          description: Total vendido por **categoria** de pagamento (Crédito, Débito, Dinheiro, Pix, Vale, Crédito Loja etc.).
          items:
            type: object
            properties:
              Category:
                type: integer
                description: 'Categoria do pagamento (`Category`). Ex.: `1` Dinheiro, `22` Crédito, `23` Débito, `24` Pix.'
              TypePaymentCategory:
                type: string
                description: Descrição amigável da categoria (`Dinheiro`, `Crédito`, `Débito`, `Pix`, `Vale`, etc.).
              EnableFrenteCaixa:
                type: integer
                enum:
                  - 0
                  - 1
                description: '`1` quando a categoria tem pelo menos um tipo de pagamento habilitado para uso no PDV.'
              TotalValue:
                type: number
                description: Total recebido no caixa nesta categoria em R$.
        InvoiceSummary:
          type: array
          description: Vendas agrupadas por modelo de NF emitida.
          items:
            type: object
            properties:
              NfeModelo:
                type: integer
                nullable: true
                enum:
                  - 55
                  - 65
                  - null
                description: 55=NF-e, 65=NFC-e, `null`=pendente (sem NF emitida).
              TotalValue:
                type: number
                description: Soma dos pedidos do grupo (NFC-e, NF-e ou pendente) em R$.
              Count:
                type: integer
                description: Quantidade de notas.
        ReceiptBase64Encode:
          type: string
          format: byte
          description: >-
            ZPL do recibo "Fechamento de Caixa" (Saldo Anterior + Total por tipo + Reforço + Sangria + Saldo Final).
            Codificado em base64 + cp850.
        ReceiptFiscalBase64Encode:
          type: string
          format: byte
          description: >-
            ZPL do recibo "Resumo Fiscal" (Total NFCe/NFe/Pendente + quantidades + breakdown por categoria de
            pagamento). Base64 + cp850.
    StoreFrontCashierOpenBody:
      type: object
      description: Body de `POST /store-front/cashier/{idbankaccount}/open`. Senha do usuário operador é obrigatória.
      required:
        - Password
      properties:
        InitialBalance:
          type: number
          description: >-
            Valor declarado pelo operador como saldo inicial do caixa em R$. Quando difere em mais de R$ 0,01 do
            `Balance` calculado, gera lançamento "Ajuste abertura de caixa". Default: 0.
        Comments:
          type: string
          nullable: true
          description: Observações sobre a abertura (gravado em `CommentsOpen`).
        Password:
          type: string
          description: Senha do usuário operador (validada via bcrypt contra a senha do usuário).
    StoreFrontCashierOpenResponse:
      type: object
      description: Resposta de `POST /store-front/cashier/{idbankaccount}/open`. Contexto operacional para inicializar o PDV.
      properties:
        IDStoreFrontCashier:
          type: integer
          format: int32
          description: Identificador da sessão criada (ou retomada quando o mesmo operador já tinha o caixa aberto).
        IDBankAccount:
          type: integer
          format: int32
          description: Conta bancária (caixa) aberta.
        IDCompany:
          type: integer
          format: int32
          description: Identificador interno da empresa dona do caixa.
        IDCompanyInvoice:
          type: integer
          format: int32
          nullable: true
          description: >-
            Identificador interno do faturador (empresa responsável pela emissão da NFC-e da venda). `null` quando não
            houver faturador configurado.
        BankNumber:
          type: string
          description: Sempre `'000'` (banco caixinha do PDV).
        RecordTimestampOpen:
          type: string
          format: date-time
          description: Data/hora em que a sessão foi aberta.
        RecordUserCreated:
          type: integer
          format: int32
          description: Identificador do operador que abriu a sessão.
        Login:
          type: string
          description: Login do operador que abriu a sessão.
        UserName:
          type: string
          description: Nome do operador que abriu a sessão.
        IDTypeOrder:
          type: integer
          format: int32
          description: Tipo de pedido padrão do caixa (ou `DefaultFrenteCaixa=1` da empresa quando a conta não tem).
        TypeOrder:
          type: string
          description: Nome do tipo de pedido padrão usado nas vendas (`TypeOrder`).
        IDCompanySalesPolicy:
          type: integer
          format: int32
          description: Política comercial herdada do tipo de pedido.
        CompanySalesPolicy:
          type: string
          description: Política comercial herdada do tipo de pedido (lista de preços + condições aplicadas no PDV).
        IDStockKeepingUnitWarehouse:
          type: integer
          format: int32
          description: Armazém padrão do tipo de pedido.
        WarehouseName:
          type: string
          description: Nome do armazém padrão do tipo de pedido — origem do estoque das vendas do caixa.
        IDStockKeepingUnitDistributionCenter:
          type: integer
          format: int32
          nullable: true
          description: Centro de distribuição do armazém padrão. `null` quando o armazém não estiver vinculado a um CD.
        IssueNFCe:
          type: integer
          enum:
            - 0
            - 1
          description: 1 = o tipo de pedido padrão emite NFCe automaticamente.
    StoreFrontCashierCloseBody:
      type: object
      description: >-
        Body de `POST /store-front/cashier/{idbankaccount}/close`. Quando o `FinalBalance` difere do `Balance`, o front
        exige `Comments` preenchido.
      required:
        - Password
      properties:
        FinalBalance:
          type: number
          description: >-
            Valor apurado pelo operador na contagem física em R$. Diferenças geram lançamento "Ajuste fechamento de
            caixa".
        Comments:
          type: string
          nullable: true
          description: Observações sobre o fechamento (gravado em `CommentsClose`). Obrigatório quando há divergência.
        Password:
          type: string
          description: Senha do usuário operador.
    StoreFrontCashierAdjustBody:
      type: object
      description: Body de `POST /store-front/cashier/{idbankaccount}/adjust`. `Type` determina sangria (2) ou reforço (1).
      required:
        - Type
        - Value
        - Password
      properties:
        Type:
          type: integer
          enum:
            - 1
            - 2
          description: '`1` = Reforço (entrada), `2` = Sangria (saída).'
        Value:
          type: number
          description: Valor em R$ (sempre positivo). Sangria não pode exceder o saldo.
        Comments:
          type: string
          nullable: true
          description: 'Observações (anexadas à descrição da transação: "Reforço: ..." ou "Sangria: ...").'
        Password:
          type: string
          description: Senha do usuário operador.
    StoreFrontCashierOrderTempItem:
      type: object
      description: >-
        Item de `GET /store-front/cashier/{idbankaccount}/order-temp`. Rascunho de pedido em montagem no PDV, persistido
        automaticamente pelo motor de promoções a cada alteração do carrinho.
      properties:
        IDStoreFrontCashierOrderTemp:
          type: integer
          format: int32
          description: Identificador do rascunho — passe para o `DELETE` quando o operador descarta a venda em andamento.
        IDBankAccount:
          type: integer
          format: int32
          description: Conta bancária (caixa) onde o rascunho foi gerado.
        OrderData:
          type: object
          additionalProperties: true
          description: >-
            Estado completo do carrinho em JSON (já parseado): `Items[]`, `Payments[]`, `IDConsumer`, `IDOrderType`,
            `IDCompanySalesPolicy`, `IDSalesman`, etc. Usado pelo PDV para retomar a venda interrompida via
            `startOrderByTemp`.
        RecordTimestamp:
          type: string
          format: date-time
          description: Última atualização do rascunho.
    WebhookLogListItem:
      type: object
      description: >-
        Item de `GET /webhook`. Representa **uma tentativa** de envio de webhook identificada pelo `UUID` da mensagem
        SQS de origem. Em caso de falha, `Attempts` é incrementado a cada nova tentativa e os campos `ResponseData` e
        `Status` refletem o último resultado.
      properties:
        IDWebhookLog:
          type: integer
          format: int32
          description: Identificador da tentativa.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora da primeira tentativa de envio.
        IDCompany:
          type: integer
          format: int32
          description: Identificador da empresa dona da notificação.
        AccountName:
          type: string
          description: Subdomínio da empresa.
        Topic:
          type: string
          maxLength: 45
          description: >-
            Nome técnico do tópico que originou a notificação (`SkuPost`, `OrderStatus`, `InvoiceIssue`,
            `TrackingDelivered`, etc.). Corresponde ao campo `Key` das parametrizações do grupo `Webhook →
            Produto/Pedido/Transporte/...`.
        EndPoint:
          type: string
          maxLength: 200
          description: >-
            URL HTTPS do destino que recebeu o `POST`. Cópia da parametrização `EndPoint` da integração `Webhook` no
            momento do envio.
        PostData:
          type: string
          maxLength: 5000
          description: >-
            JSON serializado enviado no corpo da requisição. Inclui ao menos `Topic`, `AccountName` e identificadores do
            recurso afetado (`IDSku`, `IDOrder`, etc.) além de uma URL relativa para detalhe.
        ResponseData:
          type: string
          maxLength: 5000
          nullable: true
          description: >-
            JSON serializado da resposta do destino. Em sucesso, é o corpo da resposta HTTP. Em erro, é a mensagem de
            erro (`err.response.data` ou `err.cause.reason`).
        Status:
          type: integer
          enum:
            - 0
            - 1
          description: 'Resultado da última tentativa: `1` = sucesso (destino respondeu 2xx), `0` = erro.'
        StatusName:
          type: string
          enum:
            - Sucesso
            - Erro
          description: Texto pronto para exibição derivado de `Status`.
        Attempts:
          type: integer
          nullable: true
          description: Número de tentativas já feitas para esta mensagem. Incrementa a cada nova tentativa via reenfileiramento.
    UserPrivilegeGroupListItem:
      type: object
      description: >-
        Item de `GET /user/privilege-group`. Cabeçalho do perfil — só os dados do grupo, sem a lista de privilégios
        atribuídos.
      properties:
        AccountName:
          type: string
          description: Subdomínio da empresa dona do perfil.
        IDUserPrivilegeGroup:
          type: integer
          format: int32
          description: Identificador do perfil.
        PrivilegeGroupName:
          type: string
          maxLength: 100
          description: Nome do perfil (livre).
        IDCompany:
          type: integer
          format: int32
          description: Identificador da empresa dona do perfil.
        RecordUserCreated:
          type: integer
          format: int32
          description: Identificador do usuário que criou o perfil.
        IsConsumer:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            Quando `1`, o perfil é destinado a **consumidores** (usuários externos com login restrito), e não a usuários
            internos da empresa.
        UserPrivilegeGroupStatus:
          type: integer
          enum:
            - 0
            - 1
          description: 'Situação: `0` = inativo (excluído logicamente), `1` = ativo. A listagem só devolve `1`.'
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora de cadastro.
    UserPrivilegeGroupCreate:
      type: object
      description: >-
        Corpo do `POST /user/privilege-group`. Apenas o nome — o perfil nasce **sem** nenhum privilégio. Use `POST
        /user/privilege-group/{idprivilegegroup}/resource` depois para atribuir os privilégios.
      required:
        - PrivilegeGroupName
      properties:
        PrivilegeGroupName:
          type: string
          maxLength: 100
          description: Nome do perfil. Sem restrição de duplicidade — é possível ter dois perfis com o mesmo nome na mesma empresa.
    UserPrivilegeGroupUpdate:
      type: object
      description: Corpo do `PUT /user/privilege-group/{idprivilegegroup}`. Atualiza apenas o nome.
      required:
        - PrivilegeGroupName
      properties:
        PrivilegeGroupName:
          type: string
          maxLength: 100
          description: Novo nome do perfil.
    UserPrivilegeGroupDetail:
      type: object
      description: >-
        Item de `GET /user/privilege-group/{idprivilegegroup}`. Representa **uma área** do menu
        (`ModuleGroupDescription`) com a lista de módulos do perfil. **Só vêm os módulos/privilégios atribuídos** ao
        perfil — para mostrar os disponíveis (não atribuídos), o frontend cruza com `GET /company/module`.
      properties:
        Module:
          type: array
          description: Módulos do perfil dentro desta área (deserializado pelo sistema a partir do `JSON_OBJECT` da query).
          items:
            type: object
            properties:
              ModuleGroupDescription:
                type: string
                description: 'Nome da área do menu (ex.: `Financeiro`, `Fornecedores`, `Produtos`). Repetido em cada item.'
              ModuleDescription:
                type: string
                description: 'Nome do módulo dentro da área (ex.: `Contas a Pagar`, `Categoria Fornecedores`).'
              IDModule:
                type: integer
                format: int32
                description: Identificador do módulo.
              Privilege:
                type: array
                description: Privilégios deste módulo já atribuídos ao perfil.
                items:
                  type: object
                  properties:
                    UserPrivilege:
                      type: string
                      description: 'Chave técnica do privilégio (ex.: `PrivilegeAccountsPayableView`).'
                    IDUserPrivilege:
                      type: integer
                      format: int32
                      description: Identificador numérico do privilégio. É o valor enviado no `POST .../resource`.
                    PrivilegeDescription:
                      type: string
                      description: 'Nome amigável do privilégio em PT (ex.: `Visualizar contas a pagar`).'
    JobListItem:
      type: object
      description: Item de `GET /job`. Cabeçalho do job, sem a lista de resultados.
      properties:
        IDJob:
          type: integer
          format: int32
          description: Identificador do job.
        AccountName:
          type: string
          description: Subdomínio da empresa.
        IDCompany:
          type: integer
          format: int32
          description: Identificador da empresa.
        IDTypeJob:
          type: integer
          description: Tipo da ação (`IDTypeJob`).
        TypeJob:
          type: string
          description: >-
            Nome amigável do tipo da ação (`TypeJob`). Ex.: `Criar sku/produto`, `Criar Contas a pagar`, `Importar
            extrato OFX`.
        Login:
          type: string
          description: Login do usuário que criou o job.
        RecordUserCreated:
          type: integer
          format: int32
          description: Id do usuário que criou o job.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora em que o job foi criado.
        StartedAt:
          type: string
          format: date-time
          nullable: true
          description: Quando o processamento começou. `null` enquanto não inicia.
        FinishedAt:
          type: string
          format: date-time
          nullable: true
          description: Quando o processamento terminou. `null` enquanto está em andamento.
        RestartedAt:
          type: string
          format: date-time
          nullable: true
          description: Quando o job foi reiniciado, se houve.
        Attempts:
          type: integer
          nullable: true
          description: Número de tentativas de processamento.
        IDFile:
          type: string
          maxLength: 200
          nullable: true
          description: Nome do arquivo armazenado no S3 (em `Temp/`). `null` para tipos que não exigem arquivo.
        FileHash:
          type: string
          maxLength: 45
          nullable: true
          description: >-
            Hash SHA-256 do conteúdo enviado (base64). Usado pelo `POST /job` para evitar duplicação enquanto um job
            idêntico ainda está em processamento.
        Metadata:
          type: string
          maxLength: 1000
          nullable: true
          description: >-
            JSON serializado com metadados específicos do tipo da ação (ex.: `{"IDSupplier":123}` para tabela de frete,
            `{"IDBankAccount":12}` para OFX).
        IDCompanyIntegration:
          type: integer
          nullable: true
          description: 'Integração relacionada, quando o tipo da ação usa uma (ex.: conciliação de adquirente).'
    JobDetail:
      type: object
      description: >-
        Item de `GET /job/{idjob}`. Estende `JobListItem` com a lista paginada de resultados e a URL pré-assinada do
        arquivo original.
      allOf:
        - $ref: '#/components/schemas/JobListItem'
        - type: object
          properties:
            Result:
              type: array
              description: Resultado linha-a-linha do processamento da planilha. Vazio (`[]`) enquanto o job não rodou.
              items:
                type: object
                properties:
                  IDJobsResult:
                    type: integer
                    format: int32
                    description: Identificador da linha de resultado.
                  Sheet:
                    type: string
                    nullable: true
                    description: Nome da aba da planilha (quando há mais de uma).
                  Line:
                    type: integer
                    description: Número da linha da planilha que originou este resultado.
                  Status:
                    type: integer
                    enum:
                      - 0
                      - 1
                    description: '`1` = sucesso, `0` = erro.'
                  StatusName:
                    type: string
                    enum:
                      - Sucesso
                      - Erro
                    description: Texto pronto para exibição derivado de `Status`.
                  Description:
                    type: string
                    nullable: true
                    description: >-
                      Descrição do resultado da linha — para sucesso, descreve a ação executada; para erro, descreve o
                      motivo (ex.: campo obrigatório faltando, valor inválido).
                  ID:
                    type: integer
                    nullable: true
                    description: Id do recurso afetado (SKU criado, pedido criado, conta a pagar criada, etc.).
                  Name:
                    type: string
                    nullable: true
                    description: 'Nome ou identificador externo do recurso afetado (ex.: código do SKU).'
            UrlFile:
              type: string
              format: uri
              nullable: true
              description: >-
                URL pré-assinada do S3 para baixar o arquivo original enviado. Válida por 2 dias. `null` para jobs que
                não tiveram upload.
    JobPostResponse:
      type: object
      description: >-
        Resposta do `POST /job`. O processamento é assíncrono — use o `IDJob` para consultar o resultado em `GET
        /job/{idjob}`.
      properties:
        IDJob:
          type: integer
          format: int32
          description: Identificador do job criado (ou reaproveitado, quando o mesmo arquivo já estava em processamento).
        Message:
          type: string
          enum:
            - Arquivo em processamento, aguardar resposta por email
            - Processo inserido na fila com sucesso
          description: >-
            Mensagem padrão devolvida ao cliente. `Processo inserido na fila com sucesso` é usada apenas pelas rotas
            baseadas em SQS direta (ex.: `POST /sku/{idsku}/cost/recalculate`).
    CompanyIntegrationListItem:
      type: object
      description: Item de `GET /company/integration`. Cabeçalho de uma integração da empresa com o tipo já resolvido.
      properties:
        IDCompanyIntegration:
          type: integer
          format: int32
          description: Identificador da integração.
        IDTypeCompanyIntegration:
          type: integer
          description: >-
            Identificador do tipo (`TypeCompanyIntegration`). Ex.: 10=Mercado Livre, 16=idworks, 50=Correios, 131=Stark
            Bank.
        IDTypeCompanyIntegrationCategory:
          type: integer
          description: >-
            Categoria do tipo: 1=Canal de Venda, 2=Gateway, 3=Transportadora, 4=Adquirente, 9=Banco. Outras: 7=ERP,
            8=WMS, 10=Hub, 14=Plataformas de e-commerce.
        AccountName:
          type: string
          description: Subdomínio da empresa dona da integração.
        CompanyIntegrationName:
          type: string
          maxLength: 500
          description: Nome da integração (livre). Default `Padrão`.
        IntegrationName:
          type: string
          maxLength: 45
          description: Nome amigável do tipo (resolvido do catálogo).
        SalesChannelName:
          type: string
          description: Mesmo que `IntegrationName` — exposto também como nome do canal de venda (para integrações de marketplace).
        IDSalesChannel:
          type: integer
          nullable: true
          description: Identificador do canal de venda associado (quando aplicável).
        IntegrationLogoUrl:
          type: string
          format: uri
          maxLength: 200
          nullable: true
          description: URL do logo do canal/integração (para exibição na lista).
        PathName:
          type: string
          maxLength: 45
          nullable: true
          description: >-
            Nome interno usado para rotear chamadas ao serviço de integração (ex.: `meli`, `magalu`). Vazio para
            integrações que não usam o serviço de integração.
        AuthUrl:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: >-
            Quando `1`, o tipo expõe um fluxo de **autenticação via URL** — a ação **Autenticar Integração** fica
            visível na linha da listagem.
        HubPaymentCustom:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: Flag do tipo indicando se o mapeamento de pagamento do Hub é personalizado.
        Status:
          type: integer
          enum:
            - 0
            - 1
            - 2
            - 3
          description: 'Status atual da integração: `1`=Ativo, `2`=Erro de autenticação, `3`=Não autenticado, `0`=Inativo.'
        ReputationLevel:
          type: string
          nullable: true
          description: >-
            Valor do parâmetro `ReputationLevel` desta integração (quando aplicável). Usado pela UI para colorir a linha
            (`1_red`, `2_orange`, `3_yellow`, `4_yellow`, `5_green`).
    CompanyIntegrationCreate:
      type: object
      description: >-
        Corpo do `POST /company/integration`. Cria a integração com o **mínimo** — só o tipo e um nome. O status inicial
        é derivado do catálogo do tipo. As parametrizações em si são preenchidas depois via `PUT .../parameter`.
      required:
        - IDTypeCompanyIntegration
        - CompanyIntegrationName
      properties:
        IDTypeCompanyIntegration:
          type: integer
          description: Identificador do tipo de integração (`TypeCompanyIntegration`). Precisa existir no catálogo.
        CompanyIntegrationName:
          type: string
          maxLength: 500
          description: >-
            Nome livre da integração. Útil quando a empresa tem mais de uma instância do mesmo tipo (ex.: duas contas de
            Mercado Livre).
    CompanyIntegrationUpdate:
      type: object
      description: >-
        Corpo do `PUT /company/integration/{idcompanyintegration}`. Edita apenas nome e status. Parametrizações são
        editadas em `PUT .../parameter`.
      properties:
        CompanyIntegrationName:
          type: string
          maxLength: 500
          description: Novo nome.
        Status:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            Novo status. Use `1` para reativar uma integração que estava inativa, ou `0` para inativar (a inativação
            completa, com limpeza de Hub e parametrizações, é feita pelo `DELETE`).
    CompanyIntegrationParameter:
      type: object
      description: >-
        Parametrização da integração (linha de `CompanyParameters` cruzada com a definição em `TypeCompanyParameters`).
        Devolvida pelo `GET /company/integration/{idcompanyintegration}` e usada para renderizar a tela de configuração.
      properties:
        IDTypeCompanyIntegration:
          type: integer
          description: Identificador do tipo da integração à qual esta parametrização pertence.
        IDTypeCompanyParameters:
          type: integer
          description: Identificador da parametrização no catálogo (`TypeCompanyParameters`).
        Key:
          type: string
          maxLength: 100
          description: 'Chave técnica da parametrização (ex.: `EndPoint`, `HeaderKeyAuth`, `GnreIDTypeDocument`).'
        KeyName:
          type: string
          maxLength: 100
          nullable: true
          description: 'Nome amigável em PT (ex.: `Endpoint / URL`, `Tipo de documento para criar contas a pagar GNRE operação`).'
        Description:
          type: string
          maxLength: 1000
          nullable: true
          description: Texto explicativo da parametrização.
        Type:
          type: string
          description: >-
            Tipo de campo: `string`, `password`, `boolean`, `checkbox`, `list`, `multi_list`, `string_copy` (texto
            pré-computado para o usuário copiar), `url_get` (URL gerada dinamicamente), `hidden` (não devolvido), etc.
        Required:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: Quando `1`, o campo é obrigatório.
        ParameterOrder:
          type: integer
          nullable: true
          description: Ordem de exibição dentro do grupo.
        IDTypeCompanyParametersGroup:
          type: integer
          description: Grupo lógico da parametrização (`TypeCompanyParametersGroup`).
        TypeCompanyParametersGroup:
          type: string
          description: >-
            Nome do grupo lógico (ex.: `Credenciais de Acesso`, `Fiscal Produto`, `Produto`, `Pedido`, `Transporte`,
            `GNRE`, `Webhook`).
        Value:
          type: string
          nullable: true
          description: >-
            Valor atual gravado. Para tipos `string_copy` e `url_get`, o sistema pode substituir por um valor calculado
            (ex.: URL de webhook personalizada para a empresa, com tokens embutidos). Para flags `TagBusiness` e
            `TagSellerWarehouse`, retorna `Sim`/`Não` em vez do `1`/`0` cru.
        List:
          type: array
          description: >-
            Lista de opções (apenas para `Type` `list` ou `multi_list`). Cada item tem `Value` e `Label`. Algumas chaves
            específicas (ex.: `IDCompanyInvoice`, `GnreIDTypeDocument`, `IDBankAccount`,
            `IDTypeAccountPayableReceivable`) trazem aqui a lista correspondente da empresa.


            Valores possíveis: itens de tabelas-tipo (`NfModFrete`, `CorreiosDiretoria`, etc.), planos de contas da
            empresa, contas bancárias da empresa, tipos de documento etc.)
          items:
            type: object
            properties:
              Value:
                type: string
                description: >-
                  Valor que deve ser gravado no campo `Value` ao escolher esta opção (ex.: `1`, `IDCompanyInvoice=123`,
                  código de banco).
              Label:
                type: string
                description: 'Texto exibido na lista para o usuário (ex.: `Mercado Livre`, `Faturamento Matriz`, `Banco do Brasil`).'
    CompanyParameterValue:
      type: object
      description: Item do body de `PUT /company/integration/{idcompanyintegration}/parameter`.
      required:
        - Key
      properties:
        Key:
          type: string
          description: Chave técnica da parametrização (deve existir em `TypeCompanyParameters` para o tipo da integração).
        Value:
          nullable: true
          description: >-
            Novo valor. Aceita string, número, booleano — convertido para string e gravado em `Value`. Espaços nas
            pontas são removidos (`trim`). `null` ou omitido grava `NULL`.
          type: string
    ProductionListItem:
      type: object
      description: Item de `GET /sku/production`. Cabeçalho da OP com SKU produzido, status, armazém e pedido vinculado.
      properties:
        IDStockKeepingUnitProduction:
          type: integer
          format: int32
          description: Identificador da ordem de produção.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora de cadastro.
        RecordUserCreated:
          type: string
          description: Login do usuário que criou a OP.
        IDSku:
          type: integer
          format: int32
          description: Id do SKU produzido.
        IDSkuCompany:
          type: string
          description: Código externo do SKU.
        SkuName:
          type: string
          description: Nome do SKU principal da ordem.
        Quantity:
          type: number
          description: Quantidade a produzir (decimal 10,2).
        DateEstimated:
          type: string
          format: date
          nullable: true
          description: Data estimada de conclusão.
        IDTypeStatusSkuProduction:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
          description: 'Status da etapa de produção: `1` Finalizado, `2` Aberto, `3` Em andamento, `4` Cancelado.'
        TypeStatusSkuProduction:
          type: string
          enum:
            - Finalizado
            - Aberto
            - Em andamento
            - Cancelado
          description: Texto pronto para exibição.
        Comments:
          type: string
          maxLength: 1000
          nullable: true
          description: Observações livres da ordem.
        IDOrder:
          type: integer
          nullable: true
          description: Pedido vinculado (quando a OP foi criada a partir de um pedido).
        Order:
          type: string
          nullable: true
          description: Número externo do pedido.
        OrderFrom:
          type: string
          nullable: true
          description: Canais de origem do pedido (concatenado).
        IDStockKeepingUnitWarehouse:
          type: integer
          description: Armazém de onde os insumos são consumidos e onde o produto final fica disponível.
        WarehouseName:
          type: string
          description: Nome do depósito de destino da produção.
        IDStockKeepingUnitDistributionCenter:
          type: integer
          nullable: true
          description: Identificador do centro de distribuição associado ao depósito.
        IDPurchase:
          type: integer
          nullable: true
          description: Recebimento gerado ao finalizar.
        MainImageURL:
          type: string
          nullable: true
          description: URL da imagem principal do SKU produzido (com sufixo `-thumbnail`).
        AccountName:
          type: string
          description: Conta (subdomínio) da empresa.
    ProductionDetail:
      type: object
      description: >-
        Item de `GET /sku/production/{idstockkeepingunitproduction}`. Cabeçalho + custo total + itens consumidos +
        etapas com tempo gasto e decorrido.
      allOf:
        - $ref: '#/components/schemas/ProductionListItem'
        - type: object
          properties:
            ValueCostTotal:
              type: number
              description: Soma de `ValueCostTotal` dos movimentos de consumo.
            TimeSpentTotal:
              type: string
              description: Soma de `TimeSpent` lançado nas etapas. Formato `HH:MM:SS`.
            TimeElapsedTotal:
              type: string
              description: Soma de (`RecordTimestampEnd` - `RecordTimestampStart`) das etapas. Formato `HH:MM:SS`.
            Items:
              type: array
              description: Insumos/matérias-primas consumidos.
              items:
                type: object
                properties:
                  IDSkuMovement:
                    type: integer
                    description: Identificador da movimentação de estoque associada à ordem de produção.
                  IDSku:
                    type: integer
                    description: Identificador do SKU produzido.
                  IDSkuCompany:
                    type: string
                    description: Código do SKU na empresa.
                  SkuName:
                    type: string
                    description: Nome do SKU produzido.
                  Quantity:
                    type: number
                    description: Quantidade produzida.
                  ValueCostTotal:
                    type: number
                    description: Custo total da produção em R$.
                  ValueCostUnit:
                    type: number
                    description: '`ValueCostTotal / Quantity`, 4 casas.'
                  IDStockKeepingUnitWarehouse:
                    type: integer
                    description: Armazém de destino da produção.
                  WarehouseName:
                    type: string
                    description: Nome do armazém de destino.
                  MainImageURL:
                    type: string
                    nullable: true
                    description: URL da imagem principal do SKU produzido.
                  Comments:
                    type: string
                    nullable: true
                    description: Observações da ordem de produção.
                  AccountName:
                    type: string
                    description: Conta (prefixo) da empresa.
            StockKeepingUnitProductionLineSteps:
              type: array
              description: Etapas da OP, ordenadas por `ProductionLineStepOrder`.
              items:
                type: object
                properties:
                  IDStockKeepingUnitProductionSteps:
                    type: integer
                    description: Identificador da etapa da ordem de produção.
                  IDStockKeepingUnitProductionLineSteps:
                    type: integer
                    description: Identificador da etapa na linha de produção.
                  RecordTimestamp:
                    type: string
                    format: date-time
                    description: Data e hora de criação da ordem de produção.
                  ProductionLineStepName:
                    type: string
                    description: Nome da etapa da linha de produção.
                  ProductionLineStepOrder:
                    type: number
                    description: Ordem (sequência) da etapa na linha de produção.
                  IDTypeStatusSkuProduction:
                    type: integer
                    enum:
                      - 1
                      - 2
                      - 3
                      - 4
                    description: 'Status da etapa de produção: `1` Finalizado, `2` Aberto, `3` Em andamento, `4` Cancelado.'
                  TypeStatusSkuProduction:
                    type: string
                    description: Descrição do status da etapa.
                  TimeSpent:
                    type: string
                    nullable: true
                    description: '`HH:MM:SS` — informado pelo operador.'
                  TimeElapsed:
                    type: string
                    nullable: true
                    description: '`HH:MM:SS` — diferença entre `RecordTimestampStart` e `RecordTimestampEnd`.'
                  RecordTimestampStart:
                    type: string
                    format: date-time
                    nullable: true
                    description: Data e hora de início da etapa. `null` enquanto não iniciada.
                  RecordTimestampEnd:
                    type: string
                    format: date-time
                    nullable: true
                    description: Data e hora de conclusão da etapa. `null` enquanto não finalizada.
                  RecordUserCreatedEnd:
                    type: string
                    nullable: true
                    description: Login do usuário que finalizou a etapa.
                  UserNameEnd:
                    type: string
                    nullable: true
                    description: Nome do usuário que finalizou a etapa.
    ProductionCreate:
      type: object
      description: Corpo do `POST /sku/production`.
      required:
        - IDSku
        - Quantity
        - IDStockKeepingUnitWarehouse
      properties:
        IDSku:
          type: integer
          description: SKU a produzir. Precisa ter `OwnProduction = 1` no cadastro do SKU.
        Quantity:
          type: number
          description: Quantidade a produzir. Os componentes do kit do SKU são consumidos proporcionalmente.
        IDStockKeepingUnitWarehouse:
          type: integer
          description: Armazém de onde os insumos são consumidos e onde o produto final fica disponível.
        DateEstimated:
          type: string
          format: date
          nullable: true
          description: Data estimada de conclusão.
        Comments:
          type: string
          maxLength: 1000
          nullable: true
          description: Observações livres da ordem de produção.
        IDOrder:
          type: integer
          nullable: true
          description: Pedido que originou a OP (opcional).
    ProductionUpdate:
      type: object
      description: Corpo do `PUT /sku/production/{idstockkeepingunitproduction}`. Apenas campos enviados são atualizados.
      properties:
        DateEstimated:
          type: string
          format: date
          nullable: true
          description: Data estimada de conclusão da ordem de produção.
        Comments:
          type: string
          nullable: true
          description: Observações livres.
        IDTypeStatusSkuProduction:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
          description: 'Status da etapa de produção: `1` Finalizado, `2` Aberto, `3` Em andamento, `4` Cancelado.'
        IDOrder:
          type: integer
          nullable: true
          description: Identificador do pedido de venda que originou esta ordem de produção (quando produção sob demanda).
    ProductionFinish:
      type: object
      description: Corpo do `POST /sku/production/{idstockkeepingunitproduction}/finish`. Todos opcionais.
      properties:
        IDPurchase:
          type: integer
          nullable: true
          description: Quando informado, lança o produto produzido neste Recebimento existente em vez de criar um novo.
        IDStockKeepingUnitDistributionCenter:
          type: integer
          nullable: true
          description: 'Centro de distribuição do recebimento. Default: o do armazém da OP.'
    ProductionFinishResponse:
      type: array
      description: >-
        Resposta de `POST /sku/production/{idstockkeepingunitproduction}/finish` — detalhe do Recebimento gerado (mesmo
        formato do `GET /purchase/{idpurchase}`).
      items:
        type: object
        additionalProperties: true
    ProductionSkuAdd:
      type: object
      description: Corpo do `POST /sku/production/{idstockkeepingunitproduction}/sku`.
      required:
        - IDSku
        - Quantity
      properties:
        IDSku:
          type: integer
          description: SKU a consumir (tipo 3=SKU, 6=matéria-prima, 7=variante).
        Quantity:
          type: number
          description: Quantidade do SKU a produzir nesta linha da ordem.
        IDStockKeepingUnitWarehouse:
          type: integer
          nullable: true
          description: 'Armazém do consumo. Default: o armazém da OP.'
        Comments:
          type: string
          nullable: true
          description: Observações livres do item de produção.
    ProductionSkuUpdate:
      type: object
      description: >-
        Corpo do `PUT /sku/production/{idstockkeepingunitproduction}/sku/{idskumovement}`. Apenas campos enviados são
        atualizados.
      properties:
        Quantity:
          type: number
          description: Quantidade do SKU a produzir nesta linha.
        IDStockKeepingUnitWarehouse:
          type: integer
          description: Depósito de destino do item produzido.
        ValueCostTotal:
          type: number
          description: Permite ajustar manualmente o custo total da linha.
        Comments:
          type: string
          nullable: true
          description: Observações livres do item de produção.
    ProductionStepUpdate:
      type: object
      description: Corpo do `PUT /sku/production/{idstockkeepingunitproduction}/steps/{idstockkeepingunitproductionsteps}`.
      required:
        - IDTypeStatusSkuProduction
      properties:
        IDTypeStatusSkuProduction:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
          description: 'Status da etapa de produção: `1` Finalizado, `2` Aberto, `3` Em andamento, `4` Cancelado.'
        TimeSpent:
          type: string
          nullable: true
          description: >-
            Tempo gasto na etapa, formato `HH:MM:SS`. Informado pelo operador para registrar o tempo efetivamente
            trabalhado (diferente do tempo decorrido entre início e fim).
    ProductionLineListItem:
      type: object
      description: Item de `GET /sku/production/line`. Linha de produção com suas etapas.
      properties:
        IDStockKeepingUnitProductionLine:
          type: integer
          description: Identificador da linha de produção.
        ProductionLineName:
          type: string
          maxLength: 100
          description: Nome da linha de produção.
        Default:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` = é a linha padrão da empresa (usada quando o SKU não tem linha vinculada).'
        Status:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` = ativa.'
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora de criação.
        AccountName:
          type: string
          description: Conta (subdomínio) da empresa.
        QtySteps:
          type: integer
          description: Quantidade de etapas cadastradas na linha.
        StockKeepingUnitProductionLineSteps:
          type: array
          description: Etapas ordenadas por `ProductionLineStepOrder`.
          items:
            type: object
            properties:
              IDStockKeepingUnitProductionLineSteps:
                type: integer
                description: Identificador da etapa da linha de produção.
              ProductionLineStepName:
                type: string
                maxLength: 100
                description: 'Nome da etapa (ex.: Corte, Costura, Embalagem).'
              ProductionLineStepOrder:
                type: number
                description: Decimal (3,1) — permite inserir entre etapas existentes com `1.5`.
    ProductionLineCreate:
      type: object
      description: Corpo do `POST /sku/production/line`.
      required:
        - ProductionLineName
      properties:
        ProductionLineName:
          type: string
          maxLength: 100
          description: Nome da linha de produção.
        Default:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` = marca como padrão (desmarca a anterior).'
    ProductionLineUpdate:
      type: object
      description: Corpo do `PUT /sku/production/line/{idstockkeepingunitproductionline}`.
      properties:
        ProductionLineName:
          type: string
          maxLength: 100
          description: Nome da linha de produção.
        Default:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` define esta linha como padrão (apenas uma linha por empresa pode ser padrão).'
    ProductionLineStepCreate:
      type: object
      description: Corpo dos endpoints `POST` e `PUT` de etapas de linha.
      required:
        - ProductionLineStepName
        - ProductionLineStepOrder
      properties:
        ProductionLineStepName:
          type: string
          maxLength: 100
          description: 'Nome da etapa da linha de produção (ex.: Corte, Costura, Acabamento).'
        ProductionLineStepOrder:
          type: number
          description: Decimal (3,1) — define a ordem dentro da linha.
    TrackingTemplateListItem:
      type: object
      description: >-
        Item de `GET /carrier/tracking-template`. Cada linha é uma regra de disparo de mensagem amarrada a um status de
        tracking.
      properties:
        IDCarrierTrackingTemplate:
          type: integer
          format: int32
          description: Identificador do template de rastreio.
        AccountName:
          type: string
          description: Subdomínio da empresa dona do template.
        CarrierTrackingTemplateName:
          type: string
          maxLength: 100
          nullable: true
          description: 'Nome amigável da regra (ex.: `Comunicado de envio`, `Aviso de entrega`).'
        CarrierTrackingTemplateStatus:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` = ativo (dispara); `0` = inativo (não dispara).'
        IDTypeCarrierTrackingTemplate:
          type: integer
          enum:
            - 1
            - 2
          description: '`1` = e-mail; `2` = WhatsApp/Webhook.'
        TypeCarrierTrackingTemplate:
          type: string
          enum:
            - e-mail
            - WhatsApp
          description: Texto resolvido do tipo.
        IDStatusTracking:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 7
            - 8
          description: >-
            Macro status de tracking que dispara o template. 1=Finalizado, 2=Em andamento, 3=Atenção, 4=Não iniciado,
            5=Saiu para entrega, 6=Extraviado, 7=Devolvido, 8=Postado.
        StatusTracking:
          type: string
          description: Texto resolvido (Finalizado, Em andamento, Atenção, etc.).
        EmailTitle:
          type: string
          maxLength: 150
          description: >-
            Assunto do e-mail. Aceita variáveis (`{{IDOrder}}`, `{{ConsumerNameCorporateName}}`, etc.). Para tipo
            WhatsApp/Webhook, pode ficar vazio.
        HTML:
          type: string
          description: >-
            Corpo do template (HTML para e-mail; texto/JSON para WhatsApp/Webhook). Aceita variáveis substituídas no
            momento do disparo.
        CC:
          type: string
          maxLength: 200
          nullable: true
          description: Lista de e-mails em **CC**, separados por vírgula.
        CCO:
          type: string
          maxLength: 200
          nullable: true
          description: Lista de e-mails em **CCO**, separados por vírgula.
        IDCompanyIntegration:
          type: integer
          nullable: true
          description: >-
            Integração que entrega a mensagem (provedor de e-mail ou de WhatsApp configurado em Configurações →
            Integrações).
        CompanyIntegration:
          type: string
          nullable: true
          description: Texto resolvido `IntegrationName - CompanyIntegrationName` da integração de entrega.
        IDCompanyIntegrationOrderList:
          type: array
          items:
            type: string
          description: >-
            Lista de identificadores das integrações de origem do pedido para as quais o template dispara. Vazio =
            dispara para todas. Armazenado no banco como string separada por vírgula e exposto como array.
        IDTypeOrderList:
          type: array
          items:
            type: string
          description: Lista de identificadores dos tipos de pedido para os quais o template dispara. Vazio = dispara para todos.
    TrackingTemplateCreate:
      type: object
      description: Corpo do `POST /carrier/tracking-template`.
      required:
        - IDStatusTracking
        - HTML
        - IDTypeCarrierTrackingTemplate
      properties:
        CarrierTrackingTemplateName:
          type: string
          maxLength: 100
          nullable: true
          description: Nome amigável da regra.
        IDTypeCarrierTrackingTemplate:
          type: integer
          enum:
            - 1
            - 2
          description: '`1` = e-mail; `2` = WhatsApp/Webhook. Default `1`.'
        IDStatusTracking:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 7
            - 8
          description: Macro status que dispara o template.
        HTML:
          type: string
          description: Corpo do template. HTML para e-mail; texto/JSON para WhatsApp/Webhook.
        EmailTitle:
          type: string
          maxLength: 150
          nullable: true
          description: Assunto. Obrigatório para e-mail.
        CC:
          type: string
          maxLength: 200
          nullable: true
          description: E-mails em CC separados por vírgula. Cada item validado contra regex de e-mail.
        CCO:
          type: string
          maxLength: 200
          nullable: true
          description: E-mails em CCO separados por vírgula. Mesma validação.
        IDCompanyIntegration:
          type: integer
          nullable: true
          description: Integração de entrega (provedor de e-mail/WhatsApp). Validada contra a empresa.
        IDCompanyIntegrationOrderList:
          oneOf:
            - type: array
              items:
                type: integer
            - type: string
          description: >-
            Restringe o disparo às integrações de origem do pedido informadas. Aceita array de ids ou string separada
            por vírgula. Vazio = todas. Validado contra `Show = 1`.
        IDTypeOrderList:
          oneOf:
            - type: array
              items:
                type: integer
            - type: string
          description: >-
            Restringe o disparo aos tipos de pedido informados. Aceita array de ids ou string separada por vírgula.
            Vazio = todos. Validado contra `Status = 1`.
        CarrierTrackingTemplateStatus:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` = ativo (dispara); `0` = inativo. Default `1`.'
    TrackingTemplateUpdate:
      type: object
      description: >-
        Corpo do `PUT /carrier/tracking-template/{idcarriertrackingtemplate}`. Todos os campos opcionais — atualização
        parcial.
      properties:
        CarrierTrackingTemplateName:
          type: string
          maxLength: 100
          nullable: true
          description: Nome amigável da regra.
        IDTypeCarrierTrackingTemplate:
          type: integer
          enum:
            - 1
            - 2
          description: '`1` = e-mail; `2` = WhatsApp/Webhook. Default `1`.'
        IDStatusTracking:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 7
            - 8
          description: Macro status que dispara o template.
        HTML:
          type: string
          description: Corpo do template. HTML para e-mail; texto/JSON para WhatsApp/Webhook.
        EmailTitle:
          type: string
          maxLength: 150
          nullable: true
          description: Assunto. Obrigatório para e-mail.
        CC:
          type: string
          maxLength: 200
          nullable: true
          description: E-mails em CC separados por vírgula. Cada item validado contra regex de e-mail.
        CCO:
          type: string
          maxLength: 200
          nullable: true
          description: E-mails em CCO separados por vírgula. Mesma validação.
        IDCompanyIntegration:
          type: integer
          nullable: true
          description: Integração de entrega (provedor de e-mail/WhatsApp). Validada contra a empresa.
        IDCompanyIntegrationOrderList:
          oneOf:
            - type: array
              items:
                type: integer
            - type: string
          description: >-
            Restringe o disparo às integrações de origem do pedido informadas. Aceita array de ids ou string separada
            por vírgula. Vazio = todas. Validado contra `Show = 1`.
        IDTypeOrderList:
          oneOf:
            - type: array
              items:
                type: integer
            - type: string
          description: >-
            Restringe o disparo aos tipos de pedido informados. Aceita array de ids ou string separada por vírgula.
            Vazio = todos. Validado contra `Status = 1`.
        CarrierTrackingTemplateStatus:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` = ativo (dispara); `0` = inativo. Default `1`.'
    CarrierQuotationActionRuleEnum:
      type: integer
      description: >-
        Tipo de ação aplicada quando todas as condições da regra são atendidas.


        - `1` — Adicionar X dias no prazo (`ActionValue` = dias, inteiro)

        - `2` — Alterar o preço R$ (`ActionValue` = valor em reais a somar/subtrair ao preço cotado)

        - `3` — Alterar o preço X% (`ActionValue` = percentual sobre o preço cotado)

        - `5` — Adicionar ao preço um % do valor da nota X% (`ActionValue` = percentual aplicado sobre `OrderValue`)

        - `6` — Fixar o preço em (`ActionValue` = valor em reais que sobrescreve o frete cotado)

        - `7` — Fixar o preço em uma % do valor da nota (`ActionValue` = percentual sobre `OrderValue`)

        - `9` — Excluir transportadoras selecionadas (sem `ActionValue`; exige condição 3 — `Transportadora`)

        - `10` — Fixar o preço unitário R$ X (`ActionValue` = preço por item, multiplicado pela quantidade)

        - `13` — Adicionar prazo de manuseio do CD (`ActionValue` = dias úteis somados ao prazo)


        Ações inativas (só aparecem em regras legadas): `4` (Frete proporcional para mais barato), `8` (Excluir), `11`
        (Frete grátis para o mais barato), `12` (Nunca aplicar frete grátis), `14` (Alterar o prazo por intervalo de
        janela fixa).
      enum:
        - 1
        - 2
        - 3
        - 4
        - 5
        - 6
        - 7
        - 8
        - 9
        - 10
        - 11
        - 12
        - 13
        - 14
    CarrierQuotationConditionRuleEnum:
      type: integer
      description: >-
        Tipo de condição. Todas as condições marcadas precisam ser verdadeiras (AND) para a regra disparar. Formato de
        `ConditionValue` (sempre array de strings):


        - `1` — Estado/Região: cada item é `UF` ou `UFCAPITAL`/`UFINTERIOR` (ex.: `SP`, `SPCAPITAL`).

        - `2` — CEP Destino: cada item é faixa `<CEPDe>|<CEPAté>` (8 dígitos cada, sem hífen).

        - `3` — Transportadora: cada item é `IDSupplier` (apenas fornecedores com `IDTypeSupplier=2` da empresa).

        - `4` — Valor do pedido: cada item é faixa `<De>|<Até>` em reais (ponto decimal, sem R$).

        - `6` — Integração: cada item é `IDCompanyIntegration` da empresa.

        - `7` — Peso (kg): cada item é faixa `<De>|<Até>`.

        - `8` — SKUs iguais a: cada item é `<IDSku>|<descrição>`.

        - `9` — SKUs diferentes de: cada item é `<IDSku>|<descrição>`.

        - `10` — CEP Origem: cada item é faixa `<CEPDe>|<CEPAté>`.


        Condição inativa no banco: `5` (Comparação preço de custo).
      enum:
        - 1
        - 2
        - 3
        - 4
        - 5
        - 6
        - 7
        - 8
        - 9
        - 10
    CarrierQuotationConditionPayload:
      type: object
      description: Uma condição da regra. O sistema valida `ConditionValue` de acordo com `IDTypeCarrierQuotationConditionRule`.
      required:
        - IDTypeCarrierQuotationConditionRule
        - ConditionValue
      properties:
        IDTypeCarrierQuotationConditionRule:
          $ref: '#/components/schemas/CarrierQuotationConditionRuleEnum'
          description: >-
            Tipo da condição a aplicar na regra: `1` Estado/Região, `2` CEP Destino, `3` Transportadora, `4` Valor do
            pedido, `6` Integração, `7` Peso (kg), `8` Skus iguais a, `9` Skus diferentes de, `10` CEP Origem.
        ConditionValue:
          type: array
          items:
            type: string
          description: |-
            Lista de valores aceitos por esta condição. O formato depende do tipo:
            - 1 (Estado/Região): `["SP", "SPCAPITAL", "RJINTERIOR"]`
            - 2 (CEP Destino), 10 (CEP Origem): `["01000000|01999999", "02000000|02999999"]`
            - 3 (Transportadora): `["42", "108"]` (lista de `IDSupplier`)
            - 4 (Valor do pedido): `["0|100.00", "100.01|500.00"]`
            - 6 (Integração): `["15", "22"]` (lista de `IDCompanyIntegration`)
            - 7 (Peso): `["0|5", "5.001|10"]`
            - 8/9 (SKUs): `["12345|Camiseta polo M azul", "12346|Camiseta polo G azul"]`
    CarrierQuotationConditionItem:
      type: object
      description: Condição da regra como devolvida pelo GET/list — `ConditionValue` já vem quebrado em vetor pelo separador `,`.
      properties:
        IDCarrierQuotationRuleCondition:
          type: integer
          description: Identificador da condição da regra de cotação de frete.
        IDTypeCarrierQuotationConditionRule:
          $ref: '#/components/schemas/CarrierQuotationConditionRuleEnum'
          description: >-
            Tipo da condição: `1` Estado/Região (UF de destino), `2` CEP Destino, `3` Transportadora, `4` Valor do
            pedido, `6` Integração (canal de venda), `7` Peso (kg), `8` Skus iguais a (lista de SKUs incluídos), `9`
            Skus diferentes de (lista de SKUs excluídos), `10` CEP Origem.
        TypeCarrierQuotationConditionRule:
          type: string
          description: 'Nome amigável da condição (ex.: `Estado/Região`, `CEP Destino`, `Transportadora`).'
        ConditionValue:
          type: array
          items:
            type: string
          description: >-
            Valores da condição. O formato depende de `IDTypeCarrierQuotationConditionRule`: lista de strings para tipos
            categóricos (UFs, transportadoras, integrações, SKUs); lista com par `[min, max]` para tipos de faixa (valor
            do pedido, peso, CEP).
    CarrierQuotationRuleLogItem:
      type: object
      description: Entrada do histórico de alterações da regra.
      properties:
        IDCarrierQuotationRuleLog:
          type: integer
          description: >-
            Identificador do registro de histórico (log) da regra de cotação — cada criação/alteração da regra gera uma
            linha.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora em que o registro de histórico foi gerado.
        RecordUserCreated:
          type: integer
          description: '`IDUser` que fez a alteração.'
        Login:
          type: string
          description: Login do usuário.
        Data:
          type: string
          description: |-
            JSON serializado com as mudanças. Cada chave é o nome do campo alterado e o valor segue um destes formatos:
            - `"DE: <antigo> PARA: <novo>"` — alteração de campo do cabeçalho.
            - `"<NomeCondicao>_Adicionado": "<valores>"` — condição adicionada.
            - `"<NomeCondicao>_Removido": "<valores>"` — condição removida.
    CarrierQuotationRuleListItem:
      type: object
      description: Item de `GET /carrier/quotation/rule`.
      properties:
        AccountName:
          type: string
          description: Subdomínio da empresa dona da regra.
        IDCarrierQuotationRule:
          type: integer
          description: Identificador da regra de simulação de frete.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data/hora de criação da regra.
        CarrierQuotationRuleName:
          type: string
          description: Nome amigável da regra (exibido na grid).
        Priority:
          type: integer
          minimum: 1
          description: Ordem de execução. Menor valor é avaliado primeiro.
        Status:
          type: integer
          enum:
            - 0
            - 1
          description: '`1`=Ativo, `0`=Inativo. (`2`=Excluído fica oculto na listagem.)'
        DateFrom:
          type: string
          format: date
          description: Início da vigência. `1900-01-01` quando vigência foi desligada ("sempre vigente").
        DateTo:
          type: string
          format: date
          description: Fim da vigência. `4000-01-01` quando vigência foi desligada.
        IDTypeCarrierQuotationActionRule:
          $ref: '#/components/schemas/CarrierQuotationActionRuleEnum'
          description: >-
            Tipo de ação aplicada quando todas as condições da regra são atendidas. Lista de valores em
            `CarrierQuotationActionRuleEnum`.
        TypeCarrierQuotationActionRule:
          type: string
          description: Nome amigável da ação.
        ActionValue:
          type: string
          nullable: true
          description: >-
            Valor associado à ação. Para ações de valor em R$ (`2`, `6`, `10`), vem como decimal em string (`"15.50"`);
            para `%` (`3`, `5`, `7`), valor percentual (`"10"` = 10%); para prazo (`1`, `13`), inteiro de dias (`"2"`);
            para ação `9` (Excluir transportadoras), vem `null`.
        ConditionsRules:
          type: array
          items:
            $ref: '#/components/schemas/CarrierQuotationConditionItem'
          description: >-
            Lista das condições (`AND` entre elas) que precisam ser verdadeiras para a regra disparar. Cada item segue
            `CarrierQuotationConditionItem`.
        ConditionNames:
          type: string
          description: Nomes das condições concatenados por vírgula (usado na grid).
        CarrierQuotationRuleLog:
          type: array
          items:
            $ref: '#/components/schemas/CarrierQuotationRuleLogItem'
          description: Histórico de alterações da regra. Cada entrada segue `CarrierQuotationRuleLogItem`.
    CarrierQuotationRuleDetail:
      allOf:
        - $ref: '#/components/schemas/CarrierQuotationRuleListItem'
      description: >-
        Mesmo formato da listagem — o detalhe (`GET /carrier/quotation/rule/{idcarrierquotationrule}`) e o retorno do
        POST/PUT devolvem um array com 1 item.
    CarrierQuotationRuleCreate:
      type: object
      description: Corpo do `POST /carrier/quotation/rule`. Toda regra precisa de pelo menos 1 condição.
      required:
        - CarrierQuotationRuleName
        - Priority
        - IDTypeCarrierQuotationActionRule
        - Conditions
      properties:
        CarrierQuotationRuleName:
          type: string
          description: Nome da regra (apresentado na grid).
        Priority:
          type: integer
          minimum: 1
          description: Ordem de execução. Menor valor é avaliado primeiro. UI sugere 1, 2, 3...
        Status:
          type: integer
          enum:
            - 0
            - 1
          description: '`1`=Ativo (default), `0`=Inativo.'
        DateFrom:
          type: string
          format: date
          description: >-
            Início da vigência (`YYYY-MM-DD`). Quando a UI desliga o switch "Possui vigência", o frontend envia
            `1900-01-01`.
        DateTo:
          type: string
          format: date
          description: >-
            Fim da vigência (`YYYY-MM-DD`). Quando o switch "Possui vigência" é desligado, o frontend envia
            `4000-01-01`.
        IDTypeCarrierQuotationActionRule:
          $ref: '#/components/schemas/CarrierQuotationActionRuleEnum'
          description: >-
            Tipo de ação aplicada quando todas as condições da regra são atendidas. Valores em
            `CarrierQuotationActionRuleEnum`.
        ActionValue:
          type: string
          nullable: true
          description: Valor da ação. Para ação `9` (Excluir transportadoras), enviar `null` ou omitir.
        Conditions:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/CarrierQuotationConditionPayload'
          description: >-
            Lista de condições (`AND` entre elas) — toda regra precisa de pelo menos uma. Cada item segue
            `CarrierQuotationConditionPayload`.
    CarrierQuotationVolumeItem:
      type: object
      description: >-
        Um volume/produto do array `Quotations` do POST. Para **Volume** (`IDTypeSimulation=2`), envie dimensões
        diretamente. Para **Produto** (`IDTypeSimulation=1`), o frontend já multiplica os campos pela quantidade antes
        de chamar a API — o sistema recebe só o resultado.
      required:
        - Weight
        - Height
        - Width
        - Length
      properties:
        Weight:
          type: number
          format: double
          minimum: 0.001
          description: Peso em quilos. A soma dos pesos vira o peso total (`weight` no sistema).
        Height:
          type: number
          format: double
          description: Altura em centímetros. Sistema pega o **maior** valor entre os volumes.
        Width:
          type: number
          format: double
          description: Largura em centímetros. Sistema **soma** os valores entre os volumes.
        Length:
          type: number
          format: double
          description: Comprimento em centímetros. Sistema pega o **maior** valor entre os volumes.
        ValueInvoice:
          type: number
          format: double
          nullable: true
          description: >-
            Valor da nota fiscal em reais. Usado para calcular Gris, Advalorem, Tde, taxas de seguro e outras taxas
            percentuais. Soma de todos os volumes vira `ValueInvoice` da simulação.
        Quantity:
          type: number
          format: double
          nullable: true
          description: >-
            Quantidade do produto. Só relevante quando `IDTypeSimulation=1` — neste caso o frontend já multiplica os
            campos antes de enviar.
    CarrierQuotationCreate:
      type: object
      description: Corpo do `POST /carrier/quotation`.
      required:
        - ShippingPostalCode
        - Quotations
      properties:
        ShippingPostalCode:
          type: string
          description: >-
            CEP destino. Aceita com ou sem hífen; o sistema remove caracteres não numéricos e padroniza em 8 dígitos com
            zeros à esquerda.
        Description:
          type: string
          nullable: true
          description: Descrição livre para identificar a simulação na listagem.
        Quotations:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/CarrierQuotationVolumeItem'
          description: >-
            Lista de volumes/produtos a simular (mínimo 1). O sistema agrega: soma de pesos, larguras e valores de nota;
            pega o maior entre alturas e comprimentos; usa a contagem como `Volumes`. Cada item segue
            `CarrierQuotationVolumeItem`.
        OriginPostalCode:
          type: string
          nullable: true
          description: CEP origem. Quando vazio, o sistema usa `CompanyAddressPostalCode` da empresa.
        IDOrder:
          type: integer
          nullable: true
          description: Quando a simulação é feita a partir de um pedido existente, amarra para fins de auditoria.
        IDCompanyIntegration:
          type: integer
          nullable: true
          description: Integração de origem da chamada (preenchido automaticamente quando vem de marketplace).
        IDSkuHub:
          type: string
          nullable: true
          description: SKU enviado pelo canal (preenchido automaticamente quando vem de marketplace).
        IDSkuCompany:
          type: string
          nullable: true
          description: SKU local correspondente (preenchido automaticamente quando vem de marketplace).
    CarrierQuotationListItem:
      type: object
      description: Item de `GET /carrier/quotation`. Cabeçalho da simulação sem as linhas por transportadora.
      properties:
        IDCarrierQuotation:
          type: integer
          description: Identificador da simulação.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data/hora da simulação.
        AccountName:
          type: string
          description: Subdomínio da empresa dona da simulação.
        Login:
          type: string
          description: Login do usuário que rodou a simulação.
        Description:
          type: string
          nullable: true
          description: Descrição livre informada no `POST` para identificar a simulação na listagem.
        ShippingPostalCode:
          type: string
          description: CEP destino, 8 dígitos.
        ShippingState:
          type: string
          description: UF do CEP destino.
        Weight:
          type: number
          description: Peso total agregado em kg (soma dos volumes).
        Height:
          type: number
          description: Maior altura entre os volumes em cm.
        Width:
          type: number
          description: Soma das larguras dos volumes em cm.
        Length:
          type: number
          description: Maior comprimento entre os volumes em cm.
        ValueInvoice:
          type: number
          nullable: true
          description: Soma dos valores de nota dos volumes em R$. Base de cálculo para Gris, Advalorem e demais taxas percentuais.
        Volumes:
          type: integer
          description: Quantidade de volumes enviados na cotação.
        IDOrder:
          type: integer
          nullable: true
          description: Pedido vinculado à simulação (quando a cotação foi feita a partir de um pedido existente).
        IDCompanyIntegration:
          type: integer
          nullable: true
          description: Integração de origem da chamada (preenchido automaticamente quando a cotação vem de marketplace).
        CompanyIntegration:
          type: string
          nullable: true
          description: Nome amigável `IntegrationName - CompanyIntegrationName`.
        IDSkuHub:
          type: string
          nullable: true
          description: SKU do canal informado na cotação (preenchido automaticamente quando vem de marketplace).
        CarriersName:
          type: string
          nullable: true
          description: Lista de transportadoras que responderam, separadas por vírgula.
        CarrierQuotationUUID:
          type: string
          description: UUID gerado no POST.
    CarrierQuotationItemDetail:
      type: object
      description: Cotação devolvida por uma transportadora para a simulação.
      properties:
        IDCarrierQuotationRate:
          type: integer
          description: >-
            Identificador da linha de cotação retornada por uma transportadora dentro da cotação. Cada transportadora
            consultada gera uma linha; o usuário escolhe uma para o pedido.
        IDCarrier:
          type: integer
          description: '`IDSupplier` da transportadora.'
        SupplierNameCorporateName:
          type: string
          description: Razão social ou nome fantasia da transportadora cotada (`SupplierNameCorporateName`).
        CarrierLogoUrl:
          type: string
          nullable: true
          description: URL do logotipo da transportadora para exibição na tela de seleção.
        CarrierModal:
          type: string
          nullable: true
          description: Modalidade da transportadora (cadastrada em **Modalidade Transportadora**).
        Attended:
          type: integer
          enum:
            - 0
            - 1
            - 3
            - 4
          description: '`1`=Atende, `0`=Não atende, `3`=Excluído por regra (ação 9), `4`=Fora da faixa de peso da tabela cadastrada.'
        AttendedDescription:
          type: string
          description: Texto pronto para exibição (`Atende`, `Não Atende`, `Excluído`, `Fora da faixa`).
        RateType:
          type: string
          nullable: true
          description: Tipo de tabela aplicada (varia por transportadora).
        WeightSelected:
          type: number
          description: Peso considerado no cálculo do frete em kg — maior entre `Weight` (peso real) e `WeightCubed` (peso cubado).
        WeightCubed:
          type: number
          description: Peso cubado em kg calculado a partir das dimensões do volume e do fator de cubagem da transportadora.
        Weight:
          type: number
          description: Peso real total do volume em kg.
        CarrierCubageKmM:
          type: number
          description: Índice de cubagem da transportadora (padrão 167).
        CarrierCubageFreeWeight:
          type: number
          nullable: true
          description: Peso mínimo abaixo do qual a cubagem é ignorada.
        DaysTime:
          type: number
          description: Prazo final de entrega em dias úteis (após somar `CarrierAdditionalBusinessDays` e regras aplicáveis).
        CarrierAdditionalBusinessDays:
          type: number
          description: >-
            Dias úteis adicionais somados ao prazo base da tabela (ex.: dias de coleta + processamento configurados na
            transportadora).
        CutDaysTime:
          type: integer
          description: '`1` quando a simulação rodou depois do horário de corte (`CarrierShippingCutTime`), `0` caso contrário.'
        RuleAdditionalDays:
          type: number
          nullable: true
          description: Dias adicionais por regra de simulação.
        TotalDaysTime:
          type: number
          description: Soma de `DaysTime + CarrierAdditionalBusinessDays + CutDaysTime`.
        TotalShowDaysTime:
          type: number
          description: Soma de `DaysTime + CarrierAdditionalBusinessDays + CutDaysTime + RuleAdditionalDays`.
        ShipingValue:
          type: number
          description: Valor do frete cobrado pela transportadora antes das taxas adicionais e impostos (frete-peso/frete-valor).
        AdvaloremValue:
          type: number
          description: Valor do Ad valorem em reais (seguro proporcional ao valor da carga).
        AdvaloremValuePercent:
          type: number
          description: Alíquota percentual aplicada para cálculo do Ad valorem.
        GrisValue:
          type: number
          description: Valor do GRIS (Gerenciamento de Risco) em reais.
        GrisValuePercent:
          type: number
          description: Alíquota percentual aplicada para cálculo do GRIS.
        TollValue:
          type: number
          description: Valor total de pedágio em reais.
        TollFractionValue:
          type: number
          description: >-
            Valor de pedágio por fração de peso quando a transportadora cobra por fração (frequente no modal
            rodoviário).
        AccessDifficultyRateValue:
          type: number
          description: Taxa de dificuldade de acesso (TDA) — cobrança extra para regiões de difícil acesso.
        DispatchFeeValue:
          type: number
          description: Taxa de despacho (TAS/TRT) cobrada por documento de transporte emitido.
        DeliveryDifficultyRateValue:
          type: number
          description: Taxa de dificuldade de entrega — adicional para regiões/endereços específicos.
        SECCATValue:
          type: number
          description: Valor da SECCAT (Seguro de Carga Aérea) — aplicada no modal aéreo.
        TrafficRestrictionFeeValue:
          type: number
          description: >-
            Taxa de restrição de tráfego — adicional para entregas em zonas com restrição de circulação (centros
            urbanos).
        AdministrationFeeValue:
          type: number
          description: Taxa de administração da transportadora.
        CTEFeeValue:
          type: number
          description: Taxa de emissão de CT-e (Conhecimento de Transporte Eletrônico).
        SUFRAMAFeeValue:
          type: number
          description: Taxa SUFRAMA — adicional para entregas na Zona Franca de Manaus.
        FluvialInsuranceFee:
          type: number
          description: Adicional de seguro para transporte fluvial.
        OtherFee:
          type: number
          description: Alíquota percentual de outras taxas da tabela da transportadora.
        OtherFeeValue:
          type: number
          description: Valor em reais das outras taxas calculado a partir de `OtherFee`.
        IcmsValue:
          type: number
          description: Valor do ICMS embutido no frete em reais.
        AdjustedValue:
          type: number
          description: Ajuste vindo do `CarrierAuctionPenalty` da transportadora.
        RuleAdditionalValue:
          type: number
          nullable: true
          description: Valor adicional aplicado pela regra de simulação.
        CarrierQuotationRuleValueName:
          type: string
          nullable: true
          description: Nome da regra que alterou o valor (quando houve).
        CarrierQuotationRuleDaysName:
          type: string
          nullable: true
          description: Nome da regra que alterou o prazo (quando houve).
        IDCarrierQuotationRuleValue:
          type: integer
          nullable: true
          description: >-
            Identificador da regra de cotação aplicada que alterou o valor final (regra de ajuste de preço). Vazio
            quando nenhuma regra de valor foi aplicada.
        IDCarrierQuotationRuleDays:
          type: integer
          nullable: true
          description: >-
            Identificador da regra de cotação aplicada que alterou o prazo de entrega. Vazio quando nenhuma regra de
            prazo foi aplicada.
        PriceRounding:
          type: number
          nullable: true
          description: >-
            Quando definido entre 0 e 1, arredonda `ShippingShowValue` para terminar nesse valor (ex.: `0.90` arredonda
            preço final para terminar em `,90`).
        SubtotalShippingValue:
          type: number
          nullable: true
          description: Soma de todos os componentes sem ICMS. `null` quando `Attended != 1`.
        TotalShippingValue:
          type: number
          nullable: true
          description: Subtotal + ICMS. `null` quando `Attended != 1`.
        IcmsValuePercent:
          type: number
          nullable: true
          description: Alíquota de ICMS aplicada no frete.
        ShippingShowValue:
          type: number
          nullable: true
          description: >-
            Total + `AdjustedValue` + `RuleAdditionalValue`, com aplicação opcional de `PriceRounding`. **É o valor
            final mostrado ao cliente.**
    CarrierQuotationDetail:
      type: object
      description: >-
        Resposta de `GET /carrier/quotation/{idcarrierquotation}` e do POST. Cabeçalho + array `CarrierQuotations` com
        as linhas por transportadora.
      allOf:
        - $ref: '#/components/schemas/CarrierQuotationListItem'
        - type: object
          properties:
            CompanyAddressPostalCode:
              type: string
              description: CEP de origem (endereço da empresa).
            CompanyAddressState:
              type: string
              description: UF de origem (estado da empresa).
            OriginPostalCode:
              type: string
              nullable: true
              description: CEP de origem informado na cotação, quando difere do endereço da empresa.
            ShippingIbgeCode:
              type: string
              nullable: true
              description: Código IBGE do município de destino.
            ShippingSameCity:
              type: integer
              enum:
                - 0
                - 1
              description: '`1` quando o CEP destino é da mesma cidade da empresa (ICMS zerado nestas simulações).'
            CarrierQuotations:
              type: array
              items:
                $ref: '#/components/schemas/CarrierQuotationItemDetail'
              description: Ordenado por `Attended DESC, TotalDaysTime ASC, TotalShippingValue ASC`.
    CarrierQuotationErrorTypeEnum:
      type: integer
      description: |-
        Tipo do erro de cotação de frete.
        - `1` — Variação canal não localizada: SKU do canal (`IDSkuHub`) sem mapeamento na integração.
        - `2` — Sku não localizado: SKU não cadastrado.
        - `3` — Cep não localizado: CEP destino fora da base ou inválido.
        - `4` — Sku sem peso cadastrado.
        - `5` — Sku sem dimensões cadastradas (largura, altura ou comprimento).
        - `6` — Tipo integração de venda não localizada.
      enum:
        - 1
        - 2
        - 3
        - 4
        - 5
        - 6
    CarrierQuotationErrorListItem:
      type: object
      description: Item de `GET /carrier/quotation/error`.
      properties:
        AccountName:
          type: string
          description: Subdomínio da empresa dona da chamada que falhou.
        IDCarrierQuotationError:
          type: integer
          description: Identificador do registro de erro.
        RecordTimestamp:
          type: string
          format: date-time
          description: Quando o erro foi gerado.
        ShippingPostalCode:
          type: string
          description: CEP destino que originou a chamada, padronizado em 8 dígitos com zeros à esquerda.
          maxLength: 8
        RecordUserCreated:
          type: integer
          description: >-
            `IDUser` que originou a chamada. Vários canais usam usuários técnicos fixos (Madeira Madeira = 2, Carrefour
            = 4, Tray = 294, integrações externas genéricas = 134).
        IDTypeCarrierQuotationError:
          $ref: '#/components/schemas/CarrierQuotationErrorTypeEnum'
          description: Tipo do erro de cotação. Valores em `CarrierQuotationErrorTypeEnum`.
        TypeCarrierQuotationError:
          type: string
          description: Nome amigável do tipo de erro.
        IDSkuHub:
          type: string
          nullable: true
          description: >-
            SKU enviado pelo marketplace na hora da cotação. Vem preenchido em erros de tipo `1`, `4`, `5` (problemas no
            produto).
        IDCompanyIntegration:
          type: integer
          nullable: true
          description: Integração de origem da chamada.
        CompanyIntegrationName:
          type: string
          nullable: true
          description: Nome da integração no formato `IntegrationName - CompanyIntegrationName`.
    PreCollectionPackageListItem:
      type: object
      description: >-
        Item de `GET /orders/package` (fila do Pré-Romaneio). Lista pacotes com dados do pedido, transportadora e
        romaneio atual.
      properties:
        IDPackage:
          type: integer
          description: Identificador interno do pacote.
        PackageNumber:
          type: integer
          nullable: true
          description: Número sequencial do pacote dentro do pedido (1, 2, 3 …).
        ShippingId:
          type: string
          nullable: true
          description: Código de rastreio do pacote (etiqueta da transportadora).
        IDStatusPackage:
          type: integer
          nullable: true
          description: '`TypeStatusPackage`. `1` = ok, `2` = volume processando.'
          enum:
            - 1
            - 2
        StatusPackage:
          type: string
          nullable: true
          description: Nome amigável do status do pacote.
        IDOrder:
          type: integer
          description: Pedido amarrado ao pacote.
        Order:
          type: string
          description: Número amigável do pedido.
        OrderFrom:
          type: string
          nullable: true
          description: Origem do pedido (canal de venda).
        OrderPriority:
          type: integer
          nullable: true
          description: Prioridade do pedido (0=mais alta, 10=mais baixa).
        IDStatusOrder:
          type: integer
          description: >-
            `TypeStatusOrder`. Códigos relevantes nesta tela: `6` Aguardando expedição, `22` Aguardando romaneio, `7`
            Enviado, `8` Entregue com sucesso, `5` Segurar pedido, `100` Deletado.
        StatusOrder:
          type: string
          description: Nome amigável do status do pedido.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data de criação do pacote.
        IDCarrier:
          type: integer
          nullable: true
          description: Transportadora do pedido.
        SupplierNameCorporateName:
          type: string
          nullable: true
          description: Nome da transportadora.
        AccountName:
          type: string
          description: Conta (multi-empresa).
        IDStockKeepingUnitDistributionCenter:
          type: integer
          description: CD do pedido.
        DistributionCenterName:
          type: string
          description: Nome do CD.
        IDOrdersCarrierCollectionList:
          type: integer
          nullable: true
          description: Romaneio em que o pacote está amarrado (`null` quando ainda não foi para nenhum romaneio).
    PreCollectionPostPayload:
      type: object
      required:
        - Search
        - IDCarrier
      description: Payload de `POST /fulfillment/packing/collection-list/order` (bipagem para amarrar pacote ao romaneio).
      properties:
        Search:
          type: string
          description: >-
            **Código de rastreio do pacote** (`ShippingId`) **ou** **chave de acesso da NF-e** (44 dígitos). O sistema
            detecta o formato via regex `^\d{44}$`: chave NF-e busca por `NfeChaveAcesso` e amarra todos os pacotes da
            nota; rastreio busca por `ShippingId` e amarra apenas o pacote bipado (no modo
            `PackagesOnOrdersCarrierCollectionList=1`).
        IDCarrier:
          type: integer
          description: >-
            Identificador da transportadora bipada. Precisa coincidir com `IDCarrier` do pedido — divergência retorna
            `[BadRequest] - Transportadora informada divergente do pedido`.
    OrderTrackingListItem:
      type: object
      description: >-
        Item de `GET /orders/tracking`. Combina cabeçalho do pedido, último status de tracking e indicadores de
        pontualidade.
      properties:
        AccountName:
          type: string
          description: Conta (subdomínio) que originou o pedido.
        IDOrder:
          type: integer
          description: Identificador do pedido.
        Order:
          type: string
          description: Número do pedido amigável.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data/hora de criação do pedido.
        TypeOrder:
          type: string
          description: Nome do tipo de pedido.
        NfeNumber:
          type: integer
          nullable: true
          description: Número da nota fiscal principal emitida para o pedido.
        OrderFrom:
          type: string
          nullable: true
          description: Origens externas amarradas ao pedido, concatenadas por vírgula.
        IDConsumer:
          type: integer
          nullable: true
          description: Identificador do cliente.
        ConsumerNameCorporateName:
          type: string
          nullable: true
          description: Nome/razão social do cliente.
        ConsumerCpfCnpj:
          type: string
          nullable: true
          description: CPF/CNPJ do cliente.
        ConsumerEmail:
          type: string
          nullable: true
          description: E-mail do cliente.
        ValueShipping:
          type: number
          nullable: true
          description: Valor do frete cobrado no pedido.
        ShippingPostalCode:
          type: string
          nullable: true
          description: CEP de entrega.
        ShippingCity:
          type: string
          nullable: true
          description: Cidade de entrega.
        ShippingState:
          type: string
          nullable: true
          description: UF de entrega.
        ShippingDate:
          type: string
          format: date-time
          nullable: true
          description: Maior `ShippingDate` do pedido (data de postagem).
        ShippingId:
          type: string
          nullable: true
          description: Lista de códigos de rastreio dos pacotes, concatenada por vírgula.
        ShippingEstimateDate:
          type: string
          format: date-time
          nullable: true
          description: Data estimada de entrega prometida ao consumidor (vinda do canal de venda).
        CarrierDeliveryDate:
          type: string
          format: date-time
          nullable: true
          description: Data estimada de entrega prometida pela transportadora.
        DeliveredDate:
          type: string
          format: date-time
          nullable: true
          description: Quando o pedido foi marcado como entregue (`IDEvent = 45`).
        FinishDate:
          type: string
          format: date-time
          nullable: true
          description: Quando o pedido foi finalizado (`IDEvent IN (45,52,57)`).
        ConsumerDeliveryDateDifference:
          type: integer
          nullable: true
          description: Dias entre `DeliveredDate` e `ShippingEstimateDate` (negativo = antes, positivo = depois).
        CarrierDeliveryDateDifference:
          type: integer
          nullable: true
          description: Dias entre `DeliveredDate` e `CarrierDeliveryDate`.
        TrackingIDStatus:
          type: integer
          nullable: true
          description: Último `TrackingIDStatus` do pedido (`TypeStatusTracking`).
        StatusTracking:
          type: string
          nullable: true
          description: >-
            Nome amigável do status (`Postado`, `Em andamento`, `Saiu para entrega`, `Finalizado`, `Atenção`,
            `Extraviado`, `Devolvido`).
        TrackingLastStatus:
          type: string
          nullable: true
          description: Descrição do último evento de tracking enviado pela transportadora (`Description`).
        TrackingLastStatusRecordTimestamp:
          type: string
          format: date-time
          nullable: true
          description: Data/hora do último evento de tracking enviado pela transportadora.
        IDStatusDeliveryConsumer:
          type: integer
          nullable: true
          enum:
            - 1
            - 2
            - 3
            - 4
            - 6
          description: >-
            Indicador de pontualidade vs. data estimada para o consumidor: `1`=entregue antes do prazo, `2`=entregue
            após o prazo, `3`=ainda dentro do prazo, `4`=atrasado, `6`=entregue no dia exato.
        StatusDeliveryConsumer:
          type: string
          nullable: true
          description: Nome amigável do indicador acima.
        IDStatusDeliveryCarrier:
          type: integer
          nullable: true
          enum:
            - 1
            - 2
            - 3
            - 4
            - 6
          description: Mesmos códigos do consumidor, calculados contra `CarrierDeliveryDate`.
        StatusDeliveryCarrier:
          type: string
          nullable: true
          description: Nome amigável do indicador de pontualidade calculado contra `CarrierDeliveryDate`.
        IDStatusOrder:
          type: integer
          description: >-
            Status do pedido no idworks. Ver `support data/TypeStatusOrder.csv` para a lista de valores (ex.:
            `0`=Aberto, `1`=Fechado, `7`=Enviado, `8`=Entregue com sucesso, `90`=Cancelado).
        StatusOrder:
          type: string
          nullable: true
          description: Nome amigável do `IDStatusOrder` (`StatusOrder` ou `TypeStatusOrderCompany` quando a empresa renomeou).
        IDCarrier:
          type: integer
          nullable: true
          description: Identificador da transportadora vinculada ao pedido.
        SupplierNameCorporateName:
          type: string
          nullable: true
          description: Nome/razão social da transportadora.
        IDCompanyIntegration:
          type: integer
          nullable: true
          description: Integração (canal de venda / loja) de origem do pedido.
        CompanyIntegration:
          type: string
          nullable: true
          description: '`IntegrationName - CompanyIntegrationName`.'
        SalesChannelName:
          type: string
          nullable: true
          description: Nome do canal de venda (`IntegrationName`).
    DistributionCenterItem:
      type: object
      description: Centro de distribuição (`StockKeepingUnitDistributionCenter`).
      properties:
        AccountName:
          type: string
          description: Conta (subdomínio) da empresa.
        IDStockKeepingUnitDistributionCenter:
          type: integer
          description: Identificador do centro de distribuição.
        IDCompany:
          type: integer
          description: Identificador da empresa dona.
        DistributionCenterName:
          type: string
          maxLength: 100
          description: Nome do centro de distribuição.
        Default:
          type: integer
          enum:
            - 0
            - 1
          description: Apenas 1 CD por empresa pode ser padrão.
        ShippingStreet:
          type: string
          nullable: true
          description: Logradouro.
        ShippingNumber:
          type: string
          nullable: true
          description: Número.
        ShippingComplement:
          type: string
          nullable: true
          description: Complemento.
        ShippingNeighborhood:
          type: string
          nullable: true
          description: Bairro.
        ShippingCity:
          type: string
          nullable: true
          description: Cidade.
        ShippingState:
          type: string
          nullable: true
          maxLength: 2
          description: UF.
        ShippingPostalCode:
          type: string
          nullable: true
          description: CEP em 8 dígitos (sem hífen).
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora de criação.
    DistributionCenterCreate:
      type: object
      description: Corpo do POST/PUT de Centro de Distribuição.
      required:
        - DistributionCenterName
      properties:
        DistributionCenterName:
          type: string
          maxLength: 100
          description: Nome do centro de distribuição.
        Default:
          type: integer
          enum:
            - 0
            - 1
          description: Default `1` quando ausente. Marcar `1` zera o `Default` dos demais CDs.
        ShippingStreet:
          type: string
          nullable: true
          description: Logradouro do endereço do centro de distribuição.
        ShippingNumber:
          type: string
          nullable: true
          description: Número do endereço.
        ShippingComplement:
          type: string
          nullable: true
          description: Complemento (sala, andar).
        ShippingNeighborhood:
          type: string
          nullable: true
          description: Bairro.
        ShippingCity:
          type: string
          nullable: true
          description: Cidade.
        ShippingState:
          type: string
          nullable: true
          maxLength: 2
          description: UF (sigla do estado).
        ShippingPostalCode:
          type: string
          nullable: true
          description: Sistema remove caracteres não-numéricos.
    TypeStockKeepingUnitWarehouseEnum:
      type: integer
      enum:
        - 1
        - 2
        - 3
        - 4
        - 5
        - 6
        - 7
        - 8
        - 9
        - 10
        - 11
      description: >-
        Tipo de armazém: `1` Saudável · `2` Divergência · `3` Quarentena · `4` Recebimento · `5` Falta · `6` Vencido ·
        `7` Auditoria · `8` Avaria · `9` Devolução · `10` Ressuprimento · `11` Outlet.
    WarehouseItem:
      type: object
      description: Armazém (`StockKeepingUnitWarehouse`).
      properties:
        AccountName:
          type: string
          description: Conta (subdomínio) da empresa.
        IDStockKeepingUnitWarehouse:
          type: string
          description: Devolvido como string (pode ser um número grande).
        WarehouseName:
          type: string
          maxLength: 100
          description: Nome do depósito.
        IDCompany:
          type: integer
          description: Identificador da empresa.
        IDStockKeepingUnitDistributionCenter:
          type: integer
          description: Centro de distribuição ao qual o depósito pertence.
        DistributionCenterName:
          type: string
          description: Nome do centro de distribuição.
        IDTypeStockKeepingUnitWarehouse:
          $ref: '#/components/schemas/TypeStockKeepingUnitWarehouseEnum'
          description: Natureza do depósito (vide enum em `IDTypeStockKeepingUnitWarehouse`).
        TypeStockKeepingUnitWarehouse:
          type: string
          description: Nome amigável do tipo.
        Default:
          type: integer
          enum:
            - 0
            - 1
          description: Armazém padrão (apenas 1 por empresa).
        DefaultPurchase:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: Armazém padrão de recebimento de compras (apenas 1 por empresa).
        Status:
          type: integer
          enum:
            - 0
            - 1
          description: '`1`=Ativo, `0`=Inativo (após soft delete).'
        SumQuantity:
          type: integer
          enum:
            - 0
            - 1
          description: Quando `1`, o estoque deste armazém soma no saldo agregado dos SKUs.
        IDCompanyInvoice:
          type: integer
          nullable: true
          description: Empresa que fatura por este armazém (3PL/operador logístico).
        CompanyNameCorporateNameInvoice:
          type: string
          nullable: true
          description: '`AccountName - CompanyNameCorporateName` da empresa faturadora resolvido.'
        AccountNameInvoice:
          type: string
          nullable: true
          description: >-
            Conta da empresa faturadora associada ao depósito (usada na emissão de NF-e quando o estoque sai deste
            depósito).
        ShippingStreet:
          type: string
          nullable: true
          description: Logradouro.
        ShippingNumber:
          type: string
          nullable: true
          description: Número.
        ShippingComplement:
          type: string
          nullable: true
          description: Complemento.
        ShippingNeighborhood:
          type: string
          nullable: true
          description: Bairro.
        ShippingCity:
          type: string
          nullable: true
          description: Cidade.
        ShippingState:
          type: string
          nullable: true
          maxLength: 2
          description: UF.
        ShippingPostalCode:
          type: string
          nullable: true
          description: CEP.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora de criação.
    WarehouseCreate:
      type: object
      description: Corpo do POST/PUT de Armazém.
      required:
        - WarehouseName
        - IDStockKeepingUnitDistributionCenter
        - IDTypeStockKeepingUnitWarehouse
      properties:
        WarehouseName:
          type: string
          maxLength: 100
          description: Nome do depósito.
        IDStockKeepingUnitDistributionCenter:
          type: integer
          description: CD pai.
        IDTypeStockKeepingUnitWarehouse:
          $ref: '#/components/schemas/TypeStockKeepingUnitWarehouseEnum'
          description: >-
            Natureza do depósito: `1` Saudável (estoque vendável), `2` Divergência, `3` Quarentena, `4` Recebimento, `5`
            Falta, `6` Vencido, `7` Auditoria, `8` Avaria, `9` Devolução, `10` Ressuprimento.
        IDCompanyInvoice:
          type: integer
          nullable: true
          description: Empresa faturadora — precisa ser associada à conta autenticada via CompanyMain.
        Default:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` define este depósito como padrão da empresa para movimentações de venda.'
        DefaultPurchase:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` define este depósito como padrão para entradas de compra.'
        Status:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` depósito ativo; `0` desativado (não aceita movimentações).'
        SumQuantity:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            `1` faz a quantidade deste depósito ser somada ao estoque total disponível para venda; `0` mantém o saldo
            isolado (ex.: depósito de quarentena).
        ShippingStreet:
          type: string
          nullable: true
          description: Logradouro do endereço do depósito.
        ShippingNumber:
          type: string
          nullable: true
          description: Número.
        ShippingComplement:
          type: string
          nullable: true
          description: Complemento.
        ShippingNeighborhood:
          type: string
          nullable: true
          description: Bairro.
        ShippingCity:
          type: string
          nullable: true
          description: Cidade.
        ShippingState:
          type: string
          nullable: true
          maxLength: 2
          description: UF.
        ShippingPostalCode:
          type: string
          nullable: true
          description: CEP.
    SkuLocationCategoryItem:
      type: object
      description: Categoria de endereço (`StockKeepingUnitLocationCategory`).
      properties:
        AccountName:
          type: string
          description: Conta (subdomínio) da empresa.
        IDStockKeepingUnitLocationCategory:
          type: integer
          description: Identificador da categoria de endereço.
        IDCompany:
          type: integer
          description: Identificador da empresa.
        StockKeepingUnitLocationCategoryName:
          type: string
          maxLength: 100
          description: Nome da categoria de endereço.
        IsActive:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` categoria ativa; `0` desativada (não aparece no cadastro de endereços).'
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora de criação.
    SkuLocationCategoryCreate:
      type: object
      required:
        - StockKeepingUnitLocationCategoryName
      properties:
        StockKeepingUnitLocationCategoryName:
          type: string
          maxLength: 100
          description: Nome único por empresa.
    PickingListBasketHistoryItem:
      type: object
      description: Registro do histórico de pedidos passados pelo cesto.
      properties:
        IDPickingListBasketHistory:
          type: integer
          description: Identificador da linha do histórico de uso do cesto de separação.
        IDOrder:
          type: integer
          nullable: true
          description: >-
            Pedido que ocupou o cesto neste evento do histórico. Vazio quando o evento foi de criação/liberação sem
            pedido amarrado.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora do evento (ocupação ou liberação do cesto).
    PickingListBasketItem:
      type: object
      description: Cesto picking (`PickingListBasket`).
      properties:
        AccountName:
          type: string
          description: Identificador da empresa dona do cesto.
        IDPickingListBasket:
          type: integer
          description: Identificador do cesto.
        ExternalId:
          type: string
          description: Código externo (etiqueta/barcode). Único por CD.
        IDStockKeepingUnitDistributionCenter:
          type: integer
          description: Identificador do CD a que o cesto pertence.
        DistributionCenterName:
          type: string
          description: Nome amigável do CD.
        BasketHeight:
          type: number
          nullable: true
          description: Altura em cm.
        BasketWidth:
          type: number
          nullable: true
          description: Largura em cm.
        BasketLength:
          type: number
          nullable: true
          description: Comprimento em cm.
        BasketMaxWeight:
          type: number
          nullable: true
          description: Peso máximo em kg.
        PickingListBasketStatus:
          type: integer
          enum:
            - 0
            - 1
          description: '`1`=Ativo, `0`=Inativo.'
        IDOrder:
          type: integer
          nullable: true
          description: Pedido atualmente amarrado ao cesto.
        IDPickingList:
          type: integer
          nullable: true
          description: Picking list em curso vinculada ao pedido do cesto.
        PickingListBasketHistory:
          type: array
          items:
            $ref: '#/components/schemas/PickingListBasketHistoryItem'
          description: >-
            Histórico cronológico (mais antigo → mais recente) das vinculações do cesto com pedidos durante a coleta.
            Vazio quando o cesto ainda não foi usado.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data/hora de criação do cesto.
        PickingListRelated:
          type: array
          nullable: true
          description: >-
            Picking-lists relacionadas (pai/filhas da colméia). Presente apenas no primeiro item da resposta e somente
            quando a busca é por `ExternalId` ou `IDPickingListBasket` e o cesto tem picking-list vinculada; `[]` quando
            não há relacionadas.
          items:
            type: object
            properties:
              IDPickingList:
                type: integer
              IDPickingListStatus:
                type: integer
                enum:
                  - 1
                  - 2
                  - 3
                  - 4
                  - 5
                  - 6
                  - 7
              RecordUserCreatedStartPicking:
                type: integer
                nullable: true
              IDTypePickingList:
                type: integer
                enum:
                  - 1
                  - 2
                  - 3
                  - 4
              IDPickingListFather:
                type: integer
                nullable: true
              Checked:
                type: integer
                enum:
                  - 0
                  - 1
                nullable: true
              IDPickingListBasket:
                type: integer
                nullable: true
              ExternalId:
                type: string
                nullable: true
              UserName:
                type: string
                nullable: true
              TypePickingList:
                type: string
        PickingListFather:
          type: object
          nullable: true
          description: >-
            Dados da picking-list pai (colméia). Presente apenas no primeiro item da resposta quando há picking-lists
            relacionadas.
          properties:
            RecordUserCreated:
              type: integer
            RecordUserCreatedStartPicking:
              type: integer
              nullable: true
            RecordTimestampStartPicking:
              type: string
              format: date-time
              nullable: true
            RecordTimestampFinishedPicking:
              type: string
              format: date-time
              nullable: true
            IDPickingList:
              type: integer
            IDPickingListStatus:
              type: integer
              enum:
                - 1
                - 2
                - 3
                - 4
                - 5
                - 6
                - 7
            PickingListPriority:
              type: integer
              description: Prioridade da picking-list (0 a 10).
            StatusPickingList:
              type: string
            RecordTimestampEnd:
              type: string
              format: date-time
              nullable: true
            RecordTimestamp:
              type: string
              format: date-time
            RecordUserCreatedStartPacking:
              type: integer
              nullable: true
            RecordTimestampStartPacking:
              type: string
              format: date-time
              nullable: true
            IDTypePickingList:
              type: integer
              enum:
                - 1
                - 2
                - 3
                - 4
            TypePickingList:
              type: string
            QtyOrder:
              type: integer
            QtyOrderDone:
              type: integer
            ItemsQuantity:
              type: number
            SkuQuantity:
              type: integer
    PickingListBasketCreate:
      type: object
      description: Atualização parcial do cesto de picking. Nenhum campo é obrigatório; apenas os campos enviados são atualizados.
      properties:
        IDStockKeepingUnitDistributionCenter:
          type: integer
          description: Identificador do CD onde o cesto opera.
        ExternalId:
          type: string
          nullable: true
          description: >-
            Código externo (etiqueta/barcode) do cesto. Único por CD — reenviar um código já usado por outro cesto do
            mesmo CD é rejeitado.
        BasketHeight:
          type: number
          nullable: true
          description: Altura do cesto em centímetros.
        BasketWidth:
          type: number
          nullable: true
          description: Largura do cesto em centímetros.
        BasketLength:
          type: number
          nullable: true
          description: Comprimento do cesto em centímetros.
        BasketMaxWeight:
          type: number
          nullable: true
          description: Peso máximo suportado em quilos.
        IDOrder:
          type: integer
          nullable: true
          description: >-
            Pedido a vincular ao cesto. Enviar null desvincula o pedido atualmente amarrado. Mutuamente exclusivo com
            IDPickingList e não aceito quando o cesto já tem picking-list vinculada.
        IDPickingList:
          type: integer
          nullable: true
          description: >-
            Picking-list a vincular ao cesto (fluxo colméia). Validada contra as picking-lists da empresa. Mutuamente
            exclusiva com IDOrder e não aceita quando o cesto já tem pedido vinculado.
    SkuBatchItem:
      type: object
      description: Lote (`StockKeepingUnitBatch`) com endereço, saldo e dados do SKU resolvidos.
      properties:
        AccountName:
          type: string
          description: Conta (subdomínio) da empresa.
        IDBatchNumber:
          type: integer
          description: Identificador único do lote.
        IDSku:
          type: integer
          description: Identificador do SKU dono do lote.
        IDSkuCompany:
          type: string
          description: Código de referência do SKU.
        SkuName:
          type: string
          description: Nome do SKU.
        BarCode:
          type: string
          nullable: true
          description: Código de barras principal do SKU.
        Batch:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            Vem do cadastro do SKU. `1` = SKU controla múltiplos lotes no mesmo endereço (rastreabilidade); `0` =
            unicidade SKU × endereço.
        IDStockKeepingUnitLocation:
          type: integer
          description: Endereço (posição física) onde o lote está alocado.
        Address:
          type: string
          description: Nome do endereço.
        IDStockKeepingUnitWarehouse:
          type: integer
          description: Depósito onde o lote está.
        WarehouseName:
          type: string
          description: Nome do depósito.
        IDStockKeepingUnitDistributionCenter:
          type: integer
          description: Centro de distribuição do depósito.
        DistributionCenterName:
          type: string
          description: Nome do centro de distribuição.
        IDStockKeepingUnitLocationCategory:
          type: integer
          nullable: true
          description: Categoria do endereço.
        StockKeepingUnitLocationCategoryName:
          type: string
          nullable: true
          description: Nome da categoria do endereço.
        IDStockKeepingUnitLocationGroup:
          type: integer
          nullable: true
          description: Grupo de endereços do lote.
        StockKeepingUnitLocationGroupName:
          type: string
          nullable: true
          description: Nome do grupo de endereços.
        IDTypeAddress:
          type: integer
          nullable: true
          enum:
            - 1
            - 2
            - 3
          description: 'Tipo de endereço de armazenagem: `1` Picking, `2` Pulmão, `3` Blocado.'
        TypeAddress:
          type: string
          nullable: true
          description: Descrição textual do tipo de endereço.
        BestBeforeDate:
          type: string
          format: date
          description: Validade. Default `4000-01-01` quando o produto não tem validade.
        ManufacturingDate:
          type: string
          format: date
          nullable: true
          description: Data de fabricação (rastreabilidade).
        Comments:
          type: string
          nullable: true
          description: 'Descrição/identificador do lote (texto livre, ex.: `LOTE-2024-A1`).'
        Default:
          type: integer
          enum:
            - 0
            - 1
          description: Lote padrão do SKU (apenas 1 por SKU).
        IDTypeSku:
          type: integer
          description: Tipo do SKU (vide enum em `IDTypeSku`).
        AbcCurve:
          type: string
          nullable: true
          description: Curva ABC do SKU (A, B ou C).
        MainImageURL:
          type: string
          nullable: true
          description: URL da imagem principal do SKU.
        MainImageThumbnailURL:
          type: string
          nullable: true
          description: URL da miniatura.
        BatchBalance:
          type: number
          description: >-
            Saldo do lote — soma de entradas (`IDTypeMovement=0` e `IDStatusSku=1`) menos saídas (`IDTypeMovement=1`),
            com `BalanceChange = 1`.
        QtyHandling:
          type: number
          description: Quantidade em movimentação (saídas reservadas em `IDStatusSku=0`).
        QtyAvailable:
          type: number
          description: Saldo disponível do SKU no armazém (`QtyAvailable`).
        IDBatchStatus:
          type: integer
          enum:
            - 0
            - 1
          description: 'Derivado: `1`=Ativo (saldo > 0), `0`=Inativo (saldo = 0).'
        BatchStatus:
          type: string
          enum:
            - Ativo
            - Inativo
          description: 'Situação do lote: `Ativo` quando ainda tem saldo disponível; `Inativo` quando zerado.'
        BatchDAgeInDays:
          type: integer
          description: Idade do lote em dias (hoje − RecordTimestamp).
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora de criação do lote.
        PriceSell:
          type: number
          nullable: true
          description: >-
            Preço de venda do SKU. Quando há promoção ativa e `IDCompanySalesPolicy` foi informado, já vem com o
            desconto aplicado. `null` quando o SKU não tem preço vigente.
        PriceList:
          type: number
          nullable: true
          description: Preço de tabela (lista) do SKU. `null` quando não há preço vigente.
        PercentualDiscountValue:
          type: number
          nullable: true
          description: >-
            Desconto percentual da promoção ativa do SKU, expresso como fração (ex.: `0.1` = 10%). Presente apenas
            quando `IDCompanySalesPolicy` é informado.
    SkuBatchCreate:
      type: object
      description: Corpo do `POST /sku/batch/{idsku}`.
      required:
        - IDStockKeepingUnitLocation
      properties:
        IDStockKeepingUnitLocation:
          type: integer
          description: Endereço onde o lote será criado.
        BestBeforeDate:
          type: string
          format: date
          nullable: true
          description: Validade. Obrigatório quando o SKU tem `BestBeforeRequired = 1`.
        Comments:
          type: string
          nullable: true
          description: Descrição do lote. Obrigatória quando o SKU tem `BatchRequired = 1`.
        Default:
          type: integer
          enum:
            - 0
            - 1
          description: Marca como lote padrão (zera os demais do SKU).
    SkuBatchUpdate:
      type: object
      description: Corpo do PUT — atualização parcial.
      properties:
        IDBatch:
          type: integer
          description: Usado quando o id do lote vem no body em vez de path.
        IDStockKeepingUnitLocation:
          type: integer
          description: >-
            Para transferir o lote para outro endereço. Não pode ser `null` (use DELETE para remover). Precisa ser do
            mesmo armazém do endereço atual.
        BestBeforeDate:
          type: string
          format: date
          description: Data de validade do lote.
        ManufacturingDate:
          type: string
          format: date
          description: Data de fabricação do lote.
        Comments:
          type: string
          nullable: true
          description: Observações livres do lote.
        Default:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` define este lote como o padrão de saída do SKU (consumido primeiro nas vendas); `0` lote alternativo.'
    TypeResupplyEnum:
      type: integer
      description: >-
        Tipo de ressuprimento: `1` Picking (reposição da picking), `2` Pulmão (movimentação para pulmão), `3`
        Recebimento (item recebido sendo endereçado).
      enum:
        - 1
        - 2
        - 3
    TypeResupplyModeEnum:
      type: integer
      description: >-
        Modalidade de operação: `1` Individual (1 ressuprimento = 1 pedido), `2` Agrupado (vários pedidos agrupados),
        `3` Indireto (estoque interno sem amarração a pedido).
      enum:
        - 1
        - 2
        - 3
    StatusResupplyEnum:
      type: integer
      description: 'Status: `1` Aberto, `2` Iniciado, `3` Finalizado, `4` Cancelado.'
      enum:
        - 1
        - 2
        - 3
        - 4
    ResupplyItem:
      type: object
      description: Ressuprimento (`StockKeepingUnitResupplyList`).
      properties:
        AccountName:
          type: string
          description: Conta (subdomínio) da empresa.
        IDStockKeepingUnitResupplyList:
          type: integer
          description: Identificador do ressuprimento.
        IDCompany:
          type: integer
          description: Identificador da empresa.
        IDStockKeepingUnitDistributionCenter:
          type: integer
          description: Centro de distribuição em que o ressuprimento ocorre.
        DistributionCenterName:
          type: string
          description: Nome do centro de distribuição.
        IDTypeResupply:
          $ref: '#/components/schemas/TypeResupplyEnum'
          description: 'Tipo: `1` Picking, `2` Pulmão, `3` Recebimento.'
        TypeResupply:
          type: string
          description: Picking / Pulmão / Recebimento.
        IDTypeResupplyMode:
          $ref: '#/components/schemas/TypeResupplyModeEnum'
          description: 'Modo: `1` Individual, `2` Agrupado, `3` Indireto.'
        TypeResupplyMode:
          type: string
          description: Individual / Agrupado / Indireto.
        IDResupplyStatus:
          $ref: '#/components/schemas/StatusResupplyEnum'
          description: 'Status: `1` Aberto, `2` Iniciado, `3` Finalizado, `4` Cancelado.'
        StatusResupply:
          type: string
          description: Descrição textual do status.
        StockKeepingUnitResupplyListPriority:
          type: integer
          minimum: 0
          maximum: 10
          nullable: true
          description: >-
            0 (mais alta) a 10 (mais baixa). Quando o parâmetro `UseShippingHandlingTimeInResupplyPriority` está ativo,
            o sistema reduz a prioridade conforme a data de expedição se aproxima.
        QtyOrder:
          type: integer
          nullable: true
          description: Pedidos vinculados (modalidade Individual/Agrupado).
        QtyResupply:
          type: integer
          nullable: true
          description: Itens pendentes de transferência. Quando `> 0`, a exclusão é bloqueada.
        QtyResupplyItems:
          type: integer
          nullable: true
          description: Total de unidades pendentes.
        RecordUserStart:
          type: integer
          nullable: true
          description: Colaborador atribuído (vira o campo `UserStartLogin` resolvido).
        UserStartLogin:
          type: string
          nullable: true
          description: Login do usuário que iniciou o ressuprimento.
        Comments:
          type: string
          nullable: true
          description: Observações livres.
        RecordTimestamp:
          type: string
          format: date-time
          description: Criação.
        RecordTimestampStart:
          type: string
          format: date-time
          nullable: true
          description: Início da separação (status passou a Iniciado).
        RecordTimestampFinished:
          type: string
          format: date-time
          nullable: true
          description: Conclusão.
    ResupplyCreate:
      type: object
      description: Corpo do POST. Manual ou por pedido.
      properties:
        IDTypeResupply:
          $ref: '#/components/schemas/TypeResupplyEnum'
          description: >-
            Tipo do ressuprimento: `1` Picking (do pulmão para o endereço de picking), `2` Pulmão (chegada nova ao
            pulmão), `3` Recebimento (do recebimento para o estoque).
        IDTypeResupplyMode:
          $ref: '#/components/schemas/TypeResupplyModeEnum'
          description: 'Modo de execução: `1` Individual, `2` Agrupado, `3` Indireto. Padrão `1`.'
        IDStockKeepingUnitDistributionCenter:
          type: integer
          nullable: true
          description: Vazio = usa CD padrão da empresa.
        Comments:
          type: string
          nullable: true
          description: Observações livres do ressuprimento.
        IDOrder:
          type: integer
          nullable: true
          description: 'Modo automático por pedido: aciona o processo e gera as listas necessárias com base no saldo do pedido.'
    ResupplyUpdate:
      type: object
      description: Corpo do PUT. Atualização parcial.
      properties:
        IDResupplyStatus:
          $ref: '#/components/schemas/StatusResupplyEnum'
          description: 'Status do ressuprimento: `1` Aberto, `2` Iniciado, `3` Finalizado, `4` Cancelado.'
        IDTypeResupply:
          $ref: '#/components/schemas/TypeResupplyEnum'
          description: 'Tipo do ressuprimento: `1` Picking, `2` Pulmão, `3` Recebimento.'
        IDTypeResupplyMode:
          $ref: '#/components/schemas/TypeResupplyModeEnum'
          description: 'Modo: `1` Individual, `2` Agrupado, `3` Indireto.'
        StockKeepingUnitResupplyListPriority:
          type: integer
          minimum: 0
          maximum: 10
          description: Prioridade na fila de ressuprimento — menor valor é executado primeiro.
        RecordUserStart:
          type: integer
          nullable: true
          description: Atribuir colaborador. Envie `null` para desatribuir.
        Comments:
          type: string
          nullable: true
          description: Observações livres.
    PurchaseScheduleStatusEnum:
      type: integer
      description: >-
        Status calculado pelo sistema (não persistido): `1` Recebido (check-in feito), `2` Agendado (futuro, sem
        check-in), `3` Atrasado (passou e sem check-in), `4` Não agendado (sem recebimento amarrado).
      enum:
        - 1
        - 2
        - 3
        - 4
    PurchaseScheduleItem:
      type: object
      description: >-
        Agendamento de recebimento (`StockKeepingUnitPurchaseSchedule`) com dados do recebimento, fornecedor e NF
        resolvidos.
      properties:
        AccountName:
          type: string
          description: Subdomínio da empresa dona do agendamento.
        IDStockKeepingUnitPurchaseSchedule:
          type: integer
          description: Identificador do agendamento.
        IDCompany:
          type: integer
          description: Identificador da empresa dona do agendamento.
        RecordTimestamp:
          type: string
          format: date-time
          description: Quando o agendamento foi criado.
        StartTime:
          type: string
          format: date-time
          description: Início do agendamento.
        EndTime:
          type: string
          format: date-time
          description: Fim do agendamento.
        ScheduleTitle:
          type: string
          nullable: true
          description: Título amigável (livre).
        Comments:
          type: string
          nullable: true
          description: Observações.
        IDPurchase:
          type: integer
          nullable: true
          description: Recebimento amarrado. Vazio = agendamento avulso.
        IDSupplier:
          type: integer
          nullable: true
          description: Fornecedor resolvido a partir do recebimento amarrado. Vazio quando o agendamento é avulso.
        SupplierCpfCnpj:
          type: string
          nullable: true
          description: CPF/CNPJ do fornecedor (apenas dígitos). Vazio em agendamento avulso.
        SupplierNameCorporateName:
          type: string
          nullable: true
          description: Nome ou razão social do fornecedor. Vazio em agendamento avulso.
        serie:
          type: string
          nullable: true
          description: Série da NF.
        nNF:
          type: string
          nullable: true
          description: Número da NF.
        dhEmi:
          type: string
          format: date-time
          nullable: true
          description: Data/hora de emissão da NF.
        qVol:
          type: number
          nullable: true
          description: Quantidade de volumes da NF.
        Weight:
          type: number
          nullable: true
          description: Peso bruto da NF (`pesoB` no XML).
        ItemsQuantity:
          type: number
          nullable: true
          description: Soma das quantidades dos itens do recebimento.
        SkuQuantity:
          type: integer
          nullable: true
          description: Número de SKUs distintos no recebimento.
        CheckinTimestamp:
          type: string
          format: date-time
          nullable: true
          description: Quando o recebimento foi conferido fisicamente (check-in na portaria).
        IDStatusPurchase:
          type: integer
          nullable: true
          description: Status do recebimento (`IDStatusPurchase`).
        StatusPurchase:
          type: string
          nullable: true
          description: Nome amigável do status.
        StockKeepingUnitPurchaseScheduleStatus:
          $ref: '#/components/schemas/PurchaseScheduleStatusEnum'
          description: >-
            Status do agendamento calculado pelo sistema (não persistido): `1` Recebido, `2` Agendado, `3` Atrasado, `4`
            Não agendado.
        StockKeepingUnitPurchaseScheduleStatusDescription:
          type: string
          enum:
            - Recebido
            - Agendado
            - Atrasado
            - Não agendado
          description: >-
            Descrição amigável do status do agendamento: `Recebido` (check-in feito), `Agendado` (futuro, ainda sem
            check-in), `Atrasado` (passou do `EndTime` sem check-in), `Não agendado` (sem recebimento amarrado).
    PurchaseScheduleCreate:
      type: object
      description: Corpo do POST/PUT de Agendamento.
      required:
        - StartTime
        - EndTime
      properties:
        StartTime:
          type: string
          format: date-time
          description: Início. Precisa ser ≤ EndTime.
        EndTime:
          type: string
          format: date-time
          description: Fim.
        ScheduleTitle:
          type: string
          nullable: true
          description: Título amigável (livre, máx. 100).
        Comments:
          type: string
          nullable: true
          description: Observações (livre, máx. 500).
        IDPurchase:
          type: integer
          nullable: true
          description: Recebimento a amarrar. Vazio = agendamento avulso. Não pode estar já agendado.
    PurchaseScheduleConfigTimetable:
      type: object
      description: Faixa de horário disponível em um dia da semana.
      required:
        - WeekDay
        - StartTime
        - EndTime
      properties:
        WeekDay:
          type: integer
          minimum: 0
          maximum: 6
          description: 'Dia da semana: 0=Domingo, 1=Segunda, 2=Terça, 3=Quarta, 4=Quinta, 5=Sexta, 6=Sábado.'
        StartTime:
          type: string
          description: Horário de início (`HH:MM:SS`).
        EndTime:
          type: string
          description: Horário de término (`HH:MM:SS`). Precisa ser maior que `StartTime`.
    PurchaseScheduleConfigItem:
      type: object
      description: Configuração de agendamento como devolvida por `GET /purchase/schedule/config`.
      properties:
        AccountName:
          type: string
          description: Subdomínio da empresa dona da configuração.
        IDStockKeepingUnitPurchaseScheduleConfig:
          type: integer
          description: Identificador da configuração.
        IDCompany:
          type: integer
          description: Identificador da empresa dona da configuração.
        RecordTimestamp:
          type: string
          format: date-time
          description: Quando a configuração foi criada.
        IDStockKeepingUnitDistributionCenter:
          type: integer
          description: Centro de distribuição ao qual a configuração se aplica. Cada CD aceita no máximo uma configuração.
        DistributionCenterName:
          type: string
          description: Nome do centro de distribuição.
        ScheduleDurationMinutes:
          type: string
          description: >-
            Duração de cada janela de agendamento (`HH:MM:SS`). Operações de pequeno volume costumam usar 30 min; grande
            volume usa 2h ou mais.
        MaxItemsPerDay:
          type: integer
          nullable: true
          description: Quantidade máxima de **itens** (unidades de produto) que o CD aceita receber em um único dia.
        MaxSchedulePerDay:
          type: integer
          nullable: true
          description: Quantidade máxima de **agendamentos** (notas fiscais) que o CD aceita em um único dia.
        ScheduleMaximumTimeAheadDay:
          type: integer
          nullable: true
          description: >-
            Quantos dias à frente o agendamento fica disponível. Ex.: `60` = a partir de hoje, pode marcar até daqui a
            60 dias.
        ScheduleMinimumAdvanceTimeHour:
          type: integer
          nullable: true
          description: >-
            Antecedência mínima em **horas** para marcar um agendamento. Ex.: `2` = agendamento só pode ser marcado para
            começar daqui a 2h ou mais.
        HourDifferenceAllowed:
          type: string
          nullable: true
          description: >-
            Tempo de tolerância (`HH:MM:SS`) entre o horário do agendamento e a chegada/check-in. Ex.: `00:30:00` = o
            check-in pode acontecer até 30 min depois do horário marcado sem ser considerado atrasado.
        StockKeepingUnitPurchaseScheduleConfigTimetable:
          type: array
          items:
            $ref: '#/components/schemas/PurchaseScheduleConfigTimetable'
          description: Quadro de horários disponíveis por dia da semana, ordenado por `WeekDay` e `StartTime`.
    PurchaseScheduleConfigCreate:
      type: object
      description: Corpo do `POST /purchase/schedule/config`. Cria uma configuração de agendamento para um CD.
      required:
        - IDStockKeepingUnitDistributionCenter
        - ScheduleDurationMinutes
      properties:
        IDStockKeepingUnitDistributionCenter:
          type: integer
          description: CD destino. Cada CD pode ter no máximo 1 configuração.
        ScheduleDurationMinutes:
          type: integer
          description: >-
            Duração de cada janela em minutos (o frontend converte de "2h", "30m", "1h30" para minutos antes de enviar).
            O sistema grava no campo TIME.
        MaxItemsPerDay:
          type: integer
          nullable: true
          description: >-
            Quantidade máxima de itens (unidades de produto) que o CD aceita receber em um único dia. Sem limite quando
            vazio.
        MaxSchedulePerDay:
          type: integer
          nullable: true
          description: Quantidade máxima de agendamentos (notas fiscais) que o CD aceita em um único dia. Sem limite quando vazio.
        ScheduleMaximumTimeAheadDay:
          type: integer
          nullable: true
          description: Janela em dias para frente em que o agendamento aceita marcações.
        ScheduleMinimumAdvanceTimeHour:
          type: integer
          nullable: true
          description: Antecedência mínima em horas.
        HourDifferenceAllowed:
          type: integer
          nullable: true
          description: Tolerância em minutos (frontend converte para `HH:MM:SS` no banco).
        StockKeepingUnitPurchaseScheduleConfigTimetable:
          type: array
          items:
            $ref: '#/components/schemas/PurchaseScheduleConfigTimetable'
          description: >-
            Faixas de horário por dia da semana. Quando omitido, a configuração é criada sem horários (sem
            disponibilidade).
    PurchaseScheduleConfigUpdate:
      type: object
      description: >-
        Corpo do `PUT /purchase/schedule/config/{id}`. Atualização parcial. Para
        `StockKeepingUnitPurchaseScheduleConfigTimetable`: enviar `[]` apaga todas as faixas; array preenchido substitui
        em bloco.
      properties:
        IDStockKeepingUnitDistributionCenter:
          type: integer
          description: Centro de distribuição alvo. Não pode coincidir com outro CD que já tenha configuração.
        ScheduleDurationMinutes:
          type: integer
          description: >-
            Duração de cada janela de agendamento em minutos. O frontend converte strings como `2h`, `30m`, `1h30` para
            minutos antes de enviar; o sistema grava em campo `TIME`.
        MaxItemsPerDay:
          type: integer
          nullable: true
          description: >-
            Quantidade máxima de itens (unidades de produto) que o CD aceita receber em um único dia. Sem limite quando
            vazio.
        MaxSchedulePerDay:
          type: integer
          nullable: true
          description: Quantidade máxima de agendamentos (notas fiscais) que o CD aceita em um único dia. Sem limite quando vazio.
        ScheduleMaximumTimeAheadDay:
          type: integer
          nullable: true
          description: 'Janela de dias à frente em que o agendamento aceita marcações. Ex.: `60` = de hoje até daqui a 60 dias.'
        ScheduleMinimumAdvanceTimeHour:
          type: integer
          nullable: true
          description: >-
            Antecedência mínima em horas para marcar um agendamento. Ex.: `2` = só pode marcar para começar daqui a 2h
            ou mais.
        HourDifferenceAllowed:
          type: integer
          nullable: true
          description: >-
            Tolerância entre o horário marcado e a chegada/check-in. O frontend envia em minutos; o sistema grava em
            `TIME` (`HH:MM:SS`).
        StockKeepingUnitPurchaseScheduleConfigTimetable:
          type: array
          items:
            $ref: '#/components/schemas/PurchaseScheduleConfigTimetable'
          description: >-
            Quadro de horários disponíveis por dia da semana. **Não enviado** = mantém o quadro atual. **Array vazio**
            (`[]`) = apaga todas as faixas (agendamento fica indisponível). **Array preenchido** = substitui em bloco
            (DELETE + INSERT).
    TypePickingListEnum:
      type: integer
      description: |-
        Tipo de picking list:
        - `1` — Picking: somente separação; o faturamento acontece depois.
        - `2` — Picking & Packing: separação + emissão da nota no mesmo passo (impressora sem fio).
        - `3` — Monopedido: cada picking list contém **um único pedido**.
        - `4` — Colméia: tipo cadastrado na tabela mas hoje não exposto no formulário da tela.
      enum:
        - 1
        - 2
        - 3
        - 4
    PickingListConfigurationItem:
      type: object
      description: >-
        Configuração de picking list como devolvida por `GET /fulfillment/picking/configuration`. Campos CSV
        (`IDCompanyIntegrationList`, `IDOrderTypeList`, `IDCarrierList`, `WeekIntervalAutoGenerate`) vêm já em formato
        `array`.
      properties:
        AccountName:
          type: string
          description: Identificador da empresa dona da configuração.
        IDPickingListConfiguration:
          type: integer
          description: Identificador da configuração.
        IDCompany:
          type: integer
          description: Identificador interno da empresa dona da configuração.
        PickingListConfigurationName:
          type: string
          maxLength: 500
          description: Nome da configuração (único por empresa).
        PickingListConfigurationStatus:
          type: integer
          enum:
            - 0
            - 1
          description: '`1`=Ativa (entra na geração automática), `0`=Inativa.'
        IDStockKeepingUnitDistributionCenter:
          type: integer
          description: Identificador do CD a que a configuração se aplica.
        DistributionCenterName:
          type: string
          description: Nome amigável do CD.
        IDTypePickingList:
          $ref: '#/components/schemas/TypePickingListEnum'
          description: 'Tipo de picking-list: `1` Picking, `2` Picking & Packing, `3` Monopedido, `4` Colméia.'
        TypePickingList:
          type: string
          description: Nome amigável do tipo.
        PickingPriority:
          type: integer
          minimum: 0
          maximum: 10
          nullable: true
          description: >-
            Prioridade desta configuração (0=mais alta, 10=mais baixa). Quando há mais de uma configuração competindo,
            executa primeiro a de menor prioridade.
        OrderPriority:
          type: integer
          minimum: 0
          maximum: 10
          nullable: true
          description: Filtra `OrderPriority` para essa configuração (0=mais alta, 10=mais baixa).
        OrderCreateTimeLimit:
          type: string
          nullable: true
          description: >-
            Horário-limite de criação do pedido (`HH:MM:SS`). Apenas pedidos criados até esse horário no dia entram
            automaticamente.
        IDCompanyIntegrationList:
          type: array
          items:
            type: string
          description: Lista de integrações que a configuração processa. Vazio = todas.
        IDOrderTypeList:
          type: array
          items:
            type: string
          description: Lista de tipos de pedido. Vazio = todos.
        IDCarrierList:
          type: array
          items:
            type: string
          description: Lista de transportadoras. Vazio = todas.
        ItemsQtyLimit:
          type: integer
          nullable: true
          description: Limite de unidades (somando todos os SKUs) por picking list gerada.
        OrderQtyLimit:
          type: integer
          nullable: true
          description: Limite de pedidos por picking list gerada.
        SkuQtyLimit:
          type: integer
          nullable: true
          description: Limite de SKUs diferentes por picking list gerada.
        PickingListBasketLimit:
          type: integer
          nullable: true
          description: Limite de cestos por picking list (usado em operações com cesto picking — ver Cesto Picking).
        StartAutoGenerateTime:
          type: string
          description: Horário de início da janela diária (`HH:MM:SS`).
        FinishAutoGenerateTime:
          type: string
          description: Horário de fim da janela diária (`HH:MM:SS`). Precisa ser ≥ `StartAutoGenerateTime`.
        IntervalAutoGenerateTime:
          type: string
          nullable: true
          description: 'Intervalo entre execuções (`HH:MM:SS`). Ex.: `02:00:00` = roda de 2 em 2 horas dentro da janela.'
        WeekIntervalAutoGenerate:
          type: array
          items:
            type: string
          description: Dias da semana em que roda (0=Domingo … 6=Sábado).
        AutoGenerateLastTime:
          type: string
          format: date-time
          nullable: true
          description: Última vez que o sistema executou essa configuração.
        AutoGenerateNextTime:
          type: string
          format: date-time
          nullable: true
          description: Próxima execução agendada.
        UniqueSku:
          type: integer
          enum:
            - 0
            - 1
          description: Flag interna — quando `1`, lista é exclusiva de pedidos com 1 SKU único.
        PreferLocationMoreQuantity:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            Quando `1`, na escolha de endereço de coleta o sistema prioriza o endereço com **maior saldo** para o SKU
            (esvaziando endereços antes); `0` mantém a regra padrão (endereço fixo / primeiro com saldo).
        IgnorePickingPreferenceByAllowResupplyLocation:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: >-
            Quando `1`, ignora a regra global `PickingPreferenceByAllowResupplyLocation` ao montar a coleta — endereços
            de ressuprimento podem ser usados como origem mesmo sem pacote completo. `null` herda o comportamento padrão
            da empresa.
    PickingListConfigurationCreate:
      type: object
      description: >-
        Corpo do `POST /fulfillment/picking/configuration`. Listas (`IDCompanyIntegrationList`, `IDOrderTypeList`,
        `IDCarrierList`, `WeekIntervalAutoGenerate`) podem ser arrays ou strings CSV.
      required:
        - PickingListConfigurationName
        - IDStockKeepingUnitDistributionCenter
        - StartAutoGenerateTime
        - FinishAutoGenerateTime
      properties:
        PickingListConfigurationName:
          type: string
          maxLength: 500
          description: Nome único por empresa.
        IDStockKeepingUnitDistributionCenter:
          type: integer
          description: Identificador do CD a que a configuração se aplica. Precisa pertencer à empresa.
        IDTypePickingList:
          $ref: '#/components/schemas/TypePickingListEnum'
          description: 'Tipo de picking-list: `1` Picking, `2` Picking & Packing, `3` Monopedido, `4` Colméia.'
        PickingListConfigurationStatus:
          type: integer
          enum:
            - 0
            - 1
          description: Default `1` (Ativa).
        PickingPriority:
          type: integer
          minimum: 0
          maximum: 10
          nullable: true
          description: >-
            Prioridade da configuração na resolução automática (0=mais alta, 10=mais baixa). Quando dois pedidos casam
            em mais de uma configuração, vence a que tem menor `PickingPriority`.
        OrderPriority:
          type: integer
          minimum: 0
          maximum: 10
          nullable: true
          description: >-
            Prioridade gravada nas picking-lists geradas (0=mais alta, 10=mais baixa). É a prioridade que aparece para o
            separador na fila de coleta.
        OrderCreateTimeLimit:
          type: string
          nullable: true
          description: '`HH:MM:SS` — pedidos criados até este horário no dia entram automaticamente.'
        IDCompanyIntegrationList:
          oneOf:
            - type: array
              items:
                type: integer
            - type: string
          description: >-
            Lista de integrações (canais de venda) atendidas por esta configuração. Vazio = todas as integrações da
            empresa. Aceita array de inteiros ou string CSV.
        IDTypeOrderList:
          oneOf:
            - type: array
              items:
                type: integer
            - type: string
          description: >-
            Lista de tipos de pedido atendidos por esta configuração. Vazio = todos os tipos. Aceita array de inteiros
            ou string CSV.
        IDCarrierList:
          oneOf:
            - type: array
              items:
                type: integer
            - type: string
          description: >-
            Lista de transportadoras atendidas por esta configuração. Vazio = todas. Aceita array de inteiros ou string
            CSV. Cada item precisa ser um fornecedor da empresa do tipo Transportadora.
        ItemsQtyLimit:
          type: integer
          nullable: true
          description: >-
            Quantidade máxima de itens (somatório de unidades) por picking-list gerada. Quando atingido, o sistema fecha
            a lista e abre uma nova. `null` = sem limite.
        OrderQtyLimit:
          type: integer
          nullable: true
          description: >-
            Quantidade máxima de pedidos por picking-list gerada. Pode ser sobrescrito pelo query param `OrderQtyLimit`
            no `POST /fulfillment/picking`. `null` = sem limite.
        SkuQtyLimit:
          type: integer
          nullable: true
          description: Quantidade máxima de SKUs distintos por picking-list gerada. `null` = sem limite.
        PickingListBasketLimit:
          type: integer
          nullable: true
          description: >-
            Quantidade máxima de cestos disponíveis para esta configuração — usado para dimensionar quantos pedidos
            cabem em paralelo na esteira. `null` = sem limite.
        StartAutoGenerateTime:
          type: string
          description: Horário de início da janela diária (`HH:MM:SS`).
        FinishAutoGenerateTime:
          type: string
          description: Horário de fim da janela diária. Precisa ser ≥ `StartAutoGenerateTime`.
        IntervalAutoGenerateTime:
          type: string
          nullable: true
          description: >-
            Intervalo entre execuções da geração automática dentro da janela (`HH:MM:SS`). Ex.: `00:30:00` roda a cada
            30 minutos. `null` = roda uma vez no início da janela.
        WeekIntervalAutoGenerate:
          oneOf:
            - type: array
              items:
                type: integer
                minimum: 0
                maximum: 6
            - type: string
          description: Dias da semana (0=Domingo … 6=Sábado). Vazio = todos os dias.
    PickingListConfigurationUpdate:
      allOf:
        - $ref: '#/components/schemas/PickingListConfigurationCreate'
      description: Mesmo schema do create, mas todos os campos são opcionais — atualização parcial.
    SkuLocationListItem:
      type: object
      description: Endereço como devolvido pelo `GET /sku/location?OnlyLocation=1`.
      properties:
        AccountName:
          type: string
          description: Conta (subdomínio) da empresa.
        IDStockKeepingUnitLocation:
          type: integer
          description: Identificador do endereço.
        Address:
          type: string
          description: Nome do endereço (no modo WMS é a concatenação `Andar-Rua-Módulo-Coluna-Nível`).
        Status:
          type: integer
          enum:
            - 0
            - 1
          description: '`1`=Ativo, `0`=Inativo.'
        IDStockKeepingUnitWarehouse:
          type: integer
          description: Depósito onde fica o endereço.
        WarehouseName:
          type: string
          description: Nome do depósito.
        IDStockKeepingUnitDistributionCenter:
          type: integer
          nullable: true
          description: Centro de distribuição.
        DistributionCenterName:
          type: string
          nullable: true
          description: Nome do centro de distribuição.
        Default:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` quando é o endereço padrão do armazém (apenas um por armazém).'
        AddressPriority:
          type: integer
          description: Prioridade de ordenação na picking-list. Menor = maior prioridade.
        Floor:
          type: string
          nullable: true
          description: Andar (WMS).
        Street:
          type: string
          nullable: true
          description: Rua/Corredor (WMS).
        Module:
          type: string
          nullable: true
          description: Módulo / Bloco (WMS). Numérico.
        Column:
          type: string
          nullable: true
          description: Coluna (WMS). Alfanumérico — letras viram maiúsculas.
        Level:
          type: string
          nullable: true
          description: Nível / Andar da prateleira (WMS). Numérico.
        Height:
          type: number
          format: double
          nullable: true
          description: Altura em cm (WMS).
        Width:
          type: number
          format: double
          nullable: true
          description: Largura em cm (WMS).
        Length:
          type: number
          format: double
          nullable: true
          description: Comprimento em cm (WMS).
        MaxWeight:
          type: number
          format: double
          nullable: true
          description: Peso máximo suportado em kg (WMS).
        IDTypeAddress:
          type: integer
          nullable: true
          enum:
            - 1
            - 2
            - 3
          description: 'Tipo de endereço de armazenagem: `1` Picking, `2` Pulmão, `3` Blocado.'
        TypeAddress:
          type: string
          nullable: true
          description: Nome do tipo (`Picking`, `Pulmão`, `Blocado`).
        IDStockKeepingUnitLocationCategory:
          type: integer
          nullable: true
          description: Categoria do endereço.
        StockKeepingUnitLocationCategoryName:
          type: string
          nullable: true
          description: Nome da categoria.
        IDStockKeepingUnitLocationGroup:
          type: integer
          nullable: true
          description: Grupo de endereços.
        StockKeepingUnitLocationGroupName:
          type: string
          nullable: true
          description: Nome do grupo de endereços.
        LocationSide:
          type: integer
          nullable: true
          enum:
            - 1
            - 2
          description: '`1`=Direito, `2`=Esquerdo.'
        AllowRessuply:
          type: integer
          enum:
            - 0
            - 1
          description: '`1`=Permite que tarefa de ressuprimento direcione SKU para este endereço.'
        StockKeepingUnitLocationIndex:
          type: integer
          description: Número sequencial gerado pela query.
    SkuLocationBatchItem:
      type: object
      description: >-
        Endereço × lote como devolvido pelo `GET /sku/location` (sem `OnlyLocation`). Uma linha por lote vinculado ao
        endereço.
      properties:
        AccountName:
          type: string
          description: Subdomínio (conta) da empresa dona do endereço.
        IDStockKeepingUnitLocation:
          type: integer
          description: Identificador do endereço de armazenagem.
        Address:
          type: string
          description: Texto do endereço de armazenagem (`Floor-Street-Module-Column-Level` ou nome livre).
        AddressSku:
          type: string
          description: 'Quando há lote: `Endereço | Código SKU | IDSku | Nome do produto`; quando não, é só `Address`.'
        IDStockKeepingUnitWarehouse:
          type: integer
          description: Armazém ao qual o endereço pertence.
        WarehouseName:
          type: string
          description: Nome do armazém.
        Default:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            `1` quando o endereço é o padrão do armazém (usado como destino quando nenhum endereço específico é
            informado); `0` caso contrário.
        AddressPriority:
          type: integer
          description: Prioridade do endereço na sugestão de separação/armazenagem (menor número = maior prioridade).
        IDBatchNumber:
          type: integer
          nullable: true
          description: Lote do SKU armazenado neste endereço. Vazio quando o endereço não tem saldo deste SKU em lote.
        IDSku:
          type: integer
          nullable: true
          description: SKU armazenado no endereço (quando consultado por SKU). Vazio quando o endereço está vago.
        IDSkuCompany:
          type: string
          nullable: true
          description: Código de referência do SKU.
        SkuName:
          type: string
          nullable: true
          description: Nome do SKU armazenado.
        BarCode:
          type: string
          nullable: true
          description: Código de barras principal do SKU armazenado.
        BestBeforeDate:
          type: string
          format: date
          nullable: true
          description: >-
            Data de validade do lote armazenado, no formato `YYYY-MM-DD`. Vazio quando o SKU não usa controle de
            validade.
        QtyAddress:
          type: number
          description: >-
            Saldo do lote no endereço, calculado por soma de `StockKeepingUnitMovement` (`IDTypeMovement=0` entradas,
            `IDTypeMovement=1` saídas).
        Floor:
          type: string
          nullable: true
          description: Componente `Andar` do endereço estruturado.
        Street:
          type: string
          nullable: true
          description: Componente `Rua` do endereço estruturado.
        Module:
          type: string
          nullable: true
          description: Componente `Módulo` do endereço estruturado.
        Column:
          type: string
          nullable: true
          description: Componente `Coluna` do endereço estruturado.
        Level:
          type: string
          nullable: true
          description: Componente `Nível` do endereço estruturado.
        Height:
          type: number
          nullable: true
          description: Altura útil do endereço em cm.
        Width:
          type: number
          nullable: true
          description: Largura útil do endereço em cm.
        Length:
          type: number
          nullable: true
          description: Profundidade útil do endereço em cm.
        MaxWeight:
          type: number
          nullable: true
          description: Peso máximo suportado pelo endereço em kg.
        IDTypeAddress:
          type: integer
          nullable: true
          description: 'Tipo de endereço de armazenagem: `1` Picking, `2` Pulmão, `3` Blocado.'
          enum:
            - 1
            - 2
            - 3
        TypeAddress:
          type: string
          nullable: true
          description: Descrição amigável do tipo do endereço.
        IDStockKeepingUnitLocationCategory:
          type: integer
          nullable: true
          description: 'Categoria do endereço (agrupamento configurável — ex.: refrigerados, perigosos, frágeis).'
        StockKeepingUnitLocationCategoryName:
          type: string
          nullable: true
          description: Nome da categoria do endereço.
    SkuLocationCreate:
      type: object
      description: >-
        Corpo do `POST /sku/location`. Os campos relevantes dependem do parâmetro `NewAddressParameter` (modo WMS ou
        legado).
      properties:
        Address:
          type: string
          description: >-
            **Modo legado**: obrigatório. Modo WMS: ignorado — o sistema monta a partir de
            Andar/Rua/Módulo/Coluna/Nível.
        IDStockKeepingUnitWarehouse:
          type: integer
          description: Armazém destino. Obrigatório no modo WMS; opcional no legado.
        Default:
          type: integer
          enum:
            - 0
            - 1
          description: 'Modo legado: marca como endereço padrão (zera os demais do armazém). Default 0.'
        AddressPriority:
          type: integer
          description: Prioridade para ordenação na picking-list (menor = primeiro).
        Floor:
          type: string
          description: Modo WMS — Andar. Obrigatório no cadastro individual.
        Street:
          type: string
          description: Modo WMS — Rua/Corredor. Obrigatório no cadastro individual.
        Module:
          type: string
          description: Modo WMS individual — Módulo (numérico).
        Column:
          type: string
          description: Modo WMS individual — Coluna (alfanumérico).
        Level:
          type: string
          description: Modo WMS individual — Nível (numérico).
        Height:
          type: number
          description: Altura em cm — obrigatório no WMS, deve ser `> 0`.
        Width:
          type: number
          description: Largura em cm — obrigatório no WMS, deve ser `> 0`.
        Length:
          type: number
          description: Comprimento em cm — obrigatório no WMS, deve ser `> 0`.
        MaxWeight:
          type: number
          description: Peso máximo em kg — obrigatório no WMS, deve ser `> 0`.
        IDTypeAddress:
          type: integer
          enum:
            - 1
            - 2
            - 3
          description: 'Tipo de endereço de armazenagem: `1` Picking, `2` Pulmão, `3` Blocado.'
        IDStockKeepingUnitLocationCategory:
          type: integer
          description: Obrigatório no WMS. Categoria de endereço (precisa estar ativa).
        IDStockKeepingUnitLocationGroup:
          type: integer
          nullable: true
          description: >-
            Grupo de endereços ao qual a posição física pertence (agrupa endereços com características comuns, como
            mesma rua).
        LocationSide:
          type: integer
          enum:
            - 1
            - 2
          description: 'Lado da rua: `1`=Direito, `2`=Esquerdo (WMS).'
        AllowRessuply:
          type: integer
          enum:
            - 0
            - 1
          description: Default `1`.
        Status:
          type: integer
          enum:
            - 0
            - 1
          description: Default `1`.
        BulkLocation:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` ativa o cadastro em massa por faixas (WMS). Default `0`.'
        StartModule:
          type: string
          description: Cadastro em massa — primeiro módulo (numérico).
        EndModule:
          type: string
          description: Cadastro em massa — último módulo (numérico). Precisa ser ≥ `StartModule`.
        StartColumn:
          type: string
          description: >-
            Cadastro em massa — primeira coluna. Aceita letras (A-Z) ou números; quando letras, `EndColumn` precisa
            estar no mesmo intervalo do alfabeto.
        EndColumn:
          type: string
          description: Cadastro em massa — última coluna. Precisa ser ≥ `StartColumn`.
        StartLevel:
          type: string
          description: Cadastro em massa — primeiro nível (numérico).
        EndLevel:
          type: string
          description: Cadastro em massa — último nível (numérico). Precisa ser ≥ `StartLevel`.
        Concatenator:
          type: string
          enum:
            - '-'
            - .
            - '|'
          description: Caractere usado para juntar Andar/Rua/Módulo/Coluna/Nível no `Address`. Default `-`.
    SkuLocationUpdate:
      type: object
      description: >-
        Corpo do `PUT /sku/location/{idstockkeepingunitlocation}`. Atualização parcial — só os campos enviados são
        alterados.
      properties:
        Address:
          type: string
          description: >-
            Identificação textual completa do endereço (gerada por concatenação de `Floor`, `Street`, `Module`,
            `Column`, `Level`).
        IDStockKeepingUnitWarehouse:
          type: integer
          description: Mudança bloqueada quando o endereço tem movimento.
        Default:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` define este endereço como padrão para o depósito.'
        AddressPriority:
          type: integer
          description: Prioridade do endereço na seleção automática durante o picking — menor valor é tentado primeiro.
        Floor:
          type: string
          description: Andar/piso do endereço.
        Street:
          type: string
          description: Rua/corredor do endereço.
        Module:
          type: string
          description: Módulo (estante) do endereço.
        Column:
          type: string
          description: Coluna do endereço.
        Level:
          type: string
          description: Nível (prateleira) do endereço.
        Height:
          type: number
          description: Altura útil do endereço em cm.
        Width:
          type: number
          description: Largura útil em cm.
        Length:
          type: number
          description: Profundidade útil em cm.
        MaxWeight:
          type: number
          description: Capacidade máxima de peso em kg.
        IDTypeAddress:
          type: integer
          enum:
            - 1
            - 2
            - 3
          description: 'Tipo de endereço de armazenagem: `1` Picking, `2` Pulmão, `3` Blocado.'
        IDStockKeepingUnitLocationCategory:
          type: integer
          description: Categoria do endereço (agrupamento por tipo de SKU permitido).
        IDStockKeepingUnitLocationGroup:
          type: integer
          nullable: true
          description: Grupo de endereços ao qual a posição pertence.
        LocationSide:
          type: integer
          enum:
            - 1
            - 2
          description: 'Lado do corredor: `1` esquerda, `2` direita (usado para roteirizar o picking).'
        AllowRessuply:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` permite que o endereço seja origem ou destino de ressuprimento; `0` bloqueia.'
        Status:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` endereço ativo; `0` desativado.'
    SkuLocationGroupListItem:
      type: object
      description: Grupo de endereços do estoque.
      properties:
        IDStockKeepingUnitLocationGroup:
          type: integer
          description: Identificador do grupo de endereços.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora de criação do grupo.
        IDCompany:
          type: integer
          description: Identificador da empresa.
        StockKeepingUnitLocationGroupName:
          type: string
          maxLength: 100
          description: Nome do grupo de endereços.
        AccountName:
          type: string
          description: Conta (subdomínio) da empresa.
    SkuLocationGroupCreate:
      type: object
      description: Corpo do `POST /sku/location/group` e do `PUT`.
      required:
        - StockKeepingUnitLocationGroupName
      properties:
        StockKeepingUnitLocationGroupName:
          type: string
          maxLength: 100
          description: Nome do grupo. Único por empresa.
    UserWorkShiftItem:
      type: object
      description: Turno cadastrado dentro da escala vinculada ao colaborador.
      properties:
        IDUserWorkShift:
          type: integer
          description: >-
            Identificador do turno de trabalho cadastrado para a empresa (referência usada na escala de jornada do
            colaborador).
        WeekDay:
          type: integer
          description: Dia da semana (0=Domingo ... 6=Sábado, conforme cadastro).
        StartTime:
          type: string
          description: Início do turno (`HH:MM:SS`).
        FinishTime:
          type: string
          description: Fim do turno.
    UserJobPositionRef:
      type: object
      properties:
        IDUserJobPosition:
          type: integer
          description: Identificador do cargo do usuário (referência ao cadastro de cargos da empresa).
        UserJobPositionName:
          type: string
          description: 'Nome do cargo (ex.: `Operador de logística`, `Conferente`, `Gerente`).'
    SkuLocationCategoryRef:
      type: object
      properties:
        IDStockKeepingUnitLocationCategory:
          type: integer
          description: Identificador da categoria de endereço de armazenagem.
        StockKeepingUnitLocationCategoryName:
          type: string
          description: Nome da categoria de endereço.
    SkuLocationGroupRef:
      type: object
      properties:
        IDStockKeepingUnitLocationGroup:
          type: integer
          description: Identificador do grupo de endereços de armazenagem (agrupamento usado para escalas/restrições de operação).
        StockKeepingUnitLocationGroupName:
          type: string
          description: Nome do grupo de endereços.
    UserWorkingDayListItem:
      type: object
      description: Item de `GET /user/workingday`.
      properties:
        AccountName:
          type: string
          description: Identificador (subdomínio) da empresa do colaborador.
        IDUserWorkingDay:
          type: integer
          description: Identificador do cadastro de colaborador.
        IDUser:
          type: integer
          description: Identificador do usuário associado.
        UserName:
          type: string
          description: Nome do colaborador.
        LastActivityTimestamp:
          type: string
          format: date-time
          nullable: true
          description: Último login/atividade do usuário.
        IDAcess:
          type: integer
          description: Vínculo do usuário com a empresa (`IDAcess`).
        Status:
          type: integer
          enum:
            - 1
            - 2
          description: '`1`=Ativo, `2`=Inativo.'
        IDUserWorkScale:
          type: integer
          description: Identificador da escala de trabalho vigente.
        UserWorkScaleName:
          type: string
          description: Nome da escala.
        WorkShift:
          type: array
          items:
            $ref: '#/components/schemas/UserWorkShiftItem'
          description: 'Turnos da escala (mesmo shape de `UserWorkShiftItem`): dia da semana e janela de horário.'
        IDUserJobPositionList:
          type: string
          nullable: true
          description: CSV de `IDUserJobPosition`.
        JobPositions:
          type: array
          items:
            $ref: '#/components/schemas/UserJobPositionRef'
          description: Funções que o colaborador pode exercer (`UserJobPositionRef`).
        IDUserJobPositionCurrent:
          type: integer
          nullable: true
          description: Função ativa no momento.
        CurrentPositionName:
          type: string
          nullable: true
          description: Nome da função ativa (resolvido pelo sistema).
        IDUserUpper:
          type: integer
          nullable: true
          description: Identificador do colaborador supervisor.
        UserUpperName:
          type: string
          nullable: true
          description: Nome do supervisor.
        Categories:
          type: array
          items:
            $ref: '#/components/schemas/SkuLocationCategoryRef'
          description: Categorias de endereço atendidas pelo colaborador (`SkuLocationCategoryRef`).
        LocationsGroup:
          type: array
          items:
            $ref: '#/components/schemas/SkuLocationGroupRef'
          description: Grupos de endereço atendidos pelo colaborador (`SkuLocationGroupRef`).
    UserWorkingDayCreate:
      type: object
      description: Corpo do `POST /user/workingday`. Listas CSV (string com ids separados por vírgula).
      required:
        - IDUser
        - IDUserJobPositionList
        - IDUserWorkScale
      properties:
        IDUser:
          type: integer
          description: Usuário já cadastrado no sistema. Precisa ter vínculo com a empresa (`UserCompany`).
        IDUserJobPositionList:
          type: string
          description: CSV de `IDUserJobPosition` — funções que o colaborador pode exercer.
        IDUserJobPositionCurrent:
          type: integer
          nullable: true
          description: Função ativa no momento — precisa estar dentro de `IDUserJobPositionList`.
        IDUserWorkScale:
          type: integer
          description: Escala de trabalho (cadastrada em **Turnos dos Colaboradores**).
        IDUserUpper:
          type: integer
          nullable: true
          description: '`IDUserWorkingDay` do supervisor.'
        IDStockKeepingUnitLocationCategoryList:
          type: string
          nullable: true
          description: >-
            CSV de `IDStockKeepingUnitLocationCategory` — categorias de endereço atendidas pelo colaborador (precisam
            estar ativas: `IsActive = 1`).
        IDStockKeepingUnitLocationGroupList:
          type: string
          nullable: true
          description: CSV de `IDStockKeepingUnitLocationGroup` — grupos de endereço atendidos pelo colaborador.
    UserWorkingDayUpdate:
      type: object
      description: >-
        Corpo do `PUT /user/workingday/{idworkingday}`. Atualização parcial — campos ausentes ficam intactos. Para
        limpar `IDStockKeepingUnitLocationCategoryList`, `IDStockKeepingUnitLocationGroupList` ou `IDUserUpper` enviar
        string vazia.
      properties:
        IDUser:
          type: integer
          description: Usuário cujo cadastro de colaborador será atualizado. Precisa pertencer à empresa autenticada.
        IDUserJobPositionList:
          type: string
          description: CSV de identificadores de função que o colaborador pode exercer. Lista substitui a anterior.
        IDUserJobPositionCurrent:
          type: integer
          nullable: true
          description: >-
            Função ativa do colaborador no momento — precisa estar dentro de `IDUserJobPositionList`. Envie `null` para
            limpar.
        IDUserWorkScale:
          type: integer
          description: Identificador da escala de trabalho (`UserWorkScale`) vigente.
        IDUserUpper:
          type: integer
          nullable: true
          description: >-
            Identificador do colaborador (`UserWorkingDay`) supervisor. String vazia limpa o campo. Colaborador não pode
            ser seu próprio supervisor.
        IDStockKeepingUnitLocationCategoryList:
          type: string
          nullable: true
          description: CSV de categorias de endereço atendidas pelo colaborador. String vazia limpa o campo.
        IDStockKeepingUnitLocationGroupList:
          type: string
          nullable: true
          description: CSV de grupos de endereço atendidos pelo colaborador. String vazia limpa o campo.
        Status:
          type: integer
          enum:
            - 1
            - 2
          description: 'Status do colaborador: `1` Ativo, `2` Inativo.'
    CarrierQuotationRuleUpdate:
      type: object
      description: >-
        Corpo do `PUT /carrier/quotation/rule/{idcarrierquotationrule}`. **Não é atualização parcial** — campos do
        cabeçalho ausentes são gravados como NULL. Recomenda-se enviar o cabeçalho inteiro. `Conditions` segue diff:
        condições novas são inseridas, ausentes são removidas.
      properties:
        CarrierQuotationRuleName:
          type: string
          description: Nome da regra (exibido na grid).
        Priority:
          type: integer
          minimum: 1
          description: Ordem de execução. Menor valor é avaliado primeiro.
        Status:
          type: integer
          enum:
            - 0
            - 1
          description: '`1`=Ativo, `0`=Inativo. Use o DELETE para soft delete (`Status=2`).'
        DateFrom:
          type: string
          format: date
          description: >-
            Início da vigência (`YYYY-MM-DD`). Quando a UI desliga o switch "Possui vigência", o frontend envia
            `1900-01-01`.
        DateTo:
          type: string
          format: date
          description: >-
            Fim da vigência (`YYYY-MM-DD`). Quando o switch "Possui vigência" é desligado, o frontend envia
            `4000-01-01`.
        IDTypeCarrierQuotationActionRule:
          $ref: '#/components/schemas/CarrierQuotationActionRuleEnum'
          description: >-
            Tipo de ação aplicada quando todas as condições da regra são atendidas. Valores em
            `CarrierQuotationActionRuleEnum`.
        ActionValue:
          type: string
          nullable: true
          description: >-
            Valor associado à ação. Mesmas regras do `POST`: decimal em string para R$ (`2`, `6`, `10`), percentual para
            `%` (`3`, `5`, `7`), inteiro de dias para prazo (`1`, `13`), `null` para ação `9` (Excluir transportadoras).
        Conditions:
          type: array
          items:
            $ref: '#/components/schemas/CarrierQuotationConditionPayload'
          description: >-
            Lista de condições da regra. Diff é aplicado: condições ausentes são removidas, novas são inseridas. Cada
            item segue `CarrierQuotationConditionPayload`.
    CollectionListListItem:
      type: object
      description: >-
        Item de lista de romaneios. Vem do endpoint `GET /fulfillment/packing/collection-list` e também é retornado
        pelos endpoints que invocam o `List` internamente (close, open, file, merge).
      properties:
        IDOrdersCarrierCollectionList:
          type: integer
          format: int64
          description: Identificador único do romaneio (identificador em `OrdersCarrierCollectionList`).
        AccountName:
          type: string
          description: Prefixo da conta (subdomínio idworks) à qual o romaneio pertence.
        AccountNameDistributionCenter:
          type: string
          nullable: true
          description: Prefixo da conta do CD (`StockKeepingUnitDistributionCenter` quando aplicável).
        IDStockKeepingUnitDistributionCenter:
          type: integer
          format: int64
          nullable: true
          description: Identificador do CD onde o romaneio foi criado.
        DistributionCenterName:
          type: string
          nullable: true
          description: Nome do CD.
        Login:
          type: string
          nullable: true
          description: Login do usuário que criou o romaneio.
        UserName:
          type: string
          nullable: true
          description: Nome do usuário que criou o romaneio.
        RecordUserCreated:
          type: integer
          format: int64
          nullable: true
          description: Identificador do usuário que criou o romaneio.
        OrdersCarrierCollectionListStatus:
          type: string
          enum:
            - Aberto
            - Fechado
            - Finalizado
          description: >-
            Rótulo do status atual. Mapeia para `IDOrdersCarrierCollectionListStatus`: `1`=Aberto, `2`=Fechado,
            `3`=Finalizado.
        SupplierNameCorporateName:
          type: string
          description: Nome / razão social da transportadora vinculada (`Suppliers`).
        SupplierLogoUrl:
          type: string
          format: uri
          nullable: true
          description: URL do logo do tipo da transportadora (`CarrierLogoUrl`).
        RecordTimestamp:
          type: string
          format: date-time
          description: Data de criação do romaneio (`DD/MM/YY HH:mm:ss` na exibição).
        RecordTimestampEnd:
          type: string
          format: date-time
          nullable: true
          description: Data de finalização do romaneio. Preenchido quando `IDOrdersCarrierCollectionListStatus = 3`.
        CarrierDriverDocument:
          type: string
          nullable: true
          description: RG/CPF do motorista. Preenchido após assinatura.
        CarrierDriverNameCorporateName:
          type: string
          nullable: true
          description: Nome do motorista. Preenchido após assinatura.
        CarLicensePlate:
          type: string
          nullable: true
          description: Placa do veículo. Preenchido após assinatura.
        Comments:
          type: string
          nullable: true
          description: Comentário livre do motorista ou da retirada.
        SigningRecordTimestamp:
          type: string
          format: date-time
          nullable: true
          description: >-
            Data/hora em que o motorista assinou (preenche `POST .../file`). Quando `null`, o romaneio ainda não foi
            assinado.
        QtyOrder:
          type: integer
          description: >-
            Quantidade de pedidos distintos no romaneio (soma dos vínculos por `IDOrdersCarrierCollectionList` e
            `IDOrdersCarrierCollectionList`).
        QtyPackage:
          type: integer
          description: Quantidade de volumes (`Packages`) no romaneio.
        FileName1:
          type: string
          format: uri
          nullable: true
          description: >-
            URL pré-assinada (validade 48 h) da imagem da assinatura do motorista. `null` enquanto o romaneio não foi
            assinado.
        FileName2:
          type: string
          format: uri
          nullable: true
          description: URL pré-assinada da primeira foto/anexo opcional (documento, comprovante). `null` quando não enviada.
        FileName3:
          type: string
          format: uri
          nullable: true
          description: URL pré-assinada do segundo anexo opcional.
        FileName4:
          type: string
          format: uri
          nullable: true
          description: URL pré-assinada do terceiro anexo opcional.
        FileName5:
          type: string
          format: uri
          nullable: true
          description: URL pré-assinada do PDF final do romaneio (gerado no momento da assinatura).
    CollectionListOrderItem:
      type: object
      description: >-
        Pedido vinculado a um romaneio (subobjeto de `Orders`). Reflete os dados que aparecem na tabela do modal de
        conferência.
      properties:
        IDOrder:
          type: integer
          format: int64
          description: Identificador do pedido.
        Order:
          type: string
          description: Número do pedido visível ao usuário.
        IDStatusOrder:
          type: integer
          description: >-
            Status do pedido (`TypeStatusOrder`). Valores relevantes: `6` Aguardando expedição, `7` Enviado, `8`
            Entregue, `17` Retirada, `22` Aguardando romaneio.
        StatusOrder:
          type: string
          description: Rótulo do status do pedido.
        AccountName:
          type: string
          description: Prefixo da conta do pedido.
        ConsumerCpfCnpj:
          type: string
          nullable: true
          description: CPF/CNPJ do destinatário.
        ShippingReceiverName:
          type: string
          nullable: true
          description: Nome do destinatário (entrega).
        ShippingCity:
          type: string
          nullable: true
          description: Cidade de entrega.
        ShippingState:
          type: string
          nullable: true
          description: UF de entrega.
        ShippingId:
          type: string
          nullable: true
          description: Código de rastreio da transportadora gravado no pacote.
        NfeNumber:
          type: string
          nullable: true
          description: Número da NF-e do pedido.
        NfeChaveAcesso:
          type: string
          nullable: true
          description: Chave de acesso da NF-e (44 dígitos).
        NfeTotalValue:
          type: number
          format: double
          nullable: true
          description: Valor total da NF-e.
        IDPackage:
          type: integer
          format: int64
          nullable: true
          description: Identificador do volume.
        Package:
          type: string
          nullable: true
          description: Composição `Order-PackageNumber` usada na bipagem.
        PackageNumber:
          type: integer
          nullable: true
          description: Número sequencial do volume dentro do pedido.
        Weight:
          type: number
          format: double
          nullable: true
          description: >-
            Peso do volume (`PackageWeight`). Quando vazio, calculado a partir da soma `SkuWeight * Quantity` dos
            movimentos.
        IDCarrierType:
          type: integer
          nullable: true
          description: >-
            Tipo da transportadora. `30` e `32` representam retirada (canal/marketplace ou loja); influencia transição
            do pedido para status `17` no finish.
        IDConsumer:
          type: integer
          format: int64
          nullable: true
          description: Identificador do cliente.
        IDAddress:
          type: integer
          format: int64
          nullable: true
          description: Identificador do endereço de entrega.
        IDOrderType:
          type: integer
          nullable: true
          description: Tipo do pedido (`TypeOrder`).
        IDCompanyIntegration:
          type: integer
          nullable: true
          description: Integração de origem do pedido (`CompanyIntegration`), quando aplicável.
        CompanyNameCorporateNameInvoice:
          type: string
          nullable: true
          description: Nome/razão social do faturador da NF do pedido (quando diferente da empresa de venda).
        CompanyCpfCnpjInvoice:
          type: string
          nullable: true
          description: CNPJ do faturador da NF.
        CompanyLogoUrlInvoice:
          type: string
          format: uri
          nullable: true
          description: URL do logo do faturador.
        StatusColorCode:
          type: string
          nullable: true
          description: >-
            Cor (hex) do status do pedido configurada para a empresa, ex.: #33A7D8. Usada para colorir o badge de status
            na tela.
    CollectionListPendingPackage:
      type: object
      description: >-
        Volume **pendente de embarque** — pacote de um pedido presente no romaneio que **não está** vinculado a este
        romaneio. Indica que o pedido pode ser despachado parcialmente. Subobjeto de `PedingPackages` (com o typo
        histórico do campo no banco).
      properties:
        IDOrder:
          type: integer
          format: int64
          description: Identificador do pedido a que o volume pertence.
        Order:
          type: string
          description: Código externo do pedido (número visível ao cliente).
        IDPackage:
          type: integer
          format: int64
          description: Identificador do volume (etiqueta de envio) dentro do pedido.
        PackageNumber:
          type: integer
          description: Número sequencial do volume dentro do pedido (1, 2, 3...).
        ShippingId:
          type: string
          nullable: true
          description: Código de rastreio atribuído pelo transportador/integração ao volume. Vazio até a coleta ser confirmada.
        NfeNumber:
          type: string
          nullable: true
          description: Número da nota fiscal emitida para o volume. Vazio enquanto a NF-e não foi emitida.
        ShippingReceiverName:
          type: string
          nullable: true
          description: Nome do destinatário do envio (impresso na etiqueta).
    CollectionListDetail:
      type: object
      description: >-
        Detalhe completo de um romaneio. Vem do endpoint `GET /fulfillment/packing/collection-list/{id}` e também é
        retornado por endpoints que invocam o `Get` internamente (put, finish, orderPut).
      properties:
        IDOrdersCarrierCollectionList:
          type: integer
          format: int64
          description: Identificador do romaneio.
        IDOrdersCarrierCollectionListStatus:
          type: integer
          enum:
            - 1
            - 2
            - 3
          description: Status numérico. `1` Aberto, `2` Fechado, `3` Finalizado.
        OrdersCarrierCollectionListStatus:
          type: string
          enum:
            - Aberto
            - Fechado
            - Finalizado
          description: Nome amigável do status do romaneio.
        AccountName:
          type: string
          description: Identificador da empresa dona do romaneio.
        CompanyNameCorporateName:
          type: string
          description: Nome / razão social da empresa que vendeu (ou do faturador, quando `ShowCompanyInvoiceCarrierCollection=1`).
        CompanyCpfCnpj:
          type: string
          description: >-
            CPF/CNPJ da empresa que emitiu o romaneio (ou do faturador, quando o parâmetro `Mostrar dados do faturador
            no romaneio` está ativo).
        CompanyLogoUrl:
          type: string
          format: uri
          nullable: true
          description: >-
            URL pública da logo da empresa (ou do faturador, quando o parâmetro `Mostrar dados do faturador no romaneio`
            está ativo). `null` quando não cadastrada.
        SupplierNameCorporateName:
          type: string
          description: Transportadora do romaneio.
        SupplierLogoUrl:
          type: string
          format: uri
          nullable: true
          description: >-
            URL pública da logo da transportadora (`CarrierLogoUrl`). `null` quando o tipo de transportadora não tem
            logo.
        Login:
          type: string
          nullable: true
          description: Login do colaborador que finalizou o romaneio. `null` enquanto o romaneio não estiver finalizado.
        UserName:
          type: string
          nullable: true
          description: Nome do colaborador que finalizou o romaneio. `null` enquanto o romaneio não estiver finalizado.
        RecordTimestampEnd:
          type: string
          format: date-time
          nullable: true
          description: Data de finalização. `null` enquanto status != 3.
        CarrierDriverDocument:
          type: string
          nullable: true
          description: RG ou CPF do motorista que retirou. Preenchido apenas após a assinatura (`POST .../file`).
        CarrierDriverNameCorporateName:
          type: string
          nullable: true
          description: Nome do motorista que retirou. Preenchido apenas após a assinatura.
        CarLicensePlate:
          type: string
          nullable: true
          description: Placa do veículo (até 8 caracteres). Preenchida apenas após a assinatura.
        Comments:
          type: string
          nullable: true
          description: Comentário livre informado no momento da assinatura. `null` quando não informado.
        SigningRecordTimestamp:
          type: string
          format: date-time
          nullable: true
          description: Data/hora da assinatura do motorista. `null` enquanto o romaneio não tiver sido assinado.
        FileName1:
          type: string
          format: uri
          nullable: true
          description: URL pré-assinada da assinatura (validade 48 h).
        FileName2:
          type: string
          format: uri
          nullable: true
          description: URL do segundo arquivo anexo da assinatura. `null` quando não enviado.
        FileName3:
          type: string
          format: uri
          nullable: true
          description: URL do terceiro arquivo anexo da assinatura. `null` quando não enviado.
        FileName4:
          type: string
          format: uri
          nullable: true
          description: URL do quarto arquivo anexo da assinatura. `null` quando não enviado.
        FileName5:
          type: string
          format: uri
          nullable: true
          description: URL pré-assinada do PDF final do romaneio.
        Orders:
          type: array
          items:
            $ref: '#/components/schemas/CollectionListOrderItem'
          description: Lista dos pedidos/volumes que compõem o romaneio.
        PedingPackages:
          type: array
          items:
            $ref: '#/components/schemas/CollectionListPendingPackage'
          description: >-
            Volumes de pedidos deste romaneio que estão em **outro** romaneio (ou ainda sem amarração). Usado pelo
            frontend para avisar sobre split de pacotes ao fechar.
    CollectionListPostPayload:
      type: object
      required:
        - IDCarrier
      properties:
        IDCarrier:
          type: integer
          format: int64
          description: >-
            Identificador da transportadora (`IDSupplier`) que vai retirar este romaneio. Precisa pertencer à mesma
            empresa (`IDCompany`).
    CollectionListPutPayload:
      type: object
      required:
        - IDCarrier
      properties:
        IDCarrier:
          type: integer
          format: int64
          description: >-
            Nova transportadora (`IDSupplier`). Precisa estar ativa (`SupplierStatus=1`), pertencer à mesma empresa e
            ser diferente da atual.
    CollectionListFilePayload:
      type: object
      required:
        - CarrierDriverDocument
        - CarrierDriverNameCorporateName
        - CarLicensePlate
        - FileName1
        - FileName5
      description: >-
        Payload de assinatura do romaneio pelo motorista. Todos os arquivos (`FileName1..5`) são enviados como **data
        URIs base64** (`data:image/png;base64,...` ou `data:application/pdf;base64,...`). O sistema faz upload para o S3
        `OrdersCarrierCollectionListFiles/`.
      properties:
        CarrierDriverDocument:
          type: string
          description: RG ou CPF do motorista que retirou.
        CarrierDriverNameCorporateName:
          type: string
          description: Nome do motorista.
        CarLicensePlate:
          type: string
          maxLength: 8
          description: Placa do veículo (até 8 caracteres alfanuméricos, em maiúsculas).
        Comments:
          type: string
          nullable: true
          description: Comentário livre da retirada.
        FileName1:
          type: string
          description: Imagem da assinatura digital (data URI base64). Obrigatório.
        FileName2:
          type: string
          nullable: true
          description: Primeira foto/anexo de apoio (documento, comprovante). Data URI base64.
        FileName3:
          type: string
          nullable: true
          description: Segundo anexo opcional.
        FileName4:
          type: string
          nullable: true
          description: Terceiro anexo opcional.
        FileName5:
          type: string
          description: >-
            PDF completo do romaneio assinado (data URI base64). Obrigatório — esse é o documento persistido para
            impressão futura.
    CollectionListMergePayload:
      type: object
      required:
        - IDCollectionList
      properties:
        IDCollectionList:
          oneOf:
            - type: integer
              format: int64
            - type: array
              items:
                type: integer
                format: int64
          description: >-
            Identificador (ou array de identificadores) dos romaneios **origem** que serão mesclados no romaneio destino
            (path param). Origens precisam estar em status `3` (Finalizado), não assinadas e com a mesma `IDCarrier` do
            destino. Origens são removidas da base após o merge (registros de `Orders` / `Packages` migrados para o
            destino).
    CollectionListOrderPutPayload:
      type: object
      required:
        - IDCarrier
        - IDPackageArray
      properties:
        IDCarrier:
          type: integer
          format: int64
          description: >-
            Nova transportadora para os pedidos cujos pacotes serão removidos. Precisa estar ativa e pertencer à mesma
            empresa.
        IDPackageArray:
          type: array
          minItems: 1
          items:
            type: integer
            format: int64
          description: >-
            Lista de `IDPackage` a serem removidos deste romaneio. Cada pacote precisa pertencer a este romaneio
            (validado contra `IDOrdersCarrierCollectionList` e `IDOrdersCarrierCollectionList`). Os pedidos
            correspondentes voltam para `IDStatusOrder = 22` (Aguardando expedição) com a nova transportadora atribuída.
    PackingPickingListItem:
      type: object
      description: >-
        Item de pedido pendente de conferência no packing. Vem do `Items[]` em `GET
        /fulfillment/packing/picking-list/{id}`.
      properties:
        IDSku:
          type: integer
          format: int64
          description: Identificador do SKU da linha da picking list.
        IDSkuMovement:
          type: integer
          format: int64
          description: Identificador da movimentação de estoque do pedido para este SKU.
        IDSkuCompany:
          type: string
          nullable: true
          description: Código de referência interna do SKU.
        SkuName:
          type: string
          description: Nome do SKU a separar.
        AbcCurve:
          type: string
          nullable: true
          description: Curva ABC do produto (A, B, C).
        SkuWeight:
          type: number
          format: double
          nullable: true
          description: Peso unitário do SKU em kg.
        Quantity:
          type: number
          format: double
          description: Quantidade esperada deste SKU no pedido.
        BarCode:
          type: string
          nullable: true
          description: Código de barras principal.
        BarCodeList:
          type: array
          items:
            type: string
          description: Códigos de barras alternativos aceitos.
        BarCodePackageList:
          type: array
          items:
            type: object
            properties:
              IDStockKeepingUnitBarCodePackage:
                type: integer
                description: >-
                  Identificador do código de barras alternativo cadastrado para o SKU (embalagem secundária com fator de
                  conversão).
              BarCodePackage:
                type: string
                description: 'Código de barras da embalagem alternativa (ex.: caixa com 12 unidades).'
              PackageFactor:
                type: number
                description: >-
                  Quantidade de unidades do SKU equivalente a 1 leitura deste código de barras (ex.: `12` = bipou 1
                  caixa, vale 12 unidades).
          description: Códigos de barras de embalagens (caixa, fardo) com seu fator multiplicador.
        Address:
          type: string
          nullable: true
          description: Endereço de armazenagem onde o item foi separado.
        BestBeforeDate:
          type: string
          format: date
          nullable: true
          description: Data de validade (quando aplicável).
        Order:
          type: string
          description: Número do pedido (redundância para uso no card do item).
        PickingBasket:
          type: string
          nullable: true
          description: Identificador do cesto (colmeia) interno.
        HasSerialNumber:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` se o SKU controla número de série/IMEI — exige bipagem individual.'
        MainImageURL:
          type: string
          format: uri
          nullable: true
          description: URL da imagem principal do SKU para exibição na tela do separador.
        IDSkuKit:
          type: integer
          format: int64
          nullable: true
          description: Identificador do SKU pai do kit, quando o item é parte de um kit.
        KitSkuName:
          type: string
          nullable: true
          description: >-
            Nome do SKU kit-pai quando este item é componente de um kit sendo separado. Vazio quando o item não é
            componente de kit.
        WarehouseName:
          type: string
          nullable: true
          description: Nome do armazém de onde o SKU deve ser separado.
        SupplierNameCorporateName:
          type: string
          nullable: true
          description: Nome ou razão social do fornecedor preferencial do SKU (informativo).
        PickingListBasketExternalIdList:
          type: array
          items:
            type: string
          description: Códigos externos dos cestos onde este item foi armazenado durante o picking.
    PackingPickingListOrder:
      type: object
      description: Pedido dentro de uma picking-list, com todos os itens a conferir.
      properties:
        IDOrder:
          type: integer
          format: int64
          description: Identificador do pedido a conferir.
        Order:
          type: string
          description: Número do pedido (texto exibido na tela).
        IDStatusOrder:
          type: integer
          description: Status numérico atual do pedido. Ver `TypeStatusOrderEnum`.
        StatusOrder:
          type: string
          description: Nome amigável do status atual do pedido.
        IDPickingList:
          type: integer
          format: int64
          description: Identificador da picking-list a que o pedido pertence.
        IDTypePickingList:
          type: integer
          description: 'Tipo de picking-list: `1` Picking, `2` Picking & Packing, `3` Monopedido, `4` Colméia.'
          enum:
            - 1
            - 2
            - 3
            - 4
        TypePickingList:
          type: string
          description: Nome amigável do tipo de picking-list.
        PickingBasket:
          type: string
          nullable: true
          description: >-
            Identificador sequencial do cesto/caixa atribuído ao pedido durante a separação (`PickingBasket`). `null`
            quando o pedido ainda não recebeu cesto.
        PickingListBasketExternalIdList:
          type: array
          items:
            type: string
          description: >-
            Lista de códigos externos (`ExternalId`) dos cestos usados na coleta deste pedido. Vazia quando nenhum cesto
            foi registrado.
        ConsumerNameCorporateName:
          type: string
          nullable: true
          description: Nome / razão social do consumidor.
        OrdersSalesChannelLabelStatus:
          type: string
          nullable: true
          description: Status da etiqueta no canal de venda (Mercado Livre, Magalu, etc.).
        SupplierNameCorporateName:
          type: string
          nullable: true
          description: Transportadora amarrada ao pedido.
        IDCarrierType:
          type: integer
          nullable: true
          description: >-
            Identificador do tipo de transportadora do pedido. `null` quando o pedido ainda não tem transportadora
            definida.
        PrintDanfeA4:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: Indica se o pedido exige DANFE em formato A4 (em vez de simplificada).
        ManualLabel:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: Indica que a etiqueta é gerada externamente (canal/marketplace) — usa fluxo de carregar arquivo.
        OrderPriority:
          type: integer
          description: Prioridade do pedido (0=mais alta, 10=mais baixa).
        OrderComments:
          type: string
          nullable: true
          description: Observação do pedido (texto livre cadastrado pelo operador ou pelo canal de origem).
        IDConsumer:
          type: integer
          format: int64
          nullable: true
          description: Identificador do consumidor.
        IDSupplier:
          type: integer
          format: int64
          nullable: true
          description: Identificador do fornecedor do pedido (quando vier de marketplace).
        AccountName:
          type: string
          description: Identificador da empresa dona do pedido.
        Items:
          type: array
          items:
            $ref: '#/components/schemas/PackingPickingListItem'
          description: >-
            Lista de itens esperados para conferência no packing deste pedido. Cada entrada representa um movimento de
            estoque (`StockKeepingUnitMovement`) a bipar.
        Draft:
          description: >-
            Rascunho do packing salvo (último body enviado via `POST .../order/{id}?Draft=1`). Quando vazio, retorna
            `[]`. Quando presente, contém os campos do body de packing parciais (`Items`, `Volumes`, `Packages`,
            `ItemsCheckedVol`, etc.) para restaurar o progresso do operador na tela.
        StatusColorCode:
          type: string
          nullable: true
          description: >-
            Cor (hex) do status do pedido configurada para a empresa, ex.: #33A7D8. Usada para colorir o badge de status
            na tela de packing.
    PackingItem:
      type: object
      required:
        - IDSku
        - Quantity
      description: Item conferido no packing. Cada bipagem na tela acumula uma entrada deste tipo.
      properties:
        IDSku:
          type: integer
          format: int64
          description: Identificador do SKU sendo embalado na operação de packing.
        Quantity:
          type: number
          format: double
          description: Quantidade conferida deste SKU neste volume.
        PackageNumber:
          type: integer
          default: 1
          description: Número do volume em que este item foi alocado (1, 2, 3...). Default `1`.
        SerialNumber:
          type: string
          nullable: true
          description: >-
            Número de série/IMEI do item. Obrigatório quando o SKU tem `HasSerialNumber=1`. Cada item com série precisa
            ser enviado individualmente (uma linha por unidade, `Quantity=1`).
        CommentsInvoice:
          type: string
          nullable: true
          description: Observação fiscal específica deste item (vai para a NF-e).
    PackingVolume:
      type: object
      required:
        - PackageNumber
      description: >-
        Dados físicos de um volume (peso e dimensões). Preenchidos quando a parametrização **Conferir peso e medidas ao
        adicionar volume** está ativa.
      properties:
        PackageNumber:
          type: integer
          description: Número sequencial do volume (1, 2, 3...).
        PackageWeight:
          type: number
          format: double
          description: Peso do volume em kg.
        PackageHeight:
          type: number
          format: double
          description: Altura do volume em cm.
        PackageLength:
          type: number
          format: double
          description: Comprimento do volume em cm.
        PackageWidth:
          type: number
          format: double
          description: Largura do volume em cm.
    PackingPackage:
      type: object
      required:
        - IDSku
        - Quantity
        - PackageNumber
      description: >-
        SKU tipo embalagem (Package=1) usado no volume. Preenchido quando a parametrização **Adicionar embalagem na
        conferência** está ativa. Cada embalagem entra como linha de movimentação no pedido (valor 0).
      properties:
        IDSku:
          type: integer
          format: int64
          description: Identificador do SKU embalagem.
        Quantity:
          type: number
          format: double
          description: Quantidade de embalagens usadas neste volume (geralmente 1).
        PackageNumber:
          type: integer
          description: Volume em que esta embalagem foi usada.
    PackingOrderPostPayload:
      type: object
      description: >-
        Payload de finalização (ou rascunho, com `?Draft=1`) do packing de um pedido. Quando todos os itens conferem com
        os esperados na picking-list (`Items` enviados batem com `StockKeepingUnitMovement` do pedido), o sistema cria
        os volumes, emite a NF-e e atualiza o status do pedido.
      properties:
        IDPickingList:
          type: integer
          format: int64
          description: >-
            Identificador da picking-list a que o pedido pertence. Necessário para o salvamento de rascunho
            (`?Draft=1`).
        QuantityPackages:
          type: integer
          default: 1
          description: >-
            Quantidade total de volumes do pedido. O sistema reconcilia o número de linhas em `Packages` para bater com
            este valor (cria linhas faltantes, apaga excedentes).
        Items:
          type: array
          items:
            $ref: '#/components/schemas/PackingItem'
          description: Lista de itens conferidos. Cada bipagem na tela vira uma entrada aqui.
        Volumes:
          type: array
          items:
            $ref: '#/components/schemas/PackingVolume'
          description: Peso e dimensões de cada volume. Opcional, mas exigido pelo frontend quando `AddPackageWeight=1`.
        Packages:
          type: array
          items:
            $ref: '#/components/schemas/PackingPackage'
          description: SKUs tipo embalagem usados nos volumes. Opcional, mas exigido pelo frontend quando `AddPackage=1`.
        TempAuthToken:
          type: string
          description: >-
            Token temporário obtido via `POST /user/{id}/verify`. Obrigatório quando `PartialInvoice=1` (precisa do
            privilégio **Autorizar packing/faturamento parcial**).
    PickingListMergePayload:
      type: object
      required:
        - IDPickingList
      properties:
        IDPickingList:
          type: integer
          format: int64
          description: >-
            Identificador da picking-list **destino** (na qual a origem será mesclada). Origem (path param) e destino
            precisam estar em status `1` (Pendente). O destino mantém sua prioridade e configuração; os pedidos da
            origem têm `IDPickingList` reatribuído para o destino e a picking-list de origem é removida.
    PickingListListItem:
      type: object
      description: >-
        Item da lista de picking-lists. Retornado por `GET /fulfillment/picking/picking-list` e usado como resposta dos
        handlers que invocam o List internamente (Merge).
      properties:
        IDPickingList:
          type: integer
          format: int64
          description: Identificador da picking-list.
        IDPickingListStatus:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 7
          description: >-
            Status numérico. `1` Picking-List Pendente, `2` Picking-List Iniciado, `3` Picking-List Coletado, `4`
            Packing Processando, `5` Packing Concluido, `6` Picking-List ag. continuidade, `7` Picking-List Iniciado 2.
        StatusPickingList:
          type: string
          description: >-
            Nome do status conforme retornado pelo sistema: `Picking-List Pendente`, `Picking-List Iniciado`,
            `Picking-List Coletado`, `Packing Processando`, `Packing Concluido`, `Picking-List ag. continuidade`,
            `Picking-List Iniciado 2`.
        IDTypePickingList:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
          description: 'Tipo de picking-list: `1` Picking, `2` Picking & Packing, `3` Monopedido, `4` Colméia.'
        TypePickingList:
          type: string
          description: Nome amigável do tipo de coleta (`Picking`, `Picking/Packing`, `Monopedido`, `Colméia`).
        PickingListPriority:
          type: integer
          minimum: 0
          maximum: 10
          description: >-
            Prioridade da picking-list (0=mais alta, 10=mais baixa). Recalculada conforme parametrização
            `UseShippingHandlingTimeInPickingPriority`.
        PickingListConfigurationName:
          type: string
          nullable: true
          description: Nome da configuração de picking que gerou a lista (de `PickingListConfiguration`).
        AccountName:
          type: string
          description: Identificador da empresa dona da picking-list.
        RecordUserCreated:
          type: integer
          format: int64
          description: Usuário que disparou a geração.
        Login:
          type: string
          nullable: true
          description: Login do usuário criador.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data/hora de criação.
        RecordUserCreatedStartPicking:
          type: integer
          format: int64
          nullable: true
          description: Colaborador atribuído (separador).
        LoginStartPicking:
          type: string
          nullable: true
          description: Login do colaborador atribuído ou `null` quando não atribuído.
        RecordTimestampStartPicking:
          type: string
          format: date-time
          nullable: true
          description: >-
            Data/hora em que a separação foi iniciada (`POST .../start`). `null` enquanto a picking-list estiver
            pendente.
        RecordTimestampFinishedPicking:
          type: string
          format: date-time
          nullable: true
          description: Data/hora em que a separação foi finalizada (`POST .../finish`). `null` enquanto a coleta não terminou.
        RecordUserCreatedStartPacking:
          type: integer
          format: int64
          nullable: true
          description: >-
            Identificador do colaborador que iniciou o packing dos pedidos desta picking-list. `null` antes do packing
            começar.
        LoginStartPacking:
          type: string
          nullable: true
          description: Login do colaborador que iniciou o packing.
        RecordTimestampStartPacking:
          type: string
          format: date-time
          nullable: true
          description: Data/hora em que o packing dos pedidos desta picking-list foi iniciado.
        RecordTimestampEnd:
          type: string
          format: date-time
          nullable: true
          description: Data/hora em que o packing da lista terminou.
        QtyOrder:
          type: integer
          description: Quantidade de pedidos na picking-list.
        QtyOrderDone:
          type: integer
          description: Quantidade de pedidos já processados (status `IN (6, 7, 8, 17, 19, 22, 94, 95)`).
        ItemsQuantity:
          type: number
          format: double
          description: Soma das quantidades de todos os movimentos de estoque da lista.
        SkuQuantity:
          type: integer
          description: Quantidade de SKUs distintos.
        ShippingEstimateDate:
          type: string
          format: date
          nullable: true
          description: Data prevista de entrega mais próxima entre os pedidos da lista.
        StockKeepingUnitLocationGroupName:
          type: string
          nullable: true
          description: Nomes (concatenados) dos grupos de endereço de armazenagem cobertos pela picking-list.
        TypeOrder:
          type: string
          nullable: true
          description: Tipos de pedido (concatenados) presentes na lista.
        SupplierNameCorporateName:
          type: string
          nullable: true
          description: Transportadoras (concatenadas).
        IDPickingListFather:
          type: integer
          nullable: true
          description: Identificador da picking-list pai em listas do tipo colméia (`IDTypePickingList=4`); `null` nas demais.
        Checked:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: Indica se a picking-list foi conferida (`1`) ou não (`0`).
    PickingListMovementItem:
      type: object
      description: >-
        Linha da picking-list detalhada (vem de `GET /fulfillment/picking/picking-list/{id}`). Representa uma agregação
        de movimentos de estoque por SKU + (pedido + lote) ou, em modo agrupado, por SKU + endereço.
      properties:
        IDPickingList:
          type: integer
          format: int64
          description: Identificador da picking-list a que a linha pertence.
        TypePickingList:
          type: string
          description: Nome amigável do tipo de coleta (`Picking`, `Picking/Packing`, `Monopedido`, `Colméia`).
        IDSku:
          type: integer
          format: int64
          description: Identificador do SKU a separar.
        IDSkuCompany:
          type: string
          nullable: true
          description: Código interno do SKU usado pela empresa (referência). `null` quando não cadastrado.
        SkuName:
          type: string
          description: Nome do SKU.
        AbcCurve:
          type: string
          nullable: true
          description: Curva ABC do SKU (`A`, `B`, `C`). `null` quando ainda não classificado.
        SkuWeight:
          type: number
          format: double
          nullable: true
          description: Peso unitário do SKU em quilos. `null` quando não cadastrado.
        Quantity:
          type: number
          format: double
          description: Quantidade total (soma) deste agrupamento.
        BarCode:
          type: string
          nullable: true
          description: Código de barras principal do SKU. `null` quando não cadastrado.
        BarCodeList:
          type: array
          items:
            type: string
          description: Lista de códigos de barras alternativos aceitos durante a bipagem.
        BarCodePackageList:
          type: array
          items:
            type: object
            properties:
              IDStockKeepingUnitBarCodePackage:
                type: integer
                description: Identificador da embalagem cadastrada.
              BarCodePackage:
                type: string
                description: Código de barras da embalagem (caixa, fardo, display).
              PackageFactor:
                type: number
                description: 'Quantidade de unidades contidas na embalagem (ex.: `12` para um fardo de 12 unidades).'
          description: >-
            Lista de embalagens (pacote/caixa) com seus códigos de barras e quantidade equivalente em unidades. Permite
            bipar uma caixa fechada e o sistema contar o múltiplo correto.
        Address:
          type: string
          nullable: true
          description: Endereço de armazenagem (rua-módulo-coluna-nível) onde o item será coletado.
        IDBatch:
          type: integer
          format: int64
          nullable: true
          description: Identificador do lote a separar. `null` quando o SKU não opera por lote.
        Batch:
          type: boolean
          description: Indica se o SKU é gerenciado por lote.
        BestBeforeDate:
          type: string
          format: date
          nullable: true
          description: Validade do lote no formato `YYYY-MM-DD`. `null` quando o SKU não opera por lote.
        ManufacturingDate:
          type: string
          format: date
          nullable: true
          description: Data de fabricação do lote no formato `YYYY-MM-DD`. `null` quando o SKU não opera por lote.
        Comments:
          type: string
          nullable: true
          description: 'Observação cadastrada no lote (ex.: número do romaneio de entrada). `null` quando o lote não tem observação.'
        MainImageThumbnailURL:
          type: string
          format: uri
          nullable: true
          description: URL pública da miniatura da imagem principal do SKU. `null` quando o SKU não tem imagem cadastrada.
        IDStockKeepingUnitWarehouse:
          type: integer
          format: int64
          nullable: true
          description: Identificador do armazém de origem dentro do CD. `null` quando o item ainda não está alocado a um endereço.
        WarehouseName:
          type: string
          nullable: true
          description: Nome do armazém de origem. `null` quando não alocado.
        IDSkuKit:
          type: integer
          format: int64
          nullable: true
          description: >-
            Identificador do SKU kit do qual este item faz parte (composição). `null` quando o item não pertence a um
            kit.
        KitSkuName:
          type: string
          nullable: true
          description: Nome do SKU kit pai. `null` quando o item não pertence a um kit.
        IDOrder:
          type: integer
          format: int64
          nullable: true
          description: '`null` em modo agrupado.'
        Order:
          type: string
          nullable: true
          description: Número do pedido (omitido em modo agrupado).
        IDStatusOrder:
          type: integer
          nullable: true
          description: Status numérico do pedido associado à linha. `null` na visão agrupada por SKU (`IDTypePickingList = 1`).
        StatusOrder:
          type: string
          nullable: true
          description: Nome amigável do status do pedido. `null` na visão agrupada por SKU.
        IDConsumer:
          type: integer
          format: int64
          nullable: true
          description: Identificador do consumidor do pedido. `null` na visão agrupada por SKU.
        ConsumerNameCorporateName:
          type: string
          nullable: true
          description: Nome / razão social do consumidor do pedido. `null` na visão agrupada por SKU.
        IDSupplier:
          type: integer
          format: int64
          nullable: true
          description: Identificador do fornecedor/marketplace do pedido. `null` na visão agrupada por SKU.
        SupplierNameCorporateName:
          type: string
          nullable: true
          description: Transportadora do pedido (`null` em modo agrupado).
        AccountName:
          type: string
          nullable: true
          description: Identificador da empresa dona do pedido.
        IDSkuMovement:
          type: integer
          format: int64
          nullable: true
          description: >-
            Identificador do movimento de estoque que originou a linha. Usado como path param em `PUT
            .../sku/{idskumovement}` para apontar inconformidade.
        PickingBasket:
          type: string
          nullable: true
          description: Cesto/colmeia do pedido (em modo agrupado é `null`).
        PickingListBasketExternalId:
          type: string
          nullable: true
          description: Código externo do cesto (do `PickingListBasket`).
        PrintDanfeA4:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: Indica se a transportadora exige impressão da DANFE em A4 junto da etiqueta. `1` Sim, `0` Não.
        ManualLabel:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: Indica se a transportadora opera com etiqueta manual (não emitida pelo canal de venda). `1` Sim, `0` Não.
        RecordtimestampOrder:
          type: string
          format: date-time
          nullable: true
          description: Data/hora de criação do pedido. `null` na visão agrupada por SKU.
        Floor:
          type: integer
          nullable: true
          description: Andar do endereço de coleta (usado na rota otimizada).
        Street:
          type: string
          nullable: true
          description: >-
            Identificador da rua dentro do CD (endereçamento físico). `null` quando o item ainda não tem endereço
            definido.
        Module:
          type: string
          nullable: true
          description: Identificador do módulo (estrutura/estante) dentro da rua. `null` quando sem endereço.
        Column:
          type: string
          nullable: true
          description: Identificador da coluna dentro do módulo. `null` quando sem endereço.
        Level:
          type: string
          nullable: true
          description: Identificador do nível (altura/prateleira) dentro da coluna. `null` quando sem endereço.
        LocationSide:
          type: integer
          enum:
            - 1
            - 2
          nullable: true
          description: '`1` lado direito (rua ímpar), `2` lado esquerdo (rua par).'
        StatusColorCode:
          type: string
          nullable: true
          description: 'Cor (hex) do status do pedido configurada para a empresa, ex.: #33A7D8. null na visão agrupada por SKU.'
        IDStockKeepingUnitLocation:
          type: integer
          nullable: true
          description: Identificador do endereço de armazenagem da linha.
        IDPickingListStatus:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 7
          nullable: true
          description: Status da picking-list a que a linha pertence.
        IDPickingListFather:
          type: integer
          nullable: true
          description: Identificador da picking-list pai (colméia); `null` nas demais.
        Checked:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: Indica se a picking-list foi conferida (`1`) ou não (`0`).
    PickingPostPayload:
      type: array
      description: >-
        Array de identificadores de pedido (`IDOrder`) a serem agrupados em picking-list(s). O sistema agrupa por
        **combinação de `IDStockKeepingUnitLocationGroup`** dos itens do pedido (mesmo CD obrigatório). Cada grupo único
        de endereços vira uma picking-list distinta.
      items:
        type: integer
        format: int64
    PickingListPutPayload:
      type: object
      description: >-
        Body do PUT /fulfillment/picking/picking-list/{id}. Pelo menos um campo precisa ser informado. Com ?Draft=1 o
        body é gravado como rascunho temporário (TTL 4 dias) sem tocar o banco.
      properties:
        RecordUserCreatedStartPicking:
          type: integer
          format: int64
          nullable: true
          description: >-
            Identificador do colaborador atribuído. O colaborador precisa ter jornada de trabalho ativa e função de
            separador de pedido (IDUserJobPosition = 3). Aceita null para desatribuir. Só aceito quando a picking-list
            está em status 1, 2, 3, 4, 6 ou 7.
        IDTypePickingList:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
          description: 'Tipo de picking-list: 1 Picking, 2 Picking & Packing, 3 Monopedido, 4 Colméia.'
        PickingListPriority:
          type: integer
          minimum: 0
          maximum: 10
          description: Nova prioridade (0=mais alta, 10=mais baixa).
        IDPickingListStatus:
          type: integer
          enum:
            - 4
            - 6
            - 7
          description: >-
            Move o status da picking-list. Apenas 4, 6 e 7 são aceitos — outros valores são ignorados; para 1->2 e 2->3
            use /start e /finish. Setar 6 zera automaticamente RecordUserCreatedStartPicking.
        Checked:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            Marca a conferência da picking-list (1 conferida, 0 não). Enviar vazio equivale a não alterar. Confirmar
            tipo/nullabilidade no DDL.
    PickingListFinishPayload:
      type: array
      description: >-
        Array opcional informando, para cada pedido da picking-list, os códigos externos de cestos a serem registrados
        (`PickingListBasket`). Quando preenchido, o sistema registra (upsert) cada cesto vinculado por `(CD, ExternalId,
        IDOrder)`. Quando vazio ou ausente, a finalização só atualiza status e timestamps.
      items:
        type: object
        required:
          - IDOrder
          - PickingListBasketExternalIdList
        properties:
          IDOrder:
            type: integer
            format: int64
            description: Identificador do pedido (usado quando o vínculo de cestos é informado por pedido).
          PickingListBasketExternalIdList:
            type: array
            items:
              type: string
            description: Lista de códigos externos dos cestos usados na coleta deste pedido.
    PickingNonconformityPayload:
      type: object
      required:
        - QuantityNonconformity
        - IDTypeFulfillmentNonconformity
      properties:
        QuantityNonconformity:
          type: number
          format: double
          description: >-
            Quantidade do SKU que entrou em inconformidade (faltou, está vencida ou avariada). Pode ser menor que a
            quantidade total do movimento — nesse caso, com `TransferIfPossible=1`, o movimento é dividido em dois (um
            para a quantidade ok, outro para a inconforme).
        IDTypeFulfillmentNonconformity:
          type: integer
          enum:
            - 1
            - 2
            - 5
            - 6
          description: >-
            Tipo de inconformidade (de `TypeFulfillmentNonconformity`): `1` Avariado, `2` Vencido, `5` Falta, `6`
            Ressuprimento (atribuído pelo próprio sistema quando o pulmão tem saldo).
    OrdersListItem:
      type: object
      description: >-
        Item da resposta do `GET /orders` no modo padrão (sem `SkuView=1`). Combina dados do pedido (`Orders`), do
        status (`TypeStatusOrderCompany`), do tipo de pedido (`TypeOrder`), da NF principal (`NfCompany`), da integração
        (`CompanyIntegration` + `TypeCompanyIntegration`), da transportadora (`Suppliers`), do faturador (`Company`
        aliasado) e do CD (`StockKeepingUnitDistributionCenter`). Quando `SkuView=1` é passado, o shape muda: as colunas
        planas são substituídas por um campo `Items` (array de SKUs do pedido).
      properties:
        IDOrder:
          type: integer
          format: int64
          description: Código interno do pedido.
        Order:
          type: string
          description: Número do pedido (`Order`).
        OrderFrom:
          type: string
          nullable: true
          description: Número(s) do pedido no canal de origem (CSV agregado por `GROUP_CONCAT`).
        Recordtimestamp:
          type: string
          format: date-time
          description: Data e hora de criação do pedido.
        DateLastRecordModification:
          type: string
          format: date-time
          nullable: true
          description: Data e hora da última modificação do pedido.
        AccountName:
          type: string
          description: Conta (subdomínio) a que o pedido pertence.
        Budget:
          type: integer
          enum:
            - 0
            - 1
          description: '`0` = pedido firme, `1` = orçamento.'
        BalanceChange:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` = movimenta estoque (pedido), `0` = só fiscal (nota sem movimento).'
        IDStatusOrder:
          type: integer
          description: Status do pedido (`IDStatusOrder`).
        StatusOrder:
          type: string
          description: Descrição do status do pedido para a empresa (`StatusOrder` — permite override por empresa).
        StatusColorCode:
          type: string
          nullable: true
          description: Cor hex do status (`#RRGGBB`) — usada para colorir a coluna na grade.
        IDOrderType:
          type: integer
          description: Tipo de pedido (`IDTypeOrder`).
        TypeOrder:
          type: string
          description: Descrição do tipo de pedido.
        ServiceRequest:
          type: integer
          enum:
            - 0
            - 1
          description: '`ServiceRequest` — `1` indica que o tipo é ordem de serviço.'
        IDCompanyIntegration:
          type: integer
          format: int64
          nullable: true
          description: Conta de integração que originou o pedido.
        CompanyIntegration:
          type: string
          nullable: true
          description: Rótulo amigável da conta de integração, no formato `IntegrationName - CompanyIntegrationName`.
        SalesChannelName:
          type: string
          nullable: true
          description: Nome do canal de venda (`IntegrationName`).
        IntegrationName:
          type: string
          nullable: true
          description: Mesmo conteúdo de `SalesChannelName`. Mantido por compatibilidade com clientes antigos.
        SalesChannelLogoUrl:
          type: string
          nullable: true
          description: URL do logo do canal.
        IDSalesman:
          type: integer
          format: int64
          nullable: true
          description: Vendedor (`IDUser`).
        Salesman:
          type: string
          nullable: true
          description: Vendedor, no formato `UserName - Login`.
        IDCarrier:
          type: integer
          format: int64
          nullable: true
          description: Transportadora (`IDSupplier`).
        SupplierNameCorporateName:
          type: string
          nullable: true
          description: Razão social da transportadora.
        IDCarrierType:
          type: integer
          nullable: true
          description: Tipo de transportadora (`IDCarrierType`).
        ManualLabel:
          type: integer
          nullable: true
          description: Indica se a transportadora emite etiqueta manual (`ManualLabel`).
        TrackingUrl:
          type: string
          description: URL pública do rastreio (`https://rastreioo.com.br/#/tracking/<AccountName>/<IDOrder>`).
        ShippingId:
          type: string
          nullable: true
          description: Código(s) de rastreio dos pacotes do pedido (CSV via `GROUP_CONCAT`).
        ShippingDate:
          type: string
          format: date-time
          nullable: true
          description: Data de envio do primeiro pacote (`ShippingDate`).
        ShippingEstimateDate:
          type: string
          format: date
          nullable: true
          description: Data prevista de entrega ao cliente.
        ShippingEstimateHandlingLimitDate:
          type: string
          format: date-time
          nullable: true
          description: >-
            Data limite de expedição informada pelo canal (`ShippingEstimateHandlingLimitDate`). Usada principalmente
            para Mercado Livre.
        ShippingAvailableLabelDate:
          type: string
          format: date-time
          nullable: true
          description: Data em que a etiqueta do canal ficou disponível (`ShippingAvailableLabelDate`).
        HubOrderStatus:
          type: string
          nullable: true
          description: Descrição do status do pedido no canal de venda (`Description`).
        ShippingCity:
          type: string
          nullable: true
          description: Cidade de entrega.
        ShippingState:
          type: string
          nullable: true
          description: UF de entrega.
        ShippingPostalCode:
          type: string
          nullable: true
          description: CEP de entrega.
        ShippingReceiverName:
          type: string
          nullable: true
          description: Nome do destinatário (pode diferir do cliente).
        ConsumerNameCorporateName:
          type: string
          nullable: true
          description: Nome / razão social do cliente.
        ConsumerCpfCnpj:
          type: string
          nullable: true
          description: Documento do cliente (CPF ou CNPJ).
        ConsumerEmail:
          type: string
          nullable: true
          description: E-mail do cliente.
        IDConsumer:
          type: integer
          format: int64
          nullable: true
          description: Código interno do cliente.
        IDAddress:
          type: integer
          format: int64
          nullable: true
          description: Endereço de entrega cadastrado (`IDAddress`).
        NfeNumber:
          type: integer
          nullable: true
          description: Número da NF principal.
        NfeSerie:
          type: integer
          nullable: true
          description: Série da NF principal.
        NfedhEmi:
          type: string
          format: date-time
          nullable: true
          description: Data e hora de emissão da NF principal.
        NfeChaveAcesso:
          type: string
          nullable: true
          description: Chave de acesso da NF principal (44 dígitos).
        NfePackages:
          type: integer
          nullable: true
          description: Quantidade de volumes informada na NF.
        NfeNoPayment:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` indica NF emitida sem pagamento associado.'
        NfeComments:
          type: string
          nullable: true
          description: Observações da NF.
        IDStatusInvoice:
          type: integer
          description: >-
            Status da NF: `0` Pendente, `1` Erro, `2` Enviada, `3` Emitida, `4` Processando, `5` Pendente Conciliação
            EPEC, `6` Erro Conciliação EPEC, `7` Cancelada, `8` Denegada, `9` Inutilizada.
        StatusInvoice:
          type: string
          description: Descrição do status da NF principal. `Pendente` quando ainda não há NF.
        Checked:
          type: integer
          nullable: true
          description: Marcação manual de conferido (`Checked`).
        ValueProduct:
          type: number
          format: double
          nullable: true
          description: Soma dos `PriceSellingTotal` dos itens não gratificados.
        ValueShipping:
          type: number
          format: double
          nullable: true
          description: Valor do frete do pedido (`ValueShipping`).
        ValueOrder:
          type: number
          format: double
          nullable: true
          description: 'Total do pedido: soma dos itens + `ValueShipping` + `NfeAccessoryExpenses`.'
        ValuePaid:
          type: number
          format: double
          nullable: true
          description: Soma de `Value` do pedido (valor já recebido).
        ValueDiscount:
          type: number
          format: double
          nullable: true
          description: Soma dos descontos por item (multiplicado pela quantidade).
        ProductCost:
          type: number
          format: double
          nullable: true
          description: Custo total dos itens (`ValueCostTotal` agregado, ignorando embalagens e gratificações).
        QuantityProduct:
          type: number
          format: double
          description: Soma das quantidades de itens do pedido.
        QuantitySku:
          type: integer
          description: Quantidade de SKUs distintos do pedido.
        IDPickingList:
          type: integer
          format: int64
          nullable: true
          description: Picking-list atual do pedido.
        IDOrdersCarrierCollectionList:
          type: integer
          format: int64
          nullable: true
          description: Romaneio atual do pedido.
        IDTypeOrderReturn:
          type: integer
          format: int64
          nullable: true
          description: Motivo de devolução (`IDTypeOrderReturn`).
        TypeOrderReturn:
          type: string
          nullable: true
          description: Descrição do motivo de devolução.
        IDTypeOrderResend:
          type: integer
          format: int64
          nullable: true
          description: Motivo de reenvio (`IDTypeOrderResend`).
        TypeOrderResend:
          type: string
          nullable: true
          description: Descrição do motivo de reenvio.
        OrdersSalesChannelLabelStatus:
          type: string
          nullable: true
          description: Status da etiqueta no canal (`Header`).
        OrderComments:
          type: string
          nullable: true
          description: Observações livres do pedido.
        OrderPriority:
          type: integer
          nullable: true
          description: >-
            Prioridade manual do pedido (`OrderPriority`). Quando preenchido, vence a prioridade da configuração de
            picking-list na geração da picking.
        IDStockKeepingUnitDistributionCenter:
          type: integer
          format: int64
          nullable: true
          description: Centro de distribuição vinculado ao pedido.
        DistributionCenterName:
          type: string
          nullable: true
          description: Nome do CD.
        IDStockKeepingUnitResupplyList:
          type: string
          nullable: true
          description: Listas de ressuprimento vinculadas ao pedido (CSV via `GROUP_CONCAT`).
        CompanyInvoiceTradeName:
          type: string
          nullable: true
          description: Nome fantasia da empresa faturadora.
        CompanyInvoiceAccountName:
          type: string
          nullable: true
          description: Conta (subdomínio) da empresa faturadora.
        TypePayment:
          type: string
          nullable: true
          description: >-
            Descrição do tipo de pagamento da primeira parcela. Quando a parcela aceita mais de um tipo, vem como lista
            separada por vírgula.
        Weight:
          type: number
          format: double
          nullable: true
          description: Peso do pedido. Usa `PackageWeight` quando preenchido; senão, soma `SkuWeight * Quantity` dos itens.
        Tags:
          type: array
          items:
            type: string
          description: Tags do pedido (`Tag`). Devolvido como array.
        Items:
          type: array
          nullable: true
          description: >-
            Presente apenas quando `SkuView=1`. Array de SKUs do pedido com nome, quantidade, valor unitário, kit,
            inconformidade e imagem principal.
          items:
            type: object
            properties:
              IDSku:
                type: integer
                format: int64
                description: SKU do item.
              IDSkuCompany:
                type: string
                nullable: true
                description: Código de referência do SKU.
              SkuName:
                type: string
                description: Nome do SKU (concatenando o pai quando se trata de variação).
              SkuNameOnly:
                type: string
                description: Nome do SKU sem a parte herdada do pai.
              Quantity:
                type: number
                format: double
                description: Quantidade do item no pedido.
              PriceSelling:
                type: number
                format: double
                description: 'Preço unitário (calculado: `PriceSellingTotal / Quantity`, arredondado para 4 casas).'
              PriceSellingTotal:
                type: number
                format: double
                description: Valor total do item no pedido.
              IDSkuKit:
                type: integer
                format: int64
                nullable: true
                description: Quando o item faz parte de um kit, identifica o SKU do kit pai.
              QuantityKit:
                type: number
                format: double
                nullable: true
                description: Quantidade de kits que originou esta linha.
              KitSkuName:
                type: string
                nullable: true
                description: Nome do SKU do kit pai.
              KitIDSkuCompany:
                type: string
                nullable: true
                description: Código de referência do SKU do kit pai.
              QuantityNonconformity:
                type: number
                format: double
                nullable: true
                description: Quantidade do item em inconformidade (falta, vencido, avariado).
              IDTypeFulfillmentNonconformity:
                type: integer
                nullable: true
                description: Tipo de inconformidade (ver `TypeFulfillmentNonconformity`).
                enum:
                  - 1
                  - 2
                  - 4
                  - 5
                  - 6
              TypeFulfillmentNonconformity:
                type: string
                nullable: true
                description: Descrição da inconformidade.
              MainImageURL:
                type: string
                nullable: true
                description: URL da imagem principal do SKU.
    OrderStatusPutPayload:
      type: object
      description: >-
        Body do `PUT /orders/{idorder}/status`. Move o pedido para outro status — a tela **Outbound** usa este endpoint
        com `IDOrderStatusTo=90` (Cancelar).
      required:
        - IDOrderStatusTo
      properties:
        IDOrderStatusTo:
          type: integer
          description: >-
            Status destino (`IDStatusOrder`). A transição precisa estar cadastrada em `TypeStatusOrderRule` para a
            empresa. Valores comuns disparados por telas: `0` Aberto, `1` Fechado, `5` Segurar pedido, `9` Em espera,
            `13` Em tratativa, `90` Cancelado, `91` Extraviado, `92` Extraviado parcialmente, `94` Devolvido, `95` Em
            devolução, `97` Reversa finalizada.
        StatusComment:
          type: string
          description: >-
            Comentário/motivo da transição. Obrigatório quando `CommentsRequired=1` para o destino (caso contrário,
            opcional). Quando informado, é gravado em `Comments`.
        StatusDate:
          type: string
          format: date-time
          description: >-
            Data e hora do evento. Quando omitido, usa o momento atual em America/Sao_Paulo. Não pode ser superior ao
            momento atual + 5 minutos.
    InvoiceServiceFeedItem:
      type: object
      description: >-
        Item do feed de NFSe recebidas (`NfsEvents`). Cada linha é uma NFSe emitida por um fornecedor para o CNPJ da
        empresa, capturada da prefeitura via cron com autenticação por certificado digital.
      properties:
        IDNfsEvents:
          type: integer
          format: int64
          description: Identificador único da NFSe no feed do idworks.
        IDCompany:
          type: integer
          format: int64
          description: Empresa que recebeu a nota (tomadora).
        IDCompanyInvoice:
          type: integer
          format: int64
          nullable: true
          description: Faturador (filial) específica vinculada à nota.
        AccountName:
          type: string
          description: Prefixo da conta da empresa tomadora.
        AccountNameInvoice:
          type: string
          nullable: true
          description: Prefixo da conta do faturador.
        CompanyNameCorporateNameInvoice:
          type: string
          nullable: true
          description: Nome / razão social do faturador.
        NfsNumber:
          type: string
          description: Número da NFSe.
        NfsDate:
          type: string
          format: date-time
          description: Data e hora de emissão pela prefeitura.
        NfsChaveAcesso:
          type: string
          nullable: true
          description: Chave de acesso da NFSe.
        NfsVerificationCode:
          type: string
          nullable: true
          description: Código de verificação.
        NSU:
          type: string
          nullable: true
          description: Número Sequencial Único (controle do ambiente nacional).
        IDTypeStatusInvoiceService:
          type: integer
          description: Status numérico da nota.
        StatusInvoiceService:
          type: string
          description: Label do status (Emitida, Cancelada, Substituída, Conferida, Pendente, Erro, etc.). Varia por município.
        NfsCancelDate:
          type: string
          format: date-time
          nullable: true
          description: Data do evento de cancelamento (quando `IDTypeStatusInvoiceService = 2`).
        CityCode:
          type: integer
          description: Código IBGE do município emissor. `0` indica Ambiente Nacional ADN.
        CityName:
          type: string
          description: Nome do município emissor (`CityName`).
        State:
          type: string
          description: UF do município emissor (`State`).
        NfsServiceCode:
          type: string
          description: Código do serviço (CNAE municipal).
        ServiceDescription:
          type: string
          description: Descrição do código de serviço.
        NfsSupplierCpfCnpj:
          type: string
          description: CPF/CNPJ do fornecedor (prestador).
        NfsSupplierNameCorporateName:
          type: string
          description: Nome / razão social do fornecedor.
        NfsSupplierCityInscription:
          type: string
          nullable: true
          description: Inscrição municipal do fornecedor/prestador (quando informada na nota).
        IDSupplier:
          type: integer
          format: int64
          nullable: true
          description: Identificador do fornecedor no cadastro da empresa, quando há `Suppliers` com o mesmo CNPJ.
        NfsValue:
          type: number
          format: double
          description: Valor total da nota.
        NfsISSAliquot:
          type: number
          format: double
          nullable: true
          description: Alíquota de ISS aplicada (fração decimal — `0.05` = 5%).
        NfsISSValue:
          type: number
          format: double
          nullable: true
          description: Valor de ISS destacado na nota.
        NfsISSRetained:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            Indica se o ISS foi retido pelo tomador. `1` retido (o tomador paga o ISS no lugar do prestador); `0` não
            retido.
        NfsPisValue:
          type: number
          format: double
          nullable: true
          description: Valor de PIS destacado/retido na nota.
        NfsCofinsValue:
          type: number
          format: double
          nullable: true
          description: Valor de COFINS destacado/retido na nota.
        NfsIrValue:
          type: number
          format: double
          nullable: true
          description: Valor de IRRF retido pelo tomador.
        NfsCsllValue:
          type: number
          format: double
          nullable: true
          description: Valor de CSLL retido pelo tomador.
        NfsCreditValue:
          type: number
          format: double
          nullable: true
          description: >-
            Valor de crédito de ISS quando o município oferece programa de devolução parcial ao tomador (ex.: Nota
            Carioca).
        NfsComments:
          type: string
          nullable: true
          description: Discriminação / observações.
        Show:
          type: integer
          enum:
            - 0
            - 1
          description: Flag de soft-hide. Apenas `Show=1` aparecem.
        Tags:
          type: array
          items:
            type: string
          description: Tags atribuídas em `NfsEventsTag`.
        XmlFile:
          type: string
          format: uri
          description: URL pré-assinada para download do XML.
        XmlDanfe:
          type: string
          format: uri
          description: URL pré-assinada da DANFSE PDF.
    CarrierInvoiceFeedItem:
      type: object
      description: >-
        Item retornado pelo `GET /cte`. Combina dados do CT-e (`CarrierInvoice`) com descrições resolvidas (`CtTpCte`,
        `CtCSit`, `CtToma`, `CttpServ`), eventual pedido vinculado (`Orders`, resolvido pela chave da NF-e citada),
        eventual conta a pagar associada (resolvida por fornecedor + `CTeNumber`), cálculos derivados (peso do pedido,
        diferenças de peso e frete) e URLs assinadas para XML/DANFE.
      properties:
        IDCarrierInvoice:
          type: integer
          format: int64
          description: Código interno da linha do CT-e.
        IDCompany:
          type: integer
          format: int64
          description: Empresa dona da nota (`IDCompany`).
        IDCompanyInvoice:
          type: integer
          format: int64
          nullable: true
          description: Empresa faturadora destinatária.
        AccountName:
          type: string
          description: Conta (subdomínio) da empresa.
        CompanyInvoiceAccountName:
          type: string
          nullable: true
          description: Conta da empresa faturadora destinatária.
        IDOrder:
          type: integer
          format: int64
          nullable: true
          description: >-
            Pedido vinculado (resolvido pela chave da NF-e citada no CT-e). `null` quando o CT-e referencia uma chave
            que não está no sistema.
        Order:
          type: string
          nullable: true
          description: Número do pedido vinculado (`Order`).
        IDConsumer:
          type: integer
          format: int64
          nullable: true
          description: Cliente do pedido vinculado.
        ConsumerReceiverName:
          type: string
          nullable: true
          description: Nome do destinatário/cliente no pedido vinculado.
        ConsumerCpfCnpj:
          type: string
          nullable: true
          description: Documento do cliente no pedido vinculado.
        SupplierNameCorporateName:
          type: string
          description: Razão social da transportadora emissora do CT-e.
        SupplierCpfCnpj:
          type: string
          description: CNPJ da transportadora.
        IDCarrier:
          type: integer
          format: int64
          nullable: true
          description: Transportadora cadastrada com integração ativa (`IDSupplier` via `TypeCarrier`).
        CTeDate:
          type: string
          format: date-time
          description: Data e hora de emissão do CT-e.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora em que o CT-e foi inserido no banco do idworks.
        CTeNumber:
          type: integer
          description: Número do CT-e.
        CTeAccessKey:
          type: string
          minLength: 44
          maxLength: 44
          description: Chave de acesso do CT-e (44 dígitos).
        NSU:
          type: integer
          nullable: true
          description: Número Sequencial Único (`NSU`) atribuído pela SEFAZ.
        CorreiosSRO:
          type: string
          nullable: true
          description: >-
            Código de rastreio dos Correios (`SRO`) — quando o CT-e é de transportador Correios e tem o campo
            preenchido.
        CTeSit:
          type: integer
          enum:
            - 1
            - 3
          description: 'Situação SEFAZ: `1` Uso autorizado, `3` CT-e Cancelada.'
        SitCteDescription:
          type: string
          enum:
            - Uso autorizado
            - CT-e Cancelada
          description: Descrição amigável da situação.
        CTeType:
          type: integer
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
          description: 'Tipo: `0` Normal, `1` Complementar, `2` Anulação, `3` Substituição, `4` Fatura.'
        CtTpCteDescription:
          type: string
          description: Descrição amigável do tipo (`CT-e Normal`, `CT-e Complementar`, `Anulação`, `Substituição`, `Fatura`).
        CTeToma:
          type: integer
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
          description: 'Tomador do frete: `0` Remetente, `1` Expedidor, `2` Recebedor, `3` Destinatário, `4` Outros.'
        CtTomaDescription:
          type: string
          description: Descrição amigável do tomador.
        CTetpServ:
          type: integer
          nullable: true
          description: Código do tipo de serviço prestado (`CttpServ`).
        CttpServDescription:
          type: string
          nullable: true
          description: Descrição amigável do tipo de serviço.
        InvoiceAccessKey:
          type: string
          minLength: 44
          maxLength: 44
          description: Chave de acesso da NF-e de produto vinculada (44 dígitos).
        InvoiceNumber:
          type: integer
          nullable: true
          description: Número da NF-e citada (posições 26 a 34 da chave de acesso `InvoiceAccessKey`).
        InvoiceSerie:
          type: integer
          nullable: true
          description: Série da NF-e citada (posições 23 a 25 da chave de acesso `InvoiceAccessKey`).
        Comments:
          type: string
          nullable: true
          description: Observações do CT-e (`Comments`).
        ShippingPostalCode:
          type: string
          nullable: true
          description: CEP do destinatário.
        ShippingCity:
          type: string
          nullable: true
          description: Cidade do destinatário.
        ShippingState:
          type: string
          nullable: true
          description: UF do destinatário.
        WeightCharged:
          type: number
          format: double
          nullable: true
          description: Peso cobrado pela transportadora no CT-e.
        OrderWeight:
          type: number
          format: double
          nullable: true
          description: Peso calculado do pedido (soma de peso × quantidade de cada item).
        WeightDifference:
          type: number
          format: double
          nullable: true
          description: Diferença entre peso cobrado e peso do pedido (`WeightCharged - OrderWeight`).
        ValueShipping:
          type: number
          format: double
          nullable: true
          description: Valor do frete (`ValueShipping`).
        ValueGrisInsurance:
          type: number
          format: double
          nullable: true
          description: Valor de GRIS + seguro.
        ValueICMS:
          type: number
          format: double
          nullable: true
          description: ICMS do CT-e.
        ValueISS:
          type: number
          format: double
          nullable: true
          description: ISS do CT-e.
        ValueTotalService:
          type: number
          format: double
          nullable: true
          description: Valor total do serviço cobrado (frete + GRIS + ICMS + ISS + acessórios).
        ValueRate:
          type: number
          format: double
          nullable: true
          description: Valor da tabela usado para gerar o CT-e.
        OrderValueShipping:
          type: number
          format: double
          nullable: true
          description: Valor do frete cobrado do cliente no pedido (`ValueShipping`).
        ValueShippingNet:
          type: number
          format: double
          nullable: true
          description: 'Resultado financeiro: `OrderValueShipping - ValueTotalService`. Positivo = sobra; negativo = prejuízo.'
        ValueShippingAuction:
          type: number
          format: double
          nullable: true
          description: >-
            Valor que o sistema simulou para a transportadora no momento do envio. `null` quando não há leilão de frete
            cadastrado.
        ValueShippingAuctionNet:
          type: number
          format: double
          nullable: true
          description: Diferença entre simulado e cobrado pela transportadora.
        IDStatusShippingAuctionDif:
          type: integer
          enum:
            - 1
            - 2
            - 3
          nullable: true
          description: >-
            Resultado da comparação simulado vs. cobrado: `1` simulado < cobrado, `2` simulado > cobrado, `3` empate. Só
            vem preenchido em modo `FreightConciliation=1`.
        PriceSellingTotal:
          type: number
          format: double
          nullable: true
          description: Valor total dos itens do pedido. Só vem preenchido em modo `FreightConciliation=1`.
        IDAccountPayableReceivable:
          type: integer
          format: int64
          nullable: true
          description: >-
            Conta a pagar associada à transportadora (resolvida por `IDSupplier` + `DocumentNumber = CTeNumber`). `null`
            quando ainda não foi lançada.
        XmlFile:
          type: string
          format: uri
          description: URL assinada para baixar o XML do CT-e do S3.
        XmlDanfe:
          type: string
          format: uri
          description: URL assinada para visualizar a DANFE em PDF.
    PurchaseFeedItem:
      type: object
      description: >-
        Item retornado pelo `GET /purchase/feed`. Combina dados de `NfEvents` com descrições resolvidas (`NfTpNf`,
        `NfCSit`, `NfTpEvent`), eventual recebimento criado (`IDPurchase`), eventual conta a pagar associada
        (`IDAccountPayableReceivable`, resolvida por fornecedor + número de documento), tags da linha (array agregado de
        `NfEventsTag`) e URLs assinadas para o XML e a DANFE.
      properties:
        IDNfEvents:
          type: integer
          format: int64
          description: Código interno da linha do feed.
        AccountName:
          type: string
          description: Conta (subdomínio) a que a nota pertence.
        AccountNameInvoice:
          type: string
          nullable: true
          description: Conta da empresa faturadora destinatária da nota.
        CompanyNameCorporateNameInvoice:
          type: string
          nullable: true
          description: Razão social da empresa faturadora destinatária.
        IDCompany:
          type: integer
          format: int64
          description: Empresa dona da nota (`IDCompany`).
        IDCompanyInvoice:
          type: integer
          format: int64
          nullable: true
          description: Empresa faturadora destinatária (quando há multi-empresa).
        SupplierNameCorporateName:
          type: string
          description: Razão social do fornecedor emitente da nota.
        SupplierCpfCnpj:
          type: string
          description: CPF/CNPJ do fornecedor.
        IDSupplier:
          type: integer
          format: int64
          nullable: true
          description: >-
            Fornecedor cadastrado no idworks com este CNPJ (`IDSupplier`, ativo). Pode vir `null` se o fornecedor ainda
            não foi cadastrado.
        NFeNumber:
          type: integer
          description: Número da NF-e.
        NFeAccessKey:
          type: string
          minLength: 44
          maxLength: 44
          description: Chave de acesso da NF-e (44 dígitos).
        NFeDate:
          type: string
          format: date-time
          description: Data e hora de emissão da NF-e.
        NFeValue:
          type: number
          format: double
          description: Valor total da NF-e (`NFeValue`).
        NFeTpNf:
          type: integer
          enum:
            - 0
            - 1
          description: Tipo da operação informado no XML — `0` Entrada, `1` Saída.
        NfTpNfDescription:
          type: string
          enum:
            - Entrada
            - Saída
          description: Descrição amigável do tipo (`NfTpNfDescription`).
        NFeSit:
          type: integer
          description: Código da situação SEFAZ (`SitNFe`).
        SitNfeDescription:
          type: string
          description: 'Descrição da situação SEFAZ. Valores conhecidos: `Uso autorizado`, `Uso denegado`, `NF-e Cancelada`.'
          enum:
            - Uso autorizado
            - Uso denegado
            - NF-e Cancelada
        NFeTpEvento:
          type: integer
          nullable: true
          description: >-
            Código do último evento registrado (`NfTpEvent`). Inclui manifestações do destinatário
            (`210200`/`210210`/`210220`/`210240`), eventos de transporte e eventos do próprio emitente (carta de
            correção, cancelamento).
        NfTpEventDescription:
          type: string
          nullable: true
          description: Descrição amigável do último evento.
        IDPurchase:
          type: integer
          format: int64
          nullable: true
          description: Recebimento criado a partir desta nota (`IDPurchase`). `null` quando ainda não foi criado.
        IDAccountPayableReceivable:
          type: integer
          format: int64
          nullable: true
          description: >-
            Conta a pagar associada à nota (resolvida por `IDSupplier` + `DocumentNumber = NFeNumber`). `null` quando
            ainda não há conta a pagar lançada.
        XmlFile:
          type: string
          format: uri
          description: >-
            URL assinada para baixar o XML do bucket S3. Formato:
            `https://<host>/<stage>/invoice/danfe?Folder=Inbound&Type=XML&Origin=Feed&token=<token>&File=<chave-acesso>`.
        XmlDanfe:
          type: string
          format: uri
          description: URL assinada para visualizar a DANFE em PDF. Mesmo formato que `XmlFile`, com `Type=PDF`.
        Tags:
          type: array
          items:
            type: string
          description: Tags internas vinculadas à nota (`Tag`). Devolvido como array.
    PurchaseItem:
      type: object
      description: Item de movimento de estoque vinculado ao recebimento (`StockKeepingUnitMovement`).
      properties:
        IDSkuMovement:
          type: integer
          format: int64
          description: >-
            Identificador da linha de movimentação de estoque gerada para o item do recebimento (uma linha por SKU/lote
            no recebimento).
        IDSku:
          type: integer
          format: int64
          description: Identificador do SKU recebido.
        IDSkuCompany:
          type: string
          nullable: true
          description: Código de referência interna do SKU.
        SkuName:
          type: string
          description: Nome do SKU.
        Quantity:
          type: number
          format: double
          description: Quantidade do SKU recebida nesta linha.
        ValueCostUnitPurchase:
          type: number
          format: double
          nullable: true
          description: Custo unitário de compra (sem rateio de frete e impostos).
        ValueCostTotal:
          type: number
          format: double
          nullable: true
          description: >-
            Custo total da linha (custo unitário × quantidade), já incluindo rateio de `ValueShipping`, descontos e
            tributos do item quando configurados na regra fiscal.
        IDBatch:
          type: integer
          format: int64
          nullable: true
          description: Identificador do lote do SKU recebido (`IDBatchNumber`). Vazio quando o SKU não usa controle de lote.
        Comments:
          type: string
          nullable: true
          description: Identificação do lote.
        ManufacturingDate:
          type: string
          format: date
          nullable: true
          description: >-
            Data de fabricação do lote recebido, no formato `YYYY-MM-DD`. Obrigatória quando o SKU exige
            rastreabilidade.
        BestBeforeDate:
          type: string
          format: date
          nullable: true
          description: Data de validade. `4000-01-01` indica ausência.
        IDStockKeepingUnitWarehouse:
          type: integer
          format: int64
          nullable: true
          description: Armazém de destino do item recebido.
        WarehouseName:
          type: string
          nullable: true
          description: Nome do armazém de destino.
        IDStockKeepingUnitLocation:
          type: integer
          format: int64
          nullable: true
          description: Endereço de armazenagem (rua/coluna/nível) sugerido para o item.
        Address:
          type: string
          nullable: true
          description: Texto do endereço de armazenagem (`Floor-Street-Module-Column-Level` ou nome livre).
        NfeCFOP:
          type: string
          nullable: true
          description: CFOP do item no recebimento (4 dígitos). Quando informado, define a natureza fiscal da entrada.
        NfeIcmsValue:
          type: number
          format: double
          nullable: true
          description: Valor do ICMS destacado para o item na NF-e de entrada.
        NfeIcmsSTValue:
          type: number
          format: double
          nullable: true
          description: Valor do ICMS-ST (Substituição Tributária) destacado para o item.
        NfeFcpSTValue:
          type: number
          format: double
          nullable: true
          description: Valor do FCP-ST (Fundo de Combate à Pobreza retido por ST) destacado para o item.
        NfeIPIValue:
          type: number
          format: double
          nullable: true
          description: Valor do IPI destacado para o item.
        NfePisValue:
          type: number
          format: double
          nullable: true
          description: Valor do PIS destacado para o item.
        NfeCofinsValue:
          type: number
          format: double
          nullable: true
          description: Valor do COFINS destacado para o item.
    PurchaseListItem:
      type: object
      description: Linha da lista de recebimentos retornada por `GET /purchase`.
      properties:
        IDPurchase:
          type: integer
          format: int64
          description: Identificador do recebimento.
        IDStatusPurchase:
          type: integer
          description: Status numérico (ver tabela na tag).
        StatusPurchase:
          type: string
          description: >-
            Descrição amigável do status do recebimento (`Aberto`, `Finalizado`, `Cancelada`, `Em conferência`,
            `Conferencia realizada`, `Ag. validação comercial`, `Ag. validação operacional`, `Recebimento autorizado`,
            `Recebimento recusado`, `Finalização recebimento autorizada`, `Ag. finalização comercial`, `Finalização
            recebimento recusada`, `Ag. finalização operacional`).
        RecordTimestamp:
          type: string
          format: date-time
          description: Data de criação.
        CheckinTimestamp:
          type: string
          format: date-time
          nullable: true
          description: Data em que a mercadoria chegou no CD.
        InvoiceFinishTimestamp:
          type: string
          format: date-time
          nullable: true
          description: Data de finalização.
        InvoiceFinishUser:
          type: string
          nullable: true
          description: Login do usuário que finalizou o recebimento. Vazio enquanto o recebimento não foi finalizado.
        RecordUserCreated:
          type: string
          nullable: true
          description: Login do usuário que criou o recebimento.
        AccountName:
          type: string
          description: Subdomínio da empresa dona do recebimento.
        AccountNameInvoice:
          type: string
          nullable: true
          description: Subdomínio da filial faturadora (quando multi-empresa). Vazio quando o faturador é a própria empresa.
        CompanyNameCorporateNameInvoice:
          type: string
          nullable: true
          description: Razão social da filial faturadora. Vazio quando o faturador é a própria empresa.
        IDSupplier:
          type: integer
          format: int64
          description: Identificador do fornecedor do recebimento.
        SupplierNameCorporateName:
          type: string
          description: Razão social do fornecedor.
        IDOrder:
          type: integer
          format: int64
          nullable: true
          description: Pedido de venda vinculado (devolução de cliente).
        Order:
          type: string
          nullable: true
          description: Código externo do pedido de venda vinculado.
        IDBuyOrder:
          type: integer
          format: int64
          nullable: true
          description: Pedido de compra vinculado ao recebimento.
        nNF:
          type: string
          nullable: true
          description: Número da NF-e.
        chNFe:
          type: string
          nullable: true
          description: Chave de acesso (44 dígitos).
        dhEmi:
          type: string
          format: date-time
          nullable: true
          description: Data de emissão da NF.
        TotalvNF:
          type: number
          format: double
          nullable: true
          description: Valor total da NF importada (`vNF` do XML).
        ValueProductsTotal:
          type: number
          format: double
          nullable: true
          description: Soma de `ValueCostTotal` dos itens do recebimento (custo total dos produtos).
        ValuePaymentTotal:
          type: number
          format: double
          nullable: true
          description: Soma dos valores das contas a pagar vinculadas ao recebimento.
        IDStockKeepingUnitDistributionCenter:
          type: integer
          format: int64
          nullable: true
          description: Centro de distribuição destino do recebimento.
        DistributionCenterName:
          type: string
          nullable: true
          description: Nome do centro de distribuição.
        WarehouseName:
          type: string
          nullable: true
          description: Nome do armazém quando o recebimento tem apenas um armazém envolvido.
        Comments:
          type: string
          nullable: true
          description: Observações livres do recebimento.
        StartTime:
          type: string
          format: date-time
          nullable: true
          description: Data do agendamento (`StockKeepingUnitPurchaseSchedule`).
        StockKeepingUnitPurchaseScheduleStatus:
          type: integer
          nullable: true
          description: 1=Recebido, 2=Agendado, 3=Atrasado, 4=Não agendado.
        StockKeepingUnitPurchaseScheduleStatusDescription:
          type: string
          nullable: true
          description: >-
            Descrição amigável do status do agendamento amarrado (`Recebido`, `Agendado`, `Atrasado`, `Não agendado`).
            Vazio quando o recebimento não tem agendamento.
        IDStockKeepingUnitPurchaseSchedule:
          type: integer
          nullable: true
          description: Identificador do agendamento de recebimento amarrado, quando houver.
    PurchaseDetail:
      type: object
      description: >-
        Detalhe do recebimento — retornado por `GET /purchase/{id}` (sem `?ItemsInvoice=1`). Inclui cabeçalho, dados do
        XML, itens, pagamentos e — quando vinculado a pedido de compra — itens do pedido para conciliação.
      allOf:
        - $ref: '#/components/schemas/PurchaseListItem'
        - type: object
          properties:
            Items:
              type: array
              items:
                $ref: '#/components/schemas/PurchaseItem'
              description: Itens (SKUs) do recebimento.
            Payments:
              type: array
              items:
                type: object
                description: Contas a pagar do recebimento (`AccountsPayableReceivable`).
              description: Parcelas/pagamentos vinculados ao recebimento.
            ItemsBuyOrder:
              type: array
              nullable: true
              items:
                type: object
                description: Itens do pedido de compra vinculado, para conciliação.
              description: Itens do pedido de compra vinculado, para conciliação. `null` quando não há pedido de compra.
            UrlFileXml:
              type: string
              format: uri
              nullable: true
              description: URL pré-assinada para download do XML.
            UrlFileDanfe:
              type: string
              format: uri
              nullable: true
              description: URL pré-assinada da DANFE PDF.
            natOp:
              type: string
              nullable: true
              description: Natureza da operação do XML.
            ValueShipping:
              type: number
              format: double
              nullable: true
              description: Valor do frete do recebimento em R$.
            PurchaseCheckinApproved:
              type: integer
              nullable: true
              enum:
                - 0
                - 1
              description: Estado de aprovação do checkin.
            PurchaseReceiptApproved:
              type: integer
              nullable: true
              enum:
                - 0
                - 1
              description: Estado de aprovação da finalização.
    PurchasePostPayload:
      type: object
      required:
        - IDSupplier
      properties:
        IDSupplier:
          type: integer
          format: int64
          description: Fornecedor.
        IDOrder:
          type: integer
          format: int64
          nullable: true
          description: Pedido relacionado (devolução de cliente, por ex.).
        IDBuyOrder:
          type: integer
          format: int64
          nullable: true
          description: Pedido de compra vinculado.
        IDCompanyInvoice:
          type: integer
          format: int64
          nullable: true
          description: Filial faturadora. Default = empresa do token.
        IDStockKeepingUnitDistributionCenter:
          type: integer
          format: int64
          nullable: true
          description: CD destino. Default = CD `Default=1` da empresa.
        Comments:
          type: string
          nullable: true
          description: Observações livres do recebimento (texto). Aceita `null`/omitido.
    PurchasePutPayload:
      type: object
      description: >-
        Body do PUT do recebimento. Campos editáveis variam conforme o status atual. `PurchaseCheckinApproved` e
        `PurchaseReceiptApproved` disparam transições de status com workflow de aprovação (exigem privilégios
        específicos).
      properties:
        IDSupplier:
          type: integer
          format: int64
          description: Fornecedor do recebimento. Precisa pertencer à empresa autenticada.
        IDOrder:
          type: integer
          format: int64
          nullable: true
          description: Pedido de venda vinculado ao recebimento (caso de devolução de cliente). Precisa pertencer à empresa.
        Comments:
          type: string
          nullable: true
          description: Observações livres do recebimento.
        IDStatusPurchase:
          type: integer
          description: >-
            Status alvo. Mudar para `0` (Aberto) em recebimento finalizado é uma reabertura — exige nenhuma venda dos
            produtos OU `InvoiceFinishTimestamp` há menos de 8 dias (`TotalDays < 8`).
        ValueShipping:
          type: number
          format: double
          description: Frete — rateado proporcionalmente por `ValueCostTotal` em todos os movimentos.
        IDBuyOrder:
          type: integer
          format: int64
          nullable: true
          description: >-
            Pedido de compra vinculado. Ao alterar, as contas a pagar do novo pedido de compra são marcadas com este
            `IDPurchase` e o status do pedido de compra passa para Aguardando recebimento (`1`).
        CheckinTimestamp:
          type: string
          format: date-time
          description: Data em que a mercadoria chegou.
        IDCompanyInvoice:
          type: integer
          format: int64
          nullable: true
          description: >-
            Filial faturadora (em ambientes multi-empresa). Quando informado, precisa ser uma filial cadastrada em
            `CompanyMain` da empresa autenticada.
        PurchaseCheckinApproved:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            `1` aprova o checkin (status 5/6/8 → 7). `0` recusa (status 5/6 → 8). Exige privilégio Authorize Comercial
            ou Operational.
        PurchaseReceiptApproved:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            `1` aprova a finalização (status 10/12/11 → 9). `0` recusa (status 10/12 → 11). Exige privilégio Authorize
            Receipt Comercial ou Operational.
        IDStockKeepingUnitDistributionCenter:
          type: integer
          format: int64
          nullable: true
          description: >-
            Centro de distribuição destino. Não pode ser alterado se já existem itens em um CD diferente do informado —
            remover os itens primeiro.
        dhEmi:
          type: string
          format: date-time
          description: Data de emissão da NF. Só editável quando XML não tem protocolo SEFAZ.
        nNF:
          type: string
          description: Número da nota fiscal. Não pode existir outro recebimento com mesmo `nNF` para o mesmo fornecedor.
        chNFe:
          type: string
          description: Chave de acesso da NF-e (44 dígitos). Não pode existir outro recebimento com a mesma chave.
        natOp:
          type: string
          description: Natureza da operação descrita no XML.
        NFeType:
          type: integer
          description: 'Tipo da NF-e: `0` Entrada, `1` Saída.'
        NFeFin:
          type: integer
          description: 'Finalidade da NF-e: `1` Normal, `2` Complementar, `3` Ajuste, `4` Devolução.'
    PurchaseSkuPostPayload:
      type: object
      required:
        - IDSku
        - Quantity
        - IDStockKeepingUnitWarehouse
      properties:
        IDSku:
          type: integer
          format: int64
          description: >-
            Identificador do SKU a entrar no estoque. Precisa pertencer à empresa, estar ativo (`IDStatusSku=1`) e ser
            de tipo comprável (`IDTypeSku` em `3`, `5`, `6` ou `7`).
        Quantity:
          type: number
          format: double
          description: Quantidade. Precisa ser > 0.
        ValueCostTotal:
          type: number
          format: double
          description: >-
            Valor de custo total da linha (quantidade × custo unitário). Inclui frete rateado quando há `ValueShipping`
            no recebimento.
        IDStockKeepingUnitWarehouse:
          type: integer
          format: int64
          description: Armazém destino. Precisa estar ativo e ser do mesmo CD do recebimento.
        IDBatch:
          type: integer
          format: int64
          nullable: true
          description: >-
            Identificador do lote (`StockKeepingUnitBatch`). Quando vazio e o SKU exige rastreamento (`Batch=1`), o
            sistema cria um lote novo a partir do texto enviado em `Comments` e da `ManufacturingDate`.
        IDStockKeepingUnitLocation:
          type: integer
          format: int64
          nullable: true
          description: >-
            Endereço de armazenagem. Quando `DefaultLocationPurchase` está parametrizado para o CD, é forçado para esse
            endereço.
        BestBeforeDate:
          type: string
          format: date
          description: Data de validade. Default `4000-01-01`.
        ManufacturingDate:
          type: string
          format: date
          nullable: true
          description: >-
            Data de fabricação do lote. Obrigatória quando o SKU tem `BatchRequired=1` ou rastreabilidade ativa. Precisa
            ser ≤ `BestBeforeDate`.
        Comments:
          type: string
          nullable: true
          description: Lote (texto).
        NfeCFOP:
          type: string
          nullable: true
          description: CFOP do item neste recebimento (4 dígitos). Quando informado, precisa existir no catálogo nacional de CFOPs.
    PurchaseCheckItem:
      type: object
      required:
        - IDSku
        - Quantity
      properties:
        IDSku:
          type: integer
          format: int64
          description: >-
            Identificador do SKU conferido. Precisa pertencer ao recebimento (existir em `StockKeepingUnitMovement` do
            recebimento) ou ser SKU divergente (vai para o armazém de divergência do CD).
        Quantity:
          type: number
          format: double
          description: Quantidade conferida fisicamente. Precisa ser > 0.
        BestBeforeDate:
          type: string
          format: date
          nullable: true
          description: Default `4000-01-01`.
        ManufacturingDate:
          type: string
          format: date
          nullable: true
          description: >-
            Data de fabricação do lote conferido. Quando o SKU exige rastreabilidade, é obrigatória e precisa ser ≤
            `BestBeforeDate`.
        BatchComments:
          type: string
          nullable: true
          description: Identificação textual do lote conferido (código do lote impresso no produto).
        Comments:
          type: string
          nullable: true
          description: Observações livres da conferência do item.
        IDStockKeepingUnitPurchaseItemsCheckFile:
          type: integer
          format: int64
          nullable: true
          description: Foto principal capturada via `/check/image?MainImg=1`.
        IDStockKeepingUnitPurchaseItemsCheckFile1:
          type: integer
          format: int64
          nullable: true
          description: Foto adicional 1 da etiqueta/produto (registrada via `POST /purchase/{idpurchase}/check/image`).
        IDStockKeepingUnitPurchaseItemsCheckFile2:
          type: integer
          format: int64
          nullable: true
          description: Foto adicional 2 da etiqueta/produto.
        IDStockKeepingUnitPurchaseItemsCheckFile3:
          type: integer
          format: int64
          nullable: true
          description: Foto adicional 3 da etiqueta/produto.
    PurchasePaymentPostPayload:
      type: object
      required:
        - IDSupplier
        - Value
        - DateDue
        - IDTypePayment
        - IDTypeDocument
        - IDTypeAccountPayble
      properties:
        IDSupplier:
          type: integer
          format: int64
          description: >-
            Fornecedor do título a pagar. Em geral é o mesmo fornecedor do recebimento, mas pode ser diferente (ex.:
            empresa de frete pago à parte).
        Value:
          type: number
          format: double
          description: Valor do título. Quando há retenções em `Taxes`, este é o líquido para o fornecedor.
        DateDue:
          type: string
          format: date
          description: Data de vencimento do título.
        IDTypePayment:
          type: integer
          format: int64
          description: Forma de pagamento (`TypePayment`). Precisa estar ativa para a empresa.
        IDTypeDocument:
          type: integer
          format: int64
          description: 'Tipo de documento (`TypeDocument`, ex.: Boleto, Duplicata, Nota Fiscal). Precisa estar ativo.'
        IDTypeAccountPayble:
          type: integer
          format: int64
          description: Plano de contas.
        DateDocument:
          type: string
          format: date
          nullable: true
          description: Data de emissão do documento. Quando vazio, herda da NF do recebimento na finalização.
        DocumentNumber:
          type: string
          nullable: true
          description: Número do documento. Quando vazio, herda da NF do recebimento na finalização.
        Comments:
          type: string
          nullable: true
          description: Observações livres do título.
        DateCompetence:
          type: string
          format: date
          nullable: true
          description: Data de competência contábil (mês de referência do lançamento).
        BankSlipBarCode:
          type: string
          nullable: true
          description: >-
            Linha digitável ou código de barras do boleto. Quando preenchido, alimenta a leitura do boleto na
            conciliação bancária.
        IDBankAccountForecast:
          type: integer
          format: int64
          nullable: true
          description: Conta bancária prevista para a baixa. Precisa pertencer à empresa.
        ValueDiscount:
          type: number
          format: double
          nullable: true
          description: Valor de desconto previsto no título.
        ValueInterest:
          type: number
          format: double
          nullable: true
          description: Valor de juros previsto no título.
        ValuePenalty:
          type: number
          format: double
          nullable: true
          description: Valor de multa prevista no título.
        Taxes:
          type: array
          description: Retenções fiscais. Cada item gera um título a pagar separado vinculado ao pagamento pai.
          items:
            type: object
            required:
              - IDSupplier
              - Value
              - DateDue
            properties:
              IDSupplier:
                type: integer
                format: int64
                description: Fornecedor da retenção (geralmente Receita Federal ou órgão equivalente).
              Value:
                type: number
                format: double
                description: >-
                  Valor da retenção fiscal. Gera um título a pagar separado vinculado ao título principal via
                  `IDAccountPayableReceivableFather`.
              DateDue:
                type: string
                format: date
                description: 'Data de vencimento da guia da retenção (ex.: data limite de recolhimento do imposto retido).'
    PurchaseReceiptPayload:
      type: array
      description: >-
        Opcional. Lista dos itens efetivamente recebidos — um objeto por SKU (podendo repetir o SKU por lote/armazém).
        Quando o corpo é omitido, a lista é montada a partir da conferência salva.
      items:
        type: object
        required:
          - IDSku
          - Quantity
        properties:
          IDSku:
            type: integer
            format: int64
            description: >-
              Identificador do SKU recebido. Precisa pertencer ao recebimento ou ser SKU divergente (roteado ao armazém
              de divergência do CD).
          Quantity:
            type: number
            format: double
            description: >-
              Quantidade efetivamente recebida. Precisa ser > 0 — do contrário `[BadRequest] - Nenhum SKU pode ter
              quantidade menor ou igual a zero, verifique antes de finalizar`.
          IDStockKeepingUnitWarehouse:
            type: integer
            format: int64
            nullable: true
            description: >-
              Armazém de destino do item recebido. Quando informado, precisa estar cadastrado e ativo; caso contrário
              `[BadRequest] - Armazém (IDStockKeepingUnitWarehouse) X não encontrado`.
          IDStockKeepingUnitLocation:
            type: integer
            format: int64
            nullable: true
            description: >-
              Endereço/localização de destino do item. Quando informado, precisa estar cadastrado e ativo; caso
              contrário `[BadRequest] - Endereço SKU X não encontrado`.
          IDBatch:
            type: integer
            format: int64
            nullable: true
            description: >-
              Lote de destino do item. Quando informado, precisa existir para o SKU; caso contrário `[BadRequest] - Lote
              (IDBatchNumber) X não encontrado para o sku: Y`.
          BestBeforeDate:
            type: string
            format: date
            nullable: true
            description: Data de validade do lote. Default `4000-01-01`.
          ManufacturingDate:
            type: string
            format: date
            nullable: true
            description: >-
              Data de fabricação do lote. Quando o SKU exige rastreabilidade, é obrigatória e precisa ser ≤
              `BestBeforeDate`.
          BatchComments:
            type: string
            nullable: true
            description: Identificação textual do lote recebido (código impresso no produto).
          Comments:
            type: string
            nullable: true
            description: Observações livres do item.
    HubSalesPolicyItem:
      type: object
      description: Mapeamento DE-PARA entre canal e política comercial interna.
      properties:
        IDHubSalesPolicy:
          type: integer
          format: int64
          description: Identificador do mapeamento de política comercial.
        IDCompanyIntegration:
          type: integer
          format: int64
          description: 'Identificador da integração (canal): referência a `CompanyIntegration`.'
        CompanyIntegration:
          type: string
          description: Concatenação `{IntegrationName} - {CompanyIntegrationName}` para exibição.
        CompanyIntegrationName:
          type: string
          description: Nome amigável da integração (canal) configurado pela empresa.
        IntegrationName:
          type: string
          description: Nome do tipo de integração (Mercado Livre, Vtex, etc.).
        IDTypeCompanyIntegration:
          type: integer
          description: Tipo de integração. `10`=Mercado Livre, `23`=Vtex. Define quais campos têm comportamento especial.
        IDSalesPolicyFrom:
          type: string
          nullable: true
          description: Código de política no canal (lado DE).
        IDSalesPolicyTo:
          type: integer
          format: int64
          description: 'Identificador da política comercial interna (lado PARA): referência a `CompanySalesPolicy`.'
        CompanySalesPolicy:
          type: string
          description: Nome da política comercial interna.
        ShippingFree:
          type: integer
          nullable: true
          enum:
            - 0
            - 1
            - null
          description: >-
            Filtro de frete grátis. `1`=Sim, `0`=Não, `null`=Ambos (ignorar filtro). Apenas para Mercado Livre; em
            outras integrações é forçado a `null`.
        IDOrderType:
          type: integer
          format: int64
          nullable: true
          description: Tipo de pedido (referência a `TypeOrder`).
        TypeOrder:
          type: string
          nullable: true
          description: Descrição do tipo de pedido.
        AccountName:
          type: string
          description: Identificador da empresa proprietária do mapeamento.
    HubSalesPolicyPayload:
      type: object
      required:
        - IDCompanyIntegration
        - IDSalesPolicyTo
      properties:
        IDCompanyIntegration:
          type: integer
          format: int64
          description: Integração (canal de venda) à qual o mapeamento se aplica.
        IDSalesPolicyTo:
          type: integer
          format: int64
          description: Política comercial interna (lado PARA).
        IDSalesPolicyFrom:
          type: string
          nullable: true
          description: Código de política no canal. **Obrigatório quando `IDTypeCompanyIntegration = 23` (Vtex)**.
        ShippingFree:
          type: integer
          nullable: true
          enum:
            - 0
            - 1
          description: >-
            Filtro de frete grátis (`1`=Sim, `0`=Não). Aceito apenas para Mercado Livre (`IDTypeCompanyIntegration =
            10`). Forçado a `null` no servidor em qualquer outra integração.
        IDOrderType:
          type: integer
          format: int64
          nullable: true
          description: Tipo de pedido associado (filtro adicional).
    PaymentHubItem:
      type: object
      description: Mapeamento DE-PARA — Hub Pagamento.
      properties:
        IDHubPagamento:
          type: integer
          format: int64
          description: Identificador do mapeamento de forma de pagamento.
        IDCompanyIntegration:
          type: integer
          format: int64
          description: Integração (canal) à qual o mapeamento se aplica.
        CompanyIntegration:
          type: string
          description: Concatenação `{IntegrationName} - {CompanyIntegrationName}`.
        CompanyIntegrationName:
          type: string
          description: Nome amigável da integração configurado pela empresa.
        IntegrationName:
          type: string
          description: 'Nome do tipo de integração (ex.: `Mercado Livre`, `Magalu`, `Shopee`).'
        IDTypeCompanyIntegration:
          type: integer
          description: Tipo da integração (`IDTypeCompanyIntegration`).
        IDPaymentFrom:
          type: string
          nullable: true
          description: >-
            Código de forma de pagamento usado pelo canal (string). Em integrações cujo tipo NÃO é 23, 24, 34, 45 ou 53,
            na edição (PUT) o sistema preenche automaticamente este campo com o `IDSalesChannel` da integração quando o
            body envia vazio.
        IDPaymentTo:
          type: integer
          format: int64
          description: Tipo de pagamento interno (referência a `TypePayment`).
        AccountName:
          type: string
          description: Identificador da empresa proprietária do mapeamento.
    PaymentHubPayload:
      type: object
      required:
        - IDCompanyIntegration
        - IDPaymentTo
      properties:
        IDCompanyIntegration:
          type: integer
          format: int64
          description: Integração (canal) à qual o mapeamento se aplica.
        IDPaymentFrom:
          type: string
          nullable: true
          description: >-
            Código de forma de pagamento usado pelo canal (string). Em integrações cujo tipo NÃO é 23, 24, 34, 45 ou 53,
            na edição (PUT) o sistema preenche automaticamente este campo com o `IDSalesChannel` da integração quando o
            body envia vazio.
        IDPaymentTo:
          type: integer
          format: int64
          description: Tipo de pagamento interno (referência a `TypePayment`).
        Antifraud:
          type: integer
          nullable: true
          description: Indicador de antifraude do pagamento.
    BrandHubItem:
      type: object
      description: Mapeamento DE-PARA — Hub Marcas.
      properties:
        IDHubMarcas:
          type: integer
          format: int64
          description: Identificador do mapeamento de marca.
        IDCompanyIntegration:
          type: integer
          format: int64
          description: Integração (canal) à qual o mapeamento se aplica.
        CompanyIntegration:
          type: string
          description: Concatenação `{IntegrationName} - {CompanyIntegrationName}`.
        CompanyIntegrationName:
          type: string
          description: Nome amigável da integração configurado pela empresa.
        IntegrationName:
          type: string
          description: 'Nome do tipo de integração (ex.: `Mercado Livre`, `Magalu`, `Shopee`).'
        IDTypeCompanyIntegration:
          type: integer
          description: Tipo da integração.
        IDBrandFrom:
          type: string
          nullable: true
          description: Código de marca usado pelo canal (string).
        IDBrandTo:
          type: integer
          format: int64
          description: Marca interna (referência a `StockKeepingUnitBrand`).
        AccountName:
          type: string
          description: Identificador da empresa proprietária do mapeamento.
    BrandHubPayload:
      type: object
      required:
        - IDCompanyIntegration
        - IDBrandTo
      properties:
        IDCompanyIntegration:
          type: integer
          format: int64
          description: Integração (canal) à qual o mapeamento se aplica.
        IDBrandFrom:
          type: string
          nullable: true
          description: Código de marca usado pelo canal (string).
        IDBrandTo:
          type: integer
          format: int64
          description: Marca interna (referência a `StockKeepingUnitBrand`).
    CategoryHubItem:
      type: object
      description: Mapeamento DE-PARA — Hub Categorias.
      properties:
        IDHubCategorias:
          type: integer
          format: int64
          description: Identificador do mapeamento de categoria.
        IDCompanyIntegration:
          type: integer
          format: int64
          description: Integração (canal) à qual o mapeamento se aplica.
        CompanyIntegration:
          type: string
          description: Concatenação `{IntegrationName} - {CompanyIntegrationName}`.
        CompanyIntegrationName:
          type: string
          description: Nome amigável da integração configurado pela empresa.
        IntegrationName:
          type: string
          description: Nome do tipo de integração.
        IDTypeCompanyIntegration:
          type: integer
          description: Tipo da integração.
        IDCategoryFrom:
          type: string
          nullable: true
          description: Código de categoria usado pelo canal (string).
        IDCategoryTo:
          type: integer
          format: int64
          description: Categoria interna (referência a `StockKeepingUnitCategory`).
        AccountName:
          type: string
          description: Identificador da empresa proprietária do mapeamento.
        CategoryFromTree:
          type: string
          nullable: true
          description: 'Árvore completa da categoria no canal (ex.: ''Eletrônicos > TV > Smart TV'').'
    CategoryHubPayload:
      type: object
      required:
        - IDCompanyIntegration
        - IDCategoryTo
      properties:
        IDCompanyIntegration:
          type: integer
          format: int64
          description: Integração (canal) à qual o mapeamento se aplica.
        IDCategoryFrom:
          type: string
          nullable: true
          description: Código de categoria usado pelo canal (string).
        IDCategoryTo:
          type: integer
          format: int64
          description: Categoria interna (referência a `StockKeepingUnitCategory`).
        CategoryFromTree:
          type: string
          nullable: true
          description: 'Árvore completa da categoria no canal (ex.: ''Eletrônicos > TV > Smart TV'').'
    WarehouseHubItem:
      type: object
      description: Mapeamento DE-PARA — Hub Estoque.
      properties:
        IDHubEstoque:
          type: integer
          format: int64
          description: Identificador do mapeamento de armazém.
        IDCompanyIntegration:
          type: integer
          format: int64
          description: Integração (canal) à qual o mapeamento se aplica.
        CompanyIntegration:
          type: string
          description: Concatenação `{IntegrationName} - {CompanyIntegrationName}`.
        CompanyIntegrationName:
          type: string
          description: Nome amigável da integração configurado pela empresa.
        IntegrationName:
          type: string
          description: Nome do tipo de integração.
        IDTypeCompanyIntegration:
          type: integer
          description: Tipo da integração.
        IDStockKeepingUnitWarehouseFrom:
          type: string
          nullable: true
          description: Código de armazém usado pelo canal (string). **Obrigatório**.
        IDStockKeepingUnitWarehouseTo:
          type: integer
          format: int64
          description: Armazém interno (referência a `StockKeepingUnitWarehouse`, apenas ativos).
        AccountName:
          type: string
          description: Identificador da empresa proprietária do mapeamento.
        IDOrderType:
          type: integer
          format: int64
          description: Tipo de pedido (referência a `TypeOrder`). Obrigatório.
        IDStatusOrder:
          type: integer
          nullable: true
          description: Status final opcional (apenas onde `ChangeOnCreate = 1`).
        WarehouseName:
          type: string
          nullable: true
          description: Nome do armazém interno mapeado (WarehouseName). Nulo quando não há armazém vinculado.
        Status:
          type: integer
          nullable: true
          enum:
            - 0
            - 1
          description: >-
            Indicador de armazém ativo: 1 = ativo, 0 = inativo. Refere-se ao armazém interno mapeado; não confundir com
            tipo de armazém.
        TypeOrder:
          type: string
          nullable: true
          description: Descrição do tipo de pedido associado (TypeOrder). Nulo quando não definido.
        StatusOrder:
          type: string
          nullable: true
          description: Nome do status do pedido aplicado no recebimento deste mapeamento (StatusOrder). Nulo quando não definido.
        StatusColorCode:
          type: string
          nullable: true
          description: >-
            Código hexadecimal da cor do status do pedido (ex.: #18AA8C), para exibição. Nulo quando o status do pedido
            não está definido.
    WarehouseHubPayload:
      type: object
      required:
        - IDCompanyIntegration
        - IDStockKeepingUnitWarehouseFrom
        - IDStockKeepingUnitWarehouseTo
        - IDOrderType
      properties:
        IDCompanyIntegration:
          type: integer
          format: int64
          description: Integração (canal) à qual o mapeamento se aplica.
        IDStockKeepingUnitWarehouseFrom:
          type: string
          nullable: true
          description: Código de armazém usado pelo canal (string). **Obrigatório**.
        IDStockKeepingUnitWarehouseTo:
          type: integer
          format: int64
          description: Armazém interno (referência a `StockKeepingUnitWarehouse`, apenas ativos).
        IDOrderType:
          type: integer
          format: int64
          description: Tipo de pedido aplicado quando o pedido entrar por este armazém.
        IDStatusOrder:
          type: integer
          nullable: true
          description: >-
            Status final aplicado ao pedido na criação. Aceita apenas valores de `TypeStatusOrder` configurados com
            `ChangeOnCreate = 1`.
    HubMessageItem:
      type: object
      description: Template de mensagem (`HubProductQuestionAnswerTemplate`).
      properties:
        IDHubProductQuestionAnswerTemplate:
          type: integer
          format: int64
          description: Identificador do modelo de mensagem.
        AccountName:
          type: string
          description: Identificador da empresa proprietária do modelo.
        AnswerType:
          type: integer
          enum:
            - 1
            - 2
          description: '`1` Resposta pré-cadastrada, `2` Mensagem automática.'
        AnswerTypeDescription:
          type: string
          description: Descrição amigável do tipo de resposta (`Resposta pré-cadastrada` ou `Mensagem automática`).
        Title:
          type: string
          nullable: true
          description: Identificador da mensagem. Obrigatório quando `AnswerType=2`.
        Answer:
          type: string
          description: Texto da mensagem com variáveis dinâmicas (`{{Nickname}}` etc.).
    HubMessagePayload:
      type: object
      required:
        - AnswerType
        - Answer
      properties:
        AnswerTemplate:
          type: string
          description: Texto do template de resposta.
        AnswerTitle:
          type: string
          nullable: true
          description: Título do template de resposta.
        AnswerType:
          type: integer
          enum:
            - 1
            - 2
          description: >-
            Tipo de modelo. `1` Resposta pré-cadastrada (selecionada manualmente ao responder), `2` Mensagem automática
            (disparada por gatilho do canal).
    HubQuestionAnswerItem:
      type: object
      description: Pergunta do comprador sobre um anúncio do canal (`HubProductQuestionAnswer`).
      properties:
        IDHubProductQuestionAnswer:
          type: integer
          format: int64
          description: Identificador interno da pergunta/resposta.
        AccountName:
          type: string
          description: Identificador da empresa que recebeu a pergunta.
        IDCompanyIntegration:
          type: integer
          format: int64
          description: Integração (canal) em que o anúncio está publicado.
        CompanyIntegration:
          type: string
          description: Concatenação `{IntegrationName} - {CompanyIntegrationName}` para exibição.
        IDHubProduct:
          type: integer
          format: int64
          description: Identificador interno do anúncio (`IDHubProduct`) a que a pergunta se refere.
        ProductName:
          type: string
          description: Nome do anúncio no momento da pergunta.
        AdvertisementCode:
          type: string
          description: Código do anúncio no canal.
        ReferenceCode:
          type: string
          nullable: true
          description: Código de referência do produto (SKU/EAN cadastrado).
        Question:
          type: string
          description: Texto da pergunta feita pelo comprador no canal.
        Answer:
          type: string
          nullable: true
          description: Texto da resposta enviada. `null` enquanto a pergunta não tiver sido respondida.
        Nickname:
          type: string
          nullable: true
          description: Apelido do comprador no canal.
        QuestionTimestamp:
          type: string
          format: date-time
          description: Data/hora em que a pergunta foi feita pelo comprador.
        AnswerTimestamp:
          type: string
          format: date-time
          nullable: true
          description: Data/hora em que a resposta foi enviada. `null` enquanto não respondida.
        IDTypeHubProductQuestionAnswerStatus:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
            - 7
          description: >-
            Status da pergunta no canal: `1` Não respondido, `2` Respondido, `3` Nunca respondido, `4` Em análise, `7`
            Banido.
        AdvertisementUrl:
          type: string
          format: uri
          nullable: true
          description: URL pública do anúncio no canal.
    HubOrderItem:
      type: object
      description: >-
        Linha do staging de Pedidos Integrados — pacote/pedido bruto vindo do canal. **Os nomes de campo abaixo são
        exatamente os emitidos pelo sistema** (`orderHubList` / `orderHubGet`), iguais aos nomes dos campos de
        `HubOrder` e entidades correlatas.
      properties:
        IDIntegration:
          type: integer
          format: int64
          description: Identificador único da linha de staging (`IDIntegration`).
        AccountName:
          type: string
          description: Identificador da empresa dona do pedido.
        IDCompany:
          type: integer
          format: int64
          description: Empresa dona da integração (vinculo `IDCompany`). Presente em `orderHubGet`.
        IDCompanyIntegration:
          type: integer
          format: int64
          description: Integração (canal) de onde o pedido veio.
        CompanyIntegrationName:
          type: string
          description: Nome interno da integração (instância do canal na empresa).
        IntegrationName:
          type: string
          description: 'Nome do tipo de integração (ex.: `Meli`, `VTEX`, `Shopify`).'
        IntegrationLogoUrl:
          type: string
          nullable: true
          description: URL do logo do tipo de integração (presente em `orderHubGet`).
        CompanyIntegration:
          type: string
          description: Concatenação `{IntegrationName} - {CompanyIntegrationName}` para exibição (montada apenas em `orderHubGet`).
        IDTypeCompanyIntegration:
          type: integer
          description: Tipo da integração (`IDTypeCompanyIntegration`).
        IDSalesChannel:
          type: integer
          nullable: true
          description: Identificador do canal de vendas (`IDSalesChannel`).
        SalesChannelName:
          type: string
          description: Nome do canal de vendas (alias de `IntegrationName`).
        OrderId:
          type: string
          description: Pedido origem (código no canal). Em alguns canais é o ID do pacote — vide `PackId`.
        PackId:
          type: string
          nullable: true
          description: ID do pacote no canal (alguns canais agrupam vários pedidos).
        IDOrder:
          type: integer
          format: int64
          nullable: true
          description: Identificador do pedido idworks após criação. `null` enquanto não criado.
        Order:
          type: string
          nullable: true
          description: Número do pedido idworks (`Order`). `null` enquanto o pedido idworks não tiver sido criado.
        Status:
          type: string
          description: Status do pedido no canal (string crua devolvida pela integração).
        HubOrderStatus:
          type: string
          nullable: true
          description: Descrição amigável do status do canal (`Description`).
        IDStatusOrder:
          type: integer
          nullable: true
          description: Status do pedido idworks (`IDStatusOrder`). `null` enquanto o pedido não tiver sido criado.
        StatusOrder:
          type: string
          nullable: true
          description: Descrição textual do status do pedido idworks (vazio enquanto não criado).
        IDStatusInvoice:
          type: integer
          nullable: true
          description: Status da NF (`IDStatusInvoice` quando `Main=1`).
        StatusInvoice:
          type: string
          description: Descrição textual do status da NF. `Pendente` quando ainda não foi emitida.
        CreateOrder:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` quando o status do canal permite criar o pedido idworks; `0` caso contrário (`CreateOrder`).'
        CreateOrderDescription:
          type: string
          description: '`Sim`/`Não` correspondente ao `CreateOrder` (lookup em `TypeYesNo`).'
        RecordTimestamp:
          type: string
          format: date-time
          description: Data/hora em que a linha de staging foi gravada no idworks.
        CreationTimestamp:
          type: string
          format: date-time
          description: Data/hora do pedido no canal (`CreationTimestamp`).
        ConsumerFirstName:
          type: string
          nullable: true
          description: Primeiro nome do comprador retornado pelo canal.
        ConsumerEmail:
          type: string
          nullable: true
          description: E-mail do comprador retornado pelo canal (frequentemente mascarado pela plataforma de origem).
        ConsumerDocument:
          type: string
          nullable: true
          description: CPF/CNPJ do comprador retornado pelo canal.
        QuantityItems:
          type: integer
          description: Quantidade total de itens no pacote (soma das quantidades de `HubOrderProduct`).
        QuantityPayments:
          type: integer
          description: Número de registros de pagamento associados ao pacote.
        TotalItemsValue:
          type: number
          format: double
          description: Soma do valor dos itens (quantidade × preço de venda de cada item), sem frete/desconto/juros.
        TotalDiscountValue:
          type: number
          format: double
          nullable: true
          description: Desconto total aplicado ao pacote pelo canal.
        TotalShippingValue:
          type: number
          format: double
          nullable: true
          description: Valor de frete cobrado do comprador no canal.
        TotalInterestValue:
          type: number
          format: double
          nullable: true
          description: Acréscimo (juros/taxa) cobrado do comprador no canal — comum em parcelamento sem cartão.
        TotalOrderValue:
          type: number
          format: double
          description: Valor total do pacote (itens − descontos + frete + juros).
        IDWarehouseHub:
          type: integer
          nullable: true
          description: Identificador do armazém-hub destino (resolve a partir de `IDWarehouseHub` do primeiro item).
        Origin:
          type: string
          nullable: true
          description: Origem do registro (campo cru `Origin` — geralmente o nome do consumidor do webhook que gerou a linha).
        ShippingId:
          type: string
          nullable: true
          description: Código de rastreio quando aplicável.
        ShippingCourierId:
          type: string
          nullable: true
          description: Identificador da transportadora no canal (`ShippingCourierId`).
        Coupon:
          type: string
          nullable: true
          description: Código do cupom de desconto aplicado no canal, quando houver.
        UtmCampaign:
          type: string
          nullable: true
          description: Parâmetro `utm_campaign` capturado do checkout do canal.
        UtmMedium:
          type: string
          nullable: true
          description: Parâmetro `utm_medium` capturado do checkout do canal.
        UtmSource:
          type: string
          nullable: true
          description: Parâmetro `utm_source` capturado do checkout do canal.
        UtmiCampaign:
          type: string
          nullable: true
          description: Parâmetro `utmi_campaign` capturado do checkout do canal (variante interna do canal).
        UtmiPage:
          type: string
          nullable: true
          description: Parâmetro `utmi_page` capturado do checkout do canal.
        UtmiPart:
          type: string
          nullable: true
          description: Parâmetro `utmi_part` capturado do checkout do canal.
        ShippingEstimateDate:
          type: string
          format: date
          nullable: true
          description: Data estimada de entrega prometida ao comprador no canal.
        ShippingEstimateHandlingLimitDate:
          type: string
          format: date
          nullable: true
          description: Data limite que o canal estabelece para o pacote ser despachado.
        SalesChannelOrderLink:
          type: string
          format: uri
          nullable: true
          description: >-
            URL do pedido no canal de venda. Montado apenas para alguns tipos de integração (VTEX, Mercado Livre,
            SkyHub, Olist).
        SKUs:
          type: array
          description: >-
            Itens do pacote (`HubOrderProduct`). Cada item traz `IDSku, IDSkuHub, ProductDetail, IDSkuCompany, SkuName,
            Quantity, PriceSelling, IDWarehouseHub, IDProductHub, ValueDiscount, IDIntegrationProducts, IDHubProduct`.
          items:
            type: object
        Payments:
          type: array
          description: >-
            Pagamentos do pacote (`HubOrderPayment`). Cada item traz `Acquirer, Connector, Installments, PaymentSystem,
            PaymentSystemName, TransactionIdentifier, InterestValue, Value`.
          items:
            type: object
        Messages:
          type: array
          description: Histórico de mensagens trocadas com o comprador (presente apenas em `orderHubGet`).
          items:
            type: object
        Claims:
          type: array
          description: Reclamações abertas no canal (presente apenas em `orderHubGet`).
          items:
            type: object
        ClaimsMessages:
          type: array
          description: Mensagens vinculadas às reclamações (presente apenas em `orderHubGet`).
          items:
            type: object
    HubOrderPostPayload:
      type: object
      required:
        - IDCompanyIntegration
        - OrderFrom
      properties:
        IDCompanyIntegration:
          type: integer
          format: int64
          description: Integração (canal) de onde o pedido será buscado.
        OrderFrom:
          type: string
          description: Código do pedido no canal (origem).
        ShippingId:
          type: string
          nullable: true
          description: ID de remessa — usado apenas para Mercado Livre OnSite (`IDTypeCompanyIntegration=1`).
    HubProductSizeChartRowAttribute:
      type: object
      description: >-
        Cada atributo de medida de uma linha da grade — por exemplo `BR_SIZE = M`, ou `WAIST_CIRCUMFERENCE_FROM = 72`
        com `Unit = cm`.
      properties:
        IDHubProductSizeChartRow:
          type: integer
          format: int64
          description: Identificador interno do atributo.
        IDHubProductSizeChart:
          type: integer
          format: int64
          description: Grade de tamanho a que o atributo pertence.
        FieldId:
          type: string
          description: >-
            Identificador técnico do campo de medida (ex.: `BR_SIZE`, `WAIST_CIRCUMFERENCE_FROM`). Os valores aceitos
            saem do catálogo do canal correspondente.
        FieldName:
          type: string
          description: Nome legível do campo de medida exibido na grade.
        FieldValue:
          type: string
          description: 'Valor da medida (ex.: `M`, `72`, `40-42`).'
        Unit:
          type: string
          nullable: true
          description: 'Unidade de medida quando aplicável (ex.: `cm`, `kg`).'
    HubProductSizeChartRow:
      type: object
      description: Linha (tamanho) da grade. Reúne todos os atributos de medida que descrevem aquele tamanho.
      properties:
        RowId:
          type: string
          description: 'Código único do tamanho dentro da grade (ex.: `1`, `S`, `38`). Não pode se repetir na mesma grade.'
        Attributes:
          type: array
          items:
            $ref: '#/components/schemas/HubProductSizeChartRowAttribute'
          description: Lista de atributos de medida da linha.
    HubProductSizeChartItem:
      type: object
      description: Resumo de uma grade de tamanho mapeada à integração.
      properties:
        IDHubProductSizeChart:
          type: integer
          format: int64
          description: Identificador da grade de tamanho.
        IDCompanyIntegration:
          type: integer
          format: int64
          description: Integração à qual a grade pertence.
        ExternalId:
          type: string
          nullable: true
          description: Identificador externo da grade no canal. Preenchido após sincronização bem-sucedida.
        SizeChartName:
          type: string
          description: 'Nome amigável da grade (ex.: `Camisetas masculinas adulto`).'
        TypeMeasure:
          type: string
          description: >-
            Tipo de medida da grade — ver lista de tipos em `TypeHubProductSizeChartTypeMeasure` (ex.: `BR_SIZE`,
            `CLOTHING_MEASURE`, `MIXED_MEASURE`).
        TypeMeasureDescription:
          type: string
          description: 'Descrição amigável do tipo de medida (ex.: `Medidas da peça`).'
        Gender:
          type: string
          nullable: true
          description: 'Gênero a que a grade se aplica (ex.: `Masculino`, `Feminino`, `Unissex`).'
        GenderId:
          type: string
          nullable: true
          description: Identificador técnico do gênero usado pelo canal.
        CatalogDomain:
          type: string
          nullable: true
          description: 'Domínio de catálogo no canal (ex.: `MLB-FOOTWEAR`). Determina quais campos de medida estão disponíveis.'
        CatalogDomainName:
          type: string
          nullable: true
          description: Nome amigável do domínio de catálogo.
        SizeChartStatus:
          type: integer
          description: Status da grade. `1` ativa · `2` pendente de sincronização.
        CompanyIntegration:
          type: string
          description: 'Nome composto da integração (ex.: `Mercado Livre - Loja Principal`).'
        CompanyIntegrationName:
          type: string
          description: Nome amigável da integração.
        IntegrationLogoUrl:
          type: string
          nullable: true
          description: URL do logotipo do canal.
        AccountName:
          type: string
          description: Identificador da empresa.
    HubProductSizeChartDetail:
      allOf:
        - $ref: '#/components/schemas/HubProductSizeChartItem'
        - type: object
          properties:
            HubProductSizeChartRow:
              type: array
              items:
                $ref: '#/components/schemas/HubProductSizeChartRow'
              description: Linhas (tamanhos) que compõem a grade, com todos os atributos de medida.
    HubProductSizeChartCreate:
      type: object
      required:
        - IDCompanyIntegration
        - SizeChartName
        - TypeMeasure
      properties:
        IDCompanyIntegration:
          type: integer
          format: int64
          description: Integração à qual a grade será vinculada.
        SizeChartName:
          type: string
          description: Nome amigável da grade.
        TypeMeasure:
          type: string
          description: 'Tipo de medida — ver `TypeHubProductSizeChartTypeMeasure` (ex.: `MIXED_MEASURE`, `BR_SIZE`).'
        Gender:
          type: string
          nullable: true
          description: Gênero da grade.
        GenderId:
          type: string
          nullable: true
          description: Identificador técnico do gênero no canal.
        CatalogDomain:
          type: string
          nullable: true
          description: 'Domínio de catálogo no canal (ex.: `MLB-FOOTWEAR`).'
        HubProductSizeChartRow:
          type: array
          description: >-
            Linhas (tamanhos) da grade. Cada linha tem um `RowId` único e os atributos de medida que descrevem aquele
            tamanho.
          items:
            type: object
            required:
              - RowId
            properties:
              RowId:
                type: string
                description: Código único do tamanho na grade.
              Attributes:
                type: array
                items:
                  type: object
                  required:
                    - FieldId
                    - FieldValue
                  properties:
                    FieldId:
                      type: string
                      description: Identificador técnico do campo de medida.
                    FieldName:
                      type: string
                      description: Nome legível do campo.
                    FieldValue:
                      type: string
                      description: Valor da medida.
                    Unit:
                      type: string
                      nullable: true
                      description: Unidade da medida quando aplicável.
                description: >-
                  Atributos de medida que descrevem o tamanho da linha (`FieldId`, `FieldValue`, opcionalmente
                  `FieldName` e `Unit`).
    HubProductSizeChartUpdate:
      type: object
      description: Apenas o nome e o tipo de medida podem ser alterados depois de criada a grade. Outros campos são imutáveis.
      properties:
        SizeChartName:
          type: string
          description: Novo nome da grade.
        TypeMeasure:
          type: string
          description: >-
            Novo tipo de medida. **Não pode** ser alterado se a grade já foi sincronizada com o canal (existe
            `ExternalId`).
    HubProductSizeChartRowPayload:
      type: object
      required:
        - RowId
      description: >-
        Payload para adicionar uma nova linha (tamanho) à grade. `RowId` deve ser único dentro da grade. Atributos com
        `FieldId`+`FieldValue` já existentes nessa grade são rejeitados.
      properties:
        RowId:
          type: string
          description: Código único do tamanho.
        Attributes:
          type: array
          items:
            type: object
            required:
              - FieldId
              - FieldValue
            properties:
              FieldId:
                type: string
                description: 'Identificador técnico do campo de medida no canal (ex.: `BR_SIZE`).'
              FieldName:
                type: string
                description: Nome legível do campo de medida exibido na grade.
              FieldValue:
                type: string
                description: 'Valor da medida (ex.: `M`, `72`, `40-42`).'
              Unit:
                type: string
                nullable: true
                description: 'Unidade de medida quando aplicável (ex.: `cm`, `kg`).'
          description: >-
            Atributos de medida da linha (cada um identifica uma característica do tamanho — ex.: `BR_SIZE`,
            `WAIST_CIRCUMFERENCE_FROM`).
    HubProductSizeChartRowUpdatePayload:
      type: object
      description: >-
        Payload para atualizar (upsert) atributos de uma linha existente. Combinações `FieldId` já existentes são
        atualizadas; novas são inseridas.
      properties:
        Attributes:
          type: array
          items:
            type: object
            required:
              - FieldId
              - FieldValue
            properties:
              FieldId:
                type: string
                description: Identificador técnico do campo de medida no canal.
              FieldName:
                type: string
                description: Nome legível do campo de medida.
              FieldValue:
                type: string
                description: Novo valor da medida.
              Unit:
                type: string
                nullable: true
                description: Unidade de medida quando aplicável.
          description: >-
            Atributos de medida a inserir ou atualizar — combinações `FieldId` já existentes são atualizadas; novas são
            adicionadas.
    HubProductPromotionItem:
      type: object
      description: >-
        Resumo de uma promoção do hub vinculada à empresa autenticada. O conjunto de campos varia conforme o tipo da
        promoção e seu estágio de sincronização com o canal.
      properties:
        IDHubProductPromotion:
          type: integer
          format: int64
          description: Identificador interno da promoção.
        IDCompanyIntegration:
          type: integer
          format: int64
          description: Integração (canal) à qual a promoção pertence.
        CompanyIntegration:
          type: string
          description: 'Nome composto da integração (ex.: `Mercado Livre - Loja Principal`).'
        CompanyIntegrationName:
          type: string
          description: Nome amigável da integração configurado pela empresa.
        IDTypeCompanyIntegration:
          type: integer
          description: Tipo da integração.
        IntegrationLogoUrl:
          type: string
          nullable: true
          description: URL do logotipo do canal — usado pela tela para identificar visualmente a origem da promoção.
        PromotionId:
          type: string
          nullable: true
          description: Identificador da promoção no canal externo.
        PromotionName:
          type: string
          nullable: true
          description: Nome da promoção. Para `Campanha vendedor` é limitado a 25 caracteres.
        IDTypeHubProductPromotion:
          type: integer
          description: Tipo de promoção. Consulte `/type/hub/product/promotion/type` para a lista completa.
        TypeHubProductPromotionDescription:
          type: string
          description: 'Descrição amigável do tipo (ex.: `Tradicional`, `Campanha vendedor`, `Oferta relâmpago`).'
        TypeHubProductPromotionId:
          type: string
          description: 'Identificador técnico do tipo no canal (ex.: `DEAL`, `SELLER_CAMPAIGN`, `LIGHTNING`).'
        IDTypeHubProductPromotionStatus:
          type: integer
          description: >-
            Status. `1` Ativo · `2` Iniciado · `3` Programada · `4` Candidato · `5` Finalizada · `6` Ativação pendente ·
            `7` Exclusão pendente · `8` Excluido.
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 7
            - 8
        TypeHubProductPromotionStatus:
          type: string
          description: Descrição amigável do status.
        DateFrom:
          type: string
          format: date
          nullable: true
          description: Início da vigência da promoção.
        DateTo:
          type: string
          format: date
          nullable: true
          description: Fim da vigência da promoção.
        DateDeadline:
          type: string
          format: date
          nullable: true
          description: >-
            Data limite para o vendedor aderir (campanhas com candidatura). Após essa data não é mais possível incluir
            itens.
        SellerPercent:
          type: number
          nullable: true
          description: Percentual de desconto aplicado pelo vendedor (entre `0.10` e `0.70` para Campanha vendedor).
        IntegrationPercent:
          type: number
          nullable: true
          description: Percentual de co-participação assumido pelo canal.
        IntegrationStatus:
          type: integer
          description: Estado da última sincronização. `0` Erro · `1` Sucesso · `2` Pendente.
        IntegrationStatusName:
          type: string
          nullable: true
          description: Descrição do status de integração.
        IntegrationErrorDescription:
          type: string
          nullable: true
          description: Mensagem de erro retornada pelo canal na última tentativa de sincronização.
        HubProductPromotionItemCount:
          type: integer
          description: Quantidade de anúncios incluídos na promoção.
        AccountName:
          type: string
          description: Identificador da empresa proprietária da promoção.
        SellerCreate:
          type: integer
          description: >-
            `1` quando o vendedor pode criar este tipo de promoção localmente; `0` quando a promoção é gerada no canal e
            apenas recebida no idworks. **Não retornado pelo `GET /hub/product/promotion` (listagem)** — disponível
            apenas no GET de detalhe, no POST/PUT/DELETE de item e em endpoints que fazem o JOIN com
            `TypeHubProductPromotion`.
    HubProductPromotionAdvertisement:
      type: object
      description: >-
        Anúncio incluído em uma promoção. Os campos preenchidos variam conforme o tipo da promoção (preço fixo,
        intervalo permitido, quantidade, etc.).
      properties:
        IDHubProductPromotionItem:
          type: integer
          format: int64
          description: Identificador interno do item da promoção.
        IDProductHub:
          type: string
          description: 'Identificador do anúncio no canal (ex.: `MLB123456789`).'
        IDHubProduct:
          type: integer
          format: int64
          nullable: true
          description: Identificador interno do anúncio quando há vínculo com cadastro idworks.
        HubProductName:
          type: string
          nullable: true
          description: Nome do anúncio.
        MainImageURL:
          type: string
          nullable: true
          description: URL da imagem principal do anúncio.
        SellingPrice:
          type: number
          nullable: true
          description: Preço promocional aplicado ao anúncio.
        OriginalPrice:
          type: number
          nullable: true
          description: Preço original do anúncio no canal antes da promoção.
        EffectiveDiscountPercent:
          type: string
          nullable: true
          description: Desconto efetivo calculado (`1 - SellingPrice / OriginalPrice`), com 4 casas decimais.
        DateFrom:
          type: string
          format: date-time
          nullable: true
          description: >-
            Início da vigência do anúncio dentro da promoção (pode ser diferente do `DateFrom` da promoção em tipos que
            permitem janela por anúncio).
        DateTo:
          type: string
          format: date-time
          nullable: true
          description: Fim da vigência do anúncio dentro da promoção.
        SellerPercent:
          type: number
          nullable: true
          description: Percentual de desconto efetivo do anúncio.
        IntegrationPercent:
          type: number
          nullable: true
          description: Percentual de co-participação assumido pelo canal no anúncio.
        MaximumDiscountedPrice:
          type: number
          nullable: true
          description: Preço mínimo permitido pelo canal para o anúncio (somente leitura).
        MinimumDiscountedPrice:
          type: number
          nullable: true
          description: Preço máximo permitido pelo canal para o anúncio (somente leitura).
        SetQuantityAvailable:
          type: integer
          nullable: true
          description: Quantidade reservada para a promoção (oferta relâmpago).
        MaximumQuantityAvailable:
          type: integer
          nullable: true
          description: Quantidade máxima permitida pelo canal.
        MinimumQuantityAvailable:
          type: integer
          nullable: true
          description: Quantidade mínima exigida pelo canal.
        IDTypeHubProductPromotionStatus:
          type: integer
          description: Status do anúncio na promoção. Consulte `/type/hub/product/promotion/status` para a lista completa.
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 7
            - 8
        TypeHubProductPromotionStatus:
          type: string
          description: Descrição amigável do status.
        IntegrationStatus:
          type: integer
          description: '`0` Erro · `1` Sucesso · `2` Pendente.'
        IntegrationStatusName:
          type: string
          description: Descrição do estado da última sincronização do anúncio com o canal.
        IntegrationErrorDescription:
          type: string
          nullable: true
          description: Mensagem de erro retornada pelo canal na última tentativa de sincronização do anúncio.
    HubProductPromotionDetail:
      allOf:
        - $ref: '#/components/schemas/HubProductPromotionItem'
        - type: object
          properties:
            HasNextPageItems:
              type: integer
              description: '`1` quando existem mais anúncios além desta página de 5000 itens; `0` quando o último lote foi entregue.'
            HubProductPromotionItems:
              type: array
              items:
                $ref: '#/components/schemas/HubProductPromotionAdvertisement'
              description: Anúncios incluídos na promoção (paginados em blocos de 5000).
    HubProductPromotionCreate:
      type: object
      required:
        - IDCompanyIntegration
        - IDTypeHubProductPromotion
      description: >-
        Criação manual de promoção. **Só funciona** para tipos com `SellerCreate = 1` no catálogo (atualmente `Desconto
        individual` e `Campanha vendedor`). As demais promoções são recebidas do canal e não podem ser criadas pela API.
      properties:
        IDCompanyIntegration:
          type: integer
          format: int64
          description: Integração à qual a promoção será vinculada.
        IDTypeHubProductPromotion:
          type: integer
          description: Tipo de promoção. Aceita apenas tipos com `SellerCreate = 1`.
        PromotionName:
          type: string
          description: >-
            Nome da promoção. Para `Campanha vendedor` (tipo 8) é obrigatório e limitado a 25 caracteres. Acentuação é
            normalizada (removida).
        DateFrom:
          type: string
          format: date-time
          nullable: true
          description: >-
            Início da vigência. Obrigatório para `Campanha vendedor`. Diferença para `DateTo` não pode passar de 31
            dias.
        DateTo:
          type: string
          format: date-time
          nullable: true
          description: Fim da vigência. Obrigatório para `Campanha vendedor` e precisa ser maior que hoje.
        SellerPercent:
          type: number
          nullable: true
          description: Percentual de desconto. Para `Campanha vendedor` precisa ficar entre `0.10` e `0.70` (10% a 70%).
    HubProductPromotionUpdate:
      type: object
      description: >-
        Atualização da promoção. **Só permitida** para tipos com `SellerCreate = 1`. Para `Campanha vendedor` em status
        `Iniciado` a `DateFrom` não pode ser alterada.
      properties:
        PromotionName:
          type: string
          description: Novo nome da promoção. Para `Campanha vendedor` mantém o limite de 25 caracteres.
        DateFrom:
          type: string
          format: date-time
          nullable: true
          description: >-
            Novo início da vigência. Em `Campanha vendedor` em status `Iniciado` (`IDTypeHubProductPromotionStatus=2`),
            não pode ser alterado.
        DateTo:
          type: string
          format: date-time
          nullable: true
          description: Novo fim da vigência. Diferença para `DateFrom` não pode passar de 31 dias.
        SellerPercent:
          type: number
          nullable: true
          description: Novo percentual de desconto. Para `Campanha vendedor` precisa ficar entre `0.10` e `0.70` (10% a 70%).
    HubProductPromotionItemCreate:
      type: object
      required:
        - IDProductHub
      description: >-
        Inclusão de anúncio em promoção. Só funciona quando a promoção é `SellerCreate = 1`. Para `Desconto individual`
        (tipo 3) o sistema consulta o canal para validar que o desconto está entre 5% e 80% do preço anunciado.
      properties:
        IDProductHub:
          type: string
          description: 'Identificador do anúncio no canal (ex.: `MLB123456789`).'
        IDSkuHub:
          type: string
          nullable: true
          description: Identificador do SKU/variação quando aplicável. Quando não informado, usa o próprio `IDProductHub`.
        SellingPrice:
          type: number
          description: Preço promocional do anúncio.
        DateFrom:
          type: string
          format: date-time
          nullable: true
          description: Início. Obrigatório para `Desconto individual`.
        DateTo:
          type: string
          format: date-time
          nullable: true
          description: Fim. Obrigatório para `Desconto individual`. Intervalo máximo de 31 dias.
    HubProductPromotionItemUpdate:
      type: object
      description: >-
        Atualização de anúncio em promoção. Os campos aceitos e as validações dependem do tipo da promoção: preço,
        intervalo de datas, quantidade. Ajustes fora dos limites mínimos e máximos definidos pelo canal são rejeitados.
      properties:
        SellingPrice:
          type: number
          nullable: true
          description: Preço promocional. Respeita `MinimumDiscountedPrice`/`MaximumDiscountedPrice` quando informados pelo canal.
        SetQuantityAvailable:
          type: integer
          nullable: true
          description: >-
            Quantidade reservada (aplicável a `Oferta relâmpago`). Respeita
            `MinimumQuantityAvailable`/`MaximumQuantityAvailable`.
        DateFrom:
          type: string
          format: date-time
          nullable: true
          description: Novo início para o anúncio dentro da promoção. Obrigatório para `Desconto individual`.
        DateTo:
          type: string
          format: date-time
          nullable: true
          description: >-
            Novo fim para o anúncio dentro da promoção. Obrigatório para `Desconto individual`. Intervalo máximo de 31
            dias em relação a `DateFrom`.
    TypeHubProductPromotionStatusItem:
      type: object
      properties:
        IDTypeHubProductPromotionStatus:
          type: string
          description: Identificador do status.
        TypeHubProductPromotionStatus:
          type: string
          description: Descrição amigável.
    TypeHubProductPromotionItem:
      type: object
      properties:
        IDTypeHubProductPromotion:
          type: string
          description: Identificador do tipo.
        TypeHubProductPromotionDescription:
          type: string
          description: 'Descrição amigável (ex.: `Tradicional`, `Campanha vendedor`, `Oferta do dia`).'
    SkuCollectionItem:
      type: object
      description: Coleção de produtos (`StockKeepingUnitCollection` + `AccountName` da conta dona).
      properties:
        IDStockKeepingUnitCollection:
          type: integer
          description: Identificador da coleção.
        IDCompany:
          type: integer
          description: Identificador da empresa.
        StockKeepingUnitCollectionName:
          type: string
          maxLength: 100
          description: Nome da coleção.
        AccountName:
          type: string
          description: Conta (subdomínio) da empresa.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora de criação.
    SkuCollectionCreate:
      type: object
      description: Corpo do POST/PUT de Coleção.
      required:
        - StockKeepingUnitCollectionName
      properties:
        StockKeepingUnitCollectionName:
          type: string
          maxLength: 100
          description: Nome da coleção.
    SkuGroupItem:
      type: object
      description: Grupo de SKUs equivalentes (`StockKeepingUnitGroup` + `AccountName`).
      properties:
        IDStockKeepingUnitGroup:
          type: integer
          description: Identificador do grupo de SKUs.
        IDCompany:
          type: integer
          description: Identificador da empresa.
        SkuGroupName:
          type: string
          maxLength: 100
          description: Nome do grupo de SKUs.
        AccountName:
          type: string
          description: Conta (subdomínio) da empresa.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora de criação.
    SkuGroupCreate:
      type: object
      description: Corpo do POST/PUT de Grupo SKU.
      required:
        - SkuGroupName
      properties:
        SkuGroupName:
          type: string
          maxLength: 100
          description: Nome do grupo.
    SkuSimilarCodeItem:
      type: object
      description: >-
        Linha da lista de códigos similares (`skuSimilarCodeList`). Vem da `StockKeepingUnitSimilarCode` com
        `SkuGroupName` (do grupo) e `AccountName` (da empresa) já resolvidos.
      properties:
        IDStockKeepingUnitSimilarCode:
          type: integer
          description: Id do código similar.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data de cadastro do código.
        IDStockKeepingUnitGroup:
          type: integer
          description: Id do grupo SKU a que o código pertence.
        SkuSimilarCode:
          type: string
          maxLength: 45
          description: Código alternativo.
        SkuSimilarCodeTag:
          type: string
          maxLength: 45
          nullable: true
          description: 'Tag opcional para agrupar códigos por origem (ex.: nome do fornecedor, do canal).'
        SkuGroupName:
          type: string
          maxLength: 100
          description: Nome do grupo SKU.
        AccountName:
          type: string
          description: Identificador da conta da empresa proprietária do grupo.
    SkuSimilarCodeCreate:
      type: object
      description: Corpo do POST/PUT de Código Similar.
      required:
        - IDStockKeepingUnitGroup
        - SkuSimilarCode
      properties:
        IDStockKeepingUnitGroup:
          type: integer
          description: Id do grupo SKU. Precisa pertencer à empresa autenticada.
        SkuSimilarCode:
          type: string
          maxLength: 45
          description: Código alternativo. Único por grupo.
        SkuSimilarCodeTag:
          type: string
          maxLength: 45
          nullable: true
          description: Tag opcional para agrupar códigos por origem.
    SkuSimilarCodeTagItem:
      type: object
      description: Linha da lista de tags (`skuSimilarCodeTagList`). Apenas as tags em uso, distintas, ordenadas alfabeticamente.
      properties:
        SkuSimilarCodeTag:
          type: string
          maxLength: 45
          description: Valor da tag.
        AccountName:
          type: string
          description: Identificador da conta da empresa que usa a tag.
    TypeSkuVariationItem:
      type: object
      description: >-
        Linha da lista de variações (`typeSkuVariationList`). `IDTypeProductVariation` vem como texto (CAST). O campo
        `TypeProductVariation` é o array com os valores da grade da variação.
      properties:
        IDTypeProductVariation:
          type: string
          description: Identificador da variação (devolvido como texto pelo `CAST` no SQL).
        ProductVariation:
          type: string
          maxLength: 45
          description: 'Nome da variação (ex.: `Tamanho`, `Cor`).'
        ProductVariationOrder:
          type: integer
          description: Ordem de exibição (única por empresa).
        IDTypeProductVariationType:
          type: integer
          description: Id do tipo padrão (`TypeProductVariationType`).
        TypeProductVariationType:
          type: string
          description: Nome do tipo padrão (Cor, Tamanho, Voltagem…).
        AccountName:
          type: string
          description: Subdomínio (identificador) da empresa dona da variação.
        TypeProductVariationValueList:
          type: string
          nullable: true
          description: Lista de valores da grade concatenada por vírgula (`GROUP_CONCAT`); `null` quando a variação não tem grade.
        TypeProductVariation:
          type: array
          description: Valores da grade da variação.
          items:
            type: object
            properties:
              IDTypeProductVariationValue:
                type: string
                description: Identificador do valor da grade (devolvido como texto pelo `CAST` no SQL).
              TypeProductVariationValue:
                type: string
                maxLength: 100
                description: 'Nome do valor da grade (ex.: `P`, `M`, `Azul`).'
              ProductVariationValueOrder:
                type: integer
                description: Ordem de exibição do valor dentro da grade (única por variação).
    TypeSkuVariationDetail:
      type: object
      description: >-
        Detalhe de uma variação com sua grade (`typeSkuVariationGet`). Devolvido também por POST/PUT/DELETE de valores
        da grade.
      properties:
        IDTypeProductVariation:
          type: string
          description: Identificador da variação (devolvido como texto pelo `CAST` no SQL).
        ProductVariation:
          type: string
          maxLength: 45
          description: Nome da variação.
        IDTypeProductVariationType:
          type: integer
          description: Identificador do tipo padrão (Cor, Tamanho, Voltagem…).
        TypeProductVariationType:
          type: string
          description: Nome do tipo padrão.
        TypeProductVariationValues:
          type: array
          description: Valores da grade da variação.
          items:
            type: object
            properties:
              IDTypeProductVariationValue:
                type: integer
                description: Identificador do valor da grade.
              TypeProductVariationValue:
                type: string
                maxLength: 100
                description: Nome do valor da grade.
              ProductVariationValueOrder:
                type: integer
                description: Ordem de exibição do valor dentro da grade (única por variação).
    TypeSkuVariationCreate:
      type: object
      description: >-
        Corpo do POST/PUT de variação. No PUT todos os campos são opcionais (atualização parcial).
        `ProductVariationOrder` é único por empresa; se omitido no POST, recebe `MAX+1`.
      required:
        - ProductVariation
        - IDTypeProductVariationType
      properties:
        ProductVariation:
          type: string
          maxLength: 45
          description: Nome da variação.
        IDTypeProductVariationType:
          type: integer
          description: Id do tipo padrão (de `GET /type/sku/variation/type`).
        ProductVariationOrder:
          type: integer
          description: Ordem de exibição (única por empresa).
    TypeProductVariationTypeItem:
      type: object
      description: Tipo padrão de variação do sistema (`TypeProductVariationType`). Lista fixa, igual para todas as empresas.
      properties:
        IDTypeProductVariationType:
          type: string
          description: >-
            Identificador do tipo padrão (Cor, Tamanho, Voltagem…). Tabela fixa do sistema — igual para todas as
            empresas.
        TypeProductVariationType:
          type: string
          maxLength: 45
          description: Nome do tipo padrão.
    GradeValueItem:
      type: object
      description: Valor da grade de uma variação (`skuVariationValueList`).
      properties:
        IDTypeProductVariationValue:
          type: integer
          description: Identificador do valor da grade.
        TypeProductVariationValue:
          type: string
          maxLength: 100
          description: 'Nome do valor (ex.: `P`, `Azul`, `220V`).'
        ProductVariationValueOrder:
          type: integer
          description: Ordem de exibição do valor dentro da grade (única por variação).
    GradeValueCreate:
      type: object
      description: Corpo do POST/PUT de valor da grade. `ProductVariationValueOrder` é único por variação.
      required:
        - TypeProductVariationValue
      properties:
        TypeProductVariationValue:
          type: string
          maxLength: 100
          description: 'Nome do valor da grade (ex.: Azul, M).'
        ProductVariationValueOrder:
          type: integer
          description: Ordem do valor dentro da grade (única por variação).
    CategoryTreeNode:
      type: object
      description: Nó da árvore de categorias (resposta de `categoryList` com `Type=Tree`).
      properties:
        IDCategory:
          type: integer
          description: Id da categoria.
        Name:
          type: string
          description: Nome da categoria.
        IDCategoryFather:
          type: integer
          description: Id da categoria pai; `0` quando a categoria é de topo.
        IsActive:
          type: integer
          description: Indica se a categoria está ativa (`1`) ou inativa (`0`).
        AccountName:
          type: string
          description: Conta dona da categoria.
        Children:
          type: array
          description: Subcategorias deste nó (mesma estrutura, recursiva).
          items:
            type: object
            description: (referência recursiva a `CategoryTreeNode` — não expandida)
    CategoryDetail:
      type: object
      description: Dados completos de uma categoria (resposta de `categoryGet`).
      properties:
        IDCategory:
          type: integer
          description: Id da categoria.
        Name:
          type: string
          description: Nome da categoria.
        Description:
          type: string
          nullable: true
          description: Descrição da categoria.
        Title:
          type: string
          nullable: true
          description: Título usado na loja virtual.
        Keywords:
          type: string
          nullable: true
          description: Palavras-chave usadas na loja virtual.
        IDCategoryFather:
          type: integer
          nullable: true
          description: Id da categoria pai; `null` quando é de topo.
        CategoryFather:
          type: string
          nullable: true
          description: Nome da categoria pai; `null` quando é de topo.
        IsActive:
          type: integer
          description: Indica se a categoria está ativa (`1`) ou inativa (`0`).
        ShowInStoreFront:
          type: integer
          nullable: true
          description: Exibir a categoria na loja virtual (`1`/`0`).
        ShowBrandFilter:
          type: integer
          nullable: true
          description: Exibir o filtro de marca na categoria (`1`/`0`).
        ActiveStoreFrontLink:
          type: integer
          nullable: true
          description: Ativar o link da categoria na loja virtual (`1`/`0`).
        Score:
          type: integer
          nullable: true
          description: Peso/ordenação da categoria.
        AccountName:
          type: string
          description: Conta dona da categoria.
    CategoryCreate:
      type: object
      required:
        - Name
      description: Corpo para criação de categoria.
      properties:
        Name:
          type: string
          description: Nome da categoria.
        Description:
          type: string
          nullable: true
          description: Descrição; assume `Name` quando omitida.
        Title:
          type: string
          nullable: true
          description: Título na loja virtual; assume `Name` quando omitido.
        Keywords:
          type: string
          nullable: true
          description: Palavras-chave na loja virtual; assume `Name` quando omitidas.
        IDCategoryFather:
          type: integer
          nullable: true
          description: Id da categoria pai; `null`/ausente cria categoria de topo.
        ShowInStoreFront:
          type: integer
          description: Exibir na loja virtual (`1`/`0`); padrão `1`.
        ShowBrandFilter:
          type: integer
          description: Exibir filtro de marca (`1`/`0`); padrão `1`.
        ActiveStoreFrontLink:
          type: integer
          description: Ativar link na loja virtual (`1`/`0`); padrão `1`.
        Score:
          type: integer
          nullable: true
          description: Peso/ordenação da categoria.
        IsActive:
          type: integer
          description: Categoria ativa (`1`) ou inativa (`0`).
    CategoryUpdate:
      type: object
      description: Corpo para atualização parcial de categoria. Envie apenas os campos a alterar.
      properties:
        Name:
          type: string
          description: Nome da categoria.
        Description:
          type: string
          description: Descrição da categoria.
        Title:
          type: string
          description: Título na loja virtual.
        Keywords:
          type: string
          description: Palavras-chave na loja virtual.
        IDCategoryFather:
          type: integer
          nullable: true
          description: Id da categoria pai; `null` move a categoria para o topo.
        ShowInStoreFront:
          type: integer
          description: Exibir na loja virtual (`1`/`0`).
        ShowBrandFilter:
          type: integer
          description: Exibir filtro de marca (`1`/`0`).
        ActiveStoreFrontLink:
          type: integer
          description: Ativar link na loja virtual (`1`/`0`).
        Score:
          type: integer
          description: Peso/ordenação da categoria.
        IsActive:
          type: integer
          description: Categoria ativa (`1`) ou inativa (`0`).
    SpecFieldItem:
      type: object
      description: Especificação (campo) de uma categoria, com seus valores (resposta de `skuSpecificationFieldList`).
      properties:
        IDStockKeepingUnitSpecificationsFieldId:
          type: integer
          description: Id da especificação.
        FieldName:
          type: string
          description: Nome do campo.
        FieldType:
          type: string
          description: Nome do tipo de preenchimento (texto, número, lista…).
        IDStockKeepingUnitSpecificationsFieldTypes:
          type: integer
          description: Id do tipo de preenchimento.
        IDCategory:
          type: integer
          description: Id da categoria dona da especificação (pode ser uma ancestral, quando herdada).
        CategoryName:
          type: string
          description: Nome da categoria dona da especificação.
        IDFieldExternal:
          type: string
          nullable: true
          description: Código externo do campo.
        IsRequired:
          type: integer
          nullable: true
          description: Preenchimento obrigatório no produto (`1`/`0`).
        IsActive:
          type: integer
          nullable: true
          description: Campo ativo (`1`/`0`).
        IsFilter:
          type: integer
          nullable: true
          description: Usar como filtro na loja (`1`/`0`).
        IsOnProductDetails:
          type: integer
          nullable: true
          description: Exibir nos detalhes do produto (`1`/`0`).
        IsTopMenuLinkActive:
          type: integer
          nullable: true
          description: Ativar link no menu superior (`1`/`0`).
        IsSideMenuLinkActive:
          type: integer
          nullable: true
          description: Ativar link no menu lateral (`1`/`0`).
        FieldPosition:
          type: integer
          nullable: true
          description: Ordem de exibição do campo.
        FieldValue:
          type: array
          description: Valores cadastrados para o campo (vazio para campos sem lista de opções).
          items:
            type: object
            properties:
              Value:
                type: string
                description: Texto do valor.
              IDStockKeepingUnitSpecificationsFieldValues:
                type: integer
                description: Id do valor.
              IDFieldValueExternal:
                type: string
                nullable: true
                description: Código externo do valor.
              IDField:
                type: integer
                description: Id da especificação dona do valor.
              Position:
                type: integer
                nullable: true
                description: Ordem de exibição do valor.
    SpecFieldDetail:
      type: object
      description: Especificação (campo) detalhada com seus valores (resposta de `skuSpecificationFieldIdGet`).
      properties:
        IDStockKeepingUnitSpecificationsFieldId:
          type: integer
          description: Id da especificação.
        FieldName:
          type: string
          description: Nome do campo.
        FieldType:
          type: string
          nullable: true
          description: Nome do tipo de preenchimento.
        IDStockKeepingUnitSpecificationsFieldTypes:
          type: integer
          description: Id do tipo de preenchimento.
        IDCategory:
          type: integer
          description: Id da categoria dona da especificação.
        IDFieldExternal:
          type: string
          nullable: true
          description: Código externo do campo.
        IsActive:
          type: integer
          nullable: true
          description: Campo ativo (`1`/`0`).
        IsFilter:
          type: integer
          nullable: true
          description: Usar como filtro na loja (`1`/`0`).
        IsOnProductDetails:
          type: integer
          nullable: true
          description: Exibir nos detalhes do produto (`1`/`0`).
        IsRequired:
          type: integer
          nullable: true
          description: Preenchimento obrigatório no produto (`1`/`0`).
        IsTopMenuLinkActive:
          type: integer
          nullable: true
          description: Ativar link no menu superior (`1`/`0`).
        IsSideMenuLinkActive:
          type: integer
          nullable: true
          description: Ativar link no menu lateral (`1`/`0`).
        FieldValue:
          type: array
          description: Valores cadastrados para o campo.
          items:
            type: object
            properties:
              Value:
                type: string
                description: Texto do valor.
              IDStockKeepingUnitSpecificationsFieldValues:
                type: integer
                description: Id do valor.
              IDFieldValueExternal:
                type: string
                nullable: true
                description: Código externo do valor.
    SpecFieldCreate:
      type: object
      required:
        - FieldName
        - IDStockKeepingUnitSpecificationsFieldTypes
      description: Corpo para criação de uma especificação na categoria.
      properties:
        FieldName:
          type: string
          description: Nome do campo.
        IDStockKeepingUnitSpecificationsFieldTypes:
          type: integer
          description: Id do tipo de preenchimento (ver `GET /type/sku/specification/field-type`).
        IDFieldExternal:
          type: string
          nullable: true
          description: Código externo do campo; deve ser único na categoria.
        IsFilter:
          type: integer
          nullable: true
          description: Usar como filtro na loja (`1`/`0`).
        IsOnProductDetails:
          type: integer
          nullable: true
          description: Exibir nos detalhes do produto (`1`/`0`).
        IsTopMenuLinkActive:
          type: integer
          nullable: true
          description: Ativar link no menu superior (`1`/`0`).
        IsSideMenuLinkActive:
          type: integer
          nullable: true
          description: Ativar link no menu lateral (`1`/`0`).
        IsActive:
          type: integer
          nullable: true
          description: Campo ativo (`1`/`0`).
        IsRequired:
          type: integer
          nullable: true
          description: Preenchimento obrigatório no produto (`1`/`0`).
        FieldPosition:
          type: integer
          nullable: true
          description: Ordem de exibição do campo.
    SpecFieldUpdate:
      type: object
      description: Corpo para atualização parcial de uma especificação. Envie apenas os campos a alterar.
      properties:
        FieldName:
          type: string
          description: Nome do campo.
        IDStockKeepingUnitSpecificationsFieldTypes:
          type: integer
          description: Id do tipo de preenchimento.
        IDFieldExternal:
          type: string
          nullable: true
          description: Código externo do campo; deve ser único na categoria.
        IsFilter:
          type: integer
          description: Usar como filtro na loja (`1`/`0`).
        IsOnProductDetails:
          type: integer
          description: Exibir nos detalhes do produto (`1`/`0`).
        IsTopMenuLinkActive:
          type: integer
          description: Ativar link no menu superior (`1`/`0`).
        IsSideMenuLinkActive:
          type: integer
          description: Ativar link no menu lateral (`1`/`0`).
        IsActive:
          type: integer
          description: Campo ativo (`1`/`0`).
        IsRequired:
          type: integer
          description: Preenchimento obrigatório no produto (`1`/`0`).
        FieldPosition:
          type: integer
          description: Ordem de exibição do campo.
    SpecValueCreate:
      type: object
      required:
        - Value
      description: Corpo para adicionar um valor a uma especificação do tipo lista.
      properties:
        Value:
          type: string
          description: Texto do valor.
        IDFieldValueExternal:
          type: string
          nullable: true
          description: Código externo do valor.
        Position:
          type: integer
          nullable: true
          description: Ordem de exibição do valor.
    SpecValueUpdate:
      type: object
      required:
        - Value
      description: Corpo para atualização de um valor de especificação.
      properties:
        Value:
          type: string
          description: Texto do valor.
        IDFieldValueExternal:
          type: string
          nullable: true
          description: Código externo do valor.
        Position:
          type: integer
          nullable: true
          description: Ordem de exibição do valor.
    SpecFieldTypeItem:
      type: object
      description: Tipo de preenchimento de uma especificação (lista padrão do sistema).
      properties:
        IDStockKeepingUnitSpecificationsFieldTypes:
          type: string
          description: Id do tipo de preenchimento.
        FieldType:
          type: string
          description: 'Nome do tipo (ex.: texto, número, lista).'
    HubProductSpecificationInput:
      type: object
      description: Item da ficha técnica (especificação) do anúncio.
      properties:
        IDStockKeepingUnitSpecificationsFieldId:
          type: string
          description: Identificador do campo da ficha técnica da categoria.
        FieldName:
          type: string
          description: Nome do campo da ficha técnica.
        FieldValue:
          type: string
          description: Valor do campo (texto, opção ou número). Use `NA` quando não se aplica.
        IDSpecificationValue:
          type: string
          nullable: true
          description: Identificador do valor selecionado, quando aplicável.
        SpecificationCustomValue:
          type: string
          nullable: true
          description: Valor livre, quando o campo permite texto.
    HubSkuInput:
      type: object
      description: Variação a criar junto do anúncio (fluxo de duplicação).
      required:
        - IDSku
      properties:
        IDSku:
          type: integer
          format: int64
          description: SKU vinculado à variação.
        IDCommercialCondition:
          type: integer
          format: int64
          nullable: true
          description: Condição comercial da variação.
        EcommerceModal:
          type: string
          nullable: true
          description: Modalidade de e-commerce da variação.
    HubProductSalesPolicyInput:
      type: object
      description: 'Política comercial associada ao anúncio (ex.: Vtex).'
      required:
        - IDTypeSkuSalesPolicy
      properties:
        IDTypeSkuSalesPolicy:
          type: integer
          format: int64
          description: Política comercial / condição de venda.
    HubProductImageInput:
      type: object
      description: Imagem do anúncio.
      required:
        - IDImage
        - ImageOrder
      properties:
        IDImage:
          type: integer
          format: int64
          description: Identificador da imagem.
        ImageOrder:
          type: integer
          description: Ordem de exibição da imagem.
    HubProductAutopartsInput:
      type: object
      description: Veículo compatível copiado no fluxo de duplicação (autopeças).
      properties:
        ProductId:
          type: string
          description: Identificador do veículo no catálogo do canal.
        Notes:
          type: string
          nullable: true
          description: Observações da compatibilidade.
        PositionArray:
          type: string
          nullable: true
          description: Posições de aplicação no formato `Valor|IDValor` separadas por `----`.
    HubProductCreate:
      type: object
      description: Corpo de criação do anúncio.
      required:
        - IDCompanyIntegration
        - IDProduct
      properties:
        IDCompanyIntegration:
          type: integer
          format: int64
          description: Integração (conta de canal) do anúncio.
        IDProduct:
          type: integer
          format: int64
          description: SKU/produto vinculado ao anúncio.
        IDProductHub:
          type: string
          nullable: true
          description: Código do anúncio no canal (preenchido ao vincular um anúncio já existente).
        HubProductName:
          type: string
          nullable: true
          description: Título do anúncio no canal.
        HubEcommerceDescription:
          type: string
          nullable: true
          description: Descrição do anúncio (até 5.000 caracteres).
        CategoryId:
          type: string
          nullable: true
          description: Categoria do canal.
        CategoryPath:
          type: string
          nullable: true
          description: Caminho/legenda da categoria.
        AdvertisementStatus:
          type: integer
          nullable: true
          description: 'Status do anúncio: `0` Inativo, `1` Ativo, `2` Fechado, `3` Pausado, `4` Em revisão, `5` Inabilitado canal.'
        ListingTypeId:
          type: string
          enum:
            - bronze
            - free
            - gold
            - gold_premium
            - gold_pro
            - gold_special
            - silver
          nullable: true
          description: Tipo de anúncio (Mercado Livre).
        Condition:
          type: string
          nullable: true
          description: 'Condição do item (ex.: `new`, `used`, `refurbished`) — canais que suportam condição.'
        ShippingMode:
          type: string
          enum:
            - custom
            - me1
            - me2
            - not_specified
          nullable: true
          description: Forma de entrega (Mercado Livre).
        ShippingFree:
          type: boolean
          nullable: true
          description: Frete grátis (Mercado Livre, Kabum).
        ShippingLocalPickUp:
          type: boolean
          nullable: true
          description: Permite retirada no local (Mercado Livre).
        LeadTimeDays:
          type: integer
          nullable: true
          description: Prazo de disponibilização (dias).
        WarrantyType:
          type: string
          nullable: true
          description: 'Tipo de garantia (ex.: garantia do vendedor / de fábrica / sem garantia).'
        WarrantyTime:
          type: integer
          nullable: true
          description: Prazo de garantia.
        WarrantyTimeType:
          type: string
          nullable: true
          description: 'Unidade do prazo de garantia (ex.: `days`, `months`, `years`).'
        OfficialStore:
          type: string
          nullable: true
          description: Loja Oficial (Mercado Livre).
        ShowWithoutStock:
          type: boolean
          nullable: true
          description: Mantém o anúncio visível sem estoque.
        Visible:
          type: boolean
          nullable: true
          description: Anúncio visível.
        Comments:
          type: string
          nullable: true
          description: Observações internas.
        IDHubProductQuestionAnswerTemplate:
          type: integer
          format: int64
          nullable: true
          description: Modelo de perguntas e respostas (Mercado Livre).
        PriceListSet:
          type: number
          nullable: true
          description: Preço de (preço cheio) a nível de anúncio.
        PriceSellSet:
          type: number
          nullable: true
          description: Preço por (preço de venda) a nível de anúncio.
        NetPricingSet:
          type: number
          nullable: true
          description: Preço líquido, quando o canal suporta (Mercado Livre).
        HubProductSpecification:
          type: array
          items:
            $ref: '#/components/schemas/HubProductSpecificationInput'
          description: Ficha técnica (especificações) do anúncio.
        HubProductSalesPolicy:
          type: array
          items:
            $ref: '#/components/schemas/HubProductSalesPolicyInput'
          description: 'Políticas comerciais (ex.: Vtex).'
        PricingSet:
          type: number
          nullable: true
          description: Preço manual aplicado às variações criadas automaticamente.
        HubSku:
          type: array
          items:
            $ref: '#/components/schemas/HubSkuInput'
          description: Variações a criar (usado no fluxo de duplicação).
        Autoparts:
          type: array
          items:
            $ref: '#/components/schemas/HubProductAutopartsInput'
          description: Veículos compatíveis (usado no fluxo de duplicação — autopeças).
    HubProductUpdate:
      type: object
      description: Corpo de atualização parcial do anúncio (envie apenas os campos a alterar).
      properties:
        IDCompanyIntegration:
          type: integer
          format: int64
          description: Integração (conta de canal) do anúncio.
        IDProduct:
          type: integer
          format: int64
          description: SKU/produto vinculado ao anúncio.
        IDProductHub:
          type: string
          nullable: true
          description: Código do anúncio no canal (preenchido ao vincular um anúncio já existente).
        HubProductName:
          type: string
          nullable: true
          description: Título do anúncio no canal.
        HubEcommerceDescription:
          type: string
          nullable: true
          description: Descrição do anúncio (até 5.000 caracteres).
        CategoryId:
          type: string
          nullable: true
          description: Categoria do canal.
        CategoryPath:
          type: string
          nullable: true
          description: Caminho/legenda da categoria.
        AdvertisementStatus:
          type: integer
          nullable: true
          description: 'Status do anúncio: `0` Inativo, `1` Ativo, `2` Fechado, `3` Pausado, `4` Em revisão, `5` Inabilitado canal.'
        ListingTypeId:
          type: string
          enum:
            - bronze
            - free
            - gold
            - gold_premium
            - gold_pro
            - gold_special
            - silver
          nullable: true
          description: Tipo de anúncio (Mercado Livre).
        Condition:
          type: string
          nullable: true
          description: 'Condição do item (ex.: `new`, `used`, `refurbished`) — canais que suportam condição.'
        ShippingMode:
          type: string
          enum:
            - custom
            - me1
            - me2
            - not_specified
          nullable: true
          description: Forma de entrega (Mercado Livre).
        ShippingFree:
          type: boolean
          nullable: true
          description: Frete grátis (Mercado Livre, Kabum).
        ShippingLocalPickUp:
          type: boolean
          nullable: true
          description: Permite retirada no local (Mercado Livre).
        LeadTimeDays:
          type: integer
          nullable: true
          description: Prazo de disponibilização (dias).
        WarrantyType:
          type: string
          nullable: true
          description: 'Tipo de garantia (ex.: garantia do vendedor / de fábrica / sem garantia).'
        WarrantyTime:
          type: integer
          nullable: true
          description: Prazo de garantia.
        WarrantyTimeType:
          type: string
          nullable: true
          description: 'Unidade do prazo de garantia (ex.: `days`, `months`, `years`).'
        OfficialStore:
          type: string
          nullable: true
          description: Loja Oficial (Mercado Livre).
        ShowWithoutStock:
          type: boolean
          nullable: true
          description: Mantém o anúncio visível sem estoque.
        Visible:
          type: boolean
          nullable: true
          description: Anúncio visível.
        Comments:
          type: string
          nullable: true
          description: Observações internas.
        IDHubProductQuestionAnswerTemplate:
          type: integer
          format: int64
          nullable: true
          description: Modelo de perguntas e respostas (Mercado Livre).
        PriceListSet:
          type: number
          nullable: true
          description: Preço de (preço cheio) a nível de anúncio.
        PriceSellSet:
          type: number
          nullable: true
          description: Preço por (preço de venda) a nível de anúncio.
        NetPricingSet:
          type: number
          nullable: true
          description: Preço líquido, quando o canal suporta (Mercado Livre).
        HubProductSpecification:
          type: array
          items:
            $ref: '#/components/schemas/HubProductSpecificationInput'
          description: Ficha técnica (especificações) do anúncio.
        HubProductSalesPolicy:
          type: array
          items:
            $ref: '#/components/schemas/HubProductSalesPolicyInput'
          description: 'Políticas comerciais (ex.: Vtex).'
        CatalogProductId:
          type: string
          nullable: true
          description: Produto de catálogo (Mercado Livre); vazio desvincula do catálogo.
        AutopartsException:
          type: boolean
          nullable: true
          description: Marca o anúncio como exceção de compatibilidade (autopeças).
        AutopartsUniversalCompatibility:
          type: boolean
          nullable: true
          description: Compatibilidade universal (autopeças, categorias elegíveis do Mercado Livre).
        HubProductImage:
          type: array
          items:
            $ref: '#/components/schemas/HubProductImageInput'
          description: Imagens do anúncio (substitui o conjunto atual; array vazio remove todas).
    HubSkuSpecificationInput:
      type: object
      description: Item de ficha técnica da variação.
      properties:
        IDStockKeepingUnitSpecificationsFieldId:
          type: string
          description: Identificador do campo da ficha técnica.
        FieldName:
          type: string
          description: Nome do campo.
        FieldValue:
          type: string
          description: Valor do campo (use `NA` quando não se aplica).
    HubSkuImageInput:
      type: object
      description: Imagem da variação.
      required:
        - IDImage
        - ImageOrder
      properties:
        IDImage:
          type: integer
          format: int64
          description: Identificador da imagem.
        ImageOrder:
          type: integer
          description: Ordem de exibição.
    HubProductOfferCreate:
      type: object
      description: Corpo de criação de variação do anúncio.
      required:
        - IDSku
      properties:
        IDSku:
          type: integer
          format: int64
          description: SKU vinculado à variação.
        IDSkuHub:
          type: string
          nullable: true
          description: Código da variação no canal.
        PricingSet:
          type: number
          nullable: true
          description: Preço manual da variação (não coexiste com o preço a nível de anúncio).
        HubSkuOrder:
          type: integer
          nullable: true
          description: Ordem da variação na página do canal.
        Comments:
          type: string
          nullable: true
          description: Observações internas.
        HubSkuListingTypeId:
          type: string
          enum:
            - bronze
            - free
            - gold
            - gold_premium
            - gold_pro
            - gold_special
            - silver
          nullable: true
          description: Tipo de anúncio da variação (Mercado Livre).
        HubSkuShippingFree:
          type: boolean
          nullable: true
          description: Frete grátis da variação (Mercado Livre).
        EcommerceModal:
          type: string
          nullable: true
          description: Modalidade de e-commerce.
        IDCommercialCondition:
          type: integer
          format: int64
          nullable: true
          description: Condição comercial.
        HubSkuSpecification:
          type: array
          items:
            $ref: '#/components/schemas/HubSkuSpecificationInput'
          description: Ficha técnica da variação.
    HubProductOfferUpdate:
      type: object
      description: Corpo de atualização parcial da variação (envie apenas os campos a alterar).
      properties:
        IDSku:
          type: integer
          format: int64
          nullable: true
          description: SKU vinculado à variação (quando alterado).
        IDSkuHub:
          type: string
          nullable: true
          description: Código da variação no canal.
        PricingSet:
          type: number
          nullable: true
          description: Preço manual da variação (não coexiste com o preço a nível de anúncio).
        HubSkuOrder:
          type: integer
          nullable: true
          description: Ordem da variação na página do canal.
        Comments:
          type: string
          nullable: true
          description: Observações internas.
        HubSkuListingTypeId:
          type: string
          enum:
            - bronze
            - free
            - gold
            - gold_premium
            - gold_pro
            - gold_special
            - silver
          nullable: true
          description: Tipo de anúncio da variação (Mercado Livre).
        HubSkuShippingFree:
          type: boolean
          nullable: true
          description: Frete grátis da variação (Mercado Livre).
        EcommerceModal:
          type: string
          nullable: true
          description: Modalidade de e-commerce.
        IDCommercialCondition:
          type: integer
          format: int64
          nullable: true
          description: Condição comercial.
        HubSkuSpecification:
          type: array
          items:
            $ref: '#/components/schemas/HubSkuSpecificationInput'
          description: Ficha técnica da variação.
        HubSkuImage:
          type: array
          items:
            $ref: '#/components/schemas/HubSkuImageInput'
          description: Imagens da variação (substitui o conjunto atual; array vazio remove todas).
    HubProductAutopartsPositionInput:
      type: object
      description: Posição de aplicação do veículo compatível.
      properties:
        SpecificationValue:
          type: array
          description: Valores de posição de aplicação.
          items:
            type: string
        IDSpecificationValue:
          type: array
          description: Identificadores dos valores de posição.
          items:
            type: string
    HubProductAutopartsCreate:
      type: object
      description: Corpo para adicionar um veículo compatível (autopeças).
      properties:
        ProductId:
          type: string
          description: Identificador do veículo no catálogo do canal.
        Notes:
          type: string
          nullable: true
          description: Observações da compatibilidade.
        Brand:
          type: string
          nullable: true
          description: Marca do veículo (usado só ao cadastrar veículo novo).
        Model:
          type: string
          nullable: true
          description: Modelo.
        Year:
          type: string
          nullable: true
          description: Ano.
        ShortVersion:
          type: string
          nullable: true
          description: Versão.
        Engine:
          type: string
          nullable: true
          description: Motor.
        Fuel:
          type: string
          nullable: true
          description: Combustível.
        Power:
          type: string
          nullable: true
          description: Potência.
        BodyType:
          type: string
          nullable: true
          description: Carroceria.
        Transmission:
          type: string
          nullable: true
          description: Transmissão.
        Gear:
          type: string
          nullable: true
          description: Câmbio.
        Doors:
          type: string
          nullable: true
          description: Portas.
        Steering:
          type: string
          nullable: true
          description: Direção.
        Traction:
          type: string
          nullable: true
          description: Tração.
        Valves:
          type: string
          nullable: true
          description: Válvulas.
        Trim:
          type: string
          nullable: true
          description: Acabamento.
    HubProductAutopartsUpdate:
      type: object
      description: Corpo de atualização de um veículo compatível (autopeças).
      properties:
        Notes:
          type: string
          nullable: true
          description: Observações da compatibilidade.
        HubProductAutopartsPosition:
          type: array
          items:
            $ref: '#/components/schemas/HubProductAutopartsPositionInput'
          description: Posições de aplicação (substitui o conjunto atual; array vazio remove todas).
    HubProductQuantityPricingPayload:
      type: object
      description: Faixa de preço por quantidade (Mercado Livre).
      required:
        - Quantity
        - Price
      properties:
        Quantity:
          type: integer
          description: Quantidade mínima da faixa (maior que zero).
        Price:
          type: number
          description: Preço por unidade na faixa.
    HubSkuListSummary:
      type: object
      description: Resumo de variação na listagem de anúncios.
      properties:
        IDHubAdvertisement:
          type: integer
          format: int64
          description: Identificador da variação.
        IDSku:
          type: integer
          format: int64
          description: SKU vinculado.
        IDSkuHub:
          type: string
          nullable: true
          description: Código da variação no canal.
        PricingCheck:
          type: number
          nullable: true
          description: Preço calculado para conferência.
        PricingSet:
          type: number
          nullable: true
          description: Preço manual da variação.
        OriginalPrice:
          type: number
          nullable: true
          description: Preço de tabela do SKU.
        SkuName:
          type: string
          nullable: true
          description: Nome do produto.
        IDSkuCompany:
          type: string
          nullable: true
          description: Código de referência da variação.
        BarCode:
          type: string
          nullable: true
          description: Código de barras.
        ProductVariation:
          type: string
          nullable: true
          description: 'Atributos de variação (ex.: Cor, Tamanho).'
        TypeProductVariationValue:
          type: string
          nullable: true
          description: Valores dos atributos de variação.
        HubSkuOrder:
          type: integer
          nullable: true
          description: Ordem da variação.
        PurchaseExperienceValue:
          type: number
          nullable: true
          description: Indicador de experiência de compra.
        Comments:
          type: string
          nullable: true
          description: Observações.
        MainImageURL:
          type: string
          nullable: true
          description: Imagem principal da variação.
        AccountName:
          type: string
          nullable: true
          description: Conta.
    HubProductListItem:
      type: object
      description: Item da listagem de anúncios.
      properties:
        IDHubProduct:
          type: integer
          format: int64
          description: Identificador interno do anúncio.
        IDCompanyIntegration:
          type: integer
          format: int64
          description: Integração (conta de canal).
        AccountName:
          type: string
          nullable: true
          description: Conta.
        IDProduct:
          type: integer
          format: int64
          nullable: true
          description: SKU/produto vinculado.
        IDProductHub:
          type: string
          nullable: true
          description: Código do anúncio no canal.
        HubProductName:
          type: string
          nullable: true
          description: Título do anúncio.
        SkuName:
          type: string
          nullable: true
          description: Nome do produto.
        IDSkuCompany:
          type: string
          nullable: true
          description: Código de referência do produto.
        Brand:
          type: string
          nullable: true
          description: Marca.
        IDBrand:
          type: integer
          format: int64
          nullable: true
          description: Identificador da marca.
        IDTypeSku:
          type: integer
          format: int64
          nullable: true
          description: Tipo do produto.
        TypeProduct:
          type: string
          nullable: true
          description: Descrição do tipo do produto.
        SalesChannelName:
          type: string
          nullable: true
          description: Nome do canal de vendas.
        IntegrationName:
          type: string
          nullable: true
          description: Nome do canal/integração.
        CompanyIntegrationName:
          type: string
          nullable: true
          description: Nome da conta de integração.
        IDTypeCompanyIntegration:
          type: integer
          format: int64
          nullable: true
          description: Tipo de canal.
        LogoUrl:
          type: string
          nullable: true
          description: Logotipo do canal.
        CategoryId:
          type: string
          nullable: true
          description: Categoria do canal.
        AdvertisementStatus:
          type: integer
          nullable: true
          description: 'Status do anúncio: `0` Inativo, `1` Ativo, `2` Fechado, `3` Pausado, `4` Em revisão, `5` Inabilitado canal.'
        StatusHubSku:
          type: string
          nullable: true
          description: Status do anúncio (texto).
        HubProductSubStatus:
          type: integer
          nullable: true
          description: Sub-status (código).
        SubStatus:
          type: string
          nullable: true
          description: Sub-status (texto).
        AdvertisementUrl:
          type: string
          nullable: true
          description: Endereço do anúncio no canal.
        ListingTypeId:
          type: string
          enum:
            - bronze
            - free
            - gold
            - gold_premium
            - gold_pro
            - gold_special
            - silver
          nullable: true
          description: Tipo de anúncio (Mercado Livre).
        ListingTypeDescription:
          type: string
          nullable: true
          description: Descrição do tipo de anúncio.
        Health:
          type: number
          nullable: true
          description: Qualidade do anúncio (%).
        PriceListSet:
          type: number
          nullable: true
          description: Preço de (preço cheio).
        PriceSellSet:
          type: number
          nullable: true
          description: Preço por (preço de venda).
        ShippingFree:
          type: boolean
          nullable: true
          description: Frete grátis.
        ShippingMode:
          type: string
          enum:
            - custom
            - me1
            - me2
            - not_specified
          nullable: true
          description: Forma de entrega (Mercado Livre).
        ShippingLocalPickUp:
          type: boolean
          nullable: true
          description: Retirada no local.
        ShippingLogisticType:
          type: string
          nullable: true
          description: 'Tipo de logística do canal (ex.: `fulfillment`).'
        ShippingLogisticValue:
          type: string
          nullable: true
          description: '`Full` quando logística é fulfillment do Mercado Livre.'
        ShippingTags:
          type: string
          nullable: true
          description: Etiquetas de envio do canal.
        ShippingTagsValue:
          type: string
          nullable: true
          description: '`Flex` quando entrega no mesmo dia (Mercado Livre).'
        OfficialStore:
          type: string
          nullable: true
          description: Loja Oficial (Mercado Livre).
        WarrantyTime:
          type: integer
          nullable: true
          description: Prazo de garantia.
        WarrantyTimeType:
          type: string
          nullable: true
          description: Unidade do prazo de garantia.
        ShowWithoutStock:
          type: boolean
          nullable: true
          description: Mantém visível sem estoque.
        LeadTimeDays:
          type: integer
          nullable: true
          description: Prazo de disponibilização (dias).
        Catalog:
          type: string
          nullable: true
          description: '`Catálogo` (participa) ou `Elegível` (poderia participar).'
        CatalogListing:
          type: boolean
          nullable: true
          description: Participa do catálogo (Mercado Livre).
        CatalogEligible:
          type: boolean
          nullable: true
          description: Elegível ao catálogo.
        CatalogStatus:
          type: string
          nullable: true
          description: 'Status de catálogo do canal (ex.: `winning`).'
        CatalogStatusValue:
          type: string
          nullable: true
          description: 'Posição no catálogo: Vencedor, Competindo, Compartilhado, Não listado.'
        AutopartsPendingCompatibility:
          type: integer
          nullable: true
          description: 'Autopeças: tem compatibilidade pendente.'
        AutopartsRequiredCompatibility:
          type: integer
          nullable: true
          description: 'Autopeças: exige lista de compatibilidade.'
        AutopartsUniversalCompatibility:
          type: integer
          nullable: true
          description: 'Autopeças: compatibilidade universal.'
        HubProductAutopartsQuantity:
          type: integer
          nullable: true
          description: Quantidade de veículos compatíveis associados.
        PurchaseExperienceValue:
          type: number
          nullable: true
          description: Indicador de experiência de compra.
        IDHubProductQuestionAnswerTemplate:
          type: integer
          format: int64
          nullable: true
          description: Modelo de perguntas e respostas.
        AnswerTitle:
          type: string
          nullable: true
          description: Título do modelo de mensagem.
        HubEcommerceDescription:
          type: string
          nullable: true
          description: Descrição do anúncio.
        MainImageURL:
          type: string
          nullable: true
          description: Imagem principal.
        MainImageThumbnailURL:
          type: string
          nullable: true
          description: Miniatura da imagem principal.
        HubSku:
          type: array
          items:
            $ref: '#/components/schemas/HubSkuListSummary'
          description: Variações do anúncio (resumo).
    HubProductSpecificationItem:
      type: object
      description: Item de ficha técnica do anúncio.
      properties:
        IDSpecification:
          type: string
          nullable: true
          description: Identificador do campo da ficha técnica.
        SpecificationName:
          type: string
          nullable: true
          description: Nome do campo.
        SpecificationValue:
          type: string
          nullable: true
          description: Valor do campo.
        IDSpecificationValue:
          type: string
          nullable: true
          description: Identificador do valor selecionado.
        SpecificationCustomValue:
          type: string
          nullable: true
          description: Valor livre.
    HubProductSalesPolicyItem:
      type: object
      description: Política comercial associada ao anúncio.
      properties:
        IDTypeSkuSalesPolicy:
          type: integer
          format: int64
          description: Identificador da política comercial.
        SalesPolicy:
          type: string
          nullable: true
          description: Nome da política comercial.
    HubProductImageItem:
      type: object
      description: Imagem do anúncio.
      properties:
        IDHubProductImage:
          type: integer
          format: int64
          description: Identificador da imagem do anúncio.
        IDImage:
          type: integer
          format: int64
          description: Identificador da imagem.
        ImageOrder:
          type: integer
          description: Ordem de exibição.
        Url:
          type: string
          nullable: true
          description: Endereço da imagem.
        ImageSize:
          type: integer
          nullable: true
          description: Tamanho do arquivo.
        ImageWidth:
          type: integer
          nullable: true
          description: Largura.
        ImageHeight:
          type: integer
          nullable: true
          description: Altura.
        ImageName:
          type: string
          nullable: true
          description: Nome do arquivo.
    HubProductHealthItem:
      type: object
      description: Pendência de qualidade do anúncio.
      properties:
        TypeHubProductHealthDescription:
          type: string
          nullable: true
          description: Pendência que reduz a qualidade do anúncio.
    HubProductPurchaseExperienceItem:
      type: object
      description: Indicador de experiência de compra do anúncio.
      properties:
        PurchaseExperienceValue:
          type: number
          nullable: true
          description: Indicador de experiência de compra.
    HubProductQuantityPricingItem:
      type: object
      description: Faixa de preço por quantidade (Mercado Livre).
      properties:
        IDHubProductQuantityPricing:
          type: integer
          format: int64
          description: Identificador da faixa.
        IDHubProduct:
          type: integer
          format: int64
          nullable: true
          description: Anúncio.
        Quantity:
          type: integer
          description: Quantidade mínima da faixa.
        Price:
          type: number
          description: Preço por unidade na faixa.
    HubSkuSpecificationItem:
      type: object
      description: Item de ficha técnica da variação.
      properties:
        IDSpecification:
          type: string
          nullable: true
          description: Identificador do campo da ficha técnica.
        SpecificationName:
          type: string
          nullable: true
          description: Nome do campo.
        SpecificationValue:
          type: string
          nullable: true
          description: Valor do campo.
        IDSpecificationValue:
          type: string
          nullable: true
          description: Identificador do valor selecionado.
    HubSkuImageItem:
      type: object
      description: Imagem da variação.
      properties:
        IDHubSkuImage:
          type: integer
          format: int64
          description: Identificador da imagem da variação.
        IDImage:
          type: integer
          format: int64
          description: Identificador da imagem.
        ImageOrder:
          type: integer
          description: Ordem de exibição.
        Url:
          type: string
          nullable: true
          description: Endereço da imagem.
        ImageSize:
          type: integer
          nullable: true
          description: Tamanho do arquivo.
        ImageWidth:
          type: integer
          nullable: true
          description: Largura.
        ImageHeight:
          type: integer
          nullable: true
          description: Altura.
        ImageName:
          type: string
          nullable: true
          description: Nome do arquivo.
        IDHubAdvertisement:
          type: integer
          format: int64
          nullable: true
          description: Variação à qual a imagem pertence.
    HubSkuDetail:
      type: object
      description: Variação (item) do anúncio.
      properties:
        IDHubAdvertisement:
          type: integer
          format: int64
          description: Identificador da variação.
        IDHubProduct:
          type: integer
          format: int64
          nullable: true
          description: Anúncio ao qual pertence.
        IDSku:
          type: integer
          format: int64
          nullable: true
          description: SKU vinculado.
        IDSkuHub:
          type: string
          nullable: true
          description: Código da variação no canal.
        SkuName:
          type: string
          nullable: true
          description: Nome do produto.
        IDSkuCompany:
          type: string
          nullable: true
          description: Código de referência.
        BarCode:
          type: string
          nullable: true
          description: Código de barras.
        AccountName:
          type: string
          nullable: true
          description: Conta.
        ProductVariation:
          type: string
          nullable: true
          description: Atributos de variação.
        TypeProductVariationValue:
          type: string
          nullable: true
          description: Valores dos atributos de variação.
        HubSkuOrder:
          type: integer
          nullable: true
          description: Ordem da variação.
        IDTypeSku:
          type: integer
          format: int64
          nullable: true
          description: Tipo do produto.
        TypeProduct:
          type: string
          nullable: true
          description: Descrição do tipo.
        QtyAvailable:
          type: number
          nullable: true
          description: Quantidade disponível.
        QtyToSell:
          type: number
          nullable: true
          description: Quantidade a vender.
        QtySafetyStock:
          type: integer
          nullable: true
          description: Estoque de segurança.
        InfiniteInventory:
          type: boolean
          nullable: true
          description: Estoque infinito.
        SoldQuantity:
          type: integer
          nullable: true
          description: Quantidade vendida.
        PricingSet:
          type: number
          nullable: true
          description: Preço manual da variação.
        PricingCheck:
          type: number
          nullable: true
          description: Preço calculado para conferência.
        PricingSell:
          type: number
          nullable: true
          description: Preço de venda calculado.
        PricingList:
          type: number
          nullable: true
          description: Preço de tabela calculado.
        OriginalPrice:
          type: number
          nullable: true
          description: Preço de tabela do SKU.
        PriceMultiplyValue:
          type: number
          nullable: true
          description: Fator multiplicador de preço.
        PriceAddValue:
          type: number
          nullable: true
          description: Acréscimo de preço.
        PriceRounding:
          type: number
          nullable: true
          description: Arredondamento de preço.
        CostAverage:
          type: number
          nullable: true
          description: Custo médio.
        CostLastPurchase:
          type: number
          nullable: true
          description: Custo da última compra.
        IDCommercialCondition:
          type: integer
          format: int64
          nullable: true
          description: Condição comercial.
        CommercialCondition:
          type: string
          nullable: true
          description: Descrição da condição comercial.
        EcommerceModal:
          type: string
          nullable: true
          description: Modalidade de e-commerce.
        HubSkuListingTypeId:
          type: string
          enum:
            - bronze
            - free
            - gold
            - gold_premium
            - gold_pro
            - gold_special
            - silver
          nullable: true
          description: Tipo de anúncio da variação (Mercado Livre).
        HubSkuShippingFree:
          type: boolean
          nullable: true
          description: Frete grátis da variação.
        Comments:
          type: string
          nullable: true
          description: Observações.
        MainImageURL:
          type: string
          nullable: true
          description: Imagem principal da variação.
        PurchaseExperienceValue:
          type: number
          nullable: true
          description: Indicador de experiência de compra.
        IDHubUserProduct:
          type: integer
          format: int64
          nullable: true
          description: Identificador de User Product (Mercado Livre).
        HubSkuSpecification:
          type: array
          items:
            $ref: '#/components/schemas/HubSkuSpecificationItem'
          description: Ficha técnica da variação.
        HubSkuImage:
          type: array
          items:
            $ref: '#/components/schemas/HubSkuImageItem'
          description: Imagens da variação.
        PurchaseExperience:
          type: array
          items:
            $ref: '#/components/schemas/HubProductPurchaseExperienceItem'
          description: Experiência de compra da variação.
    HubProductDetail:
      type: object
      description: Detalhe completo do anúncio.
      properties:
        IDHubProduct:
          type: integer
          format: int64
          description: Identificador interno do anúncio.
        IDProduct:
          type: integer
          format: int64
          nullable: true
          description: SKU/produto vinculado.
        IDProductHub:
          type: string
          nullable: true
          description: Código do anúncio no canal.
        AccountName:
          type: string
          nullable: true
          description: Conta.
        HubProductName:
          type: string
          nullable: true
          description: Título do anúncio.
        EcommerceTitle:
          type: string
          nullable: true
          description: Título de e-commerce do produto.
        SkuName:
          type: string
          nullable: true
          description: Nome do produto (ou título de e-commerce, conforme parametrização).
        IDSkuCompany:
          type: string
          nullable: true
          description: Código de referência do produto.
        IDBrand:
          type: integer
          format: int64
          nullable: true
          description: Marca.
        IDTypeSku:
          type: integer
          format: int64
          nullable: true
          description: Tipo do produto.
        TypeProduct:
          type: string
          nullable: true
          description: Descrição do tipo.
        HubEcommerceDescription:
          type: string
          nullable: true
          description: Descrição do anúncio.
        EcommerceDescription:
          type: string
          nullable: true
          description: Descrição de e-commerce do produto.
        Comments:
          type: string
          nullable: true
          description: Observações internas.
        IDCompanyIntegration:
          type: integer
          format: int64
          nullable: true
          description: Integração (conta de canal).
        IDTypeCompanyIntegration:
          type: integer
          format: int64
          nullable: true
          description: Tipo de canal.
        CompanyIntegrationName:
          type: string
          nullable: true
          description: Nome da conta de integração.
        IntegrationName:
          type: string
          nullable: true
          description: Nome do canal.
        SalesChannelName:
          type: string
          nullable: true
          description: Nome do canal de vendas.
        CompanyIntegration:
          type: string
          nullable: true
          description: Canal e conta (texto combinado).
        LogoUrl:
          type: string
          nullable: true
          description: Logotipo do canal.
        PathName:
          type: string
          nullable: true
          description: Caminho interno do recurso.
        CategoryId:
          type: string
          nullable: true
          description: Categoria do canal.
        IDCategory:
          type: integer
          format: int64
          nullable: true
          description: Identificador interno da categoria.
        CategoryPath:
          type: string
          nullable: true
          description: Caminho/legenda da categoria.
        AdvertisementStatus:
          type: integer
          nullable: true
          description: 'Status do anúncio: `0` Inativo, `1` Ativo, `2` Fechado, `3` Pausado, `4` Em revisão, `5` Inabilitado canal.'
        StatusHubSku:
          type: string
          nullable: true
          description: Status (texto).
        HubProductSubStatus:
          type: integer
          nullable: true
          description: Sub-status (código).
        Substatus:
          type: string
          nullable: true
          description: Sub-status (texto).
        ReviewReason:
          type: string
          nullable: true
          description: Motivo de revisão informado pelo canal.
        ReviewRemedy:
          type: string
          nullable: true
          description: Ação sugerida para resolver a revisão.
        AdvertisementUrl:
          type: string
          nullable: true
          description: Endereço do anúncio no canal.
        ListingTypeId:
          type: string
          enum:
            - bronze
            - free
            - gold
            - gold_premium
            - gold_pro
            - gold_special
            - silver
          nullable: true
          description: Tipo de anúncio (Mercado Livre).
        ListingTypeDescription:
          type: string
          nullable: true
          description: Descrição do tipo de anúncio.
        Condition:
          type: string
          nullable: true
          description: 'Condição do item (ex.: `new`, `used`).'
        ShippingMode:
          type: string
          enum:
            - custom
            - me1
            - me2
            - not_specified
          nullable: true
          description: Forma de entrega (Mercado Livre).
        ShippingModeDescription:
          type: string
          nullable: true
          description: Descrição da forma de entrega.
        ShippingFree:
          type: string
          nullable: true
          description: Frete grátis.
        ShippingLocalPickUp:
          type: string
          nullable: true
          description: Retirada no local.
        ShippingLogisticType:
          type: string
          nullable: true
          description: 'Tipo de logística (ex.: `fulfillment` = Full).'
        ShippingTags:
          type: string
          nullable: true
          description: 'Etiquetas de envio (ex.: `self_service_in` = Flex).'
        WarrantyType:
          type: string
          nullable: true
          description: Tipo de garantia.
        WarrantyTime:
          type: integer
          nullable: true
          description: Prazo de garantia.
        WarrantyTimeType:
          type: string
          nullable: true
          description: Unidade do prazo de garantia.
        LeadTimeDays:
          type: integer
          nullable: true
          description: Prazo de disponibilização (dias).
        OfficialStore:
          type: string
          nullable: true
          description: Loja Oficial (Mercado Livre).
        ShowWithoutStock:
          type: string
          nullable: true
          description: Mantém visível sem estoque.
        Visible:
          type: string
          nullable: true
          description: Anúncio visível.
        Health:
          type: number
          nullable: true
          description: Qualidade do anúncio (%).
        TotalVisits:
          type: integer
          nullable: true
          description: Total de visitas (canal).
        SoldQuantity:
          type: integer
          nullable: true
          description: Quantidade vendida.
        Rating:
          type: number
          nullable: true
          description: Avaliação média do produto no canal.
        PurchaseExperienceValue:
          type: number
          nullable: true
          description: Indicador de experiência de compra.
        PriceListSet:
          type: number
          nullable: true
          description: Preço de (preço cheio).
        PriceSellSet:
          type: number
          nullable: true
          description: Preço por (preço de venda).
        NetPricingSet:
          type: number
          nullable: true
          description: Preço líquido (Mercado Livre).
        NetPricingEligible:
          type: boolean
          nullable: true
          description: Elegível ao Preço Líquido (Mercado Livre).
        CatalogListing:
          type: boolean
          nullable: true
          description: Participa do catálogo.
        CatalogEligible:
          type: boolean
          nullable: true
          description: Elegível ao catálogo.
        CatalogProductId:
          type: string
          nullable: true
          description: Produto de catálogo (Mercado Livre).
        CatalogStatus:
          type: string
          nullable: true
          description: Status no catálogo (canal).
        CatalogPriceToWin:
          type: number
          nullable: true
          description: Preço para vencer a vitrine de catálogo.
        CatalogOpportunity:
          type: string
          nullable: true
          description: Oportunidades de melhoria sugeridas pelo canal.
        AutopartsException:
          type: boolean
          nullable: true
          description: Exceção de compatibilidade (autopeças).
        AutopartsUniversalCompatibility:
          type: boolean
          nullable: true
          description: Compatibilidade universal (autopeças).
        AutopartsUniversalCompatibilityAllowed:
          type: integer
          nullable: true
          description: Permite compatibilidade universal (autopeças/Mercado Livre).
        AutopartsPendingCompatibility:
          type: boolean
          nullable: true
          description: Compatibilidade pendente (autopeças).
        AutopartsRequiredCompatibility:
          type: boolean
          nullable: true
          description: Exige compatibilidade (autopeças).
        UserProductListing:
          type: string
          nullable: true
          description: User Product (Mercado Livre).
        UserProductEnabled:
          type: integer
          nullable: true
          description: User Product habilitado (Mercado Livre).
        HubUserProductEligible:
          type: boolean
          nullable: true
          description: Elegível a User Product (Mercado Livre).
        HubProductQuantityPricingAllowed:
          type: integer
          nullable: true
          description: Permite preço por quantidade (Mercado Livre).
        IDHubProductQuestionAnswerTemplate:
          type: integer
          format: int64
          nullable: true
          description: Modelo de perguntas e respostas.
        AnswerTitle:
          type: string
          nullable: true
          description: Título do modelo de mensagem.
        AnswerTemplate:
          type: string
          nullable: true
          description: Conteúdo do modelo de mensagem.
        MainImageURL:
          type: string
          nullable: true
          description: Imagem principal.
        MainImageThumbnailURL:
          type: string
          nullable: true
          description: Miniatura da imagem principal.
        CreatedTimestamp:
          type: string
          nullable: true
          description: Data de criação.
          format: date-time
        RecordTimestamp:
          type: string
          nullable: true
          description: Data da última alteração.
          format: date-time
        HubProductSpecification:
          type: array
          items:
            $ref: '#/components/schemas/HubProductSpecificationItem'
          description: Ficha técnica do anúncio.
        HubProductSalesPolicy:
          type: array
          items:
            $ref: '#/components/schemas/HubProductSalesPolicyItem'
          description: Políticas comerciais.
        HubProductImage:
          type: array
          items:
            $ref: '#/components/schemas/HubProductImageItem'
          description: Imagens do anúncio.
        HealthAction:
          type: array
          items:
            $ref: '#/components/schemas/HubProductHealthItem'
          description: Pendências que reduzem a qualidade.
        PurchaseExperience:
          type: array
          items:
            $ref: '#/components/schemas/HubProductPurchaseExperienceItem'
          description: Indicadores de experiência de compra.
        HubProductQuantityPricing:
          type: array
          items:
            $ref: '#/components/schemas/HubProductQuantityPricingItem'
          description: Faixas de preço por quantidade (Mercado Livre).
        HubSku:
          type: array
          items:
            $ref: '#/components/schemas/HubSkuDetail'
          description: Variações (itens) do anúncio.
    HubProductAutopartsPositionItem:
      type: object
      description: Posição de aplicação do veículo compatível.
      properties:
        SpecificationValue:
          type: array
          items:
            type: string
          description: Valores de posição de aplicação.
        IDSpecificationValue:
          type: array
          items:
            type: string
          description: Identificadores dos valores de posição.
    HubProductAutopartsItem:
      type: object
      description: Veículo compatível do anúncio de autopeças.
      properties:
        IDHubProductAutoparts:
          type: integer
          format: int64
          description: Identificador do veículo compatível.
        IDHubProduct:
          type: integer
          format: int64
          nullable: true
          description: Anúncio.
        IDCompanyIntegration:
          type: integer
          format: int64
          nullable: true
          description: Integração (conta de canal).
        IDProductHub:
          type: string
          nullable: true
          description: Código do anúncio no canal.
        ProductId:
          type: string
          nullable: true
          description: Identificador do veículo no catálogo do canal.
        Notes:
          type: string
          nullable: true
          description: Observações.
        Brand:
          type: string
          nullable: true
          description: Marca do veículo.
        Model:
          type: string
          nullable: true
          description: Modelo.
        Year:
          type: string
          nullable: true
          description: Ano.
        Trim:
          type: string
          nullable: true
          description: Acabamento.
        ShortVersion:
          type: string
          nullable: true
          description: Versão.
        Engine:
          type: string
          nullable: true
          description: Motor.
        Fuel:
          type: string
          nullable: true
          description: Combustível.
        Power:
          type: string
          nullable: true
          description: Potência.
        BodyType:
          type: string
          nullable: true
          description: Carroceria.
        Transmission:
          type: string
          nullable: true
          description: Transmissão.
        Gear:
          type: string
          nullable: true
          description: Câmbio.
        Doors:
          type: string
          nullable: true
          description: Portas.
        Steering:
          type: string
          nullable: true
          description: Direção.
        Traction:
          type: string
          nullable: true
          description: Tração.
        Valves:
          type: string
          nullable: true
          description: Válvulas.
        IDHubOrderClaim:
          type: integer
          format: int64
          nullable: true
          description: Reclamação de compatibilidade associada.
        IDOrder:
          type: integer
          format: int64
          nullable: true
          description: Pedido relacionado à reclamação.
        ClaimQuantity:
          type: integer
          nullable: true
          description: Quantidade de reclamações de compatibilidade.
        HubProductAutopartsPosition:
          type: array
          items:
            $ref: '#/components/schemas/HubProductAutopartsPositionItem'
          description: Posições de aplicação.
    TypeInventorySummaryEnum:
      type: integer
      enum:
        - 1
        - 2
        - 3
        - 4
      description: 'Tipo de inventário: `1` Endereço · `2` SKU · `3` Livre · `4` Auditoria.'
    StatusSkuInventoryEnum:
      type: integer
      enum:
        - 1
        - 2
        - 3
        - 4
        - 5
        - 6
        - 7
        - 8
        - 9
        - 10
      description: >-
        Status do inventário: `1` Finalizado · `2` Aberto · `3` Em andamento · `4` Cancelado · `5` Processando · `6` Fim
        1ª conferência · `7` Fim 2ª conferência · `8` Fim 3ª conferência · `9` Processando 2ª conf. · `10` Processando
        3ª conf.
    TypeInventorySummaryQuantityEnum:
      type: integer
      enum:
        - 1
        - 2
        - 3
      description: >-
        Estratégia de tratamento de saldo na contagem: `1` Não compensar negativos (padrão) · `2` Somar quantidade
        reservada (em manuseio) · `3` Compensar negativos.
    IDTypeQueueEnum:
      type: integer
      enum:
        - 1
        - 2
      description: 'Tipo de item da fila: `1` Endereço · `2` SKU.'
    InventorySummaryCreate:
      type: object
      required:
        - IDTypeInventorySummary
        - IDStockKeepingUnitDistributionCenter
        - IDStockKeepingUnitWarehouse
        - InventoryDescription
      properties:
        IDTypeInventorySummary:
          allOf:
            - $ref: '#/components/schemas/TypeInventorySummaryEnum'
          description: Tipo do inventário (Endereço, SKU, Livre ou Auditoria).
        IDStockKeepingUnitDistributionCenter:
          type: integer
          description: Centro de distribuição. Deve pertencer à empresa autenticada.
        IDStockKeepingUnitWarehouse:
          type: integer
          description: Armazém. Precisa estar ativo (`Status = 1`) e pertencer ao centro de distribuição informado.
        InventoryDescription:
          type: string
          description: Descrição livre que identifica o inventário.
        IDTypeQuantity:
          allOf:
            - $ref: '#/components/schemas/TypeInventorySummaryQuantityEnum'
          description: >-
            Estratégia de tratamento de saldo na contagem. Quando omitido, vale `1` (Não compensar negativos). No
            frontend a opção "Compensar saldo negativo = Sim" envia `3`.
    InventorySummaryUpdate:
      type: object
      description: >-
        Atualização do cabeçalho do inventário: muda status (finalizando conferências) ou atribui o colaborador da
        conferência corrente.
      properties:
        IDTypeStatusSkuInventory:
          allOf:
            - $ref: '#/components/schemas/StatusSkuInventoryEnum'
          description: >-
            Novo status. Os valores aceitos são apenas `6` (Fim 1ª conferência), `7` (Fim 2ª conferência) ou `8` (Fim 3ª
            conferência) — o sistema registra o timestamp correspondente. Outros valores são rejeitados conforme o
            status atual do inventário.
        InventoryStartUser:
          type: integer
          description: >-
            Colaborador da 1ª conferência. Só pode ser atribuído enquanto o inventário ainda não passou do fim da 1ª
            (status `< 6`). Precisa ser usuário ativo (`Status = 1`) na empresa.
        InventorySecondUserStart:
          type: integer
          description: >-
            Colaborador da 2ª conferência. Só pode ser atribuído quando o inventário está no status `6` (Fim 1ª
            conferência). Precisa ser usuário ativo na empresa.
        InventoryThirdUserStart:
          type: integer
          description: >-
            Colaborador da 3ª conferência. Só pode ser atribuído quando o inventário está no status `7` (Fim 2ª
            conferência). Precisa ser usuário ativo na empresa.
    InventorySummaryListItem:
      type: object
      description: Inventário (`StockKeepingUnitInventorySummary`) no formato retornado pela listagem.
      properties:
        IDStockKeepingUnitInventorySummary:
          type: integer
          description: Código do inventário.
        AccountName:
          type: string
          description: Conta (subdomínio) da empresa.
        IDCompany:
          type: integer
          description: Identificador da empresa.
        IDStockKeepingUnitDistributionCenter:
          type: integer
          nullable: true
          description: Centro de distribuição em que o inventário acontece.
        DistributionCenterName:
          type: string
          nullable: true
          description: Nome do centro de distribuição.
        IDStockKeepingUnitWarehouse:
          type: integer
          description: Depósito sob inventário.
        WarehouseName:
          type: string
          description: Nome do depósito.
        IDTypeInventorySummary:
          $ref: '#/components/schemas/TypeInventorySummaryEnum'
          description: 'Tipo do inventário: `1` Endereço (varrer endereços), `2` SKU (lista de SKUs), `3` Livre, `4` Auditoria.'
        TypeInventorySummary:
          type: string
          description: Endereço / Sku / Livre / Auditoria.
        IDTypeStatusSkuInventory:
          $ref: '#/components/schemas/StatusSkuInventoryEnum'
          description: >-
            Status do inventário: `1` Finalizado, `2` Aberto, `3` Em andamento, `4` Cancelado, `5` Processando, `6` Fim
            1ª conferência, `7` Fim 2ª conferência, `8` Fim 3ª conferência, `9` Processando 2ª conf., `10` Processando
            3ª conf.
        TypeStatusSkuInventory:
          type: string
          description: Descrição textual do status.
        IDTypeQuantity:
          $ref: '#/components/schemas/TypeInventorySummaryQuantityEnum'
          description: >-
            Política de quantidade no fechamento: `1` Não compensar negativos, `2` Somar quantidade reservada, `3`
            Compensar negativos.
        InventoryDescription:
          type: string
          nullable: true
          description: Descrição livre do inventário.
        RecordUserCreated:
          type: string
          description: Login do usuário que criou o inventário.
        InventoryStartUser:
          type: integer
          nullable: true
          description: Colaborador da 1ª conferência (ID).
        InventoryStartUserLogin:
          type: string
          nullable: true
          description: Login do usuário que iniciou o inventário.
        InventoryStartTimestamp:
          type: string
          format: date-time
          nullable: true
          description: Início da 1ª conferência.
        InventoryFirstFinishTimestamp:
          type: string
          format: date-time
          nullable: true
          description: Fim da 1ª conferência.
        InventorySecondUserStart:
          type: integer
          nullable: true
          description: Identificador do usuário que iniciou a 2ª conferência.
        InventorySecondUserStartLogin:
          type: string
          nullable: true
          description: Login do usuário da 2ª conferência.
        InventorySecondStartTimestamp:
          type: string
          format: date-time
          nullable: true
          description: Data e hora de início da 2ª conferência.
        InventorySecondFinishTimestamp:
          type: string
          format: date-time
          nullable: true
          description: Data e hora de fim da 2ª conferência.
        InventoryThirdUserStart:
          type: integer
          nullable: true
          description: Identificador do usuário da 3ª conferência.
        InventoryThirdUserStartLogin:
          type: string
          nullable: true
          description: Login do usuário da 3ª conferência.
        InventoryThirdStartTimestamp:
          type: string
          format: date-time
          nullable: true
          description: Data e hora de início da 3ª conferência.
        InventoryThirdFinishTimestamp:
          type: string
          format: date-time
          nullable: true
          description: Data e hora de fim da 3ª conferência.
        InventoryFinishUser:
          type: string
          nullable: true
          description: Login do colaborador que abriu/finalizou (`InventoryStartUser` resolvido).
        InventoryFinishTimestamp:
          type: string
          format: date-time
          nullable: true
          description: Fim do inventário (geração dos ajustes de estoque).
        RecordTimestamp:
          type: string
          format: date-time
          description: Criação do inventário.
        StockKeepingUnitInventorySummarySkuQueueCount:
          type: integer
          description: Quantidade de SKUs na fila.
        StockKeepingUnitInventorySummaryLocationQueueCount:
          type: integer
          description: Quantidade de endereços na fila.
    InventoryItemDetail:
      type: object
      description: Item contado (`StockKeepingUnitInventoryItems`) com os dados do SKU e do lote.
      properties:
        IDStockKeepingUnitInventoryItems:
          type: integer
          description: Código do item contado.
        IDSku:
          type: integer
          description: Identificador do SKU contado.
        SkuName:
          type: string
          description: Nome do SKU.
        IDSkuCompany:
          type: string
          description: Código do produto na empresa.
        BarCode:
          type: string
          nullable: true
          description: Código de barras principal.
        Batch:
          type: integer
          nullable: true
          description: Indica se o SKU usa controle de lote (`1` = sim).
        RastroControl:
          type: integer
          nullable: true
          description: SKU exige rastreabilidade (`1` = sim).
        BatchRequired:
          type: integer
          nullable: true
          description: Lote obrigatório no lançamento (`1` = sim).
        BestBeforeRequired:
          type: integer
          nullable: true
          description: Data de validade obrigatória no lançamento (`1` = sim).
        QuantityBatch:
          type: number
          nullable: true
          description: Quantidade que o sistema esperava no lote (saldo apurado).
        QuantityInventory:
          type: number
          nullable: true
          description: Quantidade contada na 1ª conferência.
        QuantityInventorySecond:
          type: number
          nullable: true
          description: Quantidade contada na 2ª conferência.
        QuantityInventoryThird:
          type: number
          nullable: true
          description: Quantidade contada na 3ª conferência.
        QuantityInventoryDiff:
          type: number
          nullable: true
          description: Diferença `QuantityInventory - QuantityBatch` (calculada).
        QuantityInventorySecondDiff:
          type: number
          nullable: true
          description: Diferença entre a quantidade contada na 2ª conferência e a quantidade do sistema.
        QuantityInventoryThirdDiff:
          type: number
          nullable: true
          description: Diferença entre a quantidade contada na 3ª conferência e a quantidade do sistema.
        IDBatch:
          type: integer
          nullable: true
          description: Código do lote contado.
        BestBeforeDate:
          type: string
          format: date
          nullable: true
          description: Data de validade (vazia quando o sistema usa `4000-01-01` como sentinel).
        ManufacturingDate:
          type: string
          format: date
          nullable: true
          description: Data de fabricação do lote contado (quando o SKU é controlado por lote).
        BatchComments:
          type: string
          nullable: true
          description: Número do lote informado.
        IDStockKeepingUnitLocation:
          type: integer
          nullable: true
          description: Endereço onde o lote está localizado.
        Address:
          type: string
          nullable: true
          description: Descrição do endereço.
        IDStockKeepingUnitWarehouse:
          type: integer
          description: Armazém do item.
        WarehouseName:
          type: string
          nullable: true
          description: Nome do depósito do item.
        AccountName:
          type: string
          description: Conta (subdomínio) da empresa.
        BarCodeList:
          type: array
          description: Códigos de barras alternativos do SKU.
          items:
            type: string
        BarCodePackageList:
          type: array
          description: Códigos de barras de embalagem (caixa, fardo) com fator de conversão.
          items:
            type: object
            properties:
              IDStockKeepingUnitBarCodePackage:
                type: integer
                description: >-
                  Identificador do código de barras de embalagem aceito para esta contagem (permite contar a caixa em
                  vez da unidade).
              BarCodePackage:
                type: string
                description: Código de barras da embalagem.
              PackageFactor:
                type: number
                description: Quantidade de unidades dentro da embalagem (multiplica a contagem).
        MainImageThumbnailURL:
          type: string
          nullable: true
          description: URL da imagem principal do SKU (thumbnail).
    InventorySkuQueueItem:
      type: object
      description: SKU presente na fila de contagem (`StockKeepingUnitInventorySummarySkuQueue`).
      properties:
        IDStockKeepingUnitInventorySummarySkuQueue:
          type: integer
          description: Identificador da entrada do SKU na fila de contagem do inventário.
        IDSku:
          type: integer
          description: Identificador do SKU enfileirado para contagem.
        SkuName:
          type: string
          description: Nome do SKU enfileirado.
        IDSkuCompany:
          type: string
          description: Código de referência interno do SKU, definido pela empresa (campo `IDSkuCompany`).
    InventoryLocationQueueItem:
      type: object
      description: Endereço presente na fila de contagem (`StockKeepingUnitInventorySummaryLocationQueue`).
      properties:
        IDStockKeepingUnitInventorySummarySkuQueue:
          type: integer
          description: Mantido por compatibilidade — corresponde ao ID da fila de endereço.
        IDStockKeepingUnitLocation:
          type: integer
          description: Identificador do endereço de armazenagem (rua/coluna/nível) incluído na fila de contagem do inventário.
        Address:
          type: string
          description: Descrição do endereço.
    InventorySummaryDetail:
      allOf:
        - $ref: '#/components/schemas/InventorySummaryListItem'
        - type: object
          description: >-
            Detalhe completo do inventário, retornado por `GET /sku/inventory-summary/{id}`. Inclui o tipo de quantidade
            resolvido, a lista de itens contados e as filas de SKUs e endereços.
          properties:
            TypeInventorySummaryQuantity:
              type: string
              description: Descrição textual (Não compensar negativos / Somar quantidade reservada / Compensar negativos).
            Items:
              type: array
              description: Itens contados (uma linha por SKU + lote).
              items:
                $ref: '#/components/schemas/InventoryItemDetail'
            StockKeepingUnitInventorySummarySkuQueue:
              type: array
              description: Fila de SKUs a inventariar (inventário tipo SKU).
              items:
                $ref: '#/components/schemas/InventorySkuQueueItem'
            StockKeepingUnitInventorySummaryLocationQueue:
              type: array
              description: >-
                Fila de endereços a inventariar (inventário tipo Endereço), ordenada para otimizar o percurso de picking
                quando os endereços têm coordenadas (`Floor`, `Street`, `Module`, `Column`, `Level`, `LocationSide`).
              items:
                $ref: '#/components/schemas/InventoryLocationQueueItem'
    InventoryItemUpdate:
      type: array
      description: >-
        Lançamento de quantidade contada de um item. O sistema lê apenas a posição `[0]`. O sistema decide
        automaticamente em qual conferência a quantidade é registrada (1ª, 2ª ou 3ª) com base no status atual do
        inventário; campos das demais conferências são ignorados.
      items:
        type: object
        properties:
          QuantityInventory:
            type: number
            description: Quantidade contada na 1ª conferência.
          QuantityInventorySecond:
            type: number
            description: >-
              Quantidade contada na 2ª conferência. Quando informada e a 2ª conferência ainda não foi iniciada, o
              sistema atribui o usuário corrente como colaborador da 2ª e muda o status para `9` (Processando 2ª conf.).
          QuantityInventoryThird:
            type: number
            description: >-
              Quantidade contada na 3ª conferência. Quando informada e a 3ª conferência ainda não foi iniciada, o
              sistema atribui o usuário corrente como colaborador da 3ª e muda o status para `10` (Processando 3ª
              conf.).
          BestBeforeDate:
            type: string
            format: date
            description: Data de validade do lote. Obrigatória quando o SKU tem `BestBeforeRequired = 1`.
          ManufacturingDate:
            type: string
            format: date
            description: Data de fabricação. Obrigatória quando o SKU tem `RastroControl = 1`.
          BatchComments:
            type: string
            description: Número do lote informado. Obrigatório quando o SKU tem `BatchRequired = 1`.
    InventorySkuQueueAdd:
      description: >-
        Item ou itens a adicionar na fila ou lançar contagem. Quando enviado como objeto único, processa apenas aquele;
        como array, processa um a um.


        - `IDTypeQueue=1` (Endereço) → o objeto deve conter `IDStockKeepingUnitLocation`.

        - `IDTypeQueue=2` (SKU) → o objeto deve conter `IDSku`.

        - Sem `IDTypeQueue` → lançamento de **contagem livre**; deve conter `IDSku`, `IDStockKeepingUnitWarehouse` e
        `QuantityInventory` (lote/validade/fabricação opcionais).
      oneOf:
        - $ref: '#/components/schemas/InventorySkuQueueAddItem'
        - type: array
          items:
            $ref: '#/components/schemas/InventorySkuQueueAddItem'
    InventorySkuQueueAddItem:
      type: object
      properties:
        IDSku:
          type: integer
          description: >-
            SKU. Obrigatório para `IDTypeQueue=2` e para lançamento de contagem livre. Precisa ser do tipo Sku,
            Matéria-prima ou Uso e consumo (`IDTypeSku IN (3, 6, 7)`) e pertencer à empresa.
        IDStockKeepingUnitLocation:
          type: integer
          description: >-
            Endereço. Obrigatório para `IDTypeQueue=1`. Precisa pertencer a um armazém do centro de distribuição do
            inventário.
        IDStockKeepingUnitWarehouse:
          type: integer
          description: Armazém da contagem. Obrigatório para lançamento de contagem livre.
        QuantityInventory:
          type: number
          description: >-
            Quantidade contada. Quando informada, distribui o saldo entre os lotes existentes (mais novo primeiro, com
            saldo positivo) e ajusta automaticamente.
        IDBatchNumber:
          type: integer
          description: Lote específico (opcional). Quando enviado, a quantidade é lançada diretamente neste lote.
        BestBeforeDate:
          type: string
          format: date
          description: >-
            Data de validade do lote a contar no inventário, no formato `YYYY-MM-DD`. Obrigatória quando o SKU exige
            rastreabilidade de validade.
        ManufacturingDate:
          type: string
          format: date
          description: >-
            Data de fabricação do lote a contar, no formato `YYYY-MM-DD`. Obrigatória quando o SKU exige rastreabilidade
            de lote.
        BatchComments:
          type: string
          description: Número do lote informado.
    InventoryFinishResult:
      type: string
      description: >-
        Retorna a string literal `"sucesso"` quando o inventário foi finalizado. Os ajustes de estoque (entradas/saídas
        em `StockKeepingUnitMovement`) são gerados de forma assíncrona durante o processamento, e uma notificação
        `SkuBalanceInventoryFinish` é publicada no webhook configurado.
      example: sucesso
    InventoryQueueAddError:
      type: object
      description: >-
        Erro parcial de adição em lote — quando a requisição envia um array, itens inválidos são acumulados aqui em vez
        de interromper a operação.
      properties:
        IDSku:
          type: integer
          description: SKU que falhou ao ser adicionado à fila de contagem.
        Armazem:
          type: integer
          description: >-
            Identificador do armazém (`IDStockKeepingUnitWarehouse`) em que o SKU não pôde ser enfileirado (ex.: armazém
            não pertence à empresa ou não tem endereços ativos).
        Lote:
          type: integer
          description: >-
            Identificador do lote (`IDBatchNumber`) que falhou ao ser enfileirado. `0` quando o SKU não usa controle de
            lote.
        Description:
          type: string
          description: 'Causa do erro: `Sku não existe`, `Armazém não existe`, `Lote não existe`.'
        Status:
          type: integer
          enum:
            - 0
          description: Sempre `0` (falha).
    SkuMovementListItem:
      type: object
      description: Linha da listagem padrão de movimentação de estoque.
      properties:
        AccountName:
          type: string
          description: Conta (subdomínio) à qual o SKU pertence.
        IDSkuMovement:
          type: integer
          description: Identificador único da movimentação.
        IDSku:
          type: integer
          description: SKU envolvido na movimentação.
        SkuName:
          type: string
          description: >-
            Nome do produto (concatenado com o nome do produto-pai em variações; respeita a parametrização
            `OnlySkuName`).
        IDSkuCompany:
          type: string
          description: Código de referência do SKU.
        BarCode:
          type: string
          nullable: true
          description: Código de barras principal do SKU.
        Brand:
          type: string
          nullable: true
          description: Nome da marca do SKU.
        CostSet:
          type: number
          format: float
          nullable: true
          description: Custo manual cadastrado na ficha do SKU.
        IDTypeMovement:
          type: integer
          description: Sentido da movimentação. `0` = entrada, `1` = saída.
          enum:
            - 0
            - 1
        TypeSkuMovement:
          type: string
          description: Texto do sentido — `Entrada` quando `IDTypeMovement = 0`, `Saída` quando `IDTypeMovement = 1`.
          enum:
            - Entrada
            - Saída
        TypeMovement:
          type: string
          nullable: true
          description: >-
            Origem da movimentação: `Recebimento`, `Venda`, `Transferência CD`, `Transferência endereço`, `Ajuste saldo
            estoque`, `Inventário`, `Produção`.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora em que a movimentação foi registrada.
        DateLastRecordModification:
          type: string
          format: date-time
          nullable: true
          description: Última modificação do registro — útil para o filtro `SinceDateLastRecordModification`.
        Quantity:
          type: number
          description: Quantidade movimentada (sempre positiva — o sentido vem de `IDTypeMovement`).
        BalanceChange:
          type: integer
          description: >-
            `1` se a movimentação alterou o saldo físico; `0` se foi apenas registro fiscal (ex.: NF simplificada ou
            pedido do tipo Nota Fiscal sem movimentação de saldo).
          enum:
            - 0
            - 1
        IDStatusSku:
          type: integer
          nullable: true
          description: Status do SKU na movimentação (`1` = saudável, `0` = não conformidade).
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
        IDStockKeepingUnitWarehouse:
          type: integer
          description: Armazém em que a movimentação aconteceu.
        WarehouseName:
          type: string
          description: Nome do armazém da movimentação.
        IDBatch:
          type: integer
          nullable: true
          description: Lote do item movimentado.
        BatchComments:
          type: string
          nullable: true
          description: Descrição do lote.
        BestBeforeDate:
          type: string
          format: date
          nullable: true
          description: Validade do lote.
        ManufacturingDate:
          type: string
          format: date
          nullable: true
          description: Data de fabricação do lote.
        Comments:
          type: string
          nullable: true
          description: Comentário livre da movimentação.
        IDOrder:
          type: integer
          nullable: true
          description: Pedido que originou a movimentação (quando é venda).
        Order:
          type: string
          nullable: true
          description: Número/identificador do pedido.
        IDPurchase:
          type: integer
          nullable: true
          description: Recebimento que originou a movimentação (quando é entrada de compra).
        IDStockKeepingUnitProduction:
          type: integer
          nullable: true
          description: Ordem de produção que originou a movimentação.
        IDOriginIDSkuMovement:
          type: integer
          nullable: true
          description: Movimentação de origem (preenchida no par origem/destino de transferências).
        IDStockKeepingUnitInventory:
          type: integer
          nullable: true
          description: Conferência de inventário associada (quando aplicável).
        IDStockKeepingUnitInventorySummary:
          type: integer
          nullable: true
          description: Resumo de inventário associado.
        IDTypeFulfillmentNonconformity:
          type: integer
          nullable: true
          description: Tipo de não conformidade no fulfillment (quando aplicável).
          enum:
            - 1
            - 2
            - 4
            - 5
            - 6
        TypeFulfillmentNonconformity:
          type: string
          nullable: true
          description: Texto da não conformidade (resolvido a partir de `IDTypeFulfillmentNonconformity` via consulta).
        QuantityNonconformity:
          type: number
          nullable: true
          description: Quantidade marcada em não conformidade.
        PriceSelling:
          type: number
          format: float
          nullable: true
          description: Preço unitário de venda (preço total dividido pela quantidade).
        PriceSellingTotal:
          type: number
          format: float
          nullable: true
          description: Preço total da venda (lado de saída).
        ValueCost:
          type: number
          format: float
          nullable: true
          description: >-
            Custo unitário (custo total dividido pela quantidade). Somente para usuários com privilégio de visualização
            de custo.
        ValueCostTotal:
          type: number
          format: float
          nullable: true
          description: Custo total da movimentação.
        ValueCostUnitPurchase:
          type: number
          format: float
          nullable: true
          description: Alias de `ValueCost` para a listagem padrão (manter retrocompatibilidade do frontend).
        NfeIpiValue:
          type: number
          format: float
          nullable: true
          description: Valor do IPI vinculado à movimentação (NF de entrada).
        NfeIcmsSTValue:
          type: number
          format: float
          nullable: true
          description: Valor do ICMS-ST destacado para o item.
        NfeFcpSTValue:
          type: number
          format: float
          nullable: true
          description: Valor do FCP-ST destacado para o item.
        ValueDiscount:
          type: number
          format: float
          nullable: true
          description: Valor de desconto destacado para o item.
        NfeCFOP:
          type: string
          nullable: true
          description: CFOP da NF associada.
        NfeNumber:
          type: integer
          nullable: true
          description: Número da NF associada (de venda para `IDTypeMovement = 1`, de entrada para `IDTypeMovement = 0`).
        NfeDhEmi:
          type: string
          format: date-time
          nullable: true
          description: Data de emissão da NF associada.
        IDStatusInvoice:
          type: integer
          nullable: true
          description: Identificador do status da NF.
        StatusInvoice:
          type: string
          nullable: true
          description: Texto do status da NF (`Pendente`, `Emitida`, `Erro`, `Cancelada`).
        IDStatusOrder:
          type: integer
          nullable: true
          description: Status do pedido (quando origem é venda).
        StatusOrder:
          type: string
          nullable: true
          description: >-
            Status atual do pedido associado à movimentação (`Aberto`, `Faturado`, `Cancelado`, etc.). Vazio para
            movimentações sem pedido.
        TypeOrder:
          type: string
          nullable: true
          description: Tipo do pedido (cadastrado em Tipo Pedido).
        IDOrderType:
          type: integer
          nullable: true
          description: >-
            Tipo do pedido associado à movimentação (venda, devolução, transferência, etc.). Vazio para movimentações
            sem pedido.
        OrderFrom:
          type: string
          nullable: true
          description: Origens declaradas no pedido, sem repetições.
        IDCompanyIntegration:
          type: integer
          nullable: true
          description: Canal de venda (integração) que originou o pedido. Vazio para movimentações sem pedido.
        CompanyIntegration:
          type: string
          nullable: true
          description: 'Nome da integração concatenado: `TipoIntegração - NomeIntegração`.'
        IDCompanyInvoice:
          type: integer
          nullable: true
          description: Filial faturadora do pedido associado. Vazio quando não se aplica.
        CompanyInvoiceNameCorporateName:
          type: string
          nullable: true
          description: Razão social da empresa faturadora.
        AccountNameInvoice:
          type: string
          nullable: true
          description: Conta da empresa faturadora.
        ConsumerNameCorporateName:
          type: string
          nullable: true
          description: Nome ou razão social do cliente do pedido.
        ConsumerCpfCnpj:
          type: string
          nullable: true
          description: CPF/CNPJ do cliente do pedido associado.
        ConsumerEmail:
          type: string
          nullable: true
          description: E-mail do cliente do pedido associado.
        IDConsumer:
          type: integer
          nullable: true
          description: Identificador do cliente do pedido associado.
        ShippingState:
          type: string
          nullable: true
          description: UF de entrega do pedido.
        InvoiceFinishTimestamp:
          type: string
          format: date-time
          nullable: true
          description: Data de finalização do recebimento (quando origem é compra).
        CheckinTimestamp:
          type: string
          format: date-time
          nullable: true
          description: Data de check-in do recebimento.
        Login:
          type: string
          nullable: true
          description: >-
            Usuário responsável pela transferência ou ajuste (resolvido a partir do `IDUser` registrado em
            `StockKeepingUnitMovementTransfer` ou `StockKeepingUnitInventory`).
        IsTransfer:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: >-
            Indica se o tipo do pedido é de transferência entre centros de distribuição (`1`) ou não (`0`). Nulo quando
            a movimentação não está vinculada a um pedido.
    SkuMovementKardexItem:
      type: object
      description: >-
        Linha do Kardex: para uma combinação SKU + armazém, mostra a movimentação com saldo acumulado e custo médio
        acumulado.
      properties:
        AccountName:
          type: string
          description: Subdomínio (conta) da empresa dona da movimentação.
        IDSkuMovement:
          type: integer
          description: Identificador da movimentação no kardex.
        IDSku:
          type: integer
          description: SKU movimentado.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora em que a movimentação foi registrada.
        DateCreated:
          type: string
          format: date-time
          description: >-
            Data efetiva — usa `RecordTimestamp` do pedido (se venda) ou do recebimento (se entrada de compra); caso
            contrário a data da própria movimentação.
        IDTypeMovement:
          type: integer
          enum:
            - 0
            - 1
          description: 'Tipo da movimentação: `0` Saída, `1` Entrada.'
        TypeSkuMovement:
          type: string
          enum:
            - Entrada
            - Saída
          description: 'Descrição textual do tipo: `Entrada` ou `Saída`.'
        TypeMovement:
          type: string
          nullable: true
          description: >-
            Origem da movimentação: `Recebimento`, `Venda`, `Transferência CD`, `Transferência endereço`, `Ajuste saldo
            estoque`, `Inventário`, `Produção`.
        Login:
          type: string
          nullable: true
          description: >-
            Nome do usuário responsável pela movimentação (transferência ou ajuste manual de inventário). Nulo para
            movimentações geradas por venda, recebimento ou produção.
        IDPurchase:
          type: integer
          nullable: true
          description: Recebimento que originou a movimentação. Vazio quando não veio de recebimento.
        IDOrder:
          type: integer
          nullable: true
          description: Pedido de venda que originou a movimentação. Vazio quando não veio de pedido.
        IDStockKeepingUnitWarehouse:
          type: integer
          description: Armazém da movimentação.
        IDStockKeepingUnitProduction:
          type: integer
          nullable: true
          description: Ordem de produção que originou a movimentação. Vazio quando não veio de produção.
        IDOriginIDSkuMovement:
          type: integer
          nullable: true
          description: >-
            Movimentação de origem em transferências/devoluções/estornos (aponta para a movimentação espelhada). Vazio
            em movimentações originais.
        IDStockKeepingUnitInventory:
          type: integer
          nullable: true
          description: Acerto de inventário (linha individual) que originou a movimentação. Vazio quando não veio de inventário.
        IDStockKeepingUnitInventorySummary:
          type: integer
          nullable: true
          description: Inventário (cabeçalho) que originou a movimentação. Vazio quando não veio de inventário.
        Quantity:
          type: number
          description: Quantidade da movimentação atual (sempre positiva).
        ValueCost:
          type: number
          format: float
          description: Custo unitário (custo total dividido pela quantidade).
        ValueCostTotal:
          type: number
          format: float
          description: Custo total da movimentação.
        CardexQty:
          type: number
          description: >-
            Saldo acumulado **após** esta linha. Calculado como soma cumulativa de entradas (entrada com `IDStatusSku =
            1`) menos saídas, ordenado por `RecordTimestamp, IDSkuMovement`.
        CardexValueCost:
          type: number
          format: float
          description: Custo total acumulado **após** esta linha.
        CardexAverageValueCost:
          type: number
          format: float
          description: >-
            Custo médio acumulado = `CardexValueCost / CardexQty`, com duas casas decimais. `0` quando saldo acumulado é
            zero.
        Comments:
          type: string
          nullable: true
          description: Observações livres da movimentação.
        StatusInvoice:
          type: string
          nullable: true
          description: >-
            Status da NF-e associada à movimentação (`Pendente`, `Autorizada`, `Cancelada`, etc.). Vazio quando a
            movimentação não tem NF-e.
        TypeFulfillmentNonconformity:
          type: string
          nullable: true
          description: >-
            Descrição do tipo de não conformidade quando a movimentação é uma divergência (avaria, falta, divergência de
            SKU). Vazio em movimentações normais.
        IsTransfer:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: >-
            Indica se o tipo do pedido é de transferência entre centros de distribuição (`1`) ou não (`0`). Nulo quando
            a movimentação não está vinculada a um pedido.
    SkuMovementKardexLocationItem:
      type: object
      description: 'Linha do Kardex por endereço: ordena cronologicamente as movimentações de um SKU em um endereço específico.'
      properties:
        AccountName:
          type: string
          description: Subdomínio (conta) da empresa dona da movimentação.
        IDSkuMovement:
          type: integer
          description: Identificador da movimentação.
        IDSku:
          type: integer
          description: SKU movimentado.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora em que a movimentação foi registrada.
        DateCreated:
          type: string
          format: date-time
          description: Data (sem hora) do dia da movimentação — usada para agrupamento por dia no relatório.
        IDTypeMovement:
          type: integer
          enum:
            - 0
            - 1
          description: 'Tipo da movimentação: `0` Saída, `1` Entrada.'
        TypeSkuMovement:
          type: string
          enum:
            - Entrada
            - Saída
          description: 'Descrição textual do tipo: `Entrada` ou `Saída`.'
        TypeMovement:
          type: string
          nullable: true
          description: >-
            Origem da movimentação: `Recebimento`, `Venda`, `Transferência CD`, `Transferência endereço`, `Ajuste saldo
            estoque`, `Inventário`, `Produção`.
        IDPurchase:
          type: integer
          nullable: true
          description: Recebimento que originou a movimentação. Vazio quando não veio de recebimento.
        IDOrder:
          type: integer
          nullable: true
          description: Pedido de venda que originou a movimentação. Vazio quando não veio de pedido.
        IDStockKeepingUnitWarehouse:
          type: integer
          description: Armazém em que a movimentação ocorreu.
        IDStockKeepingUnitLocation:
          type: integer
          description: Endereço de armazenagem (rua/coluna/nível) movimentado.
        IDBatch:
          type: integer
          nullable: true
          description: Lote movimentado. Vazio quando o SKU não usa controle de lote.
        Quantity:
          type: number
          description: Quantidade movimentada (positiva).
        CardexQty:
          type: number
          description: Saldo acumulado no endereço após esta linha.
        Comments:
          type: string
          nullable: true
          description: Observações livres da movimentação.
        IsTransfer:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: >-
            Indica se o tipo do pedido é de transferência entre centros de distribuição (`1`) ou não (`0`). Nulo quando
            a movimentação não está vinculada a um pedido.
    SkuMovementInboundItem:
      type: object
      description: Linha de entrada (recebimento) com dados de NF-e de compra e fornecedor.
      properties:
        AccountName:
          type: string
          description: Subdomínio (conta) da empresa dona da movimentação.
        IDSkuMovement:
          type: integer
          description: Identificador da movimentação de entrada.
        IDSku:
          type: integer
          description: SKU que entrou em estoque.
        IDSkuCompany:
          type: string
          description: Código de referência interno do SKU, definido pela empresa.
        BarCode:
          type: string
          nullable: true
          description: Código de barras principal do SKU.
        IDTypeMovement:
          type: integer
          enum:
            - 0
            - 1
          description: 'Tipo da movimentação: `0` Entrada, `1` Saída. Para a modalidade `SkuInbound` o valor é `0`.'
        TypeSkuMovement:
          type: string
          enum:
            - Entrada
            - Saída
          description: 'Descrição textual do tipo: `Entrada` ou `Saída`.'
        TypeMovement:
          type: string
          nullable: true
          description: >-
            Origem da movimentação: `Recebimento`, `Venda`, `Transferência CD`, `Transferência endereço`, `Ajuste saldo
            estoque`, `Inventário`, `Produção`.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora em que a movimentação foi registrada.
        BalanceChange:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            `1` quando a movimentação altera o saldo de estoque; `0` quando é apenas registro contábil/fiscal sem efeito
            em saldo.
        Quantity:
          type: number
          description: Quantidade movimentada na entrada.
        ValueCost:
          type: number
          format: float
          description: Custo unitário da entrada (já com rateio de frete/impostos quando aplicável).
        ValueCostTotal:
          type: number
          format: float
          description: Custo total da entrada (`ValueCost × Quantity`).
        NfeIpiValue:
          type: number
          format: float
          nullable: true
          description: Valor do IPI destacado para o item na NF-e de entrada.
        NfeIcmsSTValue:
          type: number
          format: float
          nullable: true
          description: Valor do ICMS-ST destacado para o item na NF-e de entrada.
        NfeFcpSTValue:
          type: number
          format: float
          nullable: true
          description: Valor do FCP-ST destacado para o item na NF-e de entrada.
        ValueDiscount:
          type: number
          format: float
          nullable: true
          description: Valor de desconto destacado para o item na NF-e de entrada.
        NfeCFOP:
          type: string
          nullable: true
          description: CFOP do item na NF-e de entrada (4 dígitos).
        NfeNumber:
          type: integer
          nullable: true
          description: Número da NF-e de entrada.
        NfeDhEmi:
          type: string
          format: date-time
          nullable: true
          description: Data e hora de emissão da NF-e de entrada.
        IDPurchase:
          type: integer
          nullable: true
          description: >-
            Recebimento (`StockKeepingUnitPurchase`) que originou a movimentação. Vazio para entradas avulsas (acerto de
            inventário, transferência).
        InvoiceFinishTimestamp:
          type: string
          format: date-time
          nullable: true
          description: >-
            Data e hora em que o recebimento foi finalizado (estoque atualizado). Vazio enquanto o recebimento está
            aberto/em conferência.
        CheckinTimestamp:
          type: string
          format: date-time
          nullable: true
          description: Data e hora do check-in do recebimento (chegada física da carga).
        IDSupplier:
          type: integer
          nullable: true
          description: Fornecedor do recebimento. Vazio em entradas sem fornecedor (acerto, transferência interna).
        SupplierNameCorporateName:
          type: string
          nullable: true
          description: Razão social ou nome do fornecedor.
        SupplierCode:
          type: string
          nullable: true
          description: Código que o fornecedor usa para o item (extraído do XML da NF de entrada).
        NfevProd:
          type: number
          format: float
          nullable: true
          description: Valor do produto declarado no XML da NF de entrada.
        IDBatch:
          type: integer
          nullable: true
          description: Lote movimentado. Vazio quando o SKU não usa controle de lote.
        WarehouseName:
          type: string
          description: Nome do armazém de destino da entrada.
        Address:
          type: string
          nullable: true
          description: Endereço físico em que o item foi alocado.
        Comments:
          type: string
          nullable: true
          description: Observações livres da movimentação.
        Login:
          type: string
          nullable: true
          description: Login do usuário que registrou a movimentação.
    SkuMovementOutboundItem:
      type: object
      description: Linha de saída (venda) com dados de NF-e de venda e do pedido.
      properties:
        AccountName:
          type: string
          description: Subdomínio (conta) da empresa dona da movimentação.
        IDSkuMovement:
          type: integer
          description: Identificador da movimentação de saída.
        IDSku:
          type: integer
          description: SKU que saiu do estoque.
        IDSkuCompany:
          type: string
          description: Código de referência interno do SKU, definido pela empresa.
        BarCode:
          type: string
          nullable: true
          description: Código de barras principal do SKU.
        IDTypeMovement:
          type: integer
          enum:
            - 0
            - 1
          description: 'Tipo da movimentação: `0` Entrada, `1` Saída. Para a modalidade `SkuOutbound` o valor é `1`.'
        TypeSkuMovement:
          type: string
          enum:
            - Entrada
            - Saída
          description: 'Descrição textual do tipo: `Entrada` ou `Saída`.'
        TypeMovement:
          type: string
          nullable: true
          description: >-
            Origem da movimentação: `Recebimento`, `Venda`, `Transferência CD`, `Transferência endereço`, `Ajuste saldo
            estoque`, `Inventário`, `Produção`.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora em que a movimentação foi registrada.
        BalanceChange:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            `1` quando a movimentação altera o saldo de estoque; `0` quando é apenas registro contábil/fiscal sem efeito
            em saldo.
        Quantity:
          type: number
          description: Quantidade movimentada na saída.
        PriceSelling:
          type: number
          format: float
          description: Preço de venda unitário aplicado.
        PriceSellingTotal:
          type: number
          format: float
          description: Valor total da venda da linha (`PriceSelling × Quantity`).
        ValueCost:
          type: number
          format: float
          description: Custo unitário do item baixado (custo médio do SKU no momento da saída).
        ValueCostTotal:
          type: number
          format: float
          description: Custo total baixado da linha (`ValueCost × Quantity`).
        NfeCFOP:
          type: string
          nullable: true
          description: CFOP do item na NF-e de saída (4 dígitos).
        NfeNumber:
          type: integer
          nullable: true
          description: Número da NF-e de saída.
        NfeDhEmi:
          type: string
          format: date-time
          nullable: true
          description: Data e hora de emissão da NF-e de saída.
        IDStatusInvoice:
          type: integer
          nullable: true
          description: >-
            Status da NF: `0` Pendente, `1` Erro, `2` Enviada, `3` Emitida, `4` Processando, `5` Pendente Conciliação
            EPEC, `6` Erro Conciliação EPEC, `7` Cancelada, `8` Denegada, `9` Inutilizada.
        StatusInvoice:
          type: string
          nullable: true
          description: Descrição textual do status da NF-e (referente a `IDStatusInvoice`).
        IDOrder:
          type: integer
          nullable: true
          description: Pedido de venda que originou a saída. Vazio para saídas avulsas.
        Order:
          type: string
          nullable: true
          description: Código externo do pedido (número visível ao cliente).
        OrderFrom:
          type: string
          nullable: true
          description: Origem do pedido (canal/marketplace ou loja física).
        IDStatusOrder:
          type: integer
          nullable: true
          description: 'Status do pedido (referência: `TypeStatusOrder`).'
        StatusOrder:
          type: string
          nullable: true
          description: Descrição amigável do status do pedido.
        TypeOrder:
          type: string
          nullable: true
          description: Descrição do tipo do pedido (venda, devolução, transferência, etc.).
        IDCompanyIntegration:
          type: integer
          nullable: true
          description: Integração (canal de venda) do pedido.
        CompanyIntegration:
          type: string
          nullable: true
          description: Nome da integração (canal de venda).
        CompanyInvoiceNameCorporateName:
          type: string
          nullable: true
          description: Razão social da filial faturadora do pedido.
        IDCompanyInvoice:
          type: integer
          nullable: true
          description: Identificador da filial faturadora do pedido.
        ConsumerNameCorporateName:
          type: string
          nullable: true
          description: Razão social ou nome do cliente do pedido.
        ConsumerCpfCnpj:
          type: string
          nullable: true
          description: CPF/CNPJ do cliente do pedido.
        ConsumerEmail:
          type: string
          nullable: true
          description: E-mail do cliente do pedido.
        ShippingState:
          type: string
          nullable: true
          description: UF de entrega do pedido (sigla com 2 letras).
        IDTypeFulfillmentNonconformity:
          type: integer
          nullable: true
          description: >-
            Tipo da não conformidade da movimentação (avaria, falta, divergência de SKU). Vazio em movimentações
            normais.
          enum:
            - 1
            - 2
            - 4
            - 5
            - 6
        TypeFulfillmentNonconformity:
          type: string
          nullable: true
          description: Descrição amigável da não conformidade.
        QuantityNonconformity:
          type: number
          nullable: true
          description: Quantidade registrada como não conformidade na movimentação.
        IDBatch:
          type: integer
          nullable: true
          description: Lote baixado. Vazio quando o SKU não usa controle de lote.
        WarehouseName:
          type: string
          description: Nome do armazém de origem da saída.
        Address:
          type: string
          nullable: true
          description: Endereço (rua/coluna/nível) de onde o SKU foi separado.
        Comments:
          type: string
          nullable: true
          description: Observações livres da movimentação.
        Login:
          type: string
          nullable: true
          description: Login do usuário que registrou a movimentação.
        IsTransfer:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: >-
            Indica se o tipo do pedido é de transferência entre centros de distribuição (`1`) ou não (`0`). Nulo quando
            a movimentação não está vinculada a um pedido.
    SkuMovementFiscalConciliationItem:
      type: object
      description: >-
        Linha da árvore de lotes consolidada (CTE recursiva). Para cada lote origem mostra movimentações descendentes e
        o saldo líquido.
      properties:
        IDSkuMovement:
          type: integer
          description: Identificador da movimentação de estoque conciliada com a nota fiscal.
        IDPurchase:
          type: integer
          nullable: true
          description: >-
            Recebimento (`StockKeepingUnitPurchase`) que originou a movimentação. Vazio para movimentações de saída ou
            avulsas.
        IDSku:
          type: integer
          description: SKU movimentado.
        IDBatch:
          type: integer
          nullable: true
          description: Lote movimentado. Vazio quando o SKU não usa controle de lote.
        IDTypeMovement:
          type: integer
          enum:
            - 0
            - 1
          description: 'Tipo da movimentação para conciliação fiscal: `0` Saída, `1` Entrada.'
        IDOriginIDSkuMovement:
          type: integer
          nullable: true
          description: >-
            Movimentação de origem em casos de transferência/devolução/estorno (aponta para a movimentação espelhada).
            Vazio em movimentações originais.
        BatchPath:
          type: string
          description: 'Caminho da árvore de lotes, ex.: `100>120>135`.'
        Quantity:
          type: number
          description: Quantidade movimentada (positiva).
        IDOrder:
          type: integer
          nullable: true
          description: Pedido de venda associado à saída. Vazio para entradas e movimentações sem pedido.
        IDBatchOrigin:
          type: integer
          description: Lote raiz (recebimento original).
        BalanceChange:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            `1` quando a movimentação altera o saldo de estoque; `0` quando é apenas registro fiscal sem efeito em
            saldo.
        dhEmi:
          type: string
          format: date-time
          nullable: true
          description: Data de emissão da NF-e do recebimento original.
        nNF:
          type: integer
          nullable: true
          description: Número da NF-e do recebimento original.
        chNFe:
          type: string
          nullable: true
          description: Chave de acesso da NF-e do recebimento original.
        InvoiceFinishTimestamp:
          type: string
          format: date-time
          nullable: true
          description: >-
            Data e hora da finalização da NF-e que conciliou esta movimentação. Vazio enquanto a NF-e não está
            conciliada.
        BalanceQuantity:
          type: number
          description: Quantidade líquida do lote (entradas menos saídas).
    SkuMovementTransferBody:
      type: object
      description: >-
        Corpo da requisição de transferência. A transferência pode ser **entre armazéns** (use
        `IDStockKeepingUnitWarehouseFrom` + `IDStockKeepingUnitWarehouseTo`) ou **entre lotes/endereços** (use
        `IDBatchFrom` + `IDBatchTo` ou `IDStockKeepingUnitLocationTo`). Origem e destino precisam estar no mesmo Centro
        de Distribuição.
      required:
        - IDSku
        - Quantity
      properties:
        IDSku:
          type: integer
          description: >-
            SKU a ser transferido. Precisa ser do tipo Sku (`IDTypeSku = 3`), Matéria-prima (`6`) ou Uso e consumo
            (`7`).
        Quantity:
          type: number
          description: Quantidade a transferir. Precisa ser maior que zero.
        IDStockKeepingUnitWarehouseFrom:
          type: integer
          description: Armazém de origem (transferência entre armazéns).
        IDStockKeepingUnitWarehouseTo:
          type: integer
          description: Armazém de destino (transferência entre armazéns).
        IDBatchFrom:
          type: integer
          description: Lote de origem (transferência entre lotes/endereços).
        IDBatchTo:
          type: integer
          description: >-
            Lote de destino (transferência entre lotes/endereços). Quando ausente, o sistema procura um lote compatível
            no endereço de destino — ou cria um novo se nenhum bate.
        IDStockKeepingUnitLocationTo:
          type: integer
          description: >-
            Endereço físico de destino (alternativa a `IDBatchTo`). Combinado com `IDBatchFrom`, o sistema escolhe ou
            cria o lote de destino conforme as parametrizações `KeepUniqueBatchForFiscalConciliation` e
            `AllowSameItemDifferentBatchSameLocation`.
        Comments:
          type: string
          nullable: true
          description: Comentário livre que fica gravado nas duas movimentações geradas.
    SkuMovementTransferResponseItem:
      type: object
      description: >-
        Linha de movimentação criada pela transferência, com dados do lote. A resposta vem como array com duas linhas
        (saída + entrada).
      properties:
        IDSkuMovement:
          type: integer
          description: >-
            Identificador da movimentação gerada pela transferência (uma linha de saída na origem e uma de entrada no
            destino — este objeto descreve uma delas).
        IDSku:
          type: integer
          description: SKU transferido.
        IDTypeMovement:
          type: integer
          enum:
            - 0
            - 1
          description: 'Tipo da movimentação: `0` Saída (perna de saída da origem), `1` Entrada (perna de entrada no destino).'
        IDStatusSku:
          type: integer
          description: 'Status do SKU na movimentação (referência: `TypeStatusSku`).'
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
        Quantity:
          type: number
          description: Quantidade transferida.
        ValueCostTotal:
          type: number
          format: float
          description: Custo total da movimentação transferida (preserva o custo médio da origem).
        IDStockKeepingUnitWarehouse:
          type: integer
          description: Armazém da movimentação (origem na perna de saída, destino na perna de entrada).
        IDBatch:
          type: integer
          nullable: true
          description: Lote transferido. Vazio quando o SKU não usa controle de lote.
        IDOriginIDSkuMovement:
          type: integer
          nullable: true
          description: >-
            Movimentação espelhada — na perna de entrada aponta para a movimentação de saída correspondente; vazio na
            perna de saída.
        Comments:
          type: string
          nullable: true
          description: Observações livres da transferência.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora em que a movimentação foi registrada.
        IDStockKeepingUnitLocation:
          type: integer
          nullable: true
          description: Endereço (rua/coluna/nível) movimentado.
        BestBeforeDate:
          type: string
          format: date
          nullable: true
          description: >-
            Data de validade do lote movimentado, no formato `YYYY-MM-DD`. Vazio quando o SKU não usa controle de
            validade.
        ManufacturingDate:
          type: string
          format: date
          nullable: true
          description: >-
            Data de fabricação do lote movimentado, no formato `YYYY-MM-DD`. Vazio quando o SKU não usa controle de
            lote.
    SkuMovementTransferBatchResponseItem:
      type: object
      description: >-
        Detalhamento de lote retornado quando `BatchResponse=1`. Lista todos os lotes ativos do SKU após a
        transferência, com endereço, saldo e quantidade disponível.
      properties:
        AccountName:
          type: string
          description: Subdomínio (conta) da empresa dona do lote transferido.
        IDBatchNumber:
          type: integer
          description: Identificador do lote transferido.
        IDSku:
          type: integer
          description: SKU do lote transferido.
        IDSkuCompany:
          type: string
          description: Código de referência interno do SKU, definido pela empresa.
        SkuName:
          type: string
          description: Nome do SKU.
        BarCode:
          type: string
          nullable: true
          description: Código de barras principal do SKU.
        IDStockKeepingUnitLocation:
          type: integer
          description: Endereço de destino do lote após a transferência.
        Address:
          type: string
          description: Texto do endereço de destino (`Floor-Street-Module-Column-Level` ou nome livre).
        IDStockKeepingUnitWarehouse:
          type: integer
          description: Armazém de destino do lote.
        WarehouseName:
          type: string
          description: Nome do armazém de destino.
        IDStockKeepingUnitDistributionCenter:
          type: integer
          description: Centro de distribuição a que pertence o armazém de destino.
        DistributionCenterName:
          type: string
          description: Nome do centro de distribuição.
        BestBeforeDate:
          type: string
          format: date
          nullable: true
          description: Data de validade do lote, no formato `YYYY-MM-DD`. Vazio quando o SKU não usa controle de validade.
        ManufacturingDate:
          type: string
          format: date
          nullable: true
          description: Data de fabricação do lote, no formato `YYYY-MM-DD`. Vazio quando o SKU não usa controle de lote.
        Comments:
          type: string
          nullable: true
          description: Identificação textual do lote (código impresso no produto) ou observações livres.
        Default:
          type: integer
          description: '`1` quando é o lote padrão do endereço.'
          enum:
            - 0
            - 1
        BatchBalance:
          type: number
          description: Saldo do lote (entradas que mexem o saldo menos saídas).
        IDBatchStatus:
          type: integer
          description: '`1` quando há saldo, `0` quando o lote está zerado.'
          enum:
            - 0
            - 1
        BatchStatus:
          type: string
          enum:
            - Ativo
            - Inativo
          description: >-
            Status do lote após a transferência: `Ativo` (lote ainda visível para movimentação) ou `Inativo` (lote
            zerado/ocultado).
        QtyAvailable:
          type: number
          description: Saldo disponível total do SKU no armazém em que está o lote.
        MainImageURL:
          type: string
          nullable: true
          description: URL da imagem principal do SKU.
        MainImageThumbnailURL:
          type: string
          nullable: true
          description: URL da miniatura da imagem principal.
        AbcCurve:
          type: string
          nullable: true
          description: Classificação ABC do SKU (`A`, `B`, `C`).
        DateLastSell:
          type: string
          format: date-time
          nullable: true
          description: Data da última venda do SKU. Vazio quando o SKU nunca foi vendido.
        IDTypeAddress:
          type: integer
          nullable: true
          description: 'Tipo de endereço de armazenagem: `1` Picking, `2` Pulmão, `3` Blocado.'
          enum:
            - 1
            - 2
            - 3
        TypeAddress:
          type: string
          nullable: true
          description: Descrição amigável do tipo de endereço.
        IDStockKeepingUnitLocationCategory:
          type: integer
          nullable: true
          description: Categoria do endereço de destino (agrupamento configurável).
        StockKeepingUnitLocationCategoryName:
          type: string
          nullable: true
          description: Nome da categoria do endereço.
        IDStockKeepingUnitLocationGroup:
          type: integer
          nullable: true
          description: Grupo de endereços ao qual o endereço de destino pertence.
        IDTypeSku:
          type: integer
          description: >-
            Tipo do SKU: `1` Clube, `2` Kit, `3` Sku (produto normal), `4` Produto com variação, `5` Serviço, `6`
            Matéria-prima, `7` Uso e consumo, `8` Caixa fechada.
        Batch:
          type: integer
          description: '`1` quando o SKU usa controle de lote rastreável.'
          enum:
            - 0
            - 1
    SkuCostRecalculateAcceptedResponse:
      type: object
      description: Resposta da fila assíncrona — o recálculo é despachado para processamento em segundo plano.
      properties:
        status:
          type: string
          example: accepted
          description: >-
            Status textual do enfileiramento — `accepted` quando o job de recálculo de custo foi enviado para
            processamento assíncrono.
        message:
          type: string
          nullable: true
          description: Mensagem complementar do gateway assíncrono (geralmente vazia ou com identificador do job).
    InventoryAdjustmentItem:
      type: object
      description: >-
        Item de um lançamento de ajuste de saldo via `POST /sku/inventory`. O sistema aplica a regra `entrada/saída`
        automaticamente comparando `QuantityInventory` contra o saldo do lote, exceto quando `IDMovementType` força a
        direção.
      required:
        - IDStockKeepingUnitWarehouse
        - IDSku
        - QuantityInventory
      properties:
        IDStockKeepingUnitWarehouse:
          type: integer
          description: Armazém onde o ajuste é feito. Precisa estar ativo (`Status = 1`) e pertencer à empresa autenticada.
        IDSku:
          type: integer
          description: SKU a ajustar. Precisa ser do tipo Sku, Matéria-prima ou Uso e consumo (`IDTypeSku IN (3, 6, 7)`).
        QuantityInventory:
          type: number
          description: >-
            Quantidade contada (saldo desejado para o lote). O sistema calcula a diferença em relação ao saldo atual do
            lote e cria uma movimentação de entrada (`IDTypeMovement = 0`) ou saída (`IDTypeMovement = 1`).
        IDBatchNumber:
          type: integer
          description: >-
            Lote específico a ajustar. Quando omitido, o sistema usa o lote padrão do SKU no armazém — quando o SKU não
            tem lote nenhum, cria automaticamente um lote no endereço padrão (`Principal`).
        Comments:
          type: string
          description: Texto livre justificando o ajuste (auditoria, perda, achado, etc.). Gravado na movimentação.
        IDStockKeepingUnitLocation:
          type: integer
          description: Endereço opcional (informativo).
        IDMovementType:
          type: integer
          enum:
            - 0
            - 1
            - 3
          description: >-
            Força a direção do ajuste: `0` entrada explícita (soma `QuantityInventory` ao saldo), `1` saída explícita
            (subtrai `QuantityInventory`), `3` ajuste pela diferença entre `QuantityInventory` e o saldo disponível
            atual do SKU (`QtyAvailable`). Quando omitido, compara contra o saldo do lote e calcula a diferença
            automaticamente.
    InventoryAdjustmentError:
      type: object
      description: >-
        Falha individual em um lançamento de ajuste. Quando o body é array, cada erro é acumulado nesta lista e o
        restante das linhas continua sendo processado.
      properties:
        SkuName:
          type: string
          nullable: true
          description: >-
            Nome do SKU cujo ajuste de estoque falhou durante o processamento — o sistema retorna este objeto na lista
            de erros quando o lançamento de movimentação para o SKU não pôde ser persistido.
        IDSkuCompany:
          type: string
          nullable: true
          description: Código de referência do SKU na empresa.
        Description:
          type: string
          description: >-
            Causa do erro. Valores conhecidos: `Sku não cadastrado`, `Item não é do tipo SKU`, `Quantidade para ajustar
            saldo não é um número`, `Armazém não cadastrado`, `Lote não encontrado`, `Lote não pertence ao armazém`,
            `Lote está inativo`.
        Status:
          type: integer
          enum:
            - 0
          description: Sempre `0` (falha).
    InventoryHistoryItem:
      type: object
      description: >-
        Linha do histórico de ajustes (`StockKeepingUnitInventory` + movimentação relacionada). Cada linha representa um
        ajuste lançado pela tela Inventário.
      properties:
        IDStockKeepingUnitInventory:
          type: integer
          description: Código do ajuste.
        AccountName:
          type: string
          description: Conta (subdomínio) da empresa.
        IDSku:
          type: integer
          description: Identificador do SKU.
        SkuName:
          type: string
          description: Nome do SKU.
        IDSkuCompany:
          type: string
          description: Código de referência do SKU.
        Barcode:
          type: string
          nullable: true
          description: Código de barras principal.
        Quantity:
          type: number
          description: Quantidade contada que foi lançada.
        IDStockKeepingUnitWarehouse:
          type: integer
          description: Depósito da movimentação.
        WarehouseName:
          type: string
          description: Nome do depósito.
        IDBatch:
          type: integer
          nullable: true
          description: Código do lote ajustado.
        Comments:
          type: string
          nullable: true
          description: Comentário informado no lançamento.
        Login:
          type: string
          description: Login do usuário que fez o ajuste.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data/hora do lançamento.
        IDSkuMovement:
          type: integer
          description: Movimentação de estoque (`StockKeepingUnitMovement`) gerada pelo ajuste.
    StockBalanceItem:
      type: object
      description: Saldo consolidado de um SKU em um armazém, com as quantidades nas várias situações e o valor em estoque.
      properties:
        IDStockKeepingUnitWarehouseBalance:
          type: string
          description: >-
            Chave composta `IDStockKeepingUnitWarehouse-IDSku` (usada como `KeyTable` na tela). Não persiste em banco —
            é gerada pelo sistema.
        IDStockKeepingUnitWarehouse:
          type: integer
          description: Identificador do depósito.
        WarehouseName:
          type: string
          description: Nome do depósito.
        IDTypeStockKeepingUnitWarehouse:
          $ref: '#/components/schemas/TypeStockKeepingUnitWarehouseEnum'
          description: >-
            Natureza do depósito: `1` Saudável, `2` Divergência, `3` Quarentena, `4` Recebimento, `5` Falta, `6`
            Vencido, `7` Auditoria, `8` Avaria, `9` Devolução, `10` Ressuprimento, `11` Outlet.
        TypeStockKeepingUnitWarehouse:
          type: string
          description: Descrição textual do tipo de armazém.
        AccountName:
          type: string
          description: Conta (subdomínio) da empresa.
        IDSku:
          type: integer
          description: Identificador do SKU.
        IDSkuCompany:
          type: string
          description: Código de referência do SKU.
        SkuName:
          type: string
          description: Nome do SKU.
        DateLastRecordModification:
          type: string
          format: date-time
          nullable: true
          description: Última modificação do cadastro do SKU.
        QtyAvailable:
          type: number
          description: >-
            Saldo disponível para venda (usa a quantidade ajustada quando configurada; caso contrário, a quantidade
            natural).
        InventoryValue:
          type: number
          description: >-
            Valor total do estoque disponível (custo × quantidade disponível). Usa o custo manual quando a empresa está
            configurada para custo fixo (`UseCostFromCostSet = 1`); caso contrário, o custo apurado.
        CostAverage:
          type: number
          description: >-
            Custo médio do SKU no armazém. Usa o custo manual quando `UseCostFromCostSet = 1`; caso contrário, o valor
            total em estoque dividido pela quantidade disponível.
        QtyReserved:
          type: number
          description: Quantidade reservada em pedidos ainda abertos.
        QtyProduction:
          type: number
          description: Quantidade em ordens de produção iniciadas ou em andamento.
        QtyBuyOrdem:
          type: number
          description: Quantidade em pedidos de compra ainda abertos (não cancelados nem concluídos).
        QtyToReceipt:
          type: number
          description: Quantidade em recebimentos ainda pendentes.
        QtyHandling:
          type: number
          description: Quantidade em manuseio — itens de pedidos já em separação/expedição com saída de estoque pendente.
        QtyOnStock:
          type: number
          description: 'Estoque físico calculado pelo sistema: `QtyAvailable + QtyReserved + QtyHandling`.'
    SkuSupplierLink:
      type: object
      description: Vínculo entre um SKU e um fornecedor.
      properties:
        IDStockKeepingUnitSuplierCode:
          type: integer
          description: Identificador do vínculo.
        IDSupplier:
          type: integer
          description: Identificador do fornecedor.
        SupplierNameCorporateName:
          type: string
          description: Nome / razão social do fornecedor.
        SupplierCode:
          type: string
          description: Código do produto no fornecedor (o que aparece na nota fiscal dele).
          nullable: true
        QuantityMultiply:
          type: number
          description: 'Multiplicador: unidades do produto que correspondem a uma unidade comprada do fornecedor.'
        PackageSize:
          type: integer
          description: Embalagem do fornecedor.
          nullable: true
        LastValueCost:
          type: number
          description: Custo de tabela informado pelo fornecedor.
          nullable: true
        PisAliquotInbound:
          type: number
          description: 'Alíquota de PIS de entrada em fração decimal (ex.: `0.0165` = 1,65%).'
          nullable: true
        CofinsAliquotInbound:
          type: number
          description: 'Alíquota de COFINS de entrada em fração decimal (ex.: `0.076` = 7,6%).'
          nullable: true
    SkuSupplierListItem:
      type: object
      description: >-
        Linha da lista consolidada de fornecedores e SKUs: dados do produto somados aos dados do vínculo com o
        fornecedor.
      properties:
        IDSku:
          type: integer
          description: Identificador do produto (SKU).
        IDStockKeepingUnitSuplierCode:
          type: integer
          description: Identificador do vínculo SKU-fornecedor.
        SkuName:
          type: string
          description: Nome do produto. Para variações, vem prefixado com o nome do produto-pai.
          nullable: true
        IDSkuCompany:
          type: string
          description: Código de referência do produto (código interno da empresa).
          nullable: true
        BarCode:
          type: string
          description: Código de barras do produto.
          nullable: true
        Category:
          type: string
          description: Nome da categoria do produto.
          nullable: true
        IDCategory:
          type: integer
          description: Identificador da categoria.
          nullable: true
        Brand:
          type: string
          description: Nome da marca do produto.
          nullable: true
        IDBrand:
          type: integer
          description: Identificador da marca.
          nullable: true
        AccountName:
          type: string
          description: Conta dona do produto.
        Package:
          type: integer
          description: Indica se o produto é uma embalagem (`1`) ou não (`0`).
        Batch:
          type: integer
          description: Indica se o produto é controlado por lote (`1`) ou não (`0`).
        OwnProduction:
          type: integer
          description: Indica produção própria (`1`) ou não (`0`).
        SkuNCM:
          type: string
          description: NCM do produto.
          nullable: true
        SkuCest:
          type: string
          description: CEST do produto.
          nullable: true
        IDTaxDepartment:
          type: integer
          description: Identificador do departamento fiscal.
          nullable: true
        CostAverage:
          type: number
          description: >-
            Custo médio do produto. Reflete o custo manual quando a parametrização "Utilizar custo manual SKU" está
            ativa.
          nullable: true
        CostLastPurchase:
          type: number
          description: >-
            Custo da última compra. Reflete o custo manual quando a parametrização "Utilizar custo manual SKU" está
            ativa.
          nullable: true
        SupplierCode:
          type: string
          description: Código do produto no fornecedor.
          nullable: true
        IDSupplier:
          type: integer
          description: Identificador do fornecedor.
        SupplierNameCorporateName:
          type: string
          description: Nome / razão social do fornecedor.
        SupplierProductReliability:
          type: integer
          description: Confiabilidade do fornecedor para o produto.
          nullable: true
        SupplierProductLeadTimeDays:
          type: integer
          description: Prazo de entrega do fornecedor, em dias.
          nullable: true
        QuantityMultiply:
          type: number
          description: Multiplicador do vínculo.
        PackageSize:
          type: integer
          description: Embalagem do fornecedor.
          nullable: true
        LastValueCost:
          type: number
          description: Custo de tabela informado pelo fornecedor.
          nullable: true
        PisAliquotInbound:
          type: number
          description: Alíquota de PIS de entrada (fração decimal).
          nullable: true
        CofinsAliquotInbound:
          type: number
          description: Alíquota de COFINS de entrada (fração decimal).
          nullable: true
        SkuHeight:
          type: number
          description: Altura do produto.
          nullable: true
        SkuLength:
          type: number
          description: Comprimento do produto.
          nullable: true
        SkuWidth:
          type: number
          description: Largura do produto.
          nullable: true
        SkuWeight:
          type: number
          description: Peso do produto.
          nullable: true
        AbcCurve:
          type: string
          description: Curva ABC do produto (`A`, `B` ou `C`).
          nullable: true
        InfiniteInventory:
          type: integer
          description: Indica estoque infinito (`1`) ou não (`0`).
        QtySafetyStock:
          type: number
          description: Estoque de segurança do produto.
          nullable: true
        QtyAvailable:
          type: number
          description: Quantidade disponível em estoque (calculada).
        PriceSell:
          type: number
          description: Preço de venda vigente do produto.
          nullable: true
        PriceList:
          type: number
          description: Preço de tabela (lista) vigente do produto.
          nullable: true
        IDProduct:
          type: integer
          description: Identificador do produto-pai, quando o SKU é uma variação.
          nullable: true
        MainImageURL:
          type: string
          description: URL da imagem principal do produto.
          nullable: true
        MainImageThumbnailURL:
          type: string
          description: URL da miniatura da imagem principal.
          nullable: true
    SkuSupplierCreate:
      type: object
      required:
        - IDSupplier
        - QuantityMultiply
        - SupplierCode
      properties:
        IDSupplier:
          type: integer
          description: Fornecedor a vincular. Deve existir na conta autenticada.
        QuantityMultiply:
          type: number
          description: 'Multiplicador: unidades do produto que correspondem a uma unidade comprada do fornecedor.'
        SupplierCode:
          type: string
          description: >-
            Código do produto no fornecedor (o que aparece na nota fiscal dele). A combinação SKU + fornecedor + código
            não pode se repetir.
        PackageSize:
          type: integer
          description: Embalagem do fornecedor. `0` ou vazio é tratado como nulo.
          nullable: true
        LastValueCost:
          type: number
          description: Custo de tabela informado pelo fornecedor.
          nullable: true
        PisAliquotInbound:
          type: number
          description: >-
            Alíquota de PIS de entrada em fração decimal (ex.: `0.0165` = 1,65%). Usada no cálculo do custo na entrada
            da nota fiscal quando a parametrização "Subtrair PIS custo" está ativa.
          nullable: true
        CofinsAliquotInbound:
          type: number
          description: >-
            Alíquota de COFINS de entrada em fração decimal (ex.: `0.076` = 7,6%). Usada no cálculo do custo na entrada
            da nota fiscal quando a parametrização "Subtrair Cofins custo" está ativa.
          nullable: true
    SkuSupplierUpdate:
      type: object
      description: 'Atualização parcial do vínculo: cada campo é alterado apenas quando enviado.'
      properties:
        IDSupplier:
          type: integer
          description: Fornecedor a vincular. Deve existir na conta autenticada.
        QuantityMultiply:
          type: number
          description: 'Multiplicador: unidades do produto que correspondem a uma unidade comprada do fornecedor.'
        SupplierCode:
          type: string
          description: >-
            Código do produto no fornecedor (o que aparece na nota fiscal dele). A combinação SKU + fornecedor + código
            não pode se repetir.
        PackageSize:
          type: integer
          description: Embalagem do fornecedor. `0` ou vazio é tratado como nulo.
          nullable: true
        LastValueCost:
          type: number
          description: Custo de tabela informado pelo fornecedor.
          nullable: true
        PisAliquotInbound:
          type: number
          description: >-
            Alíquota de PIS de entrada em fração decimal (ex.: `0.0165` = 1,65%). Usada no cálculo do custo na entrada
            da nota fiscal quando a parametrização "Subtrair PIS custo" está ativa.
          nullable: true
        CofinsAliquotInbound:
          type: number
          description: >-
            Alíquota de COFINS de entrada em fração decimal (ex.: `0.076` = 7,6%). Usada no cálculo do custo na entrada
            da nota fiscal quando a parametrização "Subtrair Cofins custo" está ativa.
          nullable: true
    UserListItem:
      type: object
      description: Item da listagem de `GET /user`.
      properties:
        IDUser:
          type: integer
          format: int32
          description: Identificador do usuário.
        UserName:
          type: string
          description: Nome do usuário.
        Login:
          type: string
          description: Login (e-mail real ou login interno gerado a partir do documento).
        UserImageUrl:
          type: string
          nullable: true
          description: URL da foto de perfil.
        Privileges:
          type: string
          nullable: true
          description: Perfis de acesso vinculados, concatenados (nomes separados por vírgula).
        LastLogin:
          type: string
          nullable: true
          description: Data/hora do último acesso.
          format: date-time
        Salesman:
          type: integer
          enum:
            - 0
            - 1
          description: 1 = é vendedor.
        RestrictAccessSalesman:
          type: integer
          enum:
            - 0
            - 1
          description: 1 = vendedor só enxerga as próprias vendas.
        DiscountPercentLimit:
          type: number
          nullable: true
          description: Limite de desconto (%) padrão do vendedor.
        UserCpfCnpj:
          type: string
          nullable: true
          description: CPF/CNPJ do usuário (somente dígitos).
        UserTelephone:
          type: string
          nullable: true
          description: Telefone.
        UserExtenalId:
          type: string
          nullable: true
          description: Código externo (integração).
        MFAEnabled:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: 1 = autenticação em dois fatores ativada.
        StatusNameUser:
          type: string
          description: Descrição do status do vínculo (Ativo/Inativo).
        AccountName:
          type: string
          description: Subdomínio da conta.
    UserDetail:
      type: object
      description: >-
        Detalhe completo do usuário. Resposta de `GET /user/{iduser}` e das operações de criação/edição/vínculos (que
        devolvem o usuário atualizado).
      properties:
        IDUser:
          type: integer
          format: int32
          description: Identificador do usuário.
        IDAcess:
          type: integer
          format: int32
          description: Identificador do vínculo do usuário com a empresa.
        Login:
          type: string
          description: Login do usuário.
        UserName:
          type: string
          description: Nome do usuário.
        UserCpfCnpj:
          type: string
          nullable: true
          description: CPF/CNPJ (somente dígitos).
        UserTelephone:
          type: string
          nullable: true
          description: Telefone.
        UserExtenalId:
          type: string
          nullable: true
          description: Código externo (integração).
        UserImageUrl:
          type: string
          nullable: true
          description: URL da foto de perfil.
        AccountName:
          type: string
          description: Subdomínio da conta.
        Status:
          type: integer
          enum:
            - 0
            - 1
          description: 'Status do vínculo: 1 = ativo, 0 = inativo.'
        LastLogin:
          type: string
          nullable: true
          description: Data/hora do último acesso.
          format: date-time
        LastPasswordChange:
          type: string
          nullable: true
          description: Data/hora da última troca de senha.
          format: date-time
        MFAEnabled:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: 1 = autenticação em dois fatores ativada.
        MFAType:
          type: string
          nullable: true
          enum:
            - email
            - totp
            - null
          description: >-
            Tipo de autenticação em dois fatores: `email` (código por e-mail) ou `totp` (app autenticador). `null`
            desativa.
        IDModuleFavorite:
          type: integer
          format: int32
          nullable: true
          description: Módulo favorito (tela inicial) do usuário.
        IDUserJobPositionList:
          type: string
          nullable: true
          description: IDs dos cargos do usuário, separados por vírgula.
        Salesman:
          type: integer
          enum:
            - 0
            - 1
          description: 1 = é vendedor.
        RestrictAccessSalesman:
          type: integer
          enum:
            - 0
            - 1
          description: 1 = vendedor só enxerga as próprias vendas.
        DiscountPercentLimit:
          type: number
          nullable: true
          description: Limite de desconto (%) padrão do vendedor.
        IDTypeSalesmanCommission:
          type: integer
          format: int32
          nullable: true
          description: >-
            Forma de liberação da comissão: 1 = parcial vinculada às parcelas, 2 = integral no faturamento, 3 = integral
            após pagamento da 1ª parcela, 4 = integral após pagamento da última parcela.
          enum:
            - 1
            - 2
            - 3
            - 4
        TypeSalesmanCommission:
          type: string
          nullable: true
          description: Descrição da forma de liberação da comissão.
        ExcludeCanceledOrdersCommission:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: 1 = pedidos cancelados não entram na comissão.
        ExcludeReturnedOrdersCommission:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: 1 = pedidos devolvidos não entram na comissão.
        Technician:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: 1 = usuário é técnico.
        UserJobPositionList:
          type: array
          description: Cargos do usuário.
          items:
            type: object
            properties:
              IDUserJobPosition:
                type: integer
                format: int32
                description: Identificador do cargo.
              UserJobPositionName:
                type: string
                description: Nome do cargo.
        UserPrivilegeGroup:
          type: array
          description: Perfis de acesso vinculados ao usuário.
          items:
            type: object
            properties:
              IDUserPrivilegeGroup:
                type: integer
                format: int32
                description: Identificador do perfil de acesso.
              PrivilegeGroupName:
                type: string
                description: Nome do perfil de acesso.
        SalesmanComission:
          type: array
          description: Regras de comissão do vendedor.
          items:
            type: object
            properties:
              IDSalesmanComission:
                type: integer
                format: int32
                description: Identificador da regra.
              RecordTimestamp:
                type: string
                description: Data/hora de criação da regra.
                format: date-time
              DateFrom:
                type: string
                nullable: true
                description: Início da vigência.
                format: date
              DateTo:
                type: string
                nullable: true
                description: Fim da vigência.
                format: date
              DiscountPercentLimit:
                type: number
                nullable: true
                description: Limite de desconto (%) para a regra valer.
              ComissionPercent:
                type: number
                nullable: true
                description: Percentual de comissão.
              IDCategory:
                type: integer
                format: int32
                nullable: true
                description: Categoria de produto à qual a regra se aplica (quando preenchida).
              Category:
                type: string
                nullable: true
                description: Nome da categoria.
              AccountName:
                type: string
                description: Subdomínio da conta.
        UserCompanyInvoice:
          type: array
          description: Empresas/filiais faturadoras que o usuário pode operar.
          items:
            type: object
            properties:
              IDUserCompanyInvoice:
                type: integer
                format: int32
                description: Identificador do vínculo.
              IDCompany:
                type: integer
                format: int32
                description: Identificador da empresa/filial faturadora.
              AccountName:
                type: string
                description: Subdomínio da filial.
              CompanyCpfCnpj:
                type: string
                nullable: true
                description: CPF/CNPJ da filial.
              CompanyNameCorporateName:
                type: string
                nullable: true
                description: Razão social da filial.
        UserCompanyDistributionCenter:
          type: array
          description: Centros de distribuição que o usuário pode operar.
          items:
            type: object
            properties:
              IDUserCompanyDistributionCenter:
                type: integer
                format: int32
                description: Identificador do vínculo.
              IDStockKeepingUnitDistributionCenter:
                type: integer
                format: int32
                description: Identificador do centro de distribuição.
              DistributionCenterName:
                type: string
                nullable: true
                description: Nome do centro de distribuição.
              AccountName:
                type: string
                description: Subdomínio da conta.
        UserCompanySupplierCategory:
          type: array
          description: Categorias de fornecedor que o usuário pode operar.
          items:
            type: object
            properties:
              IDUserCompanySupplierCategory:
                type: integer
                format: int32
                description: Identificador do vínculo.
              IDSupplierCategory:
                type: integer
                format: int32
                description: Identificador da categoria de fornecedor.
              CategoryDescription:
                type: string
                nullable: true
                description: Nome da categoria de fornecedor.
              AccountName:
                type: string
                description: Subdomínio da conta.
        UserLog:
          type: array
          description: Auditoria de alterações no cadastro do usuário (mais recente primeiro).
          items:
            type: object
            properties:
              IDUserLog:
                type: integer
                format: int32
                description: Identificador do registro de log.
              RecordTimestamp:
                type: string
                description: Data/hora da alteração.
                format: date-time
              RecordUserCreated:
                type: integer
                format: int32
                nullable: true
                description: Identificador do usuário que fez a alteração.
              Login:
                type: string
                nullable: true
                description: Login de quem fez a alteração.
              Data:
                type: string
                description: Descrição da alteração (DE/PARA dos campos).
        LoginLog:
          type: array
          description: Histórico de acessos do usuário (mais recente primeiro).
          items:
            type: object
            properties:
              IDUserLogin:
                type: integer
                format: int32
                description: Identificador do acesso.
              Login:
                type: string
                description: Login utilizado no acesso.
              RecordTimestamp:
                type: string
                description: Data/hora do acesso.
                format: date-time
              IP:
                type: string
                nullable: true
                description: Endereço de origem do acesso.
              AccountName:
                type: string
                description: Subdomínio da conta.
    UserCreate:
      type: object
      description: Corpo de `POST /user`. Obrigatório `UserName` e pelo menos um de `Login` ou `UserCpfCnpj`.
      required:
        - UserName
      properties:
        UserName:
          type: string
          description: Nome do usuário.
        Login:
          type: string
          nullable: true
          description: E-mail de login. Se omitido, o sistema gera um login interno a partir do documento.
        UserCpfCnpj:
          type: string
          nullable: true
          description: CPF/CNPJ do usuário. Obrigatório quando `Login` não é informado.
        UserTelephone:
          type: string
          nullable: true
          description: Telefone.
        UserExtenalId:
          type: string
          nullable: true
          description: Código externo (integração).
        MFAEnabled:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: 1 = ativa autenticação em dois fatores.
        MFAType:
          type: string
          nullable: true
          enum:
            - email
            - totp
            - null
          description: >-
            Tipo de autenticação em dois fatores: `email` (código por e-mail) ou `totp` (app autenticador). `null`
            desativa.
        Salesman:
          type: integer
          enum:
            - 0
            - 1
          description: 1 = marca o usuário como vendedor. Padrão 0.
        RestrictAccessSalesman:
          type: integer
          enum:
            - 0
            - 1
          description: 1 = vendedor só enxerga as próprias vendas. Padrão 0.
        DiscountPercentLimit:
          type: number
          nullable: true
          description: Limite de desconto (%) padrão do vendedor.
        IDTypeSalesmanCommission:
          type: integer
          format: int32
          nullable: true
          description: >-
            Forma de liberação da comissão: 1 = parcial vinculada às parcelas, 2 = integral no faturamento, 3 = integral
            após pagamento da 1ª parcela, 4 = integral após pagamento da última parcela.
          enum:
            - 1
            - 2
            - 3
            - 4
        ExcludeCanceledOrdersCommission:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: 1 = pedidos cancelados não entram na comissão.
        ExcludeReturnedOrdersCommission:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: 1 = pedidos devolvidos não entram na comissão.
    UserUpdate:
      type: object
      description: Corpo de `PUT /user/{iduser}`. Atualização parcial — só os campos enviados são alterados.
      properties:
        UserName:
          type: string
          description: Nome do usuário.
        Login:
          type: string
          nullable: true
          description: E-mail de login.
        UserCpfCnpj:
          type: string
          nullable: true
          description: CPF/CNPJ (somente dígitos).
        UserTelephone:
          type: string
          nullable: true
          description: Telefone.
        UserExtenalId:
          type: string
          nullable: true
          description: Código externo (integração).
        Password:
          type: string
          nullable: true
          description: >-
            Nova senha. Validada contra a política da empresa (comprimento, complexidade, reuso e validade). Trocar a
            senha de outro usuário exige privilégio de redefinir senha.
        MFAEnabled:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: 1 = ativa autenticação em dois fatores.
        MFAType:
          type: string
          nullable: true
          enum:
            - email
            - totp
            - null
          description: >-
            Tipo de autenticação em dois fatores: `email` (código por e-mail) ou `totp` (app autenticador). `null`
            desativa.
        IDModuleFavorite:
          type: integer
          format: int32
          nullable: true
          description: Módulo favorito (tela inicial).
        IDUserJobPositionList:
          type: string
          nullable: true
          description: IDs dos cargos do usuário, separados por vírgula.
        Status:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: 'Status do vínculo: 1 = ativo, 0 = inativo.'
        Salesman:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: 1 = marca o usuário como vendedor.
        RestrictAccessSalesman:
          type: integer
          enum:
            - 0
            - 1
          description: 1 = vendedor só enxerga as próprias vendas.
        DiscountPercentLimit:
          type: number
          nullable: true
          description: Limite de desconto (%) padrão do vendedor. Ignorado quando `Salesman=0`.
        IDTypeSalesmanCommission:
          type: integer
          format: int32
          nullable: true
          description: >-
            Forma de liberação da comissão: 1 = parcial vinculada às parcelas, 2 = integral no faturamento, 3 = integral
            após pagamento da 1ª parcela, 4 = integral após pagamento da última parcela.
          enum:
            - 1
            - 2
            - 3
            - 4
        ExcludeCanceledOrdersCommission:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: 1 = pedidos cancelados não entram na comissão.
        ExcludeReturnedOrdersCommission:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: 1 = pedidos devolvidos não entram na comissão.
        Technician:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: 1 = marca o usuário como técnico.
    UserPrivilegeGroupRef:
      type: object
      description: Perfil de acesso vinculado a um usuário. Item de `GET /user/{iduser}/privilege/privilege-group`.
      properties:
        IDUserPrivilegeGroup:
          type: integer
          format: int32
          description: Identificador do perfil de acesso.
        PrivilegeGroupName:
          type: string
          description: Nome do perfil de acesso.
    UserVerifyRequest:
      type: object
      description: Corpo de `POST /user/{iduser}/verify`.
      required:
        - Password
      properties:
        Password:
          type: string
          description: Senha do usuário a confirmar.
        UserPrivilege:
          type: integer
          format: int32
          nullable: true
          description: >-
            Privilégio a verificar (opcional). Quando informado, exige que o usuário possua esse privilégio para
            confirmar.
    UserCompanyInvoiceCreate:
      type: object
      description: Corpo de `POST /user/{iduser}/company-invoice`.
      required:
        - IDCompany
      properties:
        IDCompany:
          type: integer
          format: int32
          description: Identificador da empresa/filial faturadora a vincular.
    UserDistributionCenterCreate:
      type: object
      description: Corpo de `POST /user/{iduser}/distribution-center`.
      required:
        - IDStockKeepingUnitDistributionCenter
      properties:
        IDStockKeepingUnitDistributionCenter:
          type: integer
          format: int32
          description: Identificador do centro de distribuição a vincular.
    UserSupplierCategoryCreate:
      type: object
      description: Corpo de `POST /user/{iduser}/supplier-category`.
      required:
        - IDSupplierCategory
      properties:
        IDSupplierCategory:
          type: integer
          format: int32
          description: Identificador da categoria de fornecedor a vincular.
    SkuListItemSimple:
      type: object
      description: Item do listagem rasa de SKU (modo `Simple=1`).
      properties:
        IDSku:
          type: integer
          description: Identificador do SKU.
        IDCompany:
          type: integer
          description: Identificador da empresa dona do SKU.
        IDStatusSku:
          type: integer
          description: >-
            Status do SKU: `1` Ativo, `2` Compra suspensa, `3` Inativo, `4` Venda suspensa (`0` é registro logicamente
            excluído).
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
        BarCode:
          type: string
          nullable: true
          maxLength: 20
          description: Código de barras principal (EAN/GTIN).
        IDTypeSku:
          type: integer
          description: Tipo do SKU (vide os tipos de produto).
        IDSkuCompany:
          type: string
          nullable: true
          maxLength: 100
          description: Código de referência interno do SKU na empresa.
        SkuNameOnly:
          type: string
          nullable: true
          description: Nome do SKU sem prefixo do produto-pai.
        Batch:
          type: integer
          description: Indica se o SKU usa controle de lote.
        AccountName:
          type: string
          description: Subdomínio da empresa dona do SKU.
        TypeProduct:
          type: string
          description: Descrição do tipo do SKU.
        CostSet:
          type: number
          nullable: true
          description: Custo manual cadastrado para o SKU.
        SerialNumber:
          type: integer
          description: Indica se o SKU é controlado por número de série.
        CostAverage:
          type: number
          nullable: true
          description: Custo médio do SKU calculado a partir das movimentações de entrada.
        CostLastPurchase:
          type: number
          nullable: true
          description: Custo da última compra registrada para o SKU (última nota fiscal de entrada).
        InventoryValue:
          type: number
          nullable: true
          description: Valor financeiro do estoque consolidado.
        SkuHeight:
          type: number
          nullable: true
          description: Altura do SKU em cm.
        SkuLength:
          type: number
          nullable: true
          description: Comprimento do SKU em cm.
        SkuWidth:
          type: number
          nullable: true
          description: Largura do SKU em cm.
        SkuWeight:
          type: number
          nullable: true
          description: Peso bruto do SKU em kg.
        IDProduct:
          type: integer
          nullable: true
          description: Identificador do produto-pai, quando este SKU é variação.
        RastroControl:
          type: integer
          nullable: true
          description: >-
            `1` quando o SKU tem rastreabilidade extra: nos recebimentos a data de fabricação e a data de validade do
            lote passam a ser obrigatórias além do número do lote (`Batch=1`).
        BestBeforeRequired:
          type: integer
          nullable: true
          description: >-
            `1` quando a data de validade é obrigatória nas entradas (válido apenas quando o SKU tem rastreabilidade por
            lote).
        BatchRequired:
          type: integer
          nullable: true
          description: >-
            `1` quando o número do lote é obrigatório nas entradas e saídas (válido apenas quando o SKU tem
            rastreabilidade por lote).
        TypeProductVariationValue:
          type: string
          nullable: true
          description: 'Valores de variação concatenados por vírgula (ex.: `Azul,M`).'
        QtyAvailable:
          type: string
          description: Quantidade disponível em estoque (string com ajuste de margem de segurança).
        BarCodePackageList:
          type: array
          description: Códigos de barras de embalagem (caixa) do SKU.
          items:
            type: object
            properties:
              BarCodePackage:
                type: string
                description: >-
                  Código de barras alternativo cadastrado para o SKU (embalagem secundária, ex.: caixa com múltiplas
                  unidades).
              PackageFactor:
                type: integer
                description: Quantidade de unidades por embalagem.
        PriceSell:
          type: number
          nullable: true
          description: Preço de venda do SKU na política comercial padrão da empresa.
        PriceList:
          type: number
          nullable: true
          description: Preço de tabela (preço cheio) do SKU na política comercial padrão.
        LastValueCost:
          type: number
          nullable: true
          description: Último custo do fornecedor (aparece apenas quando `IDSupplierCost` é enviado).
        MainImageURL:
          type: string
          nullable: true
          description: URL da imagem principal do SKU.
        MainImageThumbnailURL:
          type: string
          nullable: true
          description: URL da miniatura da imagem principal.
        SkuName:
          type: string
          nullable: true
          description: Nome do SKU; concatenado com o nome do produto-pai quando aplicável.
        Quantity:
          type: number
          nullable: true
          description: Quantidade derivada quando o `BarCode` lido é de balança (valor por peso).
    SkuListItem:
      type: object
      description: >-
        Item da listagem padrão de SKU (modo completo). Schema parcial — a query do sistema retorna dezenas de campos
        calculados de vendas, estoque, custos e curva ABC.
      additionalProperties: true
      properties:
        IDSku:
          type: integer
          description: Identificador do SKU.
        IDCompany:
          type: integer
          description: Identificador da empresa dona do SKU.
        AccountName:
          type: string
          description: Conta (subdomínio) da empresa.
        SkuName:
          type: string
          nullable: true
          description: Nome do SKU.
        IDSkuCompany:
          type: string
          nullable: true
          maxLength: 100
          description: Código de referência interno do SKU, definido pela empresa.
        BarCode:
          type: string
          nullable: true
          maxLength: 20
          description: Código de barras principal.
        IDTypeSku:
          type: integer
          description: >-
            Tipo do SKU: `1` Clube (assinatura), `2` Kit, `3` Sku (produto normal), `4` Produto com variação (pai), `5`
            Serviço, `6` Matéria-prima, `7` Uso e consumo, `8` Caixa fechada.
        TypeProduct:
          type: string
          description: Descrição textual do tipo do SKU (vide `IDTypeSku`).
        IDBrand:
          type: integer
          nullable: true
          description: Identificador da marca.
        Brand:
          type: string
          nullable: true
          description: Nome da marca.
        IDCategory:
          type: integer
          nullable: true
          description: Identificador da categoria.
        Category:
          type: string
          nullable: true
          description: Nome da categoria.
        CategoryTree:
          type: string
          nullable: true
          description: Caminho completo da categoria (`Pai -> Filha -> Neta`).
        IDStatusSku:
          type: integer
          description: >-
            Status do SKU: `1` Ativo, `2` Compra suspensa, `3` Inativo, `4` Venda suspensa (`0` é registro logicamente
            excluído).
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
        TypeStatusSku:
          type: string
          nullable: true
          description: 'Descrição textual do status do SKU: `Ativo`, `Compra suspensa`, `Inativo`, `Venda suspensa`.'
        Package:
          type: integer
          description: '`1` indica que o SKU é uma embalagem master (caixa/fardo) usada para venda agrupada; `0` é SKU normal.'
        QtyAvailable:
          type: string
          description: >-
            Quantidade disponível em estoque (soma de todos os depósitos), em formato string para preservar a precisão
            decimal.
        PriceSell:
          type: number
          nullable: true
          description: Preço de venda na política comercial padrão da empresa.
        PriceList:
          type: number
          nullable: true
          description: Preço de tabela (preço cheio, sem desconto) na política comercial padrão.
        CostAverage:
          type: number
          nullable: true
          description: Custo médio calculado pelas movimentações de entrada.
        CostSet:
          type: number
          nullable: true
          description: Custo manual cadastrado no SKU (sobrescreve os outros custos quando informado).
        CostLastPurchase:
          type: number
          nullable: true
          description: Custo da última compra (última nota fiscal de entrada).
        InventoryValue:
          type: number
          nullable: true
          description: >-
            Valor monetário do estoque do SKU. Vem do somatório de `InventoryValue` (acumulado pelas entradas com o
            custo de cada movimentação). Quando a parametrização `UseCostFromCostSet=1` está ativa, é calculado como
            `CostSet × QtyAvailable`.
        MainImageURL:
          type: string
          nullable: true
          description: URL da imagem principal do SKU.
        MainImageThumbnailURL:
          type: string
          nullable: true
          description: URL da miniatura da imagem principal.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora de criação do registro.
        DateLastRecordModification:
          type: string
          format: date-time
          nullable: true
          description: Data e hora da última alteração do registro.
        MinimumBalanceDays:
          type: integer
          nullable: true
          description: Dias mínimos de cobertura de estoque usados no cálculo de sugestão de compra.
        MaximumBalanceDays:
          type: integer
          nullable: true
          description: Dias máximos de cobertura de estoque usados no cálculo de sugestão de compra.
    SkuDetail:
      type: object
      description: >-
        Detalhe completo de um SKU. Inclui os campos do cadastro do SKU, campos calculados (custos, estoque, valor) e
        listas relacionadas (fornecedores, códigos de barras adicionais, códigos de embalagem). Quando `Sales=1` na
        query, a resposta troca o detalhe pelas métricas históricas de venda (vide sistema).
      properties:
        IDSku:
          type: integer
          description: Identificador do SKU.
        IDCompany:
          type: integer
          description: Identificador da empresa dona do SKU.
        AccountName:
          type: string
          description: Conta (subdomínio) da empresa.
        CompanyCpfCnpj:
          type: string
          nullable: true
          description: CPF/CNPJ da empresa do SKU.
        CompanyNameCorporateName:
          type: string
          nullable: true
          description: Razão social da empresa do SKU.
        SkuName:
          type: string
          nullable: true
          maxLength: 150
          description: Nome do SKU.
        ProductName:
          type: string
          nullable: true
          description: Nome do produto-pai, quando este SKU é variação.
        IDProduct:
          type: integer
          nullable: true
          description: Quando este SKU é uma variação, identificador do SKU produto-pai que o agrupa.
        IDSkuCompany:
          type: string
          nullable: true
          maxLength: 100
          description: Código de referência interno do SKU, definido pela empresa. Único por empresa.
        BarCode:
          type: string
          nullable: true
          maxLength: 20
          description: Código de barras principal.
        IDTypeSku:
          type: integer
          description: >-
            Tipo do SKU: `1` Clube, `2` Kit, `3` Sku (produto normal), `4` Produto com variação, `5` Serviço, `6`
            Matéria-prima, `7` Uso e consumo, `8` Caixa fechada.
        TypeProduct:
          type: string
          nullable: true
          description: Descrição textual do tipo do SKU.
        IDStatusSku:
          type: integer
          description: >-
            Status do SKU: `1` Ativo, `2` Compra suspensa, `3` Inativo, `4` Venda suspensa (`0` é registro logicamente
            excluído).
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
        TypeStatusSku:
          type: string
          nullable: true
          description: Descrição textual do status (vide `IDStatusSku`).
        IDTypeSkuCondition:
          type: integer
          nullable: true
          description: 'Condição do produto: `1` novo, `2` usado, `3` recondicionado.'
          enum:
            - 1
            - 2
            - 3
        TypeSkuCondition:
          type: string
          nullable: true
          description: 'Descrição textual da condição: `Novo`, `Usado`, `Recondicionado`.'
        IDBrand:
          type: integer
          nullable: true
          description: Identificador da marca.
        Brand:
          type: string
          nullable: true
          description: Nome da marca.
        IDCategory:
          type: integer
          nullable: true
          description: Identificador da categoria.
        Category:
          type: string
          nullable: true
          description: Nome da categoria.
        IDTaxDepartment:
          type: integer
          nullable: true
          description: Identificador do departamento fiscal (regra tributária aplicada ao SKU).
        TaxDepartmentDescription:
          type: string
          nullable: true
          description: Descrição do departamento fiscal.
        IDCompanyInvoice:
          type: integer
          nullable: true
          description: Empresa faturadora associada ao SKU.
        AccountNameInvoice:
          type: string
          nullable: true
          description: Conta (subdomínio) da empresa faturadora vinculada ao SKU.
        CompanyNameCorporateNameInvoice:
          type: string
          nullable: true
          description: Razão social da empresa faturadora.
        IDCompanyInvoiceIDCompanyIntegrationList:
          type: string
          nullable: true
          description: Lista de integrações `IDCompanyIntegration` em que essa empresa faturadora deve ser usada.
        SkuHeight:
          type: number
          nullable: true
          description: Altura do SKU em cm.
        SkuLength:
          type: number
          nullable: true
          description: Comprimento do SKU em cm.
        SkuWidth:
          type: number
          nullable: true
          description: Largura do SKU em cm.
        SkuWeight:
          type: number
          nullable: true
          description: Peso bruto em kg.
        SkuWeightNet:
          type: number
          nullable: true
          description: Peso líquido em kg.
        SkuNCM:
          type: string
          nullable: true
          maxLength: 12
          description: Código NCM (Nomenclatura Comum do Mercosul) do SKU para fins fiscais.
        SkuNCMExTipi:
          type: string
          nullable: true
          maxLength: 3
          description: Ex TIPI do NCM (2 ou 3 dígitos).
        SkuCest:
          type: string
          nullable: true
          maxLength: 15
          description: Código CEST (Código Especificador da Substituição Tributária).
        SkuCst:
          type: integer
          nullable: true
          description: Origem fiscal do SKU.
        SkuCstDescription:
          type: string
          nullable: true
          description: Descrição textual da origem do produto (CST).
        MeasurementUnit:
          type: string
          nullable: true
          maxLength: 45
          description: Unidade de medida do SKU (`UN`, `KG`, `L`, `M`, etc.).
        MeasurementUnitDescription:
          type: string
          nullable: true
          description: Descrição da unidade de medida.
        CostSet:
          type: number
          nullable: true
          description: Custo manual cadastrado.
        CostAverage:
          type: number
          nullable: true
          description: Custo médio calculado pelas entradas.
        CostLastPurchase:
          type: number
          nullable: true
          description: Custo da última compra registrada.
        InventoryValue:
          type: number
          nullable: true
          description: Valor monetário do estoque (`CostAverage * QtyAvailable`).
        Batch:
          type: integer
          description: '`1` quando o SKU é controlado por lote (rastreabilidade por número de lote nas movimentações).'
        BatchRequired:
          type: integer
          nullable: true
          description: '`1` quando o número do lote é obrigatório nas entradas e saídas (apenas válido se `Batch=1`).'
        BestBeforeRequired:
          type: integer
          nullable: true
          description: '`1` quando a data de validade é obrigatória nas entradas (apenas válido se `Batch=1`).'
        BestBeforeMinimumDays:
          type: integer
          nullable: true
          description: Validade mínima aceita (em dias) no recebimento — entradas com validade menor que esse prazo são bloqueadas.
        BestBeforeDays:
          type: integer
          nullable: true
          description: Prazo de validade padrão (em dias) sugerido para o lote a partir da data de fabricação.
        RastroControl:
          type: integer
          nullable: true
          description: >-
            `1` quando o SKU tem rastreabilidade extra: nos recebimentos a data de fabricação e a data de validade do
            lote passam a ser obrigatórias além do número do lote (`Batch=1`).
        SerialNumber:
          type: integer
          description: '`1` quando o SKU é controlado por número de série (cada unidade tem identificador único).'
        Package:
          type: integer
          description: '`1` quando o SKU representa uma embalagem master (caixa/fardo) usada para integração de catálogo.'
        PackageOccupation:
          type: number
          nullable: true
          description: Ocupação do SKU no endereçamento (fator multiplicador usado no cálculo de capacidade do endereço).
        QtyAvailable:
          type: string
          description: Quantidade disponível em estoque (string para preservar precisão decimal).
        QtyReserved:
          type: string
          nullable: true
          description: Quantidade reservada em pedidos não faturados.
        QtySafetyStock:
          type: number
          nullable: true
          description: Estoque mínimo de segurança configurado.
        MinimumPickingLocationQuantity:
          type: number
          nullable: true
          description: Quantidade mínima a manter no endereço de picking (gatilho de ressuprimento).
        MaximumPickingLocationQuantity:
          type: number
          nullable: true
          description: Quantidade máxima do endereço de picking (limite superior do ressuprimento).
        BuyOrdemQuantity:
          type: string
          nullable: true
          description: Quantidade total em pedidos de compra em aberto.
        BuyOrderAlert:
          type: integer
          nullable: true
          description: '`1` liga o alerta automático de compra quando o estoque cai abaixo da quantidade configurada.'
        BuyOrderAlertManualQuantity:
          type: integer
          nullable: true
          description: Quantidade que dispara o alerta de compra quando `BuyOrderAlert=1`.
        KitsRelatedCount:
          type: integer
          nullable: true
          description: Quantos kits usam este SKU como componente (válido para SKUs do tipo normal).
        InfiniteInventory:
          type: integer
          description: '`1` quando o SKU não controla estoque (vendas não decrementam — usado para serviços e itens digitais).'
        OwnProduction:
          type: integer
          description: '`1` quando o SKU é de produção própria (libera fluxos de ordem de produção).'
        AbcCurve:
          type: string
          nullable: true
          maxLength: 1
          description: Classificação automática da curva ABC do SKU baseada em participação no faturamento (`A`, `B`, `C`).
        AbcCurveAdjust:
          type: string
          nullable: true
          maxLength: 1
          description: Curva ABC ajustada manualmente — sobrescreve `AbcCurve` quando preenchida.
        IDStockKeepingUnitProductionLine:
          type: integer
          nullable: true
          description: Linha de produção associada ao SKU.
        ProductionLineName:
          type: string
          nullable: true
          description: Nome da linha de produção.
        IDStockKeepingUnitLocationCategory:
          type: integer
          nullable: true
          description: Categoria de endereçamento sugerida ao alocar o SKU.
        StockKeepingUnitLocationCategoryName:
          type: string
          nullable: true
          description: Nome da categoria de endereçamento.
        WarrantyTime:
          type: string
          nullable: true
          maxLength: 45
          description: Quantidade de garantia (número).
        WarrantyTimeType:
          type: string
          nullable: true
          maxLength: 45
          description: Unidade da garantia (`dias`, `meses`, `anos`).
        Comments:
          type: string
          nullable: true
          maxLength: 500
          description: Observações livres do SKU.
        NfeComments:
          type: string
          nullable: true
          maxLength: 200
          description: Observações impressas na nota fiscal eletrônica.
        NfeInvoiceAsKit:
          type: integer
          nullable: true
          description: '`1` faz a NF-e detalhar os componentes do kit individualmente; `0` emite o kit como item único.'
        NfeFactorPercentSku:
          type: number
          nullable: true
          description: >-
            Fator percentual aplicado ao preço do SKU na emissão da NF-e (ex.: 0.95 reduz 5%). Quando preenchido, zera
            `NfeFactorFixedSkuValue`.
        NfeFactorPercentSkuIDCompanyIntegrationList:
          type: string
          nullable: true
          description: >-
            Lista (separada por vírgula) dos identificadores de integração de empresa em que o fator percentual deve ser
            aplicado.
        NfeFactorFixedSkuValue:
          type: number
          nullable: true
          description: Valor fixo aplicado ao preço do SKU na NF-e. Mutuamente exclusivo com `NfeFactorPercentSku`.
        LeadTimeDays:
          type: integer
          nullable: true
          description: Lead time (em dias) entre a colocação do pedido de compra e a chegada do SKU.
        EstimatedDateArrival:
          type: string
          format: date
          nullable: true
          description: Data estimada de chegada do SKU em pedidos futuros — usada quando o item está em rota de reposição.
        ShareProductImage:
          type: integer
          nullable: true
          description: '`1` quando a variação compartilha as imagens do produto-pai; `0` usa imagens próprias.'
        KitAutomaticMeasureUpdate:
          type: integer
          description: >-
            `1` recalcula automaticamente medidas (peso, dimensões) do kit a partir dos componentes ao alterar a
            composição.
        KitAutomaticPricingUpdate:
          type: integer
          nullable: true
          description: '`1` recalcula automaticamente o preço do kit a partir dos componentes ao alterar a composição.'
        EcommerceDescription:
          type: string
          nullable: true
          maxLength: 10000
          description: Descrição completa do produto para vitrine de e-commerce (texto rico).
        EcommerceDescriptionShort:
          type: string
          nullable: true
          maxLength: 3000
          description: Descrição curta para vitrine de e-commerce (resumo).
        EcommerceKeyWords:
          type: string
          nullable: true
          maxLength: 1000
          description: Palavras-chave (SEO) separadas por vírgula.
        EcommerceLinkId:
          type: string
          nullable: true
          maxLength: 400
          description: Identificador de URL amigável (slug) para a página do produto.
        EcommerceMetaTagDescription:
          type: string
          nullable: true
          maxLength: 3000
          description: Meta tag description para SEO da página do produto.
        EcommerceTitle:
          type: string
          nullable: true
          maxLength: 200
          description: Título da página do produto na vitrine de e-commerce.
        EcommerceVideoUrl:
          type: string
          nullable: true
          maxLength: 200
          description: URL de vídeo de demonstração do produto.
        EcommerceKitAutomaticDescription:
          type: integer
          nullable: true
          description: '`1` faz a descrição do kit ser composta automaticamente concatenando as descrições dos componentes.'
        MainImageURL:
          type: string
          nullable: true
          description: URL da imagem principal do SKU (ou imagem da primeira variação, quando aplicável).
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora de criação do registro.
        DateLastRecordModification:
          type: string
          format: date-time
          nullable: true
          description: Data e hora da última alteração do registro.
        Tags:
          type: array
          items:
            type: string
          description: Etiquetas livres do SKU.
        Suppliers:
          type: array
          description: Fornecedores cadastrados para este SKU.
          items:
            type: object
            properties:
              IDStockKeepingUnitSuplierCode:
                type: integer
                description: Identificador da relação SKU↔fornecedor.
              IDSupplier:
                type: integer
                description: Identificador do fornecedor.
              PackageSize:
                type: number
                nullable: true
                description: Tamanho da embalagem do fornecedor (quantidade por caixa).
              QuantityMultiply:
                type: number
                nullable: true
                description: Múltiplo mínimo de compra desse fornecedor.
              SupplierCode:
                type: string
                nullable: true
                description: Código de referência do SKU no catálogo do fornecedor.
        BarCodeList:
          type: array
          description: Códigos de barras adicionais (além do principal).
          items:
            type: object
            properties:
              IDStockKeepingUnitBarCode:
                type: integer
                description: Identificador do código de barras adicional.
              AdditionalBarCode:
                type: string
                description: Código de barras adicional (alternativo ao principal).
        BarCodePackageList:
          type: array
          description: Códigos de barras de embalagens (caixa, fardo, master).
          items:
            type: object
            properties:
              AccountName:
                type: string
                description: Conta (subdomínio) da empresa.
              IDStockKeepingUnitBarCodePackage:
                type: integer
                description: Identificador do código de barras de embalagem.
              BarCodePackage:
                type: string
                description: Código de barras da embalagem (caixa/fardo/master).
              PackageFactor:
                type: integer
                description: Quantidade de unidades dentro da embalagem.
              IDSkuKit:
                type: integer
                nullable: true
                description: Quando o código aponta para um kit equivalente, o SKU do kit.
              IDSkuCompanyKit:
                type: string
                nullable: true
                description: Quando a embalagem corresponde a um kit, código de referência (`IDSkuCompany`) do kit equivalente.
              SkuNameKit:
                type: string
                nullable: true
                description: Nome do kit equivalente, quando aplicável.
    SkuCreateBody:
      type: object
      description: Corpo para criar um novo SKU.
      required:
        - IDTypeSku
      properties:
        SkuName:
          type: string
          nullable: true
          maxLength: 150
          description: Nome do SKU.
        IDSkuCompany:
          type: string
          nullable: true
          maxLength: 100
          description: >-
            Código de referência interno do SKU. Único por empresa. Quando omitido, é preenchido automaticamente com o
            próprio `IDSku` gerado (exceto quando `Composing` é enviado).
        IDTypeSku:
          type: integer
          description: >-
            Tipo do SKU. Obrigatório. 1=Clube, 2=Kit, 3=Sku (produto normal), 4=Produto (com variação), 5=Serviço,
            6=Matéria-prima, 7=Uso e consumo, 8=Caixa.
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 7
            - 8
        BarCode:
          type: string
          nullable: true
          maxLength: 20
          description: >-
            Código de barras principal. Não pode duplicar entre SKUs da empresa. Quando omitido, é preenchido
            automaticamente com o `IDSku` gerado.
        IDBrand:
          type: integer
          nullable: true
          description: Identificador da marca. Validado contra as marcas da empresa.
        IDCategory:
          type: integer
          nullable: true
          description: Identificador da categoria do SKU.
        IDTaxDepartment:
          type: integer
          nullable: true
          description: Identificador do departamento fiscal.
        IDCompanyInvoice:
          type: integer
          nullable: true
          description: Empresa faturadora vinculada ao SKU (uma das empresas do grupo).
        IDStockKeepingUnitProductionLine:
          type: integer
          nullable: true
          description: Linha de produção associada ao SKU.
        IDStockKeepingUnitLocationCategory:
          type: integer
          nullable: true
          description: Categoria de endereçamento para o SKU.
        IDTypeSkuCondition:
          type: integer
          nullable: true
          enum:
            - 1
            - 2
            - 3
          description: 'Condição do SKU: `1` Novo, `2` Usado, `3` Recondicionado. Default `1`.'
        MeasurementUnit:
          type: string
          nullable: true
          maxLength: 45
          description: Unidade de medida (`UN`, `KG`, `L`, etc.). Default `UN`. Validada contra as unidades cadastradas.
        SkuHeight:
          type: number
          nullable: true
          description: Altura em cm.
        SkuLength:
          type: number
          nullable: true
          description: Comprimento em cm.
        SkuWidth:
          type: number
          nullable: true
          description: Largura em cm.
        SkuWeight:
          type: number
          nullable: true
          description: Peso bruto em kg.
        SkuWeightNet:
          type: number
          nullable: true
          description: Peso líquido em kg.
        SkuNCM:
          type: string
          nullable: true
          maxLength: 12
          description: Código NCM (Nomenclatura Comum do Mercosul) do SKU.
        SkuNCMExTipi:
          type: string
          nullable: true
          maxLength: 3
          description: Ex TIPI (2 ou 3 dígitos).
        SkuCest:
          type: string
          nullable: true
          maxLength: 15
          description: Código CEST (Especificador da Substituição Tributária).
        SkuCst:
          type: integer
          nullable: true
          description: Origem do SKU (validada contra a tabela de origens da NF-e).
        CostSet:
          type: number
          nullable: true
          description: Custo manual cadastrado.
        Batch:
          type: integer
          nullable: true
          description: >-
            `1` controla por lote, `0` não controla. Na criação o valor é definido pela parametrização
            `AutomaticBatchEnabledSku` da empresa — o valor enviado no corpo é ignorado no cadastro.
        BatchRequired:
          type: integer
          nullable: true
          description: >-
            `1` exige o número do lote nas movimentações de entrada/saída. Na criação o valor é definido pela
            parametrização `AutomaticBatchRequiredEnabledSku` — o valor enviado no corpo é ignorado no cadastro.
        RastroControl:
          type: integer
          nullable: true
          description: >-
            `1` ativa o controle de rastreabilidade extra: nos recebimentos passam a ser obrigatórias as datas de
            fabricação e validade. Na criação o valor é definido pela parametrização `AutomaticRastroEnabledSku` — o
            valor enviado no corpo é ignorado no cadastro.
        BestBeforeDays:
          type: integer
          nullable: true
          description: Prazo de validade padrão (em dias) a partir da data de fabricação.
        MinimumPickingLocationQuantity:
          type: number
          nullable: true
          description: Quantidade mínima do endereço de picking — abaixo disso é disparado ressuprimento.
        MaximumPickingLocationQuantity:
          type: number
          nullable: true
          description: Quantidade máxima do endereço de picking — limita o ressuprimento.
        MinimumBalanceDays:
          type: integer
          nullable: true
          description: Dias mínimos de cobertura de estoque considerados no cálculo de sugestão de compra.
        MaximumBalanceDays:
          type: integer
          nullable: true
          description: Dias máximos de cobertura de estoque considerados no cálculo de sugestão de compra.
        QtySafetyStock:
          type: number
          nullable: true
          description: Estoque mínimo de segurança.
        Package:
          type: integer
          nullable: true
          description: '`1` indica que o SKU é uma embalagem master usada para integração de catálogo. Default `0`.'
        InfiniteInventory:
          type: integer
          nullable: true
          description: '`1` quando o SKU não precisa controlar estoque.'
        OwnProduction:
          type: integer
          nullable: true
          description: '`1` quando produção própria. Default `0`.'
        SerialNumber:
          type: integer
          nullable: true
          description: '`1` quando o SKU é controlado por número de série.'
        EstimatedDateArrival:
          type: string
          format: date
          nullable: true
          description: Data estimada de chegada do SKU em uma reposição futura.
        LeadTimeDays:
          type: integer
          nullable: true
          description: Lead time (em dias) entre pedido de compra e recebimento.
        WarrantyTime:
          type: string
          nullable: true
          maxLength: 45
          description: Quantidade de garantia (número).
        WarrantyTimeType:
          type: string
          nullable: true
          maxLength: 45
          description: Unidade da garantia (`dias`, `meses`, `anos`).
        Comments:
          type: string
          nullable: true
          maxLength: 500
          description: Observações livres do SKU.
        NfeComments:
          type: string
          nullable: true
          maxLength: 200
          description: Observações que serão impressas na NF-e.
        NfeInvoiceAsKit:
          type: integer
          nullable: true
          description: '`1` faz a NF-e detalhar os componentes do kit; `0` emite o kit como item único.'
        EcommerceDescription:
          type: string
          nullable: true
          maxLength: 10000
          description: Descrição completa para vitrine de e-commerce (texto rico).
        EcommerceDescriptionShort:
          type: string
          nullable: true
          maxLength: 3000
          description: Descrição curta para vitrine de e-commerce.
        EcommerceKeyWords:
          type: string
          nullable: true
          maxLength: 1000
          description: Palavras-chave SEO separadas por vírgula.
        EcommerceLinkId:
          type: string
          nullable: true
          maxLength: 400
          description: Slug (URL amigável) da página do produto.
        EcommerceMetaTagDescription:
          type: string
          nullable: true
          maxLength: 3000
          description: Meta tag description para SEO.
        EcommerceTitle:
          type: string
          nullable: true
          maxLength: 200
          description: Título da página do produto. Quando omitido, assume o `SkuName`.
        EcommerceVideoUrl:
          type: string
          nullable: true
          maxLength: 200
          description: URL de vídeo de demonstração.
        EcommerceKitAutomaticDescription:
          type: integer
          nullable: true
          description: '`1` monta a descrição do kit automaticamente a partir dos componentes.'
        ShareProductImage:
          type: integer
          nullable: true
          description: '`1` para compartilhar as imagens do produto-pai com este SKU.'
        AbcCurveAdjust:
          type: string
          nullable: true
          maxLength: 1
          description: Curva ABC ajustada manualmente (`A`, `B`, `C`) — sobrescreve a curva calculada automaticamente.
        KitAutomaticPricingUpdate:
          type: integer
          nullable: true
          description: '`1` recalcula automaticamente o preço do kit ao alterar a composição.'
        Tags:
          type: array
          items:
            type: string
          description: Etiquetas livres do SKU.
        PriceList:
          type: number
          nullable: true
          description: Preço de tabela na criação. Quando informado junto com `PriceSell` cria um registro inicial de preço.
        PriceSell:
          type: number
          nullable: true
          description: Preço de venda na criação. Dispara a criação do registro de preço inicial.
        IDCompanySalesPolicy:
          type: integer
          nullable: true
          description: >-
            Política comercial usada para os preços enviados na criação (validada apenas quando `PriceSell` é
            informado). Quando omitida, usa a política padrão da empresa.
        Variations:
          type: array
          nullable: true
          description: Variações iniciais do SKU (tipo de variação `cor`, `tamanho`, etc. e o valor correspondente).
          items:
            type: object
            required:
              - IDTypeProductVariation
              - IDTypeProductVariationValue
            properties:
              IDTypeProductVariation:
                type: integer
                description: 'Identificador do tipo de variação (ex.: cor, tamanho).'
              IDTypeProductVariationValue:
                type: integer
                description: 'Identificador do valor da variação (ex.: azul, M).'
        IDSkuCompanyComposing:
          type: string
          nullable: true
          description: >-
            Quando criando uma variação/componente de kit, código de referência do produto-pai a vincular. Usado em
            conjunto com o query param `Composing`.
    SkuUpdateBody:
      type: object
      description: >-
        Corpo para atualização parcial de um SKU. Todos os campos são opcionais; envie apenas o que quer alterar.
        Alterar `IDTypeSku` tem regras adicionais (item sem movimentação, sem lote, sem ser componente de kit, sem
        variação, sem produto-pai — ver respostas de erro).
      properties:
        SkuName:
          type: string
          nullable: true
          maxLength: 150
          description: Nome do SKU.
        IDSkuCompany:
          type: string
          nullable: true
          maxLength: 100
          description: Código de referência interno. Único por empresa.
        IDTypeSku:
          type: integer
          description: 'Alteração restrita: SKU não pode ter movimentação, lote, componentes de kit, variação nem produto-pai.'
        IDStatusSku:
          type: integer
          description: 'Status do SKU: `1` Ativo, `2` Compra suspensa, `3` Inativo, `4` Venda suspensa.'
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
        BarCode:
          type: string
          nullable: true
          maxLength: 20
          description: Código de barras principal. Não pode duplicar entre SKUs da empresa.
        IDBrand:
          type: integer
          nullable: true
          description: Identificador da marca.
        IDCategory:
          type: integer
          nullable: true
          description: Identificador da categoria.
        IDTaxDepartment:
          type: integer
          nullable: true
          description: Identificador do departamento fiscal.
        IDCompanyInvoice:
          type: integer
          nullable: true
          description: Empresa faturadora vinculada ao SKU.
        IDCompanyInvoiceIDCompanyIntegrationList:
          type: string
          nullable: true
          description: >-
            Lista (separada por vírgula) dos identificadores de integração em que a empresa faturadora informada deve
            ser usada.
        IDStockKeepingUnitProductionLine:
          type: integer
          nullable: true
          description: Linha de produção associada ao SKU.
        IDStockKeepingUnitLocationCategory:
          type: integer
          nullable: true
          description: Categoria de endereçamento sugerida.
        IDTypeSkuCondition:
          type: integer
          nullable: true
          description: 'Condição do SKU: `1` Novo, `2` Usado, `3` Recondicionado.'
          enum:
            - 1
            - 2
            - 3
        MeasurementUnit:
          type: string
          nullable: true
          maxLength: 45
          description: Unidade de medida (`UN`, `KG`, `L`, etc.).
        SkuHeight:
          type: number
          nullable: true
          description: Altura em cm.
        SkuLength:
          type: number
          nullable: true
          description: Comprimento em cm.
        SkuWidth:
          type: number
          nullable: true
          description: Largura em cm.
        SkuWeight:
          type: number
          nullable: true
          description: Peso bruto em kg.
        SkuWeightNet:
          type: number
          nullable: true
          description: Peso líquido em kg.
        SkuNCM:
          type: string
          nullable: true
          maxLength: 12
          description: Código NCM do SKU.
        SkuNCMExTipi:
          type: string
          nullable: true
          maxLength: 3
          description: Ex TIPI do NCM (2 ou 3 dígitos).
        SkuCest:
          type: string
          nullable: true
          maxLength: 15
          description: Código CEST.
        SkuCst:
          type: integer
          nullable: true
          description: Origem do SKU (CST — Código de Situação Tributária).
        CostSet:
          type: number
          nullable: true
          description: Custo manual cadastrado (sobrescreve `CostAverage` quando informado).
        Batch:
          type: integer
          nullable: true
          description: '`1` ativa controle por lote; `0` desativa.'
        BatchRequired:
          type: integer
          nullable: true
          description: '`1` exige número do lote nas movimentações.'
        RastroControl:
          type: integer
          nullable: true
          description: '`1` ativa o controle de rastro sanitário.'
        BestBeforeRequired:
          type: integer
          nullable: true
          description: '`1` exige data de validade nas entradas.'
        BestBeforeMinimumDays:
          type: integer
          nullable: true
          description: Validade mínima aceita na entrada (em dias).
        BestBeforeDays:
          type: integer
          nullable: true
          description: Prazo de validade padrão (em dias) a partir da fabricação.
        MinimumPickingLocationQuantity:
          type: number
          nullable: true
          description: Quantidade mínima no endereço de picking — gatilho de ressuprimento.
        MaximumPickingLocationQuantity:
          type: number
          nullable: true
          description: Quantidade máxima do endereço de picking.
        QtySafetyStock:
          type: number
          nullable: true
          description: Estoque mínimo de segurança.
        Package:
          type: integer
          nullable: true
          description: '`1` define o SKU como embalagem master.'
        PackageOccupation:
          type: number
          nullable: true
          description: Ocupação no endereçamento (fator de capacidade).
        InfiniteInventory:
          type: integer
          nullable: true
          description: '`1` quando o SKU não controla estoque (serviços, itens digitais).'
        OwnProduction:
          type: integer
          nullable: true
          description: '`1` para produção própria (libera ordens de produção).'
        SerialNumber:
          type: integer
          nullable: true
          description: '`1` controla o SKU por número de série.'
        EstimatedDateArrival:
          type: string
          format: date
          nullable: true
          description: Data estimada de chegada em reposição futura.
        LeadTimeDays:
          type: integer
          nullable: true
          description: Lead time entre compra e recebimento (dias).
        WarrantyTime:
          type: string
          nullable: true
          maxLength: 45
          description: Quantidade de garantia.
        WarrantyTimeType:
          type: string
          nullable: true
          maxLength: 45
          description: Unidade da garantia (`dias`, `meses`, `anos`).
        Comments:
          type: string
          nullable: true
          maxLength: 500
          description: Observações livres.
        NfeComments:
          type: string
          nullable: true
          maxLength: 200
          description: Observações impressas na NF-e.
        NfeInvoiceAsKit:
          type: integer
          nullable: true
          description: '`1` detalha componentes do kit na NF-e; `0` emite como item único.'
        NfeFactorPercentSku:
          type: number
          nullable: true
          description: Quando enviado, zera `NfeFactorFixedSkuValue` automaticamente.
        NfeFactorPercentSkuIDCompanyIntegrationList:
          type: string
          nullable: true
          description: >-
            Lista (separada por vírgula) dos identificadores de integração em que o fator percentual de NF-e deve ser
            aplicado.
        NfeFactorFixedSkuValue:
          type: number
          nullable: true
          description: Só persistido se `NfeFactorPercentSku` for `null`.
        EcommerceDescription:
          type: string
          nullable: true
          maxLength: 10000
          description: Descrição completa para vitrine.
        EcommerceDescriptionShort:
          type: string
          nullable: true
          maxLength: 3000
          description: Descrição curta para vitrine.
        EcommerceKeyWords:
          type: string
          nullable: true
          maxLength: 1000
          description: Palavras-chave SEO.
        EcommerceLinkId:
          type: string
          nullable: true
          maxLength: 400
          description: Slug da URL do produto.
        EcommerceMetaTagDescription:
          type: string
          nullable: true
          maxLength: 3000
          description: Meta description (SEO).
        EcommerceTitle:
          type: string
          nullable: true
          maxLength: 200
          description: Título da página do produto.
        EcommerceVideoUrl:
          type: string
          nullable: true
          maxLength: 200
          description: URL de vídeo de demonstração.
        EcommerceKitAutomaticDescription:
          type: integer
          nullable: true
          description: '`1` compõe automaticamente a descrição do kit a partir dos componentes.'
        ShareProductImage:
          type: integer
          nullable: true
          description: '`1` compartilha as imagens do produto-pai com a variação.'
        AbcCurveAdjust:
          type: string
          nullable: true
          maxLength: 1
          description: Curva ABC ajustada manualmente (`A`, `B`, `C`).
        KitAutomaticMeasureUpdate:
          type: integer
          nullable: true
          description: '`1` para que medidas do kit sejam recalculadas automaticamente a partir dos componentes.'
        KitAutomaticPricingUpdate:
          type: integer
          nullable: true
          description: '`1` recalcula automaticamente o preço do kit.'
        BuyOrderAlert:
          type: integer
          nullable: true
          description: Liga alerta de pedido de compra quando estoque cai abaixo da quantidade configurada.
        BuyOrderAlertManualQuantity:
          type: integer
          nullable: true
          description: Quantidade que dispara o alerta de compra (`BuyOrderAlert=1`).
        Tags:
          type: array
          items:
            type: string
          description: Etiquetas livres do SKU (atualização substitui o conjunto inteiro).
    SkuImage:
      type: object
      description: Imagem do SKU.
      properties:
        IDImage:
          type: integer
          description: Identificador da imagem.
        IDSku:
          type: integer
          description: Identificador do SKU dono da imagem.
        Url:
          type: string
          nullable: true
          maxLength: 400
          description: URL pública da imagem no CDN.
        ImageName:
          type: string
          nullable: true
          maxLength: 300
          description: Nome original do arquivo enviado.
        ImageSize:
          type: integer
          nullable: true
          description: Tamanho do arquivo em bytes.
        ImageWidth:
          type: integer
          nullable: true
          description: Largura da imagem em pixels.
        ImageHeight:
          type: integer
          nullable: true
          description: Altura da imagem em pixels.
        ImageOrder:
          type: integer
          description: Ordem de exibição da imagem na galeria (números menores aparecem primeiro).
        IsMain:
          type: integer
          description: '`1` indica a imagem principal.'
        Kit:
          type: integer
          description: Identifica a qual kit (1-4) a imagem está associada.
        ShareProductImage:
          type: integer
          nullable: true
          description: '`1` quando a imagem é compartilhada com as variações do produto-pai.'
        ProductImage:
          type: integer
          nullable: true
          description: '`1` quando a imagem foi herdada do produto-pai.'
    KitItem:
      type: object
      description: Item (componente) de um kit.
      properties:
        AccountName:
          type: string
          description: Conta (subdomínio) da empresa.
        IDStockKeepingUnitKitItems:
          type: integer
          description: Identificador da linha do componente no kit.
        IDSkuComponent:
          type: integer
          description: Identificador do SKU usado como componente.
        Quantity:
          type: number
          description: Quantidade do componente no kit.
        Kit:
          type: integer
          description: Variante do kit (1 a 4).
        SkuName:
          type: string
          nullable: true
          description: Nome do SKU componente.
        IDSkuCompany:
          type: string
          nullable: true
          description: Código de referência interno do SKU componente.
        CostAverage:
          type: number
          nullable: true
          description: Custo médio unitário do componente.
        CostAverageTotal:
          type: number
          nullable: true
          description: Custo médio total da participação do componente no kit (`CostAverage * Quantity`).
        CostSet:
          type: number
          nullable: true
          description: Custo manual unitário do componente.
        CostSetTotal:
          type: number
          nullable: true
          description: Custo manual total da participação no kit.
        CostLastPurchase:
          type: number
          nullable: true
          description: Custo da última compra do componente (unitário).
        CostLastPurchaseTotal:
          type: number
          nullable: true
          description: Custo da última compra total para a participação no kit.
        QtyAvailable:
          type: number
          nullable: true
          description: Quantidade disponível do componente em estoque.
        PriceSell:
          type: number
          nullable: true
          description: Preço de venda unitário do componente.
        PriceSellTotal:
          type: number
          nullable: true
          description: Preço de venda total da participação do componente no kit.
        MainImageURL:
          type: string
          nullable: true
          description: URL da imagem principal do componente.
        MainImageThumbnailURL:
          type: string
          nullable: true
          description: URL da miniatura da imagem principal do componente.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora em que o componente foi adicionado ao kit.
    KitSummary:
      type: object
      description: Resumo de cada variante de kit (1 a 4) de um SKU pai.
      properties:
        index:
          type: integer
          description: >-
            Posição (1 a 4) do kit alternativo dentro do SKU. O sistema permite até 4 composições alternativas por kit
            (`Kit=1..4`).
        IDStockKeepingUnitKit:
          type: integer
          description: Identificador do registro de configuração do kit alternativo.
        Active:
          type: integer
          description: '`1` quando este kit é o ativo do SKU.'
        Kit:
          type: integer
          description: Número da variante (1 a 4).
        Priority:
          type: integer
          nullable: true
          description: Prioridade do kit alternativo na seleção automática durante a venda — menor valor é tentado primeiro.
        QtyAvailable:
          type: integer
          nullable: true
          description: Quantidade montável a partir do estoque dos componentes.
        QtySku:
          type: integer
          nullable: true
          description: Quantidade distinta de componentes.
        QtyItems:
          type: number
          nullable: true
          description: Soma das quantidades dos componentes.
        SumSellingPrice:
          type: number
          nullable: true
          description: Soma do preço de venda dos componentes dessa composição.
        SumListPrice:
          type: number
          nullable: true
          description: Soma do preço de tabela dos componentes.
        SumCostAverage:
          type: number
          nullable: true
          description: Soma do custo médio dos componentes.
        Markup:
          type: string
          nullable: true
          description: '`SumSellingPrice / SumCostAverage`, com duas casas.'
    SkuPricing:
      type: object
      description: Preço de um SKU em uma política comercial.
      properties:
        IDStockKeepingUnitPricing:
          type: integer
          description: Identificador do registro de preço.
        IDSku:
          type: integer
          description: Identificador do SKU precificado.
        IDCompanySalesPolicy:
          type: integer
          description: Identificador da política comercial (tabela de preço) a que o preço pertence.
        CompanySalesPolicy:
          type: string
          nullable: true
          description: Nome da política comercial.
        IDTypeCompanySalesPolicy:
          type: integer
          nullable: true
          description: 'Tipo da política comercial: `1` Normal, `2` Custo médio, `3` Relativa à outra política.'
          enum:
            - 1
            - 2
            - 3
        PriceList:
          type: number
          nullable: true
          description: Preço de tabela.
        PriceSell:
          type: number
          description: Preço de venda. Não pode ser zerado (vide regras da empresa).
        DateFrom:
          type: string
          format: date
          description: Vigência inicial. Default `1900-01-01`.
        DateTo:
          type: string
          format: date
          description: Vigência final. Default `4000-01-01`.
        AccountName:
          type: string
          description: Conta (subdomínio) da empresa.
        IDSkuCompany:
          type: string
          nullable: true
          description: Código de referência interno do SKU.
        BarCode:
          type: string
          nullable: true
          description: Código de barras principal do SKU.
        SkuName:
          type: string
          nullable: true
          description: Nome do SKU.
        TypeProduct:
          type: string
          nullable: true
          description: Descrição textual do tipo do SKU.
        IDTypeSku:
          type: integer
          nullable: true
          description: Tipo do SKU (vide enum em `IDTypeSku`).
        CostSet:
          type: number
          nullable: true
          description: Custo manual cadastrado.
        CostAverage:
          type: number
          nullable: true
          description: Custo médio calculado.
        CostLastPurchase:
          type: number
          nullable: true
          description: Custo da última compra.
        QtyAvailable:
          type: string
          nullable: true
          description: Quantidade disponível em estoque.
        InventoryValue:
          type: number
          nullable: true
          description: Valor monetário do estoque.
        Markup:
          type: number
          nullable: true
          description: >-
            Razão entre o preço de venda e o custo médio (`PriceSell / CostAverage`). Ex.: `2.5` indica que o preço é
            2,5× o custo médio. `null` quando `CostAverage <= 0` ou `PriceSell <= 0`.
        CompanyIntegration:
          type: string
          nullable: true
          description: Integrações que consomem essa política, concatenadas.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora de criação do preço.
        DateLastRecordModification:
          type: string
          format: date-time
          description: Data e hora da última alteração do preço.
    SkuPricingCreateBody:
      type: object
      description: Corpo para criar/atualizar um preço de SKU.
      required:
        - PriceSell
        - DateFrom
        - DateTo
      properties:
        PriceSell:
          type: number
          description: >-
            Preço de venda. Rejeitado quando zerado e a empresa não permite preço de venda zerado. Numa política do tipo
            Relativa à outra política (`IDTypeCompanySalesPolicy=3`), é recalculado a partir do preço da política base e
            o valor enviado é ignorado.
        PriceList:
          type: number
          nullable: true
          description: Preço de tabela. Numa política Relativa à outra política, é recalculado a partir da política base.
        DateFrom:
          type: string
          format: date
          description: Início da vigência do preço. Obrigatório e deve ser uma data válida.
        DateTo:
          type: string
          format: date
          description: Fim da vigência do preço. Obrigatório e deve ser uma data válida.
        IDCompanySalesPolicy:
          type: integer
          nullable: true
          description: >-
            Política comercial (tabela de preço) à qual o preço pertence. Quando omitido, usa a política padrão da
            empresa.
    SkuSerial:
      type: object
      description: Número de série de um SKU.
      properties:
        IDStockKeepingUnitSerialNumber:
          type: integer
          description: Identificador do registro de número de série.
        IDSku:
          type: integer
          description: Identificador do SKU controlado por número de série.
        SerialNumber:
          type: string
          maxLength: 45
          description: Número de série único da unidade.
        IDSkuMovementInbound:
          type: integer
          nullable: true
          description: Identificador da movimentação de entrada que cadastrou este número de série.
        IDSkuMovementOutbound:
          type: integer
          nullable: true
          description: Identificador da movimentação de saída que consumiu este número de série (quando aplicável).
        IDTypeStatusSkuSerialNumber:
          type: integer
          description: 'Status do número de série: `1` Disponível, `2` Bloqueado, `3` Utilizado.'
          enum:
            - 1
            - 2
            - 3
        TypeStatusSkuSerialNumber:
          type: string
          nullable: true
          description: Status do número de série (em estoque, vendido, em garantia, etc.).
        IDPurchase:
          type: integer
          nullable: true
          description: Recebimento (entrada) que vinculou o serial.
        IDOrder:
          type: integer
          nullable: true
          description: Pedido (saída) que consumiu o serial.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora de criação do registro.
    SkuCollectionAssociation:
      type: object
      description: Vínculo entre SKU e coleção.
      properties:
        IDStockKeepingUnitCollectionAssociation:
          type: integer
          description: Identificador da associação SKU↔coleção.
        IDSku:
          type: integer
          description: Identificador do SKU associado à coleção.
        IDStockKeepingUnitCollection:
          type: integer
          description: Identificador da coleção.
        StockKeepingUnitCollectionName:
          type: string
          nullable: true
          description: Nome da coleção.
        AccountName:
          type: string
          description: Conta (subdomínio) da empresa.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora em que o SKU foi adicionado à coleção.
    SkuGroupAssociation:
      type: object
      description: Vínculo entre SKU e grupo de SKU.
      properties:
        IDStockKeepingUnitGroupAssociation:
          type: integer
          description: Identificador da associação SKU↔grupo.
        IDSku:
          type: integer
          description: Identificador do SKU.
        IDStockKeepingUnitGroup:
          type: integer
          description: Identificador do grupo de SKUs.
        SkuGroupName:
          type: string
          nullable: true
          description: Nome do grupo.
        AccountName:
          type: string
          description: Conta (subdomínio) da empresa.
        StockKeepingUnitSimilarCode:
          type: array
          description: Códigos similares cadastrados no grupo.
          items:
            type: object
            properties:
              IDStockKeepingUnitSimilarCode:
                type: integer
                description: Identificador do código similar vinculado ao SKU dentro deste grupo.
              SkuSimilarCode:
                type: string
                description: Código de referência similar (texto livre, usado para mapear o SKU em sistemas externos).
              SkuSimilarCodeTag:
                type: string
                nullable: true
                description: 'Etiqueta/categoria do código similar (ex.: nome do canal ou marketplace que utiliza esse código).'
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora em que o SKU foi vinculado ao grupo.
    SkuVariationValue:
      type: object
      description: 'Valor de variação (grade) atribuído ao SKU. Ex.: variação `Cor` com valor `Azul`.'
      properties:
        IDStockKeepingUnitVariation:
          type: integer
          description: Identificador do registro de variação do SKU.
        IDSku:
          type: integer
          description: Identificador do SKU variação.
        IDTypeProductVariation:
          type: integer
          description: 'Identificador do tipo de variação (ex.: cor, tamanho).'
        ProductVariation:
          type: string
          nullable: true
          description: 'Nome da variação (ex.: `Cor`).'
        IDTypeProductVariationValue:
          type: integer
          description: 'Identificador do valor da variação (ex.: azul, M).'
        TypeProductVariationValue:
          type: string
          nullable: true
          description: 'Valor da variação (ex.: `Azul`).'
    SkuProductVariation:
      type: object
      description: Associação entre um SKU variação e o seu produto-pai.
      properties:
        IDStockKeepingUnitProductVariation:
          type: integer
          description: Identificador do vínculo entre SKU pai e SKU variação.
        IDProduct:
          type: integer
          description: SKU produto-pai.
        IDSku:
          type: integer
          description: SKU variação filho.
        SkuName:
          type: string
          nullable: true
          description: Nome da variação.
        BarCode:
          type: string
          nullable: true
          description: Código de barras principal da variação.
        IDSkuCompany:
          type: string
          nullable: true
          description: Código de referência interno da variação.
        AccountName:
          type: string
          description: Conta (subdomínio) da empresa.
        TypeProduct:
          type: string
          nullable: true
          description: Descrição textual do tipo do SKU.
        IDTypeSku:
          type: integer
          nullable: true
          description: Tipo do SKU (vide enum em `IDTypeSku`).
        MeasurementUnit:
          type: string
          nullable: true
          description: Unidade de medida.
        MeasurementUnitDescription:
          type: string
          nullable: true
          description: Descrição da unidade de medida.
        SkuHeight:
          type: number
          nullable: true
          description: Altura em cm.
        SkuLength:
          type: number
          nullable: true
          description: Comprimento em cm.
        SkuWidth:
          type: number
          nullable: true
          description: Largura em cm.
        SkuWeight:
          type: number
          nullable: true
          description: Peso bruto em kg.
        SkuWeightNet:
          type: number
          nullable: true
          description: Peso líquido em kg.
        SkuNCM:
          type: string
          nullable: true
          description: Código NCM.
        SkuCest:
          type: string
          nullable: true
          description: Código CEST.
        SkuCst:
          type: integer
          nullable: true
          description: Origem do SKU (CST).
        SkuCstDescription:
          type: string
          nullable: true
          description: Descrição textual da origem.
        SkuNCMExTipi:
          type: string
          nullable: true
          description: Ex TIPI do NCM.
        IDTaxDepartment:
          type: integer
          nullable: true
          description: Identificador do departamento fiscal.
        TaxDepartmentDescription:
          type: string
          nullable: true
          description: Descrição do departamento fiscal.
        MainImageURL:
          type: string
          nullable: true
          description: URL da imagem principal da variação.
        ShareProductImage:
          type: integer
          nullable: true
          description: '`1` quando a variação reusa as imagens do produto-pai.'
        IDStatusSku:
          type: integer
          description: 'Status da variação: `1` Ativo, `2` Compra suspensa, `3` Inativo, `4` Venda suspensa.'
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
        TypeStatusSku:
          type: string
          nullable: true
          description: Descrição textual do status.
        ProductVariation:
          type: string
          nullable: true
          description: Variações ordenadas, concatenadas (`Cor,Tamanho`).
        TypeProductVariationValue:
          type: string
          nullable: true
          description: Valores correspondentes (`Azul,M`).
        TypeProductVariationValueOrder:
          type: string
          nullable: true
          description: 'Ordenação concatenada das variações (ex.: `Azul-M`) — usada para classificar a variação na grade.'
        ProductVariationArray:
          type: array
          description: Variações expandidas em pares nome/valor.
          items:
            type: object
            properties:
              ProductVariation:
                type: string
                description: 'Nome do tipo de variação (ex.: `Cor`).'
              TypeProductVariationValue:
                type: string
                description: 'Valor da variação (ex.: `Azul`).'
        PriceSell:
          type: number
          nullable: true
          description: Preço de venda da variação.
        PriceList:
          type: number
          nullable: true
          description: Preço de tabela da variação.
        QtyAvailable:
          type: string
          nullable: true
          description: Quantidade disponível em estoque.
    SkuSpecificationField:
      type: object
      description: Campo de especificação técnica disponível para o SKU, com valor atual quando preenchido.
      properties:
        IDStockKeepingUnitSpecificationsFieldId:
          type: integer
          description: Identificador do campo de especificação cadastrado para a categoria.
        IDStockKeepingUnitSpecifications:
          type: integer
          nullable: true
          description: Identificador do valor de especificação preenchido para este SKU (quando já foi salvo).
        FieldName:
          type: string
          description: 'Nome do campo de especificação (ex.: `Voltagem`, `Material`).'
        IDStockKeepingUnitSpecificationsFieldTypes:
          type: integer
          description: 'Tipo do campo: `1` texto, `2` número, `3` data, `4` combo único, `5` combo múltiplo, `6` radio.'
        FieldType:
          type: string
          nullable: true
          description: Tipo de dado do campo (`text`, `number`, `select`, `date`, etc.).
        IDFieldExternal:
          type: string
          nullable: true
          description: Identificador externo do campo (mapeamento para marketplaces ou hubs).
        IDCategory:
          type: integer
          description: Categoria à qual o campo pertence.
        CategoryName:
          type: string
          nullable: true
          description: Nome da categoria.
        FieldValue:
          description: >-
            Para tipos texto/número/data, o valor literal. Para tipos combo/radio, array de objetos
            `{IDStockKeepingUnitSpecificationsFieldValues, Value}`.
    SkuLogItem:
      type: object
      description: Registro de log de integração de SKU.
      properties:
        IDStockKeepingUnitIntegrationLog:
          type: integer
          description: Identificador da linha de log de integração.
        AccountName:
          type: string
          description: Conta (subdomínio) da empresa.
        IDSku:
          type: integer
          description: Identificador do SKU integrado.
        IDSkuCompany:
          type: string
          nullable: true
          description: Código de referência interno do SKU.
        SkuName:
          type: string
          nullable: true
          description: Nome do SKU.
        Comments:
          type: string
          nullable: true
          description: Detalhe da operação (mensagem de erro ou JSON do corpo).
        Header:
          type: integer
          description: '`1` sucesso, `2` inativo, demais valores = erro.'
        Status:
          type: string
          description: Tradução de `Header` (`Sucesso`, `Inativo`, `Erro`).
        IDAction:
          type: integer
          description: Tipo de ação registrada (`IDSkuAction`).
        ActionName:
          type: string
          nullable: true
          description: 'Ação executada na integração (ex.: `Create`, `Update`, `Delete`, `Stock`, `Price`).'
        IDHubProduct:
          type: integer
          nullable: true
          description: Identificador do produto no Hub (intermediário entre o idworks e o canal de venda).
        IDCompanyIntegration:
          type: integer
          nullable: true
          description: Identificador da integração (loja/marketplace) que originou o log.
        CompanyIntegration:
          type: string
          nullable: true
          description: Nome da integração no formato `Tipo - Nome`.
        RecordUserCreated:
          type: string
          nullable: true
          description: Login do usuário que disparou o registro.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora do log.
    SkuWarehouseBalance:
      type: object
      description: Saldo do SKU em um armazém, com detalhamento por pedido/produção/recebimento/ressuprimento.
      properties:
        AccountName:
          type: string
          description: Conta (subdomínio) da empresa.
        IDStockKeepingUnitWarehouse:
          type: integer
          description: Identificador do depósito.
        WarehouseName:
          type: string
          nullable: true
          description: Nome do depósito.
        Default:
          type: integer
          nullable: true
          description: '`1` quando este é o depósito padrão da empresa.'
        IDStockKeepingUnitDistributionCenter:
          type: integer
          description: Centro de distribuição ao qual o depósito pertence.
        DistributionCenterName:
          type: string
          nullable: true
          description: Nome do centro de distribuição.
        QtyAvailable:
          type: string
          description: Quantidade disponível neste depósito.
        QtyOnStock:
          type: string
          description: Disponível + reservado + em separação.
        QtyReserved:
          type: string
          description: Quantidade reservada em pedidos não faturados.
        QtyHandling:
          type: string
          description: Em separação (picking/packing).
        QtyBuyOrdem:
          type: string
          description: Pedido de compra menos o já recebido.
        QtyToReceipt:
          type: string
          description: Em recebimento.
        QtyProduction:
          type: string
          description: Em produção.
        QtyResupply:
          type: string
          description: Em ressuprimento.
        InventoryValue:
          type: number
          nullable: true
          description: Valor monetário do saldo no depósito (`CostAverage * QtyAvailable`).
        CostAverage:
          type: string
          nullable: true
          description: Custo médio aplicado a este depósito.
        QtyReservedOrders:
          type: array
          items:
            type: object
            properties:
              RecordTimestamp:
                type: string
                format: date-time
                description: Data e hora de criação do pedido reservado.
              IDOrder:
                type: integer
                description: Identificador do pedido de venda.
              IDStatusOrder:
                type: integer
                description: Status do pedido (vide tabela de status de pedido).
              Order:
                type: string
                description: Número de exibição do pedido.
              StatusOrder:
                type: string
                description: Descrição textual do status do pedido.
              Quantity:
                type: number
                description: Quantidade reservada por este pedido.
          description: Pedidos de venda em aberto que reservam estoque neste depósito.
        QtyHandlingOrders:
          type: array
          items:
            type: object
            properties:
              RecordTimestamp:
                type: string
                format: date-time
                description: Data e hora de criação do pedido em manuseio.
              IDOrder:
                type: integer
                description: Identificador do pedido.
              IDStatusOrder:
                type: integer
                description: Status do pedido.
              Order:
                type: string
                description: Número de exibição do pedido.
              StatusOrder:
                type: string
                description: Descrição textual do status.
              Quantity:
                type: number
                description: Quantidade em manuseio para este pedido.
          description: Pedidos em manuseio/separação que estão consumindo estoque deste depósito.
        QtyProductionOrders:
          type: array
          items:
            type: object
            properties:
              RecordTimestamp:
                type: string
                format: date-time
                description: Data e hora de criação da ordem.
              IDStockKeepingUnitProduction:
                type: integer
                description: Identificador da ordem de produção.
              IDTypeStatusSkuProduction:
                type: integer
                description: 'Status da etapa de produção: `1` Finalizado, `2` Aberto, `3` Em andamento, `4` Cancelado.'
                enum:
                  - 1
                  - 2
                  - 3
                  - 4
              TypeStatusSkuProduction:
                type: string
                description: Descrição textual do status.
              Quantity:
                type: number
                description: Quantidade prevista pela ordem de produção.
          description: Ordens de produção em aberto que vão gerar entrada futura no depósito.
        QtyBuyOrdemOrders:
          type: array
          items:
            type: object
            properties:
              RecordTimestamp:
                type: string
                format: date-time
                description: Data e hora de criação do pedido de compra.
              IDBuyOrder:
                type: integer
                description: Identificador do pedido de compra.
              IDStatusBuyOrder:
                type: integer
                description: Status do pedido de compra.
                enum:
                  - 0
                  - 1
                  - 2
                  - 3
                  - 5
                  - 6
                  - 7
              StatusBuyOrder:
                type: string
                description: Descrição textual do status.
              Quantity:
                type: number
                description: Quantidade pedida.
          description: Pedidos de compra em aberto que vão gerar entrada futura no depósito.
        QtyToReceiptOrders:
          type: array
          items:
            type: object
            properties:
              RecordTimestamp:
                type: string
                format: date-time
                description: Data e hora de criação do recebimento.
              IDPurchase:
                type: integer
                description: Identificador do recebimento.
              IDStatusPurchase:
                type: integer
                description: Status do recebimento.
              StatusPurchase:
                type: string
                description: Descrição textual do status.
              Quantity:
                type: number
                description: Quantidade a receber.
          description: Recebimentos (compras) em aberto pendentes de entrada efetiva.
        QtyToResupply:
          type: array
          items:
            type: object
            properties:
              RecordTimestamp:
                type: string
                format: date-time
                description: Data e hora de criação do ressuprimento.
              IDStockKeepingUnitResupplyList:
                type: integer
                description: Identificador do ressuprimento.
              IDResupplyStatus:
                type: integer
                description: 'Status do ressuprimento: `1` Aberto, `2` Iniciado, `3` Finalizado, `4` Cancelado.'
                enum:
                  - 1
                  - 2
                  - 3
                  - 4
              StatusResupply:
                type: string
                description: Descrição textual do status.
              Quantity:
                type: number
                description: Quantidade do ressuprimento.
          description: Ressuprimentos pendentes que vão movimentar estoque do/para este depósito.
    SkuPackageItem:
      type: object
      description: SKU embalagem (`Package=1`) compartilhado entre empresas integradas via DE-PARA.
      properties:
        IDSku:
          type: integer
          description: Identificador do SKU embalagem.
        AccountName:
          type: string
          description: Conta (subdomínio) da empresa.
        Package:
          type: integer
          description: '`1` confirma que o SKU é uma embalagem master (caixa/fardo).'
        IDTypeSku:
          type: integer
          description: Tipo do SKU.
        IDSkuCompany:
          type: string
          nullable: true
          description: Código de referência interno do SKU.
        SkuName:
          type: string
          nullable: true
          description: Nome da embalagem.
        BarCode:
          type: string
          nullable: true
          description: Código de barras principal.
        Batch:
          type: integer
          description: '`1` quando a embalagem controla lote.'
        IDBrand:
          type: integer
          nullable: true
          description: Identificador da marca.
        SkuNCM:
          type: string
          nullable: true
          description: Código NCM.
        IDTaxDepartment:
          type: integer
          nullable: true
          description: Identificador do departamento fiscal.
        IDCategory:
          type: integer
          nullable: true
          description: Identificador da categoria.
        OwnProduction:
          type: integer
          description: '`1` quando a embalagem é de produção própria.'
        EcommerceDescription:
          type: string
          nullable: true
          description: Descrição da embalagem para vitrine de e-commerce.
        SkuCst:
          type: integer
          nullable: true
          description: Origem do SKU (CST).
        SkuCest:
          type: string
          nullable: true
          description: Código CEST.
        CostSet:
          type: number
          nullable: true
          description: Custo manual.
        CostAverage:
          type: number
          nullable: true
          description: Custo médio.
        CostLastPurchase:
          type: number
          nullable: true
          description: Custo da última compra.
        SkuHeight:
          type: number
          nullable: true
          description: Altura em cm.
        SkuLength:
          type: number
          nullable: true
          description: Comprimento em cm.
        SkuWidth:
          type: number
          nullable: true
          description: Largura em cm.
        SkuWeight:
          type: number
          nullable: true
          description: Peso bruto em kg.
        QtyAvailable:
          type: string
          description: Quantidade disponível em estoque.
    SkuTag:
      type: object
      description: Etiqueta livre de SKU.
      properties:
        Tag:
          type: string
          description: Texto livre da etiqueta cadastrada no SKU.
        AccountName:
          type: string
          description: Conta (subdomínio) da empresa dona da etiqueta.
    SkuSimilarCategory:
      type: object
      description: Categoria similar associada ao SKU.
      properties:
        IDStockKeepingUnitSimilarCategory:
          type: integer
          description: Identificador da associação categoria-similar do SKU.
        IDCategory:
          type: integer
          description: Identificador da categoria considerada similar.
        CategoryTree:
          type: string
          nullable: true
          description: Caminho completo da categoria (`Pai -> Filha -> Neta`).
    JobScheduledResponse:
      type: object
      description: >-
        Resposta de confirmação de um job assíncrono (`statusCode` + `body`). O formato exato do `body` varia conforme o
        tipo de job.
      properties:
        statusCode:
          type: integer
          description: >-
            Status HTTP do retorno imediato — `202` indica que o job foi aceito e enfileirado para processamento em
            background; o resultado final não vem nesta resposta.
        body:
          type: string
          description: Conteúdo JSON ou texto plano, dependendo do tipo de job.
      additionalProperties: true
    OrderItem:
      type: object
      description: Item de pedido — produto vendido, com quantidade, preço e dados fiscais.
      properties:
        IDSku:
          type: integer
          description: Identificador do produto.
        IDCategory:
          type: integer
          nullable: true
          description: Identificador da categoria do produto.
        IDCategoryArray:
          type: array
          items:
            type: string
          description: Cadeia de categorias (da raiz até a folha) do produto.
        CommentsInvoice:
          type: string
          nullable: true
          description: Observações deste item na nota fiscal.
        SkuName:
          type: string
          description: Nome completo do produto (inclui prefixo da variação quando aplicável).
        SkuNameOnly:
          type: string
          nullable: true
          description: >-
            Nome do produto sem o prefixo da variação. Removido da resposta quando a parametrização `OnlySkuName` está
            ligada.
        ReverseTaxCalculation:
          type: integer
          enum:
            - 0
            - 1
          description: Quando `1`, ICMS-ST/IPI/FCP-ST somam ao total do item; quando `0`, já estão embutidos no preço.
        NfeCFOP:
          type: string
          nullable: true
          description: CFOP fiscal aplicado a este item.
        NfeIcmsCst:
          type: string
          nullable: true
          description: CST do ICMS.
        SkuWeightTotal:
          type: number
          nullable: true
          description: Peso total (peso unitário x quantidade) em kg.
        IDTypeSku:
          type: integer
          nullable: true
          description: Tipo do produto (`StockKeepingUnit`, `Kit`, etc.).
        NfeIbsCbsCST:
          type: string
          nullable: true
          description: CST IBS/CBS (reforma tributária).
        NfeIbsCbsBaseCal:
          type: number
          nullable: true
          description: Base de cálculo IBS/CBS.
        NfeIbsAliquot:
          type: number
          nullable: true
          description: Alíquota IBS.
        NfeIbspRedAliquot:
          type: number
          nullable: true
          description: Percentual de redução da alíquota IBS.
        NfeIbsValue:
          type: number
          nullable: true
          description: Valor de IBS.
        NfeCbsAliquot:
          type: number
          nullable: true
          description: Alíquota CBS.
        NfeCbspRedAliquot:
          type: number
          nullable: true
          description: Percentual de redução da alíquota CBS.
        NfeCbsValue:
          type: number
          nullable: true
          description: Valor de CBS.
        AbcCurve:
          type: string
          nullable: true
          description: Classificação ABC do produto.
        Quantity:
          type: number
          description: Quantidade vendida.
        PriceSelling:
          type: number
          description: Preço unitário de venda (já com desconto aplicado).
        PriceList:
          type: number
          description: Preço unitário de tabela (antes do desconto).
        ValueDiscount:
          type: number
          nullable: true
          description: Valor unitário de desconto aplicado.
        PercentDiscount:
          type: number
          nullable: true
          description: Percentual de desconto sobre o preço de tabela.
        PriceSellingTotal:
          type: number
          description: Total do item (preço unitário com desconto x quantidade).
        IDSkuMovement:
          type: integer
          description: Identificador da movimentação deste item.
        QtyAvailable:
          type: number
          description: Quantidade disponível em estoque no armazém do item.
        PackageNumber:
          type: integer
          nullable: true
          description: Número do pacote ao qual este item foi alocado.
        BarCode:
          type: string
          nullable: true
          description: Código de barras do produto.
        IDSkuCompany:
          type: string
          nullable: true
          description: Código interno do produto (SKU da empresa).
        AccountName:
          type: string
          description: Subdomínio da empresa proprietária do produto.
        Batch:
          type: integer
          nullable: true
          description: Identificador do lote (`IDBatch`).
        MainImageURL:
          type: string
          nullable: true
          description: URL da imagem principal do produto.
        BestBeforeDate:
          type: string
          format: date
          nullable: true
          description: Validade do lote.
        Address:
          type: string
          nullable: true
          description: Endereço de estoque do lote (corredor/prateleira).
        IDStockKeepingUnitLocation:
          type: integer
          nullable: true
          description: Identificador do endereço de estoque.
        AddressDefault:
          type: string
          nullable: true
          description: Endereço de estoque padrão do produto no armazém.
        QuantityNonconformity:
          type: number
          nullable: true
          description: Quantidade não conforme apurada no atendimento.
        IDTypeFulfillmentNonconformity:
          type: integer
          nullable: true
          description: Tipo da não conformidade.
          enum:
            - 1
            - 2
            - 4
            - 5
            - 6
        TypeFulfillmentNonconformity:
          type: string
          nullable: true
          description: Descrição do tipo de não conformidade.
        IDStockKeepingUnitWarehouse:
          type: integer
          nullable: true
          description: Armazém de origem do item.
        WarehouseName:
          type: string
          nullable: true
          description: Nome do armazém.
        IDTaxDepartment:
          type: integer
          nullable: true
          description: Departamento fiscal do produto.
        TaxDepartmentDescription:
          type: string
          nullable: true
          description: Descrição do departamento fiscal.
        SkuNCM:
          type: string
          nullable: true
          description: NCM do produto.
        SkuCst:
          type: string
          nullable: true
          description: Origem da mercadoria (CST de origem).
        NfOrigDescription:
          type: string
          nullable: true
          description: Descrição da origem da mercadoria.
        Comments:
          type: string
          nullable: true
          description: Observações deste item.
        IDSkuKit:
          type: integer
          nullable: true
          description: Quando o item é componente de um kit, traz o identificador do kit pai.
        QuantityKit:
          type: number
          nullable: true
          description: Quantidade do kit.
        KitSkuName:
          type: string
          nullable: true
          description: Nome do kit pai.
        KitIDSkuCompany:
          type: string
          nullable: true
          description: Código interno do kit pai.
        KitBarCode:
          type: string
          nullable: true
          description: Código de barras do kit pai.
        Gratification:
          type: integer
          enum:
            - 0
            - 1
          description: Quando `1`, o item é brinde/bonificação e não compõe o valor do pedido.
        NfeNItemPed:
          type: string
          nullable: true
          description: Número do item no pedido externo (referência para integrações fiscais).
        NfeValueFcpSt:
          type: number
          description: Valor FCP-ST do item.
        NfeValueIpi:
          type: number
          description: Valor IPI do item.
        NfeValueIcmsST:
          type: number
          description: Valor ICMS-ST do item.
        EstimatedDeliveredDate:
          type: string
          format: date
          nullable: true
          description: Previsão de entrega informada pelo fornecedor para itens vinculados a pedido de compra.
        IDBuyOrder:
          type: integer
          nullable: true
          description: Pedido de compra que abastecerá este item.
        BrandName:
          type: string
          nullable: true
          description: Marca do produto.
        SerialNumberUsed:
          type: string
          nullable: true
          description: Lista de números de série utilizados na saída (separados por vírgula).
        IDSalesmanComission:
          type: integer
          nullable: true
          description: Regra de comissão aplicada a este item.
        ComissionPercent:
          type: number
          nullable: true
          description: Percentual de comissão calculado para este item.
        ComissionValue:
          type: number
          nullable: true
          description: Valor de comissão deste item.
        ValueOrderItem:
          type: number
          description: Valor do item somando, quando aplicável, ICMS-ST/IPI/FCP-ST por fora.
    OrderPayment:
      type: object
      description: Parcela / título financeiro vinculado ao pedido (forma de pagamento).
      properties:
        PaymentDescription:
          type: string
          nullable: true
          description: Descrição do tipo de pagamento.
        Category:
          type: string
          nullable: true
          description: Categoria do tipo de pagamento (cartão, boleto, dinheiro, etc.).
        Installment:
          type: integer
          description: Número da parcela.
        InstallmentTotal:
          type: integer
          description: Total de parcelas.
        DateDue:
          type: string
          format: date
          description: Data de vencimento.
        Value:
          type: number
          description: Valor da parcela.
        IDAccountPayableReceivable:
          type: integer
          description: Identificador da conta a receber.
        TID:
          type: string
          nullable: true
          description: TID retornado pela adquirente / identificador externo.
        NSU:
          type: string
          nullable: true
          description: NSU retornado pela adquirente.
        IDTypePayment:
          type: integer
          description: Identificador do tipo de pagamento.
        IDConsumer:
          type: integer
          nullable: true
          description: Identificador do cliente pagador (quando difere do cliente do pedido).
        IDTypeAccountPayableReceivable:
          type: integer
          nullable: true
          description: Subtipo financeiro (plano de contas).
        TypeAccountPaybleDescription:
          type: string
          nullable: true
          description: Descrição do plano de contas.
        IDTypeDocument:
          type: integer
          nullable: true
          description: Tipo de documento financeiro.
        BankSlipBarCode:
          type: string
          nullable: true
          description: Linha digitável do boleto, quando emitido.
        BankSlipUrl:
          type: string
          nullable: true
          description: URL do PDF do boleto.
        StatusBankSlip:
          type: string
          nullable: true
          description: Status atual do boleto.
        IDCompanyIntegration:
          type: integer
          nullable: true
          description: Integração (adquirente) que originou o pagamento.
        DaysDue:
          type: integer
          nullable: true
          description: Dias para vencimento contados da data do pedido.
        CompanyIntegration:
          type: string
          nullable: true
          description: Nome da integração de pagamento.
        Bank:
          type: string
          nullable: true
          description: Banco previsto para recebimento.
        IDBankAccountForecast:
          type: integer
          nullable: true
          description: Conta bancária prevista para recebimento.
        Comments:
          type: string
          nullable: true
          description: Observações da parcela.
    OrderPackage:
      type: object
      description: Pacote / volume gerado para o pedido (etiqueta de envio).
      properties:
        ShippingDate:
          type: string
          format: date-time
          nullable: true
          description: Data/hora do envio do pacote.
        IDPackage:
          type: integer
          description: Identificador do pacote.
        StatusPackage:
          type: string
          description: Status do pacote (criado, em separação, enviado, etc.).
        ShippingId:
          type: string
          nullable: true
          description: Código de postagem retornado pela transportadora.
        ShippingPlp:
          type: string
          nullable: true
          description: Pré-lista de postagem (PLP).
        PackageNumber:
          type: integer
          description: Número sequencial do pacote dentro do pedido.
        IDOrdersCarrierCollectionList:
          type: integer
          nullable: true
          description: Romaneio em que o pacote foi incluído.
        PackageWeight:
          type: number
          description: Peso do pacote (kg). Quando não informado, o sistema calcula pelo peso dos itens.
        PackageHeight:
          type: number
          description: Altura do pacote (cm).
        PackageLength:
          type: number
          description: Comprimento do pacote (cm).
        PackageWidth:
          type: number
          description: Largura do pacote (cm).
        UrlLabel:
          type: string
          nullable: true
          description: URL para visualizar a etiqueta do pacote. Null quando o pedido tem mais de 500 pacotes.
        UrlLabelDownload:
          type: string
          nullable: true
          description: URL para baixar a etiqueta. Null quando o pedido tem mais de 500 pacotes.
        TrackingUrl:
          type: string
          description: URL pública de rastreamento.
    OrderEvent:
      type: object
      description: Evento registrado no histórico do pedido.
      properties:
        RecordTimestamp:
          type: string
          format: date-time
          description: Quando o evento aconteceu.
        Comments:
          type: string
          nullable: true
          description: Detalhes do evento.
        Event:
          type: string
          description: Descrição do tipo de evento.
        RecordUserCreated:
          type: string
          description: Usuário que registrou o evento (nome - login).
        Status:
          type: string
          description: Cabeçalho do evento (informativo, alerta, erro).
        IDOrderEvents:
          type: integer
          description: Identificador do evento.
    OrderFile:
      type: object
      description: Arquivo (XML/DANFE) vinculado à nota fiscal principal do pedido.
      properties:
        RecordTimestamp:
          type: string
          format: date-time
          description: Quando o arquivo foi vinculado.
        IDFile:
          type: integer
          description: Identificador do arquivo.
        IDTypeFile:
          type: integer
          description: Tipo do arquivo (XML, DANFE etc.).
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 7
            - 8
        TypeFile:
          type: string
          description: Descrição do tipo de arquivo.
        UrlFileXml:
          type: string
          description: URL para baixar o XML.
        UrlFileDanfe:
          type: string
          description: URL para baixar a DANFE em PDF.
        UrlFileDanfeSimplificado:
          type: string
          description: URL para a DANFE simplificada (impressão por etiqueta).
    OrderNfeImportAddition:
      type: object
      description: Adição vinculada a uma DI (Declaração de Importação).
      properties:
        RecordTimestamp:
          type: string
          format: date-time
          description: Data de inclusão da adição.
        NfeImportnAdicao:
          type: string
          description: Número da adição na DI.
        NfeImportnSeqAdic:
          type: string
          nullable: true
          description: Número sequencial do item dentro da adição.
        NfeImportcFabricante:
          type: string
          nullable: true
          description: Código do fabricante estrangeiro.
        NfeImportvDescDI:
          type: number
          nullable: true
          description: Valor de desconto da DI.
        NfeImportnDraw:
          type: string
          nullable: true
          description: Número do drawback, quando aplicável.
        IDOrdersInvoiceImportAdditions:
          type: integer
          description: Identificador interno da adição.
    OrderDetail:
      type: object
      description: Detalhe completo do pedido — cabeçalho, itens, pagamentos, pacotes, eventos, arquivos e dados fiscais.
      properties:
        IDOrder:
          type: integer
          description: Identificador do pedido.
        Order:
          type: string
          nullable: true
          description: Número do pedido (visível ao usuário).
        Budget:
          type: integer
          enum:
            - 0
            - 1
          description: Quando `1`, o registro é um orçamento; quando `0`, é um pedido efetivado.
        Checked:
          type: integer
          nullable: true
          description: Marcação de conferência interna.
        Recordtimestamp:
          type: string
          format: date-time
          description: Quando o pedido foi criado.
        IDStatusOrder:
          type: integer
          description: Status atual do pedido.
        StatusOrder:
          type: string
          description: Descrição do status do pedido.
        StatusColorCode:
          type: string
          nullable: true
          description: Cor exibida na lista para o status.
        IDOrderType:
          type: integer
          description: Tipo de pedido (venda, devolução, transferência, etc.).
        TypeOrder:
          type: string
          description: Descrição do tipo de pedido.
        Return:
          type: integer
          enum:
            - 0
            - 1
          description: Quando `1`, o tipo de pedido é uma devolução.
        ServiceRequest:
          type: integer
          enum:
            - 0
            - 1
          description: Quando `1`, o tipo de pedido é uma ordem de serviço.
        IDServiceOrder:
          type: integer
          nullable: true
          description: Ordem de serviço vinculada, quando o tipo de pedido é serviço.
        IDCompany:
          type: integer
          description: Empresa proprietária do pedido.
        AccountName:
          type: string
          description: Subdomínio da empresa.
        CompanyNameCorporateName:
          type: string
          description: Razão social da empresa.
        CompanyTradeName:
          type: string
          nullable: true
          description: Nome fantasia da empresa.
        CompanyLogoUrl:
          type: string
          nullable: true
          description: URL do logo da empresa.
        IDCompanyInvoice:
          type: integer
          nullable: true
          description: Empresa faturadora (quando o pedido é faturado por uma filial).
        AccountNameInvoice:
          type: string
          nullable: true
          description: Subdomínio da faturadora.
        CompanyNameCorporateNameInvoice:
          type: string
          nullable: true
          description: Razão social da faturadora.
        CompanyBudgetHeaderImageUrl:
          type: string
          nullable: true
          description: Imagem de cabeçalho do orçamento.
        CompanyInvoiceLogoUrl:
          type: string
          nullable: true
          description: Logo da faturadora.
        CompanyInvoiceCpfCnpj:
          type: string
          nullable: true
          description: CNPJ/CPF da faturadora.
        CompanyInvoiceAddressState:
          type: string
          nullable: true
          description: UF da faturadora.
        CompanyInvoiceCompanyTradeName:
          type: string
          nullable: true
          description: Nome fantasia da faturadora.
        CompanyInvoiceCompanyAddressStreet:
          type: string
          nullable: true
          description: Endereço da faturadora — rua.
        CompanyInvoiceCompanyAddressCity:
          type: string
          nullable: true
          description: Endereço da faturadora — cidade.
        CompanyInvoiceCompanyAddressComplement:
          type: string
          nullable: true
          description: Endereço da faturadora — complemento.
        CompanyInvoiceCompanyAddressNeighborhood:
          type: string
          nullable: true
          description: Endereço da faturadora — bairro.
        CompanyInvoiceCompanyAddressNumber:
          type: string
          nullable: true
          description: Endereço da faturadora — número.
        CompanyInvoiceCompanyAddressPostalCode:
          type: string
          nullable: true
          description: Endereço da faturadora — CEP.
        CompanyInvoiceStateInscription:
          type: string
          nullable: true
          description: Inscrição estadual da faturadora no estado de destino.
        NfeRegimeTributario:
          type: integer
          nullable: true
          description: >-
            Regime tributário da faturadora (CRT: `1`=Simples Nacional, `2`=Simples Nacional excesso sublimite,
            `3`=Regime Normal, `4`=MEI).
        IDConsumer:
          type: integer
          nullable: true
          description: Cliente do pedido.
        ConsumerType:
          type: integer
          nullable: true
          description: 'Tipo do cliente: `1` Pessoa Física, `2` Pessoa Jurídica, `3` Estrangeiro.'
          enum:
            - 1
            - 2
            - 3
        ConsumerNameCorporateName:
          type: string
          nullable: true
          description: Nome / razão social do cliente.
        ConsumerCpfCnpj:
          type: string
          nullable: true
          description: CPF/CNPJ do cliente.
        ConsumerEmail:
          type: string
          nullable: true
          description: Email do cliente.
        ConsumerTelephone:
          type: string
          nullable: true
          description: Telefone do cliente.
        ConsumerStateInscription:
          type: string
          nullable: true
          description: Inscrição estadual do endereço selecionado do cliente.
        IDAddress:
          type: integer
          nullable: true
          description: Endereço de cobrança/principal do cliente.
        ShippingCity:
          type: string
          nullable: true
          description: Endereço de cobrança — cidade.
        ShippingComplement:
          type: string
          nullable: true
          description: Endereço de cobrança — complemento.
        ShippingNeighborhood:
          type: string
          nullable: true
          description: Endereço de cobrança — bairro.
        ShippingNumber:
          type: string
          nullable: true
          description: Endereço de cobrança — número.
        ShippingPostalCode:
          type: string
          nullable: true
          description: Endereço de cobrança — CEP.
        ShippingState:
          type: string
          nullable: true
          description: Endereço de cobrança — UF.
        ShippingStreet:
          type: string
          nullable: true
          description: Endereço de cobrança — rua.
        ShippingReceiverName:
          type: string
          description: 'Nome do recebedor no endereço de cobrança. Default: `(sem recebedor)`.'
        ShippingIDCountry:
          type: integer
          nullable: true
          description: País de cobrança.
        IDAddressDelivery:
          type: integer
          nullable: true
          description: Endereço de entrega (quando diferente do principal).
        DeliveryShippingStreet:
          type: string
          nullable: true
          description: Endereço de entrega — rua.
        DeliveryShippingNumber:
          type: string
          nullable: true
          description: Endereço de entrega — número.
        DeliveryShippingComplement:
          type: string
          nullable: true
          description: Endereço de entrega — complemento.
        DeliveryShippingNeighborhood:
          type: string
          nullable: true
          description: Endereço de entrega — bairro.
        DeliveryShippingCity:
          type: string
          nullable: true
          description: Endereço de entrega — cidade.
        DeliveryShippingState:
          type: string
          nullable: true
          description: Endereço de entrega — UF.
        DeliveryShippingPostalCode:
          type: string
          nullable: true
          description: Endereço de entrega — CEP.
        DeliveryShippingReceiverName:
          type: string
          nullable: true
          description: Recebedor no endereço de entrega.
        DeliveryShippingReceiverCpfCnpj:
          type: string
          nullable: true
          description: Documento do recebedor.
        DeliveryShippingReceiverTelephone:
          type: string
          nullable: true
          description: Telefone do recebedor.
        IDCarrier:
          type: integer
          nullable: true
          description: Transportadora selecionada.
        IDCarrierType:
          type: integer
          nullable: true
          description: Tipo da transportadora.
        SupplierNameCorporateName:
          type: string
          nullable: true
          description: Razão social da transportadora.
        SupplierTradeName:
          type: string
          nullable: true
          description: Nome fantasia da transportadora.
        SupplierLogoUrl:
          type: string
          nullable: true
          description: Logo da transportadora.
        ManualLabel:
          type: integer
          nullable: true
          description: Quando `1`, a transportadora exige etiqueta manual.
        PrintDanfeA4:
          type: integer
          nullable: true
          description: Quando `1`, imprime DANFE A4 junto com a etiqueta.
        ValueShipping:
          type: number
          nullable: true
          description: Valor do frete cobrado.
        NfModFrete:
          type: integer
          nullable: true
          description: Modalidade de frete na nota fiscal.
        NfModFreteDescription:
          type: string
          nullable: true
          description: Descrição da modalidade de frete.
        ShippingEstimateDate:
          type: string
          format: date
          nullable: true
          description: Previsão de entrega ao cliente.
        ShippingEstimateHandlingLimitDate:
          type: string
          format: date-time
          nullable: true
          description: Prazo de handling pactuado com o marketplace.
        CarrierDeliveryDate:
          type: string
          format: date-time
          nullable: true
          description: Data efetiva de entrega registrada pela transportadora.
        IDPickingList:
          type: integer
          nullable: true
          description: Picking list em que o pedido está incluído.
        IDOrdersCarrierCollectionList:
          type: integer
          nullable: true
          description: Romaneio em que o pedido está incluído.
        PickingListBasketExternalId:
          type: string
          nullable: true
          description: Identificadores externos das cestas do picking (separados por vírgula).
        IDStockKeepingUnitDistributionCenter:
          type: integer
          nullable: true
          description: Centro de distribuição que atende o pedido.
        DistributionCenterName:
          type: string
          nullable: true
          description: Nome do centro de distribuição.
        Weight:
          type: number
          nullable: true
          description: Peso total do pedido em kg.
        ExternalOrderId:
          type: string
          nullable: true
          description: 'Identificador externo do pedido (ex.: número da venda no marketplace).'
        IDCompanyIntegration:
          type: integer
          nullable: true
          description: Integração (canal de venda) que originou o pedido.
        CompanyIntegration:
          type: string
          nullable: true
          description: Nome composto da integração (`tipo - nome`).
        SalesChannelName:
          type: string
          nullable: true
          description: Nome do tipo de canal de venda.
        SalesChannelLogoUrl:
          type: string
          nullable: true
          description: Logo do canal de venda.
        ShowShipped:
          type: integer
          nullable: true
          description: Quando `1`, o canal aceita atualização de envio.
        ShowDelivered:
          type: integer
          nullable: true
          description: Quando `1`, o canal aceita atualização de entrega.
        ShowMarketplaceFee:
          type: integer
          nullable: true
          description: Quando `1`, o canal traz tarifas do marketplace.
        ShowFulfillment:
          type: integer
          nullable: true
          description: Quando `1`, o canal aceita atualização de fulfillment.
        HubOrderStatus:
          type: string
          nullable: true
          description: Status do pedido no marketplace original.
        IDSalesman:
          type: integer
          nullable: true
          description: Vendedor responsável.
        Salesman:
          type: string
          nullable: true
          description: Vendedor — nome e login concatenados.
        SalesmanName:
          type: string
          nullable: true
          description: Nome do vendedor.
        IDCompanySalesPolicy:
          type: integer
          nullable: true
          description: Política de venda aplicada ao tipo de pedido.
        CompanySalesPolicy:
          type: string
          nullable: true
          description: Descrição da política de venda.
        IssueNFCe:
          type: integer
          enum:
            - 0
            - 1
          description: Quando `1`, o tipo de pedido emite NFC-e em vez de NF-e.
        OrderPriority:
          type: integer
          nullable: true
          description: Prioridade de atendimento (0 a 10).
        OrderComments:
          type: string
          nullable: true
          description: Observações livres do pedido.
        OrderFrom:
          type: string
          nullable: true
          description: Lista de origens do pedido (`OrderFrom`) separadas por vírgula.
        BalanceChange:
          type: number
          nullable: true
          description: Saldo / troco a devolver ao cliente.
        IDTypeOrderReturn:
          type: integer
          nullable: true
          description: Tipo de devolução (quando `Return=1`).
        TypeOrderReturn:
          type: string
          nullable: true
          description: Descrição do tipo de devolução.
        IDTypeOrderReturnCategory:
          type: integer
          nullable: true
          description: Categoria da devolução (motivo).
          enum:
            - 1
            - 2
            - 3
        TypeOrderReturnCategory:
          type: string
          nullable: true
          description: Descrição da categoria de devolução.
        IDTypeOrderResend:
          type: integer
          nullable: true
          description: Quando o pedido é um reenvio, traz o tipo.
        TypeOrderResend:
          type: string
          nullable: true
          description: Descrição do tipo de reenvio.
        TypeOrderIDTypeAccountPayableReceivable:
          type: integer
          nullable: true
          description: Plano de contas padrão do tipo de pedido.
        TypeOrderTypeAccountPaybleDescription:
          type: string
          nullable: true
          description: Descrição do plano de contas padrão.
        OrdersSalesChannelLabelStatus:
          type: string
          nullable: true
          description: Status da etiqueta no canal de venda.
        IDStockKeepingUnitResupplyList:
          type: string
          nullable: true
          description: Listas de reposição vinculadas ao pedido (ids separados por vírgula).
        IDPurchase:
          type: integer
          nullable: true
          description: Identificador da compra interna vinculada (resupply).
        Tags:
          type: array
          items:
            type: string
          description: Tags aplicadas ao pedido (texto livre).
        IDNfCompany:
          type: integer
          nullable: true
          description: Identificador da nota fiscal principal.
        IDStatusInvoice:
          type: integer
          nullable: true
          description: Status da nota fiscal principal.
        StatusInvoice:
          type: string
          nullable: true
          description: Descrição do status da nota fiscal.
        NfeChaveAcesso:
          type: string
          nullable: true
          description: Chave de acesso da NF-e principal (44 dígitos).
        NfeNumber:
          type: string
          nullable: true
          description: Número da NF-e.
        NfeDhEmi:
          type: string
          format: date-time
          nullable: true
          description: Data/hora de emissão da NF-e.
        NfeSerie:
          type: string
          nullable: true
          description: Série da NF-e.
        NfeModelo:
          type: string
          nullable: true
          description: Modelo do documento fiscal (`55`=NF-e, `65`=NFC-e).
        NfModNfDescription:
          type: string
          nullable: true
          description: Descrição do modelo do documento fiscal.
        NfetpEmis:
          type: integer
          nullable: true
          description: Tipo de emissão (normal, contingência etc.).
        NfetpEmisDescription:
          type: string
          nullable: true
          description: Descrição do tipo de emissão.
        NfProcessCode:
          type: string
          nullable: true
          description: Código de processo SEFAZ retornado na última transmissão.
        NfenRec:
          type: string
          nullable: true
          description: Número do recibo SEFAZ.
        NfenProt:
          type: string
          nullable: true
          description: Número do protocolo SEFAZ.
        NfeNatureOperation:
          type: string
          nullable: true
          description: Natureza da operação.
        NfeDefaultNatureOperation:
          type: string
          nullable: true
          description: Natureza da operação inferida pelo CFOP do primeiro item.
        NfeCfopPriority:
          type: string
          nullable: true
          description: CFOP prioritário para os itens.
        NfeComments:
          type: string
          nullable: true
          description: Observações da nota fiscal.
        NfeAccessoryExpenses:
          type: number
          nullable: true
          description: Despesas acessórias (outras despesas) da NF.
        NfeFactorPercent:
          type: number
          nullable: true
          description: Fator de redução fiscal (0 a 1) aplicado na emissão.
        NfeManualTax:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: Quando `1`, os impostos são fixados manualmente (não recalculam).
        NfePackages:
          type: integer
          nullable: true
          description: Quantidade de volumes informada na NF.
        NfeNoPayment:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: Quando `1`, o pedido não gera contas a receber (cortesia/sem pagamento).
        NFeFin:
          type: integer
          nullable: true
          description: Indicador de finalidade da NF-e (1=normal, 2=complementar, 3=ajuste, 4=devolução).
        FinNfeDescription:
          type: string
          nullable: true
          description: Descrição da finalidade da NF-e.
        NFeType:
          type: integer
          nullable: true
          description: Tipo da NF-e (0=entrada, 1=saída).
        NfTpNfDescription:
          type: string
          nullable: true
          description: Descrição do tipo da NF-e.
        NfeindFinal:
          type: integer
          nullable: true
          description: Indicador de consumidor final (0=não, 1=sim).
        IndFinalDescription:
          type: string
          nullable: true
          description: Descrição do indicador de consumidor final.
        NfeExportaUFSaidaPais:
          type: string
          nullable: true
          description: UF de saída do país (operações de exportação).
        NfeExportaxLocExporta:
          type: string
          nullable: true
          description: Local de exportação (cidade).
        NfeExportaxLocDespacho:
          type: string
          nullable: true
          description: Local de despacho de exportação.
        NfeChaveAcessoDevolucao:
          type: string
          nullable: true
          description: Chaves de NF-e referenciadas (para devolução / complemento), separadas por vírgula.
        ValueProduct:
          type: number
          description: Soma de `PriceSellingTotal` dos itens não bonificados.
        ValueOrder:
          type: string
          description: Total do pedido (produtos + frete + despesas acessórias), formatado com duas casas.
        ValueComission:
          type: number
          description: Total de comissões calculadas para o vendedor.
        NfeValueCofins:
          type: number
          nullable: true
          description: Total de COFINS do pedido.
        NfeCofinsBaseCal:
          type: number
          nullable: true
          description: Base de cálculo total de COFINS.
        NfeValueFcp:
          type: number
          description: Valor de FCP (reservado, sempre 0).
        NfeValueFcpStRet:
          type: number
          description: Valor de FCP-ST retido (reservado, sempre 0).
        NfeValueFcpUfDest:
          type: number
          nullable: true
          description: FCP destinado à UF de destino.
        NfeValueIcms:
          type: number
          nullable: true
          description: Total de ICMS.
        NfeValueIcmsBaseCal:
          type: number
          nullable: true
          description: Base de cálculo total de ICMS.
        NfeValueIcmsUfDest:
          type: number
          nullable: true
          description: ICMS devido à UF de destino (DIFAL).
        NfeValueIcmsUfRemet:
          type: number
          nullable: true
          description: ICMS devido à UF do remetente (DIFAL).
        NfeValuePis:
          type: number
          nullable: true
          description: Total de PIS.
        NfePisBaseCal:
          type: number
          nullable: true
          description: Base de cálculo total de PIS.
        NfeValueIcmsST:
          type: number
          nullable: true
          description: Total de ICMS-ST.
        NfeValueIcmsSTBaseCal:
          type: number
          nullable: true
          description: Base de cálculo total de ICMS-ST.
        NfeValueIpi:
          type: number
          nullable: true
          description: Total de IPI.
        NfeValueII:
          type: number
          nullable: true
          description: Total de Imposto de Importação.
        NfeValueFcpSt:
          type: number
          nullable: true
          description: Total de FCP-ST.
        NfeImportnDI:
          type: string
          nullable: true
          description: Número da DI / DSI.
        NfeImportdDI:
          type: string
          format: date
          nullable: true
          description: Data do registro da DI.
        NfeImportxLocDesemb:
          type: string
          nullable: true
          description: Local do desembaraço aduaneiro.
        NfeImportUFDesemb:
          type: string
          nullable: true
          description: UF do desembaraço aduaneiro.
        NfeImportdDesemb:
          type: string
          format: date
          nullable: true
          description: Data do desembaraço.
        NfeImporttpViaTransp:
          type: integer
          nullable: true
          description: Via de transporte da importação.
        NftDITpViaTranspDescription:
          type: string
          nullable: true
          description: Descrição da via de transporte.
        NfeImportvAFRMM:
          type: number
          nullable: true
          description: Valor de AFRMM.
        NfeImporttpIntermedio:
          type: integer
          nullable: true
          description: Tipo de intermédio da operação de importação.
        NfDITpIntermedioDescription:
          type: string
          nullable: true
          description: Descrição do tipo de intermédio.
        NfeImportCNPJ:
          type: string
          nullable: true
          description: CNPJ do adquirente / encomendante.
        NfeImportUFTerceiro:
          type: string
          nullable: true
          description: UF do adquirente / encomendante.
        NfeImportcExportador:
          type: string
          nullable: true
          description: Código do exportador.
        NfeImportvDespAdu:
          type: number
          nullable: true
          description: Valor das despesas aduaneiras.
        NfeImportIOF:
          type: number
          nullable: true
          description: Valor do IOF da importação.
        Items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
          description: Itens do pedido.
        Payments:
          type: array
          items:
            $ref: '#/components/schemas/OrderPayment'
          description: Parcelas / pagamentos do pedido.
        Packages:
          type: array
          items:
            $ref: '#/components/schemas/OrderPackage'
          description: Pacotes gerados para envio.
        Events:
          type: array
          items:
            $ref: '#/components/schemas/OrderEvent'
          description: Histórico de eventos do pedido (últimos 500).
        Files:
          type: array
          items:
            $ref: '#/components/schemas/OrderFile'
          description: Arquivos da nota fiscal principal.
        NfeImportAdditions:
          type: array
          items:
            $ref: '#/components/schemas/OrderNfeImportAddition'
          description: Adições vinculadas à DI.
        ConsumerIDCompanySalesPolicy:
          type: integer
          format: int64
          nullable: true
          description: Identificador da política comercial padrão do cliente do pedido.
    OrderEconomics:
      type: object
      description: Indicadores econômicos do pedido — receitas, custos, impostos e margem.
      properties:
        EconomicsOrderValue:
          type: number
          nullable: true
          description: Valor total do pedido (produtos + frete + despesas).
        EconomicsProductValue:
          type: number
          nullable: true
          description: Valor total dos produtos.
        EconomicsProductValuePercent:
          type: number
          nullable: true
          description: Participação dos produtos no total.
        EconomicsShippingValue:
          type: number
          nullable: true
          description: Valor do frete cobrado.
        EconomicsShippingValuePercent:
          type: number
          nullable: true
          description: Participação do frete no total.
        EconomicsAccessoryExpenses:
          type: number
          nullable: true
          description: Despesas acessórias.
        EconomicsAccessoryExpensesPercent:
          type: number
          nullable: true
          description: Participação das despesas acessórias no total.
        EconomicsMarketplaceFee:
          type: number
          nullable: true
          description: Tarifa do marketplace (negativa).
        EconomicsMarketplaceFeePercent:
          type: number
          nullable: true
          description: Participação da tarifa do marketplace.
        EconomicsMarketplaceShippingFee:
          type: number
          nullable: true
          description: Tarifa de frete do marketplace (negativa).
        EconomicsMarketplaceShippingFeePercent:
          type: number
          nullable: true
          description: Participação da tarifa de frete do marketplace.
        EconomicsMarketplaceCouponValue:
          type: number
          nullable: true
          description: Cupons aplicados pelo marketplace.
        EconomicsMarketplaceCouponValuePercent:
          type: number
          nullable: true
          description: Participação dos cupons do marketplace.
        EconomicsTransferValue:
          type: number
          nullable: true
          description: Valor que será transferido pela operação.
        EconomicsTransferValuePercent:
          type: number
          nullable: true
          description: Participação do repasse no total.
        EconomicsSIMPLESorIRCSLLValue:
          type: number
          nullable: true
          description: Estimativa de Simples ou IR/CSLL para o pedido.
        EconomicsSIMPLESorIRCSLLValuePercent:
          type: number
          nullable: true
          description: Participação do imposto sobre o resultado.
        EconomicsPisCofinsValue:
          type: number
          nullable: true
          description: Total de PIS/COFINS.
        EconomicsPisCofinsValuePercent:
          type: number
          nullable: true
          description: Participação de PIS/COFINS.
        EconomicsIcmsValue:
          type: number
          nullable: true
          description: Total de ICMS (próprio + DIFAL).
        EconomicsIcmsValuePercent:
          type: number
          nullable: true
          description: Participação de ICMS.
        EconomicsIpiValue:
          type: number
          nullable: true
          description: Total de IPI.
        EconomicsIpiValuePercent:
          type: number
          nullable: true
          description: Participação de IPI.
        EconomicsNetRevenue:
          type: number
          nullable: true
          description: Receita líquida (após impostos e tarifas).
        EconomicsNetRevenuePercent:
          type: number
          nullable: true
          description: Participação da receita líquida sobre o total.
        EconomicsProductCost:
          type: number
          nullable: true
          description: Custo dos produtos (negativo).
        EconomicsProductCostPercent:
          type: number
          nullable: true
          description: Participação do custo dos produtos.
        EconomicsMarkUp:
          type: number
          nullable: true
          description: Mark-up (receita produto / custo produto).
        EconomicsGrossMargin:
          type: number
          nullable: true
          description: Margem bruta (receita líquida - custos diretos dos produtos).
        EconomicsGrossMarginPercent:
          type: number
          nullable: true
          description: Margem bruta percentual.
        EconomicsPackagingCost:
          type: number
          nullable: true
          description: Custo das embalagens (itens marcados como `Package`).
        EconomicsPackagingCostPercent:
          type: number
          nullable: true
          description: Participação do custo de embalagens.
        EconomicsShippingCost:
          type: number
          nullable: true
          description: Custo do frete pago à transportadora (CT-e).
        EconomicsShippingCostPercent:
          type: number
          nullable: true
          description: Participação do custo de frete.
        EconomicsAdditionalCost:
          type: number
          nullable: true
          description: Outros custos lançados como contas a pagar no pedido.
        EconomicsAdditionalCostPercent:
          type: number
          nullable: true
          description: Participação dos custos adicionais.
        EconomicsContributionMargin:
          type: number
          nullable: true
          description: Margem de contribuição (após custos diretos, embalagens e frete real).
        EconomicsContributionMarginPercent:
          type: number
          nullable: true
          description: Margem de contribuição percentual.
    OrderItemFiscal:
      type: object
      description: Item do pedido enriquecido com dados fiscais (CFOP, CST, classificação tributária) para emissão de NF.
      properties:
        IDSkuMovement:
          type: integer
          description: Identificador da movimentação.
        IDSku:
          type: integer
          description: Identificador do produto.
        IDOrder:
          type: integer
          description: Pedido ao qual o item pertence.
        Quantity:
          type: number
          description: Quantidade vendida.
        PriceSellingTotal:
          type: number
          description: Valor total do item.
        PriceSelling:
          type: number
          description: Preço unitário (`PriceSellingTotal / Quantity`).
        ValueDiscount:
          type: number
          nullable: true
          description: Desconto total do item (unitário x quantidade).
        SkuName:
          type: string
          description: Nome do produto.
        BarCode:
          type: string
          nullable: true
          description: Código de barras do produto.
        IDSkuCompany:
          type: string
          nullable: true
          description: Código interno (SKU) do produto.
        SkuNCM:
          type: string
          nullable: true
          description: NCM do produto.
        NfeCFOP:
          type: string
          nullable: true
          description: CFOP aplicado ao item.
        CfopDescription:
          type: string
          nullable: true
          description: Descrição do CFOP.
        IndexInvoice:
          type: integer
          description: Posição do item dentro da NF (1-based).
        NfeIbsCbsCST:
          type: string
          nullable: true
          description: CST IBS/CBS.
        IDNfCstIbsCbs:
          type: integer
          nullable: true
          description: Identificador da classificação tributária IBS/CBS.
        NfCstIbsCbsDescription:
          type: string
          nullable: true
          description: Descrição da classificação IBS/CBS (`cClassTrib - CST - nome`).
        NfeCofinsCst:
          type: string
          nullable: true
          description: CST de COFINS.
        NfCstCofinsDescription:
          type: string
          nullable: true
          description: Descrição do CST de COFINS.
        NfePisCst:
          type: string
          nullable: true
          description: CST de PIS.
        NfCstPisDescription:
          type: string
          nullable: true
          description: Descrição do CST de PIS.
        NfeIpiCst:
          type: string
          nullable: true
          description: CST de IPI.
        NfCstIpiDescription:
          type: string
          nullable: true
          description: Descrição do CST de IPI.
        NfeIcmsCst:
          type: string
          nullable: true
          description: CST de ICMS.
        NfCstIcmsDescription:
          type: string
          nullable: true
          description: Descrição do CST de ICMS.
        SkuCst:
          type: string
          nullable: true
          description: Origem da mercadoria (CST de origem).
        ICMSOrigDescription:
          type: string
          nullable: true
          description: Descrição da origem da mercadoria.
        NfeIcmsModBC:
          type: string
          nullable: true
          description: Modalidade da base de cálculo do ICMS.
        ICMSmodBCDescription:
          type: string
          nullable: true
          description: Descrição da modalidade de BC ICMS.
        NfeIcmsSTModBaseCal:
          type: string
          nullable: true
          description: Modalidade da base de cálculo do ICMS-ST.
        ICMSmodBCSTDescription:
          type: string
          nullable: true
          description: Descrição da modalidade de BC ICMS-ST.
        NfeIpicEnq:
          type: string
          nullable: true
          description: Código de enquadramento do IPI.
        IPIcEnqDescription:
          type: string
          nullable: true
          description: Descrição do enquadramento de IPI.
      additionalProperties: true
    OrderUpdateBody:
      type: object
      description: >-
        Corpo de atualização parcial do pedido. Apenas campos enviados são alterados — campos omitidos permanecem como
        estão. Em `?ValueAdjust=1`, o corpo aceita apenas `ValueAddOrDiscount` / `PercentAddOrDiscount` /
        `IncludeShipping`.
      properties:
        Order:
          type: string
          description: Número do pedido (texto livre exibido ao usuário).
        Budget:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` = orçamento; `0` = pedido efetivado.'
        Checked:
          type: integer
          description: Marcação de conferência.
        OrderComments:
          type: string
          nullable: true
          description: Observações livres do pedido.
        OrderPriority:
          type: integer
          minimum: 0
          maximum: 10
          description: Prioridade de atendimento (0 a 10).
        IDOrderType:
          type: integer
          description: Tipo de pedido (precisa existir na empresa).
        IDConsumer:
          type: integer
          nullable: true
          description: >-
            Cliente do pedido. Quando alterado, os dados de identificação (CPF/CNPJ, email, telefone, nome) são copiados
            do cadastro do cliente para o pedido.
        IDAddress:
          type: integer
          nullable: true
          description: >-
            Endereço de cobrança / endereço principal do cliente. Quando alterado, os campos `Shipping*` do pedido são
            reescritos com o endereço selecionado.
        IDAddressDelivery:
          type: integer
          nullable: true
          description: >-
            Endereço de entrega (quando diferente do endereço principal). Quando alterado, os campos `DeliveryShipping*`
            são reescritos.
        IDCarrier:
          type: integer
          nullable: true
          description: >-
            Transportadora. Não pode ser alterado se o pedido (ou um de seus pacotes) já estiver em romaneio; nesse caso
            retorne ao romaneio antes.
        IDOrdersCarrierCollectionList:
          type: integer
          nullable: true
          description: >-
            Romaneio em que o pedido é colocado. Precisa pertencer ao mesmo centro de distribuição do pedido e estar com
            status que permita inclusão.
        IDPickingList:
          type: integer
          nullable: true
          description: Picking list em que o pedido é colocado. Precisa estar com status que permita inclusão.
        IDSalesman:
          type: integer
          nullable: true
          description: Vendedor responsável (precisa ser usuário vinculado à empresa).
        IDCompanyInvoice:
          type: integer
          nullable: true
          description: Faturador (filial que emite a NF).
        IDCompanyIntegration:
          type: integer
          nullable: true
          description: Canal de venda (integração) ao qual o pedido pertence.
        IDStockKeepingUnitDistributionCenter:
          type: integer
          nullable: true
          description: Centro de distribuição que atende o pedido. Não pode divergir do CD dos armazéns dos itens já lançados.
        ValueShipping:
          type: number
          nullable: true
          description: Valor do frete cobrado.
        NfeAccessoryExpenses:
          type: number
          nullable: true
          description: Despesas acessórias da nota fiscal.
        ShippingEstimateDate:
          type: string
          format: date
          nullable: true
          description: Previsão de entrega ao cliente.
        NfeCfopPriority:
          type: string
          nullable: true
          description: CFOP prioritário a aplicar nos itens.
        NfeComments:
          type: string
          nullable: true
          description: Observações da nota fiscal.
        NFeFin:
          type: integer
          description: Finalidade da NF-e (1=normal, 2=complementar, 3=ajuste, 4=devolução).
        NFeType:
          type: integer
          description: Tipo da NF-e (0=entrada, 1=saída).
        NfeindFinal:
          type: integer
          enum:
            - 0
            - 1
          description: Indicador de consumidor final.
        NfModFrete:
          type: integer
          description: Modalidade de frete. Quando enviado vazio/null, o sistema grava `9` (sem frete).
        NfeNatureOperation:
          type: string
          description: Natureza da operação.
        NfeFactorPercent:
          type: number
          minimum: 0
          maximum: 1
          description: Fator de redução fiscal (entre 0 e 1).
        NfeManualTax:
          type: integer
          enum:
            - 0
            - 1
          description: Quando `1`, fixa os impostos atuais e impede recálculo automático.
        BalanceChange:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: >-
            `1` marca os itens como troca/saldo (não disparam recálculo de custo na troca de armazém); `0` trata como
            venda normal. Quando muda de `0` → `1` com nota ainda não emitida, dispara recálculo de custo de todos os
            itens.
        NfePackages:
          type: integer
          description: Quantidade de volumes a declarar na NF.
        NfeNoPayment:
          type: integer
          enum:
            - 0
            - 1
          description: Quando `1`, exclui todas as contas a receber do pedido (cortesia).
        ExternalOrderId:
          type: string
          nullable: true
          description: Identificador externo (número do pedido no marketplace, ERP, etc.).
        NfeExportaUFSaidaPais:
          type: string
          nullable: true
          description: UF de saída do país (exportações).
        NfeExportaxLocExporta:
          type: string
          nullable: true
          description: Local de exportação (cidade).
        NfeExportaxLocDespacho:
          type: string
          nullable: true
          description: Local de despacho.
        Tags:
          type: array
          items:
            type: string
          description: Lista de tags a sincronizar. Tags ausentes da lista são removidas; tags novas são inseridas.
        OrderFrom:
          type: string
          description: Origem do pedido (texto livre, separado por vírgula quando múltiplo).
        NfeChaveAcessoDevolucao:
          type: string
          nullable: true
          description: >-
            Chaves de NF-e referenciadas (44 dígitos cada, separadas por vírgula). Reescreve a lista atual quando a nota
            ainda não foi emitida.
        NfeImportnDI:
          type: string
          nullable: true
          description: Número da DI/DSI.
        NfeImportdDI:
          type: string
          format: date
          nullable: true
          description: Data do registro da DI.
        NfeImportxLocDesemb:
          type: string
          nullable: true
          description: Local do desembaraço.
        NfeImportUFDesemb:
          type: string
          nullable: true
          description: UF do desembaraço.
        NfeImportdDesemb:
          type: string
          format: date
          nullable: true
          description: Data do desembaraço.
        NfeImporttpViaTransp:
          type: integer
          nullable: true
          description: Via de transporte da importação.
        NfeImportvAFRMM:
          type: number
          nullable: true
          description: Valor de AFRMM.
        NfeImporttpIntermedio:
          type: integer
          nullable: true
          description: Tipo de intermédio.
        NfeImportCNPJ:
          type: string
          nullable: true
          description: CNPJ do adquirente/encomendante.
        NfeImportUFTerceiro:
          type: string
          nullable: true
          description: UF do adquirente/encomendante.
        NfeImportcExportador:
          type: string
          nullable: true
          description: Código do exportador.
        NfeImportvDespAdu:
          type: number
          nullable: true
          description: Valor de despesas aduaneiras.
        NfeImportIOF:
          type: number
          nullable: true
          description: Valor do IOF.
        NfeImportAdditions:
          type: array
          items:
            type: object
            properties:
              NfeImportnAdicao:
                type: string
                description: Número da adição.
              NfeImportnSeqAdic:
                type: string
                nullable: true
                description: Número sequencial dentro da adição.
              NfeImportcFabricante:
                type: string
                nullable: true
                description: Código do fabricante estrangeiro.
              NfeImportvDescDI:
                type: number
                nullable: true
                description: Valor de desconto da DI.
              NfeImportnDraw:
                type: string
                nullable: true
                description: Número do drawback.
          description: Adições da DI (substituem as atuais quando enviadas).
        ValueAddOrDiscount:
          type: number
          description: Valor absoluto a somar (positivo) ou descontar (negativo) ao total do pedido. Usado quando `?ValueAdjust=1`.
        PercentAddOrDiscount:
          type: number
          description: 'Percentual a aplicar (ex.: `-0.1` para desconto de 10%). Usado quando `?ValueAdjust=1`.'
        IncludeShipping:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            Quando `1`, inclui frete e despesas acessórias no rateio do desconto/acréscimo. Usado quando
            `?ValueAdjust=1`.
        IDStockKeepingUnitWarehouse:
          type: integer
          description: >-
            Quando enviado, dispara o fluxo de troca de armazém de todos os itens (independe dos outros campos). O novo
            armazém precisa pertencer ao mesmo centro de distribuição do pedido e o pedido não pode ter movimentação de
            saída.
        ShippingEstimateHandlingLimitDate:
          type: string
          format: date-time
          description: >-
            Data/hora limite estimada de expedição (prazo de manuseio). Usada principalmente em pedidos integrados de
            canais de venda.
    OrderSkuPostBody:
      type: object
      description: >-
        Item a adicionar ao pedido. Os campos mínimos exigidos pelo processo fiscal são `IDSku` e `Quantity` — os demais
        aceitam valores padrão e/ou são calculados pelo motor fiscal a partir do produto e da política de vendas.
      required:
        - IDSku
        - Quantity
      properties:
        IDSku:
          type: integer
          description: Identificador do produto.
        Quantity:
          type: number
          description: >-
            Quantidade. Sinal precisa ser coerente com os demais itens do pedido — itens positivos não podem coexistir
            com itens negativos no mesmo pedido.
        PriceSelling:
          type: number
          description: >-
            Preço unitário aplicado. Quando enviado `0` e o tipo de pedido bloqueia produtos com valor zero, o item é
            rejeitado (salvo quando a parametrização `GratificationZeroValue` está ligada e existe preço de tabela > 0
            na política de vendas vigente).
        PriceList:
          type: number
          description: Preço de tabela (antes do desconto).
        PriceSellingTotal:
          type: number
          description: Total do item. Quando omitido, é calculado por `PriceSelling * Quantity`.
        ValueDiscount:
          type: number
          nullable: true
          description: Desconto unitário aplicado.
        IDCompanySalesPolicy:
          type: integer
          description: Política de vendas usada para validar preço/desconto.
        IDStockKeepingUnitWarehouse:
          type: integer
          description: Armazém de origem do item. Precisa pertencer ao centro de distribuição do pedido.
        PackageNumber:
          type: integer
          nullable: true
          description: Número do pacote a alocar (criado depois via `/orders/{idorder}/packages`).
        Gratification:
          type: integer
          enum:
            - 0
            - 1
          description: Quando `1`, o item é brinde/bonificação e não soma no total do pedido.
        NfeNItemPed:
          type: string
          nullable: true
          description: Referência do item no pedido externo (integrações fiscais).
        Comments:
          type: string
          nullable: true
          description: Observações internas do item.
        CommentsInvoice:
          type: string
          nullable: true
          description: Observações do item para a NF-e.
        IDSkuKit:
          type: integer
          nullable: true
          description: Quando o item é componente de um kit explícito, identificador do kit pai.
        QuantityKit:
          type: number
          nullable: true
          description: Quantidade do kit pai.
        IDBatch:
          type: integer
          nullable: true
          description: Lote do produto a usar na saída.
      additionalProperties: true
    OrderSkuPutBody:
      type: object
      description: >-
        Atualização de um item já existente. Todos os campos são opcionais — campos omitidos não são alterados.
        Quantidade e preço passam pelo motor fiscal e disparam recálculo da nota; trocar `IDStockKeepingUnitWarehouse`
        valida que o armazém pertence ao mesmo CD do pedido.
      properties:
        IDSku:
          type: integer
          description: Quando enviado, valida que o produto existe na empresa.
        Quantity:
          type: number
          description: Nova quantidade. Sinal precisa ser coerente com os demais itens do pedido.
        PriceList:
          type: number
          description: Preço de tabela (antes do desconto).
        PriceSelling:
          type: number
          description: Novo preço unitário. Quando o desconto resultante excede o limite do vendedor, a operação é recusada.
        PriceSellingTotal:
          type: number
          description: Total do item. Quando omitido, recalculado por `PriceSelling * Quantity`.
        ValueDiscount:
          type: number
          nullable: true
          description: Desconto unitário aplicado.
        ValueShipping:
          type: number
          nullable: true
          description: Quando enviado, atualiza o frete do pedido junto com o item.
        NfeAccessoryExpenses:
          type: number
          nullable: true
          description: Quando enviado, atualiza despesas acessórias do pedido.
        QuantityNonconformity:
          type: number
          nullable: true
          description: Quantidade não conforme apontada no atendimento.
        IDTypeFulfillmentNonconformity:
          type: integer
          nullable: true
          description: Tipo de não conformidade.
          enum:
            - 1
            - 2
            - 4
            - 5
            - 6
        IDStockKeepingUnitWarehouse:
          type: integer
          description: Novo armazém do item. Precisa pertencer ao mesmo centro de distribuição do pedido.
        Gratification:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            Item de bonificação: `0`=não, `1`=sim. Itens marcados como bonificação não compõem o valor cobrado e seguem
            CFOP/CST específicos.
        NfeNItemPed:
          type: string
          nullable: true
          description: Número do item no pedido de compra do cliente, replicado na NF-e (tag `nItemPed`).
        Comments:
          type: string
          nullable: true
          description: Observações internas do item.
        CommentsInvoice:
          type: string
          nullable: true
          description: Observações do item que vão impressas na nota fiscal (tag `infAdProd`).
        NfeCFOP:
          type: string
          nullable: true
          description: >-
            CFOP aplicado ao item (4 dígitos). Quando omitido, recalculado pelo motor fiscal a partir do par
            origem/destino e do tipo de operação.
        NfeCofinsAliquot:
          type: number
          nullable: true
          description: Alíquota de COFINS (%) — campo `pCOFINS` da NF-e.
        NfeCofinsBaseCal:
          type: number
          nullable: true
          description: Base de cálculo do COFINS — campo `vBC` do grupo COFINS.
        NfeCofinsCst:
          type: string
          nullable: true
          description: CST do COFINS (ver `support data/NfCstCofins.csv`).
        NfeCofinsValue:
          type: number
          nullable: true
          description: Valor de COFINS — campo `vCOFINS`.
        NfeCofinsAliquotProd:
          type: number
          nullable: true
          description: Alíquota de COFINS por unidade tributável — campo `vAliqProd` do COFINS.
        NfeCofinsQtyProd:
          type: number
          nullable: true
          description: Quantidade tributável de COFINS — campo `qBCProd`.
        NfePisAliquot:
          type: number
          nullable: true
          description: Alíquota de PIS (%) — campo `pPIS`.
        NfePisBaseCal:
          type: number
          nullable: true
          description: Base de cálculo do PIS — campo `vBC` do grupo PIS.
        NfePisCst:
          type: string
          nullable: true
          description: CST do PIS (ver `support data/NfCstPis.csv`).
        NfePisValue:
          type: number
          nullable: true
          description: Valor de PIS — campo `vPIS`.
        NfePisAliquotProd:
          type: number
          nullable: true
          description: Alíquota de PIS por unidade tributável — campo `vAliqProd` do PIS.
        NfePisQtyProd:
          type: number
          nullable: true
          description: Quantidade tributável de PIS — campo `qBCProd`.
        NfeIpiAliquot:
          type: number
          nullable: true
          description: Alíquota de IPI (%) — campo `pIPI`.
        NfeIpiBaseCal:
          type: number
          nullable: true
          description: Base de cálculo do IPI — campo `vBC` do grupo IPI.
        NfeIpiCst:
          type: string
          nullable: true
          description: CST do IPI (ver `support data/NfCstIpi.csv`).
        NfeIpiValue:
          type: number
          nullable: true
          description: Valor de IPI — campo `vIPI`.
        NfeIpicEnq:
          type: string
          nullable: true
          description: Código de enquadramento do IPI — campo `cEnq` (ver `support data/NfIpiCEnq.csv`).
        NfeIpiQtyProd:
          type: number
          nullable: true
          description: Quantidade tributável do IPI — campo `qUnid`.
        NfeIpiValueProd:
          type: number
          nullable: true
          description: Valor por unidade tributável do IPI — campo `vUnid`.
        NfeIIValue:
          type: number
          nullable: true
          description: Valor de Imposto de Importação — campo `vII`.
        NfeIIBaseCal:
          type: number
          nullable: true
          description: Base de cálculo do Imposto de Importação — campo `vBC` do grupo II.
        NfeImportnAdicao:
          type: string
          nullable: true
          description: Número da adição (DI) — campo `nAdicao` da declaração de importação.
        NfeIIDespAdu:
          type: number
          nullable: true
          description: Valor das despesas aduaneiras — campo `vDespAdu`.
        NfeIIvAFRMM:
          type: number
          nullable: true
          description: Valor do AFRMM (Adicional ao Frete para Renovação da Marinha Mercante) — campo `vAFRMM`.
        NfeIIIOF:
          type: number
          nullable: true
          description: Valor do IOF na importação — campo `vIOF`.
        NfeIcmsFcpBaseCal:
          type: number
          nullable: true
          description: Base de cálculo do FCP (Fundo de Combate à Pobreza) na operação própria — campo `vBCFCP`.
        NfeIcmsFcpAliquot:
          type: number
          nullable: true
          description: Alíquota do FCP (%) — campo `pFCP`.
        NfeIcmsFcpValue:
          type: number
          nullable: true
          description: Valor do FCP — campo `vFCP`.
        NfeFcpSTBaseCal:
          type: number
          nullable: true
          description: Base de cálculo do FCP retido por substituição tributária — campo `vBCFCPST`.
        NfeFcpSTAliquot:
          type: number
          nullable: true
          description: Alíquota do FCP-ST (%) — campo `pFCPST`.
        NfeFcpSTValue:
          type: number
          nullable: true
          description: Valor do FCP-ST — campo `vFCPST`.
        NfeIcmsProprioAliquot:
          type: number
          nullable: true
          description: Alíquota efetiva do ICMS na operação própria (%) — campo `pICMS`.
        NfeIcmsBaseCal:
          type: number
          nullable: true
          description: Base de cálculo do ICMS — campo `vBC`.
        NfeIcmsCst:
          type: string
          nullable: true
          description: CST/CSOSN do ICMS (ver `support data/NfCstIcms.csv`).
        NfeIcmsModBC:
          type: string
          nullable: true
          description: Modalidade de determinação da base de cálculo do ICMS — campo `modBC` (ver `support data/NfModBc.csv`).
        NfeIcmsPRedBC:
          type: number
          nullable: true
          description: Percentual de redução da base de cálculo do ICMS — campo `pRedBC`.
        NfeIcmsValue:
          type: number
          nullable: true
          description: Valor do ICMS — campo `vICMS`.
        ICMScBenef:
          type: string
          nullable: true
          description: Código de benefício fiscal.
        NfeFcpUfDestAliquot:
          type: number
          nullable: true
          description: Alíquota do FCP devido à UF de destino em operação interestadual a consumidor final — campo `pFCPUFDest`.
        NfeIcmsInterstateAliquot:
          type: number
          nullable: true
          description: Alíquota interestadual aplicada em operação a consumidor final em outra UF — campo `pICMSInter`.
        NfeIcmsUfDestAliquot:
          type: number
          nullable: true
          description: Alíquota interna da UF de destino em operação interestadual a consumidor final — campo `pICMSUFDest`.
        NfeIcmsFcpUfDestBaseCal:
          type: number
          nullable: true
          description: Base de cálculo do FCP na UF de destino — campo `vBCFCPUFDest`.
        NfeIcmsUfDestBaseCal:
          type: number
          nullable: true
          description: Base de cálculo do ICMS para a UF de destino — campo `vBCUFDest`.
        NfeFcpUfDestValue:
          type: number
          nullable: true
          description: Valor do FCP devido à UF de destino — campo `vFCPUFDest`.
        NfeIcmsUfDestValue:
          type: number
          nullable: true
          description: Valor do ICMS devido à UF de destino — campo `vICMSUFDest`.
        NfeIcmsSTRetpST:
          type: number
          nullable: true
          description: Alíquota suportada pelo consumidor final do ICMS-ST retido anteriormente — campo `pST`.
        NfeIcmsSTRetBaseCal:
          type: number
          nullable: true
          description: Base de cálculo do ICMS-ST retido anteriormente — campo `vBCSTRet`.
        NfeIcmsSTRetSubstitutoValue:
          type: number
          nullable: true
          description: Valor do ICMS próprio do substituto — campo `vICMSSubstituto`.
        NfeIcmsSTRetValue:
          type: number
          nullable: true
          description: Valor do ICMS-ST retido anteriormente — campo `vICMSSTRet`.
        ICMSvBCFCPSTRet:
          type: number
          nullable: true
          description: Base de cálculo do FCP-ST retido anteriormente — campo `vBCFCPSTRet`.
        ICMSpFCPSTRet:
          type: number
          nullable: true
          description: Alíquota do FCP-ST retido anteriormente — campo `pFCPSTRet`.
        ICMSvFCPSTRet:
          type: number
          nullable: true
          description: Valor do FCP-ST retido anteriormente — campo `vFCPSTRet`.
        NfeIcmsCredSnAliquot:
          type: number
          nullable: true
          description: Alíquota aplicável de cálculo do crédito de ICMS no Simples Nacional — campo `pCredSN`.
        NfeIcmsCredSnValue:
          type: number
          nullable: true
          description: Valor do crédito de ICMS aproveitável no Simples Nacional — campo `vCredICMSSN`.
        NfeIcmsSTAliquot:
          type: number
          nullable: true
          description: Alíquota do ICMS-ST (%) — campo `pICMSST`.
        NfeIcmsSTBaseCal:
          type: number
          nullable: true
          description: Base de cálculo do ICMS-ST — campo `vBCST`.
        NfeIcmsSTMVA:
          type: number
          nullable: true
          description: Margem de Valor Agregado do ICMS-ST (%) — campo `pMVAST`.
        NfeIcmsSTModBaseCal:
          type: string
          nullable: true
          description: >-
            Modalidade de determinação da base de cálculo do ICMS-ST — campo `modBCST` (ver `support
            data/NfModBcST.csv`).
        NfeIcmsPRedBCST:
          type: number
          nullable: true
          description: Percentual de redução da base de cálculo do ICMS-ST — campo `pRedBCST`.
        NfeIcmsSTValue:
          type: number
          nullable: true
          description: Valor do ICMS-ST — campo `vICMSST`.
        NfeIbsCbsCST:
          type: string
          nullable: true
          description: CST conjunto de IBS/CBS da Reforma Tributária (ver `support data/NfCstIbsCbs.csv`).
        NfeIbsCbsBaseCal:
          type: number
          nullable: true
          description: Base de cálculo de IBS/CBS — campo `vBC` do grupo IBS/CBS.
        NfeIbsAliquot:
          type: number
          nullable: true
          description: Alíquota do IBS (%) — campo `pIBS`.
        NfeIbspRedAliquot:
          type: number
          nullable: true
          description: Percentual de redução da alíquota do IBS — campo `pRedAliq`.
        NfeIbsValue:
          type: number
          nullable: true
          description: Valor do IBS — campo `vIBS`.
        NfeCbsAliquot:
          type: number
          nullable: true
          description: Alíquota da CBS (%) — campo `pCBS`.
        NfeCbspRedAliquot:
          type: number
          nullable: true
          description: Percentual de redução da alíquota da CBS — campo `pRedAliq`.
        NfeCbsValue:
          type: number
          nullable: true
          description: Valor da CBS — campo `vCBS`.
    OrderSkuMovement:
      type: object
      description: >-
        Item adicionado retornado pelo `orderSkuPost`. Mesmo shape do item dentro de `Items` (algumas chaves podem
        aparecer apenas quando o pedido tem vendedor com regra de comissão vigente).
      properties:
        IDSkuMovement:
          type: integer
          description: Identificador da linha de movimentação de estoque gerada para o item do pedido.
        IDSku:
          type: integer
          description: Identificador do SKU adicionado ao pedido.
        SkuName:
          type: string
          description: Nome do SKU.
        Quantity:
          type: number
          description: Quantidade do SKU no item do pedido.
        PriceSelling:
          type: number
          description: Preço de venda unitário aplicado (após descontos por unidade).
        PriceList:
          type: number
          description: Preço de tabela (preço cheio) do SKU no momento da venda.
        PriceSellingTotal:
          type: number
          description: >-
            Valor total da linha já com desconto aplicado (`PriceSelling * Quantity`, onde `PriceSelling` é o preço
            unitário após desconto). Para o preço cheio antes do desconto, multiplique `PriceList * Quantity`.
        ValueDiscount:
          type: number
          nullable: true
          description: Valor de desconto monetário aplicado ao item.
        PercentDiscount:
          type: number
          nullable: true
          description: Percentual de desconto aplicado ao item.
        QtyAvailable:
          type: number
          description: Quantidade disponível em estoque do SKU no momento da inclusão (informativo para a tela).
        PackageNumber:
          type: integer
          nullable: true
          description: Número do volume (caixa) ao qual o item foi alocado durante a separação. Vazio antes do empacotamento.
        BarCode:
          type: string
          nullable: true
          description: Código de barras principal do SKU.
        IDSkuCompany:
          type: string
          nullable: true
          description: Código de referência interno do SKU, definido pela empresa.
        AccountName:
          type: string
          description: Subdomínio (conta) da empresa dona do pedido.
        IDBatch:
          type: integer
          nullable: true
          description: Lote do SKU baixado (`IDBatchNumber`). Vazio quando o SKU não usa controle de lote.
        AbcCurve:
          type: string
          nullable: true
          description: Classificação ABC do SKU (`A`, `B`, `C`) com base na participação no faturamento.
        MainImageURL:
          type: string
          nullable: true
          description: URL da imagem principal do SKU para exibição na tela do pedido.
        BestBeforeDate:
          type: string
          format: date
          nullable: true
          description: Data de validade do lote, no formato `YYYY-MM-DD`. Vazio quando o SKU não usa controle de validade.
        Address:
          type: string
          nullable: true
          description: Endereço de armazenagem (rua-coluna-nível) de onde o SKU foi separado. Vazio antes da separação.
        QuantityNonconformity:
          type: number
          nullable: true
          description: >-
            Quantidade do item registrada como não conformidade (avariada/faltante/divergente) na separação ou
            recebimento. Vazio quando não há não conformidade.
        IDTypeFulfillmentNonconformity:
          type: integer
          nullable: true
          description: >-
            Tipo da não conformidade do item (ex.: avaria, falta, divergência de SKU). Vazio quando não há não
            conformidade.
          enum:
            - 1
            - 2
            - 4
            - 5
            - 6
        TypeFulfillmentNonconformity:
          type: string
          nullable: true
          description: Descrição amigável do tipo de não conformidade.
        IDStockKeepingUnitWarehouse:
          type: integer
          description: Armazém de origem do item baixado.
        WarehouseName:
          type: string
          nullable: true
          description: Nome do armazém de origem.
        IDTaxDepartment:
          type: integer
          nullable: true
          description: Departamento fiscal (regra tributária) aplicado ao item neste pedido.
        TaxDepartmentDescription:
          type: string
          nullable: true
          description: Descrição do departamento fiscal.
        IDTypeSku:
          type: integer
          nullable: true
          description: >-
            Tipo do SKU: `1` Clube, `2` Kit, `3` Sku (produto normal), `4` Produto com variação (pai), `5` Serviço, `6`
            Matéria-prima, `7` Uso e consumo, `8` Caixa fechada.
        SkuNCM:
          type: string
          nullable: true
          description: Código NCM do SKU para fins fiscais.
        SkuCst:
          type: string
          nullable: true
          description: Código CST (Código de Situação Tributária) do SKU.
        NfOrigDescription:
          type: string
          nullable: true
          description: 'Descrição da origem da mercadoria para fins fiscais (ex.: `Nacional`, `Estrangeira - Importação direta`).'
        Comments:
          type: string
          nullable: true
          description: Observações livres do item do pedido.
        Gratification:
          type: integer
          description: '`1` quando o item é uma gratificação/bonificação (não compõe receita); `0` quando é venda normal.'
        NfeFcpSTValue:
          type: number
          description: Valor do FCP-ST (Fundo de Combate à Pobreza retido por Substituição Tributária) calculado para o item.
        NfeIcmsSTValue:
          type: number
          description: Valor do ICMS-ST (Substituição Tributária) calculado para o item.
        NfeIpiValue:
          type: number
          description: Valor do IPI calculado para o item.
        SkuWeightTotal:
          type: number
          description: Peso total da linha em kg (`SkuWeight × Quantity`) — usado em cálculos de frete.
        IDCategory:
          type: integer
          nullable: true
          description: Categoria principal (folha) do SKU.
        IDCategoryArray:
          type: array
          items:
            type: string
          description: 'Hierarquia completa de categorias do SKU, do topo até a folha (ex.: `[1, 12, 145]`).'
        IDSalesmanComission:
          type: integer
          nullable: true
          description: Identificador da regra de comissão de vendedor aplicada ao item.
        ComissionPercent:
          type: number
          nullable: true
          description: Percentual de comissão calculado para o vendedor sobre o item.
        ComissionValue:
          type: number
          nullable: true
          description: Valor de comissão em reais calculado para o vendedor sobre o item.
        ValueOrderItem:
          type: number
          description: >-
            Valor do item para totalização do pedido. Quando o tipo de pedido **não** usa cálculo reverso de imposto
            (`ReverseTaxCalculation = 0`), soma os impostos retidos: `PriceSellingTotal + NfeValueIcmsST + NfeValueFcpSt
            + NfeValueIpi`. Quando usa cálculo reverso (impostos já embutidos no preço), repete `PriceSellingTotal`. O
            desconto do item já entrou no `PriceSellingTotal`, então não é subtraído de novo.
    OrderPaymentPostBody:
      type: object
      description: >-
        Pagamento(s) a lançar no pedido. Aceita um único título ou um array de títulos — a aplicação efetiva (criação
        das parcelas, geração de boleto/link, etc.) é feita pelo processo financeiro. Os campos abaixo são os mínimos
        esperados; campos adicionais específicos do tipo de pagamento (`IDBankAccountForecast`, `DocumentNumber`, `TID`,
        `NSU`, `IDCompanyIntegration` etc.) também são aceitos.
      required:
        - IDTypePayment
        - Value
        - DateDue
      properties:
        IDTypePayment:
          type: integer
          description: Tipo de pagamento configurado na empresa.
        Value:
          type: number
          description: Valor total a lançar. Quando `?SplitInstallment` é maior que 1, o processo rateia em parcelas.
        Installment:
          type: integer
          description: Número da parcela (1-based). Default `1`.
        InstallmentTotal:
          type: integer
          description: Total de parcelas. Default `1`.
        DateDue:
          type: string
          format: date
          description: Data de vencimento da primeira parcela.
        DateCompetence:
          type: string
          format: date
          nullable: true
          description: Data de competência.
        DateDocument:
          type: string
          format: date
          nullable: true
          description: Data do documento.
        DocumentNumber:
          type: string
          nullable: true
          description: >-
            Número do documento da forma de pagamento (ex.: número do cheque, número do boleto, número da nota
            promissória). Aceita vazio.
        IDBankAccountForecast:
          type: integer
          nullable: true
          description: Conta bancária prevista para recebimento.
        IDConsumer:
          type: integer
          nullable: true
          description: Cliente pagador (quando difere do cliente do pedido).
        IDTypeAccountPayableReceivable:
          type: integer
          nullable: true
          description: Plano de contas (subtipo financeiro).
        IDTypeDocument:
          type: integer
          nullable: true
          description: Tipo de documento financeiro.
        IDCompanyIntegration:
          type: integer
          nullable: true
          description: Integração (adquirente, gateway, gateway de boleto).
        Comments:
          type: string
          nullable: true
          description: Observações livres do lançamento do pagamento.
        TID:
          type: string
          nullable: true
          description: >-
            TID (Transaction ID) retornado pela adquirente/gateway de pagamento. Preenchido quando o pagamento é por
            cartão capturado em maquininha ou gateway.
        NSU:
          type: string
          nullable: true
          description: NSU (Número Sequencial Único) retornado pela adquirente/gateway na captura do pagamento.
        Forecast:
          type: integer
          enum:
            - 0
            - 1
          description: Quando `1`, o lançamento é previsão (ainda não confirmado).
      additionalProperties: true
    AccountsPayableReceivableUpdateBody:
      type: object
      description: >-
        Atualização parcial de um título financeiro vinculado ao pedido. `IDConsumer` e `IDSupplier` são mutuamente
        exclusivos — informe apenas um. Quando o título já tem boleto/link de pagamento pago, alterações em
        `Value`/`DateDue` são bloqueadas; quando o boleto/link ainda está em aberto, a alteração dispara reemissão junto
        ao gateway.
      properties:
        Comments:
          type: string
          nullable: true
          description: Observações do título.
        IDTypePayment:
          type: integer
          description: Tipo de pagamento configurado na empresa.
        TID:
          type: string
          nullable: true
          description: >-
            Identificador da transação no adquirente/gateway de pagamento. Quando alterado junto com `Value`/`DateDue`,
            dispara reemissão do boleto/link de pagamento.
        NSU:
          type: string
          nullable: true
          description: Número sequencial único da transação fornecido pelo adquirente.
        Value:
          type: number
          description: Valor do título.
        Installment:
          type: integer
          description: Número da parcela atual (1 para a primeira). Usado em pagamentos parcelados.
        InstallmentTotal:
          type: integer
          description: Quantidade total de parcelas do pagamento.
        IDConsumer:
          type: integer
          nullable: true
          description: Cliente vinculado ao título (limpa `IDSupplier` quando enviado).
        IDSupplier:
          type: integer
          nullable: true
          description: Fornecedor vinculado ao título (limpa `IDConsumer` quando enviado).
        DateCompetence:
          type: string
          format: date
          nullable: true
          description: Data de competência. String vazia limpa o campo.
        DateDocument:
          type: string
          format: date
          nullable: true
          description: Data do documento. String vazia limpa o campo.
        DateDue:
          type: string
          format: date
          description: Data de vencimento.
        IDBankAccountForecast:
          type: integer
          nullable: true
          description: Conta bancária prevista. O literal string `"0"` é ignorado.
        DocumentNumber:
          type: string
          nullable: true
          description: Número do documento (nota, recibo, boleto).
        IDTypeAccountPayableReceivable:
          type: integer
          description: Plano de contas.
        IDTypeDocument:
          type: integer
          description: Tipo de documento financeiro.
        IDCompanyIntegration:
          type: integer
          nullable: true
          description: Integração (adquirente/gateway) associada.
        IDCompanyInvoice:
          type: integer
          nullable: true
          description: Filial faturadora (precisa pertencer ao mesmo grupo da empresa).
        ValueDiscount:
          type: number
          nullable: true
          description: Desconto aplicado no pagamento.
        ValueInterest:
          type: number
          nullable: true
          description: Juros aplicados.
        ValuePenalty:
          type: number
          nullable: true
          description: Multa aplicada.
        Forecast:
          type: integer
          enum:
            - 0
            - 1
          description: Quando `1`, marca o título como previsão.
    OrderPackagePostBody:
      type: object
      description: >-
        Pacote a criar / regenerar para o pedido. Aceita dois modos de uso: (a) criar um pacote único informando as
        dimensões; (b) garantir uma quantidade total de pacotes via `PackageQuantityTotal` (cria pacotes vazios até
        atingir o total ou apaga os excedentes — números mais altos primeiro).
      properties:
        PackageWeight:
          type: number
          nullable: true
          description: Peso do pacote (kg).
        PackageHeight:
          type: number
          nullable: true
          description: Altura do pacote (cm).
        PackageLength:
          type: number
          nullable: true
          description: Comprimento do pacote (cm).
        PackageWidth:
          type: number
          nullable: true
          description: Largura do pacote (cm).
        PackageQuantityTotal:
          type: integer
          description: Quando enviado, força a quantidade total de pacotes do pedido a esse valor (cria ou remove pacotes vazios).
        IDSku:
          type: integer
          description: >-
            Quando enviado, adiciona uma movimentação no pedido com esse produto como brinde/embalagem (quantidade `1`,
            preço `0`, armazém padrão da empresa).
    OrderPackagePutBody:
      type: object
      description: Atualização de um pacote — código de rastreio do envio e/ou vínculo com romaneio.
      properties:
        ShippingId:
          type: string
          nullable: true
          description: >-
            Código de rastreio do pacote retornado pela transportadora. Precisa ser único dentro da transportadora;
            envie string vazia ou `null` para limpar.
        IDOrdersCarrierCollectionList:
          type: integer
          nullable: true
          description: >-
            Romaneio em que o pacote é incluído. Precisa pertencer à mesma transportadora e ao mesmo centro de
            distribuição do pedido e estar com status que permita inclusão. Envie `null` para retirar do romaneio.
    OrderCustomFile:
      type: object
      description: Arquivo customizado anexado ao pedido (assinatura digital de entrega, foto de documento, fotos da entrega).
      properties:
        IDOrdersCustomFile:
          type: integer
          description: Identificador do arquivo.
        IDOrder:
          type: integer
          description: Pedido vinculado.
        IDTypeOrderFile:
          type: integer
          description: Tipo do arquivo (1=Entrega, 2=Devolução, etc. — consulte `TypeOrderFile`).
          enum:
            - 1
            - 2
            - 3
        TypeOrderFile:
          type: string
          description: Descrição do tipo.
        ConsumerDocument:
          type: string
          nullable: true
          description: Documento do recebedor.
        ConsumerNameCorporateName:
          type: string
          nullable: true
          description: Nome do recebedor.
        Comments:
          type: string
          nullable: true
          description: Observações da entrega.
        File1Name:
          type: string
          nullable: true
          description: Nome do arquivo de assinatura no S3.
        File2Name:
          type: string
          nullable: true
          description: Nome do primeiro anexo (foto do documento).
        File3Name:
          type: string
          nullable: true
          description: Nome do segundo anexo.
        File4Name:
          type: string
          nullable: true
          description: Nome do terceiro anexo.
        UrlFile1Name:
          type: string
          nullable: true
          description: URL pré-assinada do S3 (validade 2 dias) para a assinatura.
        UrlFile2Name:
          type: string
          nullable: true
          description: URL pré-assinada para o primeiro anexo.
        UrlFile3Name:
          type: string
          nullable: true
          description: URL pré-assinada para o segundo anexo.
        UrlFile4Name:
          type: string
          nullable: true
          description: URL pré-assinada para o terceiro anexo.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data de inclusão.
      additionalProperties: true
    OrderFilePostBody:
      type: object
      description: >-
        Arquivos customizados a anexar ao pedido. Pelo menos um entre `Signature`, `DocumentImage`, `DocumentImage2` ou
        `DocumentImage3` precisa vir preenchido (data URL base64).
      properties:
        Signature:
          type: string
          description: >-
            Imagem da assinatura do recebedor em formato data URL base64 (ex.: `data:image/png;base64,...`). Salva como
            `<id>_Signature.<ext>`.
        DocumentImage:
          type: string
          nullable: true
          description: Primeira imagem do documento/comprovante (data URL base64).
        DocumentImage2:
          type: string
          nullable: true
          description: Segunda imagem (data URL base64).
        DocumentImage3:
          type: string
          nullable: true
          description: Terceira imagem (data URL base64).
        ConsumerDocument:
          type: string
          nullable: true
          description: Documento do recebedor (CPF/CNPJ ou RG).
        ConsumerNameCorporateName:
          type: string
          nullable: true
          description: Nome do recebedor.
        Comments:
          type: string
          nullable: true
          description: Observações da entrega.
        IDStatusOrder:
          type: integer
          description: >-
            Status final a aplicar quando `ChangeStatus=1`. Quando omitido, o sistema escolhe automaticamente (`8` para
            transportadoras de devolução — tipos 30/32 — e `7` para as demais).
    CarrierQuotationRate:
      type: object
      description: Cotação retornada por uma transportadora elegível na disputa.
      properties:
        IDCarrier:
          type: integer
          description: Identificador do fornecedor (transportadora).
        IDCarrierQuotationRate:
          type: integer
          description: Identificador interno da cotação retornada por essa transportadora.
        Attended:
          type: integer
          description: Resultado da consulta — `1` atende, `0` não atende, `3` excluído pela regra, `4` fora da faixa.
        AttendedDescription:
          type: string
          description: Texto correspondente ao código `Attended` — `Atende`, `Não Atende`, `Excluído` ou `Fora da faixa`.
        DaysTime:
          type: integer
          description: Prazo de entrega em dias úteis informado pela transportadora.
          nullable: true
        CarrierAdditionalBusinessDays:
          type: integer
          description: Dias úteis adicionais cadastrados na transportadora.
          nullable: true
        CutDaysTime:
          type: integer
          description: Dias adicionais por horário de corte.
          nullable: true
        TotalDaysTime:
          type: integer
          description: Soma de `DaysTime`, `CarrierAdditionalBusinessDays` e `CutDaysTime`.
        TotalShowDaysTime:
          type: integer
          description: Prazo final exibido ao usuário (`TotalDaysTime` mais os dias adicionais da regra).
        RateType:
          type: string
          description: Tipo de tabela aplicada (peso, cubagem, valor).
          nullable: true
        ShipingValue:
          type: number
          description: Valor base do frete antes das taxas adicionais.
          nullable: true
        AdvaloremValue:
          type: number
          description: Valor da taxa ad valorem.
          nullable: true
        AdvaloremValuePercent:
          type: number
          description: Percentual ad valorem sobre `ValueInvoice` da cotação.
          nullable: true
        GrisValue:
          type: number
          description: Valor do GRIS (gerenciamento de risco).
          nullable: true
        GrisValuePercent:
          type: number
          description: Percentual de GRIS sobre `ValueInvoice`.
          nullable: true
        TollValue:
          type: number
          description: Valor do pedágio.
          nullable: true
        TollFractionValue:
          type: number
          description: Valor de pedágio fracionado.
          nullable: true
        AccessDifficultyRateValue:
          type: number
          description: Taxa de difícil acesso.
          nullable: true
        DispatchFeeValue:
          type: number
          description: Taxa de despacho.
          nullable: true
        DeliveryDifficultyRateValue:
          type: number
          description: Taxa de difícil entrega.
          nullable: true
        SECCATValue:
          type: number
          description: Taxa SEC/CAT.
          nullable: true
        TrafficRestrictionFeeValue:
          type: number
          description: Taxa de restrição de circulação.
          nullable: true
        AdministrationFeeValue:
          type: number
          description: Taxa administrativa.
          nullable: true
        CTEFeeValue:
          type: number
          description: Taxa de emissão de CT-e.
          nullable: true
        SUFRAMAFeeValue:
          type: number
          description: Taxa SUFRAMA.
          nullable: true
        FluvialInsuranceFee:
          type: number
          description: Taxa de seguro fluvial.
          nullable: true
        OtherFee:
          type: number
          description: Outras taxas extras.
          nullable: true
        OtherFeeValue:
          type: number
          description: Valor de outras taxas.
          nullable: true
        IcmsValue:
          type: number
          description: Valor do ICMS aplicado sobre o frete.
          nullable: true
        IcmsValuePercent:
          type: number
          description: Percentual de ICMS efetivo (`IcmsValue / TotalShippingValue`).
          nullable: true
        AdjustedValue:
          type: number
          description: Ajuste manual aplicado pela regra de cotação.
          nullable: true
        PriceRounding:
          type: number
          description: Arredondamento de centavos aplicado ao valor final.
          nullable: true
        SubtotalShippingValue:
          type: number
          description: Soma do `ShipingValue` com todas as taxas, antes do ICMS. Vem `null` quando `Attended` é diferente de `1`.
          nullable: true
        TotalShippingValue:
          type: number
          description: Subtotal mais `IcmsValue`. Vem `null` quando `Attended` é diferente de `1`.
          nullable: true
        ShippingShowValue:
          type: number
          description: Valor final exibido ao usuário (total + ajustes da regra). Vem `null` quando `Attended` é diferente de `1`.
          nullable: true
        WeightSelected:
          type: number
          description: Peso considerado na cotação (real ou cubado, o que for maior).
          nullable: true
        WeightCubed:
          type: number
          description: Peso cubado calculado.
          nullable: true
        Weight:
          type: number
          description: Peso real dos itens do pedido.
          nullable: true
        CarrierCubageKmM:
          type: number
          description: Fator de cubagem por metro cúbico configurado na transportadora.
          nullable: true
        CarrierCubageFreeWeight:
          type: number
          description: Peso mínimo isento de cubagem.
          nullable: true
        SupplierNameCorporateName:
          type: string
          description: Razão social da transportadora.
          nullable: true
        CarrierLogoUrl:
          type: string
          description: URL do logo da transportadora.
          nullable: true
        CarrierModal:
          type: string
          description: Modalidade da transportadora (rodoviário, aéreo, etc.).
          nullable: true
        CarrierQuotationRuleValueName:
          type: string
          description: Nome da regra de cotação aplicada para valor.
          nullable: true
        CarrierQuotationRuleDaysName:
          type: string
          description: Nome da regra de cotação aplicada para prazo.
          nullable: true
        IDCarrierQuotationRuleValue:
          type: integer
          description: Identificador da regra de valor aplicada.
          nullable: true
        IDCarrierQuotationRuleDays:
          type: integer
          description: Identificador da regra de prazo aplicada.
          nullable: true
        RuleAdditionalValue:
          type: number
          description: Valor extra aplicado pela regra.
          nullable: true
        RuleAdditionalDays:
          type: integer
          description: Dias extras aplicados pela regra.
          nullable: true
    CarrierQuotation:
      type: object
      description: >-
        Resultado da disputa de frete (auction) para um pedido. Ordenado por `Attended` descendente, depois prazo e
        valor totais.
      properties:
        IDCarrierQuotation:
          type: integer
          description: Identificador da disputa de frete.
        IDOrder:
          type: integer
          description: Pedido relacionado.
          nullable: true
        IDCompany:
          type: integer
          description: Empresa dona da cotação.
        ValueInvoice:
          type: number
          description: Valor declarado para cálculo de ad valorem.
          nullable: true
        Weight:
          type: number
          description: Peso total considerado na consulta.
          nullable: true
        ShippingPostalCode:
          type: string
          description: CEP de destino consultado.
          nullable: true
        Recordtimestamp:
          type: string
          format: date-time
          description: Quando a disputa foi registrada.
          nullable: true
        RecordUserCreated:
          type: integer
          description: Usuário que disparou a disputa.
          nullable: true
        Login:
          type: string
          description: Login do usuário responsável pela disputa.
          nullable: true
        CompanyAddressPostalCode:
          type: string
          description: CEP de origem da empresa.
          nullable: true
        CompanyAddressState:
          type: string
          description: UF de origem da empresa.
          nullable: true
        CarrierQuotations:
          type: array
          description: Lista de cotações por transportadora elegível.
          items:
            $ref: '#/components/schemas/CarrierQuotationRate'
    HubOrderSku:
      type: object
      description: Item do pedido no marketplace.
      properties:
        IDSku:
          type: integer
          description: Identificador do SKU interno.
          nullable: true
        IDSkuHub:
          type: string
          description: Código do SKU no marketplace.
          nullable: true
        IDSkuCompany:
          type: string
          description: Código do SKU no cadastro da empresa.
          nullable: true
        SkuName:
          type: string
          description: Nome do SKU.
          nullable: true
        Quantity:
          type: number
          description: Quantidade do item.
        PriceSelling:
          type: number
          description: Preço de venda unitário do marketplace.
          nullable: true
        ValueDiscount:
          type: number
          description: Desconto aplicado ao item.
          nullable: true
        IDWarehouseHub:
          type: string
          description: Armazém do marketplace.
          nullable: true
        IDProductHub:
          type: string
          description: Código do produto no marketplace.
          nullable: true
        IDHubProduct:
          type: integer
          description: Identificador interno do produto no hub.
          nullable: true
        IDIntegrationProducts:
          type: string
          description: Identificador do item dentro do pedido do marketplace.
          nullable: true
        Comments:
          type: string
          description: Observações enviadas pelo comprador para o item.
          nullable: true
        MainImageURL:
          type: string
          description: URL da imagem principal do SKU.
          nullable: true
    HubOrderPaymentItem:
      type: object
      description: Pagamento recebido pelo marketplace.
      properties:
        Acquirer:
          type: string
          description: Adquirente do pagamento (Cielo, Stone, etc.).
          nullable: true
        Connector:
          type: string
          description: Conector usado pelo marketplace.
          nullable: true
        Installments:
          type: integer
          description: Número de parcelas.
        PaymentSystem:
          type: string
          description: Tipo de meio de pagamento.
          nullable: true
        PaymentSystemName:
          type: string
          description: Nome amigável do meio de pagamento.
          nullable: true
        TransactionIdentifier:
          type: string
          description: Identificador da transação no adquirente.
          nullable: true
        InterestValue:
          type: number
          description: Juros aplicados pelo parcelamento.
          nullable: true
        Value:
          type: number
          description: Valor recebido.
    HubOrderMessageItem:
      type: object
      description: Mensagem trocada com o comprador no marketplace (inclui mensagens sintéticas geradas a partir de reclamações).
      properties:
        IDHubOrderMessage:
          type: integer
          description: Identificador interno da mensagem.
          nullable: true
        IDHubOrderMessageExternal:
          type: string
          description: Identificador da mensagem no marketplace.
          nullable: true
        IDIntegration:
          type: integer
          description: Pedido do marketplace ao qual a mensagem pertence.
        Message:
          type: string
          description: Texto da mensagem.
        MessageTimestamp:
          type: string
          format: date-time
          description: Data/hora de envio.
          nullable: true
        ReadTimestamp:
          type: string
          format: date-time
          description: Data/hora em que o destinatário marcou como lida.
          nullable: true
        Seller:
          type: integer
          description: Origem da mensagem — `1` quando enviada pelo lojista, demais valores indicam o comprador ou o marketplace.
        Attachments:
          type: array
          description: URLs temporárias dos anexos da mensagem (assinadas, válidas por 2 dias).
          items:
            type: string
    HubOrderClaimAction:
      type: object
      description: Ação disponível para resolver uma reclamação no marketplace.
      properties:
        Mandatory:
          type: integer
          description: '`1` quando a ação é obrigatória, `0` caso contrário.'
        IDTypeHubOrderClaimActionExternalId:
          type: string
          description: Identificador da ação no marketplace.
        TypeHubOrderClaimActionDescription:
          type: string
          description: Descrição amigável da ação.
          nullable: true
        PartialRefundOffers:
          type: array
          description: Ofertas de reembolso parcial disponíveis (apenas quando a ação é `allow_partial_refund`).
          items:
            type: object
            properties:
              Amount:
                type: number
                description: >-
                  Valor da oferta de reembolso parcial em reais — uma das opções predefinidas pelo marketplace para o
                  vendedor oferecer ao comprador.
              Percentage:
                type: number
                description: Percentual sobre o valor do pedido representado pela oferta de reembolso parcial.
        ReturnFailReasons:
          type: array
          description: Lista de motivos disponíveis para reprovar a revisão da devolução (apenas em `return_review_fail`).
          items:
            type: object
            properties:
              Reason:
                type: string
                description: >-
                  Código interno do motivo de recusa da revisão de devolução, no padrão do marketplace (ex.:
                  `received_in_bad_condition`).
              ReasonName:
                type: string
                description: Descrição amigável do motivo de recusa, em português, para exibir ao vendedor.
        OptionsList:
          type: array
          description: >-
            Modalidades de envio disponíveis e os campos esperados para cada uma (em `add_shipping_evidence` e
            `send_tracking_number`).
          items:
            type: object
            properties:
              ShippingMethod:
                type: string
                description: >-
                  Método de envio para anexar como evidência: `mail` (Correios), `carrier` (transportadora),
                  `delivered_by_seller` (entrega pelo próprio vendedor), etc.
              ShippingMethodLabel:
                type: string
                description: 'Rótulo amigável do método de envio (ex.: `Correios`, `Transportadora`, `Entrega própria`).'
              FieldList:
                type: array
                items:
                  type: object
                  properties:
                    Field:
                      type: string
                      description: >-
                        Nome técnico do campo a ser enviado no `POST /orders/hub/{idorder}/message` (ex.:
                        `ShippingDate`, `ShippingId`, `Attachment`).
                    FieldName:
                      type: string
                      description: Rótulo do campo em português para exibição na tela.
                    FieldType:
                      type: string
                      description: 'Tipo do campo no formulário: `date`, `string`, `array` (lista de anexos).'
                    FieldRequired:
                      type: integer
                      description: '`1` quando o campo é obrigatório para registrar a evidência; `0` quando opcional.'
                description: Lista de campos que o vendedor precisa preencher para registrar a evidência de envio neste método.
    HubOrderClaim:
      type: object
      description: Reclamação aberta no marketplace para o pedido.
      properties:
        IDHubOrderClaim:
          type: integer
          description: Identificador interno da reclamação.
        IDHubOrderClaimExternal:
          type: string
          description: Identificador da reclamação no marketplace.
          nullable: true
        ClaimStatus:
          type: integer
          description: Status atual da reclamação.
          nullable: true
        ClaimCreationDate:
          type: string
          format: date-time
          description: Data/hora de abertura.
          nullable: true
        IDTypeHubOrderClaimType:
          type: integer
          description: Tipo da reclamação.
          nullable: true
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 7
            - 8
        TypeHubOrderClaimTypeName:
          type: string
          description: Nome do tipo de reclamação.
          nullable: true
        IDTypeHubOrderClaimStage:
          type: integer
          description: Estágio da reclamação.
          nullable: true
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
        TypeHubOrderClaimStageName:
          type: string
          description: Nome do estágio.
          nullable: true
        IDTypeHubOrderClaimReason:
          type: integer
          description: Motivo cadastrado.
          nullable: true
        TypeHubOrderClaimReason:
          type: string
          description: Descrição do motivo.
          nullable: true
        IDTypeHubOrderClaimResolutionReason:
          type: integer
          description: Motivo de resolução.
          nullable: true
        TypeHubOrderClaimResolutionReasonDescription:
          type: string
          description: Descrição do motivo de resolução.
          nullable: true
        ClaimTimestampLastUpdated:
          type: string
          format: date-time
          description: Última atualização.
          nullable: true
        ClaimResolutionDate:
          type: string
          format: date-time
          description: Data de resolução.
          nullable: true
        IDProductHub:
          type: string
          description: Produto envolvido.
          nullable: true
        AutopartsProductId:
          type: string
          description: Identificador no catálogo de autopeças.
          nullable: true
        AutopartsProductDetail:
          type: string
          description: Descrição do produto no catálogo de autopeças.
          nullable: true
        IDHubProductAutoparts:
          type: integer
          description: Vínculo interno do produto com a base de autopeças.
          nullable: true
        DueDate:
          type: string
          format: date-time
          description: Prazo final para resposta.
          nullable: true
        ActionResponsible:
          type: string
          description: Parte responsável pela próxima ação.
          nullable: true
        ClaimTitle:
          type: string
          description: Título da reclamação.
          nullable: true
        ClaimDescription:
          type: string
          description: Texto descritivo da reclamação.
          nullable: true
        ClaimProblem:
          type: string
          description: Resumo do problema relatado.
          nullable: true
        AvailableActions:
          type: array
          description: Ações disponíveis para resolver a reclamação. Vazio quando `ClaimStatus = 1`.
          items:
            $ref: '#/components/schemas/HubOrderClaimAction'
    HubOrderClaimMessage:
      type: object
      description: Mensagem trocada no contexto de uma reclamação.
      properties:
        IDHubOrderClaimMessage:
          type: integer
          description: Identificador da mensagem.
        IDHubOrderClaim:
          type: integer
          description: Reclamação relacionada.
        Sender:
          type: integer
          description: Origem da mensagem (`1` lojista, outros valores comprador/marketplace).
        Message:
          type: string
          description: Texto da mensagem.
        MessageTimestamp:
          type: string
          format: date-time
          description: Data/hora de envio.
          nullable: true
        ReadTimestamp:
          type: string
          format: date-time
          description: Data/hora em que foi lida.
          nullable: true
        Attachments:
          type: array
          description: URLs temporárias dos anexos.
          items:
            type: string
    HubOrderDetail:
      type: object
      description: Detalhe completo do pedido integrado a um marketplace (hub).
      properties:
        IDIntegration:
          type: integer
          description: Identificador do pedido no hub.
        IDOrder:
          type: integer
          description: Pedido idworks vinculado, quando já existe.
          nullable: true
        Order:
          type: string
          description: Número do pedido no idworks.
          nullable: true
        OrderId:
          type: string
          description: Identificador do pedido no marketplace.
          nullable: true
        PackId:
          type: string
          description: Identificador do pack de pedidos no marketplace.
          nullable: true
        Status:
          type: string
          description: Status retornado pelo marketplace.
          nullable: true
        HubOrderStatus:
          type: string
          description: Tradução do status para o vocabulário do idworks.
          nullable: true
        CreateOrder:
          type: integer
          description: Sinaliza se o status atual já gera o pedido no idworks (`1`/`0`).
          nullable: true
        CreateOrderDescription:
          type: string
          description: Descrição amigável do flag `CreateOrder`.
          nullable: true
        CreationTimestamp:
          type: string
          format: date-time
          description: Quando o pedido foi criado no marketplace.
          nullable: true
        RecordTimestamp:
          type: string
          format: date-time
          description: Quando o pedido foi importado.
          nullable: true
        AccountName:
          type: string
          description: Conta idworks responsável.
          nullable: true
        IDCompanyIntegration:
          type: integer
          description: Integração de empresa associada ao pedido.
        IDTypeCompanyIntegration:
          type: integer
          description: Tipo de integração (Mercado Livre, Olist, etc.).
        IDSalesChannel:
          type: integer
          description: Canal de venda usado.
          nullable: true
        SalesChannelName:
          type: string
          description: Nome do canal de venda.
          nullable: true
        SalesChannelLogoUrl:
          type: string
          description: URL do logo do canal.
          nullable: true
        CompanyIntegrationName:
          type: string
          description: Nome amigável da conta integrada.
          nullable: true
        CompanyIntegration:
          type: string
          description: Nome composto `<Canal> - <Conta>`.
          nullable: true
        SalesChannelOrderLink:
          type: string
          description: URL para o pedido na plataforma do marketplace (apenas para Mercado Livre, SkyHub e Olist).
          nullable: true
        ConsumerDocument:
          type: string
          description: CPF/CNPJ do comprador informado pelo marketplace.
          nullable: true
        ConsumerEmail:
          type: string
          description: E-mail do comprador.
          nullable: true
        ConsumerFirstName:
          type: string
          description: Primeiro nome do comprador.
          nullable: true
        IDConsumer:
          type: integer
          description: Cliente cadastrado no idworks, quando vinculado.
          nullable: true
        Coupon:
          type: string
          description: Cupom aplicado.
          nullable: true
        ShippingId:
          type: string
          description: Código de envio principal.
          nullable: true
        ShippingCourierId:
          type: string
          description: Identificador da transportadora no marketplace.
          nullable: true
        ShippingEstimateDate:
          type: string
          format: date
          description: Previsão de entrega.
          nullable: true
        ShippingEstimateHandlingLimitDate:
          type: string
          format: date-time
          description: Prazo limite para o seller processar.
          nullable: true
        IDWarehouseHub:
          type: string
          description: Armazém do marketplace usado no pedido.
          nullable: true
        TotalOrderValue:
          type: number
          description: Valor total do pedido no marketplace.
          nullable: true
        TotalShippingValue:
          type: number
          description: Valor do frete.
          nullable: true
        TotalDiscountValue:
          type: number
          description: Desconto aplicado.
          nullable: true
        TotalInterestValue:
          type: number
          description: Juros do parcelamento.
          nullable: true
        TotalItemsValue:
          type: number
          description: Soma `Quantity * PriceSelling` dos itens.
        QuantityItems:
          type: number
          description: Soma das quantidades dos itens.
        QuantityPayments:
          type: integer
          description: Quantidade de pagamentos cadastrados.
        UtmCampaign:
          type: string
          description: Campanha UTM.
          nullable: true
        UtmMedium:
          type: string
          description: Mídia UTM.
          nullable: true
        UtmSource:
          type: string
          description: Origem UTM.
          nullable: true
        UtmiCampaign:
          type: string
          description: Campanha UTMi interna.
          nullable: true
        UtmiPage:
          type: string
          description: Página UTMi.
          nullable: true
        UtmiPart:
          type: string
          description: Parte UTMi.
          nullable: true
        SKUs:
          type: array
          description: Itens do pedido.
          items:
            $ref: '#/components/schemas/HubOrderSku'
        Payments:
          type: array
          description: Pagamentos recebidos.
          items:
            $ref: '#/components/schemas/HubOrderPaymentItem'
        Messages:
          type: array
          description: Mensagens trocadas com o comprador, já incluindo entradas geradas a partir das reclamações.
          items:
            $ref: '#/components/schemas/HubOrderMessageItem'
        Claims:
          type: array
          description: Reclamações abertas para o pedido.
          items:
            $ref: '#/components/schemas/HubOrderClaim'
        ClaimsMessages:
          type: array
          description: Mensagens das reclamações.
          items:
            $ref: '#/components/schemas/HubOrderClaimMessage'
        Index:
          type: integer
          description: Posição do registro no array de resultados (preenchida internamente).
    OrderTrackingEvent:
      type: object
      description: Evento de rastreamento registrado pelos sistemas da transportadora.
      properties:
        IDCarrierTracking:
          type: integer
          description: Identificador interno do evento.
        IDStatusTracking:
          type: integer
          description: Status interno do evento.
        Description:
          type: string
          description: Descrição do status retornada pela transportadora.
          nullable: true
        City:
          type: string
          description: Cidade onde o evento ocorreu.
          nullable: true
        State:
          type: string
          description: UF do evento.
          nullable: true
        Place:
          type: string
          description: Local específico (centro, agência).
          nullable: true
        PickUpAddress:
          type: string
          description: Endereço de retirada quando aplicável.
          nullable: true
        TrackingTimestamp:
          type: string
          format: date-time
          description: Quando o evento foi reportado.
        PackageNumber:
          type: integer
          description: Volume ao qual o evento se refere.
          nullable: true
    OrderTrackingPackage:
      type: object
      description: Volume rastreável do pedido.
      properties:
        IDPackage:
          type: integer
          description: Identificador do volume.
        PackageNumber:
          type: integer
          description: Número do volume dentro do pedido.
        ShippingId:
          type: string
          description: Código de rastreio enviado pela transportadora.
          nullable: true
        TrackingEvents:
          type: array
          description: Eventos retornados para esse volume, ordenados do mais recente para o mais antigo.
          items:
            $ref: '#/components/schemas/OrderTrackingEvent'
    OrderTrackingDetail:
      type: object
      description: Dados de rastreamento agrupados por pedido.
      properties:
        IDOrder:
          type: integer
          description: Identificador do pedido.
        Order:
          type: string
          description: Número do pedido.
        Recordtimestamp:
          type: string
          format: date-time
          description: Quando o pedido foi criado.
          nullable: true
        ShippingEstimateDate:
          type: string
          format: date
          description: Previsão de entrega prometida ao consumidor.
          nullable: true
        ConsumerNameCorporateName:
          type: string
          description: Nome do consumidor.
          nullable: true
        ConsumerCpfCnpj:
          type: string
          description: CPF/CNPJ do consumidor.
          nullable: true
        IDPackage:
          type: integer
          description: Volume principal do pedido.
          nullable: true
        IDStatusPackage:
          type: integer
          description: Status do volume principal.
          nullable: true
          enum:
            - 1
            - 2
        StatusPackage:
          type: string
          description: Descrição do status do volume.
          nullable: true
        IDCarrierType:
          type: integer
          description: Tipo da transportadora.
          nullable: true
        SupplierNameCorporateName:
          type: string
          description: Razão social da transportadora.
          nullable: true
        CarrierLogoUrl:
          type: string
          description: URL do logo da transportadora.
          nullable: true
        TrackingUrl:
          type: string
          description: URL pública para o consumidor acompanhar o rastreio.
        ShippingDate:
          type: string
          format: date-time
          description: Maior data de envio entre os volumes.
          nullable: true
        ShippingId:
          type: string
          description: Lista de códigos de rastreio agregados (separados por vírgula).
          nullable: true
        PackagesQty:
          type: integer
          description: Quantidade de volumes do pedido.
        TrackingIDStatus:
          type: integer
          description: Maior status de rastreio entre os volumes.
          nullable: true
        StatusTracking:
          type: string
          description: Descrição do status de rastreio.
          nullable: true
        TrackingLastStatus:
          type: string
          description: Último status reportado pela transportadora.
          nullable: true
        TrackingLastStatusRecordTimestamp:
          type: string
          format: date-time
          description: Data/hora do último status.
          nullable: true
        ConsumerDeliveryDateDifference:
          type: integer
          description: Diferença em dias entre a entrega e o prazo prometido ao consumidor.
          nullable: true
        CarrierDeliveryDateDifference:
          type: integer
          description: Diferença em dias entre a entrega e o prazo prometido pela transportadora.
          nullable: true
        IDStatusDeliveryConsumer:
          type: integer
          description: >-
            Classificação SLA frente ao prazo do consumidor — `1` entregue no prazo, `2` entregue em atraso, `3` em
            trânsito dentro do prazo, `4` em trânsito atrasado, `6` entregue no dia limite.
          nullable: true
        StatusDeliveryConsumer:
          type: string
          description: Descrição do `IDStatusDeliveryConsumer`.
          nullable: true
        IDStatusDeliveryCarrier:
          type: integer
          description: Classificação SLA frente ao prazo da transportadora — mesma codificação.
          nullable: true
        StatusDeliveryCarrier:
          type: string
          description: Descrição do `IDStatusDeliveryCarrier`.
          nullable: true
        Packages:
          type: array
          description: Volumes do pedido. Quando a transportadora não suporta rastreio por volume, é retornado apenas o primeiro.
          items:
            $ref: '#/components/schemas/OrderTrackingPackage'
    OrderReturnItem:
      type: object
      description: Item a ser devolvido.
      properties:
        IDSkuMovement:
          type: integer
          description: Identificador da movimentação do pedido original que está sendo devolvida.
        Quantity:
          type: number
          description: Quantidade a devolver.
      required:
        - IDSkuMovement
        - Quantity
    OrderReturnBody:
      type: object
      description: >-
        Parâmetros para gerar o pedido de devolução. Os mesmos campos podem ser enviados por query string em snake_case
        (`idtypeorderreturn`, `comments`, `balancechange`, `withvalue`, `idstockkeepingunitwarehouse`, etc.) ou em
        PascalCase no body. Quando o body traz `Items`, apenas as movimentações listadas são devolvidas; sem `Items`,
        devolve todas as movimentações do pedido original.
      properties:
        IDTypeOrderReturn:
          type: integer
          description: Tipo de devolução cadastrado em `GET /type/order/return`. Obrigatório para devoluções enviadas no body.
        IDTypeOrderReturnCategory:
          type: integer
          description: Categoria do tipo de devolução.
          nullable: true
          enum:
            - 1
            - 2
            - 3
        Comments:
          type: string
          description: Observações que vão para o pedido de devolução.
          nullable: true
        BalanceChange:
          type: integer
          enum:
            - 0
            - 1
          description: Se a devolução afeta saldo de estoque (`1` afeta, `0` não). Padrão `1`.
        WithValue:
          type: integer
          enum:
            - 0
            - 1
          description: Quando `1`, mantém preço e desconto do pedido original; quando `0`, zera os valores. Padrão `1`.
        IDStockKeepingUnitWarehouse:
          type: integer
          description: Armazém destino dos itens devolvidos. Validado contra os armazéns ativos da empresa.
          nullable: true
        CreateInbound:
          type: integer
          enum:
            - 0
            - 1
          description: Se deve gerar recebimento (`Inbound`) associado à devolução.
          nullable: true
        ConsumerVoucher:
          type: integer
          enum:
            - 0
            - 1
          description: Se deve gerar voucher de troca para o cliente.
          nullable: true
        IssueInvoice:
          type: integer
          enum:
            - 0
            - 1
          description: Se deve emitir nota fiscal de devolução automaticamente.
          nullable: true
        IDConsumer:
          type: integer
          description: >-
            Cliente alvo da devolução. Quando informado junto com `IDAddress`, substitui o cliente/endereço do pedido
            original.
          nullable: true
        IDAddress:
          type: integer
          description: Endereço alternativo de entrega para a devolução.
          nullable: true
        Items:
          type: array
          description: Lista de movimentações a devolver. Quando omitido, devolve todos os itens.
          items:
            $ref: '#/components/schemas/OrderReturnItem'
    OrderPromotion:
      type: object
      description: Promoções do PDV (idworks) e benefícios do hub aplicados ao pedido.
      properties:
        StockKeepingUnitPromotion:
          type: array
          description: Promoções de PDV vinculadas ao pedido.
          items:
            type: object
            properties:
              IDStockKeepingUnitPromotion:
                type: integer
                description: Identificador da promoção.
              StockKeepingUnitPromotionName:
                type: string
                description: Nome da promoção.
              IDOrdersPromotion:
                type: integer
                description: Vínculo entre pedido e promoção.
        HubOrderBenefit:
          type: array
          description: Benefícios/promoções aplicados pelo marketplace.
          items:
            type: object
            properties:
              BenefitName:
                type: string
                description: Nome do benefício.
                nullable: true
              IDIntegration:
                type: integer
                description: Pedido do marketplace.
              IDIntegrationBenefits:
                type: string
                description: Identificador do benefício no marketplace.
                nullable: true
    HubCarrierMapping:
      type: object
      description: >-
        Registro do DE-PARA de transportadora — espelha colunas de `HubCarrier` enriquecidas com nomes já resolvidos
        (transportadora interna, integração, modal, armazém, status final).
      properties:
        IDHubCarrier:
          type: integer
          format: int64
          description: Identificador do mapeamento.
        AccountName:
          type: string
          description: Subdomínio da conta dona do registro.
        IDCarrierFrom:
          type: string
          maxLength: 450
          description: >-
            Identificador da transportadora no canal de venda (texto livre — costuma ser o `IDCarrier`/código que chega
            no pedido do canal).
        IDCarrierTo:
          type: integer
          format: int64
          nullable: true
          description: >-
            Identificador da transportadora cadastrada no idworks (`IDSupplier`). Fica `null` quando
            `CarrierAuctionByModal=1` (leilão por modal — o sistema escolhe a transportadora em runtime).
        RecordTimestamp:
          type: string
          format: date-time
          description: Data de criação do registro.
        OrderOnHold:
          type: integer
          description: >-
            Indicador interno (`0`/`1`) — quando `1`, pedidos chegando com esta transportadora ficam retidos para
            análise.
          default: 0
        IDCompanyIntegration:
          type: integer
          format: int64
          description: Integração a que o DE-PARA pertence.
        NfeModFrete:
          type: integer
          nullable: true
          description: >-
            Modalidade de frete a aplicar na NF-e do pedido. Valor casa com `NfModFrete` (`0`=Emitente,
            `1`=Destinatário, `2`=Terceiros, `3`=Próprio remetente, `4`=Próprio destinatário, `9`=Sem frete).
        IDStatusOrder:
          type: integer
          nullable: true
          description: >-
            Status do pedido que será aplicado automaticamente quando o pedido entrar com esta transportadora. Deve
            referenciar um `TypeStatusOrder` com `ChangeOnCreate=1`.
        CarrierAuctionByModal:
          type: integer
          nullable: true
          description: >-
            Quando `1`, a transportadora final é escolhida em tempo de roteirização via leilão entre as transportadoras
            do modal indicado em `IDCarrierModal`. Quando `null`/`0`, usa a transportadora fixa em `IDCarrierTo`.
        IDCarrierModal:
          type: integer
          format: int64
          nullable: true
          description: Modal de transporte (`IDCarrierModal`) usado quando `CarrierAuctionByModal=1`.
        CarrierAuctionByModalOrderPreference:
          type: integer
          nullable: true
          description: Critério de desempate no leilão por modal. `1` = menor preço, `2` = menor prazo.
        IDStockKeepingUnitWarehouse:
          type: integer
          format: int64
          nullable: true
          description: Armazém de origem do pedido aplicado quando o pedido cai neste DE-PARA.
        IDTypeCarrierAuction:
          type: integer
          nullable: true
          description: Tipo de leilão de frete habilitado para este DE-PARA. `1` = por modalidade, `2` = por prazo.
        IDTypeCarrierAuctionTiebreaker:
          type: integer
          nullable: true
          description: >-
            Critério de desempate do leilão. `1` = transportadora com maior ocupação, `2` = transportadora com menor
            ocupação.
        SupplierNameCorporateName:
          type: string
          nullable: true
          description: >-
            Nome resolvido da transportadora interna (`SupplierTradeName - SupplierNameCorporateName`, ou só o nome
            corporativo quando não tem nome fantasia).
        CompanyIntegrationName:
          type: string
          description: Nome cadastrado da integração.
        IntegrationName:
          type: string
          description: Nome do tipo de integração (`IntegrationName`).
        IDTypeCompanyIntegration:
          type: integer
          format: int64
          description: Tipo da integração.
        CompanyIntegration:
          type: string
          description: Concatenação `{IntegrationName} - {CompanyIntegrationName}` para exibição.
        NfModFreteDescription:
          type: string
          nullable: true
          description: Descrição da modalidade de frete.
        StatusOrder:
          type: string
          nullable: true
          description: Nome do status do pedido aplicado (`StatusOrder`).
        CarrierModal:
          type: string
          nullable: true
          description: Nome do modal de transporte.
        CarrierAuctionByModalOrderPreferenceDescription:
          type: string
          nullable: true
          description: >-
            Nome do critério de desempate por modal — `Preço` quando `CarrierAuctionByModalOrderPreference=1`, `Prazo`
            quando `=2`.
        WarehouseName:
          type: string
          nullable: true
          description: Nome do armazém de origem (`WarehouseName`).
        StatusColorCode:
          type: string
          nullable: true
          description: >-
            Código hexadecimal da cor configurada para o status do pedido naquela empresa (ex.: #18AA8C); nulo quando
            usa a cor padrão.
    HubCarrierCreateBody:
      type: object
      required:
        - IDCompanyIntegration
        - IDCarrierFrom
      description: Corpo para criação de um DE-PARA de transportadora.
      properties:
        IDCompanyIntegration:
          type: integer
          format: int64
          description: Integração a que o DE-PARA pertence. Validado contra `CompanyIntegration` da empresa autenticada.
        IDCarrierFrom:
          type: string
          maxLength: 450
          description: Identificador da transportadora no canal (texto livre).
        IDCarrierTo:
          type: integer
          format: int64
          nullable: true
          description: >-
            Identificador da transportadora interna (`IDSupplier`). Quando `CarrierAuctionByModal=1` o sistema força
            este campo para `null` (leilão por modal).
        NfeModFrete:
          type: integer
          nullable: true
          description: >-
            Modalidade de frete da NF-e. `0`=Emitente, `1`=Destinatário, `2`=Terceiros, `3`=Próprio remetente,
            `4`=Próprio destinatário, `9`=Sem frete.
        IDStatusOrder:
          type: integer
          nullable: true
          description: Status do pedido aplicado na chegada. Validado contra `ChangeOnCreate=1`.
        CarrierAuctionByModal:
          type: integer
          nullable: true
          description: '`1` para ativar leilão por modal (a transportadora é escolhida em runtime).'
        CarrierAuctionByModalOrderPreference:
          type: integer
          nullable: true
          description: Critério do leilão por modal. `1`=menor preço, `2`=menor prazo.
        IDCarrierModal:
          type: integer
          format: int64
          nullable: true
          description: Modal de transporte aplicável ao leilão. Validado contra `TypeCarrierModal` da empresa.
        IDStockKeepingUnitWarehouse:
          type: integer
          format: int64
          nullable: true
          description: Armazém de origem. Validado contra `StockKeepingUnitWarehouse` da empresa.
        IDTypeCarrierAuction:
          type: integer
          nullable: true
          description: Tipo de leilão. `1`=modalidade, `2`=prazo.
        IDTypeCarrierAuctionTiebreaker:
          type: integer
          nullable: true
          description: Desempate do leilão. `1`=maior ocupação, `2`=menor ocupação.
    HubCarrierUpdateBody:
      type: object
      description: >-
        Corpo para atualização de um DE-PARA de transportadora. Mesma estrutura do POST — todos os campos são
        revalidados.
      required:
        - IDCompanyIntegration
        - IDCarrierFrom
      properties:
        IDCompanyIntegration:
          type: integer
          format: int64
          description: Integração a que o DE-PARA pertence. Validado contra `CompanyIntegration` da empresa autenticada.
        IDCarrierFrom:
          type: string
          maxLength: 450
          description: Identificador da transportadora no canal (texto livre).
        IDCarrierTo:
          type: integer
          format: int64
          nullable: true
          description: >-
            Identificador da transportadora interna (`IDSupplier`). Quando `CarrierAuctionByModal=1` o sistema força
            este campo para `null` (leilão por modal).
        NfeModFrete:
          type: integer
          nullable: true
          description: >-
            Modalidade de frete da NF-e. `0`=Emitente, `1`=Destinatário, `2`=Terceiros, `3`=Próprio remetente,
            `4`=Próprio destinatário, `9`=Sem frete.
        IDStatusOrder:
          type: integer
          nullable: true
          description: Status do pedido aplicado na chegada. Validado contra `ChangeOnCreate=1`.
        CarrierAuctionByModal:
          type: integer
          nullable: true
          description: '`1` para ativar leilão por modal (a transportadora é escolhida em runtime).'
        CarrierAuctionByModalOrderPreference:
          type: integer
          nullable: true
          description: Critério do leilão por modal. `1`=menor preço, `2`=menor prazo.
        IDCarrierModal:
          type: integer
          format: int64
          nullable: true
          description: Modal de transporte aplicável ao leilão. Validado contra `TypeCarrierModal` da empresa.
        IDStockKeepingUnitWarehouse:
          type: integer
          format: int64
          nullable: true
          description: Armazém de origem. Validado contra `StockKeepingUnitWarehouse` da empresa.
        IDTypeCarrierAuction:
          type: integer
          nullable: true
          description: Tipo de leilão. `1`=modalidade, `2`=prazo.
        IDTypeCarrierAuctionTiebreaker:
          type: integer
          nullable: true
          description: Desempate do leilão. `1`=maior ocupação, `2`=menor ocupação.
    HubAcquirerMapping:
      type: object
      description: Registro do DE-PARA de adquirente — espelha `HubAcquirer` com nomes resolvidos das integrações envolvidas.
      properties:
        IDHubAcquirer:
          type: integer
          format: int64
          description: Identificador do mapeamento.
        AccountName:
          type: string
          description: Identificador da empresa proprietária do mapeamento.
        IDAcquirerFrom:
          type: string
          maxLength: 45
          description: Identificador da adquirente no canal de venda (texto livre — código que chega no pedido importado do canal).
        IDAcquirerTo:
          type: integer
          format: int64
          description: >-
            Identificador da adquirente cadastrada no idworks (apontando para um `CompanyIntegration` do tipo adquirente
            da empresa).
        IDCompanyIntegration:
          type: integer
          format: int64
          description: Integração de venda a que o DE-PARA pertence.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data/hora de criação do mapeamento.
        CompanyIntegration:
          type: string
          description: Concatenação `{IntegrationName} - {CompanyIntegrationName}` da integração de venda.
        IDTypeCompanyIntegration:
          type: integer
          format: int64
          description: Tipo da integração de venda.
        CompanyIntegrationAcquirer:
          type: string
          description: Concatenação `{IntegrationName} - {CompanyIntegrationName}` da adquirente cadastrada (`IDAcquirerTo`).
    HubAcquirerCreateBody:
      type: object
      required:
        - IDCompanyIntegration
        - IDAcquirerFrom
        - IDAcquirerTo
      description: Corpo para criação/atualização de DE-PARA de adquirente. Mesma estrutura aceita por `POST` e `PUT`.
      properties:
        IDCompanyIntegration:
          type: integer
          format: int64
          description: Integração de venda. Validado contra `CompanyIntegration` da empresa autenticada.
        IDAcquirerFrom:
          type: string
          maxLength: 45
          description: Identificador da adquirente no canal (texto livre).
        IDAcquirerTo:
          type: integer
          format: int64
          description: >-
            Adquirente cadastrada no idworks (referencia outra `CompanyIntegration` da mesma empresa, do tipo
            adquirente).
    HubVariationMapping:
      type: object
      description: >-
        Registro do DE-PARA de variação — espelha `HubVariation` enriquecido com o nome da variação interna, a
        integração e a categoria do canal.
      properties:
        IDHubVariation:
          type: integer
          format: int64
          description: Identificador do mapeamento.
        AccountName:
          type: string
          description: Identificador da empresa proprietária do mapeamento.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data/hora de criação do mapeamento.
        IDVariationFrom:
          type: string
          maxLength: 45
          description: Identificador da variação no canal (código da variação, texto livre).
        IDVariationTo:
          type: integer
          format: int64
          description: Identificador da variação interna (`IDTypeProductVariation`).
        IDCompanyIntegration:
          type: integer
          format: int64
          description: Integração a que o DE-PARA pertence.
        IDHubCategory:
          type: integer
          format: int64
          description: >-
            DE-PARA de categoria do canal (`IDHubCategory`). A categoria intermedeia o mapeamento porque os atributos
            disponíveis dependem da categoria do produto no canal.
        VariationName:
          type: string
          description: Nome da variação interna (`ProductVariation`).
        IDSalesChannel:
          type: integer
          nullable: true
          description: Canal de venda do tipo de integração.
        CompanyIntegrationName:
          type: string
          description: Nome amigável da integração configurado pela empresa.
        IntegrationName:
          type: string
          description: Nome do tipo de integração.
        CompanyIntegration:
          type: string
          description: Concatenação `{IntegrationName} - {CompanyIntegrationName}`.
        CategoryFromTree:
          type: string
          nullable: true
          description: 'Árvore completa da categoria no canal (ex.: ''Eletrônicos > TV > Smart TV''), vinda do `HubCategory`.'
        IDTypeCompanyIntegration:
          type: integer
          format: int64
          description: Tipo da integração.
        IDCategoryFrom:
          type: string
          nullable: true
          description: Código da categoria no canal (do `HubCategory`).
    HubVariationCreateBody:
      type: object
      required:
        - IDCompanyIntegration
        - IDHubCategory
        - IDVariationFrom
        - IDVariationTo
      description: Corpo para criação/atualização de DE-PARA de variação. Mesma estrutura aceita por `POST` e `PUT`.
      properties:
        IDCompanyIntegration:
          type: integer
          format: int64
          description: Integração a que o DE-PARA pertence.
        IDHubCategory:
          type: integer
          format: int64
          description: >-
            DE-PARA de categoria do canal (obtido via `GET /hub/category`). Define o contexto em que a variação é
            válida.
        IDVariationFrom:
          type: string
          maxLength: 45
          description: Identificador da variação no canal (texto livre).
        IDVariationTo:
          type: integer
          format: int64
          description: Variação interna (`IDTypeProductVariation`). Validada contra a empresa autenticada.
    HubIntegrationResource:
      type: object
      description: >-
        Recurso de canal de venda exposto para a tela — descreve o que pode ser consultado (categorias, atributos, modos
        de envio, etc.) para um tipo de integração. Vem de `TypeSalesChannelResource`.
      properties:
        IDTypeSalesChannelResource:
          type: integer
          format: int64
          description: Identificador interno do recurso (`IDTypeSalesChannelResource`).
        ResourceType:
          type: string
          maxLength: 45
          description: >-
            Tipo do recurso (ex.: `Autoparts`, `Category`, `CategoryAttribute`, `SkuCondition`, `TypeOffer`,
            `ModeShipping`, `OfficialStore`).
        Resource:
          type: string
          maxLength: 45
          description: Chave técnica única do recurso dentro do tipo de integração.
        ResourceDescription:
          type: string
          maxLength: 500
          description: Descrição do recurso — texto exibido na tela como tooltip/ajuda.
        ResourceName:
          type: string
          maxLength: 45
          description: Nome amigável para exibição.
        ResourceUrl:
          type: string
          maxLength: 300
          description: >-
            Endpoint relativo do processo que serve o recurso. O `POST /hub/resource/{idtypecompanyintegration}` o usa
            para montar a URL final.
        ResourceOrder:
          type: integer
          description: Ordem de apresentação na tela.
        ResourceKey:
          type: string
          maxLength: 45
          nullable: true
          description: >-
            Chave do recurso retornada pelo canal — usada para correlacionar a resposta com cadastros internos quando há
            mapeamento direto.
        Confirm:
          type: integer
          nullable: true
          description: Quando `1`, a ação relacionada pede confirmação na tela.
        IDTypeCompanyIntegration:
          type: integer
          format: int64
          nullable: true
          description: Tipo de integração a que o recurso pertence.
        RateLimit:
          type: integer
          default: 1
          description: Limite de requisições por janela (segundos) para evitar throttle no canal.
        Cache:
          type: integer
          default: 0
          description: >-
            Política de armazenamento da resposta. `0` = sempre consulta o canal; `1` = armazenamento padrão (3 dias)
            com fallback para o canal em miss; `2` = só usa o armazenamento existente (alimentado por outro processo).
        IntegrationName:
          type: string
          description: Nome do tipo de integração (`IntegrationName`).
    HubNotification:
      type: object
      description: >-
        Notificação/problema de integração detectada pelo sistema (`HubIntegrationProblem`), com o tipo, categoria e o
        registro associado (pedido, SKU, anúncio, conforme o tipo do problema).
      properties:
        IDHubNotification:
          type: integer
          format: int64
          description: Identificador da notificação.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data em que o problema foi detectado.
        IDTypeHubIntegrationProblem:
          type: integer
          description: Tipo do problema (`IDTypeHubIntegrationProblem`).
        EmailStatus:
          type: integer
          nullable: true
          description: Status do disparo do e-mail de notificação ao operador. `null` quando não houve envio.
        ID:
          type: integer
          format: int64
          description: >-
            Identificador do registro afetado — o significado depende do tipo do problema (ex.: `IDOrder` para problemas
            de pedido, `IDSku` para SKU).
        Message:
          type: string
          maxLength: 5000
          nullable: true
          description: Mensagem específica do problema (quando o sistema captura o texto retornado pelo canal).
        IDCompany:
          type: integer
          format: int64
          description: Identificador interno da empresa dona da notificação.
        AccountName:
          type: string
          description: Identificador da empresa dona da notificação.
        TypeHubIntegrationProblem:
          type: string
          description: Nome do tipo do problema (resolvido).
        Component:
          type: string
          maxLength: 45
          nullable: true
          description: Componente do frontend que sabe abrir o registro afetado a partir do `ID`.
        TypeHubIntegrationProblemCategory:
          type: string
          description: Categoria do problema (resolvida de `TypeHubIntegrationProblemCategory`).
        Params:
          type: string
          nullable: true
          description: >-
            Concatenação `Params + ID` — string já pronta para o frontend usar como parâmetro de navegação para o
            registro afetado.
    ConsumerAddress:
      type: object
      description: Endereço de entrega/cobrança do cliente.
      properties:
        IDAddress:
          type: integer
          format: int32
          description: Identificador do endereço.
        ConsumerStateInscription:
          type: string
          maxLength: 20
          nullable: true
          description: >-
            Inscrição estadual aplicada a este endereço. Quando `ShippingState=MG` e o valor não é `ISENTO`, o sistema
            completa com zeros à esquerda até 13 dígitos.
        ShippingCity:
          type: string
          maxLength: 100
          nullable: true
          description: Cidade. Para endereços fora do Brasil (`IDCountry` diferente de `1`), o sistema grava `EXTERIOR`.
        ShippingComplement:
          type: string
          maxLength: 200
          nullable: true
          description: Complemento do endereço.
        ShippingNeighborhood:
          type: string
          maxLength: 100
          nullable: true
          description: Bairro.
        ShippingNumber:
          type: string
          maxLength: 80
          nullable: true
          description: Número do endereço.
        ShippingPostalCode:
          type: string
          maxLength: 10
          nullable: true
          description: CEP. Apenas dígitos são considerados para a consulta IBGE.
        ShippingReceiverName:
          type: string
          maxLength: 100
          nullable: true
          description: Nome do recebedor.
        ShippingState:
          type: string
          maxLength: 2
          nullable: true
          description: UF. Para endereços no exterior, o sistema grava `EX`.
        ShippingStreet:
          type: string
          maxLength: 100
          nullable: true
          description: Logradouro.
        ShippingIbgeCode:
          type: integer
          format: int32
          nullable: true
          description: Código IBGE do município, resolvido a partir do CEP.
        StatusAddress:
          type: integer
          format: int32
          description: '`1` ativo, `0` removido. A listagem só retorna endereços ativos.'
        RecordTimestamp:
          type: string
          format: date-time
          description: Data/hora de cadastro do endereço.
        IDCountry:
          type: integer
          format: int32
          description: Identificador do país. `1` = Brasil.
        Country:
          type: string
          description: Nome do país.
        ConsumerCpfCnpj:
          type: string
          maxLength: 14
          nullable: true
          description: 'CPF ou CNPJ associado ao endereço (pode divergir do cliente, ex.: entrega em nome de terceiro).'
        ConsumerEmail:
          type: string
          maxLength: 200
          nullable: true
          description: E-mail associado ao endereço.
        ConsumerTelephone:
          type: string
          maxLength: 15
          nullable: true
          description: Telefone associado ao endereço.
    ConsumerAddressCreateBody:
      type: object
      description: Corpo do `POST` para cadastrar um endereço de cliente.
      required:
        - ShippingPostalCode
        - ShippingState
        - ShippingCity
        - ShippingStreet
      properties:
        IDCountry:
          type: integer
          format: int32
          default: 1
          description: >-
            Identificador do país. Default `1` (Brasil). Quando diferente de `1`, o sistema valida contra os países
            cadastrados, força `ShippingState=EX` e `ShippingCity=EXTERIOR` e pula a consulta de CEP.
        ShippingPostalCode:
          type: string
          maxLength: 10
          description: CEP. Para `IDCountry=1`, o sistema consulta a base de CEP interna para resolver o código IBGE do município.
        ShippingState:
          type: string
          maxLength: 2
          description: UF.
        ShippingCity:
          type: string
          maxLength: 100
          description: Cidade.
        ShippingNeighborhood:
          type: string
          maxLength: 100
          nullable: true
          description: Bairro.
        ShippingStreet:
          type: string
          maxLength: 100
          description: Logradouro.
        ShippingNumber:
          type: string
          maxLength: 80
          nullable: true
          description: Número.
        ShippingComplement:
          type: string
          maxLength: 200
          nullable: true
          description: Complemento.
        ShippingReceiverName:
          type: string
          maxLength: 100
          nullable: true
          description: Nome do recebedor.
        ConsumerStateInscription:
          type: string
          maxLength: 20
          nullable: true
          description: >-
            Inscrição estadual. Quando `ShippingState=MG` e o valor não for `ISENTO`, é preenchido à esquerda com zeros
            até 13 dígitos.
        ConsumerCpfCnpj:
          type: string
          maxLength: 14
          nullable: true
          description: CPF ou CNPJ vinculado ao endereço (quando difere do cliente).
    ConsumerAddressUpdateBody:
      type: object
      description: Corpo do `PUT` para atualizar um endereço de cliente. Todos os campos são opcionais — envie só os que mudaram.
      properties:
        IDCountry:
          type: integer
          format: int32
          description: >-
            Identificador do país. Quando ausente, é assumido como `1` (Brasil). Diferente de `1` força
            `ShippingState=EX` e `ShippingCity=EXTERIOR` e pula a consulta de CEP.
        ShippingPostalCode:
          type: string
          maxLength: 10
          nullable: true
          description: CEP. Para `IDCountry=1`, dispara consulta da base de CEP interna para resolver o código IBGE.
        ShippingState:
          type: string
          maxLength: 2
          nullable: true
          description: UF.
        ShippingCity:
          type: string
          maxLength: 100
          nullable: true
          description: Cidade.
        ShippingNeighborhood:
          type: string
          maxLength: 100
          nullable: true
          description: Bairro.
        ShippingStreet:
          type: string
          maxLength: 100
          nullable: true
          description: Logradouro.
        ShippingNumber:
          type: string
          maxLength: 80
          nullable: true
          description: Número.
        ShippingComplement:
          type: string
          maxLength: 200
          nullable: true
          description: Complemento.
        ShippingReceiverName:
          type: string
          maxLength: 100
          nullable: true
          description: Nome do recebedor.
        ConsumerStateInscription:
          type: string
          maxLength: 20
          nullable: true
          description: >-
            Inscrição estadual. Quando `ShippingState=MG` e o valor não for `ISENTO`, é preenchido à esquerda com zeros
            até 13 dígitos.
        ConsumerCpfCnpj:
          type: string
          maxLength: 14
          nullable: true
          description: CPF ou CNPJ vinculado ao endereço.
        ConsumerEmail:
          type: string
          maxLength: 200
          nullable: true
          description: E-mail vinculado ao endereço.
        ConsumerTelephone:
          type: string
          maxLength: 15
          nullable: true
          description: Telefone vinculado ao endereço.
    ConsumerContact:
      type: object
      description: Contato vinculado ao cliente.
      properties:
        IDConsumerContact:
          type: integer
          format: int32
          description: Identificador do contato.
        ContactName:
          type: string
          maxLength: 100
          description: Nome do contato.
        ContactEmail:
          type: string
          maxLength: 100
          nullable: true
          description: E-mail do contato.
        ContactTelephone:
          type: string
          maxLength: 100
          nullable: true
          description: Telefone do contato.
        ContactResponsability:
          type: string
          maxLength: 100
          nullable: true
          description: Responsabilidade ou cargo do contato.
        LegalRepresentative:
          type: integer
          format: int32
          default: 0
          description: '`1` quando o contato é representante legal do cliente; `0` caso contrário.'
        RecordTimestamp:
          type: string
          format: date-time
          description: Data/hora do cadastro.
    ConsumerContactCreateBody:
      type: object
      description: Corpo do `POST` para criar um contato.
      required:
        - ContactName
      properties:
        ContactName:
          type: string
          maxLength: 100
          description: Nome do contato.
        ContactEmail:
          type: string
          maxLength: 100
          nullable: true
          description: E-mail do contato.
        ContactTelephone:
          type: string
          maxLength: 100
          nullable: true
          description: Telefone do contato. Aceita também a chave `ContactTelephon` (typo histórico) como fallback.
        ContactResponsability:
          type: string
          maxLength: 100
          nullable: true
          description: Responsabilidade ou cargo do contato.
        LegalRepresentative:
          type: integer
          format: int32
          default: 0
          description: '`1` para marcar como representante legal; `0` caso contrário. Default `0`.'
    ConsumerContactUpdateBody:
      type: object
      description: Corpo do `PUT` para atualizar um contato. Apenas os campos enviados são alterados.
      properties:
        ContactName:
          type: string
          maxLength: 100
          description: Nome do contato.
        ContactEmail:
          type: string
          maxLength: 100
          nullable: true
          description: E-mail do contato.
        ContactTelephone:
          type: string
          maxLength: 100
          nullable: true
          description: Telefone do contato.
        ContactResponsability:
          type: string
          maxLength: 100
          nullable: true
          description: Responsabilidade ou cargo do contato.
        LegalRepresentative:
          type: integer
          format: int32
          description: '`1` para marcar como representante legal; `0` caso contrário.'
    ConsumerCreditBody:
      type: object
      description: Corpo do `POST`/`PUT` de crédito do cliente.
      required:
        - IDTypePayment
        - CreditValue
      properties:
        IDTypePayment:
          type: integer
          format: int32
          description: >-
            Forma de pagamento (`TypePayment`) cadastrada para a empresa autenticada. Um cliente não pode ter dois
            créditos para a mesma forma de pagamento.
        CreditValue:
          type: number
          format: decimal
          multipleOf: 0.01
          description: Valor do limite de crédito.
        CommercialConditions:
          type: string
          maxLength: 45
          nullable: true
          description: 'Condições comerciais livres (ex.: prazo negociado, observações).'
    ConsumerVoucher:
      type: object
      description: Movimento de vale (crédito ou consumo) do cliente.
      properties:
        IDConsumerVoucher:
          type: integer
          format: int32
          description: Identificador do movimento.
        IDConsumer:
          type: integer
          format: int32
          description: Cliente dono do vale.
        IDOrder:
          type: integer
          format: int32
          nullable: true
          description: Pedido que originou o consumo do vale, quando aplicável.
        Value:
          type: number
          format: decimal
          multipleOf: 0.01
          description: Valor do movimento (sempre positivo). O sinal é dado por `IDTypeAccount`.
        IDTypeAccount:
          type: integer
          format: int32
          enum:
            - 0
            - 1
          description: >-
            Tipo do movimento — `0` entrada (crédito gerado a favor do cliente), `1` saída (consumo do vale em um
            pedido).
        RecordUserCreated:
          type: integer
          format: int32
          nullable: true
          description: Usuário que registrou o movimento.
        Comments:
          type: string
          maxLength: 200
          nullable: true
          description: Comentário livre sobre o movimento.
        IDCompanyInvoice:
          type: integer
          format: int32
          nullable: true
          description: Empresa faturadora dona do saldo (quando o vale é específico de um faturador).
        RecordTimestamp:
          type: string
          format: date-time
          description: Data/hora do movimento.
        AccountName:
          type: string
          description: Nome da conta da empresa.
        UserName:
          type: string
          nullable: true
          description: Nome do usuário que registrou.
        Login:
          type: string
          nullable: true
          description: Login do usuário que registrou.
        AccountNameInvoice:
          type: string
          nullable: true
          description: Nome da conta do faturador (`IDCompanyInvoice`).
        BalanceValue:
          type: number
          format: decimal
          multipleOf: 0.01
          description: >-
            Saldo acumulado por cliente + faturador, calculado por janela ordenada pela data do movimento (`SUM` com
            `OVER PARTITION BY`).
    ConsumerVoucherCreateBody:
      type: object
      description: Corpo do `POST` para gerar um vale (movimento de entrada) para o cliente.
      required:
        - Value
      properties:
        Value:
          type: number
          format: decimal
          multipleOf: 0.01
          description: Valor do vale. Precisa ser numérico e estritamente positivo.
        Comments:
          type: string
          maxLength: 200
          nullable: true
          description: Comentário livre.
        IDCompanyInvoice:
          type: integer
          format: int32
          nullable: true
          description: >-
            Empresa faturadora à qual o vale fica vinculado. Se omitido, o sistema usa a empresa do cliente. Quando
            informado e diferente da empresa do cliente, é validado como faturador filho dela (`CompanyMain`).
    ConsumerVoucherDeleteBody:
      type: object
      description: Corpo opcional do `DELETE` de vale.
      properties:
        Comments:
          type: string
          maxLength: 200
          nullable: true
          description: Comentário livre registrado no log de exclusão.
    ConsumerSalesmanBody:
      type: object
      description: Corpo do `POST` para vincular um vendedor ao cliente.
      required:
        - IDAcess
      properties:
        IDAcess:
          type: integer
          format: int32
          description: >-
            Identificador do vínculo usuário-empresa (`IDAcess`) que representa o vendedor. Precisa estar ativo e
            pertencer à mesma empresa do cliente. A combinação `IDConsumer` + `IDAcess` é única; um vínculo já existente
            é mantido/atualizado (upsert).
    ConsumerDetail:
      type: object
      description: >-
        Detalhe completo do cliente devolvido pelos endpoints de criação/edição/exclusão de blocos vinculados. Inclui
        dados cadastrais, endereços, contatos, vendedores, créditos, cartões salvos, histórico de alterações
        (`ConsumerLog`) e arquivos. Mesmo shape de `GET /consumer/{idconsumer}`.
      properties:
        IDConsumer:
          type: integer
          format: int32
          description: Identificador do cliente.
        ConsumerNameCorporateName:
          type: string
          nullable: true
          description: Nome (PF) ou razão social (PJ).
        ConsumerTradeName:
          type: string
          nullable: true
          description: Nome fantasia.
        ConsumerCpfCnpj:
          type: string
          nullable: true
          description: CPF (PF) ou CNPJ (PJ).
        ConsumerEmail:
          type: string
          nullable: true
          description: E-mail principal.
        ConsumerTelephone:
          type: string
          nullable: true
          description: Telefone principal.
        ConsumerBirthDate:
          type: string
          format: date
          nullable: true
          description: Data de nascimento (PF).
        ConsumerType:
          type: integer
          format: int32
          description: 'Tipo do cliente: `1` Pessoa Física, `2` Pessoa Jurídica, `3` Estrangeiro.'
          enum:
            - 1
            - 2
            - 3
        StatusConsumer:
          type: integer
          format: int32
          description: Status do cadastro (`TypeStatusConsumer`).
          enum:
            - 0
            - 1
            - 2
            - 3
        Address:
          type: array
          description: Endereços ativos.
          items:
            $ref: '#/components/schemas/ConsumerAddress'
        Contacts:
          type: array
          description: Contatos do cliente.
          items:
            $ref: '#/components/schemas/ConsumerContact'
        ConsumerCredit:
          type: array
          description: Limites de crédito por forma de pagamento (já com saldo utilizado e disponível calculados).
          items:
            type: object
            properties:
              IDConsumerCredit:
                type: integer
                format: int32
                description: Identificador interno do crédito.
              IDTypePayment:
                type: integer
                format: int32
                description: Forma de pagamento à qual o crédito está vinculado (`IDTypePayment`).
              TypePaymentDescription:
                type: string
                description: Descrição da forma de pagamento.
              CreditValue:
                type: number
                format: decimal
                multipleOf: 0.01
                description: Valor do limite de crédito concedido para a forma de pagamento.
              CommercialConditions:
                type: string
                nullable: true
                description: 'Condições comerciais livres (ex.: prazo negociado, observações).'
              CreditValueUsed:
                type: number
                format: decimal
                multipleOf: 0.01
                description: Valor já utilizado considerando contas a receber em aberto, líquido de baixas bancárias.
              CreditValueLeft:
                type: number
                format: decimal
                multipleOf: 0.01
                description: Saldo restante (`CreditValue - CreditValueUsed`).
        ConsumerSalesman:
          type: array
          description: Vendedores vinculados.
          items:
            type: object
            properties:
              IDConsumerSalesman:
                type: integer
                format: int32
                description: Identificador do vínculo cliente–vendedor.
              IDAcess:
                type: integer
                format: int32
                description: Identificador do vínculo usuário–empresa que representa o vendedor (`IDAcess`).
              Login:
                type: string
                description: Login (email) do vendedor.
              UserName:
                type: string
                description: Nome do vendedor.
              RecordTimestamp:
                type: string
                format: date-time
                description: Data/hora em que o vínculo foi criado.
        ConsumerCreditCard:
          type: array
          description: Cartões de crédito salvos.
          items:
            type: object
            additionalProperties: true
        ConsumerLog:
          type: array
          description: Histórico de alterações do cadastro.
          items:
            type: object
            additionalProperties: true
        ConsumerFile:
          type: array
          description: Arquivos anexos do cliente (com URL pré-assinada para download).
          items:
            type: object
            additionalProperties: true
        ConsumerVoucherValue:
          type: number
          format: decimal
          multipleOf: 0.01
          nullable: true
          description: >-
            Saldo total dos vales do cliente. Filtrado por faturador quando `BlockVoucherDifferentCompanyInvoice` está
            ativo.
        OrderQuantity:
          type: integer
          format: int32
          description: Total de pedidos do cliente.
        OrderRevenueValueTotal:
          type: number
          format: decimal
          multipleOf: 0.01
          nullable: true
          description: Soma das contas a receber do cliente.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data/hora do cadastro.
        DateLastRecordModification:
          type: string
          format: date-time
          nullable: true
          description: Última atualização.
    UserSigninLocalBody:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          description: >-
            `Login` do usuário (email) ou CPF/CNPJ. O sistema detecta automaticamente o formato e busca pelo campo
            correspondente.
        password:
          type: string
          format: password
          description: Senha em texto plano. É comparada com o hash armazenado.
        mfacode:
          type: string
          nullable: true
          description: >-
            Código de MFA. Obrigatório apenas quando o usuário tem `MFAEnabled = 1`: 6 dígitos recebidos por email (MFA
            `email`) ou o código atual do Google Authenticator (MFA `totp`).
        expireinhour:
          type: string
          nullable: true
          description: 'Tempo de expiração do token JWT, no formato aceito pelo `jsonwebtoken` (ex.: `12h`, `7d`). Default `14h`.'
    UserSigninResponse:
      type: object
      description: Resposta de login concluído com sucesso.
      properties:
        success:
          type: boolean
          description: Sempre `true` neste retorno.
        token:
          type: string
          description: Token JWT a ser enviado em `Authorization` nas próximas requisições.
        body:
          type: object
          description: Dados do usuário autenticado para o frontend exibir.
          properties:
            id:
              type: integer
              description: Identificador `IDUser`.
            email:
              type: string
              description: '`Login` do usuário (email).'
            UserName:
              type: string
              description: Nome do usuário.
            CompanyCpfCnpj:
              type: string
              nullable: true
              description: CPF/CNPJ da empresa.
            Salesman:
              type: integer
              nullable: true
              description: Indica se o usuário é vendedor da empresa.
            RestrictAccessSalesman:
              type: integer
              nullable: true
              description: Indica se o acesso do vendedor é restrito (vê apenas seus pedidos).
            CompanyNameCorporateName:
              type: string
              description: Razão social da empresa.
            CompanyLogoUrl:
              type: string
              nullable: true
              description: URL do logo da empresa.
            CompanyLogoUrlMain:
              type: string
              nullable: true
              description: URL do logo da empresa principal do grupo.
            AccountNameMain:
              type: string
              description: '`AccountName` da empresa principal do grupo.'
            CompanyNameCorporateNameMain:
              type: string
              description: Razão social da empresa principal do grupo.
            ExternalDashboard:
              type: string
              nullable: true
              description: URL de dashboard externo configurado.
            Theme:
              type: string
              nullable: true
              description: Tema visual padrão da empresa.
            UserImageUrl:
              type: string
              nullable: true
              description: URL da foto do usuário.
            IDModuleFavorite:
              type: array
              items:
                type: string
              description: Lista de módulos favoritados pelo usuário (ids).
            HelpDeskToken:
              type: string
              description: JWT para autenticar o usuário no portal de chamados.
            HelpDeskChatToken:
              type: string
              description: JWT para autenticar o usuário no chat de suporte.
            CompanyPaymentStatus:
              type: integer
              nullable: true
              description: Status financeiro da empresa.
            Parameters:
              type: array
              description: Parâmetros da integração de notificações da empresa.
              items:
                type: object
            ChatIA:
              type: integer
              enum:
                - 0
                - 1
              description: '`1` quando o usuário tem habilitada a integração de chat com IA; caso contrário, `0`.'
            IDCompanyMainShare:
              type: integer
              nullable: true
              description: Identificador da empresa cujos dados estão sendo compartilhados com a empresa atual.
            CompanyMainShare:
              type: string
              nullable: true
              description: '`AccountName` da empresa que compartilha dados com a atual.'
            DaysBeforePasswordExpiration:
              type: integer
              nullable: true
              description: Dias restantes para a senha expirar. `null` quando não há expiração configurada.
    UserSigninMFAChallenge:
      type: object
      description: >-
        Desafio de MFA. Retornado quando o usuário precisa fornecer (ou cadastrar) um segundo fator antes de receber o
        token.
      properties:
        MFAEnabled:
          type: boolean
          description: Sempre `true` neste retorno.
        MFAType:
          type: string
          enum:
            - email
            - totp
          description: Tipo de MFA configurado para o usuário.
        EnrollmentRequired:
          type: boolean
          nullable: true
          description: >-
            Presente apenas no primeiro acesso com MFA `totp`. `true` indica que o usuário precisa cadastrar o segredo
            no Google Authenticator usando `OtpAuthUrl`.
        OtpAuthUrl:
          type: string
          nullable: true
          description: >-
            URL no formato `otpauth://` para o usuário escanear no Google Authenticator. Presente apenas quando
            `EnrollmentRequired = true`.
        Message:
          type: string
          nullable: true
          description: >-
            Mensagem orientando o próximo passo (ex.: `Código enviado por e-mail`, `Digite o codigo do Google
            Authenticator`).
    UserPasswordResetConfirmBody:
      type: object
      required:
        - password
      properties:
        password:
          type: string
          format: password
          description: >-
            Nova senha em texto plano. Precisa atender às regras configuradas pela empresa (tamanho mínimo,
            complexidade, histórico).
    UserWorkScale:
      type: object
      description: Escala de trabalho com seus turnos.
      properties:
        AccountName:
          type: string
          description: Conta a que a escala pertence.
        IDUserWorkScale:
          type: integer
          format: int32
          description: Identificador da escala.
        UserWorkScaleName:
          type: string
          maxLength: 45
          description: Nome da escala.
        WorkShift:
          type: array
          description: Turnos que compõem a escala.
          items:
            type: object
            properties:
              IDUserWorkShift:
                type: integer
                format: int32
                description: Identificador do turno.
              IDUserWorkScale:
                type: integer
                format: int32
                description: Identificador da escala dona deste turno.
              WeekDay:
                type: integer
                minimum: 0
                maximum: 6
                description: 'Dia da semana: `0`=domingo, `1`=segunda, `2`=terça, `3`=quarta, `4`=quinta, `5`=sexta, `6`=sábado.'
              StartTime:
                type: string
                pattern: ^\d{2}:\d{2}(:\d{2})?$
                description: Horário de início do turno (`HH:mm:ss`).
              FinishTime:
                type: string
                pattern: ^\d{2}:\d{2}(:\d{2})?$
                description: Horário de fim do turno (`HH:mm:ss`).
    UserWorkScaleCreateBody:
      type: object
      required:
        - UserWorkScaleName
      properties:
        UserWorkScaleName:
          type: string
          maxLength: 45
          description: Nome da escala. Precisa ser único dentro da empresa.
    UserWorkScaleUpdateBody:
      type: object
      required:
        - UserWorkScaleName
      properties:
        UserWorkScaleName:
          type: string
          maxLength: 45
          description: Novo nome da escala. Precisa ser único dentro da empresa.
    UserWorkShiftCreateBody:
      type: object
      required:
        - IDUserWorkScale
        - shifts
      properties:
        IDUserWorkScale:
          type: integer
          format: int32
          description: Identificador da escala cujos turnos serão substituídos.
        shifts:
          type: array
          description: Lista completa dos turnos da escala. O sistema apaga os turnos atuais e insere estes no lugar.
          items:
            type: object
            required:
              - WeekDay
              - StartTime
              - FinishTime
            properties:
              WeekDay:
                type: integer
                minimum: 0
                maximum: 6
                description: 'Dia da semana: `0`=domingo, `1`=segunda, `2`=terça, `3`=quarta, `4`=quinta, `5`=sexta, `6`=sábado.'
              StartTime:
                type: string
                pattern: ^\d{2}:\d{2}(:\d{2})?$
                description: Horário de início do turno (`HH:mm:ss`).
              FinishTime:
                type: string
                pattern: ^\d{2}:\d{2}(:\d{2})?$
                description: Horário de fim do turno (`HH:mm:ss`).
    UserNotification:
      type: object
      description: Versão do sistema marcada como atual e suas novidades publicadas.
      properties:
        IDSystemVersion:
          type: integer
          format: int32
          description: Identificador da versão.
        Version:
          type: string
          maxLength: 45
          description: Número/rótulo da versão.
        DateRelease:
          type: string
          format: date
          description: Data de liberação da versão.
        Current:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` quando esta é a versão atual exibida ao usuário.'
        Updates:
          type: array
          description: Novidades publicadas nessa versão.
          items:
            type: object
            properties:
              IDSystemVersionUpdate:
                type: integer
                format: int32
                description: Identificador da novidade.
              Update:
                type: string
                maxLength: 1000
                description: Título da novidade.
              Kind:
                type: string
                maxLength: 45
                nullable: true
                description: 'Categoria da novidade (ex.: `Novidade`, `Correção`).'
              RecordTimestamp:
                type: string
                format: date-time
                description: Quando a novidade foi publicada.
              Description:
                type: string
                maxLength: 1000
                nullable: true
                description: Descrição detalhada.
              URLImage:
                type: string
                maxLength: 500
                nullable: true
                description: URL de imagem ilustrativa.
              URLRedirect:
                type: string
                maxLength: 500
                nullable: true
                description: Link de saiba mais.
              Confirm:
                type: integer
                enum:
                  - 0
                  - 1
                description: '`1` quando o usuário autenticado já confirmou a leitura desta novidade; caso contrário, `0`.'
    UserCompany:
      type: object
      description: Vínculo do usuário com uma empresa.
      properties:
        IDCompany:
          type: integer
          format: int32
          description: Identificador da empresa.
        AccountName:
          type: string
          description: Identificador textual da conta (subdomínio).
        IDUser:
          type: integer
          format: int32
          description: Identificador do usuário.
        Salesman:
          type: integer
          nullable: true
          description: Indica se o usuário é vendedor nessa empresa.
        CertificadoBestBeforeDate:
          type: string
          format: date
          nullable: true
          description: Validade do certificado digital da empresa.
        CompanyTradeName:
          type: string
          nullable: true
          description: Nome fantasia.
        NfeSerie:
          type: string
          nullable: true
          description: Série de NFe em uso.
        NfeUltima:
          type: integer
          nullable: true
          description: Último número de NFe emitido.
        CompanyNameCorporateName:
          type: string
          description: Razão social.
        Login:
          type: string
          description: '`Login` (email) do usuário.'
        UserName:
          type: string
          description: Nome do usuário.
        CompanyLogoUrl:
          type: string
          nullable: true
          description: URL do logo da empresa.
    UserCompanyInvoice:
      type: object
      description: Vínculo do usuário com uma empresa faturadora.
      properties:
        IDUserCompanyInvoice:
          type: integer
          format: int32
          description: Identificador do vínculo.
        IDCompany:
          type: integer
          format: int32
          description: Identificador da empresa faturadora.
        IDUser:
          type: integer
          format: int32
          description: Identificador do usuário.
        CompanyCpfCnpj:
          type: string
          nullable: true
          description: CPF/CNPJ da faturadora.
        CompanyNameCorporateName:
          type: string
          description: Razão social da faturadora.
        AccountName:
          type: string
          description: '`AccountName` da faturadora.'
    UserMenuGroup:
      type: object
      description: Grupo de módulos exibido como uma seção no menu lateral.
      properties:
        IDModuleGroup:
          type: integer
          format: int32
          description: Identificador do grupo.
        ModuleGroupDescription:
          type: string
          description: 'Nome do grupo (ex.: `Financeiro`, `Estoque`).'
        iconName:
          type: string
          nullable: true
          description: Ícone do grupo no menu antigo.
        newIconName:
          type: string
          nullable: true
          description: Ícone do grupo no menu novo.
        link:
          type: string
          nullable: true
          description: Link padrão do grupo.
        index:
          type: integer
          nullable: true
          description: Ordem de exibição.
        Module:
          type: array
          description: Módulos que compõem o grupo.
          items:
            $ref: '#/components/schemas/UserMenuItem'
    UserMenuItem:
      type: object
      description: Item de menu (módulo ou submódulo). Em `Version=2`, `Module` traz os submódulos aninhados.
      properties:
        IDUserPrivilege:
          type: integer
          format: int32
          description: Identificador do privilégio que libera este item.
        IDModule:
          type: integer
          format: int32
          description: Identificador do módulo.
        ModuleDescription:
          type: string
          description: 'Nome amigável do módulo (ex.: `Contas a Pagar`).'
        link:
          type: string
          nullable: true
          description: 'Rota no frontend (ex.: `/accounts/payable`).'
        icon:
          type: string
          nullable: true
          description: Ícone do item no menu antigo.
        newIcon:
          type: string
          nullable: true
          description: Ícone do item no menu novo.
        header:
          type: string
          nullable: true
          description: Título exibido no topo da tela.
        KeyWords:
          type: string
          nullable: true
          description: Palavras-chave para a busca dentro do menu.
        Module:
          type: array
          nullable: true
          description: Submódulos aninhados. Presente apenas em `Version=2`. Lista vazia `[]` quando não há filhos.
          items:
            type: object
            properties:
              IDUserPrivilege:
                type: integer
                format: int32
                description: Identificador do privilégio (`IDUserPrivilege`) que libera o item de menu para o usuário.
              IDModule:
                type: integer
                format: int32
                description: Identificador do módulo (`IDModule`) ao qual o item de menu pertence.
              ModuleDescription:
                type: string
                description: >-
                  Descrição amigável do módulo, exibida como rótulo do item no menu (ex.: `Contas a Pagar`, `Pedidos`,
                  `SKUs`).
              link:
                type: string
                nullable: true
                description: >-
                  Rota interna do frontend a que o item leva quando clicado (ex.: `/accounts/payable`). Vazio em itens
                  que apenas agrupam submenus.
              icon:
                type: string
                nullable: true
                description: Nome do ícone clássico exibido ao lado do item de menu (referência ao set de ícones do frontend).
              newIcon:
                type: string
                nullable: true
                description: Nome do ícone novo (set Phosphor/Lucide usado no redesign) exibido ao lado do item.
              header:
                type: string
                nullable: true
                description: Título adicional exibido em cabeçalhos de seção do menu/breadcrumb quando o item é um agrupador.
              KeyWords:
                type: string
                nullable: true
                description: >-
                  Palavras-chave em português separadas por vírgula usadas pela busca global do menu para casar termos
                  digitados pelo usuário com o item.
    UserPrivilegeGroup:
      type: object
      description: Perfil de acesso (grupo de privilégios) configurado para a empresa.
      properties:
        IDUserPrivilegeGroup:
          type: integer
          format: int32
          description: Identificador do perfil.
        PrivilegeGroupName:
          type: string
          description: Nome do perfil.
        Module:
          type: array
          description: Módulos cobertos pelo perfil, cada um com seus privilégios.
          items:
            type: object
            properties:
              IDModule:
                type: integer
                format: int32
                description: Identificador do módulo.
              ModuleDescription:
                type: string
                description: Nome do módulo.
              Privilege:
                type: array
                description: Privilégios do módulo.
                items:
                  type: object
                  properties:
                    IDUserPrivilege:
                      type: integer
                      format: int32
                      description: Identificador do privilégio.
                    UserPrivilege:
                      type: string
                      description: 'Chave técnica do privilégio (ex.: `PrivilegeAccountsPayableInsert`).'
                    PrivilegeDescription:
                      type: string
                      description: Nome amigável do privilégio.
    UserLoginPayload:
      type: object
      description: Payload de login reidratado. Mesmo formato do campo `body` retornado em `POST /user/signin/local`.
      properties:
        id:
          type: integer
          description: Identificador `IDUser`.
        email:
          type: string
          description: '`Login` do usuário.'
        UserName:
          type: string
          description: Nome do usuário.
        Salesman:
          type: integer
          nullable: true
          description: >-
            `1` quando o usuário é vendedor (acessa relatórios de comissão e atua como vendedor em pedidos); `0`/`null`
            caso contrário.
        RestrictAccessSalesman:
          type: integer
          nullable: true
          description: >-
            `1` quando o vendedor só enxerga os próprios pedidos/clientes (restrição de visão de carteira); `0`/`null`
            quando enxerga toda a base.
        CompanyNameCorporateName:
          type: string
          description: Razão social da empresa em que o usuário está logado.
        CompanyLogoUrl:
          type: string
          nullable: true
          description: URL do logotipo da empresa para exibição no cabeçalho.
        CompanyLogoUrlMain:
          type: string
          nullable: true
          description: >-
            URL do logotipo da empresa-mãe quando o usuário está em uma filial (em ambientes multi-empresa). Repete
            `CompanyLogoUrl` quando não há empresa-mãe.
        AccountNameMain:
          type: string
          description: >-
            Subdomínio da empresa-mãe (em ambientes multi-empresa). Repete o subdomínio da empresa atual quando não há
            empresa-mãe.
        CompanyNameCorporateNameMain:
          type: string
          description: >-
            Razão social da empresa-mãe (em ambientes multi-empresa). Repete a razão social atual quando não há
            empresa-mãe.
        ExternalDashboard:
          type: string
          nullable: true
          description: >-
            URL de dashboard externo embutido no sistema (ex.: relatórios em ferramenta de BI). Vazio quando não
            configurado.
        Theme:
          type: string
          nullable: true
          description: >-
            Tema visual aplicado ao usuário (`light`/`dark` ou nome do tema customizado). Vazio quando usa o tema
            padrão.
        UserImageUrl:
          type: string
          nullable: true
          description: URL da foto/avatar do usuário.
        IDModuleFavorite:
          type: array
          items:
            type: string
          description: Lista de IDs de módulos marcados como favoritos pelo usuário, para atalhos no menu.
        HelpDeskToken:
          type: string
          description: Token JWT para autenticar o usuário no widget de help desk (Zendesk).
        HelpDeskChatToken:
          type: string
          description: Token JWT para autenticar o usuário no chat do help desk (Zendesk Chat).
        CompanyPaymentStatus:
          type: integer
          nullable: true
          description: >-
            Status financeiro da assinatura da empresa no idworks (ex.: `1` em dia, outros valores indicam
            inadimplência) — usado para bloquear funcionalidades quando a assinatura está em atraso.
        Parameters:
          type: array
          items:
            type: object
          description: >-
            Lista de parâmetros de integrações configuradas para a empresa, retornados quando o login é feito por um
            usuário com acesso a integrações (cada item traz a chave e o valor da parametrização da integração).
    TaxDepartmentSummary:
      type: object
      description: Resumo de departamento fiscal (formato da lista).
      properties:
        IDTaxDepartment:
          type: integer
          description: Identificador do departamento fiscal.
        TaxDepartmentDescription:
          type: string
          maxLength: 100
          description: Nome do departamento fiscal.
        Status:
          type: integer
          enum:
            - 0
            - 1
          description: Situação. `1` ativo; `0` inativo.
        AccountName:
          type: string
          description: Identificador da conta (subdomínio) à qual o departamento pertence.
    TaxDepartmentCreateBody:
      type: object
      required:
        - TaxDepartmentDescription
      properties:
        TaxDepartmentDescription:
          type: string
          maxLength: 100
          description: Nome do departamento fiscal. Deve ser único entre os departamentos ativos da empresa.
    TaxDepartmentUpdateBody:
      type: object
      required:
        - TaxDepartmentDescription
      properties:
        TaxDepartmentDescription:
          type: string
          maxLength: 100
          description: Novo nome do departamento fiscal. Deve permanecer único entre os departamentos ativos da empresa.
    TaxDepartmentDetail:
      type: object
      description: Detalhe de um departamento fiscal com o array de regras fiscais (`Cfop[]`).
      properties:
        IDTaxDepartment:
          type: integer
          description: Identificador do departamento fiscal.
        TaxDepartmentDescription:
          type: string
          maxLength: 100
          description: Nome do departamento fiscal.
        Status:
          type: integer
          enum:
            - 0
            - 1
          description: Situação. `1` ativo; `0` inativo.
        AccountName:
          type: string
          description: Identificador da conta (subdomínio).
        Cfop:
          type: array
          description: >-
            Regras fiscais (CFOPs) cadastradas no departamento. Cada item ordenado pela flag `Standard` (regras padrão
            primeiro).
          items:
            $ref: '#/components/schemas/TaxCfopSummary'
    TaxCfopSummary:
      type: object
      description: >-
        Resumo de uma regra fiscal (CFOP) dentro do departamento (formato do array `Cfop[]` no `GET
        /tax/{idtaxdepartment}`).
      properties:
        IDTax:
          type: integer
          description: Identificador da regra fiscal.
        IDTaxDepartment:
          type: integer
          description: Identificador do departamento fiscal.
        IDCompany:
          type: integer
          description: Identificador da empresa (matriz ou filial) à qual a regra pertence.
        CompanyTradeName:
          type: string
          nullable: true
          description: Nome fantasia da empresa.
        CompanyNameCorporateNameInvoice:
          type: string
          nullable: true
          description: Razão social da empresa (usada na nota).
        AccountNameInvoice:
          type: string
          nullable: true
          description: Identificador da conta da empresa emissora.
        TypeTaxName:
          type: string
          nullable: true
          maxLength: 100
          description: Apelido da regra fiscal.
        Standard:
          type: integer
          enum:
            - 0
            - 1
          description: Quando `1`, indica que esta é a regra padrão da operação.
        Gratification:
          type: integer
          enum:
            - 0
            - 1
          description: Quando `1`, regra de bonificação (saída sem cobrança).
        NfeindFinal:
          type: integer
          enum:
            - 0
            - 1
          description: Indicador de consumidor final. `1` Consumidor Final; `0` Normal.
        NfeindFinalDescription:
          type: string
          description: Descrição textual de `NfeindFinal` (`Consumidor Final` ou `Normal`).
        NfeTaxPayer:
          type: integer
          enum:
            - 0
            - 1
          description: Indicador de destinatário contribuinte do ICMS.
        NfeExport:
          type: integer
          enum:
            - 0
            - 1
          description: Quando `1`, indica operação de importação/exportação.
        TaxSkuCest:
          type: string
          nullable: true
          maxLength: 15
          description: CEST (Código Especificador da Substituição Tributária) — sobrescreve o cadastrado no SKU.
        PisCst:
          type: string
          nullable: true
          maxLength: 2
          description: CST PIS (saída).
        PisAliquot:
          type: number
          nullable: true
          description: Alíquota PIS (saída), em decimal (0–1).
        CofinsCst:
          type: string
          nullable: true
          maxLength: 2
          description: CST COFINS (saída).
        CofinsAliquot:
          type: number
          nullable: true
          description: Alíquota COFINS (saída), em decimal (0–1).
        NfCstCofinsDescription:
          type: string
          nullable: true
          description: Descrição do CST COFINS (saída).
        NfCstPisDescription:
          type: string
          nullable: true
          description: Descrição do CST PIS (saída).
        PisCstInbound:
          type: string
          nullable: true
          maxLength: 2
          description: CST PIS (entrada).
        PisAliquotInbound:
          type: number
          nullable: true
          description: Alíquota PIS (entrada), em decimal.
        CofinsCstInbound:
          type: string
          nullable: true
          maxLength: 2
          description: CST COFINS (entrada).
        CofinsAliquotInbound:
          type: number
          nullable: true
          description: Alíquota COFINS (entrada), em decimal.
        NfCstCofinsInboundDescription:
          type: string
          nullable: true
          description: Descrição do CST COFINS (entrada).
        NfCstPisInboundDescription:
          type: string
          nullable: true
          description: Descrição do CST PIS (entrada).
        IpiCst:
          type: string
          nullable: true
          maxLength: 2
          description: CST IPI (saída).
        IpiAliquot:
          type: number
          nullable: true
          description: Alíquota IPI (saída), em decimal.
        IpiCEnq:
          type: string
          nullable: true
          maxLength: 3
          description: Enquadramento legal do IPI (saída).
        NfCstIpiDescription:
          type: string
          nullable: true
          description: Descrição do CST IPI (saída).
        NfIpiCEnqDescription:
          type: string
          nullable: true
          description: Descrição do enquadramento legal do IPI.
        IpiCstInbound:
          type: string
          nullable: true
          maxLength: 2
          description: CST IPI (entrada).
        IpiAliquotInbound:
          type: number
          nullable: true
          description: Alíquota IPI (entrada), em decimal.
        NfCstIpiInboundDescription:
          type: string
          nullable: true
          description: Descrição do CST IPI (entrada).
        CfopOutboundInState:
          type: integer
          nullable: true
          description: CFOP de saída para operação dentro do estado (dígito inicial 5 ou 7).
        CfopOutboundInStateDescription:
          type: string
          nullable: true
          description: Descrição/Natureza da operação do CFOP de saída no estado.
        CfopOutboundOutState:
          type: integer
          nullable: true
          description: CFOP de saída para operação fora do estado (dígito inicial 6).
        CfopOutboundOutStateDescription:
          type: string
          nullable: true
          description: Descrição/Natureza da operação do CFOP de saída fora do estado.
        CfopInboundInState:
          type: integer
          nullable: true
          description: CFOP de entrada para operação dentro do estado (dígito inicial 1 ou 3).
        CfopInboundInStateDescription:
          type: string
          nullable: true
          description: Descrição/Natureza da operação do CFOP de entrada no estado.
        CfopInboundOutState:
          type: integer
          nullable: true
          description: CFOP de entrada para operação fora do estado (dígito inicial 2).
        CfopInboundOutStateDescription:
          type: string
          nullable: true
          description: Descrição/Natureza da operação do CFOP de entrada fora do estado.
    TaxCfopDetail:
      type: object
      description: Detalhe completo de uma regra fiscal (CFOP) com as regras ICMS por estado (`Icms[]`).
      properties:
        IDCompany:
          type: integer
          description: Identificador da empresa (matriz ou filial) à qual a regra pertence.
        CompanyTradeName:
          type: string
          nullable: true
          description: Nome fantasia da empresa.
        CompanyNameCorporateNameInvoice:
          type: string
          nullable: true
          description: Razão social da empresa (usada na nota).
        AccountNameInvoice:
          type: string
          nullable: true
          description: Identificador da conta da empresa emissora.
        CompanyAddressStateInvoice:
          type: string
          nullable: true
          maxLength: 2
          description: UF da empresa emissora (usada para identificar operações no estado x fora do estado).
        IDTax:
          type: integer
          description: Identificador da regra fiscal.
        IDTaxDepartment:
          type: integer
          description: Identificador do departamento fiscal.
        TypeTaxName:
          type: string
          nullable: true
          maxLength: 100
          description: Apelido da regra fiscal.
        Standard:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` quando é a regra padrão da operação.'
        Gratification:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` quando regra de bonificação.'
        NfeindFinal:
          type: integer
          enum:
            - 0
            - 1
          description: Indicador de consumidor final.
        NfeTaxPayer:
          type: integer
          enum:
            - 0
            - 1
          description: Indicador de destinatário contribuinte do ICMS.
        NfeExport:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` quando operação de importação/exportação.'
        ReverseTaxCalculation:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` quando aplica cálculo reverso (impostos por dentro do valor total).'
        IssueNFCe:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` quando a regra emite NFCe modelo 65 em vez de NF-e modelo 55.'
        IIAliquot:
          type: number
          nullable: true
          description: Alíquota de Imposto de Importação, em decimal — relevante quando `NfeExport=1`.
        TaxSkuCest:
          type: string
          nullable: true
          maxLength: 15
          description: CEST que sobrescreve o cadastrado no SKU.
        PisCst:
          type: string
          nullable: true
          maxLength: 2
          description: CST PIS (saída).
        PisAliquot:
          type: number
          nullable: true
          description: Alíquota PIS (saída), em decimal.
        NfCstPisDescription:
          type: string
          nullable: true
          description: Descrição do CST PIS (saída).
        CofinsCst:
          type: string
          nullable: true
          maxLength: 2
          description: CST COFINS (saída).
        CofinsAliquot:
          type: number
          nullable: true
          description: Alíquota COFINS (saída), em decimal.
        NfCstCofinsDescription:
          type: string
          nullable: true
          description: Descrição do CST COFINS (saída).
        PisCstInbound:
          type: string
          nullable: true
          maxLength: 2
          description: CST PIS (entrada).
        PisAliquotInbound:
          type: number
          nullable: true
          description: Alíquota PIS (entrada), em decimal.
        NfCstPisInboundDescription:
          type: string
          nullable: true
          description: Descrição do CST PIS (entrada).
        CofinsCstInbound:
          type: string
          nullable: true
          maxLength: 2
          description: CST COFINS (entrada).
        CofinsAliquotInbound:
          type: number
          nullable: true
          description: Alíquota COFINS (entrada), em decimal.
        NfCstCofinsInboundDescription:
          type: string
          nullable: true
          description: Descrição do CST COFINS (entrada).
        IpiCst:
          type: string
          nullable: true
          maxLength: 2
          description: CST IPI (saída).
        IpiAliquot:
          type: number
          nullable: true
          description: Alíquota IPI (saída), em decimal.
        NfCstIpiDescription:
          type: string
          nullable: true
          description: Descrição do CST IPI (saída).
        IpiCEnq:
          type: string
          nullable: true
          maxLength: 3
          description: Enquadramento legal do IPI.
        NfIpiCEnqDescription:
          type: string
          nullable: true
          description: Descrição do enquadramento legal do IPI.
        IpiCstInbound:
          type: string
          nullable: true
          maxLength: 2
          description: CST IPI (entrada).
        IpiAliquotInbound:
          type: number
          nullable: true
          description: Alíquota IPI (entrada), em decimal.
        NfCstIpiInboundDescription:
          type: string
          nullable: true
          description: Descrição do CST IPI (entrada).
        IDNfCstIbsCbs:
          type: integer
          nullable: true
          description: Identificador da classificação tributária IBS/CBS.
        NfCstIbsCbsDescription:
          type: string
          nullable: true
          description: Descrição da classificação IBS/CBS (`cClassTrib - cClassTribName`).
        CfopOutboundInState:
          type: integer
          nullable: true
          description: CFOP de saída dentro do estado.
        CfopOutboundInStateDescription:
          type: string
          nullable: true
          description: Descrição/Natureza do CFOP de saída no estado.
        CfopOutboundInStateNfeNatureOperation:
          type: string
          nullable: true
          maxLength: 60
          description: >-
            Natureza de operação customizada para o CFOP de saída no estado (quando preenchida, substitui a descrição
            padrão na nota).
        CfopOutboundOutState:
          type: integer
          nullable: true
          description: CFOP de saída fora do estado.
        CfopOutboundOutStateDescription:
          type: string
          nullable: true
          description: Descrição/Natureza do CFOP de saída fora do estado.
        CfopOutboundOutStateNfeNatureOperation:
          type: string
          nullable: true
          maxLength: 60
          description: Natureza de operação customizada para o CFOP de saída fora do estado.
        CfopInboundInState:
          type: integer
          nullable: true
          description: CFOP de entrada dentro do estado.
        CfopInboundInStateDescription:
          type: string
          nullable: true
          description: Descrição/Natureza do CFOP de entrada no estado.
        CfopInboundInStateNfeNatureOperation:
          type: string
          nullable: true
          maxLength: 60
          description: Natureza de operação customizada para o CFOP de entrada no estado.
        CfopInboundOutState:
          type: integer
          nullable: true
          description: CFOP de entrada fora do estado.
        CfopInboundOutStateDescription:
          type: string
          nullable: true
          description: Descrição/Natureza do CFOP de entrada fora do estado.
        CfopInboundOutStateNfeNatureOperation:
          type: string
          nullable: true
          maxLength: 60
          description: Natureza de operação customizada para o CFOP de entrada fora do estado.
        Icms:
          type: array
          description: Regras ICMS por estado destino vinculadas a esta regra fiscal. Ordenadas por nome do estado.
          items:
            $ref: '#/components/schemas/TaxInterstate'
    TaxCfopCreateBody:
      type: object
      required:
        - IDCompanyBranch
        - PisCst
        - CofinsCst
        - Standard
        - NfeindFinal
        - TypeTaxName
      properties:
        IDCompanyBranch:
          type: integer
          description: Identificador da empresa (matriz ou filial) a que esta regra fiscal se aplica.
        TypeTaxName:
          type: string
          nullable: true
          maxLength: 100
          description: Apelido da regra fiscal.
        Standard:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            `1` para marcar como regra padrão da operação (impede duplicidade de padrão por estado destino dentro do
            mesmo departamento).
        NfeindFinal:
          type: integer
          enum:
            - 0
            - 1
          description: Indicador de consumidor final. `1` Consumidor Final; `0` Normal.
        NfeTaxPayer:
          type: integer
          enum:
            - 0
            - 1
          default: 0
          description: Indicador de destinatário contribuinte do ICMS.
        Gratification:
          type: integer
          enum:
            - 0
            - 1
          default: 0
          description: '`1` para operação de bonificação.'
        NfeExport:
          type: integer
          enum:
            - 0
            - 1
          default: 0
          description: '`1` para operação de importação/exportação.'
        ReverseTaxCalculation:
          type: integer
          enum:
            - 0
            - 1
          default: 1
          description: '`1` aplica cálculo reverso (impostos por dentro do valor total).'
        IssueNFCe:
          type: integer
          enum:
            - 0
            - 1
          default: 0
          description: '`1` emite NFCe modelo 65 em vez de NF-e modelo 55.'
        PisCst:
          type: string
          maxLength: 2
          description: CST PIS (saída). Obrigatório.
        PisAliquot:
          type: number
          nullable: true
          description: Alíquota PIS (saída), em decimal (0–0,5). Valores acima de 0,5 (50%) são bloqueados.
        CofinsCst:
          type: string
          maxLength: 2
          description: CST COFINS (saída). Obrigatório.
        CofinsAliquot:
          type: number
          nullable: true
          description: Alíquota COFINS (saída), em decimal (0–0,5).
        PisCstInbound:
          type: string
          nullable: true
          maxLength: 2
          description: CST PIS (entrada).
        PisAliquotInbound:
          type: number
          nullable: true
          description: Alíquota PIS (entrada), em decimal.
        CofinsCstInbound:
          type: string
          nullable: true
          maxLength: 2
          description: CST COFINS (entrada).
        CofinsAliquotInbound:
          type: number
          nullable: true
          description: Alíquota COFINS (entrada), em decimal.
        IpiCst:
          type: string
          nullable: true
          maxLength: 2
          description: CST IPI (saída). Quando informado, exige enquadramento `IpiCEnq` válido para o CST.
        IpiAliquot:
          type: number
          nullable: true
          description: Alíquota IPI (saída), em decimal. Ignorado quando `IpiCst` está em branco.
        IpiCEnq:
          type: string
          nullable: true
          maxLength: 3
          description: >-
            Enquadramento legal do IPI. Faixas: CSTs `02/52` exigem 300–399; `04/54` exigem 0–99; `05/55` exigem
            100–199.
        IpiCstInbound:
          type: string
          nullable: true
          maxLength: 2
          description: CST IPI (entrada).
        IpiAliquotInbound:
          type: number
          nullable: true
          description: Alíquota IPI (entrada), em decimal.
        IDNfCstIbsCbs:
          type: integer
          nullable: true
          description: Identificador da classificação tributária IBS/CBS. Quando informado, é validado contra o cadastro.
        CfopOutboundInState:
          type: integer
          nullable: true
          description: CFOP de saída dentro do estado. Deve começar com 5 ou 7 e existir no cadastro.
        CfopOutboundInStateNfeNatureOperation:
          type: string
          nullable: true
          maxLength: 60
          description: Natureza de operação customizada (sobrescreve a descrição padrão do CFOP na nota).
        CfopOutboundOutState:
          type: integer
          nullable: true
          description: CFOP de saída fora do estado. Deve começar com 6.
        CfopOutboundOutStateNfeNatureOperation:
          type: string
          nullable: true
          maxLength: 60
          description: Natureza de operação customizada.
        CfopInboundInState:
          type: integer
          nullable: true
          description: CFOP de entrada dentro do estado. Deve começar com 1 ou 3.
        CfopInboundInStateNfeNatureOperation:
          type: string
          nullable: true
          maxLength: 60
          description: Natureza de operação customizada.
        CfopInboundOutState:
          type: integer
          nullable: true
          description: CFOP de entrada fora do estado. Deve começar com 2.
        CfopInboundOutStateNfeNatureOperation:
          type: string
          nullable: true
          maxLength: 60
          description: Natureza de operação customizada.
        IIAliquot:
          type: number
          nullable: true
          description: Alíquota de Imposto de Importação, em decimal — relevante quando `NfeExport=1`.
        TaxSkuCest:
          type: string
          nullable: true
          maxLength: 15
          description: CEST que sobrescreve o cadastrado no SKU.
    TaxCfopUpdateBody:
      type: object
      description: >-
        Atualização parcial — campos não enviados ficam inalterados. Strings vazias em `PisCstInbound` e
        `CofinsCstInbound` são interpretadas como remoção do CST de entrada.
      properties:
        IDCompanyBranch:
          type: integer
          description: Identificador da empresa (matriz ou filial) a que esta regra fiscal se aplica.
        TypeTaxName:
          type: string
          maxLength: 100
          description: Apelido da regra fiscal.
        Standard:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` marca como regra padrão da operação.'
        NfeindFinal:
          type: integer
          enum:
            - 0
            - 1
          description: Indicador de consumidor final.
        NfeTaxPayer:
          type: integer
          enum:
            - 0
            - 1
          description: Indicador de destinatário contribuinte do ICMS.
        Gratification:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` para operação de bonificação.'
        NfeExport:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` para operação de importação/exportação.'
        ReverseTaxCalculation:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` aplica cálculo reverso.'
        IssueNFCe:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` emite NFCe modelo 65.'
        PisCst:
          type: string
          maxLength: 2
          description: CST PIS (saída).
        PisAliquot:
          type: number
          nullable: true
          description: Alíquota PIS (saída), em decimal (0–0,5).
        CofinsCst:
          type: string
          maxLength: 2
          description: CST COFINS (saída).
        CofinsAliquot:
          type: number
          nullable: true
          description: Alíquota COFINS (saída), em decimal (0–0,5).
        PisCstInbound:
          type: string
          nullable: true
          maxLength: 2
          description: CST PIS (entrada). String vazia remove o valor (`null`).
        PisAliquotInbound:
          type: number
          nullable: true
          description: Alíquota PIS (entrada), em decimal.
        CofinsCstInbound:
          type: string
          nullable: true
          maxLength: 2
          description: CST COFINS (entrada). String vazia remove o valor (`null`).
        CofinsAliquotInbound:
          type: number
          nullable: true
          description: Alíquota COFINS (entrada), em decimal.
        IpiCst:
          type: string
          nullable: true
          maxLength: 2
          description: CST IPI (saída). Quando informado, exige `IpiCEnq` na faixa correspondente.
        IpiAliquot:
          type: number
          nullable: true
          description: Alíquota IPI (saída), em decimal.
        IpiCEnq:
          type: string
          nullable: true
          maxLength: 3
          description: Enquadramento legal do IPI. Faixas válidas por CST IPI.
        IpiCstInbound:
          type: string
          nullable: true
          maxLength: 2
          description: CST IPI (entrada).
        IpiAliquotInbound:
          type: number
          nullable: true
          description: Alíquota IPI (entrada), em decimal.
        IDNfCstIbsCbs:
          type: integer
          nullable: true
          description: Identificador da classificação tributária IBS/CBS.
        CfopOutboundInState:
          type: integer
          nullable: true
          description: CFOP de saída dentro do estado.
        CfopOutboundInStateNfeNatureOperation:
          type: string
          nullable: true
          maxLength: 60
          description: Natureza de operação customizada para o CFOP de saída no estado.
        CfopOutboundOutState:
          type: integer
          nullable: true
          description: CFOP de saída fora do estado.
        CfopOutboundOutStateNfeNatureOperation:
          type: string
          nullable: true
          maxLength: 60
          description: Natureza de operação customizada para o CFOP de saída fora do estado.
        CfopInboundInState:
          type: integer
          nullable: true
          description: CFOP de entrada dentro do estado.
        CfopInboundInStateNfeNatureOperation:
          type: string
          nullable: true
          maxLength: 60
          description: Natureza de operação customizada para o CFOP de entrada no estado.
        CfopInboundOutState:
          type: integer
          nullable: true
          description: CFOP de entrada fora do estado.
        CfopInboundOutStateNfeNatureOperation:
          type: string
          nullable: true
          maxLength: 60
          description: Natureza de operação customizada para o CFOP de entrada fora do estado.
        IIAliquot:
          type: number
          nullable: true
          description: Alíquota de Imposto de Importação, em decimal.
        TaxSkuCest:
          type: string
          nullable: true
          maxLength: 15
          description: CEST que sobrescreve o cadastrado no SKU.
    TaxInterstate:
      type: object
      description: Regra ICMS por estado destino vinculada a uma regra fiscal (CFOP).
      properties:
        IDStockKeepingUnitIcmsTaxInterstate:
          type: integer
          description: Identificador da regra ICMS por estado.
        StateTo:
          type: string
          maxLength: 2
          description: UF de destino (sigla — `SP`, `RJ`, etc.).
        StateName:
          type: string
          nullable: true
          description: Nome do estado destino.
        IcmsCst:
          type: string
          maxLength: 3
          description: CST ICMS — controla quais demais campos da regra são exigidos/ignorados.
        CstDescription:
          type: string
          nullable: true
          description: Descrição do CST ICMS.
        IcmsModBC:
          type: integer
          nullable: true
          description: >-
            Modalidade de base de cálculo do ICMS (`0` Margem Valor Agregado; `1` Pauta; `2` Preço Tabelado; `3` Valor
            da operação).
        IcmsModBCDescription:
          type: string
          nullable: true
          description: Descrição da modalidade da base de cálculo.
        IcmsAliquot:
          type: number
          nullable: true
          description: Alíquota ICMS, em decimal (0–1).
        IcmsPRedBC:
          type: number
          nullable: true
          description: Percentual de redução da base de cálculo do ICMS, em decimal.
        IcmsDifalPRedBC:
          type: number
          nullable: true
          description: Percentual de redução da base do ICMS DIFAL, em decimal.
        FecpAliquot:
          type: number
          nullable: true
          description: Alíquota do Fundo de Combate à Pobreza (FCP), em decimal.
        IcmsModBCST:
          type: integer
          nullable: true
          description: Modalidade de base do ICMS ST (`0`–`6`).
        IcmsModBCSTDescription:
          type: string
          nullable: true
          description: Descrição da modalidade da base do ICMS ST.
        IcmsPMVAST:
          type: number
          nullable: true
          description: MVA — Margem de Valor Agregado para produto nacional (origens fiscais 0/4/5/6/7), em decimal.
        IcmsPMVASTSimples:
          type: number
          nullable: true
          description: MVA para produto nacional quando o cliente é do Simples Nacional, em decimal.
        IcmsPMVASTMadeOutBrazil:
          type: number
          nullable: true
          description: MVA para produto importado (origens fiscais 1/2/3/8), em decimal.
        IcmsPMVASTSimplesMadeOutBrazil:
          type: number
          nullable: true
          description: MVA para produto importado quando o cliente é do Simples Nacional, em decimal.
        IcmsPRedBCST:
          type: number
          nullable: true
          description: Percentual de redução da base do ICMS ST, em decimal.
        IcmsSTAliquot:
          type: number
          nullable: true
          description: Alíquota interna do ICMS ST, em decimal. Vazio usa a `IcmsAliquot`.
        IcmsStBaseCalMethod:
          type: integer
          enum:
            - 1
            - 2
          description: 'Método da base do ICMS ST: `1` Base Simples; `2` Base D. Conv. 06/2009.'
        IcmsStDifalBaseCalMethod:
          type: integer
          enum:
            - 1
            - 2
            - 3
          description: 'Método da base do DIFAL ST: `1` Base Simples; `2` Base D. Conv. 148/2018; `3` Base D. Leg. Interna.'
        MethodOutside:
          type: integer
          enum:
            - 0
            - 1
          description: Método de cálculo do ICMS. `1` Por Fora; `0` Por Dentro.
        MethodOutsideDescription:
          type: string
          nullable: true
          description: Descrição textual de `MethodOutside`.
        MethodOutsideDifal:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: Método de cálculo do DIFAL. `1` Por Fora; `0` Por Dentro.
        MethodOutsideDifalDescription:
          type: string
          nullable: true
          description: Descrição textual de `MethodOutsideDifal`.
        IcmscBenef:
          type: string
          nullable: true
          maxLength: 45
          description: Código de benefício fiscal do estado destino.
        IcmsPDif:
          type: number
          nullable: true
          description: Percentual de diferimento do ICMS, em decimal.
        FecpPDif:
          type: number
          nullable: true
          description: Percentual de diferimento do FCP, em decimal.
        CfopOutbound:
          type: integer
          nullable: true
          description: CFOP de saída específico deste estado — sobrescreve o do CFOP-pai.
        CfopInbound:
          type: integer
          nullable: true
          description: CFOP de entrada específico deste estado — sobrescreve o do CFOP-pai.
        ItemCommentsInvoice:
          type: string
          nullable: true
          maxLength: 500
          description: Texto livre adicionado à tag `infoAdProd` do XML para este estado destino.
    TaxInterstateCreateBody:
      type: object
      required:
        - IcmsCst
        - StateTo
      properties:
        StateTo:
          type: string
          maxLength: 2
          description: UF de destino. Obrigatório. Não pode coincidir com outra regra já cadastrada para o mesmo CFOP.
        IcmsCst:
          type: string
          maxLength: 3
          description: >-
            CST ICMS. Define quais demais campos são obrigatórios. Validado contra `NfCstIcms` segundo o regime
            tributário da empresa.
        IcmsModBC:
          type: integer
          nullable: true
          default: 3
          description: Modalidade de base de cálculo do ICMS. Padrão `3` (Valor da operação). Aceita `0`–`3`.
        IcmsAliquot:
          type: number
          nullable: true
          description: Alíquota ICMS, em decimal (0–1).
        IcmsPRedBC:
          type: number
          nullable: true
          description: Percentual de redução da BC do ICMS, em decimal. Para CSTs `20` e `70`, deve ser maior que zero.
        IcmsDifalPRedBC:
          type: number
          nullable: true
          default: 0
          description: Percentual de redução da BC do ICMS DIFAL, em decimal (0–1).
        FecpAliquot:
          type: number
          nullable: true
          description: Alíquota FCP, em decimal (0–1). `null` é tratado como `0`.
        IcmsModBCST:
          type: integer
          nullable: true
          description: Modalidade de base do ICMS ST (`0`–`6`). Obrigatória nos CSTs com ST.
        IcmsPMVAST:
          type: number
          nullable: true
          description: MVA — produto nacional, em decimal.
        IcmsPMVASTSimples:
          type: number
          nullable: true
          description: MVA — produto nacional, cliente do Simples, em decimal.
        IcmsPMVASTMadeOutBrazil:
          type: number
          nullable: true
          description: MVA — produto importado, em decimal.
        IcmsPMVASTSimplesMadeOutBrazil:
          type: number
          nullable: true
          description: MVA — produto importado, cliente do Simples, em decimal.
        IcmsPRedBCST:
          type: number
          nullable: true
          description: Percentual de redução da BC do ICMS ST, em decimal.
        IcmsSTAliquot:
          type: number
          nullable: true
          description: Alíquota interna do ICMS ST, em decimal. Vazio assume a `IcmsAliquot`.
        IcmsStBaseCalMethod:
          type: integer
          enum:
            - 1
            - 2
          default: 1
          description: Método da base do ICMS ST. `1` (default) Base Simples; `2` Base D. Conv. 06/2009.
        IcmsStDifalBaseCalMethod:
          type: integer
          enum:
            - 1
            - 2
            - 3
          default: 1
          description: Método da base do DIFAL ST. `1` (default) Base Simples; `2` Conv. 148/2018; `3` D. Leg. Interna.
        MethodOutside:
          type: integer
          enum:
            - 0
            - 1
          default: 1
          description: '`1` (default) cálculo Por Fora; `0` Por Dentro.'
        MethodOutsideDifal:
          type: integer
          enum:
            - 0
            - 1
          default: 1
          description: '`1` (default) DIFAL Por Fora; `0` Por Dentro.'
        IcmscBenef:
          type: string
          nullable: true
          maxLength: 45
          description: Código de benefício fiscal do estado destino.
        IcmsPDif:
          type: number
          nullable: true
          description: Percentual de diferimento do ICMS, em decimal.
        FecpPDif:
          type: number
          nullable: true
          description: Percentual de diferimento do FCP, em decimal.
        CfopOutbound:
          type: integer
          nullable: true
          description: CFOP de saída específico deste estado (override do CFOP-pai).
        CfopInbound:
          type: integer
          nullable: true
          description: CFOP de entrada específico deste estado (override do CFOP-pai).
        ItemCommentsInvoice:
          type: string
          nullable: true
          maxLength: 500
          description: Texto livre adicionado à tag `infoAdProd` do XML para este estado destino.
    TaxInterstateUpdateBody:
      type: object
      description: >-
        Atualização parcial — campos não enviados mantêm o valor anterior. As validações por CST do `POST` continuam
        aplicáveis quando os campos relevantes são enviados.
      properties:
        StateTo:
          type: string
          maxLength: 2
          description: >-
            UF de destino. Quando alterada, o sistema valida novamente duplicidade entre regras do mesmo CFOP e (quando
            o CFOP é `Standard=1`) contra outras regras padrão do mesmo departamento.
        IcmsCst:
          type: string
          maxLength: 3
          description: CST ICMS.
        IcmsModBC:
          type: integer
          nullable: true
          description: Modalidade de base de cálculo do ICMS (`0`–`3`).
        IcmsAliquot:
          type: number
          nullable: true
          description: Alíquota ICMS, em decimal.
        IcmsPRedBC:
          type: number
          nullable: true
          description: Percentual de redução da BC do ICMS, em decimal.
        IcmsDifalPRedBC:
          type: number
          nullable: true
          description: Percentual de redução da BC do DIFAL, em decimal.
        FecpAliquot:
          type: number
          nullable: true
          description: Alíquota FCP, em decimal.
        IcmsModBCST:
          type: integer
          nullable: true
          description: Modalidade de base do ICMS ST.
        IcmsPMVAST:
          type: number
          nullable: true
          description: MVA — produto nacional, em decimal.
        IcmsPMVASTSimples:
          type: number
          nullable: true
          description: MVA — produto nacional, cliente do Simples, em decimal.
        IcmsPMVASTMadeOutBrazil:
          type: number
          nullable: true
          description: MVA — produto importado, em decimal.
        IcmsPMVASTSimplesMadeOutBrazil:
          type: number
          nullable: true
          description: MVA — produto importado, cliente do Simples, em decimal.
        IcmsPRedBCST:
          type: number
          nullable: true
          description: Percentual de redução da BC do ICMS ST, em decimal.
        IcmsSTAliquot:
          type: number
          nullable: true
          description: Alíquota interna do ICMS ST, em decimal.
        IcmsStBaseCalMethod:
          type: integer
          enum:
            - 1
            - 2
          description: Método da base do ICMS ST.
        IcmsStDifalBaseCalMethod:
          type: integer
          enum:
            - 1
            - 2
            - 3
          description: Método da base do DIFAL ST.
        MethodOutside:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` Por Fora; `0` Por Dentro.'
        MethodOutsideDifal:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` DIFAL Por Fora; `0` Por Dentro.'
        IcmscBenef:
          type: string
          nullable: true
          maxLength: 45
          description: Código de benefício fiscal.
        IcmsPDif:
          type: number
          nullable: true
          description: Percentual de diferimento do ICMS, em decimal.
        FecpPDif:
          type: number
          nullable: true
          description: Percentual de diferimento do FCP, em decimal.
        CfopOutbound:
          type: integer
          nullable: true
          description: CFOP de saída específico deste estado (override).
        CfopInbound:
          type: integer
          nullable: true
          description: CFOP de entrada específico deste estado (override).
        ItemCommentsInvoice:
          type: string
          nullable: true
          maxLength: 500
          description: Texto livre adicionado à tag `infoAdProd` do XML.
    InvoiceServiceDetail:
      type: object
      description: Detalhe completo de uma NFS-e (`ServiceOrder`).
      properties:
        IDServiceOrder:
          type: integer
          description: Identificador da NFS-e.
        AccountName:
          type: string
          description: Identificador da conta (subdomínio) emissora.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data de criação do registro.
        IDCompany:
          type: integer
          description: Empresa emissora.
        CityCode:
          type: integer
          description: Código IBGE do município emissor.
        CityName:
          type: string
          description: Nome do município emissor.
        State:
          type: string
          maxLength: 2
          description: UF do município emissor.
        IDConsumer:
          type: integer
          description: Cliente tomador do serviço.
        ConsumerNameCorporateName:
          type: string
          nullable: true
          maxLength: 200
          description: Nome/razão social do tomador (snapshot no momento da emissão).
        ConsumerCpfCnpj:
          type: string
          nullable: true
          maxLength: 14
          description: CPF/CNPJ do tomador (snapshot).
        ConsumerEmail:
          type: string
          nullable: true
          maxLength: 200
          description: E-mail do tomador (snapshot).
        ConsumerTelephone:
          type: string
          nullable: true
          maxLength: 15
          description: Telefone do tomador (snapshot).
        IDAddress:
          type: integer
          nullable: true
          description: Endereço do tomador escolhido para a nota.
        ShippingStreet:
          type: string
          nullable: true
          maxLength: 100
          description: Logradouro do tomador (snapshot).
        ShippingNumber:
          type: string
          nullable: true
          maxLength: 80
          description: Número do endereço (snapshot).
        ShippingComplement:
          type: string
          nullable: true
          maxLength: 200
          description: Complemento (snapshot).
        ShippingNeighborhood:
          type: string
          nullable: true
          maxLength: 100
          description: Bairro (snapshot).
        ShippingCity:
          type: string
          nullable: true
          maxLength: 100
          description: Cidade (snapshot).
        ShippingState:
          type: string
          nullable: true
          maxLength: 2
          description: UF (snapshot).
        ShippingPostalCode:
          type: string
          nullable: true
          maxLength: 8
          description: CEP (snapshot).
        ShippingReceiverName:
          type: string
          nullable: true
          maxLength: 100
          description: Nome de quem recebe (snapshot).
        IDCompanyInvoice:
          type: integer
          nullable: true
          description: Empresa faturadora (quando diferente da emissora).
        AccountNameInvoice:
          type: string
          nullable: true
          description: Identificador da conta da faturadora.
        CompanyNameCorporateNameInvoice:
          type: string
          nullable: true
          description: Razão social da faturadora.
        NfsComments:
          type: string
          nullable: true
          maxLength: 2000
          description: Observações que vão para a nota.
        NfsDate:
          type: string
          format: date-time
          nullable: true
          description: Data de emissão (preenchida quando a NFS-e é emitida).
        NfsServiceCode:
          type: string
          nullable: true
          maxLength: 45
          description: Código de serviço municipal.
        ServiceDescription:
          type: string
          nullable: true
          description: Descrição do código de serviço.
        NfsServiceQuantity:
          type: integer
          nullable: true
          description: Quantidade do serviço. Default `1`.
        NfsServiceUnitValue:
          type: number
          nullable: true
          description: Valor unitário do serviço.
        NfsValue:
          type: number
          nullable: true
          description: Valor total do serviço (`NfsServiceQuantity * NfsServiceUnitValue`).
        NfsIRRFRetentionValue:
          type: number
          nullable: true
          description: Valor de retenção de IRRF.
        NfsPISRetentionValue:
          type: number
          nullable: true
          description: Valor de retenção de PIS.
        NfsCOFINSRetentionValue:
          type: number
          nullable: true
          description: Valor de retenção de COFINS.
        NfsCSLLRetentionValue:
          type: number
          nullable: true
          description: Valor de retenção de CSLL.
        NfsISSAliquot:
          type: number
          nullable: true
          description: Alíquota do ISS.
        ReceiptNumber:
          type: string
          nullable: true
          maxLength: 45
          description: Número do recibo provisório (RPS).
        RpsNumber:
          type: integer
          nullable: true
          description: Número do RPS.
        NfsNumber:
          type: integer
          nullable: true
          description: Número definitivo da NFS-e emitida.
        NfsVerificationCode:
          type: string
          nullable: true
          maxLength: 45
          description: Código de verificação devolvido pela prefeitura.
        NfsCancelDate:
          type: string
          format: date-time
          nullable: true
          description: Data de cancelamento.
        NfsCancelDescription:
          type: string
          nullable: true
          maxLength: 200
          description: Motivo do cancelamento.
        NfsChaveAcesso:
          type: string
          nullable: true
          maxLength: 60
          description: Chave de acesso da NFS-e nacional (Ambiente Nacional).
        CompanyCityInscription:
          type: string
          nullable: true
          maxLength: 45
          description: Inscrição municipal da empresa emissora (snapshot).
        IDStatusInvoice:
          type: integer
          description: >-
            Status da NF: `0` Pendente, `1` Erro, `2` Enviada, `3` Emitida, `4` Processando, `5` Pendente Conciliação
            EPEC, `6` Erro Conciliação EPEC, `7` Cancelada, `8` Denegada, `9` Inutilizada.
        StatusInvoice:
          type: string
          description: Descrição do status.
        NfsNBS:
          type: string
          nullable: true
          description: Código NBS (Nomenclatura Brasileira de Serviços), formatado em `9.9999.99.99`.
        NfsNBSDescription:
          type: string
          nullable: true
          description: Descrição do NBS.
        NfsCClassTrib:
          type: string
          nullable: true
          maxLength: 45
          description: Código de classificação tributária (Reforma Tributária).
        NfsCClassTribName:
          type: string
          nullable: true
          description: Nome da classificação tributária.
        NfsCClassTribDescription:
          type: string
          nullable: true
          description: Descrição da classificação tributária.
        NfsCstIbsCbs:
          type: string
          nullable: true
          description: CST IBS/CBS associado à classificação.
        NfsCstIbsCbsDescription:
          type: string
          nullable: true
          description: Descrição do CST IBS/CBS.
        NfsPRedIBS:
          type: number
          nullable: true
          description: Percentual de redução de IBS.
        NfsPRedCBS:
          type: number
          nullable: true
          description: Percentual de redução de CBS.
        NfsCIndOp:
          type: string
          nullable: true
          maxLength: 45
          description: Código indicador de operação (NFS-e nacional).
        NfsCIndOpIBSLocation:
          type: string
          nullable: true
          description: Local de tributação do IBS associado ao indicador de operação.
        NfsIndFinal:
          type: integer
          nullable: true
          enum:
            - 0
            - 1
          description: Indicador de consumidor final. `1` consumidor final, `0` não.
        IDOrder:
          type: integer
          nullable: true
          description: Pedido (`Orders`) vinculado à NFS-e, quando houver.
        ValuePaid:
          type: number
          nullable: true
          description: Soma das contas a receber vinculadas à NFS-e.
        UrlFileXml:
          type: string
          nullable: true
          description: URL assinada para baixar o XML da NFS-e.
        UrlFileDanfe:
          type: string
          nullable: true
          description: URL assinada para baixar a DANFSE em PDF.
        Events:
          type: array
          description: Histórico de eventos da NFS-e (`ServiceOrderLog`), em ordem decrescente.
          items:
            type: object
            properties:
              RecordTimestamp:
                type: string
                format: date-time
                description: Data do evento.
              Comments:
                type: string
                nullable: true
                description: Comentário/corpo do evento.
              Event:
                type: string
                description: Descrição do tipo de evento.
              RecordUserCreated:
                type: string
                description: Login do usuário responsável.
              Status:
                type: string
                description: Cor/cabeçalho do evento (`HeaderMessage`).
        Payments:
          type: array
          description: Contas a receber vinculadas à NFS-e (`AccountsPayableReceivable` com `IDTypeAccount=0`).
          items:
            type: object
            properties:
              IDAccountPayableReceivable:
                type: integer
                description: Identificador da conta a receber.
              PaymentDescription:
                type: string
                description: Descrição do tipo de pagamento.
              Category:
                type: integer
                description: Categoria do tipo de pagamento.
              Installment:
                type: integer
                description: Número desta parcela.
              InstallmentTotal:
                type: integer
                description: Total de parcelas.
              DateDue:
                type: string
                format: date
                description: Data de vencimento.
              Value:
                type: number
                description: Valor da parcela.
              TID:
                type: string
                nullable: true
                description: Identificador de transação.
              NSU:
                type: string
                nullable: true
                description: Número Sequencial Único.
              IDTypePayment:
                type: integer
                description: Tipo de pagamento.
              IDConsumer:
                type: integer
                nullable: true
                description: Cliente da conta.
              IDTypeAccountPayableReceivable:
                type: integer
                description: Plano de contas.
              TypeAccountPaybleDescription:
                type: string
                nullable: true
                description: Descrição do plano de contas.
              IDTypeDocument:
                type: integer
                description: Tipo do documento.
              IDStatusAccountPayableReceivable:
                type: integer
                description: Status da conta a receber.
                enum:
                  - 0
                  - 1
                  - 2
                  - 3
                  - 4
                  - 5
                  - 6
              IDBankAccountForecast:
                type: integer
                nullable: true
                description: Banco previsto.
              Bank:
                type: string
                nullable: true
                description: Nome do banco.
              BankSlipBarCode:
                type: string
                nullable: true
                description: Código de barras do boleto, quando o pagamento é via boleto.
              BankSlipUrl:
                type: string
                nullable: true
                description: URL do boleto, quando aplicável.
              IDCompanyIntegration:
                type: integer
                nullable: true
                description: Integração de cobrança vinculada.
              CompanyIntegration:
                type: string
                nullable: true
                description: Nome completo da integração (`<tipo> - <nome>`).
              DaysDue:
                type: integer
                nullable: true
                description: Dias até o vencimento contados a partir da emissão.
    InvoiceServiceUpdateBody:
      type: object
      description: >-
        Atualização parcial de uma NFS-e em status Pendente/Erro. Todos os campos são opcionais — campos omitidos não
        são alterados.
      properties:
        IDConsumer:
          type: integer
          nullable: true
          description: >-
            Cliente tomador. Quando alterado, os campos snapshot do cliente (nome, CPF/CNPJ, e-mail, telefone) são
            reescritos a partir do cadastro.
        IDAddress:
          type: integer
          nullable: true
          description: >-
            Endereço do cliente escolhido para a nota. Quando alterado, os campos snapshot do endereço (rua, número,
            complemento, bairro, cidade, UF, CEP, recebedor) são reescritos.
        IDCompanyInvoice:
          type: integer
          description: Empresa faturadora (quando diferente da emissora). Precisa estar relacionada à emissora (`CompanyMain`).
        NfsComments:
          type: string
          nullable: true
          maxLength: 2000
          description: Observações que vão para a nota.
        NfsServiceCode:
          type: string
          nullable: true
          maxLength: 45
          description: >-
            Código de serviço municipal. Validado contra `NfsServiceCode` do município (ou nacional `0` para municípios
            fora de SP/Rio capital).
        NfsServiceQuantity:
          type: integer
          description: Quantidade do serviço.
        NfsServiceUnitValue:
          type: number
          description: Valor unitário do serviço.
        NfsIRRFRetentionValue:
          type: number
          nullable: true
          description: >-
            Valor de retenção de IRRF. Quando `null`, o sistema calcula a partir do percentual configurado na empresa
            faturadora (`IRRetentionPercent`).
        NfsPISRetentionValue:
          type: number
          nullable: true
          description: Valor de retenção de PIS. Mesmo cálculo automático quando `null`.
        NfsCOFINSRetentionValue:
          type: number
          nullable: true
          description: Valor de retenção de COFINS. Mesmo cálculo automático quando `null`.
        NfsCSLLRetentionValue:
          type: number
          nullable: true
          description: Valor de retenção de CSLL. Mesmo cálculo automático quando `null`.
        NfsISSAliquot:
          type: number
          nullable: true
          description: Alíquota do ISS.
        NfsNBS:
          type: string
          nullable: true
          description: Código NBS. O sistema remove pontos antes de validar contra a lista oficial.
        NfsCClassTrib:
          type: string
          nullable: true
          description: Código de classificação tributária (Reforma Tributária). Validado contra `NfCstIbsCbs` para NFSe.
        NfsCIndOp:
          type: string
          nullable: true
          description: Código indicador de operação. Validado contra `NfsCIndOp`.
        NfsIndFinal:
          type: integer
          nullable: true
          enum:
            - 0
            - 1
          description: Indicador de consumidor final. `1` consumidor final, `0` não.
    InvoiceServicePaymentCreateBody:
      type: object
      description: >-
        Corpo do lançamento de pagamento de NFS-e. Todos os campos são opcionais — o sistema preenche com os padrões da
        empresa.
      properties:
        Comments:
          type: string
          nullable: true
          description: Observações.
        IDTypePayment:
          type: integer
          description: 'Tipo de pagamento. Default: tipo padrão de pedido da empresa.'
        TID:
          type: string
          nullable: true
          description: Identificador de transação (gateway).
        NSU:
          type: string
          nullable: true
          description: Número Sequencial Único (gateway).
        Value:
          type: number
          description: Valor da parcela (ou total quando `SplitInstallment=0`).
        InstallmentTotal:
          type: integer
          description: Total de parcelas. Default `1`.
        Installment:
          type: integer
          description: Número da primeira parcela. Default `1`.
        DateCompetence:
          type: string
          format: date
          nullable: true
          description: Data de competência.
        DateDocument:
          type: string
          format: date
          nullable: true
          description: Data do documento.
        DateDue:
          type: string
          format: date
          nullable: true
          description: Data de vencimento da primeira parcela. Quando omitida, é calculada com `DaysDue` do tipo de pagamento.
        DocumentNumber:
          type: string
          nullable: true
          description: Número do documento.
        IDBankAccountForecast:
          type: integer
          nullable: true
          description: 'Banco de recebimento previsto. Default: banco principal de recebimento.'
        IDTypeAccountPayableReceivable:
          type: integer
          description: 'Plano de contas. Default: plano padrão configurado para pedidos.'
        IDTypeDocument:
          type: integer
          description: 'Tipo do documento. Default: tipo padrão.'
        IDCompanyIntegration:
          type: integer
          nullable: true
          description: Integração de cobrança vinculada.
        IDCompanyInvoice:
          type: integer
          nullable: true
          description: 'Empresa faturadora. Default: empresa do pedido/NFS-e.'
        DaysDue:
          type: integer
          nullable: true
          description: Dias até o vencimento (alternativa a `DateDue`).
    InvoiceServicePaymentUpdateBody:
      type: object
      description: Atualização parcial de uma conta a receber vinculada à NFS-e.
      properties:
        Comments:
          type: string
          nullable: true
          description: Observações.
        IDTypePayment:
          type: integer
          description: Tipo de pagamento. Validado contra os cadastrados na empresa.
        TID:
          type: string
          nullable: true
          description: Identificador de transação (gateway).
        NSU:
          type: string
          nullable: true
          description: Número Sequencial Único (gateway).
        Value:
          type: number
          description: Valor da parcela.
        InstallmentTotal:
          type: integer
          description: Total de parcelas.
        Installment:
          type: integer
          description: Número desta parcela.
        IDConsumer:
          type: integer
          nullable: true
          description: Cliente vinculado. Não pode ser enviado junto com `IDSupplier`.
        DateCompetence:
          type: string
          format: date
          nullable: true
          description: Data de competência.
        DateDocument:
          type: string
          format: date
          nullable: true
          description: Data do documento.
        DateDue:
          type: string
          format: date
          description: Data de vencimento. Quando alterada, `DaysDue` é recalculado.
        IDBankAccountForecast:
          type: integer
          description: Banco de recebimento previsto.
        DocumentNumber:
          type: string
          nullable: true
          description: Número do documento.
        IDTypeAccountPayableReceivable:
          type: integer
          description: Plano de contas.
        IDTypeDocument:
          type: integer
          description: Tipo do documento.
        IDCompanyIntegration:
          type: integer
          nullable: true
          description: Integração de cobrança vinculada.
        IDCompanyInvoice:
          type: integer
          description: Empresa faturadora.
        ValueDiscount:
          type: number
          nullable: true
          description: Valor de desconto.
        ValueInterest:
          type: number
          nullable: true
          description: Valor de juros.
        ValuePenalty:
          type: number
          nullable: true
          description: Valor de multa.
        IDSupplier:
          type: integer
          nullable: true
          description: Fornecedor. Não pode ser enviado junto com `IDConsumer`.
        Forecast:
          type: integer
          enum:
            - 0
            - 1
          description: '`1` indica conta em previsão.'
    BuyOrderLog:
      type: object
      description: Linha do histórico de um pedido de compra (`StockKeepingUnitBuyOrderLog`).
      properties:
        IDStockKeepingUnitBuyOrderLog:
          type: integer
          description: Identificador da linha do histórico.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data do evento.
        RecordUserCreated:
          type: integer
          description: Identificador do usuário responsável.
        Login:
          type: string
          description: Login do usuário responsável.
        IDBuyOrder:
          type: integer
          description: Pedido de compra do evento.
        Data:
          type: string
          maxLength: 5000
          description: Descrição do evento (texto livre ou JSON com diff de campos quando é alteração).
    BuyOrderMergeBody:
      type: object
      required:
        - IDBuyOrder
      properties:
        IDBuyOrder:
          type: integer
          description: Identificador do pedido de compra de destino — todos os itens do pedido da URL serão movidos para este.
    BuyOrderPaymentCreateBody:
      type: object
      description: >-
        Corpo do lançamento/atualização de pagamento de pedido de compra. Todos os campos são opcionais; quando não
        enviados, o `INSERT` grava `NULL`.
      properties:
        IDTypePayment:
          type: integer
          nullable: true
          description: Tipo de pagamento. Validado contra os cadastrados na empresa.
        IDTypeDocument:
          type: integer
          nullable: true
          description: Tipo do documento. Validado contra os cadastrados na empresa.
        IDTypeAccountPayble:
          type: integer
          nullable: true
          description: Plano de contas. Precisa ser de último nível (sem filhos em `TypeAccountPayble`).
        Value:
          type: number
          nullable: true
          description: Valor da conta a pagar.
        DateDue:
          type: string
          format: date
          nullable: true
          description: Data de vencimento.
        DateCompetence:
          type: string
          format: date
          nullable: true
          description: Data de competência.
        Comments:
          type: string
          nullable: true
          description: Observações.
    BuyOrderSkuCreateBody:
      type: object
      required:
        - IDSku
        - Quantity
      description: Item a adicionar ao pedido de compra.
      properties:
        IDSku:
          type: integer
          description: >-
            SKU a comprar. Precisa estar ativo e ser do tipo Sku, Serviço, Matéria-prima ou Uso e consumo (`IDTypeSku`
            em `3`, `5`, `6`, `7`).
        Quantity:
          type: number
          description: Quantidade a comprar.
        ValueCostUnit:
          type: number
          nullable: true
          description: Custo unitário.
        BestBeforeDate:
          type: string
          format: date
          nullable: true
          description: Validade (quando aplicável).
        Comments:
          type: string
          nullable: true
          maxLength: 200
          description: Observações sobre o item.
        IDStockKeepingUnitWarehouse:
          type: integer
          nullable: true
          description: >-
            Armazém de destino. Quando omitido, usa o armazém padrão da empresa. O centro de distribuição precisa bater
            com o do pedido.
        EstimatedDeliveredDate:
          type: string
          format: date
          nullable: true
          description: Data estimada de entrega.
        IDSkuMovement:
          type: integer
          nullable: true
          description: Movimento de SKU de origem (quando o item nasce de outro fluxo).
    BuyOrderSkuUpdateBody:
      type: object
      description: Atualização parcial de item do pedido de compra. Todos os campos são opcionais.
      properties:
        IDSku:
          type: integer
          description: Novo SKU. Validado contra `IDTypeSku` em `3`, `5`, `6`, `7`.
        IDStockKeepingUnitWarehouse:
          type: integer
          description: Novo armazém. O centro de distribuição precisa bater com o do pedido.
        Quantity:
          type: number
          description: Nova quantidade.
        ValueCostUnit:
          type: number
          description: Novo custo unitário.
        BestBeforeDate:
          type: string
          format: date
          nullable: true
          description: Validade.
        Comments:
          type: string
          nullable: true
          maxLength: 200
          description: Observações.
        EstimatedDeliveredDate:
          type: string
          format: date
          nullable: true
          description: Data estimada de entrega.
    ChargeBankSlipOrderBody:
      type: object
      description: >-
        Sem campos obrigatórios. O sistema resolve cliente, integração, tipo de pedido e tipo de pagamento a partir do
        boleto e da configuração da empresa.
    CompanyBill:
      type: object
      description: Empresa com a lista de faturas mensais. Quando não há faturas, `Bills` vem vazio.
      properties:
        AccountName:
          type: string
          description: Identificador (subdomínio) da empresa.
        CompanyNameCorporateName:
          type: string
          description: Razão social da empresa.
        CompanyCpfCnpj:
          type: string
          description: CNPJ/CPF da empresa.
        Bills:
          type: array
          description: Faturas mensais ordenadas pela competência mais recente.
          items:
            type: object
            properties:
              IDCompanyBilling:
                type: integer
                description: Identificador da fatura.
              RecordTimestamp:
                type: string
                format: date-time
                description: Data de criação da fatura.
              BillingDateMonth:
                type: string
                format: date-time
                description: Mês de competência da fatura.
              DueDate:
                type: string
                format: date
                description: Vencimento da fatura.
              TotalBillValue:
                type: number
                description: Soma dos valores cobrados na fatura.
              IDServiceOrder:
                type: integer
                nullable: true
                description: Identificador da ordem de serviço/nota fiscal de serviço.
              NfsDate:
                type: string
                format: date-time
                nullable: true
                description: Data de emissão da nota fiscal de serviço.
              IDStatusInvoice:
                type: integer
                nullable: true
                description: Status da nota fiscal de serviço.
              NfsNumber:
                type: string
                nullable: true
                description: Número da nota fiscal de serviço.
              NfsVerificationCode:
                type: string
                nullable: true
                description: Código de verificação da nota fiscal.
              NfsValue:
                type: number
                nullable: true
                description: Valor da nota fiscal (quantidade × valor unitário).
              StatusInvoice:
                type: string
                nullable: true
                description: Descrição do status da nota fiscal.
              InvoiceUrl:
                type: string
                description: URL externa de consulta da nota fiscal.
              IDStatusBankSlip:
                type: integer
                nullable: true
                description: >-
                  Status do boleto: `1` Aguardando pagamento, `2` Pago, `3` Pendente, `4` Cancelado, `5` Baixa manual,
                  `6` Protesto.
                enum:
                  - 1
                  - 2
                  - 3
                  - 4
                  - 5
                  - 6
              BankSlipUrl:
                type: string
                nullable: true
                description: URL para download do boleto.
              IDBankSlip:
                type: integer
                nullable: true
                description: Identificador do boleto.
              DatePaid:
                type: string
                format: date-time
                nullable: true
                description: Data do pagamento do boleto.
              StatusBankSlip:
                type: string
                nullable: true
                description: Descrição do status do boleto.
              Charges:
                type: array
                description: Itens cobrados na fatura (regras aplicadas no mês).
                items:
                  type: object
                  properties:
                    IDCompanyBillingCharges:
                      type: integer
                      description: Identificador do item cobrado.
                    TotalValue:
                      type: number
                      description: Valor total do item.
                    TotalQuantity:
                      type: integer
                      description: Quantidade contabilizada no mês.
                    IDCompanyBillingRules:
                      type: integer
                      description: Regra de cobrança aplicada.
                    DateFrom:
                      type: string
                      format: date
                      description: Vigência inicial da regra.
                    DateTo:
                      type: string
                      format: date
                      description: Vigência final da regra.
                    IDTypeCompanyBillingCharges:
                      type: integer
                      description: Identificador do tipo de cobrança.
                    RangeFrom:
                      type: integer
                      description: Limite inferior da faixa de quantidade.
                    RangeTo:
                      type: integer
                      description: Limite superior da faixa de quantidade.
                    UnitValue:
                      type: number
                      nullable: true
                      description: Valor unitário da faixa.
                    MinimumValue:
                      type: number
                      nullable: true
                      description: Valor mínimo cobrado na faixa.
                    Comments:
                      type: string
                      nullable: true
                      description: Observações da regra.
                    TypeCompanyBillingCharges:
                      type: string
                      description: Descrição do tipo de cobrança.
    CompanyDashboardSummary:
      type: object
      description: Categoria de painel com os cartões configurados para a empresa.
      properties:
        IDTypeCompanyDashboardCategory:
          type: integer
          description: Identificador da categoria do painel.
        Privilege:
          type: string
          nullable: true
          description: Privilégio exigido para visualizar a categoria.
        TypeCompanyDashboardCategory:
          type: string
          description: Descrição amigável da categoria.
        TypeCompanyDashboard:
          type: array
          description: Cartões/blocos exibidos na categoria.
          items:
            type: object
            properties:
              IDTypeCompanyDashboard:
                type: integer
                description: Identificador do bloco.
              TypeCompanyDashboard:
                type: string
                description: Descrição do bloco.
              Value:
                type: string
                description: Valor formatado do bloco (pode incluir total de itens entre parênteses).
              URLSearchParams:
                type: string
                nullable: true
                description: Querystring para abrir a tela detalhada.
              component:
                type: string
                nullable: true
                description: Componente de UI a renderizar.
              UpdatedAt:
                type: string
                format: date-time
                nullable: true
                description: Última atualização do bloco.
              Difference:
                type: number
                nullable: true
                description: Variação em relação à comparação anterior.
              ValueTotal:
                type: number
                nullable: true
                description: Valor consolidado do bloco.
              UserPrivilege:
                type: string
                nullable: true
                description: Privilégio do usuário para ver o bloco.
              ItemsTotal:
                type: integer
                nullable: true
                description: Quantidade de itens contabilizados.
    CompanyDashboardOrderStatus:
      type: object
      description: Contagem de pedidos para um status configurado para a empresa.
      properties:
        IDStatusOrder:
          type: string
          description: Identificador do status (devolvido como string).
        StatusOrder:
          type: string
          description: Descrição do status para a empresa.
        Order:
          type: integer
          description: Ordem de exibição do status.
        StatusOrderDescription:
          type: string
          nullable: true
          description: Descrição auxiliar do status.
        Qty:
          type: integer
          description: Quantidade de pedidos no status.
    CompanyModule:
      type: object
      description: Grupo de módulos contratados com seus módulos e privilégios.
      properties:
        Module:
          type: array
          items:
            type: object
            properties:
              ModuleGroupDescription:
                type: string
                description: Nome do grupo de módulos.
              ModuleDescription:
                type: string
                description: Nome do módulo.
              IDModule:
                type: integer
                description: Identificador do módulo.
              Privilege:
                type: array
                description: Privilégios do módulo.
                items:
                  type: object
                  properties:
                    UserPrivilege:
                      type: string
                      description: Chave técnica do privilégio.
                    IDUserPrivilege:
                      type: integer
                      description: Identificador do privilégio.
                    PrivilegeDescription:
                      type: string
                      description: Descrição amigável.
                    KeyWords:
                      type: string
                      nullable: true
                      description: Palavras-chave para busca.
          description: Módulos contratados pela empresa dentro deste grupo, cada um com seus privilégios.
    CompanyReportCustom:
      type: object
      description: Relatório personalizado cadastrado pela empresa, com estrutura completa.
      properties:
        IDTypeCompanyReport:
          type: integer
          description: Identificador do relatório.
        TypeCompanyReport:
          type: string
          description: Nome do relatório.
        IDTypeCompanyReportGroup:
          type: integer
          description: Grupo do relatório (sempre `9` para personalizados).
        Comments:
          type: string
          nullable: true
          description: Observações.
        Complete:
          type: integer
          description: Indica se o relatório terminou de processar.
        MySQLQuery1:
          type: string
          nullable: true
          description: SQL gerada para execução.
        MySQLQuery2:
          type: string
          nullable: true
          description: 'Segunda variante da SQL gerada (usada quando o relatório precisa de duas consultas — ex.: resumo + detalhe).'
        BigQueryQuery1:
          type: string
          nullable: true
          description: SQL equivalente em BigQuery usada quando o relatório é roteado para o data warehouse externo.
        BigQueryQuery2:
          type: string
          nullable: true
          description: Segunda variante da SQL em BigQuery (par com `MySQLQuery2`).
        ReportStructure:
          type: object
          description: Estrutura do relatório (campos, filtros, agrupamento, ordenação).
          properties:
            ReportName:
              type: string
              description: Nome do relatório.
            ReportType:
              type: integer
              description: Tipo de relatório personalizado.
            Select:
              type: array
              description: Identificadores dos campos selecionados.
              items:
                type: integer
            Where:
              type: array
              description: Filtros aplicados.
              items:
                type: object
                properties:
                  FieldID:
                    type: integer
                    description: Identificador do campo.
                  Value:
                    description: Valor(es) do filtro.
                  Operator:
                    type: string
                    description: 'Operador inferido pelo tipo do campo: `IN`, `BETWEEN` ou `>=`.'
            GroupBy:
              type: array
              description: Identificadores dos campos de agrupamento.
              items:
                type: integer
            OrderBy:
              type: array
              description: Ordenação aplicada.
              items:
                type: object
                properties:
                  FieldID:
                    type: integer
                    description: Identificador do campo.
                  Direction:
                    type: string
                    enum:
                      - ASC
                      - DESC
                    description: Direção da ordenação.
        RecordTimestamp:
          type: string
          format: date-time
          nullable: true
          description: Data de criação.
        IDCompanyReport:
          type: integer
          description: Vínculo com a empresa.
        IDCompany:
          type: integer
          description: Identificador da empresa.
        AccountName:
          type: string
          description: Subdomínio da empresa.
        IDTypeCustomReport:
          type: integer
          nullable: true
          description: Tipo de relatório personalizado (base).
        CustomReportType:
          type: string
          nullable: true
          description: Descrição da base do relatório.
        FieldList:
          type: array
          description: Catálogo completo dos campos referenciados no relatório.
          items:
            type: object
            properties:
              IDTypeReportCustomField:
                type: integer
                description: Identificador do campo.
              FieldName:
                type: string
                description: Nome da coluna.
              FieldType:
                type: string
                nullable: true
                description: Tipo do campo (`integer`, `decimal`, `date`, `datetime`, `string`).
              TableName:
                type: string
                nullable: true
                description: Tabela de origem.
              Expression:
                type: string
                nullable: true
                description: Expressão SQL alternativa quando o campo é calculado.
              Groupable:
                type: integer
                description: '`1` quando o campo é somável.'
              Active:
                type: integer
                description: '`1` quando o campo está ativo.'
    CompanyReportCustomCreateBody:
      type: object
      required:
        - ReportName
        - ReportType
        - Select
      properties:
        ReportName:
          type: string
          description: 'Nome do relatório. Default: `"Relatório Personalizado"`.'
        ReportType:
          type: integer
          description: Identificador do tipo de relatório personalizado (define a tabela base).
        Select:
          type: array
          description: Identificadores dos campos a retornar.
          items:
            type: integer
        Where:
          type: array
          description: >-
            Filtros aplicados. O operador é inferido pelo tipo do campo: `IN` (default), `BETWEEN` (datas) ou `>=`
            (decimais).
          items:
            type: object
            required:
              - FieldID
            properties:
              FieldID:
                type: integer
                description: Identificador do campo.
              Value:
                description: Valor(es) do filtro.
        GroupBy:
          type: array
          description: Identificadores dos campos de agrupamento.
          items:
            type: integer
        OrderBy:
          type: array
          description: Ordenação dos campos selecionados.
          items:
            type: object
            required:
              - FieldID
            properties:
              FieldID:
                type: integer
                description: Identificador do campo (precisa estar em `Select`).
              Direction:
                type: string
                enum:
                  - ASC
                  - DESC
                description: Direção da ordenação. Default `ASC`.
    Goal:
      type: object
      description: Meta cadastrada para a empresa, com o desdobramento conforme o tipo.
      properties:
        IDCompanyGoal:
          type: integer
          description: Identificador da meta.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data de criação.
        IDCompany:
          type: integer
          description: Identificador da empresa.
        AccountName:
          type: string
          description: Subdomínio da empresa.
        IDTypeGoal:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
          description: 'Tipo da meta: `1` vendedor, `2` faturador, `3` tipo de pedido, `4` integração.'
        TypeGoal:
          type: string
          description: Descrição do tipo de meta.
        GoalName:
          type: string
          maxLength: 45
          description: Nome da meta.
        DateFrom:
          type: string
          format: date
          description: Data inicial de vigência.
        DateTo:
          type: string
          format: date
          description: Data final de vigência.
        GoalSalesmans:
          type: array
          description: Valores por vendedor (apenas quando `IDTypeGoal=1`).
          items:
            type: object
            properties:
              IDCompanyGoalSalesmans:
                type: integer
                description: Identificador do item.
              IDUser:
                type: integer
                description: Identificador do vendedor.
              Login:
                type: string
                description: Login do vendedor.
              GoalValue:
                type: number
                description: Valor da meta para o vendedor.
        GoalCompanyInvoices:
          type: array
          description: Valores por faturador (apenas quando `IDTypeGoal=2`).
          items:
            type: object
            properties:
              IDCompanyGoalCompanyInvoices:
                type: integer
                description: Identificador do item.
              IDCompanyInvoice:
                type: integer
                description: Identificador do faturador.
              AccountName:
                type: string
                description: Subdomínio do faturador.
              GoalValue:
                type: number
                description: Valor da meta para o faturador.
        GoalTypeOrders:
          type: array
          description: Valores por tipo de pedido (apenas quando `IDTypeGoal=3`).
          items:
            type: object
            properties:
              IDCompanyGoalTypeOrders:
                type: integer
                description: Identificador do item.
              IDTypeOrder:
                type: integer
                description: Identificador do tipo de pedido.
              TypeOrder:
                type: string
                description: Descrição do tipo de pedido.
              GoalValue:
                type: number
                description: Valor da meta para o tipo de pedido.
        GoalCompanyIntegrations:
          type: array
          description: Valores por integração (apenas quando `IDTypeGoal=4`).
          items:
            type: object
            properties:
              IDCompanyGoalCompanyIntegrations:
                type: integer
                description: Identificador do item.
              IDCompanyIntegration:
                type: integer
                description: Identificador da integração da empresa.
              CompanyIntegration:
                type: string
                description: Nome amigável da integração (`<tipo> - <nome>`).
              GoalValue:
                type: number
                description: Valor da meta para a integração.
    GoalCreateBody:
      type: object
      required:
        - IDTypeGoal
        - GoalName
        - DateFrom
        - DateTo
      properties:
        IDTypeGoal:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
          description: 'Tipo da meta: `1` vendedor, `2` faturador, `3` tipo de pedido, `4` integração.'
        GoalName:
          type: string
          maxLength: 45
          description: Nome da meta.
        DateFrom:
          type: string
          format: date
          description: Data inicial de vigência.
        DateTo:
          type: string
          format: date
          description: Data final de vigência. Precisa ser maior ou igual a `DateFrom`.
        GoalSalesmans:
          type: array
          description: Desdobramento por vendedor. Obrigatório quando `IDTypeGoal=1`. Cada vendedor precisa pertencer à empresa.
          items:
            type: object
            required:
              - IDUser
              - GoalValue
            properties:
              IDUser:
                type: integer
                description: Identificador do vendedor.
              GoalValue:
                type: number
                description: Valor da meta para o vendedor.
        GoalCompanyInvoices:
          type: array
          description: >-
            Desdobramento por faturador. Obrigatório quando `IDTypeGoal=2`. Cada faturador precisa estar vinculado à
            empresa principal.
          items:
            type: object
            required:
              - IDCompanyInvoice
              - GoalValue
            properties:
              IDCompanyInvoice:
                type: integer
                description: Identificador do faturador.
              GoalValue:
                type: number
                description: Valor da meta para o faturador.
        GoalTypeOrders:
          type: array
          description: >-
            Desdobramento por tipo de pedido. Obrigatório quando `IDTypeGoal=3`. Cada tipo precisa estar ativo para a
            empresa.
          items:
            type: object
            required:
              - IDTypeOrder
              - GoalValue
            properties:
              IDTypeOrder:
                type: integer
                description: Identificador do tipo de pedido.
              GoalValue:
                type: number
                description: Valor da meta para o tipo de pedido.
        GoalCompanyIntegrations:
          type: array
          description: >-
            Desdobramento por integração. Obrigatório quando `IDTypeGoal=4`. Cada integração precisa estar visível para
            a empresa.
          items:
            type: object
            required:
              - IDCompanyIntegration
              - GoalValue
            properties:
              IDCompanyIntegration:
                type: integer
                description: Identificador da integração da empresa.
              GoalValue:
                type: number
                description: Valor da meta para a integração.
    GoalUpdateBody:
      type: object
      required:
        - IDTypeGoal
        - GoalName
        - DateFrom
        - DateTo
      description: >-
        Mesmo contrato do POST. Todos os campos do desdobramento são opcionais; quando informados, substituem os
        existentes.
      properties:
        IDTypeGoal:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
          description: 'Tipo da meta: `1` vendedor, `2` faturador, `3` tipo de pedido, `4` integração.'
        GoalName:
          type: string
          maxLength: 45
          description: Nome da meta.
        DateFrom:
          type: string
          format: date
          description: Data inicial de vigência.
        DateTo:
          type: string
          format: date
          description: Data final de vigência.
        GoalSalesmans:
          type: array
          items:
            type: object
          description: Desdobramento por vendedor.
        GoalCompanyInvoices:
          type: array
          items:
            type: object
          description: Desdobramento por faturador.
        GoalTypeOrders:
          type: array
          items:
            type: object
          description: Desdobramento por tipo de pedido.
        GoalCompanyIntegrations:
          type: array
          items:
            type: object
          description: Desdobramento por integração.
    CorreiosReversa:
      type: object
      description: Solicitação de logística reversa Correios para um pedido.
      properties:
        IDCorreiosReverso:
          type: integer
          description: Identificador da coleta reversa.
        IDOrder:
          type: integer
          nullable: true
          description: Identificador do pedido vinculado.
        IDColeta:
          type: string
          maxLength: 45
          description: Código da coleta nos Correios.
        SRO:
          type: string
          maxLength: 45
          nullable: true
          description: Código de rastreio (SRO) da reversa.
        Prazo:
          type: string
          format: date
          nullable: true
          description: Prazo limite da coleta.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data de criação da coleta.
        TipoColeta:
          type: string
          maxLength: 45
          nullable: true
          description: 'Modalidade: domiciliar (`1`/`2`) ou em agência (`0`).'
        IDCarrier:
          type: integer
          nullable: true
          description: Identificador da transportadora.
        Order:
          type: string
          nullable: true
          description: Número do pedido.
        AccountName:
          type: string
          description: Subdomínio da empresa.
        SupplierNameCorporateName:
          type: string
          nullable: true
          description: Razão social da transportadora.
        OrderFrom:
          type: string
          nullable: true
          description: Origens do pedido separadas por vírgula.
    CorreiosReversaCreateBody:
      type: object
      required:
        - IDOrder
        - IDCarrier
      properties:
        IDOrder:
          type: integer
          description: Identificador do pedido a ser revertido.
        QtyObject:
          type: integer
          description: Quantidade de objetos da coleta.
        IDCarrier:
          type: integer
          description: Identificador da transportadora Correios.
        TipoColeta:
          type: integer
          description: 'Modalidade da coleta: `0` em agência (default), demais valores indicam coleta domiciliar.'
        Schedule:
          type: object
          description: Agendamento da coleta domiciliar quando aplicável.
          properties:
            DateCollect:
              type: string
              format: date
              description: Data prevista para a coleta.
            PeriodCollect:
              type: string
              description: Período do dia para a coleta.
    CorreiosPI:
      type: object
      description: Postagem Imediata Correios para um pacote.
      properties:
        IDCorreiosPI:
          type: integer
          description: Identificador da PI.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data de criação da PI.
        IDPackage:
          type: integer
          description: Identificador do pacote.
        PINumber:
          type: string
          maxLength: 45
          nullable: true
          description: Número da PI.
        PICode:
          type: string
          maxLength: 45
          nullable: true
          description: Código da PI.
        IDComplaintReason:
          type: integer
          nullable: true
          description: Motivo da reclamação.
        ComplaintReason:
          type: string
          nullable: true
          description: Descrição do motivo da reclamação.
        DateOpeningPI:
          type: string
          format: date-time
          nullable: true
          description: Data de abertura da PI.
        DatePostingObject:
          type: string
          format: date-time
          nullable: true
          description: Data de postagem do objeto.
        DateMaxDelivery:
          type: string
          format: date-time
          nullable: true
          description: Prazo máximo de entrega.
        DateLastEvent:
          type: string
          format: date-time
          nullable: true
          description: Data do último evento.
        StatusPI:
          type: string
          maxLength: 45
          nullable: true
          description: Status atual da PI.
        SubStatusPI:
          type: string
          maxLength: 45
          nullable: true
          description: Sub-status atual da PI.
        LastMessageResponse:
          type: string
          maxLength: 1000
          nullable: true
          description: Última mensagem retornada pelos Correios.
        DateLastResponse:
          type: string
          format: date-time
          nullable: true
          description: Data da última resposta dos Correios.
        ShippingId:
          type: string
          nullable: true
          description: Identificador de embarque.
        ShippingDate:
          type: string
          format: date-time
          nullable: true
          description: Data do embarque.
        IDOrder:
          type: integer
          description: Identificador do pedido.
        Order:
          type: string
          nullable: true
          description: Número do pedido.
        CarrierDeliveryDate:
          type: string
          format: date-time
          nullable: true
          description: Data prevista de entrega pela transportadora.
        AccountName:
          type: string
          description: Subdomínio da empresa.
        SupplierNameCorporateName:
          type: string
          nullable: true
          description: Razão social da transportadora.
        OrderFrom:
          type: string
          nullable: true
          description: Origens do pedido separadas por vírgula.
    FileUploadResponse:
      type: object
      description: Registro do arquivo recém-vinculado ao consumidor, com URL pré-assinada de download.
      properties:
        RecordTimestamp:
          type: string
          format: date-time
          description: Data/hora de criação do vínculo.
        IDConsumerFile:
          type: integer
          format: int64
          description: Identificador do arquivo vinculado.
        IDTypeFile:
          type: integer
          description: Tipo do arquivo (mesmos valores aceitos no query `IDTypeFile`).
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 7
            - 8
        TypeFile:
          type: string
          description: 'Nome legível do tipo do arquivo (ex.: `Documento Fiscal PDF`).'
        IDConsumer:
          type: integer
          format: int64
          description: Identificador do consumidor dono do arquivo.
        Key:
          type: string
          description: Chave interna do objeto no bucket (`Consumer/<id>.<ext>`).
        UrlFile:
          type: string
          format: uri
          description: URL pré-assinada para download direto do arquivo (validade aproximada de 48 horas).
    AppChatTokenResponse:
      type: object
      required:
        - token
      properties:
        token:
          type: string
          description: >-
            JWT assinado para abrir a sessão de chat. Carrega `external_id`, `email`, `name`, `email_verified=true` e
            `scope=user`; expiração padrão de 12 horas.
    PostalCodeAddress:
      type: object
      description: >-
        Endereço retornado pela consulta de CEP, combinando dados do cadastro interno de logradouros com o município
        (IBGE) correspondente à faixa de CEP.
      properties:
        Street:
          type: string
          nullable: true
          description: Logradouro.
        PostalCode:
          type: string
          description: CEP (somente dígitos).
        Neighborhood:
          type: string
          nullable: true
          description: Bairro.
        AdditionalInfo:
          type: string
          nullable: true
          description: Complemento padrão do logradouro (quando cadastrado).
        Latitude:
          type: number
          nullable: true
          description: Latitude do logradouro (quando disponível).
        Longitude:
          type: number
          nullable: true
          description: Longitude do logradouro (quando disponível).
        State:
          type: string
          description: UF do município, derivada da faixa de CEP.
        CityName:
          type: string
          description: Nome do município.
        CityCodeIBGE:
          type: integer
          description: Código IBGE do município (`CityCode`).
    SkuMovementKardexBatchItem:
      type: object
      description: Item do Kardex cronológico de um lote (`Type=KardexBatch`), com saldo e custo acumulados do lote.
      properties:
        AccountName:
          type: string
          description: Subdomínio (identificador) da empresa.
        IDSkuMovement:
          type: integer
          description: Identificador da movimentação de estoque.
        IDSku:
          type: integer
          description: Identificador do SKU.
        RecordTimestamp:
          type: string
          format: date-time
          description: Data e hora da movimentação.
        Comments:
          type: string
          nullable: true
          description: Observações da movimentação.
        IDStockKeepingUnitProduction:
          type: integer
          nullable: true
          description: Identificador da ordem de produção relacionada, quando houver.
        IDTypeMovement:
          type: integer
          enum:
            - 0
            - 1
          description: 'Tipo da movimentação: `0` entrada, `1` saída.'
        IDPurchase:
          type: integer
          nullable: true
          description: Identificador do recebimento relacionado, quando houver.
        IDOrder:
          type: integer
          nullable: true
          description: Identificador do pedido relacionado, quando houver.
        IDStockKeepingUnitWarehouse:
          type: integer
          description: Identificador do armazém da movimentação.
        IDOriginIDSkuMovement:
          type: integer
          nullable: true
          description: Identificador da movimentação de origem (transferências/estornos), quando houver.
        IDStockKeepingUnitInventory:
          type: integer
          nullable: true
          description: Identificador do inventário relacionado, quando houver.
        IDStockKeepingUnitInventorySummary:
          type: integer
          nullable: true
          description: Identificador do resumo de inventário relacionado, quando houver.
        Quantity:
          type: number
          description: Quantidade movimentada (positiva para entrada, negativa para saída).
        IDBatch:
          type: integer
          description: Identificador do lote.
        WarehouseName:
          type: string
          description: Nome do armazém da movimentação.
        IDStockKeepingUnitLocation:
          type: integer
          nullable: true
          description: Identificador do endereço, quando houver.
        Address:
          type: string
          nullable: true
          description: Endereço de estoque, quando houver.
        BestBeforeDate:
          type: string
          format: date
          nullable: true
          description: Data de validade do lote, quando houver.
        ManufacturingDate:
          type: string
          format: date
          nullable: true
          description: Data de fabricação do lote, quando houver.
        BatchComments:
          type: string
          nullable: true
          description: Observações do lote, quando houver.
        ValueCost:
          type: number
          description: Custo unitário da movimentação.
        ValueCostTotal:
          type: number
          description: Custo total da movimentação.
        CardexQty:
          type: number
          description: Saldo acumulado do lote após esta movimentação.
        CardexValueCost:
          type: number
          description: Custo total acumulado do lote após esta movimentação.
        DateCreated:
          type: string
          format: date-time
          description: Data e hora de criação do registro.
        Login:
          type: string
          nullable: true
          description: Login do usuário responsável pela movimentação.
        TypeMovement:
          type: string
          nullable: true
          description: >-
            Origem da movimentação: `Recebimento`, `Venda`, `Transferência CD`, `Transferência endereço`, `Ajuste saldo
            estoque`, `Inventário`, `Produção`.
        TypeSkuMovement:
          type: string
          nullable: true
          enum:
            - Entrada
            - Saída
          description: 'Sentido da movimentação: `Entrada` ou `Saída`.'
        CardexAverageValueCost:
          type: string
          nullable: true
          description: Custo médio acumulado no kardex, com 2 casas decimais.
        IsTransfer:
          type: integer
          enum:
            - 0
            - 1
          nullable: true
          description: >-
            Indica se o tipo do pedido é de transferência entre centros de distribuição (`1`) ou não (`0`). Nulo quando
            a movimentação não está vinculada a um pedido.
  responses:
    Unauthorized:
      description: >-
        Falha de autenticação: header `Authorization` ausente, malformado ou com token JWT inválido/expirado. O corpo
        segue o formato padrão (`{ "message": "Unauthorized" }`), sem o prefixo `[BadRequest]`.
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Unauthorized
x-tagGroups:
  - name: Catálogo
    tags:
      - Categorias Similares
      - Categorias de Produto
      - Coleções
      - Códigos Similares
      - Códigos de Barras
      - Códigos de Barras (Embalagem)
      - Especificações de SKU
      - Especificações por Categoria
      - Fornecedores ↔ SKUs
      - Grupos de SKU
      - Imagens de SKU
      - Kits
      - Marcas
      - Preços
      - Produtos e SKUs
      - SKU — Etiqueta
      - Tags de SKU
      - Templates de Importação
      - Tipos de Embalagem
      - Tipos — Canal de Venda
      - Tipos — SKU
      - Variações (Grade)
  - name: Estoque
    tags:
      - Armazéns
      - Centros de Distribuição
      - Endereços de Estoque
      - Inventário
      - Inventário (Legacy)
      - Log de SKU
      - Lotes
      - Movimentação de Estoque
      - Números de Série
      - Produção
      - Recálculo de Custo
      - Ressuprimento
      - Saldo de Estoque
  - name: Vendas
    tags:
      - Pedidos
      - Promoção PDV
      - Tipos — Pedido
  - name: PDV
    tags:
      - Frente de Caixa
      - Pagamento PDV
      - Tipos — PDV
  - name: Fulfillment
    tags:
      - Packing
      - Picking
      - Tipos — Fulfillment
  - name: Frete
    tags:
      - Correios — PI
      - Cotação de Frete
      - Faixa de Etiquetas Correios
      - Logística Reversa Correios
      - Modalidades de Transporte
      - Templates de Rastreamento
      - Tipos — Cotação
  - name: Compras
    tags:
      - Agendamento de Recebimento
      - DE-PARA CFOP Recebimento
      - Feed de NF-e
      - Pedido de Compra
      - Recebimento
      - Tipos — Compras
  - name: Nota Fiscal
    tags:
      - CT-e
      - NF-e / NFC-e
      - NFS-e
      - Tipos — CT-e
      - Tipos — Nota Fiscal
  - name: Impostos
    tags:
      - Departamentos Tributários
      - Tipos — Impostos
  - name: Financeiro
    tags:
      - Boleto Bancário
      - Conciliação Bancária
      - Contas Bancárias
      - Contas a Pagar
      - Contas a Receber
      - Fluxo de Caixa
      - Tipos — Contas e Pagamento
  - name: Clientes
    tags:
      - Cadastro de Clientes
      - Tipos — Cliente
  - name: Fornecedores
    tags:
      - Cadastro de Fornecedores
      - Categorias de Fornecedor
      - Tipos — Fornecedor
  - name: Marketplaces
    tags:
      - Hub — Anúncios
      - Hub — Categorias
      - Hub — DE-PARA Adquirentes
      - Hub — DE-PARA Transportadora
      - Hub — DE-PARA Variações
      - Hub — Estoque
      - Hub — Marcas
      - Hub — Notificações
      - Hub — Pagamento
      - Hub — Pedidos
      - Hub — Política Comercial
      - Hub — Recursos
      - Hub — Tipos de Referência
  - name: Usuários
    tags:
      - Autenticação
      - Cadastro de Usuários
      - Jornada de Trabalho
      - Metas
      - Notificações de Versão
      - Perfis de Acesso
      - Tipos — Metas
      - Tipos — Usuário
  - name: Empresa
    tags:
      - Cobrança
      - Dashboards
      - Etiquetas (Empresa)
      - Integrações
      - Minha Empresa
      - Módulos Contratados
      - Políticas Comerciais
      - Relatórios Customizados
      - Tipos — Empresa
      - Tipos — Etiquetas
      - Tipos — Relatórios
      - Transições de Status
  - name: Plataforma
    tags:
      - Arquivos
      - Jobs e Tarefas
      - Logs de Webhook
      - Tipos — Jobs
      - Webhooks / Callbacks
