c6_bank 0.2.0

data/docs/rails_initializer_example.rb

@@ -0,0 +1,17 @@
+# config/initializers/c6_bank.rb
+#
+# Store secrets in Rails credentials or environment variables.
+# Never commit real certificates or client secrets.
+
+C6Bank.configure do |c|
+  c.client_id     = Rails.application.credentials.dig(:c6_bank, :client_id) || ENV.fetch("C6_CLIENT_ID")
+  c.client_secret = Rails.application.credentials.dig(:c6_bank, :client_secret) || ENV.fetch("C6_CLIENT_SECRET")
+  c.pix_key       = Rails.application.credentials.dig(:c6_bank, :pix_key) || ENV["C6_PIX_KEY"]
+
+  c.certificate_path = Rails.application.credentials.dig(:c6_bank, :cert_path) || ENV.fetch("C6_CERT_PATH")
+  c.private_key_path = Rails.application.credentials.dig(:c6_bank, :key_path) || ENV.fetch("C6_KEY_PATH")
+
+  c.environment = Rails.env.production? ? :production : :sandbox
+  c.partner_software_name = "MyApp"
+  c.partner_software_version = "1.0.0"
+end

data/docs/roteiro_mapping.md

@@ -0,0 +1,31 @@
+# Roteiro de Conformidade → Gem
+
+Paths below match the official C6 OpenAPI (`docs/openapi/bolepix.yaml`, `docs/openapi/pix-api.yaml`).
+
+## Bolepix (`client.boletos`) — `/v2/bank_slips`
+
+| Roteiro | Method |
+|---|---|
+| 1–3 Emitir (simples, juros/multa, desconto) | `create` / `C6Bank::Boleto::Request` (`with_fees`, `with_juros`, `with_multa`, `add_desconto`) |
+| 4 Baixa | `cancel` / `baixa` → `PUT /v2/bank_slips/{id}/cancel` |
+| 5 Alterar | `update` → `PATCH /v2/bank_slips/{id}` |
+| 6 Consultar | `find` → `GET /v2/bank_slips/{id}` |
+| Listar | `list` → `GET /v2/bank_slips/list` |
+| PDF | `pdf` → `GET /v2/bank_slips/{id}/pdf` |
+
+Pix QR on a boleto: set `C6_PIX_KEY` (EVP). Opt out with `req.without_pix`.
+
+## Pix (`client.pix`) — `/v2/pix`
+
+| Roteiro | Method | HTTP |
+|---|---|---|
+| 7.1 / 7.2 Cobrança imediata | `create_immediate_charge` | `POST /cob` or `PUT /cob/{txid}` |
+| 7.3 Consultar cob | `find_immediate` | `GET /cob/{txid}` |
+| 7.4 Listar cob | `list_immediate` | `GET /cob` |
+| 7.5 Cobrança com vencimento | `create_due_charge` | `PUT /cobv/{txid}` |
+| 7.6 / 7.7 Consultar cobv | `find_due` / `list_due` | `GET /cobv/{txid}`, `GET /cobv` |
+| 7.8 Webhook | `configure_webhook` | `PUT /webhook/{chave}` |
+
+## Payments / DDA (`client.dda`)
+
+Still a thin wrapper. Confirm paths in the Agendamento de Pagamentos spec before homologating section 8.

data/examples/auth_probe.rb

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require_relative "env"
+require "c6_bank"
+
+C6BankExamples.load_env!
+
+client = C6Bank::Client.from_env
+client.authenticate!
+puts "Authenticated. scope=#{client.scope.inspect}"
+rescue C6Bank::AuthenticationError => e
+  abort e.message

data/examples/boleto_cases.rb

@@ -0,0 +1,56 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "date"
+require "json"
+require_relative "env"
+require "c6_bank"
+
+C6BankExamples.load_env!
+
+client = C6Bank::Client.from_env
+client.authenticate!
+
+due_date = (Date.today + 10).iso8601
+
+puts "=== Bolepix with Pix (default when C6_PIX_KEY is set) ==="
+req = C6Bank.boleto_request(
+  amount: 150.75,
+  due_date: due_date,
+  description: "Pedido 42"
+)
+req.payer(
+  name: "Fulano de Tal",
+  tax_id: "12345678909",
+  address: {
+    address: "Av. Nove de Julho, 3186",
+    neighborhood: "Jardins",
+    city: "Sao Paulo",
+    state: "SP",
+    zip_code: "01406000"
+  }
+)
+req.with_fees(
+  fine_value: 10,
+  fine_deadline: 5,
+  fine_type: "FIXED_VALUE",
+  interest_value: 0.5,
+  interest_deadline: 1,
+  interest_type: "VALUE_PER_DAY"
+)
+req.bank_slip(instructions: ["Nao receber apos o vencimento"])
+
+puts JSON.pretty_generate(req.to_h.merge("payment_method" => req.to_h[:payment_method]))
+puts
+puts client.boletos.create(req)
+
+puts "\n=== Boleto only ==="
+req2 = C6Bank.boleto_request(amount: 99.90, due_date: due_date, description: "Somente boleto")
+req2.payer(
+  name: "Empresa Exemplo Ltda",
+  tax_id: "12345678000195",
+  address: { address: "Rua Teste 100", city: "Curitiba", state: "PR", zip_code: "80010000" }
+)
+req2.without_pix
+puts client.boletos.create(req2)

data/examples/env.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module C6BankExamples
+  module_function
+
+  def load_env!(path = File.expand_path("../.env", __dir__))
+    return unless File.file?(path)
+
+    File.readlines(path, chomp: true).each do |line|
+      next if line.strip.empty? || line.lstrip.start_with?("#")
+
+      key, value = line.split("=", 2)
+      next unless key && value
+
+      ENV[key] = unquote(value) if ENV[key].nil? || ENV[key].empty?
+    end
+  end
+
+  def unquote(value)
+    value.strip.sub(/\A(['"])(.*)\1\z/, '\2')
+  end
+end

data/examples/live_sandbox.rb

@@ -0,0 +1,90 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Hits the C6 sandbox with the credentials in `.env`.
+#
+#   bundle exec ruby examples/live_sandbox.rb
+#
+# Sandbox hours: Monday–Friday 07:00–22:00 BRT.
+
+require "bundler/setup"
+require "date"
+require "json"
+require_relative "env"
+require "c6_bank"
+
+$stdout.sync = true
+
+C6BankExamples.load_env!
+
+client = C6Bank::Client.from_env
+
+puts "Environment : #{client.config.environment}"
+puts "Base URL    : #{client.config.effective_base_url}"
+puts "Client ID   : #{client.config.client_id[0, 8]}…"
+puts "Pix key     : #{client.config.pix_key}"
+puts "Wallet      : #{client.config.effective_billing_scheme}"
+puts
+
+begin
+  client.authenticate!
+  puts "Auth OK"
+  puts "Scope     : #{client.scope.inspect}"
+rescue C6Bank::AuthenticationError => e
+  abort <<~MSG
+    Auth failed: #{e.message}
+
+    Typical causes:
+    - mTLS certificate expired or not issued for this client_id
+    - sandbox closed (Mon-Fri 07:00-22:00 BRT)
+    - client_id / client_secret mismatch
+  MSG
+end
+
+due_date = (Date.today + 10).iso8601
+
+puts "\n=== Bolepix (boleto + Pix QR) ==="
+req = C6Bank.boleto_request(
+  amount: 12.34,
+  due_date: due_date,
+  description: "c6_bank gem live sandbox"
+)
+req.payer(
+  name: "Fulano de Tal",
+  tax_id: "12345678909",
+  address: {
+    address: "Av. Nove de Julho, 3186",
+    neighborhood: "Jardins",
+    city: "Sao Paulo",
+    state: "SP",
+    zip_code: "01406000"
+  }
+)
+req.bank_slip(instructions: ["Pagavel via boleto ou Pix"])
+
+begin
+  bolepix = client.boletos.create(req)
+  puts JSON.pretty_generate(bolepix)
+  pix = bolepix.dig("payment_method", "pix") || bolepix.dig(:payment_method, :pix)
+  if pix
+    puts "Pix QR present: #{pix['qr_code'] || pix[:qr_code] ? 'yes' : 'no'}"
+    puts "Pix reference : #{pix['reference'] || pix[:reference]}"
+  else
+    puts "WARN: charge created without Pix. Check that C6_PIX_KEY is a registered EVP key."
+  end
+rescue C6Bank::ApiError => e
+  puts "Bolepix failed (#{e.status}): #{e.body}"
+end
+
+puts "\n=== Pix cob (immediate charge) ==="
+begin
+  cob = client.pix.create_immediate_charge(
+    amount: "5.00",
+    expiration: 3600,
+    devedor: { cpf: "12345678909", nome: "Fulano de Tal" },
+    solicitacaoPagador: "c6_bank gem live sandbox"
+  )
+  puts JSON.pretty_generate(cob)
+rescue C6Bank::ApiError => e
+  puts "Pix cob failed (#{e.status}): #{e.body}"
+end

data/examples/pix_cases.rb

@@ -0,0 +1,42 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "date"
+require "json"
+require_relative "env"
+require "c6_bank"
+
+C6BankExamples.load_env!
+
+client = C6Bank::Client.from_env
+client.authenticate!
+
+puts "=== Immediate Pix charge (cob) ==="
+cob = client.pix.create_immediate_charge(
+  amount: "89.90",
+  expiration: 3600,
+  devedor: { cpf: "12345678909", nome: "Fulano" },
+  solicitacaoPagador: "Servico prestado"
+)
+puts JSON.pretty_generate(cob)
+
+puts "\n=== Due Pix charge (cobv) ==="
+cobv = client.pix.create_due_charge(
+  amount: "250.00",
+  due_date: (Date.today + 15).iso8601,
+  days_after_due: 30,
+  devedor: {
+    cpf: "12345678909",
+    nome: "Fulano de Tal",
+    logradouro: "Alameda Souza, 80",
+    cidade: "Recife",
+    uf: "PE",
+    cep: "70011750"
+  },
+  solicitacaoPagador: "Cobranca com vencimento"
+)
+puts JSON.pretty_generate(cobv)
+
+puts "\nConsult by txid:"
+puts JSON.pretty_generate(client.pix.find_immediate(cob.fetch("txid")))

data/exe/c6_bank

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "c6_bank"

data/lib/c6_bank/boleto/request.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module C6Bank
+  module Boleto
+    # Builder for C6 Bank Bolepix (bank slip + optional Pix QR) requests.
+    #
+    # Matches the official OpenAPI spec (docs/openapi/bolepix.yaml).
+    class Request
+      attr_reader :data
+
+      def self.generate_external_reference_id
+        require "securerandom"
+        SecureRandom.alphanumeric(26).upcase
+      end
+
+      def self.apply_defaults(body, config, omit_pix: false)
+        payload = C6Bank::Pix::Payload.stringify(body)
+        payment_method = payload["payment_method"] ||= {}
+        bank_slip = payment_method["bank_slip"] ||= {}
+        bank_slip["billing_scheme"] ||= config.effective_billing_scheme
+
+        if omit_pix
+          payment_method.delete("pix")
+        elsif payment_method["pix"].nil? && config.pix_key
+          payment_method["pix"] = { "key" => config.pix_key, "type" => "EVP" }
+        end
+
+        payload["external_reference_id"] ||= generate_external_reference_id
+        payload
+      end
+
+      def initialize(params = {})
+        @omit_pix = false
+        @data = {
+          external_reference_id: params[:external_reference_id] || params["external_reference_id"],
+          amount: params[:amount] || params[:valor] || params["amount"] || params["valor"],
+          due_date: params[:due_date] || params[:data_vencimento] || params["due_date"] || params["data_vencimento"],
+          description: params[:description] || params["description"],
+          days_after_due_date: params[:days_after_due_date] || params["days_after_due_date"],
+          origin: params[:origin] || params["origin"],
+          payer: normalize_payer(params[:payer] || params["payer"]),
+          fees: normalize_fees(params[:fees] || params["fees"]),
+          payment_method: {
+            bank_slip: {}
+          }
+        }.compact
+
+        return unless params[:payment_method] || params["payment_method"]
+
+        @data[:payment_method] = (params[:payment_method] || params["payment_method"]).dup
+      end
+
+      def omit_pix?
+        @omit_pix
+      end
+
+      def payer(name: nil, tax_id: nil, email: nil, address: nil, **rest)
+        payer_data = {
+          name: name,
+          tax_id: tax_id,
+          email: email,
+          address: address
+        }.merge(rest).compact
+        @data[:payer] = normalize_payer(payer_data)
+        self
+      end
+
+      def with_fees(**fee_params)
+        @data[:fees] = normalize_fees(fee_params)
+        self
+      end
+
+      def bank_slip(billing_scheme: nil, our_number: nil, your_number: nil, instructions: nil, **rest)
+        @data[:payment_method] ||= {}
+        bs = @data[:payment_method][:bank_slip] ||= {}
+        bs[:billing_scheme] = billing_scheme.to_s if billing_scheme
+        bs[:our_number] = our_number.to_s if our_number
+        bs[:your_number] = your_number.to_s if your_number
+        bs[:instructions] = Array(instructions) if instructions
+        bs.merge!(rest.transform_keys(&:to_sym))
+        self
+      end
+
+      def pix(key:, type: "EVP")
+        @omit_pix = false
+        @data[:payment_method] ||= {}
+        @data[:payment_method][:pix] = { key: key, type: type }
+        self
+      end
+
+      def without_pix
+        @omit_pix = true
+        @data[:payment_method]&.delete(:pix)
+        self
+      end
+
+      def with_juros(valor:, tipo: :diario)
+        tipo_str = case tipo.to_s.downcase
+                   when "diario", "value_per_day" then "VALUE_PER_DAY"
+                   when "monthly_percentage", "mensal" then "MONTHLY_PERCENTAGE"
+                   else tipo.to_s.upcase
+                   end
+        fees = @data[:fees] || {}
+        fees[:interest_value] = valor
+        fees[:interest_type] = tipo_str
+        @data[:fees] = fees
+        self
+      end
+
+      def with_multa(tipo:, valor:)
+        tipo_str = case tipo.to_s.downcase
+                   when "fixo", "fixed" then "FIXED_VALUE"
+                   when "percentual", "percentage", "%" then "PERCENTAGE"
+                   else tipo.to_s.upcase
+                   end
+        fees = @data[:fees] || {}
+        fees[:fine_value] = valor
+        fees[:fine_type] = tipo_str
+        @data[:fees] = fees
+        self
+      end
+
+      def add_desconto(**opts)
+        fees = @data[:fees] ||= {}
+        fees[:first_discount_value] = opts[:valor] || opts[:value] if opts[:valor] || opts[:value]
+        fees[:first_discount_deadline] = opts[:dias_antes] || opts[:deadline] if opts[:dias_antes] || opts[:deadline]
+        if opts[:tipo] || opts[:type]
+          t = (opts[:tipo] || opts[:type]).to_s.upcase
+          fees[:discount_type] = t
+        end
+        self
+      end
+
+      def to_h
+        result = @data.dup
+        if result[:payment_method].is_a?(Hash)
+          result[:payment_method] = result[:payment_method].dup
+          result[:payment_method].delete(:pix) if result[:payment_method][:pix].nil? || omit_pix?
+        end
+        result.compact
+      end
+
+      private
+
+      def normalize_payer(payer)
+        return nil unless payer
+
+        p = payer.is_a?(Hash) ? payer.dup : {}
+        p[:tax_id] ||= p.delete(:cpf_cnpj) || p.delete("cpf_cnpj")
+        addr = p[:address] || p["address"]
+        p[:address] = addr.transform_keys(&:to_sym) if addr.is_a?(Hash)
+        p.transform_keys(&:to_sym).compact
+      end
+
+      def normalize_fees(fees)
+        return nil unless fees
+
+        f = fees.is_a?(Hash) ? fees.dup : {}
+        f.transform_keys(&:to_sym).compact
+      end
+    end
+  end
+end

data/lib/c6_bank/client.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "openssl"
+require "json"
+require "time"
+require "uri"
+
+module C6Bank
+  class Client
+    TOKEN_PATHS = ["/v1/auth", "/v1/auth/"].freeze
+
+    attr_reader :config, :scope
+
+    def self.from_env(**overrides)
+      new(
+        {
+          client_id: ENV.fetch("C6_CLIENT_ID"),
+          client_secret: ENV.fetch("C6_CLIENT_SECRET"),
+          certificate_path: ENV.fetch("C6_CERT_PATH"),
+          private_key_path: ENV.fetch("C6_KEY_PATH"),
+          pix_key: ENV["C6_PIX_KEY"],
+          environment: (ENV["C6_ENV"] || "sandbox").to_sym,
+          partner_software_name: ENV["C6_PARTNER_SOFTWARE_NAME"],
+          partner_software_version: ENV["C6_PARTNER_SOFTWARE_VERSION"],
+          base_url: ENV["C6_BASE_URL"],
+          auth_base_url: ENV["C6_AUTH_BASE_URL"],
+          token_path: ENV["C6_TOKEN_PATH"],
+          boleto_path: ENV["C6_BOLETO_PATH"],
+          pix_path: ENV["C6_PIX_PATH"]
+        }.compact.merge(overrides)
+      )
+    end
+
+    def initialize(options = {})
+      @config = Configuration.new
+
+      options.each do |key, value|
+        setter = "#{key}="
+        @config.public_send(setter, value) if @config.respond_to?(setter)
+      end
+
+      @config.validate!
+
+      @token = nil
+      @token_expires_at = nil
+      @scope = nil
+      @preferred_token_path = options[:token_path] || @config.token_path
+    end
+
+    def connection
+      @connection ||= build_connection
+    end
+
+    def boletos
+      Resources::Boleto.new(self)
+    end
+
+    def pix
+      Resources::Pix.new(self)
+    end
+
+    def dda
+      Resources::Dda.new(self)
+    end
+
+    def request(method, path, body: nil, params: nil, headers: {}, raw: false)
+      ensure_authenticated!
+
+      response = perform_request(method, path, body: body, params: params, headers: headers)
+      begin
+        raw ? raw_or_error(response) : handle_response(response)
+      rescue AuthenticationError
+        raise unless response.status == 401
+
+        @token = nil
+        @token_expires_at = nil
+        ensure_authenticated!
+        response = perform_request(method, path, body: body, params: params, headers: headers)
+        raw ? raw_or_error(response) : handle_response(response)
+      end
+    end
+
+    def authenticate!(token_path: nil)
+      @config.validate!
+
+      auth_base = @config.effective_auth_base_url
+      token_conn = Faraday.new(url: auth_base) do |f|
+        f.ssl.merge!(ssl_options)
+        f.request :retry, max: @config.max_retries, interval: 0.5, interval_randomness: 0.5, backoff_factor: 2,
+                          methods: %i[post], retry_statuses: [429, 500, 502, 503, 504]
+        f.options.open_timeout = @config.open_timeout
+        f.options.timeout = @config.read_timeout
+        f.adapter Faraday.default_adapter
+      end
+
+      paths = if token_path
+                [token_path]
+              else
+                [@preferred_token_path, *TOKEN_PATHS].compact.uniq
+              end
+
+      last_error = nil
+      paths.each do |path|
+        resp = token_conn.post(path) do |req|
+          req.headers.merge!(
+            "Content-Type" => "application/x-www-form-urlencoded",
+            "Accept" => "application/json"
+          )
+          req.body = URI.encode_www_form(
+            grant_type: "client_credentials",
+            client_id: @config.client_id,
+            client_secret: @config.client_secret
+          )
+        end
+
+        if resp.status.between?(200, 299)
+          store_token(resp)
+          @preferred_token_path = path
+          return true
+        end
+
+        last_error = AuthenticationError.new("Could not obtain token (#{resp.status}): #{utf8(resp.body)}")
+      end
+
+      raise last_error if last_error
+
+      raise AuthenticationError, "Could not obtain token"
+    end
+
+    def authenticated?
+      @token && @token_expires_at && Time.now < @token_expires_at
+    end
+
+    def set_token(access_token, expires_in: 3600)
+      @token = access_token
+      @token_expires_at = Time.now + expires_in.to_i - 30
+    end
+
+    def auth_headers(extra = {})
+      h = {}
+      h["Authorization"] = "Bearer #{@token}" if @token
+      h["partner-software-name"] = @config.partner_software_name if @config.partner_software_name
+      h["partner-software-version"] = @config.partner_software_version if @config.partner_software_version
+      h.merge(extra)
+    end
+
+    private
+
+    def ensure_authenticated!
+      authenticate! unless authenticated?
+    end
+
+    def store_token(resp)
+      parsed = begin
+        JSON.parse(resp.body.to_s)
+      rescue JSON::ParserError
+        {}
+      end
+      token = parsed["access_token"] || parsed["token"] || parsed["accessToken"]
+
+      raise AuthenticationError, "Response did not include access_token. Body: #{resp.body}" unless token
+
+      @token = token
+      @scope = parsed["scope"]
+      expires = parsed["expires_in"] || parsed["expiresIn"] || 3600
+      @token_expires_at = Time.now + expires.to_i - 30
+      true
+    end
+
+    def build_connection
+      Faraday.new(url: @config.effective_base_url) do |f|
+        f.ssl.merge!(ssl_options)
+        f.request :retry, max: @config.max_retries,
+                          interval: 0.5,
+                          interval_randomness: 0.5,
+                          backoff_factor: 2,
+                          methods: %i[get head options],
+                          retry_statuses: [429, 500, 502, 503, 504]
+        f.options.open_timeout = @config.open_timeout
+        f.options.timeout = @config.read_timeout
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def ssl_options
+      {
+        client_cert: @config.ssl_certificate,
+        client_key: @config.ssl_private_key,
+        verify: true
+      }
+    end
+
+    def perform_request(method, path, body:, params:, headers:)
+      request_headers = {
+        "Accept" => "application/json"
+      }.merge(headers)
+
+      request_headers["Content-Type"] ||= "application/json" if body
+      request_headers["Authorization"] = "Bearer #{@token}" if @token
+      request_headers["partner-software-name"] = @config.partner_software_name if @config.partner_software_name
+      request_headers["partner-software-version"] = @config.partner_software_version if @config.partner_software_version
+
+      connection.public_send(method, path) do |req|
+        req.params.update(params) if params
+        req.body = json_body(body) unless body.nil?
+        req.headers.merge!(request_headers)
+      end
+    end
+
+    def json_body(body)
+      return body if body.is_a?(String)
+
+      JSON.generate(body)
+    end
+
+    def raw_or_error(response)
+      return response if response.status.between?(200, 299)
+
+      handle_response(response)
+    end
+
+    def utf8(value)
+      str = value.to_s.dup
+      str.force_encoding("UTF-8")
+      str.encode("UTF-8", invalid: :replace, undef: :replace)
+    end
+
+    def handle_response(response)
+      case response.status
+      when 200..299
+        return nil if response.body.to_s.strip.empty?
+
+        begin
+          JSON.parse(response.body)
+        rescue JSON::ParserError
+          utf8(response.body)
+        end
+      when 401
+        @token = nil
+        @token_expires_at = nil
+        raise AuthenticationError, "Unauthorized (401): #{utf8(response.body)}"
+      when 404
+        raise NotFoundError.new("Not found", status: 404, body: utf8(response.body), response: response)
+      when 429
+        raise RateLimitError.new("Rate limited", status: 429, body: utf8(response.body), response: response)
+      when 500..599
+        raise ServerError.new("Server error", status: response.status, body: utf8(response.body), response: response)
+      else
+        raise ApiError.new("API error", status: response.status, body: utf8(response.body), response: response)
+      end
+    end
+  end
+end