Skip to content

fix(celcoin): correct sandbox host and bill-payment routes - #215

Merged
dangazineu merged 1 commit into
mainfrom
fix/celcoin-billpayment-routes
Jul 5, 2026
Merged

fix(celcoin): correct sandbox host and bill-payment routes#215
dangazineu merged 1 commit into
mainfrom
fix/celcoin-billpayment-routes

Conversation

@dangazineu

Copy link
Copy Markdown
Contributor

The Celcoin sandbox host and the boleto/bill-payment routes had drifted from Celcoin's current API, so the bill-payment tools failed at runtime. The sandbox host sandbox-api.celcoin.com.br no longer resolves, read_barcode hit a GET route that returns 404, pay_bill sent a bare amount with no authorize reference (Celcoin rejects this with errorCode 44 "Valor nao permitido"), and create_boleto/get_boleto/cancel_boleto pointed at the bill-payment namespace instead of the bill-issuance product. This corrects the host and routes to match Celcoin's documented contract and adds tests that lock the request shapes in place.


What changed

  • Sandbox host: sandbox-api.celcoin.com.br (dead) → sandbox.openfinance.celcoin.dev, in src/index.ts and README.md. CELCOIN_SANDBOX stays the provider's own sandbox switch.
  • read_barcode: now POST /v5/transactions/billpayments/authorize with body { barCode: { type, digitable } } (type 1 = concessionária/utility, 2 = bank slip). The consult/reserve step; returns a transactionId that opens a reservation window.
  • pay_bill: keeps POST /v5/transactions/billpayments but sends the correct confirm body — externalNSU, cpfcnpj, transactionIdAuthorize (from authorize), billData (value, originalValue, valueWithDiscount, valueWithAdditional), barCode (type, digitable), dueDate. The input schema gained the fields callers need; transactionIdAuthorize is required.
  • create_boleto: POST /billissuance/v1/bill (real issuance) instead of the 404 bankslip route.
  • get_boleto / cancel_boleto: repointed at the bill-issuance product (GET/DELETE /billissuance/v1/bill/:id) with clarifying comments.
  • Version: 0.2.2 → 0.2.3 across package.json, server.json, and the hardcoded version: in index.ts (was 0.2.1 there) so the catalog audit stays consistent.
  • tsconfig: excludes src/__tests__ from the build (matches the mercado-pago package) so the new contract test's cross-package import does not break tsc.

Tests

  • src/__tests__/index.test.ts: unit tests for the authorize route + body, the confirm body carrying transactionIdAuthorize/cpfcnpj/billData/externalNSU (regression guard for errorCode 44), the /billissuance/v1/bill issuance route, the get/cancel routes, and the sandbox host. The existing "18 tools" assertion still holds — no tools added.
  • src/__tests__/contract.test.ts: a live authorize→confirm handshake gated on CELCOIN_CLIENT_ID, skipped in CI (no creds) and runnable locally against the sandbox.

npm test (repo root): 147 passed, 32 skipped. Celcoin package: 12 passed, 1 skipped. Catalog audit: 0 HIGH findings.

Follow-up

Publishing @codespar/mcp-celcoin@0.2.3 to npm is a separate follow-up dispatch; the version bump here is consistent across package.json, server.json, and index.ts so the manual publish workflow will pick it up.

Notes on verification

  • The read_barcode authorize contract and create_boleto issuance route (/billissuance/v1/bill) are confirmed against the current Celcoin developer docs.
  • The pay_bill confirm body matches the corrected field set; the exact get_boleto/cancel_boleto cancel semantics under billissuance were inferred from the query-by-id route and are annotated with comments — they should be confirmed against a live sandbox account before relying on the cancel path.

The Celcoin sandbox host and the boleto/bill-payment routes had drifted from
Celcoin's current API, so the bill-payment tools failed at runtime. The
sandbox host sandbox-api.celcoin.com.br no longer resolves, read_barcode hit a
GET route that returns 404, pay_bill sent a bare amount with no authorize
reference (Celcoin rejects this with errorCode 44 "Valor nao permitido"), and
create_boleto/get_boleto/cancel_boleto pointed at the bill-payment namespace
instead of the bill-issuance product. This corrects the host and routes to
match Celcoin's documented contract and adds tests that lock the request
shapes in place.

---

## What changed

- **Sandbox host**: `sandbox-api.celcoin.com.br` (dead) → `sandbox.openfinance.celcoin.dev`, in `src/index.ts` and `README.md`. `CELCOIN_SANDBOX` remains the provider's own sandbox switch.
- **read_barcode**: now `POST /v5/transactions/billpayments/authorize` with body `{ barCode: { type, digitable } }` (type 1 = concessionária/utility, 2 = bank slip). This is the consult/reserve step; it returns a `transactionId` that opens a reservation window.
- **pay_bill**: keeps `POST /v5/transactions/billpayments` but sends the correct confirm body — `externalNSU`, `cpfcnpj`, `transactionIdAuthorize` (from the authorize step), `billData` (`value`, `originalValue`, `valueWithDiscount`, `valueWithAdditional`), `barCode` (`type`, `digitable`), and `dueDate`. The input schema gained the fields callers need to pass, and `transactionIdAuthorize` is required.
- **create_boleto**: `POST /billissuance/v1/bill` (real issuance) instead of the 404 bill-payment bankslip route.
- **get_boleto / cancel_boleto**: repointed at the bill-issuance product (`GET`/`DELETE /billissuance/v1/bill/:id`) with clarifying comments; the bill-payment namespace has no issued-boleto lifecycle.
- **Version**: bumped 0.2.2 → 0.2.3 across `package.json`, `server.json`, and the hardcoded `version:` in `index.ts` (was 0.2.1 there) so the catalog audit stays consistent.
- **tsconfig**: excludes `src/__tests__` from the build (matches the mercado-pago package), so the new contract test's cross-package import does not break `tsc`.

## Tests

- `src/__tests__/index.test.ts`: added unit tests asserting the authorize route + body, the confirm body carrying `transactionIdAuthorize`/`cpfcnpj`/`billData`/`externalNSU` (a regression guard for errorCode 44), the `/billissuance/v1/bill` issuance route, the get/cancel routes, and the sandbox host. The existing "18 tools" assertion still holds — no tools were added.
- `src/__tests__/contract.test.ts`: a new live authorize→confirm handshake gated on `CELCOIN_CLIENT_ID`, skipped in CI (no creds) and runnable locally against the sandbox.

Tool count unchanged at 18; `npm test` passes (celcoin: 12 passed, 1 skipped).
@dangazineu
dangazineu marked this pull request as ready for review July 5, 2026 04:54
@dangazineu
dangazineu merged commit 66c6cef into main Jul 5, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant