openapi: 3.0.1
info:
  title: Baixas
  version: v1
  description: API para gerenciamento de baixas
servers:
  - url: https://api-v2.contaazul.com
    description: Servidor de produção
tags:
  - name: v1
    description: >-
      Conjunto de recursos para acompanhar e administrar operações relacionadas
      ao gerenciamento de baixas - esses recursos incluem criar uma nova baixa,
      retornar as baixas pelo id da parcela, atualizar parcialmente uma baixa
      por id, deletar baixa por id e retornar a baixa por id
security:
  - BearerAuth: []
paths:
  /v1/financeiro/eventos-financeiros/parcelas/{parcela_id}/baixa:
    post:
      summary: Criar uma nova baixa
      operationId: criarBaixa
      description: Cria uma baixa para uma parcela específica
      tags:
        - v1
      parameters:
        - name: parcela_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: 35473eec-4e74-11ee-b500-9f61de8a8b8b
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BaixaCriacaoRequestDTO'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaixaCriacaoResponseDTO'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '429':
          description: Too Many Requests
        '500':
          description: Internal Server Error
    get:
      summary: Retornar as baixas pelo id da parcela
      operationId: listarBaixas
      description: Lista todas as baixas associadas ao id da parcela
      tags:
        - v1
      parameters:
        - name: parcela_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: 35473eec-4e74-11ee-b500-9f61de8a8b8b
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BaixaResponseDTO'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '429':
          description: Too Many Requests
        '500':
          description: Internal Server Error
  /v1/financeiro/eventos-financeiros/parcelas/baixa/{baixa_id}:
    patch:
      summary: Atualizar parcialmente uma baixa por id
      operationId: atualizarBaixa
      description: Atualiza os dados de uma baixa existente
      tags:
        - v1
      parameters:
        - name: baixa_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: 35473eec-4e74-11ee-b500-9f61de8a8b8b
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BaixaAtualizacaoRequestDTO'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaixaCriacaoResponseDTO'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '429':
          description: Too Many Requests
        '500':
          description: Internal Server Error
    delete:
      summary: Deletar baixa por id
      operationId: deletarBaixa
      description: Remove uma baixa pelo id fornecido
      tags:
        - v1
      parameters:
        - name: baixa_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: 35473eec-4e74-11ee-b500-9f61de8a8b8b
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '404':
          description: Not Found
        '429':
          description: Too Many Requests
        '500':
          description: Internal Server Error
    get:
      summary: Retornar a baixa por id
      operationId: buscarBaixa
      description: Retorna os detalhes de uma baixa pelo id fornecido
      tags:
        - v1
      parameters:
        - name: baixa_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: 35473eec-4e74-11ee-b500-9f61de8a8b8b
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaixaResponseDTO'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '404':
          description: Not Found
        '429':
          description: Too Many Requests
        '500':
          description: Internal Server Error
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Token de autorização Bearer JWT
  schemas:
    BaixaCriacaoRequestDTO:
      type: object
      required:
        - data_pagamento
        - conta_financeira
        - composicao_valor
      properties:
        data_pagamento:
          type: string
          format: date
          example: '2023-10-01'
          description: Data do pagamento
        composicao_valor:
          $ref: '#/components/schemas/ValorComposicaoDTO'
        conta_financeira:
          type: string
          format: uuid
          example: 35473eec-4e74-11ee-b500-9f61de8a8b8b
          description: Identificador único da conta financeira
        metodo_pagamento:
          type: string
          example: CARTAO_CREDITO
          description: Método de pagamento
          enum:
            - DINHEIRO
            - CARTAO_CREDITO
            - BOLETO_BANCARIO
            - CARTAO_CREDITO_VIA_LINK
            - CHEQUE
            - CARTAO_DEBITO
            - TRANSFERENCIA_BANCARIA
            - OUTRO
            - CARTEIRA_DIGITAL
            - CASHBACK
            - CREDITO_LOJA
            - CREDITO_VIRTUAL
            - DEPOSITO_BANCARIO
            - PIX_PAGAMENTO_INSTANTANEO
        observacao:
          type: string
          example: 'Pagamento referente à fatura #1234.'
          description: Observação
        nsu:
          type: string
          example: '1234567890'
          description: Número sequencial único
    BaixaCriacaoResponseDTO:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 35473eec-4e74-11ee-b500-9f61de8a8b8b
          description: Identificador único gerado automaticamente após a criação
        versao:
          type: integer
          format: int64
          example: 1
          description: Versão da baixa
        data_pagamento:
          type: string
          format: date
          example: '2023-10-01'
          description: Data do pagamento
        composicao_valor:
          $ref: '#/components/schemas/ValorComposicaoDTO'
        conta_financeira:
          type: string
          format: uuid
          example: 35473eec-4e74-11ee-b500-9f61de8a8b8b
          description: Identificador único da conta financeira
        metodo_pagamento:
          type: string
          example: CARTAO_CREDITO
          description: Método de pagamento
          enum:
            - DINHEIRO
            - CARTAO_CREDITO
            - BOLETO_BANCARIO
            - CARTAO_CREDITO_VIA_LINK
            - CHEQUE
            - CARTAO_DEBITO
            - TRANSFERENCIA_BANCARIA
            - OUTRO
            - CARTEIRA_DIGITAL
            - CASHBACK
            - CREDITO_LOJA
            - CREDITO_VIRTUAL
            - DEPOSITO_BANCARIO
            - PIX_PAGAMENTO_INSTANTANEO
        observacao:
          type: string
          example: 'Pagamento referente à fatura #1234.'
          description: Observação
        nsu:
          type: string
          example: '1234567890'
          description: Número sequencial único
    BaixaResponseDTO:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 35473eec-4e74-11ee-b500-9f61de8a8b8b
          description: Identificador único da baixa
        versao:
          type: integer
          format: int64
          example: 1
          description: Versão da baixa
        data_pagamento:
          type: string
          format: date
          example: '2023-10-01'
          description: Data do pagamento
        valor_composicao:
          $ref: '#/components/schemas/ValorComposicaoDTO'
        conta_financeira:
          type: string
          format: uuid
          example: 35473eec-4e74-11ee-b500-9f61de8a8b8b
          description: Identificador único da conta financeira
        id_reconciliacao:
          type: string
          format: uuid
          example: 35473eec-4e74-11ee-b500-9f61de8a8b8b
          description: Identificador único da reconciliação
        id_parcela:
          type: string
          format: uuid
          example: 35473eec-4e74-11ee-b500-9f61de8a8b8b
          description: Identificador único da parcela
        id_solicitacao_cobranca:
          type: string
          format: uuid
          example: 35473eec-4e74-11ee-b500-9f61de8a8b8b
          description: Identificador único da solicitação de cobrança
        observacao:
          type: string
          example: 'Pagamento referente à fatura #1234.'
          description: Observação
        metodo_pagamento:
          type: string
          example: CARTAO_CREDITO
          description: Método de pagamento
          enum:
            - DINHEIRO
            - CARTAO_CREDITO
            - BOLETO_BANCARIO
            - CARTAO_CREDITO_VIA_LINK
            - CHEQUE
            - CARTAO_DEBITO
            - TRANSFERENCIA_BANCARIA
            - OUTRO
            - CARTEIRA_DIGITAL
            - CASHBACK
            - CREDITO_LOJA
            - CREDITO_VIRTUA
            - DEPOSITO_BANCARIO
            - PIX_PAGAMENTO_INSTANTANEO
            - PROGRAMA_FIDELIDADE
            - SEM_PAGAMENTO
            - VALE_ALIMENTACAO
            - VALE_COMBUSTIVEL
            - VALE_PRESENTE
            - VALE_REFEICAO
            - PIX_COBRANCA
            - DEBITO_AUTOMATICO
        origem:
          type: string
          example: SALDO_CONTA_BANCARIA
          description: Origem
          enum:
            - LANCAMENTO_FINANCEIRO
            - DAS
            - FOLHA
            - TRANSFERENCIA
            - SALDO_CONTA_BANCARIA
            - VENDA
            - COMPRA
            - VENDA_AGENDADA
            - COMPRA_AGENDADA
            - IMPORTACAO_DOCUMENTO
            - IMPOSTO_RETIDO
            - SIC
            - NOTA_COMPRA
            - ANTECIPACAO
            - RENEGOCIACAO
            - HONORARIOS_CONTABEIS
        id_recibo_digital:
          type: string
          format: uuid
          example: 35473eec-4e74-11ee-b500-9f61de8a8b8b
          description: Identificador único do recibo digital
        tipo_evento_financeiro:
          type: string
          example: RECEITA
          description: Tipo de evento financeiro
          enum:
            - RECEITA
            - DESPESA
        nsu:
          type: string
          example: '1234567890'
          description: Número sequencial único
        id_referencia:
          type: string
          example: REF1234
          description: Identificador único da referência
        atualizado_em:
          type: string
          format: date-time
          example: '2023-10-01T12:00:00Z'
          description: Data de atualização
        anexos:
          type: array
          items:
            $ref: '#/components/schemas/AnexoBaixaResponseDTO'
    AnexoBaixaResponseDTO:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 35473eec-4e74-11ee-b500-9f61de8a8b8b
          description: Identificador único do anexo
        referencia:
          type: string
          example: REF1234
          description: Referência associada ao anexo
        nome:
          type: string
          example: pagamento_recibo.pdf
          description: Nome do anexo
        descricao:
          type: string
          example: 'Recibo de pagamento referente à fatura #1234.'
          description: Descrição detalhada do anexo
        tipo:
          type: string
          example: RECIBO_DIGITAL
          description: Tipo do anexo
          enum:
            - RECIBO_DIGITAL
            - RECIBO
        tipo_conteudo:
          type: string
          example: FILE
          description: Tipo de conteúdo do anexo
          enum:
            - FILE
            - URL
        url:
          type: string
          example: https://example.com/attachment.pdf
          description: URL do anexo
    ValorComposicaoDTO:
      type: object
      required:
        - valor_bruto
      properties:
        multa:
          type: number
          format: double
          example: 5
          description: Valor da multa, deve ser maior ou igual a zero
        juros:
          type: number
          format: double
          example: 2.5
          description: Valor dos juros, deve ser maior ou igual a zero
        valor_bruto:
          type: number
          format: double
          example: 150
          description: Valor bruto, deve ser informado e maior ou igual a zero
        desconto:
          type: number
          format: double
          example: 10
          description: Valor do desconto, deve ser maior ou igual a zero
        taxa:
          type: number
          format: double
          example: 3.75
          description: Valor da taxa, deve ser maior ou igual a zero
    BaixaAtualizacaoRequestDTO:
      type: object
      required:
        - versao
      properties:
        versao:
          type: integer
          format: int64
          example: 1
          description: >-
            Versão atual do registro. Este valor será incrementado após sucesso
            na atualização
        data_pagamento:
          type: string
          format: date
          example: '2023-10-01'
          description: Data do pagamento
        composicao_valor:
          $ref: '#/components/schemas/ValorComposicaoDTO'
        conta_financeira:
          type: string
          format: uuid
          example: 35473eec-4e74-11ee-b500-9f61de8a8b8b
          description: Identificador único da conta financeira
        metodo_pagamento:
          type: string
          example: CARTAO_CREDITO
          description: Método de pagamento
          enum:
            - DINHEIRO
            - CARTAO_CREDITO
            - BOLETO_BANCARIO
            - CARTAO_CREDITO_VIA_LINK
            - CHEQUE
            - CARTAO_DEBITO
            - TRANSFERENCIA_BANCARIA
            - OUTRO
            - CARTEIRA_DIGITAL
            - CASHBACK
            - CREDITO_LOJA
            - CREDITO_VIRTUA
            - DEPOSITO_BANCARIO
            - PIX_PAGAMENTO_INSTANTANEO
        observacao:
          type: string
          example: 'Pagamento referente à fatura #1234.'
          description: Observação adicional
        nsu:
          type: string
          example: '1234567890'
          description: Número sequencial único
