c6_bank 0.2.0

data/docs/openapi/bolepix.yaml

@@ -0,0 +1,850 @@
+openapi: 3.0.3
+info:
+  title: Bolepix
+  version: 1.1.1
+  description: |-
+    ## O que esta API permite?
+    A API de Bolepix oferece uma solução completa para a gestão de cobranças. Com ela, é possível automatizar processos financeiros, integrar diferentes métodos de pagamento em um único fluxo e garantir maior flexibilidade e agilidade na conciliação de recebíveis.
+
+    ## Objetivo
+    O objetivo da API é permitir a emissão, edição, consulta, download e baixa (cancelamento) de cobranças que podem ser pagas tanto por boleto bancário quanto por Pix QR Code no C6 Bank.
+
+    - Emissão de uma cobrança contendo boleto bancário e Pix QR Code.
+    - Acréscimo de juros e multa ao valor inicial para pagamento pós vencimento.
+    - Concessão de desconto por antecipação do pagamento.
+    - Consulta de uma cobrança previamente emitida.
+    - Listagem de cobranças com filtros por data e status.
+    - Download da cobrança emitida em formato PDF.
+    - Atualização parcial de uma cobrança emitida.
+    - Cancelamento (baixa) de uma cobrança não paga.
+
+    ________________
+
+    ## Carteiras
+
+    O C6 Bank oferece duas carteiras de cobrança:
+
+    Carteira para **produção** sendo a carteira do número: 15
+
+    Carteira para **sandbox** sendo a carteira do número: 21
+
+    ________________
+
+    ## **Resumo Técnico da API**
+
+    Operações disponíveis para esta API:
+
+    | Operações                                                                                               |
+    |:-------------------------------------------------------------------------------------------------------:|
+    | [Emitir cobrança Bolepix](bolepix#tag/api-de-bolepix/post/v2/bank_slips)                                |
+    | [Listar cobranças](bolepix#tag/api-de-bolepix/get/v2/bank_slips/list)                                   |
+    | [Consultar cobrança](bolepix#tag/api-de-bolepix/get/v2/bank_slips/{external_reference_id})              |
+    | [Download do PDF](bolepix#tag/api-de-bolepix/get/v2/bank_slips/{external_reference_id}/pdf)             |
+    | [Atualizar cobrança](bolepix#tag/api-de-bolepix/patch/v2/bank_slips/{external_reference_id})     |
+    | [Cancelar cobrança](bolepix#tag/api-de-bolepix/put/v2/bank_slips/{external_reference_id}/cancel)        |
+
+    ## Endereços dos ambientes:
+
+    | Ambiente | Host                                 | Path            |
+    |:--------:|------------------------------------- |-----------------|
+    | Sandbox  | https://baas-api-sandbox.c6bank.info | /v2/bank_slips/ |
+    | Produção | https://baas-api.c6bank.info         | /v2/bank_slips/ |
+servers:
+  - url: https://baas-api-sandbox.c6bank.info
+    description: Ambiente sandbox
+  - url: https://baas-api.c6bank.info
+    description: Ambiente produtivo
+tags:
+  - name: API de Bolepix
+    description: Operações de Bolepix
+paths:
+  /v2/bank_slips:
+    post:
+      tags:
+        - API de Bolepix
+      summary: Emitir cobrança
+      description: Emite uma nova cobrança contendo boleto bancário e, de forma opcional, um QR Code Pix para pagamento.
+      parameters:
+        - $ref: '#/components/parameters/Authorization'
+        - $ref: '#/components/parameters/PartnerSoftwareName'
+        - $ref: '#/components/parameters/PartnerSoftwareVersion'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/bank_slip_pix_create_request'
+        required: true
+      responses:
+        '201':
+          description: Cobrança emitida com sucesso
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/bank_slip_pix_create_response'
+        '4XX':
+          description: Para descrição de erros visite a <a href="https://developers.c6bank.com.br/apis/errors">documentação correspondente</a>.
+        '5XX':
+          description: Para descrição de erros visite a <a href="https://developers.c6bank.com.br/apis/errors">documentação correspondente</a>.
+  /v2/bank_slips/list:
+    get:
+      tags:
+        - API de Bolepix
+      summary: Listar cobranças
+      description: Retorna uma lista paginada de cobranças emitidas. É obrigatório informar ao menos um intervalo de datas (payment_date, due_date ou credit_date).
+      parameters:
+        - $ref: '#/components/parameters/Authorization'
+        - $ref: '#/components/parameters/PartnerSoftwareName'
+        - $ref: '#/components/parameters/PartnerSoftwareVersion'
+        - name: payment_date_from
+          in: query
+          description: Data de início para filtro por data de pagamento. Formato YYYY-MM-DD (O intervalo máximo entre datas é de 60 dias).
+          required: false
+          schema:
+            type: string
+            format: date
+        - name: payment_date_to
+          in: query
+          description: Data de fim para filtro por data de pagamento. Formato YYYY-MM-DD (O intervalo máximo entre datas é de 60 dias).
+          required: false
+          schema:
+            type: string
+            format: date
+        - name: due_date_from
+          in: query
+          description: Data de início para filtro por data de vencimento. Formato YYYY-MM-DD (O intervalo máximo entre datas é de 60 dias).
+          required: false
+          schema:
+            type: string
+            format: date
+        - name: due_date_to
+          in: query
+          description: Data de fim para filtro por data de vencimento. Formato YYYY-MM-DD (O intervalo máximo entre datas é de 60 dias).
+          required: false
+          schema:
+            type: string
+            format: date
+        - name: credit_date_from
+          in: query
+          description: Data de início para filtro por data de crédito. Formato YYYY-MM-DD (O intervalo máximo entre datas é de 60 dias).
+          required: false
+          schema:
+            type: string
+            format: date
+        - name: credit_date_to
+          in: query
+          description: Data de fim para filtro por data de crédito. Formato YYYY-MM-DD (O intervalo máximo entre datas é de 60 dias).
+          required: false
+          schema:
+            type: string
+            format: date
+        - name: status
+          in: query
+          description: "Filtro por status atual da cobrança. <br> Possíveis status: <br> **CREATED** -> Cobrança criada. <br> **PAID** -> Pagamento liquidado. <br> **CANCELED** -> Cobrança cancelada. <br> **WAITING_CONFIRMATION** -> O pagamento da cobrança foi confirmado, no entanto, os recursos financeiros ainda não foram creditados na conta."
+          required: false
+          schema:
+            type: string
+            enum:
+              - CREATED
+              - PAID
+              - CANCELED
+              - WAITING_CONFIRMATION
+        - name: external_reference_id
+          in: query
+          description: Filtro por external reference id.
+          required: false
+          schema:
+            type: string
+            example: 01KP640RNSYXH9G41GR27RTAWP
+            pattern: '^[A-Z0-9]{26}$'
+            minLength: 26
+            maxLength: 26
+        - name: page
+          in: query
+          description: Número da página para paginação dos resultados.
+          required: false
+          schema:
+            type: integer
+            minimum: 0
+            default: 0
+        - name: size
+          in: query
+          description: Quantidade de itens por página.
+          required: false
+          schema:
+            type: integer
+            default: 20
+            minimum: 1
+            maximum: 100
+            example: 20
+      responses:
+        '200':
+          description: Lista de cobranças retornada com sucesso
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/bank_slip_pix_list_response'
+        '4XX':
+          description: Para descrição de erros visite a <a href="https://developers.c6bank.com.br/apis/errors">documentação correspondente</a>.
+        '5XX':
+          description: Para descrição de erros visite a <a href="https://developers.c6bank.com.br/apis/errors">documentação correspondente</a>.
+  /v2/bank_slips/{external_reference_id}:
+    parameters:
+      - $ref: '#/components/parameters/PartnerSoftwareName'
+      - $ref: '#/components/parameters/PartnerSoftwareVersion'
+      - $ref: '#/components/parameters/Authorization'
+    get:
+      tags:
+        - API de Bolepix
+      summary: Consultar cobrança
+      description: Retorna os dados completos de uma cobrança previamente emitida.
+      parameters:
+        - $ref: '#/components/parameters/Bank_Slip_Id'
+      responses:
+        '200':
+          description: Cobrança obtida com sucesso
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/bank_slip_pix_get_response'
+        '4XX':
+          description: Para descrição de erros visite a <a href="https://developers.c6bank.com.br/apis/errors">documentação correspondente</a>.
+        '5XX':
+          description: Para descrição de erros visite a <a href="https://developers.c6bank.com.br/apis/errors">documentação correspondente</a>.
+    patch:
+      tags:
+        - API de Bolepix
+      summary: Atualizar cobrança
+      description: Atualiza parcialmente uma cobrança já emitida.
+      parameters:
+        - $ref: '#/components/parameters/Bank_Slip_Id'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/bank_slip_pix_patch_request'
+        required: true
+      responses:
+        '200':
+          description: Cobrança atualizada com sucesso
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/bank_slip_pix_get_response'
+              example:
+                id: "01KYAJSQFP21E44C97DG0ZNRST"
+                amount: 109.25
+                due_date: "2026-07-10"
+                payment_method:
+                  bank_slip:
+                    originator_id: "000006242018"
+                    billing_scheme: "17"
+                    billing_type: "3"
+                    bar_code: "33693150300000109250000062420180010310417213"
+                    digitable_line: "33690.00009   62420.180010   03104.172139   3   15030000010925"
+                    our_number: "0577702972"
+                    number: "01KYAJSR9NAD1CZ001JHPCRRN6"
+                  pix: null
+                external_reference_id: "BB3TCTYDJQ2HBM64ZU7ZIOK4FC"
+                description: "string"
+                days_after_due_date: 0
+                status: "CREATED"
+                payer:
+                  name: "Alan Santos"
+                  tax_id: "51709522000153"
+                  address:
+                    address: "Av. General Hosorio, 1234"
+                    neighborhood: "Bairro"
+                    city: "São Paulo"
+                    state: "SP"
+                    zip_code: "05093000"
+                fees:
+                  fine_type: "FIXED_VALUE"
+                  fine_value: 10.25
+                  interest_type: "VALUE_PER_DAY"
+                  interest_value: 10.25
+                  discount_type: "VALUE_PER_DAY"
+                  first_discount_value: 0.00
+                  first_discount_deadline: 0
+                origin: "string"
+        '4XX':
+          description: Para descrição de erros visite a <a href="https://developers.c6bank.com.br/apis/errors">documentação correspondente</a>.
+        '5XX':
+          description: Para descrição de erros visite a <a href="https://developers.c6bank.com.br/apis/errors">documentação correspondente</a>.
+  /v2/bank_slips/{external_reference_id}/pdf:
+    parameters:
+      - $ref: '#/components/parameters/PartnerSoftwareName'
+      - $ref: '#/components/parameters/PartnerSoftwareVersion'
+      - $ref: '#/components/parameters/Authorization'
+    get:
+      tags:
+        - API de Bolepix
+      summary: Consulta de PDF da cobrança
+      description: Retorna o PDF da cobrança para download ou impressão.
+      parameters:
+        - $ref: '#/components/parameters/Bank_Slip_Id'
+      responses:
+        '200':
+          description: PDF da cobrança obtido com sucesso
+        '4XX':
+          description: Para descrição de erros visite a <a href="https://developers.c6bank.com.br/apis/errors">documentação correspondente</a>.
+        '5XX':
+          description: Para descrição de erros visite a <a href="https://developers.c6bank.com.br/apis/errors">documentação correspondente</a>.
+  /v2/bank_slips/{external_reference_id}/cancel:
+    put:
+      tags:
+        - API de Bolepix
+      summary: Cancelar cobrança
+      description: Cancela uma cobrança previamente emitida. Após o cancelamento, o título não estará mais disponível para pagamento.
+      parameters:
+        - $ref: '#/components/parameters/Authorization'
+        - $ref: '#/components/parameters/PartnerSoftwareName'
+        - $ref: '#/components/parameters/PartnerSoftwareVersion'
+        - $ref: '#/components/parameters/Bank_Slip_Id'
+      responses:
+        '204':
+          description: Cobrança cancelada com sucesso
+        '4XX':
+          description: Para descrição de erros, visite a <a href="https://developers.c6bank.com.br/apis/errors">documentação correspondente</a>.
+        '5XX':
+          description: Para descrição de erros, visite a <a href="https://developers.c6bank.com.br/apis/errors">documentação correspondente</a>.
+components:
+  parameters:
+    Authorization:
+      in: header
+      name: Authorization
+      description: Token de acesso obtido via API de Autenticação. Formato `Bearer {{token}}`.
+      schema:
+        type: string
+      required: true
+      example: "Bearer {{your_access_token}}"
+    PartnerSoftwareName:
+      in: header
+      name: partner-software-name
+      description: Nome do software parceiro que está realizando a integração. Utilizado para identificação e rastreabilidade.
+      schema:
+        type: string
+      required: false
+      example: "Super PDV"
+    PartnerSoftwareVersion:
+      in: header
+      name: partner-software-version
+      description: Versão do software parceiro. Facilita o suporte e diagnóstico em caso de problemas.
+      schema:
+        type: string
+      required: false
+      example: "1.0.0"
+    Bank_Slip_Id:
+      in: path
+      name: external_reference_id
+      description: Identificador único da cobrança atribuído pelo integrador. Utilizado em todas as operações de consulta, atualização e cancelamento.
+      schema:
+        type: string
+        pattern: '^[A-Z0-9]{26}$'
+        minLength: 26
+        maxLength: 26
+      required: true
+      example: "01J3NCKY6Q99QC4D7T733D35QD"
+  schemas:
+    address:
+      type: object
+      description: Endereço do pagador (sacado) vinculado à cobrança.
+      required:
+        - city
+        - state
+        - address
+        - zip_code
+        - neighborhood
+      properties:
+        address:
+          type: string
+          example: "Av. Nove de Julho, 3186"
+          maxLength: 40
+          description: Logradouro e número. Limite de 40 caracteres no total.
+        neighborhood:
+          type: string
+          example: "Jardim Paulista"
+          maxLength: 40
+          description: Bairro do endereço.
+        city:
+          type: string
+          example: "São Paulo"
+          maxLength: 40
+          description: Cidade do endereço.
+        state:
+          type: string
+          example: "SP"
+          maxLength: 2
+          pattern: "[A-Z]{2}"
+          description: UF do endereço. Duas letras maiúsculas (ex. SP, RJ, MG).
+        zip_code:
+          type: string
+          example: '01406000'
+          minLength: 8
+          maxLength: 8
+          pattern: "\\d{8}"
+          description: CEP do endereço, somente números (sem traço).
+    description:
+      type: string
+      example: "Mensalidade referente a Junho/2026"
+      maxLength: 100
+      description: Texto descritivo da cobrança. Máximo de 100 caracteres.
+    fees:
+      type: object
+      description: Configuração de multa, juros e desconto aplicáveis à cobrança.
+      properties:
+        fine_value:
+          type: number
+          example: 10.0
+          minimum: 0
+          description: Valor da multa por atraso no pagamento.
+        fine_deadline:
+          type: integer
+          example: 1
+          description: Dias após o vencimento para aplicação da multa.
+        fine_type:
+          type: string
+          example: FIXED_VALUE
+          enum:
+            - FIXED_VALUE
+            - PERCENTAGE
+          description: |
+            Tipo de cálculo da multa:
+            - `FIXED_VALUE` — valor fixo em reais.
+            - `PERCENTAGE` — percentual sobre o valor da cobrança.
+        interest_value:
+          type: number
+          example: 0.33
+          minimum: 0
+          description: Valor dos juros por atraso.
+        interest_deadline:
+          type: integer
+          example: 1
+          description: Dias após o vencimento para início da cobrança de juros.
+        interest_type:
+          type: string
+          example: VALUE_PER_DAY
+          enum:
+            - VALUE_PER_DAY
+            - MONTHLY_PERCENTAGE
+          description: |
+            Tipo de cálculo dos juros:
+            - `VALUE_PER_DAY` — valor fixo cobrado por dia de atraso.
+            - `MONTHLY_PERCENTAGE` — percentual mensal aplicado proporcionalmente.
+        discount_type:
+          type: string
+          example: VALUE_PER_DAY
+          enum:
+            - VALUE_PER_DAY
+            - MONTHLY_PERCENTAGE
+          description: |
+            Tipo de cálculo do desconto por antecipação:
+            - `VALUE_PER_DAY` — valor fixo por dia de antecipação.
+            - `MONTHLY_PERCENTAGE` — percentual mensal proporcional.
+        first_discount_value:
+          type: number
+          example: 5.0
+          minimum: 0
+          description: Valor do desconto concedido por pagamento antecipado.
+        first_discount_deadline:
+          type: integer
+          example: 10
+          description: Dias antes do vencimento em que o desconto é aplicável.
+    amount:
+      type: number
+      example: 150.00
+      maximum: 5000000
+      description: Valor da cobrança em reais. Máximo de R$ 5.000.000,00.
+    origin:
+      type: string
+      example: "e-commerce"
+      maxLength: 20
+      description: Canal ou origem da cobrança (ex. e-commerce, PDV, ERP).
+    bank_slip_pix_create_request:
+      type: object
+      required:
+        - amount
+        - due_date
+        - description
+        - payer
+        - payment_method
+      properties:
+        external_reference_id:
+          $ref: '#/components/schemas/external_reference_id'
+        amount:
+          $ref: '#/components/schemas/amount'
+        due_date:
+          $ref: "#/components/schemas/due_date"
+        description:
+          $ref: '#/components/schemas/description'
+        days_after_due_date:
+          type: integer
+          example: 10
+          description: "Quantidade de dias, contados a partir da data de vencimento, após os quais a cobrança expira."
+        payer:
+          $ref: '#/components/schemas/payer'
+        fees:
+          $ref: '#/components/schemas/fees'
+        payment_method:
+          type: object
+          description: "Objeto utilizado para controle do método de pagamento. Este campo é obrigatório para emissão da cobrança"
+          required:
+            - bank_slip
+          properties:
+            bank_slip:
+              type: object
+              description: "Objeto utilizado para controle do método de pagamento boleto e pix. Existe a possibilidade de emitir um boleto sem Pix, basta não passar os dois campos próprios para Pix."
+              required:
+                - billing_scheme
+              properties:
+                our_number:
+                  $ref: '#/components/schemas/our_number'
+                billing_scheme:
+                  $ref: '#/components/schemas/billing_scheme'
+                your_number:
+                  $ref: '#/components/schemas/your_number'
+                instructions:
+                  $ref: "#/components/schemas/instructions"
+            pix:
+              type: object
+              description: "Objeto utilizado para controle das informações específicas do pagamento via Pix."
+              required:
+                - type
+                - key
+              properties:
+                key:
+                  type: string
+                  example: '123e4567-e89b-12d3-a456-426614174000'
+                  description: "Chave Pix a ser utilizada para geração do QR Code. **Importante:** A chave estar cadastrada no C6 Bank e precisa ser do tipo chave aleatória. Se esse campo não for enviado ou se for enviado uma chave PIX inválida, a cobrança é criada normalmente, mas sem as informações do Pix (QR Code, imagem do QR Code e referência)."
+                type:
+                  type: string
+                  example: 'EVP'
+                  description: "Tipo de chave Pix utilizada. Atualmente só é suportado EVP. **Importante:** Se esse campo não for enviado, a cobrança será criada normalmente, mas sem as informações do Pix (QR Code, imagem do QR Code e referência)."
+                  enum:
+                    - 'EVP'
+        origin:
+          $ref: '#/components/schemas/origin'
+    bank_slip_pix_patch_request:
+      type: object
+      properties:
+        amount:
+          $ref: '#/components/schemas/amount'
+        due_date:
+          $ref: "#/components/schemas/due_date"
+        description:
+          $ref: '#/components/schemas/description'
+        days_after_due_date:
+          type: integer
+          example: 30
+          description: "Quantidade de dias, contados a partir da data de vencimento, após os quais a cobrança expira."
+        payer:
+          type: object
+          description: Dados do pagador do título.
+          properties:
+            email:
+              type: string
+              format: email
+              example: pagador@email.com.br
+              maxLength: 70
+              description: Endereço de email do cliente pagador (sacado).
+            address:
+              $ref: '#/components/schemas/address'
+        fees:
+          $ref: '#/components/schemas/fees'
+        payment_method:
+          type: object
+          description: "Objeto utilizado para controle do método de pagamento."
+          properties:
+            bank_slip:
+              type: object
+              description: "Objeto utilizado para controle das informações específicas do boleto."
+              properties:
+                your_number:
+                  $ref: '#/components/schemas/your_number'
+                instructions:
+                  $ref: "#/components/schemas/instructions"
+        origin:
+          $ref: '#/components/schemas/origin'
+    bank_slip_pix_create_response:
+      type: object
+      properties:
+        id:
+          $ref: '#/components/schemas/id'
+        external_reference_id:
+          $ref: '#/components/schemas/external_reference_id'
+        amount:
+          $ref: '#/components/schemas/amount'
+        due_date:
+          $ref: "#/components/schemas/due_date"
+        payment_method:
+          $ref: '#/components/schemas/payment_method'
+    bank_slip_pix_get_response:
+      type: object
+      properties:
+        amount:
+          $ref: '#/components/schemas/amount'
+        due_date:
+          $ref: "#/components/schemas/due_date"
+        emission_date:
+          $ref: "#/components/schemas/emission_date"
+        payment_method:
+          $ref: '#/components/schemas/payment_method'
+        id:
+          $ref: '#/components/schemas/id'
+        description:
+          $ref: '#/components/schemas/description'
+        days_after_due_date:
+          type: integer
+          example: 10
+          description: "Quantidade de dias, contados a partir da data de vencimento, após os quais a cobrança expira."
+        status:
+          type: string
+          enum:
+            - CREATED
+            - PAID
+            - CANCELED
+            - WAITING_CONFIRMATION
+          example: "CREATED"
+          description: "Status atual da cobrança. <br> Possíveis status: <br> **CREATED** -> Cobrança criada. <br> **PAID** -> Pagamento liquidado. <br> **CANCELED** -> Cobrança cancelada. <br> **WAITING_CONFIRMATION** -> O pagamento da cobrança foi confirmado, no entanto, os recursos financeiros ainda não foram creditados na conta."
+        payer:
+          $ref: '#/components/schemas/payer'
+        fees:
+          $ref: '#/components/schemas/fees'
+        origin:
+          $ref: '#/components/schemas/origin'
+        external_reference_id:
+          $ref: '#/components/schemas/external_reference_id'
+    bank_slip_pix_object_list_response:
+      allOf:
+        - $ref: '#/components/schemas/bank_slip_pix_get_response'
+        - type: object
+          properties:
+            payments:
+              $ref: '#/components/schemas/payments'
+    bank_slip_pix_list_response:
+      type: object
+      properties:
+        content:
+          type: array
+          items:
+            $ref: '#/components/schemas/bank_slip_pix_object_list_response'
+        total_elements:
+          type: integer
+          example: 10
+        total_pages:
+          type: integer
+          example: 1
+        page:
+          type: integer
+          example: 0
+        size:
+          type: integer
+          example: 20
+    payments:
+      type: array
+      description: Lista de pagamentos da cobrança.
+      items:
+        type: object
+        required:
+          - amount
+          - external_payment_id
+          - payment_date
+          - payment_type
+        properties:
+          amount:
+            type: string
+            description: Valor do pagamento com duas casas decimais.
+            example: "123.45"
+            pattern: '^\d+(\.\d{2})$'
+          external_payment_id:
+            type: string
+            description: Identificador externo do pagamento.
+            example: "01KVG41MYPFJRCJE4AVK9NCFQ1"
+            pattern: '^[A-Z0-9]{26}$'
+            minLength: 26
+            maxLength: 26
+          payment_date:
+            type: string
+            format: date
+            description: Data em que o pagamento foi realizado.
+            example: "2026-06-19"
+          credit_date:
+            type: string
+            format: date
+            description: Data em que o valor foi creditado na conta.
+            example: "2026-06-22"
+          payment_type:
+            type: string
+            description: Tipo de pagamento.
+            example: "BANK_SLIP"
+            enum:
+              - BANK_SLIP
+              - PIX
+    payment_method:
+      type: object
+      description: "Objeto utilizado para controle do método de pagamento. Este campo é obrigatório para emissão da cobrança"
+      required:
+        - bank_slip
+        - pix
+      properties:
+        bank_slip:
+          type: object
+          description: "Objeto utilizado para controle das informações específicas do boleto."
+          properties:
+            originator_id:
+              $ref: "#/components/schemas/originator_id"
+            billing_scheme:
+              $ref: '#/components/schemas/billing_scheme'
+            billing_type:
+              $ref: '#/components/schemas/billing_type'
+            digitable_line:
+              $ref: '#/components/schemas/digitable_line'
+            bar_code:
+              $ref: '#/components/schemas/bar_code'
+            our_number:
+              $ref: '#/components/schemas/our_number'
+            number:
+              type: string
+              example: '12345678'
+              description: "Número do título gerado pelo cliente. Este campo é utilizado para controle do título pelo cliente e deve ser único para cada título emitido."
+        pix:
+          type: object
+          description: "Objeto utilizado para controle das informações específicas do pagamento via Pix."
+          properties:
+            qr_code:
+              type: string
+              example: '00020126580014BR.GOV.BCB.PIX0114123e4567-e89b-12d3-a456-4266141740005204000053039865404123.455802BR5909Fulano de Tal6009Sao Paulo61080540900062070503***6304B14F'
+              description: "Código QR para pagamento via Pix."
+            image_content:
+              type: string
+              format: byte
+              description: "Imagem do código QR para pagamento via Pix, codificada em Base64."
+            mime_type:
+              type: string
+              example: 'image/png'
+              description: "Tipo MIME da imagem do código QR para pagamento via Pix."
+            reference:
+              type: string
+              example: '123e4567-e89b-12d3-a456-426614174000'
+              description: "Identificador único para controle do pagamento via Pix."
+    bar_code:
+      type: string
+      example: '33695969000000123450000003048720009224128213'
+      readOnly: true
+      description: Código de barras do boleto (44 dígitos). Gerado automaticamente pelo banco.
+    billing_scheme:
+      type: string
+      example: "15"
+      description: |
+        Carteira de cobrança:
+        - Produção: `15`
+        - Sandbox: `21`
+    billing_type:
+      type: string
+      readOnly: true
+      description: |
+        Modalidade de emissão do boleto:
+        - `3` — emissão pelo banco (cobrança registrada).
+        - `4` — emissão pelo cedente (cobrança direta).
+      enum:
+        - "3"
+        - "4"
+    digitable_line:
+      type: string
+      example: '33690.00009   03048.720001   92241.282133   5   96900000012345'
+      readOnly: true
+      description: Linha digitável do boleto (47 caracteres).
+    due_date:
+      type: string
+      format: date
+      example: "2026-12-30"
+      description: Data de vencimento da cobrança no formato `YYYY-MM-DD`. Deve ser igual ou posterior à data atual.
+    emission_date:
+      type: string
+      format: date
+      example: "2026-06-15"
+      readOnly: true
+      description: Data em que a cobrança foi emitida. Preenchida automaticamente pelo banco.
+    external_reference_id:
+      type: string
+      example: 01KP640RNSYXH9G41GR27RTAWP
+      pattern: '^[A-Z0-9]{26}$'
+      minLength: 26
+      maxLength: 26
+      description: |
+        Identificador único da cobrança definido pelo integrador (26 caracteres alfanuméricos maiúsculos).
+        Não pode ser reutilizado — cada nova cobrança deve ter um `external_reference_id` diferente.
+        Se enviado em duplicidade, retornará os dados da cobrança já existente.
+    id:
+      type: string
+      readOnly: true
+      example: 01HVSBSTN8CCTCTEQT6MC7TD4B
+      description: Identificador interno da cobrança gerado pelo C6 Bank. Utilizado como chave principal nas operações.
+    instructions:
+      type: array
+      items:
+        type: string
+        maxLength: 80
+      maxItems: 4
+      example: ["Não receber após o vencimento", "Multa de 2% após vencimento"]
+      description: Instruções impressas no boleto para o operador de caixa. Máximo de 4 linhas com até 80 caracteres cada.
+    internal_id:
+      type: string
+      example: A1234
+      readOnly: true
+      description: Identificador interno do boleto no sistema bancário.
+    originator_id:
+      type: string
+      readOnly: true
+      example: "000000304872"
+      description: Código do cedente (beneficiário) no C6 Bank.
+    our_number:
+      type: string
+      example: "0000003048"
+      minLength: 1
+      maxLength: 10
+      pattern: '^\d{1,10}$'
+      description: |
+        Nosso número — identificador único do título junto ao banco para o cedente.
+        Geralmente gerado pelo banco, mas pode ser informado pelo integrador.
+    your_number:
+      type: string
+      example: "0000003048"
+      minLength: 1
+      maxLength: 10
+      pattern: '^\d{1,10}$'
+      description: Número de controle do integrador. Utilizado para referência interna do título no sistema do parceiro.
+    payer:
+      type: object
+      description: Dados do pagador (sacado) — pessoa física ou jurídica responsável pelo pagamento.
+      required:
+        - name
+        - tax_id
+        - address
+      properties:
+        name:
+          type: string
+          example: "José da Silva"
+          maxLength: 40
+          pattern: "^(?!\\s*$).+"
+          description: Nome completo (PF) ou razão social (PJ) do pagador. Máximo de 40 caracteres.
+        tax_id:
+          type: string
+          example: '12345678910'
+          minLength: 11
+          maxLength: 14
+          description: |
+            CPF (11 dígitos) ou CNPJ (14 dígitos) do pagador.
+            Enviar somente números, sem máscara, respeitando zeros à esquerda.
+        email:
+          type: string
+          format: email
+          example: "pagador@email.com.br"
+          maxLength: 70
+          description: E-mail do pagador. Utilizado para envio de notificações sobre a cobrança.
+        address:
+          $ref: '#/components/schemas/address'
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT