c6_bank 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d85a23a335c256e6eebc98545e7161dafb42806fdff667eaf9731a7515868ff5
+  data.tar.gz: 57258199ce71cdf3e11f79f5340bc8d1a1a505f0d48c8fff1e2a59a5fc59892d
+SHA512:
+  metadata.gz: 0f813fa0ebfc94866b98fcdd3cf3671ab78eea8ab32cf88ad43f2e05129b9019a1552da55d2eb8a4b40a2a6e5a3a10bf876456226e9ac5e975a9386c4e38f0e0
+  data.tar.gz: 1c70fc4cf3586658b4d867cf8c2bc6bbb352e075e04f65d24aa93b7d3cbace626d7c1857a1e8a3d7082a07f5c6a285338d08e650e2ff5df203c0ce03afbda01e

data/.env.example

@@ -0,0 +1,11 @@
+# C6 Bank credentials (sandbox)
+# Copy to .env and fill in. Never commit .env.
+
+C6_ENV=sandbox
+C6_CLIENT_ID=your-client-id
+C6_CLIENT_SECRET=your-client-secret
+C6_PIX_KEY=your-evp-pix-key
+C6_CERT_PATH=docs/certs/c6_sandbox.crt
+C6_KEY_PATH=docs/certs/c6_sandbox.key
+C6_PARTNER_SOFTWARE_NAME=c6_bank-gem
+C6_PARTNER_SOFTWARE_VERSION=0.2.0

data/.ruby-version

@@ -0,0 +1 @@
+ruby-3.4.7

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+## [Unreleased]
+
+- Request Bolepix PDFs with `Accept: */*` because sandbox returns 406 for `application/pdf` alone.
+
+## [0.2.0] - 2026-09-18
+
+- Wire the client to the official C6 contracts: auth `/v1/auth`, Bolepix `/v2/bank_slips`, Pix `/v2/pix`.
+- Enable Pix automatically on Bolepix charges when `pix_key` is configured (EVP random key).
+- Implement Pix cob/cobv, received Pix, refunds and webhook helpers.
+- Add Bolepix list + patch, authenticated PDF download, and `Client.from_env`.
+- Stop shipping hardcoded credentials in examples and the README.
+
+## [0.1.0] - 2026-06-17
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"c6_bank" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["byellokore@users.noreply.github.com"](mailto:"byellokore@users.noreply.github.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Gabriel Fontoura Dos Santos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,318 @@
+# c6_bank
+
+Ruby client for [C6 Bank BaaS](https://developers.c6bank.com.br/get-started). It speaks the three contracts this gem is built around:
+
+| Product | What it does | Path |
+|---|---|---|
+| **Auth** | OAuth2 client-credentials token over mTLS | `POST /v1/auth` |
+| **Bolepix** | One charge payable as boleto **and** Pix QR | `/v2/bank_slips` |
+| **Pix** | BACEN Pix cob / cobv, received Pix, refunds, webhooks | `/v2/pix` |
+
+Hosts:
+
+- Sandbox: `https://baas-api-sandbox.c6bank.info`
+- Production: `https://baas-api.c6bank.info`
+
+Sandbox is available **Monday–Friday, 07:00–22:00 BRT**. Tokens expire after about **10 minutes of inactivity**.
+
+Official portal: [developers.c6bank.com.br](https://developers.c6bank.com.br/get-started)
+
+## Requirements
+
+- Ruby >= 3.2 (developed on 3.4.7)
+- C6 `client_id` + `client_secret`
+- mTLS certificate + private key issued by C6 for this client
+- For Pix / Bolepix QR: an **EVP (random) Pix key** registered on the C6 account
+
+Bolepix only generates a QR Code when `payment_method.pix` is sent with `type: "EVP"` and a key C6 already knows. Other key types (CPF, e-mail, phone) are accepted by the standalone Pix API, not by Bolepix.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "c6_bank"
+```
+
+```bash
+bundle install
+```
+
+Until this gem is published, point Bundler at the repo:
+
+```ruby
+gem "c6_bank", path: "../se_six_ruby"
+```
+
+## Configure with environment variables
+
+Copy `.env.example` to `.env` (gitignored) and fill in values from the C6 portal. **Never commit secrets or certificates.**
+
+```bash
+C6_ENV=sandbox
+C6_CLIENT_ID=...
+C6_CLIENT_SECRET=...
+C6_PIX_KEY=...          # EVP random key, required for Pix QR
+C6_CERT_PATH=/secure/path/c6.crt
+C6_KEY_PATH=/secure/path/c6.key
+C6_PARTNER_SOFTWARE_NAME=MyERP
+C6_PARTNER_SOFTWARE_VERSION=1.0.0
+```
+
+```ruby
+require "c6_bank"
+
+client = C6Bank::Client.from_env
+client.authenticate!
+puts client.scope
+# e.g. "bankslip.write webhook.read pix.read webhook.write pix.write bankslip.read"
+```
+
+Or configure explicitly:
+
+```ruby
+C6Bank.configure do |c|
+  c.client_id = ENV.fetch("C6_CLIENT_ID")
+  c.client_secret = ENV.fetch("C6_CLIENT_SECRET")
+  c.pix_key = ENV.fetch("C6_PIX_KEY")
+  c.certificate_path = ENV.fetch("C6_CERT_PATH")
+  c.private_key_path = ENV.fetch("C6_KEY_PATH")
+  c.environment = :sandbox # or :production
+  c.partner_software_name = "MyERP"
+  c.partner_software_version = "1.0.0"
+end
+
+C6Bank.boletos.create(...)
+C6Bank.pix.create_immediate_charge(amount: "10.00")
+```
+
+`environment` selects the host **and** the Bolepix wallet (`billing_scheme`): `"21"` in sandbox, `"15"` in production.
+
+## Authentication
+
+Every call, including the token request, uses **mutual TLS**. The gem:
+
+1. Presents your client certificate + key
+2. Posts `application/x-www-form-urlencoded` `grant_type=client_credentials` to `/v1/auth`
+3. Sends `Authorization: Bearer …` on resource calls
+4. Refreshes the token on expiry and retries once on HTTP 401
+
+If the certificate `Not After` date is in the past, the gem prints a warning. C6 will typically reject the handshake until you replace the pair.
+
+## Bolepix — boleto + Pix in one charge
+
+This is the usual receivables flow. When `pix_key` is configured, Pix is attached automatically.
+
+```ruby
+req = C6Bank.boleto_request(
+  amount: 150.75,
+  due_date: "2026-10-20",
+  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_type: "FIXED_VALUE",
+  fine_value: 10,
+  fine_deadline: 5,
+  interest_type: "VALUE_PER_DAY",
+  interest_value: 0.5,
+  interest_deadline: 1
+)
+
+req.bank_slip(instructions: ["Nao receber apos o vencimento"])
+# req.without_pix  # opt out of the QR Code
+
+charge = client.boletos.create(req)
+
+charge["external_reference_id"]
+charge.dig("payment_method", "bank_slip", "digitable_line")
+charge.dig("payment_method", "pix", "qr_code")        # EMV / copia-e-cola
+charge.dig("payment_method", "pix", "image_content")  # Base64 PNG
+charge.dig("payment_method", "pix", "reference")
+```
+
+Other Bolepix operations:
+
+```ruby
+client.boletos.find(external_reference_id)
+client.boletos.list(due_date_from: "2026-09-01", due_date_to: "2026-09-30", status: "CREATED")
+client.boletos.update(external_reference_id, due_date: "2026-11-01")
+pdf = client.boletos.pdf(external_reference_id)
+client.boletos.cancel(external_reference_id)
+```
+
+`external_reference_id` is 26 uppercase `A-Z0-9` characters. The gem generates one when you omit it. Sending the same id twice returns the existing charge (idempotent).
+
+List requires at least one date range (`payment_date_*`, `due_date_*` or `credit_date_*`), max 60 days.
+
+If Pix data is missing on the response, C6 created the boleto but skipped QR generation: the key is not EVP, not registered, or was omitted.
+
+## Troubleshooting
+
+### `403` `mtls_error`
+
+C6 rejected the client certificate. Typical causes:
+
+- The `.crt` / `.key` pair expired (C6 sandbox certs are typically valid ~1 year)
+- The pair belongs to a **different** `client_id` than `C6_CLIENT_ID`
+- The files were issued for the other environment (sandbox vs production)
+
+Download a fresh pair from the same e-mail / portal message that contained the new `client_id` and `client_secret`, then point `C6_CERT_PATH` and `C6_KEY_PATH` at those files.
+
+The certificate currently in `docs/GabrielFDSCT/` expired on **2026-02-21** and will not authenticate.
+
+### Sandbox closed
+
+Auth and resource calls fail outside Monday–Friday 07:00–22:00 BRT.
+
+### Bolepix without QR Code
+
+`C6_PIX_KEY` must be an **EVP (random UUID) key** already registered on the C6 account. CPF / e-mail / phone keys work on `/v2/pix` cob charges, not on Bolepix QR generation.
+
+## Pix — standalone cob / cobv
+
+C6's Pix API follows BACEN Pix v2 (`/v2/pix`). Field names in the HTTP body are the official ones (`chave`, `calendario`, `valor.original`, `pixCopiaECola`). The gem also accepts Ruby-friendly aliases (`amount`, `due_date`, `expiration`, `pix_key`).
+
+### Immediate charge (cob)
+
+```ruby
+# Bank generates txid
+cob = client.pix.create_immediate_charge(
+  amount: "37.00",
+  expiration: 3600, # seconds
+  devedor: { cpf: "12345678909", nome: "Fulano de Tal" },
+  solicitacaoPagador: "Servico prestado"
+)
+
+cob["txid"]
+cob["pixCopiaECola"]
+cob["status"] # ATIVA, CONCLUIDA, ...
+
+# Or you choose txid (26–35 alphanumeric)
+client.pix.create_immediate_charge(
+  txid: C6Bank::Pix.generate_txid,
+  amount: "10.50",
+  expiration: 1800
+)
+
+client.pix.find_immediate(txid)
+client.pix.list_immediate(inicio: "2026-09-01T00:00:00Z", fim: "2026-09-18T23:59:59Z")
+client.pix.revise_immediate(txid, valor: { original: "40.00" })
+```
+
+### Due-date charge (cobv)
+
+```ruby
+cobv = client.pix.create_due_charge(
+  amount: "250.00",
+  due_date: "2026-10-20",
+  days_after_due: 30,
+  devedor: {
+    nome: "Fulano de Tal",
+    cpf: "12345678909",
+    logradouro: "Alameda Souza, 80",
+    cidade: "Recife",
+    uf: "PE",
+    cep: "70011750"
+  }
+)
+
+client.pix.find_due(cobv.fetch("txid"))
+client.pix.list_due(inicio: "2026-09-01T00:00:00Z", fim: "2026-09-30T23:59:59Z")
+```
+
+### Received Pix, refunds, webhook
+
+```ruby
+client.pix.list_received(inicio: "...", fim: "...")
+client.pix.received(e2eid)
+client.pix.refund(e2eid, refund_id, valor: "10.00")
+
+client.pix.configure_webhook(webhook_url: "https://example.com/webhooks/c6/pix")
+client.pix.webhook
+client.pix.delete_webhook
+```
+
+Webhook `PUT /v2/pix/webhook/{chave}` is called when a Pix **with txid** is received for that DICT key. Use HTTPS.
+
+## Rails
+
+See `docs/rails_initializer_example.rb`. Put the certificate files outside the git tree (or in an encrypted credential), for example `config/certs/` which you gitignore.
+
+```ruby
+# app/models/invoice.rb
+def issue_c6_charge!
+  req = C6Bank.boleto_request(
+    amount: amount.to_f,
+    due_date: due_on.iso8601,
+    description: "Fatura #{id}"
+  )
+  req.payer(name: customer.name, tax_id: customer.tax_id, address: customer.c6_address)
+  response = C6Bank.boletos.create(req)
+
+  update!(
+    c6_external_id: response["external_reference_id"],
+    linha_digitavel: response.dig("payment_method", "bank_slip", "digitable_line"),
+    pix_copia_e_cola: response.dig("payment_method", "pix", "qr_code")
+  )
+end
+```
+
+## Errors
+
+| Class | When |
+|---|---|
+| `C6Bank::ConfigurationError` | Missing credentials, certs, or Pix key |
+| `C6Bank::AuthenticationError` | Token call failed or HTTP 401 |
+| `C6Bank::NotFoundError` | HTTP 404 |
+| `C6Bank::RateLimitError` | HTTP 429 |
+| `C6Bank::ServerError` | HTTP 5xx |
+| `C6Bank::ApiError` | Other 4xx (`status` and `body` are on the exception) |
+
+## Try it against sandbox
+
+```bash
+cp .env.example .env   # then edit
+bundle exec ruby examples/live_sandbox.rb
+bundle exec ruby examples/boleto_cases.rb
+bundle exec ruby examples/pix_cases.rb
+bundle exec bin/console
+```
+
+OpenAPI dumps used to implement this gem live in `docs/openapi/` (`bolepix.yaml`, `pix-api.yaml`).
+
+## Homologation
+
+C6 asks partners to run the [Roteiro de Testes](https://developers.c6bank.com.br/get-started) and send evidence to `homologacaoapi@c6bank.com`. `docs/roteiro_mapping.md` maps those cases to gem methods.
+
+Production Bolepix wallet is **15**. Sandbox wallet is **21**.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## Security
+
+- Do not commit `.env`, `.crt`, `.key`, or real `client_secret` values.
+- If a secret was pasted into chat, e-mail, or a ticket, rotate it in the C6 portal.
+- Keep the mTLS certificate on disk with tight permissions (`chmod 600`).
+- Prefer Rails credentials / a secret manager in production over raw env files.
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/docs/NEXT_STEPS.md

@@ -0,0 +1,17 @@
+# Next steps
+
+The gem now targets the published C6 contracts:
+
+- Auth `POST /v1/auth`
+- Bolepix `/v2/bank_slips` (Pix QR when `pix_key` is an EVP key)
+- Pix `/v2/pix` (cob, cobv, webhooks)
+
+Use `.env` (see `.env.example`) and:
+
+```bash
+bundle exec ruby examples/live_sandbox.rb
+```
+
+If authentication fails, the usual cause is an expired or mismatched mTLS certificate — C6 issues a `.crt` + `.key` pair together with `client_id` / `client_secret`. Replace `C6_CERT_PATH` and `C6_KEY_PATH`.
+
+Homologation evidence: `docs/roteiro_mapping.md` + e-mail `homologacaoapi@c6bank.com`.