fix(celcoin): correct sandbox host and bill-payment routes - #215
Merged
Conversation
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
marked this pull request as ready for review
July 5, 2026 04:54
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.brno longer resolves,read_barcodehit a GET route that returns 404,pay_billsent a bare amount with no authorize reference (Celcoin rejects this with errorCode 44 "Valor nao permitido"), andcreate_boleto/get_boleto/cancel_boletopointed 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-api.celcoin.com.br(dead) →sandbox.openfinance.celcoin.dev, insrc/index.tsandREADME.md.CELCOIN_SANDBOXstays the provider's own sandbox switch.POST /v5/transactions/billpayments/authorizewith body{ barCode: { type, digitable } }(type 1 = concessionária/utility, 2 = bank slip). The consult/reserve step; returns atransactionIdthat opens a reservation window.POST /v5/transactions/billpaymentsbut 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;transactionIdAuthorizeis required.POST /billissuance/v1/bill(real issuance) instead of the 404 bankslip route.GET/DELETE /billissuance/v1/bill/:id) with clarifying comments.package.json,server.json, and the hardcodedversion:inindex.ts(was 0.2.1 there) so the catalog audit stays consistent.src/__tests__from the build (matches the mercado-pago package) so the new contract test's cross-package import does not breaktsc.Tests
src/__tests__/index.test.ts: unit tests for the authorize route + body, the confirm body carryingtransactionIdAuthorize/cpfcnpj/billData/externalNSU(regression guard for errorCode 44), the/billissuance/v1/billissuance 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 onCELCOIN_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.3to npm is a separate follow-up dispatch; the version bump here is consistent acrosspackage.json,server.json, andindex.tsso the manual publish workflow will pick it up.Notes on verification
read_barcodeauthorize contract andcreate_boletoissuance route (/billissuance/v1/bill) are confirmed against the current Celcoin developer docs.pay_billconfirm body matches the corrected field set; the exactget_boleto/cancel_boletocancel semantics underbillissuancewere 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.