From 454331d2b5a9482c0327855fde0a7210033ecdd3 Mon Sep 17 00:00:00 2001 From: Fabiano Cruz Date: Wed, 11 Nov 2026 08:19:43 -0300 Subject: [PATCH 1/3] feat(sdk): executor under its public name, provider apart (sdk 0.16.29, enterprise#1983) OpenAPI snapshot refreshed to the served document (b9b057565a31, 390 operations) after enterprise#2564 (fdf6ecece, production 2026-11-11 03:33Z); src/generated regenerated. executor is codespar_simulator | provider_sandbox, executor_provider carries the provider, and consent/payment/receipt carry executor_label, environment and real_money. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01RmCN2L9X5C6vdDBLVJ5Fuq --- package-lock.json | 2 +- packages/core/CHANGELOG.md | 21 + packages/core/openapi-snapshot.json | 8670 +++++++++++++++++++-- packages/core/package.json | 2 +- packages/core/src/generated/openapi.ts | 4488 +++++++++-- packages/core/src/generated/operations.ts | 19 +- 6 files changed, 12012 insertions(+), 1190 deletions(-) diff --git a/package-lock.json b/package-lock.json index 6052586..ad5e335 100644 --- a/package-lock.json +++ b/package-lock.json @@ -3039,7 +3039,7 @@ }, "packages/core": { "name": "@codespar/sdk", - "version": "0.16.28", + "version": "0.16.29", "license": "MIT", "dependencies": { "@codespar/types": "^0.10.1 || ^0.11.0", diff --git a/packages/core/CHANGELOG.md b/packages/core/CHANGELOG.md index 4914bb5..a945958 100644 --- a/packages/core/CHANGELOG.md +++ b/packages/core/CHANGELOG.md @@ -1,5 +1,26 @@ # @codespar/sdk — CHANGELOG +## 0.16.29 — 2026-11-11 + +### Changed + +- **Executor under its public name (enterprise#1983).** In the generated types, `executor` is now `"codespar_simulator" | "provider_sandbox" | null` and `"celcoin_sandbox"` is gone from the enum. That covers `GET /v1/account/ledger`, `/payments` and `/sessions`, proposals, receipts, consents and the consumer payment response. An exhaustive `switch` that has a `"celcoin_sandbox"` case no longer compiles; read `"provider_sandbox"` instead. +- The concrete provider comes apart in `executor_provider` (`"celcoin" | null`). The server always resolves it, and the caller never chooses it. +- Consent, payment and receipt also carry `executor_label`, `environment` and `real_money`. In Test, `real_money` is always `false`, even when a sandbox confirmed with `moneyMoved: true`. +- `POST /v1/consents` and the consent submit can answer 400 `executor_provider_not_selectable` when the body names `provider` or `executor_provider`. +- Old records keep their stored value; the API reads them under the public name. +- The Charge (Collect) `issuer` and `payment.executor` are a separate contract and keep `celcoin_sandbox`. + +### Added + +- OpenAPI snapshot refreshed to the served document (b9b057565a31, 390 operations), and `src/generated/` regenerated from it. Besides the executor fields, it picks up what was served since 0.16.28: + - `/v1/ofb/sweeping` (7 operations); + - `/v1/ofb/jsr` (7 operations); + - `/v1/onboarding/first-receive` (GET, POST); + - `GET /v1/shop/agent/capabilities`. + + Only types and the operation table change; no handwritten method was added for them. + ## 0.16.28 — 2026-10-30 ### Added diff --git a/packages/core/openapi-snapshot.json b/packages/core/openapi-snapshot.json index 6a4b761..c1dbe9d 100644 --- a/packages/core/openapi-snapshot.json +++ b/packages/core/openapi-snapshot.json @@ -1,16 +1,16 @@ { "snapshot": { "source": "https://api.codespar.dev/openapi.json", - "fetched_at": "2026-10-31T00:54:41.356Z", - "sha256": "4ae3274e16aa0655cacab1b3a1f0c1fbe8ad710fe2c0184c9b0aa816fdd0095c", + "fetched_at": "2026-11-11T11:18:25.811Z", + "sha256": "b9b057565a31502b762e37b6c0c713984543f48a2425e34729bf1332afa34cfb", "etag": null, "last_modified": null, "info": { "title": "CodeSpar AgentGate API", "version": "0.3.0" }, - "paths": 317, - "operations": 373, + "paths": 329, + "operations": 390, "generator": "openapi-typescript@7.13.0" }, "document": { @@ -1045,7 +1045,71 @@ "format": "date-time" }, "routing": {}, - "failover_trail": {} + "failover_trail": {}, + "actor": { + "type": [ + "object", + "null" + ], + "properties": { + "via": { + "type": "string", + "enum": [ + "oauth", + "bearer", + "service" + ], + "description": "How the caller authenticated: an OAuth connection (an MCP client), an API key, or the platform's service key (the dashboard)." + }, + "client_name_declared": { + "type": [ + "string", + "null" + ], + "description": "On `oauth`: the name the OAuth client declared about itself at dynamic registration. Self-declared, never verified." + }, + "client_id_masked": { + "type": [ + "string", + "null" + ], + "description": "On `oauth`: the client id, last four characters only." + }, + "key_id_masked": { + "type": [ + "string", + "null" + ], + "description": "On `bearer`: the API key id, last four characters only." + } + }, + "required": [ + "via" + ], + "description": "Who triggered the call, as its authentication knew it (0408). Null when not recorded; never inferred from a mandate or a session." + }, + "agent": { + "type": [ + "object", + "null" + ], + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "id", + "name" + ], + "description": "The agent the call's session belongs to, when the session is a registered agent's. Null on the shared remote-MCP session, whose callers are told apart by `actor`, never by a mandate's agent." + } }, "required": [ "id", @@ -1667,6 +1731,52 @@ }, "adapter": { "type": "string" + }, + "executor": { + "type": [ + "string", + "null" + ], + "enum": [ + "codespar_simulator", + "provider_sandbox" + ], + "description": "Who executes (or executed) the payment, by the same name the integrator chooses with on POST /v1/consents. `codespar_simulator` (\"Simulado pela CodeSpar\": no provider is called) or `provider_sandbox` (the provider's sandbox, over the account the server bound to this consumer); both Test only. Null when no executor applies, Live included. The name is the MODE: the provider, account, project, consumer and environment are resolved by the server before the signature and checked again when the payment runs; no request field chooses them (`executor_provider_not_selectable`), and a provider failure is never turned into a simulation. Records written before this name existed keep their stored value and are read in these words." + }, + "executor_provider": { + "type": [ + "string", + "null" + ], + "enum": [ + "celcoin" + ], + "description": "The concrete provider behind `executor`, as the server resolved it: `celcoin` for `provider_sandbox`; null for `codespar_simulator` (no provider is called) and when `executor` is null. Read-only." + }, + "executor_label": { + "type": [ + "string", + "null" + ], + "description": "The executor's label as the consent screen, the dashboard and the receipt show it. In Test it ends \"· sem dinheiro real\"." + }, + "environment": { + "type": [ + "string", + "null" + ], + "enum": [ + "test", + "live" + ], + "description": "The project's environment." + }, + "real_money": { + "type": [ + "boolean", + "null" + ], + "description": "False in Test, always: no real money moves, including when the provider's sandbox CONFIRMED the operation (`moneyMoved: true` / `settlement: \"confirmed\"` then mean the sandbox settled it). True in Live." } }, "required": [ @@ -1676,7 +1786,12 @@ "rail", "provider", "moneyMoved", - "adapter" + "adapter", + "executor", + "executor_provider", + "executor_label", + "environment", + "real_money" ] }, "wallet": { @@ -4324,7 +4439,7 @@ "minLength": 1, "maxLength": 128, "pattern": "^[a-z0-9_]+(\\.[a-z0-9_]+)*$", - "description": "The event type to subscribe to. Matching is EXACT string equality — there is no prefix and no wildcard, so `commerce.payment.succeeded` does not receive `commerce.payment.received`. A name outside the list below is accepted and recorded (`trigger.event_unknown`) rather than refused, so you can subscribe ahead of a release; until something emits it the subscription simply never fires. What this build emits: account_binding.closed, agent_autonomy.changed, approval.decided, approval.pending, collect.attempt.cancelled, collect.attempt.expired, collect.attempt.failed, collect.attempt.issued, collect.attempt.ready, collect.attempt.superseded, collect.link.archived, collect.link.paused, collect.link.published, collect.payment.exception, collect.payment.paid, collect.refund.awaiting_decision, collect.refund.honored, collect.refund.required, commerce.account_entry_credit.received, commerce.account_entry_debit.received, commerce.account_launch_in.received, commerce.account_launch_out.received, commerce.account_status.changed, commerce.cashout.confirmed, commerce.charge.cancelled, commerce.charge.created, commerce.charge.expired, commerce.charge.expiry_notified, commerce.charge.paid, commerce.charge.payment_notified, commerce.dict_claim.cancelled, commerce.dict_claim.completed, commerce.dict_claim.confirmed, commerce.dict_claim.opened, commerce.dict_claim.waiting, commerce.internal_transfer_in.received, commerce.internal_transfer_out.received, commerce.mandate.expiring, commerce.mandate.granted, commerce.mandate.paused, commerce.mandate.resumed, commerce.mandate.revoked, commerce.onboarding.backgroundcheck_approved, commerce.onboarding.backgroundcheck_pending, commerce.onboarding.backgroundcheck_rejected, commerce.onboarding.documentscopy_approved, commerce.onboarding.documentscopy_pending, commerce.onboarding.documentscopy_processing, commerce.onboarding.documentscopy_rejected, commerce.onboarding.proposal_approved, commerce.onboarding.proposal_processing_documentscopy, commerce.onboarding.proposal_rejected, commerce.organization.paused, commerce.organization.resumed, commerce.payment.failed, commerce.payment.pending, commerce.payment.received, commerce.payment.refunded, commerce.payment.succeeded, commerce.payment.updated, commerce.pix_out.failed, commerce.pix_out.succeeded, commerce.pix_out.unconfirmed, commerce.pix_reversal_in.received, commerce.pix_reversal_out.received, commerce.recurrence.authorized, commerce.recurrence.cancelled, commerce.recurrence.cycle.accepted, commerce.recurrence.cycle.announced_late, commerce.recurrence.cycle.awaiting_instruction, commerce.recurrence.cycle.cancelled, commerce.recurrence.cycle.expired, commerce.recurrence.cycle.instruction_blocked, commerce.recurrence.cycle.instruction_missing, commerce.recurrence.cycle.instruction_refused, commerce.recurrence.cycle.paid, commerce.recurrence.cycle.queued_instruction_expired, commerce.recurrence.cycle.rejected, commerce.recurrence.cycle.scheduled, commerce.recurrence.cycle.settled_by_held_credit, commerce.recurrence.denied, commerce.recurrence.requested, commerce.recurrence.settlement_held, commerce.recurrence.settlement_hold_overdue, commerce.recurrence.settlement_hold_resolved, commerce.recurrence.settlement_possible_double_credit, commerce.rinne.observed, commerce.spend.failed, commerce.spend.settled, commerce.ted_in.succeeded, dda.boleto.registered, dda.subscription.activated, dda.subscription.failed, gate.paywall.charged, payable.batch.completed, payable.batch.item_executed, payable.batch.item_refused, payable.rejected, project.archived, project.unarchived, proxy_call.failed, proxy_call.succeeded, sandbox.provisioning.account_bound, sandbox.provisioning.initial_credit, sandbox.provisioning.resumed, session.closed, space_credential_revocation.requested, spaces_consent.accepted, spaces_customer_account.resumed, spaces_customer_account.suspended, system.health.degraded, system.health.recovered, tool_call.failed, tool_call.succeeded, trigger.delivery.failed, trigger.paused_automatically, trigger.test_fire, user.signed_up, wallet.balance.below." + "description": "The event type to subscribe to. Matching is EXACT string equality — there is no prefix and no wildcard, so `commerce.payment.succeeded` does not receive `commerce.payment.received`. A name outside the list below is accepted and recorded (`trigger.event_unknown`) rather than refused, so you can subscribe ahead of a release; until something emits it the subscription simply never fires. What this build emits: account_binding.closed, agent_autonomy.changed, api_key.mandate_bound, api_key.mandate_unbound, approval.decided, approval.pending, collect.attempt.cancelled, collect.attempt.expired, collect.attempt.failed, collect.attempt.issued, collect.attempt.ready, collect.attempt.superseded, collect.link.archived, collect.link.paused, collect.link.published, collect.payment.exception, collect.payment.paid, collect.refund.awaiting_decision, collect.refund.honored, collect.refund.required, commerce.account_entry_credit.received, commerce.account_entry_debit.received, commerce.account_launch_in.received, commerce.account_launch_out.received, commerce.account_status.changed, commerce.cashout.confirmed, commerce.charge.cancelled, commerce.charge.created, commerce.charge.expired, commerce.charge.expiry_notified, commerce.charge.failed, commerce.charge.paid, commerce.charge.payment_notified, commerce.charge.payment_received, commerce.dict_claim.cancelled, commerce.dict_claim.completed, commerce.dict_claim.confirmed, commerce.dict_claim.opened, commerce.dict_claim.waiting, commerce.internal_transfer_in.received, commerce.internal_transfer_out.received, commerce.mandate.expiring, commerce.mandate.granted, commerce.mandate.paused, commerce.mandate.resumed, commerce.mandate.revoked, commerce.onboarding.backgroundcheck_approved, commerce.onboarding.backgroundcheck_pending, commerce.onboarding.backgroundcheck_rejected, commerce.onboarding.documentscopy_approved, commerce.onboarding.documentscopy_pending, commerce.onboarding.documentscopy_processing, commerce.onboarding.documentscopy_rejected, commerce.onboarding.proposal_approved, commerce.onboarding.proposal_processing_documentscopy, commerce.onboarding.proposal_rejected, commerce.organization.paused, commerce.organization.resumed, commerce.payment.failed, commerce.payment.pending, commerce.payment.received, commerce.payment.refunded, commerce.payment.succeeded, commerce.payment.updated, commerce.pix_out.failed, commerce.pix_out.succeeded, commerce.pix_out.unconfirmed, commerce.pix_reversal_in.received, commerce.pix_reversal_out.received, commerce.recurrence.authorized, commerce.recurrence.cancelled, commerce.recurrence.cycle.accepted, commerce.recurrence.cycle.announced_late, commerce.recurrence.cycle.awaiting_instruction, commerce.recurrence.cycle.cancelled, commerce.recurrence.cycle.expired, commerce.recurrence.cycle.instruction_blocked, commerce.recurrence.cycle.instruction_missing, commerce.recurrence.cycle.instruction_refused, commerce.recurrence.cycle.paid, commerce.recurrence.cycle.queued_instruction_expired, commerce.recurrence.cycle.rejected, commerce.recurrence.cycle.scheduled, commerce.recurrence.cycle.settled_by_held_credit, commerce.recurrence.denied, commerce.recurrence.requested, commerce.recurrence.settlement_held, commerce.recurrence.settlement_hold_overdue, commerce.recurrence.settlement_hold_resolved, commerce.recurrence.settlement_possible_double_credit, commerce.rinne.observed, commerce.spend.failed, commerce.spend.settled, commerce.ted_in.succeeded, dda.boleto.registered, dda.subscription.activated, dda.subscription.failed, gate.paywall.charged, payable.batch.completed, payable.batch.item_executed, payable.batch.item_refused, payable.rejected, project.archived, project.unarchived, proxy_call.failed, proxy_call.succeeded, sandbox.provisioning.account_bound, sandbox.provisioning.initial_credit, sandbox.provisioning.pix_key_registered, sandbox.provisioning.resumed, session.closed, space_credential_revocation.requested, spaces_consent.accepted, spaces_customer_account.resumed, spaces_customer_account.suspended, system.health.degraded, system.health.recovered, tool_call.failed, tool_call.succeeded, trigger.delivery.failed, trigger.paused_automatically, trigger.test_fire, user.signed_up, wallet.balance.below." }, "server_id": { "type": "string", @@ -4706,7 +4821,7 @@ "minLength": 1, "maxLength": 128, "pattern": "^[a-z0-9_]+(\\.[a-z0-9_]+)*$", - "description": "The event type to subscribe to. Matching is EXACT string equality — there is no prefix and no wildcard, so `commerce.payment.succeeded` does not receive `commerce.payment.received`. A name outside the list below is accepted and recorded (`trigger.event_unknown`) rather than refused, so you can subscribe ahead of a release; until something emits it the subscription simply never fires. What this build emits: account_binding.closed, agent_autonomy.changed, approval.decided, approval.pending, collect.attempt.cancelled, collect.attempt.expired, collect.attempt.failed, collect.attempt.issued, collect.attempt.ready, collect.attempt.superseded, collect.link.archived, collect.link.paused, collect.link.published, collect.payment.exception, collect.payment.paid, collect.refund.awaiting_decision, collect.refund.honored, collect.refund.required, commerce.account_entry_credit.received, commerce.account_entry_debit.received, commerce.account_launch_in.received, commerce.account_launch_out.received, commerce.account_status.changed, commerce.cashout.confirmed, commerce.charge.cancelled, commerce.charge.created, commerce.charge.expired, commerce.charge.expiry_notified, commerce.charge.paid, commerce.charge.payment_notified, commerce.dict_claim.cancelled, commerce.dict_claim.completed, commerce.dict_claim.confirmed, commerce.dict_claim.opened, commerce.dict_claim.waiting, commerce.internal_transfer_in.received, commerce.internal_transfer_out.received, commerce.mandate.expiring, commerce.mandate.granted, commerce.mandate.paused, commerce.mandate.resumed, commerce.mandate.revoked, commerce.onboarding.backgroundcheck_approved, commerce.onboarding.backgroundcheck_pending, commerce.onboarding.backgroundcheck_rejected, commerce.onboarding.documentscopy_approved, commerce.onboarding.documentscopy_pending, commerce.onboarding.documentscopy_processing, commerce.onboarding.documentscopy_rejected, commerce.onboarding.proposal_approved, commerce.onboarding.proposal_processing_documentscopy, commerce.onboarding.proposal_rejected, commerce.organization.paused, commerce.organization.resumed, commerce.payment.failed, commerce.payment.pending, commerce.payment.received, commerce.payment.refunded, commerce.payment.succeeded, commerce.payment.updated, commerce.pix_out.failed, commerce.pix_out.succeeded, commerce.pix_out.unconfirmed, commerce.pix_reversal_in.received, commerce.pix_reversal_out.received, commerce.recurrence.authorized, commerce.recurrence.cancelled, commerce.recurrence.cycle.accepted, commerce.recurrence.cycle.announced_late, commerce.recurrence.cycle.awaiting_instruction, commerce.recurrence.cycle.cancelled, commerce.recurrence.cycle.expired, commerce.recurrence.cycle.instruction_blocked, commerce.recurrence.cycle.instruction_missing, commerce.recurrence.cycle.instruction_refused, commerce.recurrence.cycle.paid, commerce.recurrence.cycle.queued_instruction_expired, commerce.recurrence.cycle.rejected, commerce.recurrence.cycle.scheduled, commerce.recurrence.cycle.settled_by_held_credit, commerce.recurrence.denied, commerce.recurrence.requested, commerce.recurrence.settlement_held, commerce.recurrence.settlement_hold_overdue, commerce.recurrence.settlement_hold_resolved, commerce.recurrence.settlement_possible_double_credit, commerce.rinne.observed, commerce.spend.failed, commerce.spend.settled, commerce.ted_in.succeeded, dda.boleto.registered, dda.subscription.activated, dda.subscription.failed, gate.paywall.charged, payable.batch.completed, payable.batch.item_executed, payable.batch.item_refused, payable.rejected, project.archived, project.unarchived, proxy_call.failed, proxy_call.succeeded, sandbox.provisioning.account_bound, sandbox.provisioning.initial_credit, sandbox.provisioning.resumed, session.closed, space_credential_revocation.requested, spaces_consent.accepted, spaces_customer_account.resumed, spaces_customer_account.suspended, system.health.degraded, system.health.recovered, tool_call.failed, tool_call.succeeded, trigger.delivery.failed, trigger.paused_automatically, trigger.test_fire, user.signed_up, wallet.balance.below." + "description": "The event type to subscribe to. Matching is EXACT string equality — there is no prefix and no wildcard, so `commerce.payment.succeeded` does not receive `commerce.payment.received`. A name outside the list below is accepted and recorded (`trigger.event_unknown`) rather than refused, so you can subscribe ahead of a release; until something emits it the subscription simply never fires. What this build emits: account_binding.closed, agent_autonomy.changed, api_key.mandate_bound, api_key.mandate_unbound, approval.decided, approval.pending, collect.attempt.cancelled, collect.attempt.expired, collect.attempt.failed, collect.attempt.issued, collect.attempt.ready, collect.attempt.superseded, collect.link.archived, collect.link.paused, collect.link.published, collect.payment.exception, collect.payment.paid, collect.refund.awaiting_decision, collect.refund.honored, collect.refund.required, commerce.account_entry_credit.received, commerce.account_entry_debit.received, commerce.account_launch_in.received, commerce.account_launch_out.received, commerce.account_status.changed, commerce.cashout.confirmed, commerce.charge.cancelled, commerce.charge.created, commerce.charge.expired, commerce.charge.expiry_notified, commerce.charge.failed, commerce.charge.paid, commerce.charge.payment_notified, commerce.charge.payment_received, commerce.dict_claim.cancelled, commerce.dict_claim.completed, commerce.dict_claim.confirmed, commerce.dict_claim.opened, commerce.dict_claim.waiting, commerce.internal_transfer_in.received, commerce.internal_transfer_out.received, commerce.mandate.expiring, commerce.mandate.granted, commerce.mandate.paused, commerce.mandate.resumed, commerce.mandate.revoked, commerce.onboarding.backgroundcheck_approved, commerce.onboarding.backgroundcheck_pending, commerce.onboarding.backgroundcheck_rejected, commerce.onboarding.documentscopy_approved, commerce.onboarding.documentscopy_pending, commerce.onboarding.documentscopy_processing, commerce.onboarding.documentscopy_rejected, commerce.onboarding.proposal_approved, commerce.onboarding.proposal_processing_documentscopy, commerce.onboarding.proposal_rejected, commerce.organization.paused, commerce.organization.resumed, commerce.payment.failed, commerce.payment.pending, commerce.payment.received, commerce.payment.refunded, commerce.payment.succeeded, commerce.payment.updated, commerce.pix_out.failed, commerce.pix_out.succeeded, commerce.pix_out.unconfirmed, commerce.pix_reversal_in.received, commerce.pix_reversal_out.received, commerce.recurrence.authorized, commerce.recurrence.cancelled, commerce.recurrence.cycle.accepted, commerce.recurrence.cycle.announced_late, commerce.recurrence.cycle.awaiting_instruction, commerce.recurrence.cycle.cancelled, commerce.recurrence.cycle.expired, commerce.recurrence.cycle.instruction_blocked, commerce.recurrence.cycle.instruction_missing, commerce.recurrence.cycle.instruction_refused, commerce.recurrence.cycle.paid, commerce.recurrence.cycle.queued_instruction_expired, commerce.recurrence.cycle.rejected, commerce.recurrence.cycle.scheduled, commerce.recurrence.cycle.settled_by_held_credit, commerce.recurrence.denied, commerce.recurrence.requested, commerce.recurrence.settlement_held, commerce.recurrence.settlement_hold_overdue, commerce.recurrence.settlement_hold_resolved, commerce.recurrence.settlement_possible_double_credit, commerce.rinne.observed, commerce.spend.failed, commerce.spend.settled, commerce.ted_in.succeeded, dda.boleto.registered, dda.subscription.activated, dda.subscription.failed, gate.paywall.charged, payable.batch.completed, payable.batch.item_executed, payable.batch.item_refused, payable.rejected, project.archived, project.unarchived, proxy_call.failed, proxy_call.succeeded, sandbox.provisioning.account_bound, sandbox.provisioning.initial_credit, sandbox.provisioning.pix_key_registered, sandbox.provisioning.resumed, session.closed, space_credential_revocation.requested, spaces_consent.accepted, spaces_customer_account.resumed, spaces_customer_account.suspended, system.health.degraded, system.health.recovered, tool_call.failed, tool_call.succeeded, trigger.delivery.failed, trigger.paused_automatically, trigger.test_fire, user.signed_up, wallet.balance.below." }, "server_id": { "type": "string", @@ -6176,7 +6291,7 @@ }, "/v1/wallets/{id}/ledger": { "post": { - "description": "Post a ledger entry. Admin role. Idempotent on (wallet_id, attempt_id, kind) and (wallet_id, kind, external_ref). Returns 200 with the prior row on retry, 201 on fresh insert. `kind=fund` is accepted only in a test project; in a live project it is refused with 409 `fund_requires_test_project` and nothing is written, because a live wallet is credited only by a real Pix, TED or provider receipt.", + "description": "Post a ledger entry. Admin role. Idempotent on (wallet_id, attempt_id, kind) and (wallet_id, kind, external_ref). Returns 200 with the prior row on retry, 201 on fresh insert. `kind=fund` is accepted only in a test project; in a live project it is refused with 409 `fund_requires_test_project` and nothing is written, because a live wallet is credited only by a real Pix, TED or provider receipt. A `reverse` names the entry it reverses in `metadata.reverses` and a `release` the hold it releases in `metadata.hold_ref` (ledger ids of this wallet, same currency, with the sign that undoes it, and an `attempt_id`); without one it is refused with 400 `ledger_entry_reference_required`. In a live project a `reverse` that would raise the available balance is refused with 409 `reverse_requires_test_project`.", "parameters": [ { "schema": { @@ -6217,6 +6332,51 @@ } } }, + "400": { + "description": "A `reverse` or `release` that names no entry; nothing was written.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "ledger_entry_reference_required" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, "404": { "description": "Not Found", "content": { @@ -6239,7 +6399,7 @@ } }, "409": { - "description": "A `fund` in a live project, posted with an API key; nothing was written.", + "description": "A `fund`, or a `reverse` that would raise available, in a live project; a reverse or release whose named entry is not this wallet's or whose amount does not undo it; nothing was written.", "content": { "application/json": { "schema": { @@ -6251,7 +6411,12 @@ "code": { "type": "string", "enum": [ - "fund_requires_test_project" + "fund_requires_test_project", + "reverse_requires_test_project", + "ledger_entry_reference_invalid", + "ledger_entry_reference_mismatch", + "reverse_exceeds_original", + "hold_already_resolved" ] }, "message": { @@ -7156,7 +7321,7 @@ "/v1/account/balances": { "get": { "summary": "Account balances, per currency", - "description": "The sum of the balance caches of every non-closed wallet in the caller's project, one row per currency. `held_minor` is `balance_minor − available_minor`, the money open holds reserve. `open_holds` counts HOLD entries that no release or debit settles yet, paired by `metadata.hold_ref`, by `withdrawal_id` for owner withdrawals, or by `attempt_id` — the same pairing the hold sweeper uses.\n\nScoped to the organization AND the project: another project's wallets are in no sum.", + "description": "The sum of the balance caches of every non-closed wallet in the caller's project, one row per currency. `held_minor` is `balance_minor − available_minor`, the money open holds reserve. `open_holds` counts HOLD entries that no release or debit settles yet, paired by `metadata.hold_ref`, by `withdrawal_id` for owner withdrawals, or by `attempt_id` — the same pairing the hold sweeper uses.\n\n`currencies` is the ACCOUNT's money (`account`): every wallet in Live and where the own Test account rule does not apply; that account's wallet for a Test project with its own bound account; none (an empty list, never a zero) for a Test project the rule reaches with no account yet. The simulator's residue there is `simulator_legacy`, apart, with its totals.\n\nScoped to the organization AND the project: another project's wallets are in no sum.", "responses": { "200": { "description": "OK", @@ -7168,6 +7333,70 @@ "project_id": { "type": "string" }, + "usdc_accounts": { + "type": "array", + "items": { + "type": "object", + "properties": { + "wallet_id": { + "type": "string" + }, + "display_name": { + "type": "string" + }, + "network": { + "type": "string", + "enum": [ + "base", + "base-sepolia" + ] + }, + "address": { + "type": [ + "string", + "null" + ] + }, + "state": { + "type": "string", + "enum": [ + "queued", + "syncing", + "ready", + "needs_attention" + ] + }, + "faucet": { + "type": [ + "string", + "null" + ] + }, + "reason": { + "type": [ + "string", + "null" + ] + }, + "checked_at": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "wallet_id", + "network", + "address", + "state", + "faucet", + "reason", + "checked_at" + ] + }, + "description": "Managed USDC addresses for the wallets included in this account's balance; absent on older APIs." + }, "currencies": { "type": "array", "items": { @@ -7179,7 +7408,7 @@ "balance_minor": { "type": "string", "pattern": "^-?\\d+$", - "description": "Σ wallet_balances.balance_minor over the project's non-closed wallets; for a Test project with its own bound account, over that account's wallet only (the simulator's legacy balance stays in the ledger, out of the sum)." + "description": "Σ wallet_balances.balance_minor over the ACCOUNT's non-closed wallets: every wallet of the project in Live and where `account.applies` is false; for a Test project with its own bound account, that account's wallet only." }, "available_minor": { "type": "string", @@ -7203,7 +7432,106 @@ "held_minor", "open_holds" ] - } + }, + "description": "The account's money only. Empty when `account.exists` is false (a Test project with no own account yet): the simulator's residue is never presented as the account's balance, nor as a zero one; it is in `simulator_legacy`." + }, + "account": { + "type": "object", + "properties": { + "applies": { + "type": "boolean", + "description": "The own Test account rule reaches this project: Test, the switch reaching its org, not a proof project." + }, + "exists": { + "type": "boolean", + "description": "There is an account whose money `currencies` shows. False only where the rule applies and no account is bound yet." + }, + "wallet_ids": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The wallets `currencies` sums: the source of this figure. Another answer naming one of these wallets (the Shop chat's `wallet_id`) reads the same money; one naming another wallet reads another source, never to be added to this one." + }, + "consumer_id": { + "type": [ + "string", + "null" + ], + "description": "With its own bound account: that account's consumer. Null otherwise." + }, + "funding_source_id": { + "type": [ + "string", + "null" + ], + "description": "With its own bound account: that account's funding source. Null otherwise." + } + }, + "required": [ + "applies", + "exists", + "wallet_ids", + "consumer_id", + "funding_source_id" + ], + "description": "Which money `currencies` is (Fabiano 21/10, 02/11): the same cut as the ledger's running balance and the statement document." + }, + "simulator_legacy": { + "type": [ + "object", + "null" + ], + "properties": { + "origin": { + "type": "string", + "enum": [ + "simulator" + ] + }, + "wallet_ids": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The wallets of the residue: its source, apart from `account.wallet_ids`." + }, + "currencies": { + "type": "array", + "items": { + "type": "object", + "properties": { + "currency": { + "type": "string" + }, + "balance_minor": { + "type": "string", + "pattern": "^-?\\d+$" + }, + "available_minor": { + "type": "string", + "pattern": "^-?\\d+$" + }, + "held_minor": { + "type": "string", + "pattern": "^-?\\d+$" + } + }, + "required": [ + "currency", + "balance_minor", + "available_minor", + "held_minor" + ] + } + } + }, + "required": [ + "origin", + "wallet_ids", + "currencies" + ], + "description": "Where the rule applies: the project's other wallets (the simulator's residue, its legacy test funding among it), per currency, apart from the account's. Detail to consult, never available money of the account. Null where the rule does not apply or there is none. No entry is changed." }, "as_of": { "type": "string", @@ -7213,6 +7541,8 @@ "required": [ "project_id", "currencies", + "account", + "simulator_legacy", "as_of" ] } @@ -7233,7 +7563,7 @@ "/v1/account/ledger": { "get": { "summary": "The project's ledger, every wallet merged", - "description": "Every ledger entry of every wallet in the caller's project (closed wallets included: the ledger is history), newest first by entry id. Page with `before` set to the previous page's `next_before`; `next_before` is null on the last page.\n\n`hold_ref` returns that hold and every release, debit and fee that settles it — an id that is not a hold of this project returns no entries.\n\n`category` returns the entries stamped with that spend category at write time: `recebivel` on money received, `fornecedor` on a payable's payment, `compra` on a codespar_shop purchase, and otherwise what the agent declared on codespar_pay. It is never inferred from the description, so an entry no writer categorised is in no category and is listed only without the filter.\n\n`source` and `phase` are the writer's own stamps, as written: they name an entry no writer described, e.g. `consumer-payments` + `settle-fund` is a payment's settlement FUND. A phase is only unique within its source; both are open vocabularies and null where unstamped.\n\n`proposal_id` is the payment proposal the entry was booked for: a pay proposal's, read from its attempt id (`_t_hold|_debit`); a receive proposal's, on the FUND of the Pix charge it sent. Only when that proposal is in this org and project; the `proposal_id` filter returns those entries.\n\n`reverses`, on a REVERSE entry, is the id of the entry it reverses when that entry is in this project; null on every other kind.\n\n`agent_id` is resolved through the entry's consumer mandate, else, on the FUND of a Pix charge a receive proposal sent, that proposal's agent, else the wallet's agent. `balance_after_minor` is the running BOOKED balance of the project in the entry's currency, over every entry and not only the filtered ones: holds and releases leave it unchanged, as they leave `balance_minor` unchanged. At the newest entry it equals the sum of `balance_minor` over the project's wallets in that currency.", + "description": "Every ledger entry of every wallet in the caller's project (closed wallets included: the ledger is history), newest first by entry id. Page with `before` set to the previous page's `next_before`; `next_before` is null on the last page.\n\n`hold_ref` returns that hold and every release, debit and fee that settles it — an id that is not a hold of this project returns no entries.\n\n`category` returns the entries stamped with that spend category at write time: `recebivel` on money received, `fornecedor` on a payable's payment, `compra` on a codespar_shop purchase, and otherwise what the agent declared on codespar_pay. It is never inferred from the description, so an entry no writer categorised is in no category and is listed only without the filter.\n\n`source` and `phase` are the writer's own stamps, as written: they name an entry no writer described, e.g. `consumer-payments` + `settle-fund` is a payment's settlement FUND. A phase is only unique within its source; both are open vocabularies and null where unstamped.\n\n`proposal_id` is the payment proposal the entry was booked for: a pay proposal's, read from its attempt id (`_t_hold|_debit`); a receive proposal's, on the FUND of the Pix charge it sent. Only when that proposal is in this org and project; the `proposal_id` filter returns those entries.\n\n`reverses`, on a REVERSE entry, is the id of the entry it reverses when that entry is in this project; null on every other kind.\n\n`agent_id` is resolved through the entry's consumer mandate, else, on the FUND of a Pix charge a receive proposal sent, that proposal's agent, else the wallet's agent. `balance_after_minor` is the running BOOKED balance in the entry's currency over the same wallets as GET /v1/account/balances, over every entry and not only the filtered ones: holds and releases leave it unchanged, as they leave `balance_minor` unchanged. At the newest entry it equals the sum of `balance_minor` over those wallets. For a Test project with its own bound account only that account's wallet counts, and for one with no account yet none does: an entry of another wallet (the simulator's, its legacy test funding among it) is listed with its origin, `outside_account_balance` true, and the simulator's own running balance at that point.", "parameters": [ { "schema": { @@ -7529,14 +7859,89 @@ ], "enum": [ "codespar_simulator", - "celcoin_sandbox" + "provider_sandbox" + ], + "description": "\"codespar_simulator\" on the hold and the debit of a demonstration payment, settled on the CodeSpar simulator (\"Simulado pela CodeSpar\"); \"provider_sandbox\" on those of a payment made at a provider's sandbox (`executor_provider` names it); null on every other entry. Test only: no real money either way." + }, + "executor_provider": { + "type": [ + "string", + "null" + ], + "enum": [ + "celcoin" + ], + "description": "ent#1983: the concrete provider behind `executor` (\"celcoin\" for `provider_sandbox`), resolved by the server; null for the simulator and every other entry." + }, + "payee_name": { + "type": [ + "string", + "null" + ], + "description": "On a payment's DEBIT: who it credited. From what the provider answered about the destination when the money went out (`payee_name_source` `dict` or `credit_party`), else the merchant name a paid QR Code declared (`br_code`: the QR's own words, not a confirmed payee). Null otherwise, and on a payment sealed before the provider's answer was recorded: never inferred." + }, + "payee_name_source": { + "type": [ + "string", + "null" + ], + "enum": [ + "dict", + "credit_party", + "br_code" ], - "description": "\"codespar_simulator\" on the hold and the debit of a demonstration payment, settled on the CodeSpar simulator (\"Simulado pela CodeSpar\"); \"celcoin_sandbox\" on those of a payment of the restricted integrated proof, made at the Celcoin sandbox (\"Integrado (sandbox Celcoin)\"); null on every other entry." + "description": "Where `payee_name` came from." + }, + "triggered_by": { + "type": [ + "object", + "null" + ], + "properties": { + "via": { + "type": "string", + "enum": [ + "oauth", + "bearer", + "service" + ], + "description": "How the caller authenticated: an OAuth connection (an MCP client), an API key, or the platform's service key (the dashboard)." + }, + "client_name_declared": { + "type": [ + "string", + "null" + ], + "description": "On `oauth`: the name the OAuth client declared about itself at dynamic registration. Self-declared, never verified." + }, + "client_id_masked": { + "type": [ + "string", + "null" + ], + "description": "On `oauth`: the client id, last four characters only." + }, + "key_id_masked": { + "type": [ + "string", + "null" + ], + "description": "On `bearer`: the API key id, last four characters only." + } + }, + "required": [ + "via" + ], + "description": "On a payment's DEBIT: who triggered the tool call that made the payment (its `actor`, 0408), found by the call's own attempt or receipt id. Null when no recorded call matches: a payment from the dashboard's own buttons, or one made before 0408. Never filled in from the mandate's agent." }, "balance_after_minor": { "type": "string", "pattern": "^-?\\d+$", - "description": "Running BOOKED balance of the project in this currency right after this entry: Σ amount_minor of every fund/debit/fee/reverse entry up to and including it, in id order; hold, release and reconcile entries repeat the previous value. Equals Σ balance_minor at the head (= available + held)." + "description": "Running BOOKED balance in this currency right after this entry, over the same wallets as GET /v1/account/balances: Σ amount_minor of every fund/debit/fee/reverse entry of those wallets up to and including it, in id order; hold, release and reconcile entries repeat the previous value. Equals Σ balance_minor at the head (= available + held). Each entry runs in its own scope (Fabiano 21/10, 02/11): the account's wallets as GET /v1/account/balances cuts them, or, on an entry with `outside_account_balance` true, the simulator's residue's own running balance at that point (never the account's, never an invented 0)." + }, + "outside_account_balance": { + "type": "boolean", + "description": "True on an entry of a wallet GET /v1/account/balances does not sum: the simulator's residue (its legacy test funding among it) of a Test project with its own bound account, or every entry of one the own-account rule reaches with no account yet. Shown with its own origin, never counted in the account's balance; false everywhere else." } }, "required": [ @@ -7564,7 +7969,12 @@ "source", "phase", "executor", - "balance_after_minor" + "executor_provider", + "payee_name", + "payee_name_source", + "triggered_by", + "balance_after_minor", + "outside_account_balance" ] } }, @@ -7954,6 +8364,34 @@ "tool_calls": { "type": "integer", "description": "session_tool_calls in the window, in this project, of the sessions the agent opened (`sessions.agent_did`). A session opened without an agent counts for nobody." + }, + "via_connections": { + "type": "array", + "items": { + "type": "object", + "properties": { + "client_name_declared": { + "type": [ + "string", + "null" + ], + "description": "The OAuth client's name as it declared it at dynamic registration; never verified." + }, + "spent_minor": { + "type": "string", + "pattern": "^-?\\d+$" + }, + "payments": { + "type": "integer" + } + }, + "required": [ + "client_name_declared", + "spent_minor", + "payments" + ] + }, + "description": "The part of `spent_minor` that an external OAuth connection (an MCP client) paid under this agent's mandate, by the connection's declared name: the tool call that made the payment carries the connection (0408). Not this agent's own act; empty when none, and for payments made before 0408." } }, "required": [ @@ -7962,7 +8400,8 @@ "spent_within_mandate_minor", "received_minor", "last_activity_at", - "tool_calls" + "tool_calls", + "via_connections" ] } } @@ -8342,9 +8781,19 @@ ], "enum": [ "codespar_simulator", - "celcoin_sandbox" + "provider_sandbox" ], - "description": "\"codespar_simulator\" when the payment was a demonstration settled on the CodeSpar simulator (\"Simulado pela CodeSpar\"); \"celcoin_sandbox\" when it ran in the restricted integrated proof, at the Celcoin sandbox (\"Integrado (sandbox Celcoin)\"); null for every other payment. What the payment recorded when it ran." + "description": "\"codespar_simulator\" when the payment was a demonstration settled on the CodeSpar simulator (\"Simulado pela CodeSpar\"); \"provider_sandbox\" when it ran at a provider's sandbox (`executor_provider` names it); null for every other payment. What the payment recorded when it ran. Test only: no real money either way." + }, + "executor_provider": { + "type": [ + "string", + "null" + ], + "enum": [ + "celcoin" + ], + "description": "ent#1983: the concrete provider behind `executor` (\"celcoin\" for `provider_sandbox`), resolved by the server; null for the simulator and every other entry." }, "created_at": { "type": "string", @@ -8370,6 +8819,7 @@ "receipt_id", "debit_entry_id", "executor", + "executor_provider", "created_at", "updated_at" ] @@ -8449,7 +8899,7 @@ "/v1/account/fund/sandbox": { "post": { "summary": "Add test balance (test projects only)", - "description": "Credits test balance, in BRL, in a TEST project. Nothing is sent to any bank or provider; `rail` is the label the person picked. The entry is a FUND marked `test_funding: true` on GET /v1/account/ledger, and it is never counted as money received.\n\n`target` picks the wallet. `account` (the default) is the project's account wallet, created on first use: the account Wallet shows it, but no agent spends from it. `consumer` is the consumer wallet a mandate spend reserves and debits: `mandate_id`'s consumer, else `consumer_id`, else the one consumer the organization's active BRL mandates name; none or several answer `test_funding_target_required` with the candidates. Naming `mandate_id` or `consumer_id` implies `consumer`. A consumer wallet created here starts with exactly the amount funded.\n\nAt most 1000000 centavos per call. `idempotency_key` is required: the same key with the same amount and wallet answers the first entry with 200 and `idempotent_replay: true`; with another amount or wallet, `idempotency_key_conflict`. Requires an admin or owner (`x-codespar-user` on the dashboard path).\n\nA Test project with its own bound provider account (`payments` active) is credited THERE instead: the amount goes to the bound account, claimed before it is sent and copied into the binding consumer's wallet ledger (`consumer_id` names it), with no platform total. An earlier credit still in flight or whose result is unknown blocks the next (`sandbox_funding_open_claim`); a platform guard's refusal before the send answers `sandbox_funding_refused` (422), a provider refusal `sandbox_funding_failed`.", + "description": "Credits test balance, in BRL, in a TEST project. Nothing is sent to any bank or provider; `rail` is the label the person picked. The entry is a FUND marked `test_funding: true` on GET /v1/account/ledger, and it is never counted as money received.\n\n`target` picks the wallet. `account` (the default) is the project's account wallet, created on first use: the account Wallet shows it, but no agent spends from it. `consumer` is the consumer wallet a mandate spend reserves and debits: `mandate_id`'s consumer, else `consumer_id`, else the one consumer the organization's active BRL mandates name; none or several answer `test_funding_target_required` with the candidates. Naming `mandate_id` or `consumer_id` implies `consumer`. A consumer wallet created here starts with exactly the amount funded.\n\nAt most 1000000 centavos per call. `idempotency_key` is required: the same key with the same amount and wallet answers the first entry with 200 and `idempotent_replay: true`; with another amount or wallet, `idempotency_key_conflict`. An admin or owner performs it from the dashboard; an API key is refused with 403 `admin_session_required`, whatever its scopes.\n\nA Test project with its own bound provider account (`payments` active) is credited THERE instead: the amount goes to the bound account, claimed before it is sent and copied into the binding consumer's wallet ledger (`consumer_id` names it), with no platform total. An earlier credit still in flight or whose result is unknown blocks the next (`sandbox_funding_open_claim`); a platform guard's refusal before the send answers `sandbox_funding_refused` (422), a provider refusal `sandbox_funding_failed`.", "requestBody": { "content": { "application/json": { @@ -8750,7 +9200,7 @@ } }, "403": { - "description": "The acting member is below admin, or the dashboard forwarded no member.", + "description": "The acting member is below admin, the dashboard forwarded no member, or the credential is an API key (`admin_session_required`: this is administrative, whatever the key's scopes).", "content": { "application/json": { "schema": { @@ -9395,7 +9845,7 @@ } }, "403": { - "description": "The acting member is below admin, or the dashboard forwarded no member.", + "description": "The acting member is below admin, the dashboard forwarded no member, or the credential is an API key (`admin_session_required`: this is administrative, whatever the key's scopes).", "content": { "application/json": { "schema": { @@ -9818,9 +10268,19 @@ ], "enum": [ "codespar_simulator", - "celcoin_sandbox" + "provider_sandbox" ], - "description": "\"codespar_simulator\" when this session's payments were demonstrations settled on the CodeSpar simulator (\"Simulado pela CodeSpar\"); \"celcoin_sandbox\" when they ran in the restricted integrated proof, at the Celcoin sandbox (\"Integrado (sandbox Celcoin)\"); null otherwise." + "description": "\"codespar_simulator\" when this session's payments were demonstrations settled on the CodeSpar simulator (\"Simulado pela CodeSpar\"); \"provider_sandbox\" when they ran at a provider's sandbox (`executor_provider` names it); null otherwise. Test only: no real money either way." + }, + "executor_provider": { + "type": [ + "string", + "null" + ], + "enum": [ + "celcoin" + ], + "description": "ent#1983: the concrete provider behind `executor` (\"celcoin\" for `provider_sandbox`); null otherwise." } }, "required": [ @@ -9839,7 +10299,8 @@ "title", "scene", "conversation_id", - "executor" + "executor", + "executor_provider" ] } }, @@ -9922,7 +10383,7 @@ "/v1/onboarding": { "get": { "summary": "The first-access guide's progress for the project", - "description": "Three steps, read in one call. `agent`: the organization has a registered agent other than a Playground scene's own; `in_project` says whether one of them works in this project (an active mandate funds it). `scenario`: a session of this project recorded a tool call; the first one names the session and, for a Playground session, its scene. `result`: money moved under a mandate in this project (the first debit); test funding is not a result. Read-only. `project_id`, when sent, must be the project the request resolved to, or the answer is 404.", + "description": "Three steps, read in one call. `agent`: the organization has a registered agent other than a Playground scene's own; `in_project` says whether one of them works in this project (an active mandate funds it). `scenario`: a session of this project recorded a tool call; the first one names the session and, for a Playground session, its scene. `result`: money moved under a mandate in this project (the first debit); test funding is not a result. Added for the new guide, each derived from the server's own records, with a `state` (done, pending, or unverified when the read failed: `done` is then null, never a false nobody read): `receive` (the first Collect payment confirmed by the provider, in the ledger, with its signed receipt; test funding, the initial credit included, never counts; the same source as the first receipt's `project_has_confirmed_receipt`), `shop_payment` (the Shop assistant's first settled, debited and receipted payment), `approval` (a person's first decision on a proposal parked above the mandate's limit) and `connect` (a valid connection from its own state: an unexpired, unrevoked OAuth grant under a live key, else an API key used at least once and not revoked). Read-only. `project_id`, when sent, must be the project the request resolved to, or the answer is 404.", "parameters": [ { "schema": { @@ -10046,66 +10507,286 @@ "ledger_entry_id", "at" ] - } - }, - "required": [ - "project_id", - "environment", - "agent", - "scenario", - "result" - ] - } - } - } - }, - "400": { - "description": "The query did not match the schema.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "error": { + }, + "receive": { "type": "object", "properties": { - "code": { + "state": { "type": "string", "enum": [ - "invalid_query" + "done", + "pending", + "unverified" + ], + "description": "done: the fact is there. pending: read, and it is not. unverified: the read failed; `done` is then null." + }, + "done": { + "type": [ + "boolean", + "null" + ], + "description": "Null only when `state` is unverified." + }, + "at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "When the first confirmed Collect payment was paid." + }, + "charge_id": { + "type": [ + "string", + "null" ] }, - "message": { - "type": "string" + "receipt_id": { + "type": [ + "string", + "null" + ] }, - "details": { - "type": "object", - "additionalProperties": {} + "ledger_entry_id": { + "type": [ + "string", + "null" + ] } }, "required": [ - "code", - "message" + "state", + "done", + "at", + "charge_id", + "receipt_id", + "ledger_entry_id" ] }, - "request_id": { - "type": [ - "string", - "null" - ], - "description": "Echoes the `X-Request-Id` header when the request carried one." + "shop_payment": { + "type": "object", + "properties": { + "state": { + "type": "string", + "enum": [ + "done", + "pending", + "unverified" + ], + "description": "done: the fact is there. pending: read, and it is not. unverified: the read failed; `done` is then null." + }, + "done": { + "type": [ + "boolean", + "null" + ], + "description": "Null only when `state` is unverified." + }, + "origin": { + "type": [ + "string", + "null" + ], + "enum": [ + "wallet_pix", + "wallet_boleto", + "external_card", + "store_on_file" + ], + "description": "Where the money came from. wallet_*: a Wallet debit the provider settled. external_card / store_on_file: the store's order, no Wallet leg and no settlement claimed." + }, + "at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "wallet_*: when the debit posted. External: when the store's order closed the attempt." + }, + "proposal_id": { + "type": [ + "string", + "null" + ] + }, + "mandate_id": { + "type": [ + "string", + "null" + ] + }, + "receipt_id": { + "type": [ + "string", + "null" + ], + "description": "The Wallet payment's receipt; null for an external purchase, whose receipt is its order record." + }, + "ledger_entry_id": { + "type": [ + "string", + "null" + ], + "description": "Null when the origin does not go through the Wallet." + }, + "order_id": { + "type": [ + "string", + "null" + ], + "description": "The store's order id, for an external purchase." + } + }, + "required": [ + "state", + "done", + "origin", + "at", + "proposal_id", + "mandate_id", + "receipt_id", + "ledger_entry_id", + "order_id" + ] + }, + "approval": { + "type": "object", + "properties": { + "state": { + "type": "string", + "enum": [ + "done", + "pending", + "unverified" + ], + "description": "done: the fact is there. pending: read, and it is not. unverified: the read failed; `done` is then null." + }, + "done": { + "type": [ + "boolean", + "null" + ], + "description": "Null only when `state` is unverified." + }, + "at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "When a person first decided a proposal parked above the mandate's limit." + }, + "proposal_id": { + "type": [ + "string", + "null" + ] + }, + "decision": { + "type": [ + "string", + "null" + ], + "enum": [ + "approved", + "denied" + ] + }, + "receipt_id": { + "type": [ + "string", + "null" + ], + "description": "The receipt of the approved payment, once it was paid." + } + }, + "required": [ + "state", + "done", + "at", + "proposal_id", + "decision", + "receipt_id" + ] + }, + "connect": { + "type": "object", + "properties": { + "state": { + "type": "string", + "enum": [ + "done", + "pending", + "unverified" + ], + "description": "done: the fact is there. pending: read, and it is not. unverified: the read failed; `done` is then null." + }, + "done": { + "type": [ + "boolean", + "null" + ], + "description": "Null only when `state` is unverified." + }, + "at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "OAuth: when the live refresh token was issued (each refresh rotates it). A key: its last use (a key records no other)." + }, + "via": { + "type": [ + "string", + "null" + ], + "enum": [ + "oauth", + "bearer" + ] + }, + "client_name_declared": { + "type": [ + "string", + "null" + ], + "description": "The name the OAuth client declared at registration; never verified." + }, + "key_id_masked": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "state", + "done", + "at", + "via", + "client_name_declared", + "key_id_masked" + ] } }, "required": [ - "error", - "request_id" + "project_id", + "environment", + "agent", + "scenario", + "result", + "receive", + "shop_payment", + "approval", + "connect" ] } } } }, - "404": { - "description": "`project_id` names a project other than the one the request resolved to.", + "400": { + "description": "The query did not match the schema.", "content": { "application/json": { "schema": { @@ -10117,7 +10798,52 @@ "code": { "type": "string", "enum": [ - "not_found" + "invalid_query" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "404": { + "description": "`project_id` names a project other than the one the request resolved to.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "not_found" ] }, "message": { @@ -10160,6 +10886,341 @@ ] } }, + "/v1/onboarding/first-receive": { + "get": { + "summary": "The project's first test receipt (the guide's Receber R$ 10)", + "description": "Read-only. The project's first-receive obligation is a Collect link under the reference `codespar_first_receive` (version 1), R$ 10,00, paid by the platform's Test payer. States, from Collect's records, never a clock: `not_started` (no link, or no attempt), `creating_charge` (the charge waits for its copia-e-cola), `paying` (open, the Test payer has not taken it: a POST pays it), `awaiting_confirmation` (the payer took it, or a payment is not yet confirmed with its receipt), `received` (`paid_confirmed`, in the ledger, with its signed receipt; the only state that says received), `failed` (`refusal.retriable` says whether a POST starts again, on the same link), `blocked` (a precondition is missing; nothing is created).", + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "object": { + "type": "string", + "enum": [ + "first_receive" + ] + }, + "state": { + "type": "string", + "enum": [ + "not_started", + "creating_charge", + "paying", + "awaiting_confirmation", + "received", + "failed", + "blocked" + ] + }, + "amount_minor": { + "type": "integer", + "description": "Always 1000 (R$ 10,00): the server's, never the request's." + }, + "link_id": { + "type": [ + "string", + "null" + ] + }, + "attempt_id": { + "type": [ + "string", + "null" + ] + }, + "charge_id": { + "type": [ + "string", + "null" + ] + }, + "payment": { + "type": [ + "object", + "null" + ], + "properties": { + "payment_id": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "paid_confirmed" + ] + }, + "receipt_id": { + "type": "string" + }, + "ledger_entry_id": { + "type": "string" + }, + "paid_at": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "payment_id", + "status", + "receipt_id", + "ledger_entry_id", + "paid_at" + ], + "description": "Only in `received`: confirmed by the provider (D-A), with its ledger entry and signed receipt." + }, + "refusal": { + "type": [ + "object", + "null" + ], + "properties": { + "code": { + "type": "string", + "description": "blocked: not_test, collect_off, receive_unavailable, insufficient_role. failed: the Collect or test-pay code." + }, + "message": { + "type": "string" + }, + "retriable": { + "type": "boolean", + "description": "Whether a POST may start again; false needs something else first (the refusal says what)." + }, + "next_action": { + "type": "string" + } + }, + "required": [ + "code", + "message", + "retriable" + ], + "description": "In `blocked` and `failed`." + }, + "project_has_confirmed_receipt": { + "type": "boolean", + "description": "Any confirmed Collect receipt of the project, from this link or another: the guide's first step is done." + } + }, + "required": [ + "object", + "state", + "amount_minor", + "link_id", + "attempt_id", + "charge_id", + "payment", + "refusal", + "project_has_confirmed_receipt" + ] + } + } + } + } + }, + "x-codespar-scope": "collect:read", + "security": [ + { + "bearerAuth": [ + "collect:read" + ] + } + ] + }, + "post": { + "summary": "Take the project's first test receipt one step further", + "description": "No body. Idempotent: a repeated click, a refresh or a timeout resumes the same obligation, never a second link, attempt or payment. From where the records are: creates or answers the referenced link, publishes it, asks it for an attempt, or has the Test payer pay the open attempt (one payment per charge). The copia-e-cola arrives after the POST, so the answer is often `creating_charge`; once the GET reads `paying`, one more POST pays it. Test projects only; an admin's or the owner's act from the dashboard, or the project's own key. Answers the GET's view. States, from Collect's records, never a clock: `not_started` (no link, or no attempt), `creating_charge` (the charge waits for its copia-e-cola), `paying` (open, the Test payer has not taken it: a POST pays it), `awaiting_confirmation` (the payer took it, or a payment is not yet confirmed with its receipt), `received` (`paid_confirmed`, in the ledger, with its signed receipt; the only state that says received), `failed` (`refusal.retriable` says whether a POST starts again, on the same link), `blocked` (a precondition is missing; nothing is created).", + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "object": { + "type": "string", + "enum": [ + "first_receive" + ] + }, + "state": { + "type": "string", + "enum": [ + "not_started", + "creating_charge", + "paying", + "awaiting_confirmation", + "received", + "failed", + "blocked" + ] + }, + "amount_minor": { + "type": "integer", + "description": "Always 1000 (R$ 10,00): the server's, never the request's." + }, + "link_id": { + "type": [ + "string", + "null" + ] + }, + "attempt_id": { + "type": [ + "string", + "null" + ] + }, + "charge_id": { + "type": [ + "string", + "null" + ] + }, + "payment": { + "type": [ + "object", + "null" + ], + "properties": { + "payment_id": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "paid_confirmed" + ] + }, + "receipt_id": { + "type": "string" + }, + "ledger_entry_id": { + "type": "string" + }, + "paid_at": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "payment_id", + "status", + "receipt_id", + "ledger_entry_id", + "paid_at" + ], + "description": "Only in `received`: confirmed by the provider (D-A), with its ledger entry and signed receipt." + }, + "refusal": { + "type": [ + "object", + "null" + ], + "properties": { + "code": { + "type": "string", + "description": "blocked: not_test, collect_off, receive_unavailable, insufficient_role. failed: the Collect or test-pay code." + }, + "message": { + "type": "string" + }, + "retriable": { + "type": "boolean", + "description": "Whether a POST may start again; false needs something else first (the refusal says what)." + }, + "next_action": { + "type": "string" + } + }, + "required": [ + "code", + "message", + "retriable" + ], + "description": "In `blocked` and `failed`." + }, + "project_has_confirmed_receipt": { + "type": "boolean", + "description": "Any confirmed Collect receipt of the project, from this link or another: the guide's first step is done." + } + }, + "required": [ + "object", + "state", + "amount_minor", + "link_id", + "attempt_id", + "charge_id", + "payment", + "refusal", + "project_has_confirmed_receipt" + ] + } + } + } + }, + "400": { + "description": "A body was sent: amount, receiver and payer are the server's.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "invalid_body" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + } + }, + "x-codespar-scope": "collect:write", + "security": [ + { + "bearerAuth": [ + "collect:write" + ] + } + ] + } + }, "/v1/account/test-balance": { "get": { "summary": "The test balance, the refill quota and the Adicionar fundos cap", @@ -10297,7 +11358,7 @@ "/v1/account/fund/sandbox/refill": { "post": { "summary": "Refill the test balance (test projects only, confirmed)", - "description": "Brings the project's test balance (available + held, every wallet) back up to 10000 centavos, crediting only the difference to the account wallet; a balance already there answers 200 with `refilled: false` and credits nothing. At most 3 refills per São Paulo calendar day per project; the credit and the quota use are one row in one transaction, and a refill that credits nothing uses no quota. Adicionar fundos is a separate action and never counts. An explicit, confirmed act of a person: the body must be `{ \"confirm\": true }`. The entry is test funding (`test_funding_kind: refill`) and never money received. Admin or owner.\n\nA Test project with its own bound provider account (`payments` active) refills THAT account: its balance is read at the provider and only the difference to the target is credited there, claimed before it is sent, with NO daily quota (`refill.daily_limit` and `left_today` null). An unreadable balance credits nothing (502 `test_funding_failed`).", + "description": "Brings the project's test balance (available + held, every wallet) back up to 10000 centavos, crediting only the difference to the account wallet; a balance already there answers 200 with `refilled: false` and credits nothing. At most 3 refills per São Paulo calendar day per project; the credit and the quota use are one row in one transaction, and a refill that credits nothing uses no quota. Adicionar fundos is a separate action and never counts. An explicit, confirmed act of a person: the body must be `{ \"confirm\": true }`. The entry is test funding (`test_funding_kind: refill`) and never money received. Admin or owner, from the dashboard; an API key is refused with 403 `admin_session_required`.\n\nA Test project with its own bound provider account (`payments` active) refills THAT account: its balance is read at the provider and only the difference to the target is credited there, claimed before it is sent, with NO daily quota (`refill.daily_limit` and `left_today` null). An unreadable balance credits nothing (502 `test_funding_failed`).", "requestBody": { "content": { "application/json": { @@ -10674,7 +11735,7 @@ } }, "403": { - "description": "The acting member is below admin, or the dashboard forwarded no member.", + "description": "The acting member is below admin, the dashboard forwarded no member, or the credential is an API key (`admin_session_required`: this is administrative, whatever the key's scopes).", "content": { "application/json": { "schema": { @@ -16383,6 +17444,5569 @@ ] } }, + "/v1/ofb/sweeping/consents": { + "post": { + "summary": "Open a sweeping consent", + "description": "Opens a sweeping authorisation at the provider for a consumer's own bank account, to be pulled into their own Celcoin account (`funding_source_id`). The consumer approves it once at their bank, at `authorisation_url`; after that, pulls need no per-payment approval within the bank's limits.\n\nThe consent is written before the provider is called. If the provider fails while it is being opened, the consent is answered as an error and kept as `canceled`.\n\nRequires the `consents:write` scope. Test projects only.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "consumer_id": { + "type": "string", + "minLength": 1, + "maxLength": 128 + }, + "wallet_id": { + "type": "string", + "minLength": 1, + "maxLength": 128 + }, + "funding_source_id": { + "type": "string", + "minLength": 1, + "maxLength": 128 + }, + "participant_id": { + "type": "string", + "format": "uuid" + }, + "triggers": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "manual", + "automatic" + ] + }, + "minItems": 1, + "maxItems": 2, + "default": [ + "manual" + ] + }, + "limits": { + "type": "object", + "properties": { + "total_minor": { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 + }, + "per_transaction_minor": { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 + } + }, + "default": {}, + "additionalProperties": false + }, + "expires_at": { + "type": "string", + "format": "date-time" + }, + "redirect_url": { + "type": "string", + "format": "uri" + } + }, + "required": [ + "consumer_id", + "wallet_id", + "funding_source_id", + "participant_id" + ], + "additionalProperties": false + } + } + } + }, + "responses": { + "201": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "`ofb_`-prefixed. Also the external id the provider keeps for this authorisation." + }, + "consumer_id": { + "type": "string" + }, + "wallet_id": { + "type": [ + "string", + "null" + ] + }, + "funding_source_id": { + "type": [ + "string", + "null" + ], + "description": "The consumer's `pix-celcoin` funding source the sweep lands in." + }, + "participant_id": { + "type": "string", + "description": "The provider's id for the consumer's bank, as passed when the consent was opened." + }, + "provider": { + "type": "string", + "enum": [ + "iniciador", + "celcoin-itp" + ] + }, + "status": { + "type": "string", + "enum": [ + "pending", + "authorised", + "consumed", + "revoked", + "rejected", + "expired", + "canceled", + "failed" + ], + "description": "`pending` until the consumer approves at their bank, then `authorised`. Terminal: `consumed`, `revoked` (after approval), `rejected` (refused or rejected before approval), `expired`, `canceled` (the provider canceled it, or it failed while being opened) and `failed` (a provider error). It only moves forward." + }, + "authorisation_url": { + "type": [ + "string", + "null" + ], + "description": "Where the consumer approves the consent at their bank. Present while `pending` only; open it once." + }, + "debtor": { + "type": [ + "object", + "null" + ], + "properties": { + "ispb": { + "type": [ + "string", + "null" + ] + }, + "account_masked": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "ispb", + "account_masked" + ], + "description": "The account the bank authorised the pulls from, as the provider reports it. Null until `authorised`." + }, + "limits": { + "type": [ + "object", + "null" + ], + "properties": { + "total_minor": { + "type": [ + "integer", + "null" + ] + }, + "per_transaction_minor": { + "type": [ + "integer", + "null" + ] + } + }, + "required": [ + "total_minor", + "per_transaction_minor" + ], + "description": "The limits as the bank stated them on approval, in centavos. Null until `authorised`." + }, + "created_at": { + "type": "string" + }, + "authorized_at": { + "type": [ + "string", + "null" + ] + }, + "expires_at": { + "type": [ + "string", + "null" + ] + }, + "revoked_at": { + "type": [ + "string", + "null" + ] + }, + "consumed_at": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "id", + "consumer_id", + "wallet_id", + "funding_source_id", + "participant_id", + "provider", + "status", + "authorisation_url", + "debtor", + "limits", + "created_at", + "authorized_at", + "expires_at", + "revoked_at", + "consumed_at" + ] + } + } + } + }, + "400": { + "description": "The body did not match the schema.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "invalid_body" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "409": { + "description": "This project already holds an open sweeping consent for this consumer at this bank (`consent_active_for_consumer`), or another project of the organization does (`bank_consent_held_elsewhere`).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "consent_active_for_consumer", + "bank_consent_held_elsewhere" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "422": { + "description": "Not live, or the destination cannot receive a sweep.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "ofb_not_live", + "sweep_destination_unresolved" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "502": { + "description": "The provider refused the call. `details.provider_code` is the provider's own error code; terminal for this request.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "sweep_provider_refused" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "503": { + "description": "The provider gave no definite answer (`sweep_provider_ambiguous`, retriable), the platform has no active trigger of a requested kind (`sweep_trigger_unavailable`), the deployment has no sweeping provider (`ofb_adapter_unavailable`) or another request holds this grant's lock (`consent_lock_timeout`, retriable).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "sweep_provider_ambiguous", + "sweep_trigger_unavailable", + "ofb_adapter_unavailable", + "consent_lock_timeout" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + } + }, + "x-codespar-scope": "consents:write", + "security": [ + { + "bearerAuth": [ + "consents:write" + ] + } + ] + }, + "get": { + "summary": "List sweeping consents", + "description": "The project's sweeping consents, most recent first, as stored: the list does not call the provider.\n\nRequires the `consents:read` scope.", + "parameters": [ + { + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 200, + "default": 50 + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 128 + }, + "required": false, + "name": "consumer_id", + "in": "query" + }, + { + "schema": { + "type": "string", + "enum": [ + "pending", + "authorised", + "consumed", + "revoked", + "rejected", + "expired", + "canceled", + "failed" + ] + }, + "required": false, + "name": "status", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "sweep_consents": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "`ofb_`-prefixed. Also the external id the provider keeps for this authorisation." + }, + "consumer_id": { + "type": "string" + }, + "wallet_id": { + "type": [ + "string", + "null" + ] + }, + "funding_source_id": { + "type": [ + "string", + "null" + ], + "description": "The consumer's `pix-celcoin` funding source the sweep lands in." + }, + "participant_id": { + "type": "string", + "description": "The provider's id for the consumer's bank, as passed when the consent was opened." + }, + "provider": { + "type": "string", + "enum": [ + "iniciador", + "celcoin-itp" + ] + }, + "status": { + "type": "string", + "enum": [ + "pending", + "authorised", + "consumed", + "revoked", + "rejected", + "expired", + "canceled", + "failed" + ], + "description": "`pending` until the consumer approves at their bank, then `authorised`. Terminal: `consumed`, `revoked` (after approval), `rejected` (refused or rejected before approval), `expired`, `canceled` (the provider canceled it, or it failed while being opened) and `failed` (a provider error). It only moves forward." + }, + "authorisation_url": { + "type": [ + "string", + "null" + ], + "description": "Where the consumer approves the consent at their bank. Present while `pending` only; open it once." + }, + "debtor": { + "type": [ + "object", + "null" + ], + "properties": { + "ispb": { + "type": [ + "string", + "null" + ] + }, + "account_masked": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "ispb", + "account_masked" + ], + "description": "The account the bank authorised the pulls from, as the provider reports it. Null until `authorised`." + }, + "limits": { + "type": [ + "object", + "null" + ], + "properties": { + "total_minor": { + "type": [ + "integer", + "null" + ] + }, + "per_transaction_minor": { + "type": [ + "integer", + "null" + ] + } + }, + "required": [ + "total_minor", + "per_transaction_minor" + ], + "description": "The limits as the bank stated them on approval, in centavos. Null until `authorised`." + }, + "created_at": { + "type": "string" + }, + "authorized_at": { + "type": [ + "string", + "null" + ] + }, + "expires_at": { + "type": [ + "string", + "null" + ] + }, + "revoked_at": { + "type": [ + "string", + "null" + ] + }, + "consumed_at": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "id", + "consumer_id", + "wallet_id", + "funding_source_id", + "participant_id", + "provider", + "status", + "authorisation_url", + "debtor", + "limits", + "created_at", + "authorized_at", + "expires_at", + "revoked_at", + "consumed_at" + ] + } + } + }, + "required": [ + "sweep_consents" + ] + } + } + } + }, + "400": { + "description": "The query did not match the schema.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "invalid_query" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + } + }, + "x-codespar-scope": "consents:read", + "security": [ + { + "bearerAuth": [ + "consents:read" + ] + } + ] + } + }, + "/v1/ofb/sweeping/consents/{id}": { + "get": { + "summary": "Read one sweeping consent", + "description": "While the consent is `pending` or `authorised`, the provider is read and the consent moves forward with it; a terminal consent is answered as stored.\n\nRequires the `consents:read` scope.", + "parameters": [ + { + "schema": { + "type": "string", + "description": "`ofb_`-prefixed sweeping consent id." + }, + "required": true, + "description": "`ofb_`-prefixed sweeping consent id.", + "name": "id", + "in": "path" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "`ofb_`-prefixed. Also the external id the provider keeps for this authorisation." + }, + "consumer_id": { + "type": "string" + }, + "wallet_id": { + "type": [ + "string", + "null" + ] + }, + "funding_source_id": { + "type": [ + "string", + "null" + ], + "description": "The consumer's `pix-celcoin` funding source the sweep lands in." + }, + "participant_id": { + "type": "string", + "description": "The provider's id for the consumer's bank, as passed when the consent was opened." + }, + "provider": { + "type": "string", + "enum": [ + "iniciador", + "celcoin-itp" + ] + }, + "status": { + "type": "string", + "enum": [ + "pending", + "authorised", + "consumed", + "revoked", + "rejected", + "expired", + "canceled", + "failed" + ], + "description": "`pending` until the consumer approves at their bank, then `authorised`. Terminal: `consumed`, `revoked` (after approval), `rejected` (refused or rejected before approval), `expired`, `canceled` (the provider canceled it, or it failed while being opened) and `failed` (a provider error). It only moves forward." + }, + "authorisation_url": { + "type": [ + "string", + "null" + ], + "description": "Where the consumer approves the consent at their bank. Present while `pending` only; open it once." + }, + "debtor": { + "type": [ + "object", + "null" + ], + "properties": { + "ispb": { + "type": [ + "string", + "null" + ] + }, + "account_masked": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "ispb", + "account_masked" + ], + "description": "The account the bank authorised the pulls from, as the provider reports it. Null until `authorised`." + }, + "limits": { + "type": [ + "object", + "null" + ], + "properties": { + "total_minor": { + "type": [ + "integer", + "null" + ] + }, + "per_transaction_minor": { + "type": [ + "integer", + "null" + ] + } + }, + "required": [ + "total_minor", + "per_transaction_minor" + ], + "description": "The limits as the bank stated them on approval, in centavos. Null until `authorised`." + }, + "created_at": { + "type": "string" + }, + "authorized_at": { + "type": [ + "string", + "null" + ] + }, + "expires_at": { + "type": [ + "string", + "null" + ] + }, + "revoked_at": { + "type": [ + "string", + "null" + ] + }, + "consumed_at": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "id", + "consumer_id", + "wallet_id", + "funding_source_id", + "participant_id", + "provider", + "status", + "authorisation_url", + "debtor", + "limits", + "created_at", + "authorized_at", + "expires_at", + "revoked_at", + "consumed_at" + ] + } + } + } + }, + "404": { + "description": "Not Found. No sweeping consent with this id in the caller's project. A data-sharing consent's id answers here too.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "not_found" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "422": { + "description": "The project is live. Sweeping serves test projects only, against the provider's sandbox (`details.reason` `live_not_enabled`).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "ofb_not_live" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "502": { + "description": "The provider refused the call. `details.provider_code` is the provider's own error code; terminal for this request.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "sweep_provider_refused" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "503": { + "description": "No definite answer: the provider did not answer, answered a status this API does not map yet (`sweep_provider_ambiguous`, retriable with the same request), or the deployment cannot reach a sweeping provider (`ofb_adapter_unavailable`).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "sweep_provider_ambiguous", + "ofb_adapter_unavailable" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + } + }, + "x-codespar-scope": "consents:read", + "security": [ + { + "bearerAuth": [ + "consents:read" + ] + } + ] + } + }, + "/v1/ofb/sweeping/consents/{id}/revoke": { + "post": { + "summary": "Revoke a sweeping consent", + "description": "Reads the provider first, then rejects a consent still awaiting approval (`rejected`) or revokes an authorised one (`revoked`).\n\nRequires the `consents:write` scope.", + "parameters": [ + { + "schema": { + "type": "string", + "description": "`ofb_`-prefixed sweeping consent id." + }, + "required": true, + "description": "`ofb_`-prefixed sweeping consent id.", + "name": "id", + "in": "path" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "reason": { + "type": "string", + "minLength": 1, + "maxLength": 512 + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "`ofb_`-prefixed. Also the external id the provider keeps for this authorisation." + }, + "consumer_id": { + "type": "string" + }, + "wallet_id": { + "type": [ + "string", + "null" + ] + }, + "funding_source_id": { + "type": [ + "string", + "null" + ], + "description": "The consumer's `pix-celcoin` funding source the sweep lands in." + }, + "participant_id": { + "type": "string", + "description": "The provider's id for the consumer's bank, as passed when the consent was opened." + }, + "provider": { + "type": "string", + "enum": [ + "iniciador", + "celcoin-itp" + ] + }, + "status": { + "type": "string", + "enum": [ + "pending", + "authorised", + "consumed", + "revoked", + "rejected", + "expired", + "canceled", + "failed" + ], + "description": "`pending` until the consumer approves at their bank, then `authorised`. Terminal: `consumed`, `revoked` (after approval), `rejected` (refused or rejected before approval), `expired`, `canceled` (the provider canceled it, or it failed while being opened) and `failed` (a provider error). It only moves forward." + }, + "authorisation_url": { + "type": [ + "string", + "null" + ], + "description": "Where the consumer approves the consent at their bank. Present while `pending` only; open it once." + }, + "debtor": { + "type": [ + "object", + "null" + ], + "properties": { + "ispb": { + "type": [ + "string", + "null" + ] + }, + "account_masked": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "ispb", + "account_masked" + ], + "description": "The account the bank authorised the pulls from, as the provider reports it. Null until `authorised`." + }, + "limits": { + "type": [ + "object", + "null" + ], + "properties": { + "total_minor": { + "type": [ + "integer", + "null" + ] + }, + "per_transaction_minor": { + "type": [ + "integer", + "null" + ] + } + }, + "required": [ + "total_minor", + "per_transaction_minor" + ], + "description": "The limits as the bank stated them on approval, in centavos. Null until `authorised`." + }, + "created_at": { + "type": "string" + }, + "authorized_at": { + "type": [ + "string", + "null" + ] + }, + "expires_at": { + "type": [ + "string", + "null" + ] + }, + "revoked_at": { + "type": [ + "string", + "null" + ] + }, + "consumed_at": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "id", + "consumer_id", + "wallet_id", + "funding_source_id", + "participant_id", + "provider", + "status", + "authorisation_url", + "debtor", + "limits", + "created_at", + "authorized_at", + "expires_at", + "revoked_at", + "consumed_at" + ] + } + } + } + }, + "400": { + "description": "The body did not match the schema.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "invalid_body" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "404": { + "description": "Not Found. No sweeping consent with this id in the caller's project. A data-sharing consent's id answers here too.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "not_found" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "409": { + "description": "The consent is already terminal, or is still being opened at the provider (`details.in_flight`).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "illegal_transition" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "422": { + "description": "The project is live. Sweeping serves test projects only, against the provider's sandbox (`details.reason` `live_not_enabled`).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "ofb_not_live" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "502": { + "description": "The provider refused the call. `details.provider_code` is the provider's own error code; terminal for this request.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "sweep_provider_refused" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "503": { + "description": "No definite answer: the provider did not answer, answered a status this API does not map yet (`sweep_provider_ambiguous`, retriable with the same request), or the deployment cannot reach a sweeping provider (`ofb_adapter_unavailable`).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "sweep_provider_ambiguous", + "ofb_adapter_unavailable" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + } + }, + "x-codespar-scope": "consents:write", + "security": [ + { + "bearerAuth": [ + "consents:write" + ] + } + ] + } + }, + "/v1/ofb/sweeping/pulls": { + "post": { + "summary": "Pull Pix under a sweeping consent", + "description": "Pulls `amount_minor` from the consumer's bank account into their own Celcoin account, under an `authorised` sweeping consent opened with the `automatic` trigger. No user is present: the pull needs no approval at the bank within the limits the bank set on the consent.\n\nThe consent is read at the provider first, and the amount is checked against the bank's per-transaction limit before the pull is sent. The pull is written before the provider is called.\n\nA pull moves money, so the `Idempotency-Key` header is required. The same key with the same body answers the pull the first request created, never a second one; when that request got no definite answer, the retry looks the pull up at the provider and sends it again only when the provider has none.\n\nRequires the `wallets:admin` scope. Test projects only.", + "parameters": [ + { + "schema": { + "type": "string", + "maxLength": 255, + "description": "Required. Send the same key on every retry of the same pull." + }, + "required": true, + "description": "Required. Send the same key on every retry of the same pull.", + "name": "Idempotency-Key", + "in": "header" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "consent_id": { + "type": "string", + "minLength": 1, + "maxLength": 128 + }, + "amount_minor": { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 + }, + "risk_signals": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "AUTOMATIC" + ] + }, + "last_login_date_time": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "type", + "last_login_date_time" + ], + "additionalProperties": false + } + }, + "required": [ + "consent_id", + "amount_minor", + "risk_signals" + ], + "additionalProperties": false + } + } + } + }, + "responses": { + "200": { + "description": "A replay: the same `Idempotency-Key` and body as an earlier request, answered with the pull it created (`replayed: true`).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "`swp_`-prefixed." + }, + "consent_id": { + "type": "string", + "description": "The `ofb_`-prefixed sweeping consent the pull ran under." + }, + "consumer_id": { + "type": "string" + }, + "wallet_id": { + "type": "string" + }, + "provider": { + "type": "string", + "enum": [ + "iniciador", + "celcoin-itp" + ] + }, + "amount_minor": { + "type": "integer", + "description": "In centavos." + }, + "currency": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "pending", + "settling", + "completed", + "rejected", + "expired", + "canceled", + "failed", + "unknown" + ], + "description": "`pending` while the provider processes it, `settling` once the Pix is on its way, then a terminal `completed`, `rejected`, `expired`, `canceled` (the provider refused it when it was sent) or `failed` (the provider reported an error). `unknown`: no definite answer yet; retry the create with the same `Idempotency-Key`. It only moves forward." + }, + "provider_status": { + "type": [ + "string", + "null" + ], + "description": "The provider's own status, as it reported it. On a read, a status this API does not map yet is shown here while `status` stays as stored." + }, + "end_to_end_id": { + "type": [ + "string", + "null" + ], + "description": "The Pix end-to-end id, once the provider reports it." + }, + "error_code": { + "type": [ + "string", + "null" + ], + "description": "The provider's error code, or why the pull has no definite answer." + }, + "credited": { + "type": "boolean", + "description": "Always `false` for now: a pull `completed` at the provider is not yet credited in the wallet." + }, + "replayed": { + "type": "boolean", + "description": "`true` when the answer is a pull an earlier request with the same key created." + }, + "created_at": { + "type": "string" + }, + "updated_at": { + "type": "string" + } + }, + "required": [ + "id", + "consent_id", + "consumer_id", + "wallet_id", + "provider", + "amount_minor", + "currency", + "status", + "provider_status", + "end_to_end_id", + "error_code", + "credited", + "replayed", + "created_at", + "updated_at" + ] + } + } + } + }, + "202": { + "description": "The pull was written and sent to the provider.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "`swp_`-prefixed." + }, + "consent_id": { + "type": "string", + "description": "The `ofb_`-prefixed sweeping consent the pull ran under." + }, + "consumer_id": { + "type": "string" + }, + "wallet_id": { + "type": "string" + }, + "provider": { + "type": "string", + "enum": [ + "iniciador", + "celcoin-itp" + ] + }, + "amount_minor": { + "type": "integer", + "description": "In centavos." + }, + "currency": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "pending", + "settling", + "completed", + "rejected", + "expired", + "canceled", + "failed", + "unknown" + ], + "description": "`pending` while the provider processes it, `settling` once the Pix is on its way, then a terminal `completed`, `rejected`, `expired`, `canceled` (the provider refused it when it was sent) or `failed` (the provider reported an error). `unknown`: no definite answer yet; retry the create with the same `Idempotency-Key`. It only moves forward." + }, + "provider_status": { + "type": [ + "string", + "null" + ], + "description": "The provider's own status, as it reported it. On a read, a status this API does not map yet is shown here while `status` stays as stored." + }, + "end_to_end_id": { + "type": [ + "string", + "null" + ], + "description": "The Pix end-to-end id, once the provider reports it." + }, + "error_code": { + "type": [ + "string", + "null" + ], + "description": "The provider's error code, or why the pull has no definite answer." + }, + "credited": { + "type": "boolean", + "description": "Always `false` for now: a pull `completed` at the provider is not yet credited in the wallet." + }, + "replayed": { + "type": "boolean", + "description": "`true` when the answer is a pull an earlier request with the same key created." + }, + "created_at": { + "type": "string" + }, + "updated_at": { + "type": "string" + } + }, + "required": [ + "id", + "consent_id", + "consumer_id", + "wallet_id", + "provider", + "amount_minor", + "currency", + "status", + "provider_status", + "end_to_end_id", + "error_code", + "credited", + "replayed", + "created_at", + "updated_at" + ] + } + } + } + }, + "400": { + "description": "The body did not match the schema, the `Idempotency-Key` header is missing (`sweep_idempotency_key_required`) or longer than 255 characters (`invalid_idempotency_key`).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "invalid_body", + "sweep_idempotency_key_required", + "invalid_idempotency_key" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "403": { + "description": "The key does not carry the `wallets:admin` scope. Bare body; nothing was read or written.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string", + "enum": [ + "forbidden" + ] + }, + "message": { + "type": "string" + }, + "status": { + "type": "number", + "enum": [ + 403 + ] + } + }, + "required": [ + "error", + "message", + "status" + ] + } + } + } + }, + "404": { + "description": "Not Found. No sweeping consent with this id in the caller's project.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "not_found" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "409": { + "description": "The consent cannot carry a pull now (`sweep_consent_not_authorised`), the key already created a pull with another consent or amount (`idempotency_key_conflict`), or another request with this key is still sending it (`sweep_pull_in_flight`, retriable).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "sweep_consent_not_authorised", + "idempotency_key_conflict", + "sweep_pull_in_flight" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "422": { + "description": "Not live, above one of the bank's limits (`details.limit`: `per_transaction`, or `total` counted over the consent's earlier pulls that may move money; `details.reason` `limit_unreadable` when a limit exists and cannot be read), or the consent has no automatic trigger.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "ofb_not_live", + "sweep_limit_exceeded", + "sweep_trigger_not_on_consent" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "502": { + "description": "The provider refused the pull. `details.provider_code` is the provider's own error code; the pull is kept as `canceled` and terminal for this key.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "sweep_provider_refused" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "503": { + "description": "No definite answer from the provider (`sweep_provider_ambiguous`): the pull is kept as `unknown`; retry the same request with the same `Idempotency-Key`. A refused re-send of a pull whose first answer was lost is answered this way too (`details.resend_refused`). Or the deployment cannot reach a sweeping provider (`ofb_adapter_unavailable`).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "sweep_provider_ambiguous", + "ofb_adapter_unavailable" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + } + }, + "x-codespar-scope": "wallets:admin", + "security": [ + { + "bearerAuth": [ + "wallets:admin" + ] + } + ] + }, + "get": { + "summary": "List sweeping pulls", + "description": "The project's sweeping pulls, most recent first, as stored: the list does not call the provider.\n\nRequires the `wallets:read` scope.", + "parameters": [ + { + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 200, + "default": 50 + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 128 + }, + "required": false, + "name": "consent_id", + "in": "query" + }, + { + "schema": { + "type": "string", + "enum": [ + "pending", + "settling", + "completed", + "rejected", + "expired", + "canceled", + "failed", + "unknown" + ] + }, + "required": false, + "name": "status", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "sweep_pulls": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "`swp_`-prefixed." + }, + "consent_id": { + "type": "string", + "description": "The `ofb_`-prefixed sweeping consent the pull ran under." + }, + "consumer_id": { + "type": "string" + }, + "wallet_id": { + "type": "string" + }, + "provider": { + "type": "string", + "enum": [ + "iniciador", + "celcoin-itp" + ] + }, + "amount_minor": { + "type": "integer", + "description": "In centavos." + }, + "currency": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "pending", + "settling", + "completed", + "rejected", + "expired", + "canceled", + "failed", + "unknown" + ], + "description": "`pending` while the provider processes it, `settling` once the Pix is on its way, then a terminal `completed`, `rejected`, `expired`, `canceled` (the provider refused it when it was sent) or `failed` (the provider reported an error). `unknown`: no definite answer yet; retry the create with the same `Idempotency-Key`. It only moves forward." + }, + "provider_status": { + "type": [ + "string", + "null" + ], + "description": "The provider's own status, as it reported it. On a read, a status this API does not map yet is shown here while `status` stays as stored." + }, + "end_to_end_id": { + "type": [ + "string", + "null" + ], + "description": "The Pix end-to-end id, once the provider reports it." + }, + "error_code": { + "type": [ + "string", + "null" + ], + "description": "The provider's error code, or why the pull has no definite answer." + }, + "credited": { + "type": "boolean", + "description": "Always `false` for now: a pull `completed` at the provider is not yet credited in the wallet." + }, + "replayed": { + "type": "boolean", + "description": "`true` when the answer is a pull an earlier request with the same key created." + }, + "created_at": { + "type": "string" + }, + "updated_at": { + "type": "string" + } + }, + "required": [ + "id", + "consent_id", + "consumer_id", + "wallet_id", + "provider", + "amount_minor", + "currency", + "status", + "provider_status", + "end_to_end_id", + "error_code", + "credited", + "replayed", + "created_at", + "updated_at" + ] + } + } + }, + "required": [ + "sweep_pulls" + ] + } + } + } + }, + "400": { + "description": "The query did not match the schema.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "invalid_query" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "403": { + "description": "The key does not carry the `wallets:read` scope. Bare body; nothing was read or written.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string", + "enum": [ + "forbidden" + ] + }, + "message": { + "type": "string" + }, + "status": { + "type": "number", + "enum": [ + 403 + ] + } + }, + "required": [ + "error", + "message", + "status" + ] + } + } + } + } + }, + "x-codespar-scope": "wallets:read", + "security": [ + { + "bearerAuth": [ + "wallets:read" + ] + } + ] + } + }, + "/v1/ofb/sweeping/pulls/{id}": { + "get": { + "summary": "Read one sweeping pull", + "description": "While the pull is not terminal, the provider is read and the pull moves forward with it; a terminal pull is answered as stored. A read never sends a pull again: that is the create retry's job.\n\nRequires the `wallets:read` scope.", + "parameters": [ + { + "schema": { + "type": "string", + "description": "`swp_`-prefixed sweeping pull id." + }, + "required": true, + "description": "`swp_`-prefixed sweeping pull id.", + "name": "id", + "in": "path" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "`swp_`-prefixed." + }, + "consent_id": { + "type": "string", + "description": "The `ofb_`-prefixed sweeping consent the pull ran under." + }, + "consumer_id": { + "type": "string" + }, + "wallet_id": { + "type": "string" + }, + "provider": { + "type": "string", + "enum": [ + "iniciador", + "celcoin-itp" + ] + }, + "amount_minor": { + "type": "integer", + "description": "In centavos." + }, + "currency": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "pending", + "settling", + "completed", + "rejected", + "expired", + "canceled", + "failed", + "unknown" + ], + "description": "`pending` while the provider processes it, `settling` once the Pix is on its way, then a terminal `completed`, `rejected`, `expired`, `canceled` (the provider refused it when it was sent) or `failed` (the provider reported an error). `unknown`: no definite answer yet; retry the create with the same `Idempotency-Key`. It only moves forward." + }, + "provider_status": { + "type": [ + "string", + "null" + ], + "description": "The provider's own status, as it reported it. On a read, a status this API does not map yet is shown here while `status` stays as stored." + }, + "end_to_end_id": { + "type": [ + "string", + "null" + ], + "description": "The Pix end-to-end id, once the provider reports it." + }, + "error_code": { + "type": [ + "string", + "null" + ], + "description": "The provider's error code, or why the pull has no definite answer." + }, + "credited": { + "type": "boolean", + "description": "Always `false` for now: a pull `completed` at the provider is not yet credited in the wallet." + }, + "replayed": { + "type": "boolean", + "description": "`true` when the answer is a pull an earlier request with the same key created." + }, + "created_at": { + "type": "string" + }, + "updated_at": { + "type": "string" + } + }, + "required": [ + "id", + "consent_id", + "consumer_id", + "wallet_id", + "provider", + "amount_minor", + "currency", + "status", + "provider_status", + "end_to_end_id", + "error_code", + "credited", + "replayed", + "created_at", + "updated_at" + ] + } + } + } + }, + "403": { + "description": "The key does not carry the `wallets:read` scope. Bare body; nothing was read or written.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string", + "enum": [ + "forbidden" + ] + }, + "message": { + "type": "string" + }, + "status": { + "type": "number", + "enum": [ + 403 + ] + } + }, + "required": [ + "error", + "message", + "status" + ] + } + } + } + }, + "404": { + "description": "Not Found. No sweeping pull with this id in the caller's project.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "not_found" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "422": { + "description": "The project is live. Sweeping serves test projects only, against the provider's sandbox (`details.reason` `live_not_enabled`).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "ofb_not_live" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "502": { + "description": "The provider refused the read.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "sweep_provider_refused" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "503": { + "description": "No definite answer from the provider (`sweep_provider_ambiguous`, retriable), or the deployment cannot reach a sweeping provider (`ofb_adapter_unavailable`).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "sweep_provider_ambiguous", + "ofb_adapter_unavailable" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + } + }, + "x-codespar-scope": "wallets:read", + "security": [ + { + "bearerAuth": [ + "wallets:read" + ] + } + ] + } + }, + "/v1/ofb/jsr/enrollments": { + "post": { + "summary": "Register a passkey for Pix com biometria", + "description": "Opens an enrollment at the bank for the consumer's own account and answers `approval_url`, the hosted page where the person registers a passkey on their device. The page expires about a minute after it is made: call this only with the person about to open it, and open a new enrollment if it expired (the old one ends `rejected` on its own). It carries a credential of its own: hand it to the person and to no log. The API keeps it nowhere.\n\nRequires the `consents:write` scope. Test projects only.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "consumer_id": { + "type": "string", + "minLength": 1, + "maxLength": 128 + }, + "wallet_id": { + "type": "string", + "minLength": 1, + "maxLength": 128 + }, + "funding_source_id": { + "type": "string", + "minLength": 1, + "maxLength": 128 + }, + "participant_id": { + "type": "string", + "format": "uuid" + }, + "device_context": { + "type": "object", + "properties": { + "os_version": { + "type": "string", + "minLength": 1, + "maxLength": 64 + }, + "user_time_zone_offset": { + "type": "string", + "pattern": "^[+-][0-9]{2}(:?[0-9]{2})?$" + }, + "language": { + "type": "string", + "minLength": 2, + "maxLength": 16 + }, + "screen_dimensions": { + "type": "object", + "properties": { + "width": { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 100000 + }, + "height": { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 100000 + } + }, + "required": [ + "width", + "height" + ], + "additionalProperties": false + }, + "account_tenure": { + "type": "string", + "format": "date" + } + }, + "required": [ + "os_version", + "user_time_zone_offset", + "language", + "screen_dimensions", + "account_tenure" + ], + "additionalProperties": false + } + }, + "required": [ + "consumer_id", + "wallet_id", + "funding_source_id", + "participant_id", + "device_context" + ], + "additionalProperties": false + } + } + } + }, + "responses": { + "201": { + "description": "The enrollment, `pending`, with the page to open now.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "`ofb_`-prefixed." + }, + "consumer_id": { + "type": "string" + }, + "wallet_id": { + "type": [ + "string", + "null" + ] + }, + "funding_source_id": { + "type": [ + "string", + "null" + ] + }, + "participant_id": { + "type": "string", + "description": "The bank, as the provider's participant id." + }, + "provider": { + "type": "string", + "enum": [ + "iniciador" + ] + }, + "status": { + "type": "string", + "enum": [ + "pending", + "authorised", + "revoked", + "rejected", + "expired", + "canceled" + ], + "description": "`pending` until the person registers the passkey on the hosted page, then `authorised`; terminal `rejected` (not registered in its window, or revoked before it was), `revoked`, `expired`, or `canceled` (the provider failed while it was being opened). It only moves forward." + }, + "debtor": { + "type": [ + "object", + "null" + ], + "properties": { + "ispb": { + "type": [ + "string", + "null" + ] + }, + "account_masked": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "ispb", + "account_masked" + ], + "description": "The bank account the enrollment is bound to, once authorised." + }, + "bank_transaction_limit_minor": { + "type": [ + "integer", + "null" + ], + "description": "The bank's per-transaction limit in centavos, as the provider reports it. The bank enforces it." + }, + "created_at": { + "type": "string" + }, + "authorized_at": { + "type": [ + "string", + "null" + ] + }, + "expires_at": { + "type": [ + "string", + "null" + ] + }, + "revoked_at": { + "type": [ + "string", + "null" + ] + }, + "approval_url": { + "type": "string", + "description": "It carries a credential of its own: hand it to the person and to no log. The API keeps it nowhere." + } + }, + "required": [ + "id", + "consumer_id", + "wallet_id", + "funding_source_id", + "participant_id", + "provider", + "status", + "debtor", + "bank_transaction_limit_minor", + "created_at", + "authorized_at", + "expires_at", + "revoked_at", + "approval_url" + ] + } + } + } + }, + "400": { + "description": "The body did not match the schema.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "invalid_body" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "403": { + "description": "The key does not carry the `consents:write` scope. Bare body; nothing was read or written.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string", + "enum": [ + "forbidden" + ] + }, + "message": { + "type": "string" + }, + "status": { + "type": "number", + "enum": [ + 403 + ] + } + }, + "required": [ + "error", + "message", + "status" + ] + } + } + } + }, + "422": { + "description": "Not live, or the destination cannot receive a payment (`jsr_destination_unresolved`, `details.reason`).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "ofb_not_live", + "jsr_destination_unresolved" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "502": { + "description": "The provider refused (`jsr_provider_refused`). `details.provider_code` is its own code; its free text is never relayed.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "jsr_provider_refused" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "503": { + "description": "No definite answer from the provider (`jsr_provider_ambiguous`), or the deployment has no JSR provider credentials (`ofb_adapter_unavailable`).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "jsr_provider_ambiguous", + "ofb_adapter_unavailable" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + } + }, + "x-codespar-scope": "consents:write", + "security": [ + { + "bearerAuth": [ + "consents:write" + ] + } + ] + }, + "get": { + "summary": "List JSR enrollments", + "description": "The project's enrollments, most recent first, as stored.\n\nRequires the `consents:read` scope.", + "parameters": [ + { + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 200, + "default": 50 + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 128 + }, + "required": false, + "name": "consumer_id", + "in": "query" + }, + { + "schema": { + "type": "string", + "enum": [ + "pending", + "authorised", + "revoked", + "rejected", + "expired", + "canceled" + ] + }, + "required": false, + "name": "status", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "jsr_enrollments": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "`ofb_`-prefixed." + }, + "consumer_id": { + "type": "string" + }, + "wallet_id": { + "type": [ + "string", + "null" + ] + }, + "funding_source_id": { + "type": [ + "string", + "null" + ] + }, + "participant_id": { + "type": "string", + "description": "The bank, as the provider's participant id." + }, + "provider": { + "type": "string", + "enum": [ + "iniciador" + ] + }, + "status": { + "type": "string", + "enum": [ + "pending", + "authorised", + "revoked", + "rejected", + "expired", + "canceled" + ], + "description": "`pending` until the person registers the passkey on the hosted page, then `authorised`; terminal `rejected` (not registered in its window, or revoked before it was), `revoked`, `expired`, or `canceled` (the provider failed while it was being opened). It only moves forward." + }, + "debtor": { + "type": [ + "object", + "null" + ], + "properties": { + "ispb": { + "type": [ + "string", + "null" + ] + }, + "account_masked": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "ispb", + "account_masked" + ], + "description": "The bank account the enrollment is bound to, once authorised." + }, + "bank_transaction_limit_minor": { + "type": [ + "integer", + "null" + ], + "description": "The bank's per-transaction limit in centavos, as the provider reports it. The bank enforces it." + }, + "created_at": { + "type": "string" + }, + "authorized_at": { + "type": [ + "string", + "null" + ] + }, + "expires_at": { + "type": [ + "string", + "null" + ] + }, + "revoked_at": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "id", + "consumer_id", + "wallet_id", + "funding_source_id", + "participant_id", + "provider", + "status", + "debtor", + "bank_transaction_limit_minor", + "created_at", + "authorized_at", + "expires_at", + "revoked_at" + ] + } + } + }, + "required": [ + "jsr_enrollments" + ] + } + } + } + }, + "400": { + "description": "The query did not match the schema.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "invalid_query" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "403": { + "description": "The key does not carry the `consents:read` scope. Bare body; nothing was read or written.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string", + "enum": [ + "forbidden" + ] + }, + "message": { + "type": "string" + }, + "status": { + "type": "number", + "enum": [ + 403 + ] + } + }, + "required": [ + "error", + "message", + "status" + ] + } + } + } + } + }, + "x-codespar-scope": "consents:read", + "security": [ + { + "bearerAuth": [ + "consents:read" + ] + } + ] + } + }, + "/v1/ofb/jsr/enrollments/{id}": { + "get": { + "summary": "Read one JSR enrollment", + "description": "While not terminal, the provider is read and the enrollment moves forward with it.\n\nRequires the `consents:read` scope.", + "parameters": [ + { + "schema": { + "type": "string" + }, + "required": true, + "name": "id", + "in": "path" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "`ofb_`-prefixed." + }, + "consumer_id": { + "type": "string" + }, + "wallet_id": { + "type": [ + "string", + "null" + ] + }, + "funding_source_id": { + "type": [ + "string", + "null" + ] + }, + "participant_id": { + "type": "string", + "description": "The bank, as the provider's participant id." + }, + "provider": { + "type": "string", + "enum": [ + "iniciador" + ] + }, + "status": { + "type": "string", + "enum": [ + "pending", + "authorised", + "revoked", + "rejected", + "expired", + "canceled" + ], + "description": "`pending` until the person registers the passkey on the hosted page, then `authorised`; terminal `rejected` (not registered in its window, or revoked before it was), `revoked`, `expired`, or `canceled` (the provider failed while it was being opened). It only moves forward." + }, + "debtor": { + "type": [ + "object", + "null" + ], + "properties": { + "ispb": { + "type": [ + "string", + "null" + ] + }, + "account_masked": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "ispb", + "account_masked" + ], + "description": "The bank account the enrollment is bound to, once authorised." + }, + "bank_transaction_limit_minor": { + "type": [ + "integer", + "null" + ], + "description": "The bank's per-transaction limit in centavos, as the provider reports it. The bank enforces it." + }, + "created_at": { + "type": "string" + }, + "authorized_at": { + "type": [ + "string", + "null" + ] + }, + "expires_at": { + "type": [ + "string", + "null" + ] + }, + "revoked_at": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "id", + "consumer_id", + "wallet_id", + "funding_source_id", + "participant_id", + "provider", + "status", + "debtor", + "bank_transaction_limit_minor", + "created_at", + "authorized_at", + "expires_at", + "revoked_at" + ] + } + } + } + }, + "403": { + "description": "The key does not carry the `consents:read` scope. Bare body; nothing was read or written.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string", + "enum": [ + "forbidden" + ] + }, + "message": { + "type": "string" + }, + "status": { + "type": "number", + "enum": [ + 403 + ] + } + }, + "required": [ + "error", + "message", + "status" + ] + } + } + } + }, + "404": { + "description": "No JSR enrollment with this id in the caller's project.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "not_found" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "422": { + "description": "The project is live. JSR serves test projects only, against the provider's sandbox (`details.reason` `live_not_enabled`).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "ofb_not_live" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "502": { + "description": "The provider refused (`jsr_provider_refused`). `details.provider_code` is its own code; its free text is never relayed.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "jsr_provider_refused" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "503": { + "description": "No definite answer from the provider (`jsr_provider_ambiguous`), or the deployment has no JSR provider credentials (`ofb_adapter_unavailable`).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "jsr_provider_ambiguous", + "ofb_adapter_unavailable" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + } + }, + "x-codespar-scope": "consents:read", + "security": [ + { + "bearerAuth": [ + "consents:read" + ] + } + ] + } + }, + "/v1/ofb/jsr/enrollments/{id}/revoke": { + "post": { + "summary": "Revoke a JSR enrollment", + "description": "Revokes the enrollment at the provider, then here: `revoked`, or `rejected` for one never authorised. Deleting the passkey on the device does not revoke it.\n\nRequires the `consents:write` scope.", + "parameters": [ + { + "schema": { + "type": "string" + }, + "required": true, + "name": "id", + "in": "path" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "reason": { + "type": "string", + "minLength": 1, + "maxLength": 512, + "description": "Recorded on this API's own consent event. Not sent to the provider: no reason field of its revoke is known." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "`ofb_`-prefixed." + }, + "consumer_id": { + "type": "string" + }, + "wallet_id": { + "type": [ + "string", + "null" + ] + }, + "funding_source_id": { + "type": [ + "string", + "null" + ] + }, + "participant_id": { + "type": "string", + "description": "The bank, as the provider's participant id." + }, + "provider": { + "type": "string", + "enum": [ + "iniciador" + ] + }, + "status": { + "type": "string", + "enum": [ + "pending", + "authorised", + "revoked", + "rejected", + "expired", + "canceled" + ], + "description": "`pending` until the person registers the passkey on the hosted page, then `authorised`; terminal `rejected` (not registered in its window, or revoked before it was), `revoked`, `expired`, or `canceled` (the provider failed while it was being opened). It only moves forward." + }, + "debtor": { + "type": [ + "object", + "null" + ], + "properties": { + "ispb": { + "type": [ + "string", + "null" + ] + }, + "account_masked": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "ispb", + "account_masked" + ], + "description": "The bank account the enrollment is bound to, once authorised." + }, + "bank_transaction_limit_minor": { + "type": [ + "integer", + "null" + ], + "description": "The bank's per-transaction limit in centavos, as the provider reports it. The bank enforces it." + }, + "created_at": { + "type": "string" + }, + "authorized_at": { + "type": [ + "string", + "null" + ] + }, + "expires_at": { + "type": [ + "string", + "null" + ] + }, + "revoked_at": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "id", + "consumer_id", + "wallet_id", + "funding_source_id", + "participant_id", + "provider", + "status", + "debtor", + "bank_transaction_limit_minor", + "created_at", + "authorized_at", + "expires_at", + "revoked_at" + ] + } + } + } + }, + "400": { + "description": "The body did not match the schema.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "invalid_body" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "403": { + "description": "The key does not carry the `consents:write` scope. Bare body; nothing was read or written.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string", + "enum": [ + "forbidden" + ] + }, + "message": { + "type": "string" + }, + "status": { + "type": "number", + "enum": [ + 403 + ] + } + }, + "required": [ + "error", + "message", + "status" + ] + } + } + } + }, + "404": { + "description": "No JSR enrollment with this id in the caller's project.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "not_found" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "409": { + "description": "Terminal already, or still being opened (`details.in_flight`).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "illegal_transition" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "422": { + "description": "The project is live. JSR serves test projects only, against the provider's sandbox (`details.reason` `live_not_enabled`).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "ofb_not_live" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "502": { + "description": "The provider refused (`jsr_provider_refused`). `details.provider_code` is its own code; its free text is never relayed.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "jsr_provider_refused" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "503": { + "description": "No definite answer from the provider (`jsr_provider_ambiguous`), or the deployment has no JSR provider credentials (`ofb_adapter_unavailable`).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "jsr_provider_ambiguous", + "ofb_adapter_unavailable" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + } + }, + "x-codespar-scope": "consents:write", + "security": [ + { + "bearerAuth": [ + "consents:write" + ] + } + ] + } + }, + "/v1/ofb/jsr/payments": { + "post": { + "summary": "Pay from the consumer's bank with Pix com biometria", + "description": "Creates a Pix from the consumer's bank account into their own Celcoin account under an `authorised` enrollment, and answers `approval_url`, the hosted page where the person signs it with the passkey. Unsigned, the bank ends it `rejected` in about ten minutes (`signature_timed_out`); it is never sent again, and a new approval is a new payment with a new key.\n\nThe provider binds a payment to the holder's newest authorised enrollment at that bank. A payment is refused before it is sent unless the named enrollment is that one (`jsr_enrollment_not_newest`), and one bound to another anyway is kept with `needs_human`, its page withheld (`jsr_enrollment_mismatch`).\n\nThe `Idempotency-Key` header is required. It carries a credential of its own: hand it to the person and to no log. The API keeps it nowhere.\n\nRequires the `wallets:admin` scope. Test projects only.", + "parameters": [ + { + "schema": { + "type": "string", + "maxLength": 255, + "description": "Required. The same key on every retry of the same payment." + }, + "required": true, + "description": "Required. The same key on every retry of the same payment.", + "name": "Idempotency-Key", + "in": "header" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "enrollment_id": { + "type": "string", + "minLength": 1, + "maxLength": 128 + }, + "amount_minor": { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 + }, + "description": { + "type": "string", + "minLength": 1, + "maxLength": 100 + } + }, + "required": [ + "enrollment_id", + "amount_minor" + ], + "additionalProperties": false + } + } + } + }, + "responses": { + "200": { + "description": "A replay of the payment the same key created (`replayed: true`).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "`swp_`-prefixed: a JSR payment is a pull, credited as one." + }, + "enrollment_id": { + "type": "string" + }, + "consumer_id": { + "type": "string" + }, + "wallet_id": { + "type": "string" + }, + "provider": { + "type": "string", + "enum": [ + "iniciador" + ] + }, + "amount_minor": { + "type": "integer", + "description": "In centavos." + }, + "currency": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "pending", + "settling", + "completed", + "rejected", + "expired", + "canceled", + "failed", + "unknown" + ], + "description": "`pending` until the person signs it and the bank settles it, then `completed`; `rejected` when nobody signed it in time (`signature_timed_out`) or the bank refused it; `canceled` when the provider refused the create. `unknown`: no definite answer, or bound to another enrollment (`needs_human`)." + }, + "provider_status": { + "type": [ + "string", + "null" + ] + }, + "end_to_end_id": { + "type": [ + "string", + "null" + ], + "description": "The Pix end-to-end id. Assigned at create, so a rejected payment has one too: only `completed` moved money." + }, + "error_code": { + "type": [ + "string", + "null" + ] + }, + "signature_timed_out": { + "type": "boolean", + "description": "The bank ended it because the person did not sign within about ten minutes (TIMEOUT_CONSENTIMENTO)." + }, + "needs_human": { + "type": "boolean", + "description": "A person must check it at the provider: it is never sent again." + }, + "approval_url": { + "type": [ + "string", + "null" + ], + "description": "The hosted page where the person signs this payment with the passkey, while it waits for that. Handed only to a key with `wallets:admin`. It carries a credential of its own: hand it to the person and to no log. The API keeps it nowhere." + }, + "approval_url_withheld": { + "type": "boolean", + "description": "The payment waits for a signature, and the key reading it lacks `wallets:admin`: the signing page authorises a debit, so it is not handed to a read-only key." + }, + "credited": { + "type": "boolean", + "description": "Always `false` for now: a completed payment is not yet credited in the wallet." + }, + "replayed": { + "type": "boolean" + }, + "created_at": { + "type": "string" + }, + "updated_at": { + "type": "string" + } + }, + "required": [ + "id", + "enrollment_id", + "consumer_id", + "wallet_id", + "provider", + "amount_minor", + "currency", + "status", + "provider_status", + "end_to_end_id", + "error_code", + "signature_timed_out", + "needs_human", + "approval_url", + "approval_url_withheld", + "credited", + "replayed", + "created_at", + "updated_at" + ] + } + } + } + }, + "202": { + "description": "The payment was written and created at the provider; the person signs it at `approval_url`.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "`swp_`-prefixed: a JSR payment is a pull, credited as one." + }, + "enrollment_id": { + "type": "string" + }, + "consumer_id": { + "type": "string" + }, + "wallet_id": { + "type": "string" + }, + "provider": { + "type": "string", + "enum": [ + "iniciador" + ] + }, + "amount_minor": { + "type": "integer", + "description": "In centavos." + }, + "currency": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "pending", + "settling", + "completed", + "rejected", + "expired", + "canceled", + "failed", + "unknown" + ], + "description": "`pending` until the person signs it and the bank settles it, then `completed`; `rejected` when nobody signed it in time (`signature_timed_out`) or the bank refused it; `canceled` when the provider refused the create. `unknown`: no definite answer, or bound to another enrollment (`needs_human`)." + }, + "provider_status": { + "type": [ + "string", + "null" + ] + }, + "end_to_end_id": { + "type": [ + "string", + "null" + ], + "description": "The Pix end-to-end id. Assigned at create, so a rejected payment has one too: only `completed` moved money." + }, + "error_code": { + "type": [ + "string", + "null" + ] + }, + "signature_timed_out": { + "type": "boolean", + "description": "The bank ended it because the person did not sign within about ten minutes (TIMEOUT_CONSENTIMENTO)." + }, + "needs_human": { + "type": "boolean", + "description": "A person must check it at the provider: it is never sent again." + }, + "approval_url": { + "type": [ + "string", + "null" + ], + "description": "The hosted page where the person signs this payment with the passkey, while it waits for that. Handed only to a key with `wallets:admin`. It carries a credential of its own: hand it to the person and to no log. The API keeps it nowhere." + }, + "approval_url_withheld": { + "type": "boolean", + "description": "The payment waits for a signature, and the key reading it lacks `wallets:admin`: the signing page authorises a debit, so it is not handed to a read-only key." + }, + "credited": { + "type": "boolean", + "description": "Always `false` for now: a completed payment is not yet credited in the wallet." + }, + "replayed": { + "type": "boolean" + }, + "created_at": { + "type": "string" + }, + "updated_at": { + "type": "string" + } + }, + "required": [ + "id", + "enrollment_id", + "consumer_id", + "wallet_id", + "provider", + "amount_minor", + "currency", + "status", + "provider_status", + "end_to_end_id", + "error_code", + "signature_timed_out", + "needs_human", + "approval_url", + "approval_url_withheld", + "credited", + "replayed", + "created_at", + "updated_at" + ] + } + } + } + }, + "400": { + "description": "The body did not match the schema, or the `Idempotency-Key` header is missing (`jsr_idempotency_key_required`) or too long (`invalid_idempotency_key`).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "invalid_body", + "jsr_idempotency_key_required", + "invalid_idempotency_key" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "403": { + "description": "The key does not carry the `wallets:admin` scope. Bare body; nothing was read or written.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string", + "enum": [ + "forbidden" + ] + }, + "message": { + "type": "string" + }, + "status": { + "type": "number", + "enum": [ + 403 + ] + } + }, + "required": [ + "error", + "message", + "status" + ] + } + } + } + }, + "404": { + "description": "No JSR enrollment with this id in the caller's project.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "not_found" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "409": { + "description": "The enrollment cannot carry a payment (`jsr_enrollment_not_authorised`), is not the one the provider would bind it to (`jsr_enrollment_not_newest`), the provider bound it to another (`jsr_enrollment_mismatch`, `needs_human`), the key created another payment (`idempotency_key_conflict`), is still sending it (`jsr_payment_in_flight`), or sent it with no definite answer (`jsr_payment_unresolved`, `needs_human`).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "jsr_enrollment_not_authorised", + "jsr_enrollment_not_newest", + "jsr_enrollment_mismatch", + "idempotency_key_conflict", + "jsr_payment_in_flight", + "jsr_payment_unresolved" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "422": { + "description": "Not live, above a limit (`jsr_limit_exceeded`: the test ceiling of R$ 100 per payment and R$ 1.000 per enrollment, `details.source` `platform_test`, or the bank's per-transaction limit, `bank`), or the destination cannot receive it (`jsr_destination_unresolved`).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "ofb_not_live", + "jsr_limit_exceeded", + "jsr_destination_unresolved" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "502": { + "description": "The provider refused (`jsr_provider_refused`). `details.provider_code` is its own code; its free text is never relayed.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "jsr_provider_refused" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "503": { + "description": "No definite answer from the provider (`jsr_provider_ambiguous`), or the deployment has no JSR provider credentials (`ofb_adapter_unavailable`).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "jsr_provider_ambiguous", + "ofb_adapter_unavailable" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + } + }, + "x-codespar-scope": "wallets:admin", + "security": [ + { + "bearerAuth": [ + "wallets:admin" + ] + } + ] + }, + "get": { + "summary": "List JSR payments", + "description": "The project's JSR payments, most recent first, as stored; no signing page.\n\nRequires the `wallets:read` scope.", + "parameters": [ + { + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 200, + "default": 50 + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 128 + }, + "required": false, + "name": "enrollment_id", + "in": "query" + }, + { + "schema": { + "type": "string", + "enum": [ + "pending", + "settling", + "completed", + "rejected", + "expired", + "canceled", + "failed", + "unknown" + ] + }, + "required": false, + "name": "status", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "jsr_payments": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "`swp_`-prefixed: a JSR payment is a pull, credited as one." + }, + "enrollment_id": { + "type": "string" + }, + "consumer_id": { + "type": "string" + }, + "wallet_id": { + "type": "string" + }, + "provider": { + "type": "string", + "enum": [ + "iniciador" + ] + }, + "amount_minor": { + "type": "integer", + "description": "In centavos." + }, + "currency": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "pending", + "settling", + "completed", + "rejected", + "expired", + "canceled", + "failed", + "unknown" + ], + "description": "`pending` until the person signs it and the bank settles it, then `completed`; `rejected` when nobody signed it in time (`signature_timed_out`) or the bank refused it; `canceled` when the provider refused the create. `unknown`: no definite answer, or bound to another enrollment (`needs_human`)." + }, + "provider_status": { + "type": [ + "string", + "null" + ] + }, + "end_to_end_id": { + "type": [ + "string", + "null" + ], + "description": "The Pix end-to-end id. Assigned at create, so a rejected payment has one too: only `completed` moved money." + }, + "error_code": { + "type": [ + "string", + "null" + ] + }, + "signature_timed_out": { + "type": "boolean", + "description": "The bank ended it because the person did not sign within about ten minutes (TIMEOUT_CONSENTIMENTO)." + }, + "needs_human": { + "type": "boolean", + "description": "A person must check it at the provider: it is never sent again." + }, + "approval_url": { + "type": [ + "string", + "null" + ], + "description": "The hosted page where the person signs this payment with the passkey, while it waits for that. Handed only to a key with `wallets:admin`. It carries a credential of its own: hand it to the person and to no log. The API keeps it nowhere." + }, + "approval_url_withheld": { + "type": "boolean", + "description": "The payment waits for a signature, and the key reading it lacks `wallets:admin`: the signing page authorises a debit, so it is not handed to a read-only key." + }, + "credited": { + "type": "boolean", + "description": "Always `false` for now: a completed payment is not yet credited in the wallet." + }, + "replayed": { + "type": "boolean" + }, + "created_at": { + "type": "string" + }, + "updated_at": { + "type": "string" + } + }, + "required": [ + "id", + "enrollment_id", + "consumer_id", + "wallet_id", + "provider", + "amount_minor", + "currency", + "status", + "provider_status", + "end_to_end_id", + "error_code", + "signature_timed_out", + "needs_human", + "approval_url", + "approval_url_withheld", + "credited", + "replayed", + "created_at", + "updated_at" + ] + } + } + }, + "required": [ + "jsr_payments" + ] + } + } + } + }, + "400": { + "description": "The query did not match the schema.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "invalid_query" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "403": { + "description": "The key does not carry the `wallets:read` scope. Bare body; nothing was read or written.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string", + "enum": [ + "forbidden" + ] + }, + "message": { + "type": "string" + }, + "status": { + "type": "number", + "enum": [ + 403 + ] + } + }, + "required": [ + "error", + "message", + "status" + ] + } + } + } + } + }, + "x-codespar-scope": "wallets:read", + "security": [ + { + "bearerAuth": [ + "wallets:read" + ] + } + ] + } + }, + "/v1/ofb/jsr/payments/{id}": { + "get": { + "summary": "Read one JSR payment", + "description": "While not terminal, the provider is read and the payment moves forward with it. While the payment waits for the signature, `approval_url` is the signing page again for a key with `wallets:admin`; a key with only `wallets:read` gets `approval_url: null` and `approval_url_withheld: true`. A payment left `pending` with no provider id past the longest a create can take is parked `unknown` with `error_code` `lost_send` and `needs_human`.\n\nRequires the `wallets:read` scope.", + "parameters": [ + { + "schema": { + "type": "string" + }, + "required": true, + "name": "id", + "in": "path" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "`swp_`-prefixed: a JSR payment is a pull, credited as one." + }, + "enrollment_id": { + "type": "string" + }, + "consumer_id": { + "type": "string" + }, + "wallet_id": { + "type": "string" + }, + "provider": { + "type": "string", + "enum": [ + "iniciador" + ] + }, + "amount_minor": { + "type": "integer", + "description": "In centavos." + }, + "currency": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "pending", + "settling", + "completed", + "rejected", + "expired", + "canceled", + "failed", + "unknown" + ], + "description": "`pending` until the person signs it and the bank settles it, then `completed`; `rejected` when nobody signed it in time (`signature_timed_out`) or the bank refused it; `canceled` when the provider refused the create. `unknown`: no definite answer, or bound to another enrollment (`needs_human`)." + }, + "provider_status": { + "type": [ + "string", + "null" + ] + }, + "end_to_end_id": { + "type": [ + "string", + "null" + ], + "description": "The Pix end-to-end id. Assigned at create, so a rejected payment has one too: only `completed` moved money." + }, + "error_code": { + "type": [ + "string", + "null" + ] + }, + "signature_timed_out": { + "type": "boolean", + "description": "The bank ended it because the person did not sign within about ten minutes (TIMEOUT_CONSENTIMENTO)." + }, + "needs_human": { + "type": "boolean", + "description": "A person must check it at the provider: it is never sent again." + }, + "approval_url": { + "type": [ + "string", + "null" + ], + "description": "The hosted page where the person signs this payment with the passkey, while it waits for that. Handed only to a key with `wallets:admin`. It carries a credential of its own: hand it to the person and to no log. The API keeps it nowhere." + }, + "approval_url_withheld": { + "type": "boolean", + "description": "The payment waits for a signature, and the key reading it lacks `wallets:admin`: the signing page authorises a debit, so it is not handed to a read-only key." + }, + "credited": { + "type": "boolean", + "description": "Always `false` for now: a completed payment is not yet credited in the wallet." + }, + "replayed": { + "type": "boolean" + }, + "created_at": { + "type": "string" + }, + "updated_at": { + "type": "string" + } + }, + "required": [ + "id", + "enrollment_id", + "consumer_id", + "wallet_id", + "provider", + "amount_minor", + "currency", + "status", + "provider_status", + "end_to_end_id", + "error_code", + "signature_timed_out", + "needs_human", + "approval_url", + "approval_url_withheld", + "credited", + "replayed", + "created_at", + "updated_at" + ] + } + } + } + }, + "403": { + "description": "The key does not carry the `wallets:read` scope. Bare body; nothing was read or written.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string", + "enum": [ + "forbidden" + ] + }, + "message": { + "type": "string" + }, + "status": { + "type": "number", + "enum": [ + 403 + ] + } + }, + "required": [ + "error", + "message", + "status" + ] + } + } + } + }, + "404": { + "description": "No JSR payment with this id in the caller's project.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "not_found" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "422": { + "description": "The project is live. JSR serves test projects only, against the provider's sandbox (`details.reason` `live_not_enabled`).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "ofb_not_live" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "502": { + "description": "The provider refused (`jsr_provider_refused`). `details.provider_code` is its own code; its free text is never relayed.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "jsr_provider_refused" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "503": { + "description": "No definite answer from the provider (`jsr_provider_ambiguous`), or the deployment has no JSR provider credentials (`ofb_adapter_unavailable`).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "jsr_provider_ambiguous", + "ofb_adapter_unavailable" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + } + }, + "x-codespar-scope": "wallets:read", + "security": [ + { + "bearerAuth": [ + "wallets:read" + ] + } + ] + } + }, "/v1/fees": { "get": { "summary": "Which rate-card lanes are measured and charged for this org", @@ -25975,7 +32599,7 @@ "/v1/health": { "get": { "summary": "Read graded dependency health, as this credential's tenant sees it", - "description": "Dependency checks and the schema version, graded into one `status`. The checks run in parallel behind a three-second budget each; one that throws or times out is reported in its own failed shape with `message` carrying the reason, and the response still carries the others. So the operation is expected back in under four seconds however badly the database is behaving.\n\nEVERY CHECK SAYS WHAT IT MEASURED AND WHAT THAT MEANS HERE. Its own `status` keeps its vocabulary; beside it, `state` separates a real failure from pending configuration, from no activity, and from a feature not in use, with `required`, a `reason` code and, where something has to be set up, an `action`. A new account with no integration, no provider call and no FX quote reads `healthy`, with `connections` pending configuration.\n\nGRADE ON `status`, AND READ THE RULE BEFORE WRITING THE ALERT. Only `state: failure` grades. `down` means `db` or `vault` fails. `degraded` means any other check fails, which today is one of: the tool catalog is not loaded (`tool_catalog`), a USD/BRL quote the router needs is missing, stale or unreadable (`fx_rates`; no deployment needs one until the router normalizes cost across currencies, and until then the quote is `not_in_use` whatever its age), a live Celcoin connection lacks a webhook subscription (`celcoin_webhook_subscriptions`), or a Pix Automático worker with work to do is stale, failing or never ran (`recurrence_holds`, `recurrence_scheduler`, including a hold past its time), or a BolePix paid twice has had its refund owed for longer than 3 days (`bolepix_refunds`), or this production process has no working tool strategy and refuses every meta-tool call with 503 `tool_strategy_unavailable` (`tool_strategy`; reads, authentication and webhooks keep working). Everything else grades `healthy`. `attention` lists the failing checks and the ones pending configuration by name.\n\n`metrics` IS READ, NEVER GRADED. `metrics.recurrence_instruction_alarms` counts the Pix Automático instruction alarms still open on a cycle still ahead, per kind and reason, for the calling org: a cycle not announced, an instruction refused, held back by a ceiling, or queued and expired. Each alarm already reached its tenant as an event in the recurrence's project; this is the standing number, and it never moves `status`.\n\nNON-NOMINAL MEASUREMENTS THAT DO NOT MOVE THE GRADE, and an alert that wants them has to read the field rather than the grade: `embeddings.status` `low` or `empty` (discovery answers from its keyword fallback), `connections.status` `partial` or `none`, `telemetry.status` `idle` or `stale` (no provider call is no activity, not a fault), and `fx_rates.status` `stale` or `missing` while no quote is needed. None of them stops a call from being served.\n\nONLY HALF OF ONE CHECK IS PER TENANT. `connections.connected` counts connections in the calling credential's own org and project. `connections.total_servers` counts every active provider in the catalog and is the same number for every reader, so the ratio between them is not a tenant completion percentage.\n\nTHIS READ WRITES, and the write is observable. Each call stores a snapshot of its own result against the calling org, and when the grade differs from the previous snapshot's it publishes `system.health.degraded` or `system.health.recovered` into the calling project, carrying a field-by-field diff of what moved. Anything subscribed to those event types in that project fires. Polling this endpoint therefore has side effects, and two monitors polling the same org write into one shared snapshot history — a transition either of them causes is seen once, by whoever's call crossed it. Where the 30-day history is switched on, each call also counts one observation in `GET /v1/health/history` for the calling org, so a monitor polling this endpoint moves that history too.\n\nTHE HANDLER ANSWERS 200 FOR EVERY STATE IT GRADES, `down` included: a dead dependency is reported in the body and never mapped onto an HTTP status. That is why the map below has one entry. It is not a promise that nothing else can come back. Three things produce a non-200 here and none of them is a grade: a credential that does not authenticate, a credential whose grants do not cover this read — both refused before the handler runs, and neither described in the map below, because the answer to them is the same on every operation the same door guards — and a refusal of the snapshot write above, which is a defect on our side rather than a dependency being down. Alert on `status`. A non-200 is a bug report, and which of the three it is decides who should be reading it.", + "description": "Dependency checks and the schema version, graded into one `status`. The checks run in parallel behind a three-second budget each; one that throws or times out is reported in its own failed shape with `message` carrying the reason, and the response still carries the others. So the operation is expected back in under four seconds however badly the database is behaving.\n\nEVERY CHECK SAYS WHAT IT MEASURED AND WHAT THAT MEANS HERE. Its own `status` keeps its vocabulary; beside it, `state` separates a real failure from pending configuration, from no activity, and from a feature not in use, with `required`, a `reason` code and, where something has to be set up, an `action`. A new account with no integration, no provider call and no FX quote reads `healthy`, with `connections` pending configuration.\n\nGRADE ON `status`, AND READ THE RULE BEFORE WRITING THE ALERT. Only `state: failure` grades. `down` means `db` or `vault` fails. `degraded` means any other check fails, which today is one of: the tool catalog is not loaded (`tool_catalog`), a USD/BRL quote the router needs is missing, stale or unreadable (`fx_rates`; no deployment needs one until the router normalizes cost across currencies, and until then the quote is `not_in_use` whatever its age), a live Celcoin connection lacks a webhook subscription (`celcoin_webhook_subscriptions`), or a Pix Automático worker with work to do is stale, failing or never ran (`recurrence_holds`, `recurrence_scheduler`, including a hold past its time), or a BolePix paid twice has had its refund owed for longer than 3 days (`bolepix_refunds`), or a Live money state is waiting on a person (`money_reconcile`: an accepted cash-out the provider failed later, a hold whose dispatch outcome is unknown, a dispatch whose process died, or a return or inbound credit that could not be applied), or this production process has no working tool strategy and refuses every meta-tool call with 503 `tool_strategy_unavailable` (`tool_strategy`; reads, authentication and webhooks keep working). Everything else grades `healthy`. `attention` lists the failing checks and the ones pending configuration by name.\n\n`metrics` IS READ, NEVER GRADED. `metrics.recurrence_instruction_alarms` counts the Pix Automático instruction alarms still open on a cycle still ahead, per kind and reason, for the calling org: a cycle not announced, an instruction refused, held back by a ceiling, or queued and expired. Each alarm already reached its tenant as an event in the recurrence's project; this is the standing number, and it never moves `status`.\n\nNON-NOMINAL MEASUREMENTS THAT DO NOT MOVE THE GRADE, and an alert that wants them has to read the field rather than the grade: `embeddings.status` `low` or `empty` (discovery answers from its keyword fallback), `connections.status` `partial` or `none`, `telemetry.status` `idle` or `stale` (no provider call is no activity, not a fault), and `fx_rates.status` `stale` or `missing` while no quote is needed. None of them stops a call from being served.\n\nONLY HALF OF ONE CHECK IS PER TENANT. `connections.connected` counts connections in the calling credential's own org and project. `connections.total_servers` counts every active provider in the catalog and is the same number for every reader, so the ratio between them is not a tenant completion percentage.\n\nTHIS READ WRITES, and the write is observable. Each call stores a snapshot of its own result against the calling org, and when the grade differs from the previous snapshot's it publishes `system.health.degraded` or `system.health.recovered` into the calling project, carrying a field-by-field diff of what moved. Anything subscribed to those event types in that project fires. Polling this endpoint therefore has side effects, and two monitors polling the same org write into one shared snapshot history — a transition either of them causes is seen once, by whoever's call crossed it. Where the 30-day history is switched on, each call also counts one observation in `GET /v1/health/history` for the calling org, so a monitor polling this endpoint moves that history too.\n\nTHE HANDLER ANSWERS 200 FOR EVERY STATE IT GRADES, `down` included: a dead dependency is reported in the body and never mapped onto an HTTP status. That is why the map below has one entry. It is not a promise that nothing else can come back. Three things produce a non-200 here and none of them is a grade: a credential that does not authenticate, a credential whose grants do not cover this read — both refused before the handler runs, and neither described in the map below, because the answer to them is the same on every operation the same door guards — and a refusal of the snapshot write above, which is a defect on our side rather than a dependency being down. Alert on `status`. A non-200 is a bug report, and which of the three it is decides who should be reading it.", "responses": { "200": { "description": "OK", @@ -27753,7 +34377,7 @@ "url": "https://github.com/codespar/codespar-enterprise/issues/979", "description": "ent#979 — canonical path and alias window" }, - "description": "DEPRECATED alias of `POST /v1/connections/start`, kept for two releases. The same handler is registered at both paths and both require the same grant, so switching the path changes nothing else. Build against the canonical path, which carries the full description of this flow.\n\nTWO DIFFERENT REDIRECT URIS ARE IN PLAY, and mixing them up is the usual first failure. The `redirect_uri` in the body is where OUR callback sends the browser once the flow finishes, and it is stored against the state token; it must be https. The `redirect_uri` embedded inside the returned `authorize_url` is our own callback, and that is the value the provider has to have allowlisted.\n\n`link_token` is the same value as the `state` parameter inside `authorize_url`. It is single use and expires at `expires_at`, ten minutes out.\n\nThe refusals are bare `{ error, ... }` bodies, not the nested envelope the rest of this document mostly uses. A provider with no OAuth configuration is 404. A missing platform client credential is 500 — that is our seeding defect, not a caller error, and no change to the request fixes it.", + "description": "DEPRECATED alias of `POST /v1/connections/start`, kept for two releases. The same handler is registered at both paths and both require the same grant, so switching the path changes nothing else. Build against the canonical path, which carries the full description of this flow.\n\nTWO DIFFERENT REDIRECT URIS ARE IN PLAY, and mixing them up is the usual first failure. The `redirect_uri` in the body is where OUR callback sends the browser once the flow finishes, and it is stored against the state token; it must be https. The `redirect_uri` embedded inside the returned `authorize_url` is our own callback, and that is the value the provider has to have allowlisted.\n\n`link_token` is the same value as the `state` parameter inside `authorize_url`. It is single use and expires at `expires_at`, ten minutes out.\n\nThe refusals are bare `{ error, ... }` bodies, not the nested envelope the rest of this document mostly uses. A provider with no OAuth configuration is 404. A missing platform client credential is 500 — that is our seeding defect, not a caller error, and no change to the request fixes it.\n\nThe exception is a person's own Google account (`server_id` `google-calendar`, `google-drive` or `gmail`), described on the canonical path: its refusals use the `error.code` envelope, an API key or an OAuth token carries no person (403 `bearer_token_has_no_person`), `user_id` must be the signed-in person, `scopes` is refused because the connector's scopes are fixed, and the connectors switched off answer 503 `connector_disabled`.", "requestBody": { "content": { "application/json": { @@ -27847,6 +34471,55 @@ } } }, + "403": { + "description": "Google connectors only: no verified person rides on the request, the session token does not verify or names someone else, `user_id` is not the signed-in person, or the person is not a member of the organization.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "bearer_token_has_no_person", + "user_token_required", + "user_token_invalid", + "user_token_identity_mismatch", + "not_a_member" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, "404": { "description": "The provider has no OAuth configuration in the catalog.", "content": { @@ -27934,6 +34607,52 @@ } } } + }, + "503": { + "description": "Google connectors only: they are switched off on this deployment, or it cannot verify a person's session.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "connector_disabled", + "user_token_verification_unconfigured" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } } }, "x-codespar-scope": "connections:write", @@ -28909,7 +35628,7 @@ "/v1/wallets/{id}/transfer": { "post": { "summary": "Withdraw from a consumer wallet under the consumer's signed mandate", - "description": "Moves money OUT of a consumer-scoped wallet — USDC to a Base address, BRL to a Pix key. Hold, then send, then debit; on a send failure the hold is released.\n\nTHE MONEY IS AUTHORIZED BY THE CONSUMER'S SIGNED MANDATE, NOT BY WHO IS CALLING. `mandate`, `signature`, `agent_id` and `purpose` are all four required in practice: the schema marks them optional only so that omitting them produces a typed `mandate_required` refusal instead of a shapeless 400. No key, no role and no header substitutes for them, and the attribution recorded on the withdrawal is derived from the verified mandate rather than from anything the caller wrote. The destination must be NAMED in the mandate's signed withdrawal allowlist — its own field, separate from the list of merchants the agent may pay, so that a shopping grant is not also a cash-out grant.\n\nAND YET THE PATH DOES READ AN IDENTITY HEADER, BEFORE ANY OF THAT. The route carries an `admin` role gate as a preHandler, and that gate reads `x-codespar-user` and answers 403 on its own, before the mandate is looked at. Send the header, naming a member who holds `admin` or `owner` in the organization. On a dashboard-forwarded credential a missing header is refused immediately. On an API key the gate is being rolled out and currently lets the request through while recording it, so a key that works today without the header will stop working when the rollout completes — this is the one sentence to act on if you are integrating now.\n\nRead the two gates as two different questions. The role gate asks who may ASK for a withdrawal; the mandate asks whether the money's owner AGREED to it. Passing the first does not weaken the second.\n\nA THIRD GATE RUNS AFTER THE MANDATE: the same policy engine that governs agent spend, under the tool name `wallet:withdraw`. An organization rule targeting wallet tools therefore applies to money leaving a wallet, and can refuse or route the withdrawal to an approval even when the consumer's mandate is perfectly valid.\n\nIDEMPOTENCY, AND THE TWO WAYS IT REFUSES. Send `idempotency_key` and a replay returns the original 201 with the original `tx_hash`. A key whose withdrawal is still in flight is 409 `withdrawal_in_progress`; a key whose withdrawal FAILED is 409 `withdrawal_failed` and is permanently spent — retry under a NEW key. Without a key there is no replay protection at all and a repeated request sends twice.\n\n`amount_minor` is an integer in the currency's minor unit as the ROUTE reads it; the mandate's caps may be accounted in the currency's native unit, and the conversion between the two is done for you.\n\nTHE 403 ARRIVES IN THREE DIFFERENT BODY SHAPES depending on which gate refused — see that response's own description. This is the one status on this operation where a client cannot assume the envelope.\n\nScope: `wallets:admin`. Org and seller wallets never reach any of this: they are refused 409 `no_onchain_wallet` before the mandate is read.", + "description": "Moves money OUT of a consumer-scoped wallet — USDC to a Base address, BRL to a Pix key. Hold, then send, then debit; on a send failure the hold is released.\n\nTHE MONEY IS AUTHORIZED BY THE CONSUMER'S SIGNED MANDATE, NOT BY WHO IS CALLING. `mandate`, `signature`, `agent_id` and `purpose` are all four required in practice: the schema marks them optional only so that omitting them produces a typed `mandate_required` refusal instead of a shapeless 400. No key, no role and no header substitutes for them, and the attribution recorded on the withdrawal is derived from the verified mandate rather than from anything the caller wrote. The destination must be NAMED in the mandate's signed withdrawal allowlist — its own field, separate from the list of merchants the agent may pay, so that a shopping grant is not also a cash-out grant.\n\nTHE ROLE GATE DOES NOT AUTHORIZE THIS. With an API key holding `wallets:admin` the mandate above is the whole authorization; `x-codespar-user` is not read. On the dashboard the gate also asks for a member who holds `admin` or `owner`.\n\nRead the two gates as two different questions. The role gate asks who may ASK for a withdrawal; the mandate asks whether the money's owner AGREED to it. Passing the first does not weaken the second.\n\nA THIRD GATE RUNS AFTER THE MANDATE: the same policy engine that governs agent spend, under the tool name `wallet:withdraw`. An organization rule targeting wallet tools therefore applies to money leaving a wallet, and can refuse or route the withdrawal to an approval even when the consumer's mandate is perfectly valid.\n\nIDEMPOTENCY, AND THE TWO WAYS IT REFUSES. Send `idempotency_key` and a replay returns the original 201 with the original `tx_hash`. A key whose withdrawal is still in flight is 409 `withdrawal_in_progress`; a key whose withdrawal FAILED is 409 `withdrawal_failed` and is permanently spent — retry under a NEW key. Without a key there is no replay protection at all and a repeated request sends twice.\n\n`amount_minor` is an integer in the currency's minor unit as the ROUTE reads it; the mandate's caps may be accounted in the currency's native unit, and the conversion between the two is done for you.\n\nTHE 403 ARRIVES IN THREE DIFFERENT BODY SHAPES depending on which gate refused — see that response's own description. This is the one status on this operation where a client cannot assume the envelope.\n\nScope: `wallets:admin`. Org and seller wallets never reach any of this: they are refused 409 `no_onchain_wallet` before the mandate is read.", "parameters": [ { "schema": { @@ -29121,7 +35840,7 @@ } }, "403": { - "description": "Forbidden, from one of THREE gates, in THREE different body shapes. Parse defensively: `error` is a string on two of them and an object on the third.\n\n(a) THE ROLE GATE, bare body: `{ error, required: \"admin\", message?, status? }`. `error` is `insufficient_role` when the acting member is not senior enough, `bearer_admin_role_missing` when no `x-codespar-user` was forwarded, `bearer_admin_user_not_member` when the forwarded user is not in the organization, or `bearer_admin_role_unresolved` when the role could not be looked up. The last three carry a `message` and `status`.\n\n(b) THE MANDATE GATE, `apiError` envelope. `mandate_required` (one of the four proof fields is missing), `mandate_consumer_mismatch`, `mandate_currency_mismatch`, `mandate_` for a mandate that is not active, `mandate_sig_invalid` (the STORED row failed its own integrity check), `expired`, `agent_mismatch`, `purpose_mismatch`, `per_tx_cap_exceeded`, `total_cap_exceeded`, `currency_not_authorized`, `merchant_not_allowed`, and `withdrawal_destination_unpinned` — which carries `error.details` naming what the mandate DID authorize, so an agent can open a re-consent flow rather than stopping at a refusal it cannot interpret.\n\n(c) THE POLICY GATE, bare body: `{ error: \"policy_denied\", reason, ruleType, ruleId }`, each of the last three nullable. When the matched rule requires an approval the body also carries `approval_id` and `expires_at`; their presence is the signal that the withdrawal is pending a human rather than refused.\n\n`total_cap_exceeded` appears under (b) but is emitted from TWO places — the mandate verifier and the withdrawal executor's own cap check against what the mandate has already spent. The code and the envelope are the same either way; do not read it as proof of which check ran.", + "description": "Forbidden, from one of THREE gates, in THREE different body shapes. Parse defensively: `error` is a string on two of them and an object on the third.\n\n(a) THE ROLE GATE, bare body: `{ error: \"insufficient_role\", required: \"admin\" }`, when the dashboard's acting member is not senior enough or the credential is an OAuth token. An API key is not refused by this gate.\n\n(b) THE MANDATE GATE, `apiError` envelope. `mandate_required` (one of the four proof fields is missing), `mandate_consumer_mismatch`, `mandate_currency_mismatch`, `mandate_` for a mandate that is not active, `mandate_sig_invalid` (the STORED row failed its own integrity check), `expired`, `agent_mismatch`, `purpose_mismatch`, `per_tx_cap_exceeded`, `total_cap_exceeded`, `currency_not_authorized`, `merchant_not_allowed`, and `withdrawal_destination_unpinned` — which carries `error.details` naming what the mandate DID authorize, so an agent can open a re-consent flow rather than stopping at a refusal it cannot interpret.\n\n(c) THE POLICY GATE, bare body: `{ error: \"policy_denied\", reason, ruleType, ruleId }`, each of the last three nullable. When the matched rule requires an approval the body also carries `approval_id` and `expires_at`; their presence is the signal that the withdrawal is pending a human rather than refused.\n\n`total_cap_exceeded` appears under (b) but is emitted from TWO places — the mandate verifier and the withdrawal executor's own cap check against what the mandate has already spent. The code and the envelope are the same either way; do not read it as proof of which check ran.", "content": { "application/json": { "schema": { @@ -29132,10 +35851,7 @@ "error": { "type": "string", "enum": [ - "insufficient_role", - "bearer_admin_role_missing", - "bearer_admin_user_not_member", - "bearer_admin_role_unresolved" + "insufficient_role" ] }, "required": { @@ -29143,15 +35859,6 @@ "enum": [ "admin" ] - }, - "message": { - "type": "string" - }, - "status": { - "type": "number", - "enum": [ - 403 - ] } }, "required": [ @@ -29526,7 +36233,7 @@ "/v1/wallets/{id}/statement-import": { "post": { "summary": "Hand the reconciler a bank statement", - "description": "Feeds normalized bank-statement lines in so the next reconciliation cycle can match them against this wallet's ledger. It records what the bank says happened; it does not move money and it does not post ledger entries.\n\n`provider_event_id` IS THE WHOLE MATCH KEY. It must equal the ledger row's `external_ref` — the Pix end-to-end id, the SPI identifier, the Open Finance transaction id, whatever the bank stamped. Every other field on an entry is for reporting: the matcher reads only this one. An entry whose id matches nothing is accepted, counted as imported, and simply never matches.\n\nIMPORTING THE SAME STATEMENT TWICE IS SAFE, and that is what the response's two counters are for. Deduplication is on `(source, provider_event_id)` within the project, so `imported` counts the entries that were new and `duplicates` counts the ones already held. The two always sum to the number of entries you sent, so a shortfall means you miscounted your own batch, not that anything was dropped. Re-uploading a whole statement to pick up a few new lines is the intended usage.\n\nEACH ENTRY BECOMES A `commerce.payment.received` EVENT, published through the ordinary event path rather than written straight to storage. That matters because it means your webhook subscriptions fire for imported statement credits exactly as they do for provider-delivered ones. The fan-out is fire-and-forget, so a slow subscriber of yours cannot stall the import.\n\n`occurred_at` KEEPS THE BANK'S OWN TIMESTAMP on the stored event, which is what makes the reconciler's cutoffs and ordering behave. Omitting it means the event is stamped on arrival, which will misplace a back-dated statement inside those windows.\n\n`source` names where the statement came from, lowercase kebab-case only, and it is half the dedup key: importing the same bank line under two different sources stores it twice.\n\nTHE 202 IS AN ACKNOWLEDGEMENT, NOT A RECONCILIATION. The entries are stored; the matching happens on the next cycle, and `next_recon_cycle_within_seconds` is how long that is at most. Nothing here reports a match.\n\nScope: `wallets:admin`, and the route additionally requires the `admin` role: send `x-codespar-user` naming an admin or owner of the organization.", + "description": "Feeds normalized bank-statement lines in so the next reconciliation cycle can match them against this wallet's ledger. It records what the bank says happened; it does not move money and it does not post ledger entries.\n\n`provider_event_id` IS THE WHOLE MATCH KEY. It must equal the ledger row's `external_ref` — the Pix end-to-end id, the SPI identifier, the Open Finance transaction id, whatever the bank stamped. Every other field on an entry is for reporting: the matcher reads only this one. An entry whose id matches nothing is accepted, counted as imported, and simply never matches.\n\nIMPORTING THE SAME STATEMENT TWICE IS SAFE, and that is what the response's two counters are for. Deduplication is on `(source, provider_event_id)` within the project, so `imported` counts the entries that were new and `duplicates` counts the ones already held. The two always sum to the number of entries you sent, so a shortfall means you miscounted your own batch, not that anything was dropped. Re-uploading a whole statement to pick up a few new lines is the intended usage.\n\nEACH ENTRY BECOMES A `commerce.payment.received` EVENT, published through the ordinary event path rather than written straight to storage. That matters because it means your webhook subscriptions fire for imported statement credits exactly as they do for provider-delivered ones. The fan-out is fire-and-forget, so a slow subscriber of yours cannot stall the import.\n\n`occurred_at` KEEPS THE BANK'S OWN TIMESTAMP on the stored event, which is what makes the reconciler's cutoffs and ordering behave. Omitting it means the event is stamped on arrival, which will misplace a back-dated statement inside those windows.\n\n`source` names where the statement came from, lowercase kebab-case only, and it is half the dedup key: importing the same bank line under two different sources stores it twice.\n\nTHE 202 IS AN ACKNOWLEDGEMENT, NOT A RECONCILIATION. The entries are stored; the matching happens on the next cycle, and `next_recon_cycle_within_seconds` is how long that is at most. Nothing here reports a match.\n\nAdministrative: an admin or owner performs it from the dashboard. An API key is refused with 403 `admin_session_required`, whatever its scopes.", "parameters": [ { "schema": { @@ -29681,7 +36388,7 @@ } }, "403": { - "description": "Forbidden, from the role gate, in a BARE body — not the `apiError` envelope the 400 and 404 use. `insufficient_role` when the acting member is not senior enough; on an API key, `bearer_admin_role_missing`, `bearer_admin_user_not_member` or `bearer_admin_role_unresolved`, each with a `message` and `status`.", + "description": "Forbidden, from the role gate, in a BARE body — not the `apiError` envelope the 400 and 404 use. `insufficient_role` when the acting member is not senior enough (with `required: \"admin\"`); on an API key, `admin_session_required`, with a `message` and `status`, whatever its scopes.", "content": { "application/json": { "schema": { @@ -29691,9 +36398,7 @@ "type": "string", "enum": [ "insufficient_role", - "bearer_admin_role_missing", - "bearer_admin_user_not_member", - "bearer_admin_role_unresolved" + "admin_session_required" ] }, "required": { @@ -29713,8 +36418,7 @@ } }, "required": [ - "error", - "required" + "error" ] } } @@ -34822,7 +41526,7 @@ "/v1/connections/start": { "post": { "summary": "Begin the Connect Link OAuth flow for a provider", - "description": "The entry point for providers that cannot be connected by posting a key. It mints a single-use state token, stores the caller's org, project and environment against it, and returns the provider's authorize URL with that token already embedded.\n\nSend the user to `authorize_url`. The provider redirects to our callback, which exchanges the code, vaults the tokens under the project recorded at start, revokes any existing connection for the same (project, user, server) and writes the new one. The callback is not part of this document: it is unauthenticated by necessity, since the provider carries no CodeSpar credential.\n\n`link_token` is the same value as the `state` parameter inside `authorize_url`; it is single use and expires at `expires_at`, ten minutes out. `redirect_uri` must be https and is where the callback sends the browser back, with `status=connected&connection_id=…`, `status=denied&error=…` or `status=error&error=…` appended.\n\n`POST /v1/connect/start` is the same handler on a second path. A provider with no OAuth configuration is 404; a missing platform client credential is 500, which is our seeding defect and not the caller's error. Both bodies are bare `{ error, … }`, not the `error.code` envelope.\n\n**A person's own Google account** (`server_id` `google-calendar`, `google-drive` or `gmail`) is connected for its owner only. The owner is the signed-in person whose session token the dashboard forwards (`x-codespar-user-token`), and `user_id` must name that person; an API key or an OAuth token carries no person and is refused `bearer_token_has_no_person` (403). The connector asks for its own scopes, so `scopes` is refused (400 `invalid_body`). The consent asks for offline access, always shows Google's consent screen and keeps earlier grants. Test and Live projects both use the real Google: there is no Google sandbox, and the data is the person's own. These refusals use the `error.code` envelope. Off on the deployment, the three answer `connector_disabled` (503).", + "description": "The entry point for providers that cannot be connected by posting a key. It mints a single-use state token, stores the caller's org, project and environment against it, and returns the provider's authorize URL with that token already embedded.\n\nSend the user to `authorize_url`. The provider redirects to our callback, which exchanges the code, vaults the tokens under the project recorded at start, revokes any existing connection for the same (project, user, server) and writes the new one. The callback is not part of this document: it is unauthenticated by necessity, since the provider carries no CodeSpar credential.\n\n`link_token` is the same value as the `state` parameter inside `authorize_url`; it is single use and expires at `expires_at`, ten minutes out. `redirect_uri` must be https and is where the callback sends the browser back, with `status=connected&connection_id=…`, `status=denied&error=…` or `status=error&error=…` appended.\n\n`POST /v1/connect/start` is the same handler on a second path. A provider with no OAuth configuration is 404; a missing platform client credential is 500, which is our seeding defect and not the caller's error. Both bodies are bare `{ error, … }`, not the `error.code` envelope.\n\n**A person's own Google account** (`server_id` `google-calendar`, `google-drive` or `gmail`) is connected for its owner only. The owner is the signed-in person whose session token the dashboard forwards (`x-codespar-user-token`), and `user_id` must name that person; an API key or an OAuth token carries no person and is refused `bearer_token_has_no_person` (403). The connector asks for its own fixed scopes, so `scopes` is refused (400 `invalid_body`): `openid`, `https://www.googleapis.com/auth/userinfo.email` and `https://www.googleapis.com/auth/userinfo.profile` (which Google account it is), plus one product scope, `https://www.googleapis.com/auth/calendar` for `google-calendar`, `https://www.googleapis.com/auth/drive` for `google-drive` and `https://www.googleapis.com/auth/gmail.modify` for `gmail`. The person may untick the product scope at Google; the connection then reads where a narrower grant allows it and a write answers `connector_scope_insufficient`. The consent asks for offline access, always shows Google's consent screen and keeps earlier grants. A Test project uses the real Google: there is no Google sandbox, and the data is the person's own. A Live project is refused `google_connectors_live_disabled` (409), here and at the callback, before anything is sent to Google. These refusals use the `error.code` envelope. Off on the deployment, the three answer `connector_disabled` (503).", "requestBody": { "content": { "application/json": { @@ -35054,7 +41758,7 @@ } }, "503": { - "description": "Google connectors only: they are switched off on this deployment.", + "description": "Google connectors only: they are switched off on this deployment, or it cannot verify a person's session.", "content": { "application/json": { "schema": { @@ -35903,6 +42607,13 @@ "partner" ], "default": "hosted" + }, + "executor": { + "type": "string", + "enum": [ + "codespar_simulator", + "provider_sandbox" + ] } }, "required": [ @@ -35929,31 +42640,174 @@ "type": "string", "description": "ISO 8601. The token expires 24 hours after this call; a consumer opening the link after that sees an expired consent and nothing is created. This is the TOKEN's TTL, not the mandate's: the mandate's own TTL is `intent.mandate_ttl_seconds`, counted from the moment the consumer signs." }, - "surface": { - "type": "string", - "enum": [ - "hosted", - "partner" + "surface": { + "type": "string", + "enum": [ + "hosted", + "partner" + ], + "description": "Echo of the requested surface, which is fixed for this token's life. `hosted`: the consumer signs on the page at `consent_url` and the submit must NOT carry an attestation. `partner`: you render the screen and call `GET /v1/consents/{token}` and `POST /v1/consents/{token}/submit` yourself, and the submit MUST carry `attestation`." + }, + "consent_url": { + "type": "string", + "description": "The hosted page for this token, composed from the server's configured base. Hand it to the consumer on the `hosted` surface. It is returned on `partner` too, where it is a usable fallback: the same token also answers on the page." + }, + "executor": { + "type": [ + "string", + "null" + ], + "enum": [ + "codespar_simulator", + "provider_sandbox" + ], + "description": "Who executes (or executed) the payment, by the same name the integrator chooses with on POST /v1/consents. `codespar_simulator` (\"Simulado pela CodeSpar\": no provider is called) or `provider_sandbox` (the provider's sandbox, over the account the server bound to this consumer); both Test only. Null when no executor applies, Live included. The name is the MODE: the provider, account, project, consumer and environment are resolved by the server before the signature and checked again when the payment runs; no request field chooses them (`executor_provider_not_selectable`), and a provider failure is never turned into a simulation. Records written before this name existed keep their stored value and are read in these words." + }, + "executor_provider": { + "type": [ + "string", + "null" + ], + "enum": [ + "celcoin" + ], + "description": "The concrete provider behind `executor`, as the server resolved it: `celcoin` for `provider_sandbox`; null for `codespar_simulator` (no provider is called) and when `executor` is null. Read-only." + }, + "executor_label": { + "type": [ + "string", + "null" + ], + "description": "The executor's label as the consent screen, the dashboard and the receipt show it. In Test it ends \"· sem dinheiro real\"." + }, + "environment": { + "type": [ + "string", + "null" + ], + "enum": [ + "test", + "live" + ], + "description": "The project's environment." + }, + "real_money": { + "type": [ + "boolean", + "null" + ], + "description": "False in Test, always: no real money moves, including when the provider's sandbox CONFIRMED the operation (`moneyMoved: true` / `settlement: \"confirmed\"` then mean the sandbox settled it). True in Live." + } + }, + "required": [ + "token", + "expires_at", + "surface", + "consent_url", + "executor", + "executor_provider", + "executor_label", + "environment", + "real_money" + ] + } + } + } + }, + "400": { + "description": "The body did not match the schema (`invalid_body`), `executor` was sent for a mandate that is not single-currency BRL Pix (`executor_requires_brl_pix`), or the body named a provider (`provider` / `executor_provider`, top level or in `intent`: `executor_provider_not_selectable`, `details.field`): the provider behind `provider_sandbox` is resolved by the server. Nothing was created.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "invalid_body", + "executor_requires_brl_pix", + "executor_provider_not_selectable" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "409": { + "description": "`executor: \"provider_sandbox\"` and the project's provider sandbox is not ready (`provider_sandbox_not_ready`): `details.missing` names each gap, `details.next_steps` says who does what, and `details.alternative` names the simulator. Nothing was created.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "provider_sandbox_not_ready" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" ], - "description": "Echo of the requested surface, which is fixed for this token's life. `hosted`: the consumer signs on the page at `consent_url` and the submit must NOT carry an attestation. `partner`: you render the screen and call `GET /v1/consents/{token}` and `POST /v1/consents/{token}/submit` yourself, and the submit MUST carry `attestation`." - }, - "consent_url": { - "type": "string", - "description": "The hosted page for this token, composed from the server's configured base. Hand it to the consumer on the `hosted` surface. It is returned on `partner` too, where it is a usable fallback: the same token also answers on the page." + "description": "Echoes the `X-Request-Id` header when the request carried one." } }, "required": [ - "token", - "expires_at", - "surface", - "consent_url" + "error", + "request_id" ] } } } }, - "400": { - "description": "The body did not match the schema. `details.issues` carries the Zod issues; the refusals with their own message are a `\"*\"` entry in `intent.withdrawal_allowlist` and a `intent.dda_allowlist` entry that is not a CPF (11 digits) or a CNPJ (14 digits).", + "422": { + "description": "`executor` in a Live project: `simulation_refused_live` for `codespar_simulator` (Live never simulates) and `executor_test_only` for `provider_sandbox`. Nothing was created.", "content": { "application/json": { "schema": { @@ -35965,7 +42819,8 @@ "code": { "type": "string", "enum": [ - "invalid_body" + "simulation_refused_live", + "executor_test_only" ] }, "message": { @@ -36197,6 +43052,13 @@ "partner" ], "default": "hosted" + }, + "executor": { + "type": "string", + "enum": [ + "codespar_simulator", + "provider_sandbox" + ] } }, "required": [ @@ -36234,20 +43096,71 @@ "consent_url": { "type": "string", "description": "The hosted page for this token, composed from the server's configured base. Hand it to the consumer on the `hosted` surface. It is returned on `partner` too, where it is a usable fallback: the same token also answers on the page." + }, + "executor": { + "type": [ + "string", + "null" + ], + "enum": [ + "codespar_simulator", + "provider_sandbox" + ], + "description": "Who executes (or executed) the payment, by the same name the integrator chooses with on POST /v1/consents. `codespar_simulator` (\"Simulado pela CodeSpar\": no provider is called) or `provider_sandbox` (the provider's sandbox, over the account the server bound to this consumer); both Test only. Null when no executor applies, Live included. The name is the MODE: the provider, account, project, consumer and environment are resolved by the server before the signature and checked again when the payment runs; no request field chooses them (`executor_provider_not_selectable`), and a provider failure is never turned into a simulation. Records written before this name existed keep their stored value and are read in these words." + }, + "executor_provider": { + "type": [ + "string", + "null" + ], + "enum": [ + "celcoin" + ], + "description": "The concrete provider behind `executor`, as the server resolved it: `celcoin` for `provider_sandbox`; null for `codespar_simulator` (no provider is called) and when `executor` is null. Read-only." + }, + "executor_label": { + "type": [ + "string", + "null" + ], + "description": "The executor's label as the consent screen, the dashboard and the receipt show it. In Test it ends \"· sem dinheiro real\"." + }, + "environment": { + "type": [ + "string", + "null" + ], + "enum": [ + "test", + "live" + ], + "description": "The project's environment." + }, + "real_money": { + "type": [ + "boolean", + "null" + ], + "description": "False in Test, always: no real money moves, including when the provider's sandbox CONFIRMED the operation (`moneyMoved: true` / `settlement: \"confirmed\"` then mean the sandbox settled it). True in Live." } }, "required": [ "token", "expires_at", "surface", - "consent_url" + "consent_url", + "executor", + "executor_provider", + "executor_label", + "environment", + "real_money" ] } } } }, "400": { - "description": "The body did not match the schema. `details.issues` carries the Zod issues; the refusals with their own message are a `\"*\"` entry in `intent.withdrawal_allowlist` and a `intent.dda_allowlist` entry that is not a CPF (11 digits) or a CNPJ (14 digits).", + "description": "The body did not match the schema (`invalid_body`), `executor` was sent for a mandate that is not single-currency BRL Pix (`executor_requires_brl_pix`), or the body named a provider (`provider` / `executor_provider`, top level or in `intent`: `executor_provider_not_selectable`, `details.field`): the provider behind `provider_sandbox` is resolved by the server. Nothing was created.", "content": { "application/json": { "schema": { @@ -36259,7 +43172,100 @@ "code": { "type": "string", "enum": [ - "invalid_body" + "invalid_body", + "executor_requires_brl_pix", + "executor_provider_not_selectable" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "409": { + "description": "`executor: \"provider_sandbox\"` and the project's provider sandbox is not ready (`provider_sandbox_not_ready`): `details.missing` names each gap, `details.next_steps` says who does what, and `details.alternative` names the simulator. Nothing was created.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "provider_sandbox_not_ready" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "422": { + "description": "`executor` in a Live project: `simulation_refused_live` for `codespar_simulator` (Live never simulates) and `executor_test_only` for `provider_sandbox`. Nothing was created.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "simulation_refused_live", + "executor_test_only" ] }, "message": { @@ -36366,6 +43372,52 @@ "partner" ], "description": "The surface this token was opened for. `partner` means the submit requires `attestation`; `hosted` means it refuses one. Read it before submitting rather than assuming: the org chose it when it created the consent." + }, + "executor": { + "type": [ + "string", + "null" + ], + "enum": [ + "codespar_simulator", + "provider_sandbox" + ], + "description": "Who executes (or executed) the payment, by the same name the integrator chooses with on POST /v1/consents. `codespar_simulator` (\"Simulado pela CodeSpar\": no provider is called) or `provider_sandbox` (the provider's sandbox, over the account the server bound to this consumer); both Test only. Null when no executor applies, Live included. The name is the MODE: the provider, account, project, consumer and environment are resolved by the server before the signature and checked again when the payment runs; no request field chooses them (`executor_provider_not_selectable`), and a provider failure is never turned into a simulation. Records written before this name existed keep their stored value and are read in these words." + }, + "executor_provider": { + "type": [ + "string", + "null" + ], + "enum": [ + "celcoin" + ], + "description": "The concrete provider behind `executor`, as the server resolved it: `celcoin` for `provider_sandbox`; null for `codespar_simulator` (no provider is called) and when `executor` is null. Read-only." + }, + "executor_label": { + "type": [ + "string", + "null" + ], + "description": "The executor's label as the consent screen, the dashboard and the receipt show it. In Test it ends \"· sem dinheiro real\"." + }, + "environment": { + "type": [ + "string", + "null" + ], + "enum": [ + "test", + "live" + ], + "description": "The project's environment." + }, + "real_money": { + "type": [ + "boolean", + "null" + ], + "description": "False in Test, always: no real money moves, including when the provider's sandbox CONFIRMED the operation (`moneyMoved: true` / `settlement: \"confirmed\"` then mean the sandbox settled it). True in Live." } }, "required": [ @@ -36376,7 +43428,12 @@ "intent", "expires_at", "rails_supported", - "surface" + "surface", + "executor", + "executor_provider", + "executor_label", + "environment", + "real_money" ] } } @@ -36516,206 +43573,356 @@ } } } - } - } - } - }, - "/v1/consents/{token}/submit": { - "post": { - "summary": "Submit a consent and receive the signed mandate", - "security": [], - "description": "Consumes the token and returns the signed consumer mandate. In one transaction: the consumer's secret is provisioned if this is their first consent, the funding source is created from `provider_token` (encrypted through the vault, never stored in the clear), the consent record is written with the IP and user-agent of THIS call, the mandate is signed with the consumer's secret and the token is consumed. No credential: the token is the authentication, and it is one-shot.\n\nWHO may call it is decided by the surface the org chose at creation, and the two are not interchangeable:\n\n- `hosted` — the consumer's browser submits from our page. `attestation` is REFUSED (400 `attestation_not_accepted`): our page witnessed the act, and the IP and user-agent on the consent record are the consumer's.\n- `partner` — your server submits. `attestation` is REQUIRED (400 `attestation_required`): the IP and user-agent recorded are your server's, so the only statement about the human is yours. It is signed into the mandate as `consent_attestation` and cannot be edited afterwards without breaking the signature.\n\n`attestation.method` says how the human authorized: `partner_session` (an authenticated session in your product), `in_person`, `verified_code` (a code YOU issued and verified), `partner_biometric` (YOU ran a biometric check at the moment of the act), or `sandbox_fixture` (no human authorized: a CodeSpar test surface signed a sandbox fixture; accepted ONLY for a test project, 403 `attestation_sandbox_fixture_not_permitted` on a live one). `partner_biometric` is not a flavour of `partner_session`: in a dispute a session says someone was logged in and a biometric says a body was present. We capture and verify no biometric ourselves — this records what YOU assert, sealed by the mandate signature so it cannot be edited afterwards; the evidence behind it stays with you. `asserted_at` is the instant you say they authorized, in Unix seconds. `reference` is your own record id, `[A-Za-z0-9_-]{1,120}`, and never personal data — it is joined into the signed string, so the character set is the schema's, not a suggestion.\n\n`attestation.evidence` (optional) is what you OBSERVED of the act, signed with the rest of the mandate. `channel` is required and decides which other keys may be present, because a value a channel cannot expose was inferred, and an inferred value inside a signed record reads exactly like an observed one:\n\n- `whatsapp`, `sms`, `email`, `llm_chat` — `contact`, `message_id`, `session_id`, `provider_ts`. These hand you a conversation, not a connection.\n- `web_chat` — the above plus `ip`, `user_agent`, `geo`. A browser has no install, so no `device_id_hash`.\n- `app` — the above plus `device_id_hash`.\n- `other` — everything, because we cannot say what a channel we have not named exposes. An auditor reading `other` knows exactly that.\n\nA key outside its channel's set, or a key the object does not declare, is a 400 `attestation_evidence_invalid` with `details.key` naming it — never a silent drop. `contact` is the e-mail or E.164 phone the consumer acted from; it is hashed server-side into the signed `contact_hash` and never stored in the clear. `device_id_hash` you hash yourself (64 hex characters). `geo` is `{country, region, city}` and refuses coordinates.\n\n`method: \"verified_code\"` additionally REQUIRES `evidence.contact` to carry a contact verification we ran for this consumer in the last 24h (`POST /v1/consumers/{consumerId}/contact-verifications`), or the submit is refused with 409 `contact_verification_required` and the token is left unspent. A rung that is only asserted is not stronger than the one below it.", - "parameters": [ - { - "schema": { - "type": "string" - }, - "required": true, - "name": "token", - "in": "path" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "consumer_id": { - "type": "string", - "minLength": 1, - "maxLength": 120 - }, - "rail": { - "type": "string", - "enum": [ - "pix-consent", - "card-token", - "ted-debit-auth", - "usd-ach-debit", - "usdc-onchain" - ] - }, - "provider_token": { - "type": "string", - "minLength": 1, - "maxLength": 2048 - }, - "display_label": { - "type": "string", - "maxLength": 80 - }, - "attestation": { - "type": "object", - "properties": { - "method": { - "type": "string", - "enum": [ - "partner_session", - "in_person", - "verified_code", - "partner_biometric", - "sandbox_fixture" - ] - }, - "asserted_at": { - "type": "integer", - "exclusiveMinimum": 0 - }, - "reference": { - "type": "string", - "pattern": "^[A-Za-z0-9_-]{1,120}$" - }, - "evidence": { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": [ - "whatsapp", - "web_chat", - "app", - "llm_chat", - "sms", - "email", - "other" - ] - }, - "message_id": { - "type": "string", - "pattern": "^[A-Za-z0-9_.:=+-]{1,120}$" - }, - "session_id": { - "type": "string", - "pattern": "^[A-Za-z0-9_.:=+-]{1,120}$" - }, - "provider_ts": { - "type": "integer", - "exclusiveMinimum": 0 - }, - "ip": { - "type": "string", - "format": "ip" - }, - "user_agent": { - "type": "string", - "minLength": 1, - "maxLength": 512 - }, - "device_id_hash": { - "type": "string", - "pattern": "^[0-9a-f]{64}$" - }, - "geo": { - "type": "object", - "properties": { - "country": { - "type": "string", - "pattern": "^[A-Z]{2}$" - }, - "region": { - "type": "string", - "minLength": 1, - "maxLength": 64 - }, - "city": { - "type": "string", - "minLength": 1, - "maxLength": 64 - } - }, - "required": [ - "country" - ], - "additionalProperties": false - }, - "contact": { - "type": "string", - "minLength": 3, - "maxLength": 254 - } - }, - "required": [ - "channel" - ], - "additionalProperties": false - } - }, - "required": [ - "method", - "asserted_at" - ] - } - }, - "required": [ - "consumer_id", - "rail", - "provider_token" - ] - } - } - } - }, - "responses": { - "201": { - "description": "The mandate is signed and stored, and the token is spent. Store the mandate and its signature: both are presented on every spend.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "mandate_id": { - "type": "string" - }, - "mandate": { - "type": "object", - "additionalProperties": {}, - "description": "The signed consumer mandate. Store it server-side with its signature; the agent presents both on every spend." - }, - "signature": { - "type": "string", - "description": "HMAC of the mandate's canonical payload, hex." - }, - "callback_url": { - "type": [ - "string", - "null" - ], - "description": "The `callback_url` given at creation, echoed so the caller can post the mandate on." - } - }, - "required": [ - "mandate_id", - "mandate", - "signature", - "callback_url" - ] - } - } - } + } + } + } + }, + "/v1/consents/{token}/submit": { + "post": { + "summary": "Submit a consent and receive the signed mandate", + "security": [], + "description": "Consumes the token and returns the signed consumer mandate. In one transaction: the consumer's secret is provisioned if this is their first consent, the funding source is created from `provider_token` (encrypted through the vault, never stored in the clear), the consent record is written with the IP and user-agent of THIS call, the mandate is signed with the consumer's secret and the token is consumed. No credential: the token is the authentication, and it is one-shot.\n\nWHO may call it is decided by the surface the org chose at creation, and the two are not interchangeable:\n\n- `hosted` — the consumer's browser submits from our page. `attestation` is REFUSED (400 `attestation_not_accepted`): our page witnessed the act, and the IP and user-agent on the consent record are the consumer's.\n- `partner` — your server submits. `attestation` is REQUIRED (400 `attestation_required`): the IP and user-agent recorded are your server's, so the only statement about the human is yours. It is signed into the mandate as `consent_attestation` and cannot be edited afterwards without breaking the signature.\n\n`attestation.method` says how the human authorized: `partner_session` (an authenticated session in your product), `in_person`, `verified_code` (a code YOU issued and verified), `partner_biometric` (YOU ran a biometric check at the moment of the act), or `sandbox_fixture` (no human authorized: a CodeSpar test surface signed a sandbox fixture; accepted ONLY for a test project, 403 `attestation_sandbox_fixture_not_permitted` on a live one). `partner_biometric` is not a flavour of `partner_session`: in a dispute a session says someone was logged in and a biometric says a body was present. We capture and verify no biometric ourselves — this records what YOU assert, sealed by the mandate signature so it cannot be edited afterwards; the evidence behind it stays with you. `asserted_at` is the instant you say they authorized, in Unix seconds. `reference` is your own record id, `[A-Za-z0-9_-]{1,120}`, and never personal data — it is joined into the signed string, so the character set is the schema's, not a suggestion.\n\n`attestation.evidence` (optional) is what you OBSERVED of the act, signed with the rest of the mandate. `channel` is required and decides which other keys may be present, because a value a channel cannot expose was inferred, and an inferred value inside a signed record reads exactly like an observed one:\n\n- `whatsapp`, `sms`, `email`, `llm_chat` — `contact`, `message_id`, `session_id`, `provider_ts`. These hand you a conversation, not a connection.\n- `web_chat` — the above plus `ip`, `user_agent`, `geo`. A browser has no install, so no `device_id_hash`.\n- `app` — the above plus `device_id_hash`.\n- `other` — everything, because we cannot say what a channel we have not named exposes. An auditor reading `other` knows exactly that.\n\nA key outside its channel's set, or a key the object does not declare, is a 400 `attestation_evidence_invalid` with `details.key` naming it — never a silent drop. `contact` is the e-mail or E.164 phone the consumer acted from; it is hashed server-side into the signed `contact_hash` and never stored in the clear. `device_id_hash` you hash yourself (64 hex characters). `geo` is `{country, region, city}` and refuses coordinates.\n\n`method: \"verified_code\"` additionally REQUIRES `evidence.contact` to carry a contact verification we ran for this consumer in the last 24h (`POST /v1/consumers/{consumerId}/contact-verifications`), or the submit is refused with 409 `contact_verification_required` and the token is left unspent. A rung that is only asserted is not stronger than the one below it.", + "parameters": [ + { + "schema": { + "type": "string" + }, + "required": true, + "name": "token", + "in": "path" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "consumer_id": { + "type": "string", + "minLength": 1, + "maxLength": 120 + }, + "rail": { + "type": "string", + "enum": [ + "pix-consent", + "card-token", + "ted-debit-auth", + "usd-ach-debit", + "usdc-onchain" + ] + }, + "provider_token": { + "type": "string", + "minLength": 1, + "maxLength": 2048 + }, + "display_label": { + "type": "string", + "maxLength": 80 + }, + "attestation": { + "type": "object", + "properties": { + "method": { + "type": "string", + "enum": [ + "partner_session", + "in_person", + "verified_code", + "partner_biometric", + "sandbox_fixture" + ] + }, + "asserted_at": { + "type": "integer", + "exclusiveMinimum": 0 + }, + "reference": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{1,120}$" + }, + "evidence": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": [ + "whatsapp", + "web_chat", + "app", + "llm_chat", + "sms", + "email", + "other" + ] + }, + "message_id": { + "type": "string", + "pattern": "^[A-Za-z0-9_.:=+-]{1,120}$" + }, + "session_id": { + "type": "string", + "pattern": "^[A-Za-z0-9_.:=+-]{1,120}$" + }, + "provider_ts": { + "type": "integer", + "exclusiveMinimum": 0 + }, + "ip": { + "type": "string", + "format": "ip" + }, + "user_agent": { + "type": "string", + "minLength": 1, + "maxLength": 512 + }, + "device_id_hash": { + "type": "string", + "pattern": "^[0-9a-f]{64}$" + }, + "geo": { + "type": "object", + "properties": { + "country": { + "type": "string", + "pattern": "^[A-Z]{2}$" + }, + "region": { + "type": "string", + "minLength": 1, + "maxLength": 64 + }, + "city": { + "type": "string", + "minLength": 1, + "maxLength": 64 + } + }, + "required": [ + "country" + ], + "additionalProperties": false + }, + "contact": { + "type": "string", + "minLength": 3, + "maxLength": 254 + } + }, + "required": [ + "channel" + ], + "additionalProperties": false + } + }, + "required": [ + "method", + "asserted_at" + ] + } + }, + "required": [ + "consumer_id", + "rail", + "provider_token" + ] + } + } + } + }, + "responses": { + "201": { + "description": "The mandate is signed and stored, and the token is spent. Store the mandate and its signature: both are presented on every spend.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "mandate_id": { + "type": "string" + }, + "mandate": { + "type": "object", + "additionalProperties": {}, + "description": "The signed consumer mandate. Store it server-side with its signature; the agent presents both on every spend." + }, + "signature": { + "type": "string", + "description": "HMAC of the mandate's canonical payload, hex." + }, + "callback_url": { + "type": [ + "string", + "null" + ], + "description": "The `callback_url` given at creation, echoed so the caller can post the mandate on." + }, + "executor": { + "type": [ + "string", + "null" + ], + "enum": [ + "codespar_simulator", + "provider_sandbox" + ], + "description": "Who executes (or executed) the payment, by the same name the integrator chooses with on POST /v1/consents. `codespar_simulator` (\"Simulado pela CodeSpar\": no provider is called) or `provider_sandbox` (the provider's sandbox, over the account the server bound to this consumer); both Test only. Null when no executor applies, Live included. The name is the MODE: the provider, account, project, consumer and environment are resolved by the server before the signature and checked again when the payment runs; no request field chooses them (`executor_provider_not_selectable`), and a provider failure is never turned into a simulation. Records written before this name existed keep their stored value and are read in these words." + }, + "executor_provider": { + "type": [ + "string", + "null" + ], + "enum": [ + "celcoin" + ], + "description": "The concrete provider behind `executor`, as the server resolved it: `celcoin` for `provider_sandbox`; null for `codespar_simulator` (no provider is called) and when `executor` is null. Read-only." + }, + "executor_label": { + "type": [ + "string", + "null" + ], + "description": "The executor's label as the consent screen, the dashboard and the receipt show it. In Test it ends \"· sem dinheiro real\"." + }, + "environment": { + "type": [ + "string", + "null" + ], + "enum": [ + "test", + "live" + ], + "description": "The project's environment." + }, + "real_money": { + "type": [ + "boolean", + "null" + ], + "description": "False in Test, always: no real money moves, including when the provider's sandbox CONFIRMED the operation (`moneyMoved: true` / `settlement: \"confirmed\"` then mean the sandbox settled it). True in Live." + }, + "executor_guidance": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "funding_source_executor_required" + ] + }, + "message": { + "type": "string" + }, + "next": { + "type": "object", + "properties": { + "action": { + "type": "string", + "enum": [ + "reconsent_with_executor" + ] + }, + "endpoint": { + "type": "string" + }, + "executor_choices": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "codespar_simulator", + "provider_sandbox" + ] + } + } + }, + "required": [ + "action", + "endpoint", + "executor_choices" + ] + } + }, + "required": [ + "code", + "message", + "next" + ], + "description": "Test only: present when the mandate was signed over a `pix-consent` source with no executor. A payment under it is refused with `funding_source_executor_required`; open a new consent naming `executor`." + } + }, + "required": [ + "mandate_id", + "mandate", + "signature", + "callback_url", + "executor", + "executor_provider", + "executor_label", + "environment", + "real_money" + ] + } + } + } + }, + "400": { + "description": "The body did not match the schema (`invalid_body`, with the Zod issues in `details.issues`), the attestation does not match the token's surface (`attestation_required` on `partner` without one, `attestation_not_accepted` on `hosted` with one), or the evidence carries a key its channel cannot expose or one the object does not declare (`attestation_evidence_invalid`, `details.key`), or a consent opened with `executor` was submitted with a rail other than `pix-consent` (`executor_rail_mismatch`), or the body named a provider (`executor_provider_not_selectable`, `details.field`): the source signed is the one the server resolved for the consent's executor.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "invalid_body", + "attestation_required", + "attestation_not_accepted", + "attestation_evidence_invalid", + "executor_rail_mismatch", + "executor_provider_not_selectable" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } }, - "400": { - "description": "The body did not match the schema (`invalid_body`, with the Zod issues in `details.issues`), the attestation does not match the token's surface (`attestation_required` on `partner` without one, `attestation_not_accepted` on `hosted` with one), or the evidence carries a key its channel cannot expose or one the object does not declare (`attestation_evidence_invalid`, `details.key`).", + "403": { + "description": "`attestation.method` is `sandbox_fixture` and the consent's project is not a test project: a fixture attestation is accepted only in test. Nothing was signed.", "content": { "application/json": { "schema": { @@ -36727,10 +43934,7 @@ "code": { "type": "string", "enum": [ - "invalid_body", - "attestation_required", - "attestation_not_accepted", - "attestation_evidence_invalid" + "attestation_sandbox_fixture_not_permitted" ] }, "message": { @@ -36762,8 +43966,8 @@ } } }, - "403": { - "description": "`attestation.method` is `sandbox_fixture` and the consent's project is not a test project: a fixture attestation is accepted only in test. Nothing was signed.", + "404": { + "description": "No such token.", "content": { "application/json": { "schema": { @@ -36775,7 +43979,7 @@ "code": { "type": "string", "enum": [ - "attestation_sandbox_fixture_not_permitted" + "not_found" ] }, "message": { @@ -36807,8 +44011,8 @@ } } }, - "404": { - "description": "No such token.", + "409": { + "description": "The token was already submitted, or a concurrent submit won the race (nothing was created twice: the loser rolls back whole); or `method: \"verified_code\"` was claimed without a contact verification for this consumer in the last 24h, in which case nothing was created at all and the token is still pending; or the consent was opened with `executor: \"provider_sandbox\"` and the project has no sandbox account bound to THIS consumer (`provider_sandbox_not_ready`, `details.missing`/`next_steps`): nothing was signed, the token is still pending and no other source is used.", "content": { "application/json": { "schema": { @@ -36820,7 +44024,10 @@ "code": { "type": "string", "enum": [ - "not_found" + "consent_already_resolved", + "consent_race", + "contact_verification_required", + "provider_sandbox_not_ready" ] }, "message": { @@ -36852,8 +44059,8 @@ } } }, - "409": { - "description": "The token was already submitted, or a concurrent submit won the race (nothing was created twice: the loser rolls back whole); or `method: \"verified_code\"` was claimed without a contact verification for this consumer in the last 24h, in which case nothing was created at all and the token is still pending.", + "410": { + "description": "The token expired. Start a new consent.", "content": { "application/json": { "schema": { @@ -36865,9 +44072,7 @@ "code": { "type": "string", "enum": [ - "consent_already_resolved", - "consent_race", - "contact_verification_required" + "consent_expired" ] }, "message": { @@ -36899,8 +44104,8 @@ } } }, - "410": { - "description": "The token expired. Start a new consent.", + "422": { + "description": "The consent was opened with `executor` and its project is not a Test project (`simulation_refused_live`, `executor_test_only`). Nothing was signed.", "content": { "application/json": { "schema": { @@ -36912,7 +44117,8 @@ "code": { "type": "string", "enum": [ - "consent_expired" + "simulation_refused_live", + "executor_test_only" ] }, "message": { @@ -37170,7 +44376,7 @@ } }, "409": { - "description": "Local state refuses. `psp_attempt_in_flight`: the same attempt is already in flight; retry the SAME `attempt_id` once it has answered, never a new one. `psp_attempt_uncertain`: an earlier attempt ended with an unknown outcome and this intent is PINNED to it, so present the same `attempt_id` again, never a new one. `psp_attempt_conflict`: the earlier attempt was already compensated. `attempt_id_conflict`: this `attempt_id` was already used for a different payment (`mismatched_fields` names what differs); nothing was held or sent. `attempt_id_unavailable`: another project of this organization holds this `attempt_id`; use a new one.", + "description": "Local state refuses. `psp_attempt_in_flight`: the same attempt is already in flight; retry the SAME `attempt_id` once it has answered, never a new one. `psp_attempt_uncertain`: an earlier attempt ended with an unknown outcome and this intent is PINNED to it, so present the same `attempt_id` again, never a new one. `psp_attempt_conflict`: the earlier attempt was already compensated. `attempt_id_conflict`: this `attempt_id` was already used for a different payment (`mismatched_fields` names what differs); nothing was held or sent. `attempt_id_unavailable`: another project of this organization holds this `attempt_id`; use a new one. `funding_source_executor_required` (Test only, ent#1983): the mandate's `pix-consent` source was signed without an executor; nothing was sent and the mandate is unchanged; `details.next` says to open a new consent naming `executor` (`codespar_simulator` or `provider_sandbox`).", "content": { "application/json": { "schema": { @@ -37182,6 +44388,7 @@ "code": { "type": "string", "enum": [ + "funding_source_executor_required", "psp_attempt_in_flight", "psp_attempt_uncertain", "psp_attempt_conflict", @@ -37596,7 +44803,7 @@ } }, "409": { - "description": "Local state refuses, on the same five conditions as the by-id route.", + "description": "Local state refuses, on the same conditions as the by-id route, `funding_source_executor_required` included.", "content": { "application/json": { "schema": { @@ -37608,6 +44815,7 @@ "code": { "type": "string", "enum": [ + "funding_source_executor_required", "psp_attempt_in_flight", "psp_attempt_uncertain", "psp_attempt_conflict", @@ -38087,10 +45295,10 @@ { "schema": { "type": "string", - "description": "Our own row status: `pending`, `settled`, `expired`." + "description": "Our own row status: `pending`, `settled`, `expired`, `failed`." }, "required": false, - "description": "Our own row status: `pending`, `settled`, `expired`.", + "description": "Our own row status: `pending`, `settled`, `expired`, `failed`.", "name": "status", "in": "query" }, @@ -38181,6 +45389,31 @@ "unconfirmable" ] }, + "failure": { + "type": "object", + "properties": { + "code": { + "type": "string" + }, + "provider_status": { + "type": [ + "string", + "null" + ] + }, + "failed_at": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "code", + "provider_status", + "failed_at" + ] + }, "settlement_as_of": { "type": [ "string", @@ -38278,7 +45511,7 @@ }, "post": { "summary": "Issue a charge", - "description": "Issues an inbound charge: the buyer pays the merchant. The RAIL IS A FIELD, not a path. `method: \"pix\"` mints an immediate Pix that hands back its copy-and-paste string right away and expires in about an hour. `method: \"boleto\"` WITH a `due_date` issues a cobrança com vencimento: ONE receivable the payer settles either as a boleto (barcode and linha digitável) or by Pix. One debt, two payable legs, never two documents.\n\n**The cobrança com vencimento answers `PROCESSING` with `payable: false` and no document.** The instrument registers with the clearing house first. Subscribe to `commerce.charge.created` rather than polling for a barcode that is not late, only not made yet. `commerce.charge.paid` is the event that means the funds arrived, by either leg.\n\n**`idempotency_key` is REQUIRED for that combination**, and it is checked before anything reaches the issuer. A repeat with the same key returns the charge already issued, or its still-open reservation, instead of a second receivable the same debtor could pay twice. Send it as the `Idempotency-Key` header, as the body's `idempotency_key`, or as both with the SAME value; two different values are refused rather than one silently winning.\n\n**`consumer_id` is REQUIRED for a `boleto` too**: it names the merchant-side consumer the receivable settles into, and its wallet is what the payment credits. Without it there is nothing to settle into and the call is refused with `consumer_id_required` before anything is sent. In a test project any stable id of your own works: the project's shared-sandbox receiver stands in for the consumer's account at the issuer (the consumer is never onboarded there), and `POST /v1/test/charges/{chargeId}/pay` settles the charge into that consumer's wallet.\n\n**A test project with its own sandbox account** (prepared by the platform, its receiving capability active) receives every charge, `boleto` and immediate `pix` alike, into that account, on the Pix key registered for it, and nowhere else. `consumer_id` may then be omitted when the project has exactly one consumer with such an account. A consumer whose account is not ready yet is refused with `receiving_identity_missing` and `details.not_ready` (`receiver_not_bound` or `pix_key_pending`), before anything is sent.\n\nAn agreement in N instalments is N cobranças, one per parcela, each with its own `due_date` and its own key. There is no single instalment charge.\n\n**Each refusal names a `reason`, and the reason is what to branch on.** The two error `code` values (`invalid_args`, `provider_error`) are too coarse: they cover six different situations, and reading them as one would turn `not found` into `bad request`.\n\n| reason | status | what it means |\n|---|---|---|\n| `charge_id_missing` | 400 | the call named no charge |\n| `project_scope_missing` | 400 | the credential is not project-scoped, and a charge belongs to one project |\n| `consumer_id_required` | 400 | a `boleto` create named no `consumer_id`, so there is no wallet for the receivable to settle into |\n| `charge_not_found` | 404 | no charge under that id FOR THIS TENANT |\n| `charge_reference_ambiguous` | 409 | the reference is one charge's id AND another's idempotency key; query by the charge id |\n| `issuance_unconfirmed` | 409 | the key holds a reservation whose create never got an answer |\n| `already_payment_notified` | 409 | the clearing house already notified a payment |\n| `not_cancellable_in_this_state` | 409 | the issuer accepts a cancellation only in some states |\n| `provider_status_unreadable` | 502 | the issuer did not answer the read |\n| `provider_cancel_failed` | 502 | the issuer refused the withdrawal |\n| `project_access_call_cap` | 429 | a test project with its own sandbox account reached its limit of sandbox calls (60 a clock hour, 300 a day, shared with every other call of the project); nothing was sent, retry after `Retry-After` seconds |\n| `project_access_calls_unavailable` | 503 | that project's register of sandbox calls could not be written; nothing was sent, retry after `Retry-After` seconds |\n\n`charge_not_found` is deliberately the SAME answer for an id that belongs to another project and for an id that exists nowhere. Telling those apart would be an oracle about another tenant over a string anyone can guess.", + "description": "Issues an inbound charge: the buyer pays the merchant. The RAIL IS A FIELD, not a path. `method: \"pix\"` mints an immediate Pix that hands back its copy-and-paste string right away and expires in about an hour. `method: \"boleto\"` WITH a `due_date` issues a cobrança com vencimento: ONE receivable the payer settles either as a boleto (barcode and linha digitável) or by Pix. One debt, two payable legs, never two documents.\n\n**The cobrança com vencimento answers `PROCESSING` with `payable: false` and no document.** The instrument registers with the clearing house first. Subscribe to `commerce.charge.created` rather than polling for a barcode that is not late, only not made yet. `commerce.charge.paid` is the event that means the funds arrived, by either leg: it is published only after CodeSpar settled the charge and credited the wallet, never on the provider's word alone, and once per charge. A charge the issuer refuses to register closes as `local_status: \"failed\"` and publishes `commerce.charge.failed` once instead.\n\n**`idempotency_key` is REQUIRED for that combination**, and it is checked before anything reaches the issuer. A repeat with the same key returns the charge already issued, or its still-open reservation, instead of a second receivable the same debtor could pay twice. Send it as the `Idempotency-Key` header, as the body's `idempotency_key`, or as both with the SAME value; two different values are refused rather than one silently winning.\n\n**`consumer_id` is REQUIRED for a `boleto` too**: it names the merchant-side consumer the receivable settles into, and its wallet is what the payment credits. Without it there is nothing to settle into and the call is refused with `consumer_id_required` before anything is sent. In a test project any stable id of your own works: the project's shared-sandbox receiver stands in for the consumer's account at the issuer (the consumer is never onboarded there), and `POST /v1/test/charges/{chargeId}/pay` settles the charge into that consumer's wallet.\n\n**A test project with its own sandbox account** (prepared by the platform, its receiving capability active) receives every charge, `boleto` and immediate `pix` alike, into that account, on the Pix key registered for it, and nowhere else. `consumer_id` may then be omitted when the project has exactly one consumer with such an account. A consumer whose account is not ready yet is refused with `receiving_identity_missing` and `details.not_ready` (`receiver_not_bound` or `pix_key_pending`), before anything is sent.\n\nAn agreement in N instalments is N cobranças, one per parcela, each with its own `due_date` and its own key. There is no single instalment charge.\n\n**Each refusal names a `reason`, and the reason is what to branch on.** The two error `code` values (`invalid_args`, `provider_error`) are too coarse: they cover six different situations, and reading them as one would turn `not found` into `bad request`.\n\n| reason | status | what it means |\n|---|---|---|\n| `charge_id_missing` | 400 | the call named no charge |\n| `project_scope_missing` | 400 | the credential is not project-scoped, and a charge belongs to one project |\n| `consumer_id_required` | 400 | a `boleto` create named no `consumer_id`, so there is no wallet for the receivable to settle into |\n| `charge_not_found` | 404 | no charge under that id FOR THIS TENANT |\n| `charge_reference_ambiguous` | 409 | the reference is one charge's id AND another's idempotency key; query by the charge id |\n| `issuance_unconfirmed` | 409 | the key holds a reservation whose create never got an answer |\n| `already_payment_notified` | 409 | the clearing house already notified a payment |\n| `not_cancellable_in_this_state` | 409 | the issuer accepts a cancellation only in some states |\n| `provider_status_unreadable` | 502 | the issuer did not answer the read |\n| `provider_cancel_failed` | 502 | the issuer refused the withdrawal |\n| `project_access_call_cap` | 429 | a test project with its own sandbox account reached its limit of sandbox calls (60 a clock hour, 300 a day, shared with every other call of the project); nothing was sent, retry after `Retry-After` seconds |\n| `project_access_calls_unavailable` | 503 | that project's register of sandbox calls could not be written; nothing was sent, retry after `Retry-After` seconds |\n\n`charge_not_found` is deliberately the SAME answer for an id that belongs to another project and for an id that exists nowhere. Telling those apart would be an oracle about another tenant over a string anyone can guess.", "requestBody": { "content": { "application/json": { @@ -38356,11 +45589,40 @@ }, "local_status": { "type": "string", - "description": "What CodeSpar recorded, which is a different question from `status`." + "description": "What CodeSpar recorded, which is a different question from `status`: `pending`, `settled`, `expired` (cancelled or expired unpaid) or `failed`. `failed` is terminal: the issuer refused to register the charge (`status: \"ERROR\"`, no boleto and no Pix ever issued), so nothing was ever payable and nothing was charged; `failure` says why. Create a new charge. PROCESSING, a slow registration or a missing callback are never `failed`." + }, + "failure": { + "type": "object", + "properties": { + "code": { + "type": "string", + "description": "`issuer_rejected`: the issuer refused to register the charge." + }, + "provider_status": { + "type": [ + "string", + "null" + ], + "description": "The issuer's own word, preserved (`ERROR`)." + }, + "failed_at": { + "type": [ + "string", + "null" + ], + "description": "When CodeSpar closed the charge as failed." + } + }, + "required": [ + "code", + "provider_status", + "failed_at" + ], + "description": "Present only when `local_status` is `failed`. The charge's history, ids and correlation stay readable; `commerce.charge.failed` was published once when it closed." }, "status_conflict": { "type": "boolean", - "description": "True whenever the issuer's known state and ours disagree, instead of one of them silently winning. They agree only as follows: our `pending` beside the issuer's PENDING or PROCESSING; our `settled` beside CONFIRMED or PENDING (the issuer's read can lag a payment); our `expired` beside CANCELLED or PENDING (lag after a cancel). Every other pair is a conflict, including an issuer ERROR, an issuer terminal state on a charge we still hold open, and a status spelling we do not recognise. False when no issuer state is known at all. `settlement: \"unconfirmable\"` is the narrower case of both sides terminal and different." + "description": "True whenever the issuer's known state and ours disagree, instead of one of them silently winning. They agree only as follows: our `pending` beside the issuer's PENDING or PROCESSING; our `settled` beside CONFIRMED or PENDING (the issuer's read can lag a payment); our `expired` beside CANCELLED or PENDING (lag after a cancel); our `failed` beside ERROR (the refusal it records). Every other pair is a conflict, including an issuer ERROR, an issuer terminal state on a charge we still hold open, and a status spelling we do not recognise. False when no issuer state is known at all. `settlement: \"unconfirmable\"` is the narrower case of both sides terminal and different." }, "method": { "type": "string" @@ -38637,11 +45899,40 @@ }, "local_status": { "type": "string", - "description": "What CodeSpar recorded, which is a different question from `status`." + "description": "What CodeSpar recorded, which is a different question from `status`: `pending`, `settled`, `expired` (cancelled or expired unpaid) or `failed`. `failed` is terminal: the issuer refused to register the charge (`status: \"ERROR\"`, no boleto and no Pix ever issued), so nothing was ever payable and nothing was charged; `failure` says why. Create a new charge. PROCESSING, a slow registration or a missing callback are never `failed`." + }, + "failure": { + "type": "object", + "properties": { + "code": { + "type": "string", + "description": "`issuer_rejected`: the issuer refused to register the charge." + }, + "provider_status": { + "type": [ + "string", + "null" + ], + "description": "The issuer's own word, preserved (`ERROR`)." + }, + "failed_at": { + "type": [ + "string", + "null" + ], + "description": "When CodeSpar closed the charge as failed." + } + }, + "required": [ + "code", + "provider_status", + "failed_at" + ], + "description": "Present only when `local_status` is `failed`. The charge's history, ids and correlation stay readable; `commerce.charge.failed` was published once when it closed." }, "status_conflict": { "type": "boolean", - "description": "True whenever the issuer's known state and ours disagree, instead of one of them silently winning. They agree only as follows: our `pending` beside the issuer's PENDING or PROCESSING; our `settled` beside CONFIRMED or PENDING (the issuer's read can lag a payment); our `expired` beside CANCELLED or PENDING (lag after a cancel). Every other pair is a conflict, including an issuer ERROR, an issuer terminal state on a charge we still hold open, and a status spelling we do not recognise. False when no issuer state is known at all. `settlement: \"unconfirmable\"` is the narrower case of both sides terminal and different." + "description": "True whenever the issuer's known state and ours disagree, instead of one of them silently winning. They agree only as follows: our `pending` beside the issuer's PENDING or PROCESSING; our `settled` beside CONFIRMED or PENDING (the issuer's read can lag a payment); our `expired` beside CANCELLED or PENDING (lag after a cancel); our `failed` beside ERROR (the refusal it records). Every other pair is a conflict, including an issuer ERROR, an issuer terminal state on a charge we still hold open, and a status spelling we do not recognise. False when no issuer state is known at all. `settlement: \"unconfirmable\"` is the narrower case of both sides terminal and different." }, "method": { "type": "string" @@ -38963,11 +46254,40 @@ }, "local_status": { "type": "string", - "description": "What CodeSpar recorded, which is a different question from `status`." + "description": "What CodeSpar recorded, which is a different question from `status`: `pending`, `settled`, `expired` (cancelled or expired unpaid) or `failed`. `failed` is terminal: the issuer refused to register the charge (`status: \"ERROR\"`, no boleto and no Pix ever issued), so nothing was ever payable and nothing was charged; `failure` says why. Create a new charge. PROCESSING, a slow registration or a missing callback are never `failed`." + }, + "failure": { + "type": "object", + "properties": { + "code": { + "type": "string", + "description": "`issuer_rejected`: the issuer refused to register the charge." + }, + "provider_status": { + "type": [ + "string", + "null" + ], + "description": "The issuer's own word, preserved (`ERROR`)." + }, + "failed_at": { + "type": [ + "string", + "null" + ], + "description": "When CodeSpar closed the charge as failed." + } + }, + "required": [ + "code", + "provider_status", + "failed_at" + ], + "description": "Present only when `local_status` is `failed`. The charge's history, ids and correlation stay readable; `commerce.charge.failed` was published once when it closed." }, "status_conflict": { "type": "boolean", - "description": "True whenever the issuer's known state and ours disagree, instead of one of them silently winning. They agree only as follows: our `pending` beside the issuer's PENDING or PROCESSING; our `settled` beside CONFIRMED or PENDING (the issuer's read can lag a payment); our `expired` beside CANCELLED or PENDING (lag after a cancel). Every other pair is a conflict, including an issuer ERROR, an issuer terminal state on a charge we still hold open, and a status spelling we do not recognise. False when no issuer state is known at all. `settlement: \"unconfirmable\"` is the narrower case of both sides terminal and different." + "description": "True whenever the issuer's known state and ours disagree, instead of one of them silently winning. They agree only as follows: our `pending` beside the issuer's PENDING or PROCESSING; our `settled` beside CONFIRMED or PENDING (the issuer's read can lag a payment); our `expired` beside CANCELLED or PENDING (lag after a cancel); our `failed` beside ERROR (the refusal it records). Every other pair is a conflict, including an issuer ERROR, an issuer terminal state on a charge we still hold open, and a status spelling we do not recognise. False when no issuer state is known at all. `settlement: \"unconfirmable\"` is the narrower case of both sides terminal and different." }, "method": { "type": "string" @@ -39260,7 +46580,7 @@ "/v1/test/charges/{chargeId}/pay": { "post": { "summary": "Pay a charge in the sandbox", - "description": "Plays the DEBTOR of a test charge: settles it through the SAME path a Celcoin `charge-in` webhook takes (translate, publish `commerce.charge.paid`, reconcile, ledger `fund()` with the `pending -> settled` claim). It is not a status write, so the event fans out to your triggers exactly as a real payment would, and the ledger and receipt side effects are the ones production produces.\n\n**Test-mode only, fail-closed.** A live-environment key or project answers 403 `sandbox_pay_not_permitted` before the body is read or any query runs.\n\n**Nothing claims money moved.** The event payload, the ledger entry and the charge row all carry `simulated: true` and `settled_against: \"sandbox_fixture\"`; a real `charge-in` never carries either.\n\n**Only a payable charge settles.** The debtor can only pay a document the issuer handed over: the charge must be open, a boleto or Pix recorded, and the issuer's last known status PENDING (or CONFIRMED, the issuer already calling it paid) — the conditions of `payable: true` on the read. Anything else is refused with 409 `charge_not_payable` before anything is written, exactly as a live debtor would find nothing to pay.\n\n**Idempotent.** The provider event id is the one the real delivery would carry, so a second pay dedupes at the event (no second trigger fire), the ledger dedupes on the charge, and a charge already `settled` answers its recorded state with `idempotent_replay: true` whatever amount the second call names.\n\n`chargeId` is the id `create` returned, or your own idempotency key, resolved under the caller's org and project: another tenant's charge is `charge_not_found`, never `forbidden`.", + "description": "Plays the DEBTOR of a test charge: settles it through the SAME path a Celcoin `charge-in` webhook takes (translate, reconcile, ledger `fund()` with the `pending -> settled` claim, and `commerce.charge.paid` written by that same settling transaction). It is not a status write, so the event fans out to your triggers exactly as a real payment would, and the ledger and receipt side effects are the ones production produces.\n\n**Test-mode only, fail-closed.** A live-environment key or project answers 403 `sandbox_pay_not_permitted` before the body is read or any query runs.\n\n**Nothing claims money moved.** The event payload, the ledger entry and the charge row all carry `simulated: true` and `settled_against: \"sandbox_fixture\"`; a real `charge-in` never carries either.\n\n**Only a payable charge settles.** The debtor can only pay a document the issuer handed over: the charge must be open, a boleto or Pix recorded, and the issuer's last known status PENDING (or CONFIRMED, the issuer already calling it paid) — the conditions of `payable: true` on the read. Anything else is refused with 409 `charge_not_payable` before anything is written, exactly as a live debtor would find nothing to pay.\n\n**Idempotent.** The provider event id is the one the real delivery would carry, so a second pay dedupes at the event (no second trigger fire), the ledger dedupes on the charge, and a charge already `settled` answers its recorded state with `idempotent_replay: true` whatever amount the second call names.\n\n`chargeId` is the id `create` returned, or your own idempotency key, resolved under the caller's org and project: another tenant's charge is `charge_not_found`, never `forbidden`.", "parameters": [ { "schema": { @@ -39547,7 +46867,7 @@ } }, "409": { - "description": "The charge exists and cannot be paid, and nothing was settled, credited or published: `issuance_unconfirmed` is a reservation whose create never got an answer; `charge_not_payable` is a charge with no document a debtor could pay, and `details.reason` says which: `issuer_rejected` (the issuer left it in ERROR, no boleto or Pix ever existed — terminal, create a new charge), `charge_closed` (expired or cancelled, ours or the issuer's — terminal, create a new charge), `instrument_not_registered` (the issuer has not handed over a boleto or Pix yet — read the charge and pay once it answers `payable: true`); `charge_reference_ambiguous` is a reference that is one charge's id and another's idempotency key — pay by the charge id; `collect_simulated_settle_refused` is a Collect link's charge, issued on a real rail: in Test it is paid with POST /v1/collect/attempts/{attemptId}/test-pay (`details.next_action`), never by this simulation.", + "description": "The charge exists and cannot be paid, and nothing was settled, credited or published: `issuance_unconfirmed` is a reservation whose create never got an answer; `charge_not_payable` is a charge with no document a debtor could pay, and `details.reason` says which: `issuer_rejected` (the issuer left it in ERROR, no boleto or Pix ever existed, and the charge reads `local_status: \"failed\"` once closed — terminal, create a new charge), `charge_closed` (expired or cancelled, ours or the issuer's — terminal, create a new charge), `instrument_not_registered` (the issuer has not handed over a boleto or Pix yet — read the charge and pay once it answers `payable: true`); `charge_reference_ambiguous` is a reference that is one charge's id and another's idempotency key — pay by the charge id; `collect_simulated_settle_refused` is a Collect link's charge, issued on a real rail: in Test it is paid with POST /v1/collect/attempts/{attemptId}/test-pay (`details.next_action`), never by this simulation.", "content": { "application/json": { "schema": { @@ -39654,7 +46974,7 @@ "post": { "deprecated": true, "summary": "Pay a charge in the sandbox (alias path)", - "description": "Alias of `POST /v1/test/charges/{chargeId}/pay` (ent#979 contract: one handler, two paths, one scope). Same body, same answers.\n\nPlays the DEBTOR of a test charge: settles it through the SAME path a Celcoin `charge-in` webhook takes (translate, publish `commerce.charge.paid`, reconcile, ledger `fund()` with the `pending -> settled` claim). It is not a status write, so the event fans out to your triggers exactly as a real payment would, and the ledger and receipt side effects are the ones production produces.\n\n**Test-mode only, fail-closed.** A live-environment key or project answers 403 `sandbox_pay_not_permitted` before the body is read or any query runs.\n\n**Nothing claims money moved.** The event payload, the ledger entry and the charge row all carry `simulated: true` and `settled_against: \"sandbox_fixture\"`; a real `charge-in` never carries either.\n\n**Only a payable charge settles.** The debtor can only pay a document the issuer handed over: the charge must be open, a boleto or Pix recorded, and the issuer's last known status PENDING (or CONFIRMED, the issuer already calling it paid) — the conditions of `payable: true` on the read. Anything else is refused with 409 `charge_not_payable` before anything is written, exactly as a live debtor would find nothing to pay.\n\n**Idempotent.** The provider event id is the one the real delivery would carry, so a second pay dedupes at the event (no second trigger fire), the ledger dedupes on the charge, and a charge already `settled` answers its recorded state with `idempotent_replay: true` whatever amount the second call names.\n\n`chargeId` is the id `create` returned, or your own idempotency key, resolved under the caller's org and project: another tenant's charge is `charge_not_found`, never `forbidden`.", + "description": "Alias of `POST /v1/test/charges/{chargeId}/pay` (ent#979 contract: one handler, two paths, one scope). Same body, same answers.\n\nPlays the DEBTOR of a test charge: settles it through the SAME path a Celcoin `charge-in` webhook takes (translate, reconcile, ledger `fund()` with the `pending -> settled` claim, and `commerce.charge.paid` written by that same settling transaction). It is not a status write, so the event fans out to your triggers exactly as a real payment would, and the ledger and receipt side effects are the ones production produces.\n\n**Test-mode only, fail-closed.** A live-environment key or project answers 403 `sandbox_pay_not_permitted` before the body is read or any query runs.\n\n**Nothing claims money moved.** The event payload, the ledger entry and the charge row all carry `simulated: true` and `settled_against: \"sandbox_fixture\"`; a real `charge-in` never carries either.\n\n**Only a payable charge settles.** The debtor can only pay a document the issuer handed over: the charge must be open, a boleto or Pix recorded, and the issuer's last known status PENDING (or CONFIRMED, the issuer already calling it paid) — the conditions of `payable: true` on the read. Anything else is refused with 409 `charge_not_payable` before anything is written, exactly as a live debtor would find nothing to pay.\n\n**Idempotent.** The provider event id is the one the real delivery would carry, so a second pay dedupes at the event (no second trigger fire), the ledger dedupes on the charge, and a charge already `settled` answers its recorded state with `idempotent_replay: true` whatever amount the second call names.\n\n`chargeId` is the id `create` returned, or your own idempotency key, resolved under the caller's org and project: another tenant's charge is `charge_not_found`, never `forbidden`.", "parameters": [ { "schema": { @@ -39941,7 +47261,7 @@ } }, "409": { - "description": "The charge exists and cannot be paid, and nothing was settled, credited or published: `issuance_unconfirmed` is a reservation whose create never got an answer; `charge_not_payable` is a charge with no document a debtor could pay, and `details.reason` says which: `issuer_rejected` (the issuer left it in ERROR, no boleto or Pix ever existed — terminal, create a new charge), `charge_closed` (expired or cancelled, ours or the issuer's — terminal, create a new charge), `instrument_not_registered` (the issuer has not handed over a boleto or Pix yet — read the charge and pay once it answers `payable: true`); `charge_reference_ambiguous` is a reference that is one charge's id and another's idempotency key — pay by the charge id; `collect_simulated_settle_refused` is a Collect link's charge, issued on a real rail: in Test it is paid with POST /v1/collect/attempts/{attemptId}/test-pay (`details.next_action`), never by this simulation.", + "description": "The charge exists and cannot be paid, and nothing was settled, credited or published: `issuance_unconfirmed` is a reservation whose create never got an answer; `charge_not_payable` is a charge with no document a debtor could pay, and `details.reason` says which: `issuer_rejected` (the issuer left it in ERROR, no boleto or Pix ever existed, and the charge reads `local_status: \"failed\"` once closed — terminal, create a new charge), `charge_closed` (expired or cancelled, ours or the issuer's — terminal, create a new charge), `instrument_not_registered` (the issuer has not handed over a boleto or Pix yet — read the charge and pay once it answers `payable: true`); `charge_reference_ambiguous` is a reference that is one charge's id and another's idempotency key — pay by the charge id; `collect_simulated_settle_refused` is a Collect link's charge, issued on a real rail: in Test it is paid with POST /v1/collect/attempts/{attemptId}/test-pay (`details.next_action`), never by this simulation.", "content": { "application/json": { "schema": { @@ -62272,6 +69592,52 @@ "at" ] } + }, + "executor": { + "type": [ + "string", + "null" + ], + "enum": [ + "codespar_simulator", + "provider_sandbox" + ], + "description": "Who executes (or executed) the payment, by the same name the integrator chooses with on POST /v1/consents. `codespar_simulator` (\"Simulado pela CodeSpar\": no provider is called) or `provider_sandbox` (the provider's sandbox, over the account the server bound to this consumer); both Test only. Null when no executor applies, Live included. The name is the MODE: the provider, account, project, consumer and environment are resolved by the server before the signature and checked again when the payment runs; no request field chooses them (`executor_provider_not_selectable`), and a provider failure is never turned into a simulation. Records written before this name existed keep their stored value and are read in these words." + }, + "executor_provider": { + "type": [ + "string", + "null" + ], + "enum": [ + "celcoin" + ], + "description": "The concrete provider behind `executor`, as the server resolved it: `celcoin` for `provider_sandbox`; null for `codespar_simulator` (no provider is called) and when `executor` is null. Read-only." + }, + "executor_label": { + "type": [ + "string", + "null" + ], + "description": "The executor's label as the consent screen, the dashboard and the receipt show it. In Test it ends \"· sem dinheiro real\"." + }, + "environment": { + "type": [ + "string", + "null" + ], + "enum": [ + "test", + "live" + ], + "description": "The project's environment." + }, + "real_money": { + "type": [ + "boolean", + "null" + ], + "description": "False in Test, always: no real money moves, including when the provider's sandbox CONFIRMED the operation (`moneyMoved: true` / `settlement: \"confirmed\"` then mean the sandbox settled it). True in Live." } }, "required": [ @@ -62287,7 +69653,12 @@ "receipt_sig", "receipt_sig_ed25519", "receipt_sig_kid", - "exceptions" + "exceptions", + "executor", + "executor_provider", + "executor_label", + "environment", + "real_money" ] } } @@ -62688,6 +70059,52 @@ ] } }, + "executor": { + "type": [ + "string", + "null" + ], + "enum": [ + "codespar_simulator", + "provider_sandbox" + ], + "description": "Who executes (or executed) the payment, by the same name the integrator chooses with on POST /v1/consents. `codespar_simulator` (\"Simulado pela CodeSpar\": no provider is called) or `provider_sandbox` (the provider's sandbox, over the account the server bound to this consumer); both Test only. Null when no executor applies, Live included. The name is the MODE: the provider, account, project, consumer and environment are resolved by the server before the signature and checked again when the payment runs; no request field chooses them (`executor_provider_not_selectable`), and a provider failure is never turned into a simulation. Records written before this name existed keep their stored value and are read in these words." + }, + "executor_provider": { + "type": [ + "string", + "null" + ], + "enum": [ + "celcoin" + ], + "description": "The concrete provider behind `executor`, as the server resolved it: `celcoin` for `provider_sandbox`; null for `codespar_simulator` (no provider is called) and when `executor` is null. Read-only." + }, + "executor_label": { + "type": [ + "string", + "null" + ], + "description": "The executor's label as the consent screen, the dashboard and the receipt show it. In Test it ends \"· sem dinheiro real\"." + }, + "environment": { + "type": [ + "string", + "null" + ], + "enum": [ + "test", + "live" + ], + "description": "The project's environment." + }, + "real_money": { + "type": [ + "boolean", + "null" + ], + "description": "False in Test, always: no real money moves, including when the provider's sandbox CONFIRMED the operation (`moneyMoved: true` / `settlement: \"confirmed\"` then mean the sandbox settled it). True in Live." + }, "payee": { "type": [ "object", @@ -62770,6 +70187,11 @@ "receipt_sig_ed25519", "receipt_sig_kid", "exceptions", + "executor", + "executor_provider", + "executor_label", + "environment", + "real_money", "payee" ] } @@ -73273,7 +80695,7 @@ } }, "403": { - "description": "Forbidden. The operation requires the `admin` role in the organization, resolved from the acting user forwarded in `x-codespar-user`. Known values of `error`: `insufficient_role`, `bearer_admin_role_missing`, `bearer_admin_user_not_member`, `bearer_admin_role_unresolved`. The same status and body shape also carry the scope gate's refusals, which reach every route in this subtree including the two reads: `forbidden` when the credential lacks the scope the route is mapped to, and the two alarms `scopes_unresolved` and `route_scope_unresolved`.", + "description": "Forbidden. On the dashboard the operation requires the `admin` role in the organization, resolved from the acting user forwarded in `x-codespar-user` (`insufficient_role`). An API key carrying `mcp-servers:write` is not refused by that gate; an OAuth access token is (`insufficient_role`). The fee sweep is administrative: an API key gets `admin_session_required` there, whatever its scopes. The same status and body shape also carry the scope gate's refusals, which reach every route in this subtree including the two reads: `forbidden` when the credential lacks the scope the route is mapped to, and the two alarms `scopes_unresolved` and `route_scope_unresolved`.", "content": { "application/json": { "schema": { @@ -73650,7 +81072,7 @@ } }, "403": { - "description": "Forbidden. The operation requires the `admin` role in the organization, resolved from the acting user forwarded in `x-codespar-user`. Known values of `error`: `insufficient_role`, `bearer_admin_role_missing`, `bearer_admin_user_not_member`, `bearer_admin_role_unresolved`. The same status and body shape also carry the scope gate's refusals, which reach every route in this subtree including the two reads: `forbidden` when the credential lacks the scope the route is mapped to, and the two alarms `scopes_unresolved` and `route_scope_unresolved`.", + "description": "Forbidden. On the dashboard the operation requires the `admin` role in the organization, resolved from the acting user forwarded in `x-codespar-user` (`insufficient_role`). An API key carrying `mcp-servers:write` is not refused by that gate; an OAuth access token is (`insufficient_role`). The fee sweep is administrative: an API key gets `admin_session_required` there, whatever its scopes. The same status and body shape also carry the scope gate's refusals, which reach every route in this subtree including the two reads: `forbidden` when the credential lacks the scope the route is mapped to, and the two alarms `scopes_unresolved` and `route_scope_unresolved`.", "content": { "application/json": { "schema": { @@ -74459,7 +81881,7 @@ } }, "403": { - "description": "Forbidden. The operation requires the `admin` role in the organization, resolved from the acting user forwarded in `x-codespar-user`. Known values of `error`: `insufficient_role`, `bearer_admin_role_missing`, `bearer_admin_user_not_member`, `bearer_admin_role_unresolved`. The same status and body shape also carry the scope gate's refusals, which reach every route in this subtree including the two reads: `forbidden` when the credential lacks the scope the route is mapped to, and the two alarms `scopes_unresolved` and `route_scope_unresolved`.", + "description": "Forbidden. On the dashboard the operation requires the `admin` role in the organization, resolved from the acting user forwarded in `x-codespar-user` (`insufficient_role`). An API key carrying `mcp-servers:write` is not refused by that gate; an OAuth access token is (`insufficient_role`). The fee sweep is administrative: an API key gets `admin_session_required` there, whatever its scopes. The same status and body shape also carry the scope gate's refusals, which reach every route in this subtree including the two reads: `forbidden` when the credential lacks the scope the route is mapped to, and the two alarms `scopes_unresolved` and `route_scope_unresolved`.", "content": { "application/json": { "schema": { @@ -74562,7 +81984,7 @@ "description": "No Content" }, "403": { - "description": "Forbidden. The operation requires the `admin` role in the organization, resolved from the acting user forwarded in `x-codespar-user`. Known values of `error`: `insufficient_role`, `bearer_admin_role_missing`, `bearer_admin_user_not_member`, `bearer_admin_role_unresolved`. The same status and body shape also carry the scope gate's refusals, which reach every route in this subtree including the two reads: `forbidden` when the credential lacks the scope the route is mapped to, and the two alarms `scopes_unresolved` and `route_scope_unresolved`.", + "description": "Forbidden. On the dashboard the operation requires the `admin` role in the organization, resolved from the acting user forwarded in `x-codespar-user` (`insufficient_role`). An API key carrying `mcp-servers:write` is not refused by that gate; an OAuth access token is (`insufficient_role`). The fee sweep is administrative: an API key gets `admin_session_required` there, whatever its scopes. The same status and body shape also carry the scope gate's refusals, which reach every route in this subtree including the two reads: `forbidden` when the credential lacks the scope the route is mapped to, and the two alarms `scopes_unresolved` and `route_scope_unresolved`.", "content": { "application/json": { "schema": { @@ -74788,7 +82210,7 @@ } }, "403": { - "description": "Forbidden. The operation requires the `admin` role in the organization, resolved from the acting user forwarded in `x-codespar-user`. Known values of `error`: `insufficient_role`, `bearer_admin_role_missing`, `bearer_admin_user_not_member`, `bearer_admin_role_unresolved`. The same status and body shape also carry the scope gate's refusals, which reach every route in this subtree including the two reads: `forbidden` when the credential lacks the scope the route is mapped to, and the two alarms `scopes_unresolved` and `route_scope_unresolved`.", + "description": "Forbidden. On the dashboard the operation requires the `admin` role in the organization, resolved from the acting user forwarded in `x-codespar-user` (`insufficient_role`). An API key carrying `mcp-servers:write` is not refused by that gate; an OAuth access token is (`insufficient_role`). The fee sweep is administrative: an API key gets `admin_session_required` there, whatever its scopes. The same status and body shape also carry the scope gate's refusals, which reach every route in this subtree including the two reads: `forbidden` when the credential lacks the scope the route is mapped to, and the two alarms `scopes_unresolved` and `route_scope_unresolved`.", "content": { "application/json": { "schema": { @@ -74877,7 +82299,7 @@ "/v1/mcp-servers/platform-fees/sweep": { "post": { "summary": "Move accrued platform fees to the organization's wallet now", - "description": "Settled tool calls on a server with `platform_fee_bps` above zero accrue a fee owed to the platform partner. This moves everything unswept for the calling organization to its provisioned platform wallet and marks those accruals swept. The body takes no fields.\n\nONE TRANSFER PER (ENVIRONMENT, SOURCE ACCOUNT) PAIR, NOT PER ACCOUNT. Accruals are grouped by the seller's source account AND the environment they were earned in, and each group is one on-chain transfer: `live` settles on Base, `test` on Base Sepolia. The source account name is derived from the organization and the seller's `consumer_id` and does not carry the environment, so ONE seller selling in both environments produces TWO transfers that repeat the same `source` in `transfers`, on two different chains. Do not read `transfers` as one row per seller, and do not sum a `source` expecting a single chain's movement.\n\nA BACKGROUND JOB ALREADY DOES THIS, hourly by default. This endpoint is the manual trigger over the same core; it is not the only way fees move, so a zero result usually means the job got there first.\n\nNOT IDEMPOTENT. Each call executes real transfers, so it is not safe to retry blindly. Concurrency is the one case that is handled for you: a per-organization lock is held for the pass, and a second caller arriving while one runs gets 409 `sweep_in_progress` and moves no money. A call that times out on the client side may still have transferred; re-read the result of the next sweep rather than repeating this one.\n\nPARTIAL SUCCESS IS A 200. A group whose transfer failed appears in `transfers` with `status: \"failed\"` and `tx: null`, its accruals are left unswept for the next pass, and the response is still 200. `swept` and `total_atomic` count the successful transfers only, so compare them against `transfers` rather than assuming everything moved. `total_atomic` sums across environments and is therefore not a single chain's amount.\n\nWith nothing to sweep the response is `swept: 0`, `total_atomic: \"0\"`, an empty `transfers`, and no `partner_wallet`.\n\n503 `payto_provisioning_unavailable` is broader than its name: the handler maps EVERY error thrown by the pass to that one code, so it covers a database failure during the sweep as well as a platform wallet that could not be provisioned.\n\nThis operation needs the `platform-fees:sweep` scope, which the other seven do not.", + "description": "Settled tool calls on a server with `platform_fee_bps` above zero accrue a fee owed to the platform partner. This moves everything unswept for the calling organization to its provisioned platform wallet and marks those accruals swept. The body takes no fields.\n\nONE TRANSFER PER (ENVIRONMENT, SOURCE ACCOUNT) PAIR, NOT PER ACCOUNT. Accruals are grouped by the seller's source account AND the environment they were earned in, and each group is one on-chain transfer: `live` settles on Base, `test` on Base Sepolia. The source account name is derived from the organization and the seller's `consumer_id` and does not carry the environment, so ONE seller selling in both environments produces TWO transfers that repeat the same `source` in `transfers`, on two different chains. Do not read `transfers` as one row per seller, and do not sum a `source` expecting a single chain's movement.\n\nA BACKGROUND JOB ALREADY DOES THIS, hourly by default. This endpoint is the manual trigger over the same core; it is not the only way fees move, so a zero result usually means the job got there first.\n\nNOT IDEMPOTENT. Each call executes real transfers, so it is not safe to retry blindly. Concurrency is the one case that is handled for you: a per-organization lock is held for the pass, and a second caller arriving while one runs gets 409 `sweep_in_progress` and moves no money. A call that times out on the client side may still have transferred; re-read the result of the next sweep rather than repeating this one.\n\nPARTIAL SUCCESS IS A 200. A group whose transfer failed appears in `transfers` with `status: \"failed\"` and `tx: null`, its accruals are left unswept for the next pass, and the response is still 200. `swept` and `total_atomic` count the successful transfers only, so compare them against `transfers` rather than assuming everything moved. `total_atomic` sums across environments and is therefore not a single chain's amount.\n\nWith nothing to sweep the response is `swept: 0`, `total_atomic: \"0\"`, an empty `transfers`, and no `partner_wallet`.\n\n503 `payto_provisioning_unavailable` is broader than its name: the handler maps EVERY error thrown by the pass to that one code, so it covers a database failure during the sweep as well as a platform wallet that could not be provisioned.\n\nAdministrative, unlike the other seven: an admin or owner performs it from the dashboard, and an API key is refused with 403 `admin_session_required`, whatever its scopes.", "responses": { "200": { "description": "OK", @@ -74945,7 +82367,7 @@ } }, "403": { - "description": "Forbidden. The operation requires the `admin` role in the organization, resolved from the acting user forwarded in `x-codespar-user`. Known values of `error`: `insufficient_role`, `bearer_admin_role_missing`, `bearer_admin_user_not_member`, `bearer_admin_role_unresolved`. The same status and body shape also carry the scope gate's refusals, which reach every route in this subtree including the two reads: `forbidden` when the credential lacks the scope the route is mapped to, and the two alarms `scopes_unresolved` and `route_scope_unresolved`.", + "description": "Forbidden. On the dashboard the operation requires the `admin` role in the organization, resolved from the acting user forwarded in `x-codespar-user` (`insufficient_role`). An API key carrying `mcp-servers:write` is not refused by that gate; an OAuth access token is (`insufficient_role`). The fee sweep is administrative: an API key gets `admin_session_required` there, whatever its scopes. The same status and body shape also carry the scope gate's refusals, which reach every route in this subtree including the two reads: `forbidden` when the credential lacks the scope the route is mapped to, and the two alarms `scopes_unresolved` and `route_scope_unresolved`.", "content": { "application/json": { "schema": { @@ -80607,7 +88029,7 @@ } }, "403": { - "description": "Forbidden. The acting user does not satisfy the org-role guard in front of this route. With an OAuth access token this is the live behaviour when `x-codespar-user` is absent or names a user below admin; with an API key it appears only where the deployment enforces the same guard.", + "description": "Forbidden. The org-role guard in front of this route refused. It refuses an OAuth access token, which is not the dashboard, whatever `x-codespar-user` says. An API key is not refused by this guard: its grant is its scope.", "content": { "application/json": { "schema": { @@ -80615,7 +88037,9 @@ "properties": { "error": { "type": "string", - "description": "`insufficient_role` on the ordinary path." + "enum": [ + "insufficient_role" + ] }, "required": { "type": "string", @@ -80623,17 +88047,6 @@ "admin" ], "description": "The minimum org role this route asks for." - }, - "message": { - "type": "string", - "description": "Present only on the enforced API-key path." - }, - "status": { - "type": "number", - "enum": [ - 403 - ], - "description": "Present only on the enforced API-key path." } }, "required": [ @@ -81220,7 +88633,7 @@ } }, "403": { - "description": "Forbidden. The acting user does not satisfy the org-role guard in front of this route. With an OAuth access token this is the live behaviour when `x-codespar-user` is absent or names a user below admin; with an API key it appears only where the deployment enforces the same guard.", + "description": "Forbidden. The org-role guard in front of this route refused. It refuses an OAuth access token, which is not the dashboard, whatever `x-codespar-user` says. An API key is not refused by this guard: its grant is its scope.", "content": { "application/json": { "schema": { @@ -81228,7 +88641,9 @@ "properties": { "error": { "type": "string", - "description": "`insufficient_role` on the ordinary path." + "enum": [ + "insufficient_role" + ] }, "required": { "type": "string", @@ -81236,17 +88651,6 @@ "admin" ], "description": "The minimum org role this route asks for." - }, - "message": { - "type": "string", - "description": "Present only on the enforced API-key path." - }, - "status": { - "type": "number", - "enum": [ - 403 - ], - "description": "Present only on the enforced API-key path." } }, "required": [ @@ -81608,7 +89012,7 @@ }, "delete": { "summary": "Delete a paywall", - "description": "HARD delete, and 204 with no body. The row is removed rather than deactivated, because a paywall is configuration and not audit data; if what you want is to stop serving while keeping the row, patch `active` to false instead.\n\nWHAT IT DOES NOT DELETE: the settlement evidence and the metered refund attempts. Neither carries a foreign key to the paywall, so both survive the delete. What is lost is the way IN to them, since the stats operation resolves the paywall first and answers 404 once the row is gone. Read the stats before deleting if you need the totals.\n\nThe slug returns to the global namespace and any other tenant may then claim it, so a delete-and-recreate is not guaranteed to get the same gateway URL back.\n\nAUTHORIZATION, as deployed rather than as named, and it is NOT the same for the two credentials this document describes.\n\nWith an OAUTH ACCESS TOKEN the org-role guard in front of this route is ordinary and live: the acting user must be forwarded in `x-codespar-user` and must hold at least the admin role in the organization. No header, or a user who is not an admin, is 403 `insufficient_role` before the handler runs.\n\nWith an API KEY the same guard is in a measurement window: it resolves the forwarded user, RECORDS the request when that user would not have sufficed, and lets it through anyway. So today a key carrying `paywalls:write` deletes without forwarding anybody. A deployment that closes the window refuses those calls with 403 as well, so forward `x-codespar-user` if you have it: it is already required on the token path, it is inert on the key path while the window is open, and it is what keeps the call working when the window closes.", + "description": "HARD delete, and 204 with no body. The row is removed rather than deactivated, because a paywall is configuration and not audit data; if what you want is to stop serving while keeping the row, patch `active` to false instead.\n\nWHAT IT DOES NOT DELETE: the settlement evidence and the metered refund attempts. Neither carries a foreign key to the paywall, so both survive the delete. What is lost is the way IN to them, since the stats operation resolves the paywall first and answers 404 once the row is gone. Read the stats before deleting if you need the totals.\n\nThe slug returns to the global namespace and any other tenant may then claim it, so a delete-and-recreate is not guaranteed to get the same gateway URL back.\n\nAUTHORIZATION. With an API KEY the grant is the key's scope: a key carrying `paywalls:write` deletes, and `x-codespar-user` is not read. Only an admin mints a key. An OAUTH ACCESS TOKEN is refused with 403 `insufficient_role` before the handler runs: this write belongs to a key or to the dashboard.", "parameters": [ { "schema": { @@ -81624,7 +89028,7 @@ "description": "No Content" }, "403": { - "description": "Forbidden. The acting user does not satisfy the org-role guard in front of this route. With an OAuth access token this is the live behaviour when `x-codespar-user` is absent or names a user below admin; with an API key it appears only where the deployment enforces the same guard.", + "description": "Forbidden. The org-role guard in front of this route refused. It refuses an OAuth access token, which is not the dashboard, whatever `x-codespar-user` says. An API key is not refused by this guard: its grant is its scope.", "content": { "application/json": { "schema": { @@ -81632,7 +89036,9 @@ "properties": { "error": { "type": "string", - "description": "`insufficient_role` on the ordinary path." + "enum": [ + "insufficient_role" + ] }, "required": { "type": "string", @@ -81640,17 +89046,6 @@ "admin" ], "description": "The minimum org role this route asks for." - }, - "message": { - "type": "string", - "description": "Present only on the enforced API-key path." - }, - "status": { - "type": "number", - "enum": [ - 403 - ], - "description": "Present only on the enforced API-key path." } }, "required": [ @@ -109282,6 +116677,51 @@ } } }, + "409": { + "description": "A Test project the own-account rule reaches has no own account yet: there is no account to state, so no statement (never the simulator's residue as the account's, nor an empty one closing at 0).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "statement_account_missing" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, "500": { "description": "The ledger of the period does not reconcile; logged, nothing served.", "content": { @@ -110704,8 +118144,147 @@ } } }, - "409": { - "description": "No source of the asked groups exists in this environment.", + "409": { + "description": "No source of the asked groups exists in this environment.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "research_no_sources" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + }, + "503": { + "description": "No source answered, or Shop purchases are off on this deployment.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "research_no_sources", + "shop_purchases_disabled" + ] + }, + "message": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": {} + } + }, + "required": [ + "code", + "message" + ] + }, + "request_id": { + "type": [ + "string", + "null" + ], + "description": "Echoes the `X-Request-Id` header when the request carried one." + } + }, + "required": [ + "error", + "request_id" + ] + } + } + } + } + }, + "x-codespar-scope": "shop:purchases:write", + "security": [ + { + "bearerAuth": [ + "shop:purchases:write" + ] + } + ] + } + }, + "/v1/shop/agent/research/{id}": { + "get": { + "summary": "Read a research back", + "description": "Scope `shop:purchases:read`. The research this project's keys ran, with each offer's `stale` computed at the time of the answer.\n\n**What an assistant can and cannot do.** It proposes a purchase and reads where it stands; it never pays, approves, saves a card or logs in at a store. A verified person presses Pagar on the dashboard and completes what the purchase waits for (the protected card or CVV form, the store login); the purchase then runs through the same executor as the Shop's own chat, at most once at the store. No answer carries a card number, a security code, a cookie or a collect secret. Test projects only in this first delivery; behind `SHOP_PURCHASES_ENABLED`.", + "parameters": [ + { + "schema": { + "type": "string", + "description": "The research id (`srr_...`), from `POST /v1/shop/agent/research`." + }, + "required": true, + "description": "The research id (`srr_...`), from `POST /v1/shop/agent/research`.", + "name": "id", + "in": "path" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "research": { + "type": "object", + "additionalProperties": {}, + "description": "The research as CONTRATO-I2 describes it: offers, recommendation, sources." + } + }, + "required": [ + "research" + ] + } + } + } + }, + "403": { + "description": "The key does not hold `shop:purchases:read`.", "content": { "application/json": { "schema": { @@ -110715,10 +118294,7 @@ "type": "object", "properties": { "code": { - "type": "string", - "enum": [ - "research_no_sources" - ] + "type": "string" }, "message": { "type": "string" @@ -110749,79 +118325,42 @@ } } }, - "503": { - "description": "No source answered, or Shop purchases are off on this deployment.", + "404": { + "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { - "type": "object", - "properties": { - "code": { - "type": "string", - "enum": [ - "research_no_sources", - "shop_purchases_disabled" - ] - }, - "message": { - "type": "string" - }, - "details": { - "type": "object", - "additionalProperties": {} - } - }, - "required": [ - "code", - "message" + "type": "string", + "enum": [ + "not_found" ] - }, - "request_id": { - "type": [ - "string", - "null" - ], - "description": "Echoes the `X-Request-Id` header when the request carried one." } }, "required": [ - "error", - "request_id" + "error" ] } } } } }, - "x-codespar-scope": "shop:purchases:write", + "x-codespar-scope": "shop:purchases:read", "security": [ { "bearerAuth": [ - "shop:purchases:write" + "shop:purchases:read" ] } ] } }, - "/v1/shop/agent/research/{id}": { + "/v1/shop/agent/capabilities": { "get": { - "summary": "Read a research back", - "description": "Scope `shop:purchases:read`. The research this project's keys ran, with each offer's `stale` computed at the time of the answer.\n\n**What an assistant can and cannot do.** It proposes a purchase and reads where it stands; it never pays, approves, saves a card or logs in at a store. A verified person presses Pagar on the dashboard and completes what the purchase waits for (the protected card or CVV form, the store login); the purchase then runs through the same executor as the Shop's own chat, at most once at the store. No answer carries a card number, a security code, a cookie or a collect secret. Test projects only in this first delivery; behind `SHOP_PURCHASES_ENABLED`.", - "parameters": [ - { - "schema": { - "type": "string", - "description": "The research id (`srr_...`), from `POST /v1/shop/agent/research`." - }, - "required": true, - "description": "The research id (`srr_...`), from `POST /v1/shop/agent/research`.", - "name": "id", - "in": "path" - } - ], + "summary": "What the Shop can do in this project and mode", + "description": "Scope `shop:purchases:read`. The seven tasks, always all seven and in this order: `research`, `purchase`, `reserve`, `pay_pix`, `pay_boleto`, `pay_dda`, `receive_pix`. Each is `available` (an executable path is wired and on for the key's project in its mode; `scope` narrows what it covers, e.g. `test_store`: the synthetic test store only), `needs_step` (it waits for a person's act, named by `step`: `resume_shop_mandate`, `rebind_integrated_proof`, `confirm_shop_mandate`) or `unavailable` (`reason`, a code for logs and mapping). Derived from the gates the Shop's own paths read, the same answer the Shop's dashboard reads: researching is not reserving, and reserving is not paying (`reserve` has no executor). A mandate never signed is not a step in Test; it is confirmed by a person when a payment first needs it. Reads only: nothing is provisioned, signed or enabled, in Test or in Live. Served whatever `SHOP_PURCHASES_ENABLED` says: a switch that is off is answered as the reason of the tasks it gates.", "responses": { "200": { "description": "OK", @@ -110830,14 +118369,82 @@ "schema": { "type": "object", "properties": { - "research": { - "type": "object", - "additionalProperties": {}, - "description": "The research as CONTRATO-I2 describes it: offers, recommendation, sources." + "project_id": { + "type": "string" + }, + "environment": { + "type": "string", + "enum": [ + "test", + "live" + ] + }, + "capabilities": { + "type": "array", + "items": { + "type": "object", + "properties": { + "task": { + "type": "string", + "enum": [ + "research", + "purchase", + "reserve", + "pay_pix", + "pay_boleto", + "pay_dda", + "receive_pix" + ] + }, + "state": { + "type": "string", + "enum": [ + "available", + "needs_step", + "unavailable" + ] + }, + "step": { + "type": [ + "string", + "null" + ], + "description": "Only with needs_step: the person's act it waits for." + }, + "reason": { + "type": [ + "string", + "null" + ], + "description": "Only with unavailable: a code for logs and mapping, never shown raw." + }, + "scope": { + "type": [ + "string", + "null" + ], + "description": "What available covers, e.g. test_store: the synthetic test store only." + } + }, + "required": [ + "task", + "state", + "step", + "reason", + "scope" + ] + } + }, + "as_of": { + "type": "string", + "description": "When the gates were read (ISO 8601)." } }, "required": [ - "research" + "project_id", + "environment", + "capabilities", + "as_of" ] } } @@ -110884,27 +118491,6 @@ } } } - }, - "404": { - "description": "Not Found", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "error": { - "type": "string", - "enum": [ - "not_found" - ] - } - }, - "required": [ - "error" - ] - } - } - } } }, "x-codespar-scope": "shop:purchases:read", @@ -111044,7 +118630,7 @@ "/v1/projects": { "post": { "summary": "Create a project", - "description": "Creates a project in the organization this credential resolves to.\n\nROLE. This is an administrative operation and it carries the `admin` role gate. On a credential of the kind this document describes — an API key or an OAuth access token — that gate does NOT refuse today. It resolves the user forwarded in the `x-codespar-user` header against this organization's members, records the outcome when no user was forwarded, the user is not a member of the organization, or the user ranks below `admin`, and then lets the request through. Refusal is behind a server-side rollout flag that is currently off. Forward an `admin` or `owner` user in `x-codespar-user` now: when the flag is turned on, a call that does not carry one starts being answered with 403 instead of being served.\n\nSCOPE. A key created with an explicit scope list needs `projects:write` and is answered with 403 without it. A wildcard key passes: the wildcard is what a key gets when it is created without an explicit list, which is every key by default.\n\n`slug` is unique per organization, lowercase alphanumerics plus `_` and `-`, at most 64 characters, and `default` is reserved because the auto-seeded first project already holds it. A slug already taken in the organization is refused with 400 and code `slug_conflict`, not 409, and `details.slug` echoes the value that collided.\n\n`environment` is `test` when omitted and is fixed once the row exists: the update operation has no field for it. `live` needs the organization to be approved for live by CodeSpar; until it is, a live create is refused with 403 and code `org_not_approved_for_live` before anything is written, whatever the credential and whatever its role or scopes. Approval is granted by CodeSpar, never through this API. Test projects need no approval. A new project is never the organization's default — the insert writes `false` — so promote it afterwards with `PATCH /v1/projects/{id}` if that is what you want.\n\n`settings` seeds the settings sub-resource. Every key is checked against the settings registry, for the environment the project is about to be born with, BEFORE anything is inserted, so an unknown key, a wrong-typed value, or a key that does not apply to that environment refuses the whole call and leaves no project behind. The refusal is 400 `invalid_body` with `details.key` naming the offending setting. Settings are not part of the response body; read them back with `GET /v1/projects/{id}/settings`.", + "description": "Creates a project in the organization this credential resolves to.\n\nROLE. This is an administrative operation: an `admin` or `owner` performs it from the dashboard. An API key is refused with 403 `admin_session_required`, whatever its scopes and even on the project it was issued in. `x-codespar-user` is not read for an API key. An OAuth access token is refused with 403 `insufficient_role`.\n\n`slug` is unique per organization, lowercase alphanumerics plus `_` and `-`, at most 64 characters, and `default` is reserved because the auto-seeded first project already holds it. A slug already taken in the organization is refused with 400 and code `slug_conflict`, not 409, and `details.slug` echoes the value that collided.\n\n`environment` is `test` when omitted and is fixed once the row exists: the update operation has no field for it. `live` needs the organization to be approved for live by CodeSpar; until it is, a live create is refused with 403 and code `org_not_approved_for_live` before anything is written, whatever the credential and whatever its role or scopes. Approval is granted by CodeSpar, never through this API. Test projects need no approval. A new project is never the organization's default — the insert writes `false` — so promote it afterwards with `PATCH /v1/projects/{id}` if that is what you want.\n\n`settings` seeds the settings sub-resource. Every key is checked against the settings registry, for the environment the project is about to be born with, BEFORE anything is inserted, so an unknown key, a wrong-typed value, or a key that does not apply to that environment refuses the whole call and leaves no project behind. The refusal is 400 `invalid_body` with `details.key` naming the offending setting. Settings are not part of the response body; read them back with `GET /v1/projects/{id}/settings`.", "requestBody": { "content": { "application/json": { @@ -111434,7 +119020,7 @@ }, "patch": { "summary": "Rename a project, change its slug, or promote it to default", - "description": "At least one field must be present; an empty body is refused with 400.\n\nROLE. This is an administrative operation and it carries the `admin` role gate. On a credential of the kind this document describes — an API key or an OAuth access token — that gate does NOT refuse today. It resolves the user forwarded in the `x-codespar-user` header against this organization's members, records the outcome when no user was forwarded, the user is not a member of the organization, or the user ranks below `admin`, and then lets the request through. Refusal is behind a server-side rollout flag that is currently off. Forward an `admin` or `owner` user in `x-codespar-user` now: when the flag is turned on, a call that does not carry one starts being answered with 403 instead of being served.\n\nSCOPE. A key created with an explicit scope list needs `projects:write` and is answered with 403 without it. A wildcard key passes: the wildcard is what a key gets when it is created without an explicit list, which is every key by default.\n\n`is_default` accepts `true` and nothing else. A project cannot be un-defaulted, and the only way to move the default is to promote a different project: the previous default is cleared and the new one set in one transaction, so no committed state ever shows two defaults. Promoting a project that is already the default is a no-op.\n\n`environment` is absent on purpose and cannot be changed here or anywhere else. A cross-tenant id is 404, on the same reasoning as the read.\n\nTWO THINGS ARE ANSWERED WITH `slug_conflict`, and only one of them is about a slug. A slug already taken in the organization is 400 `slug_conflict` with `details.slug` carrying the value you sent. A patch that names NO slug can also get `slug_conflict`, and then `details.slug` is null — but the collision there is not a slug at all: the only other unique index on the table is the partial one that permits a single default per organization, so what you hit is two promotions racing. The handler labels both the same way. Read a null `details.slug` as `retry the promotion`, not as a slug collision to go hunting for.\n\nThe 200 body is the project as it stands after the update.", + "description": "At least one field must be present; an empty body is refused with 400.\n\nROLE. This is an administrative operation: an `admin` or `owner` performs it from the dashboard. An API key is refused with 403 `admin_session_required`, whatever its scopes and even on the project it was issued in. `x-codespar-user` is not read for an API key. An OAuth access token is refused with 403 `insufficient_role`.\n\n`is_default` accepts `true` and nothing else. A project cannot be un-defaulted, and the only way to move the default is to promote a different project: the previous default is cleared and the new one set in one transaction, so no committed state ever shows two defaults. Promoting a project that is already the default is a no-op.\n\n`environment` is absent on purpose and cannot be changed here or anywhere else. A cross-tenant id is 404, on the same reasoning as the read.\n\nTWO THINGS ARE ANSWERED WITH `slug_conflict`, and only one of them is about a slug. A slug already taken in the organization is 400 `slug_conflict` with `details.slug` carrying the value you sent. A patch that names NO slug can also get `slug_conflict`, and then `details.slug` is null — but the collision there is not a slug at all: the only other unique index on the table is the partial one that permits a single default per organization, so what you hit is two promotions racing. The handler labels both the same way. Read a null `details.slug` as `retry the promotion`, not as a slug collision to go hunting for.\n\nThe 200 body is the project as it stands after the update.", "parameters": [ { "schema": { @@ -111627,7 +119213,7 @@ }, "delete": { "summary": "Delete a project", - "description": "A hard delete, not a soft one: the project row is removed and most of what hangs off it goes with it. 204 with no body on success.\n\nROLE. This is an administrative operation and it carries the `admin` role gate. On a credential of the kind this document describes — an API key or an OAuth access token — that gate does NOT refuse today. It resolves the user forwarded in the `x-codespar-user` header against this organization's members, records the outcome when no user was forwarded, the user is not a member of the organization, or the user ranks below `admin`, and then lets the request through. Refusal is behind a server-side rollout flag that is currently off. Forward an `admin` or `owner` user in `x-codespar-user` now: when the flag is turned on, a call that does not carry one starts being answered with 403 instead of being served.\n\nSCOPE. A key created with an explicit scope list needs `projects:write` and is answered with 403 without it. A wildcard key passes: the wildcard is what a key gets when it is created without an explicit list, which is every key by default.\n\nFour refusals, all 409 because the request is well formed and conflicts with an invariant the organization relies on:\n\n- `cannot_delete_default`: promote another project to default first.\n- `cannot_delete_last_project`: an organization always keeps at least one project for new resources to attach to.\n- `cannot_delete_with_consumer_records`: the project still owns consumer records, which are kept rather than dragged along by the delete.\n- `cannot_delete_with_bill_records`: the project still holds Bill records (meters, usage events, closed cycles or statements), which are billing history and pending obligations and are kept. When consumer records also hold the project, `cannot_delete_with_consumer_records` answers first.\n\nAll four carry `details.project_id`. The last two also carry `details.blocked_by`, a list of `{ table, rows }`. A pre-flight probe names EVERY blocking table with its row count, so one refusal tells you everything to clear rather than making you rediscover the next blocker on each retry. A record inserted between that probe and the delete is caught by a backstop that can only name the one table that raised, and reports `rows: null` for it; an empty `blocked_by` means even that table was not identifiable. Nothing in this API deletes those records for you.\n\nA cross-tenant id is 404, not 403.", + "description": "A hard delete, not a soft one: the project row is removed and most of what hangs off it goes with it. 204 with no body on success.\n\nROLE. This is an administrative operation: an `admin` or `owner` performs it from the dashboard. An API key is refused with 403 `admin_session_required`, whatever its scopes and even on the project it was issued in. `x-codespar-user` is not read for an API key. An OAuth access token is refused with 403 `insufficient_role`.\n\nFour refusals, all 409 because the request is well formed and conflicts with an invariant the organization relies on:\n\n- `cannot_delete_default`: promote another project to default first.\n- `cannot_delete_last_project`: an organization always keeps at least one project for new resources to attach to.\n- `cannot_delete_with_consumer_records`: the project still owns consumer records, which are kept rather than dragged along by the delete.\n- `cannot_delete_with_bill_records`: the project still holds Bill records (meters, usage events, closed cycles or statements), which are billing history and pending obligations and are kept. When consumer records also hold the project, `cannot_delete_with_consumer_records` answers first.\n\nAll four carry `details.project_id`. The last two also carry `details.blocked_by`, a list of `{ table, rows }`. A pre-flight probe names EVERY blocking table with its row count, so one refusal tells you everything to clear rather than making you rediscover the next blocker on each retry. A record inserted between that probe and the delete is caught by a backstop that can only name the one table that raised, and reports `rows: null` for it; an empty `blocked_by` means even that table was not identifiable. Nothing in this API deletes those records for you.\n\nA cross-tenant id is 404, not 403.", "parameters": [ { "schema": { @@ -111748,7 +119334,7 @@ "/v1/projects/{id}/archive": { "post": { "summary": "Archive a project", - "description": "The way out for a project that cannot be deleted because it holds records: nothing is deleted, moved or revoked. It is refused while the project has open money obligations (409 `project_has_open_operations`), so nothing recurring stops in silence. An archived project leaves `GET /v1/projects` (list it with `?include_archived=1`), its API keys and OAuth tokens are refused with 403 `project_archived`, the dashboard's writes in it too, and the workers start nothing for it; provider events of objects created before keep being recorded. The organization's default project is not archived (409 `cannot_archive_default`). Asking for the state the project is already in answers 200 with `changed: false`. Recorded in the organization's audit log.\n\nROLE. This is an administrative operation and it carries the `admin` role gate. On a credential of the kind this document describes — an API key or an OAuth access token — that gate does NOT refuse today. It resolves the user forwarded in the `x-codespar-user` header against this organization's members, records the outcome when no user was forwarded, the user is not a member of the organization, or the user ranks below `admin`, and then lets the request through. Refusal is behind a server-side rollout flag that is currently off. Forward an `admin` or `owner` user in `x-codespar-user` now: when the flag is turned on, a call that does not carry one starts being answered with 403 instead of being served.\n\nSCOPE. A key created with an explicit scope list needs `projects:write` and is answered with 403 without it. A wildcard key passes: the wildcard is what a key gets when it is created without an explicit list, which is every key by default.\n\nA cross-tenant id is 404, not 403.", + "description": "The way out for a project that cannot be deleted because it holds records: nothing is deleted, moved or revoked. It is refused while the project has open money obligations (409 `project_has_open_operations`), so nothing recurring stops in silence. An archived project leaves `GET /v1/projects` (list it with `?include_archived=1`), its API keys and OAuth tokens are refused with 403 `project_archived`, the dashboard's writes in it too, and the workers start nothing for it; provider events of objects created before keep being recorded. The organization's default project is not archived (409 `cannot_archive_default`). Asking for the state the project is already in answers 200 with `changed: false`. Recorded in the organization's audit log.\n\nROLE. This is an administrative operation: an `admin` or `owner` performs it from the dashboard. An API key is refused with 403 `admin_session_required`, whatever its scopes and even on the project it was issued in. `x-codespar-user` is not read for an API key. An OAuth access token is refused with 403 `insufficient_role`.\n\n\n\nA cross-tenant id is 404, not 403.", "parameters": [ { "schema": { @@ -111905,7 +119491,7 @@ "/v1/projects/{id}/unarchive": { "post": { "summary": "Unarchive a project", - "description": "Restores an archived project as it was: listed again, its keys and operations accepted. Asking for the state the project is already in answers 200 with `changed: false`. Recorded in the organization's audit log.\n\nROLE. This is an administrative operation and it carries the `admin` role gate. On a credential of the kind this document describes — an API key or an OAuth access token — that gate does NOT refuse today. It resolves the user forwarded in the `x-codespar-user` header against this organization's members, records the outcome when no user was forwarded, the user is not a member of the organization, or the user ranks below `admin`, and then lets the request through. Refusal is behind a server-side rollout flag that is currently off. Forward an `admin` or `owner` user in `x-codespar-user` now: when the flag is turned on, a call that does not carry one starts being answered with 403 instead of being served.\n\nSCOPE. A key created with an explicit scope list needs `projects:write` and is answered with 403 without it. A wildcard key passes: the wildcard is what a key gets when it is created without an explicit list, which is every key by default.\n\nA cross-tenant id is 404, not 403.", + "description": "Restores an archived project as it was: listed again, its keys and operations accepted. Asking for the state the project is already in answers 200 with `changed: false`. Recorded in the organization's audit log.\n\nROLE. This is an administrative operation: an `admin` or `owner` performs it from the dashboard. An API key is refused with 403 `admin_session_required`, whatever its scopes and even on the project it was issued in. `x-codespar-user` is not read for an API key. An OAuth access token is refused with 403 `insufficient_role`.\n\n\n\nA cross-tenant id is 404, not 403.", "parameters": [ { "schema": { @@ -112016,7 +119602,7 @@ "/v1/projects/{id}/settings": { "get": { "summary": "Read a project's effective settings", - "description": "Every setting declared for the project's environment, with its effective value, the declared default, and whether the value was set explicitly or is still tracking that default. `explicit: false` means the key will follow the default if the default ever moves.\n\nSCOPE. A key created with an explicit scope list needs `projects:settings` and is answered with 403 without it. A wildcard key passes: the wildcard is what a key gets when it is created without an explicit list, which is every key by default.\n\nThis read alone carries NO role gate. The write and the history read below both do, and what that gate currently does is described on each of them.\n\nThe list is filtered by environment: a setting declared test-only does not appear on a live project at all, so an empty list is a normal answer rather than an error. A stored value whose key is no longer declared is omitted too. Every setting the registry declares as this is written applies to `test` only, which makes an empty list what a `live` project returns — a fact about the current declarations, not about this route.\n\nA cross-tenant id is 404.", + "description": "Every setting declared for the project's environment, with its effective value, the declared default, and whether the value was set explicitly or is still tracking that default. `explicit: false` means the key will follow the default if the default ever moves.\n\nSCOPE. A key created with an explicit scope list needs `projects:settings` and is answered with 403 without it. A wildcard key passes: the wildcard is what a key gets when it is created without an explicit list, which is every key by default.\n\nThis read alone carries NO role gate. The write and the history read below both do, and what that gate does is described on each of them. An API key reads only the project it was issued in: another `{id}` is 403 `api_key_other_project`.\n\nThe list is filtered by environment: a setting declared test-only does not appear on a live project at all, so an empty list is a normal answer rather than an error. A stored value whose key is no longer declared is omitted too. Every setting the registry declares as this is written applies to `test` only, which makes an empty list what a `live` project returns — a fact about the current declarations, not about this route.\n\nA cross-tenant id is 404.", "parameters": [ { "schema": { @@ -112160,7 +119746,7 @@ }, "patch": { "summary": "Set or reset a project's settings", - "description": "The body is `{ \"settings\": { : } }`. A `null` value RESETS that key to default-tracking; it does not store null. Multiple keys in one call are applied together.\n\nROLE. This is an administrative operation and it carries the `admin` role gate. On a credential of the kind this document describes — an API key or an OAuth access token — that gate does NOT refuse today. It resolves the user forwarded in the `x-codespar-user` header against this organization's members, records the outcome when no user was forwarded, the user is not a member of the organization, or the user ranks below `admin`, and then lets the request through. Refusal is behind a server-side rollout flag that is currently off. Forward an `admin` or `owner` user in `x-codespar-user` now: when the flag is turned on, a call that does not carry one starts being answered with 403 instead of being served.\n\nSCOPE. A key created with an explicit scope list needs `projects:settings` and is answered with 403 without it. A wildcard key passes: the wildcard is what a key gets when it is created without an explicit list, which is every key by default.\n\nThe whole batch is validated against the settings registry before anything is written, so one bad entry rejects the entire call and nothing changes. An unknown key, a value of the wrong type, or a key that does not apply to the project's environment is 400 `invalid_body` with `details.key` naming the offender. An empty `settings` object is 400 as well, with no `details`.\n\nEach key that actually changes appends one audit entry in the same transaction as the write, so the change and its record cannot come apart.\n\nREPEATING A CALL IS NOT ALWAYS FREE, and the asymmetry is worth reading before you build a retry on it. A reset of a key already tracking its default is a true no-op: nothing is written and nothing is recorded. A WRITE is not symmetric with that. The shortcut that skips a write applies only to a key that is ALREADY explicit and already holds the value you sent. On a key still tracking its default — the state every key is in on a fresh project — sending exactly the default's own value IS a change: the key becomes explicit, it appears in the stored blob, and one audit entry is appended whose `old_value` and `new_value` are equal. The SECOND identical call is the one that does nothing. So a retry that looks idempotent can still be the call that flips a key off default-tracking, which matters because an explicit key stops following the default if the default later moves.\n\nThe 200 body is the same shape the read returns: the effective settings AFTER the write, not only the keys this call touched.\n\nA cross-tenant id is 404.", + "description": "The body is `{ \"settings\": { : } }`. A `null` value RESETS that key to default-tracking; it does not store null. Multiple keys in one call are applied together.\n\nROLE. This is an administrative operation: an `admin` or `owner` performs it from the dashboard. An API key is refused with 403 `admin_session_required`, whatever its scopes and even on the project it was issued in. `x-codespar-user` is not read for an API key. An OAuth access token is refused with 403 `insufficient_role`.\n\nThe whole batch is validated against the settings registry before anything is written, so one bad entry rejects the entire call and nothing changes. An unknown key, a value of the wrong type, or a key that does not apply to the project's environment is 400 `invalid_body` with `details.key` naming the offender. An empty `settings` object is 400 as well, with no `details`.\n\nEach key that actually changes appends one audit entry in the same transaction as the write, so the change and its record cannot come apart.\n\nREPEATING A CALL IS NOT ALWAYS FREE, and the asymmetry is worth reading before you build a retry on it. A reset of a key already tracking its default is a true no-op: nothing is written and nothing is recorded. A WRITE is not symmetric with that. The shortcut that skips a write applies only to a key that is ALREADY explicit and already holds the value you sent. On a key still tracking its default — the state every key is in on a fresh project — sending exactly the default's own value IS a change: the key becomes explicit, it appears in the stored blob, and one audit entry is appended whose `old_value` and `new_value` are equal. The SECOND identical call is the one that does nothing. So a retry that looks idempotent can still be the call that flips a key off default-tracking, which matters because an explicit key stops following the default if the default later moves.\n\nThe 200 body is the same shape the read returns: the effective settings AFTER the write, not only the keys this call touched.\n\nA cross-tenant id is 404.", "parameters": [ { "schema": { @@ -112369,7 +119955,7 @@ "/v1/projects/{id}/settings/history": { "get": { "summary": "Read a project's settings audit log", - "description": "The ordered change history for this project's settings, oldest first.\n\nROLE. This is an administrative operation and it carries the `admin` role gate. On a credential of the kind this document describes — an API key or an OAuth access token — that gate does NOT refuse today. It resolves the user forwarded in the `x-codespar-user` header against this organization's members, records the outcome when no user was forwarded, the user is not a member of the organization, or the user ranks below `admin`, and then lets the request through. Refusal is behind a server-side rollout flag that is currently off. Forward an `admin` or `owner` user in `x-codespar-user` now: when the flag is turned on, a call that does not carry one starts being answered with 403 instead of being served.\n\nSCOPE. A key created with an explicit scope list needs `projects:settings` and is answered with 403 without it. A wildcard key passes: the wildcard is what a key gets when it is created without an explicit list, which is every key by default.\n\nOne entry per key that actually changed, so a call that wrote a value an already-explicit key was already holding leaves no trace here. Note what does leave a trace: writing a key's own default value while it is still tracking that default is a change, and it lands here with `old_value` equal to `new_value`. `explicit_before` and `explicit_after` are what separate a reset from a write: a reset ends with `explicit_after: false` and a `new_value` equal to the declared default.\n\nCapped at the 200 OLDEST entries and not paginated. Read that carefully: the order is ascending and the limit is applied after it, so once a project has recorded more than 200 changes this endpoint stops showing the most RECENT ones. There is no cursor and no limit parameter to page past it.\n\n`created_at` on each entry is not a parseable RFC 3339 timestamp; see the field's own description.\n\nA cross-tenant id is 404.", + "description": "The ordered change history for this project's settings, oldest first.\n\nROLE. This is an administrative operation: an `admin` or `owner` performs it from the dashboard. An API key is refused with 403 `admin_session_required`, whatever its scopes and even on the project it was issued in. `x-codespar-user` is not read for an API key. An OAuth access token is refused with 403 `insufficient_role`.\n\nOne entry per key that actually changed, so a call that wrote a value an already-explicit key was already holding leaves no trace here. Note what does leave a trace: writing a key's own default value while it is still tracking that default is a change, and it lands here with `old_value` equal to `new_value`. `explicit_before` and `explicit_after` are what separate a reset from a write: a reset ends with `explicit_after: false` and a `new_value` equal to the declared default.\n\nCapped at the 200 OLDEST entries and not paginated. Read that carefully: the order is ascending and the limit is applied after it, so once a project has recorded more than 200 changes this endpoint stops showing the most RECENT ones. There is no cursor and no limit parameter to page past it.\n\n`created_at` on each entry is not a parseable RFC 3339 timestamp; see the field's own description.\n\nA cross-tenant id is 404.", "parameters": [ { "schema": { @@ -112525,20 +120111,27 @@ ] }, "level": { - "type": "string", + "type": [ + "string", + "null" + ], "enum": [ "confirm_each", "confirm_exceptions", "within_mandate" ], - "description": "`confirm_each`: a person confirms every payment. `confirm_exceptions`: a payment above `exception_amount_minor`, or to a payee never paid, waits for a person. `within_mandate`: the agent pays inside the mandate unconfirmed. No level widens a mandate. A project that never changed it is at `confirm_each`." + "description": "The level the payment step applies. `confirm_each`: a person confirms every payment. `confirm_exceptions`: a payment above `exception_amount_minor`, or to a payee never paid, waits for a person. `within_mandate`: the agent pays inside the mandate unconfirmed. No level widens a mandate. A test project that never changed it is at `confirm_each`. Null where no level applies (a live project, or a deployment that releases none): there the agent pays within the mandate and the project's approval rules, with no per-payment confirmation." + }, + "applies": { + "type": "boolean", + "description": "Whether the agent's autonomy applies to this project's payments now. False on a live project, where `level` is null." }, "exception_amount_minor": { "type": [ "integer", "null" ], - "description": "The threshold of `confirm_exceptions`, in minor units; null at the other levels." + "description": "The threshold of `confirm_exceptions`, in minor units; null at the other levels and where no level applies." }, "version": { "type": "integer", @@ -112578,18 +120171,55 @@ "pending" ], "description": "`pending` on a live project; null on a test project." + }, + "payment_approval_rules": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "agents": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The agents it applies to (`*` for all)." + }, + "payment_tools": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The payment tools it holds for a person: `consumer_payment:execute` (every consumer payment door), `codespar_pay`, `codespar_crypto_pay`, `codespar_shop`." + } + }, + "required": [ + "id", + "name", + "agents", + "payment_tools" + ] + }, + "description": "The organization's approval rules that hold a payment for a person, in the engine's order and by its first-match scan. They apply in every environment; in a live project, where no autonomy level applies, these and the mandate's limits are what stand before a payment." } }, "required": [ "project_id", "environment", "level", + "applies", "exception_amount_minor", "version", "updated_by", "updated_at", "available_levels", - "live_activation" + "live_activation", + "payment_approval_rules" ] } } @@ -112725,20 +120355,27 @@ ] }, "level": { - "type": "string", + "type": [ + "string", + "null" + ], "enum": [ "confirm_each", "confirm_exceptions", "within_mandate" ], - "description": "`confirm_each`: a person confirms every payment. `confirm_exceptions`: a payment above `exception_amount_minor`, or to a payee never paid, waits for a person. `within_mandate`: the agent pays inside the mandate unconfirmed. No level widens a mandate. A project that never changed it is at `confirm_each`." + "description": "The level the payment step applies. `confirm_each`: a person confirms every payment. `confirm_exceptions`: a payment above `exception_amount_minor`, or to a payee never paid, waits for a person. `within_mandate`: the agent pays inside the mandate unconfirmed. No level widens a mandate. A test project that never changed it is at `confirm_each`. Null where no level applies (a live project, or a deployment that releases none): there the agent pays within the mandate and the project's approval rules, with no per-payment confirmation." + }, + "applies": { + "type": "boolean", + "description": "Whether the agent's autonomy applies to this project's payments now. False on a live project, where `level` is null." }, "exception_amount_minor": { "type": [ "integer", "null" ], - "description": "The threshold of `confirm_exceptions`, in minor units; null at the other levels." + "description": "The threshold of `confirm_exceptions`, in minor units; null at the other levels and where no level applies." }, "version": { "type": "integer", @@ -112778,18 +120415,55 @@ "pending" ], "description": "`pending` on a live project; null on a test project." + }, + "payment_approval_rules": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "agents": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The agents it applies to (`*` for all)." + }, + "payment_tools": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The payment tools it holds for a person: `consumer_payment:execute` (every consumer payment door), `codespar_pay`, `codespar_crypto_pay`, `codespar_shop`." + } + }, + "required": [ + "id", + "name", + "agents", + "payment_tools" + ] + }, + "description": "The organization's approval rules that hold a payment for a person, in the engine's order and by its first-match scan. They apply in every environment; in a live project, where no autonomy level applies, these and the mandate's limits are what stand before a payment." } }, "required": [ "project_id", "environment", "level", + "applies", "exception_amount_minor", "version", "updated_by", "updated_at", "available_levels", - "live_activation" + "live_activation", + "payment_approval_rules" ] } }, @@ -114715,7 +122389,7 @@ } }, "403": { - "description": "Forbidden. This write is gated on an organization role, and the guard refused. It is reachable with an OAuth access token or a service credential: either no acting user was forwarded in the `x-codespar-user` header, or the user it named does not hold at least `admin` in the organization. Re-sending the same header will not help in the second case — promote that user, or forward one who already qualifies.\n\nAN API KEY IS NOT REFUSED HERE TODAY. The role requirement is not enforced for that credential at this version, so a key alone completes the write and a 200 is not evidence that anyone holding `admin` authorized it. Plan for the header: it is the arm that will be closed.", + "description": "Forbidden. This write is gated on an organization role, and the guard refused. It refuses an OAuth access token, which is not the dashboard, whatever `x-codespar-user` says.\n\nAn API key is not refused by this guard: a key carries no role, its grant is its scope (`payment-links:write`), and only an admin mints a key. `x-codespar-user` is not read for a key.", "content": { "application/json": { "schema": { @@ -116154,7 +123828,7 @@ } }, "403": { - "description": "Forbidden. This write is gated on an organization role, and the guard refused. It is reachable with an OAuth access token or a service credential: either no acting user was forwarded in the `x-codespar-user` header, or the user it named does not hold at least `admin` in the organization. Re-sending the same header will not help in the second case — promote that user, or forward one who already qualifies.\n\nAN API KEY IS NOT REFUSED HERE TODAY. The role requirement is not enforced for that credential at this version, so a key alone completes the write and a 200 is not evidence that anyone holding `admin` authorized it. Plan for the header: it is the arm that will be closed.", + "description": "Forbidden. This write is gated on an organization role, and the guard refused. It refuses an OAuth access token, which is not the dashboard, whatever `x-codespar-user` says.\n\nAn API key is not refused by this guard: a key carries no role, its grant is its scope (`payment-links:write`), and only an admin mints a key. `x-codespar-user` is not read for a key.", "content": { "application/json": { "schema": { @@ -116254,7 +123928,7 @@ "description": "No Content" }, "403": { - "description": "Forbidden. This write is gated on an organization role, and the guard refused. It is reachable with an OAuth access token or a service credential: either no acting user was forwarded in the `x-codespar-user` header, or the user it named does not hold at least `admin` in the organization. Re-sending the same header will not help in the second case — promote that user, or forward one who already qualifies.\n\nAN API KEY IS NOT REFUSED HERE TODAY. The role requirement is not enforced for that credential at this version, so a key alone completes the write and a 200 is not evidence that anyone holding `admin` authorized it. Plan for the header: it is the arm that will be closed.", + "description": "Forbidden. This write is gated on an organization role, and the guard refused. It refuses an OAuth access token, which is not the dashboard, whatever `x-codespar-user` says.\n\nAn API key is not refused by this guard: a key carries no role, its grant is its scope (`payment-links:write`), and only an admin mints a key. `x-codespar-user` is not read for a key.", "content": { "application/json": { "schema": { diff --git a/packages/core/package.json b/packages/core/package.json index dc2deda..3ee596f 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -1,6 +1,6 @@ { "name": "@codespar/sdk", - "version": "0.16.28", + "version": "0.16.29", "description": "Commerce SDK for AI agents \u2014 sessions, managed auth, Complete Loop orchestration for Latin American APIs", "type": "module", "main": "./dist/index.js", diff --git a/packages/core/src/generated/openapi.ts b/packages/core/src/generated/openapi.ts index 23f13d0..21c4e3d 100644 --- a/packages/core/src/generated/openapi.ts +++ b/packages/core/src/generated/openapi.ts @@ -1,5 +1,5 @@ // GENERATED FILE — do not edit. -// Source: openapi-snapshot.json (sha256 4ae3274e16aa0655cacab1b3a1f0c1fbe8ad710fe2c0184c9b0aa816fdd0095c, fetched 2026-10-31T00:54:41.356Z +// Source: openapi-snapshot.json (sha256 b9b057565a31502b762e37b6c0c713984543f48a2425e34729bf1332afa34cfb, fetched 2026-11-11T11:18:25.811Z // from https://api.codespar.dev/openapi.json, API 0.3.0). // Regenerate: npm run spec:generate (in packages/core) export interface paths { @@ -1613,7 +1613,7 @@ export interface paths { content: { "application/json": { name: string; - /** @description The event type to subscribe to. Matching is EXACT string equality — there is no prefix and no wildcard, so `commerce.payment.succeeded` does not receive `commerce.payment.received`. A name outside the list below is accepted and recorded (`trigger.event_unknown`) rather than refused, so you can subscribe ahead of a release; until something emits it the subscription simply never fires. What this build emits: account_binding.closed, agent_autonomy.changed, approval.decided, approval.pending, collect.attempt.cancelled, collect.attempt.expired, collect.attempt.failed, collect.attempt.issued, collect.attempt.ready, collect.attempt.superseded, collect.link.archived, collect.link.paused, collect.link.published, collect.payment.exception, collect.payment.paid, collect.refund.awaiting_decision, collect.refund.honored, collect.refund.required, commerce.account_entry_credit.received, commerce.account_entry_debit.received, commerce.account_launch_in.received, commerce.account_launch_out.received, commerce.account_status.changed, commerce.cashout.confirmed, commerce.charge.cancelled, commerce.charge.created, commerce.charge.expired, commerce.charge.expiry_notified, commerce.charge.paid, commerce.charge.payment_notified, commerce.dict_claim.cancelled, commerce.dict_claim.completed, commerce.dict_claim.confirmed, commerce.dict_claim.opened, commerce.dict_claim.waiting, commerce.internal_transfer_in.received, commerce.internal_transfer_out.received, commerce.mandate.expiring, commerce.mandate.granted, commerce.mandate.paused, commerce.mandate.resumed, commerce.mandate.revoked, commerce.onboarding.backgroundcheck_approved, commerce.onboarding.backgroundcheck_pending, commerce.onboarding.backgroundcheck_rejected, commerce.onboarding.documentscopy_approved, commerce.onboarding.documentscopy_pending, commerce.onboarding.documentscopy_processing, commerce.onboarding.documentscopy_rejected, commerce.onboarding.proposal_approved, commerce.onboarding.proposal_processing_documentscopy, commerce.onboarding.proposal_rejected, commerce.organization.paused, commerce.organization.resumed, commerce.payment.failed, commerce.payment.pending, commerce.payment.received, commerce.payment.refunded, commerce.payment.succeeded, commerce.payment.updated, commerce.pix_out.failed, commerce.pix_out.succeeded, commerce.pix_out.unconfirmed, commerce.pix_reversal_in.received, commerce.pix_reversal_out.received, commerce.recurrence.authorized, commerce.recurrence.cancelled, commerce.recurrence.cycle.accepted, commerce.recurrence.cycle.announced_late, commerce.recurrence.cycle.awaiting_instruction, commerce.recurrence.cycle.cancelled, commerce.recurrence.cycle.expired, commerce.recurrence.cycle.instruction_blocked, commerce.recurrence.cycle.instruction_missing, commerce.recurrence.cycle.instruction_refused, commerce.recurrence.cycle.paid, commerce.recurrence.cycle.queued_instruction_expired, commerce.recurrence.cycle.rejected, commerce.recurrence.cycle.scheduled, commerce.recurrence.cycle.settled_by_held_credit, commerce.recurrence.denied, commerce.recurrence.requested, commerce.recurrence.settlement_held, commerce.recurrence.settlement_hold_overdue, commerce.recurrence.settlement_hold_resolved, commerce.recurrence.settlement_possible_double_credit, commerce.rinne.observed, commerce.spend.failed, commerce.spend.settled, commerce.ted_in.succeeded, dda.boleto.registered, dda.subscription.activated, dda.subscription.failed, gate.paywall.charged, payable.batch.completed, payable.batch.item_executed, payable.batch.item_refused, payable.rejected, project.archived, project.unarchived, proxy_call.failed, proxy_call.succeeded, sandbox.provisioning.account_bound, sandbox.provisioning.initial_credit, sandbox.provisioning.resumed, session.closed, space_credential_revocation.requested, spaces_consent.accepted, spaces_customer_account.resumed, spaces_customer_account.suspended, system.health.degraded, system.health.recovered, tool_call.failed, tool_call.succeeded, trigger.delivery.failed, trigger.paused_automatically, trigger.test_fire, user.signed_up, wallet.balance.below. */ + /** @description The event type to subscribe to. Matching is EXACT string equality — there is no prefix and no wildcard, so `commerce.payment.succeeded` does not receive `commerce.payment.received`. A name outside the list below is accepted and recorded (`trigger.event_unknown`) rather than refused, so you can subscribe ahead of a release; until something emits it the subscription simply never fires. What this build emits: account_binding.closed, agent_autonomy.changed, api_key.mandate_bound, api_key.mandate_unbound, approval.decided, approval.pending, collect.attempt.cancelled, collect.attempt.expired, collect.attempt.failed, collect.attempt.issued, collect.attempt.ready, collect.attempt.superseded, collect.link.archived, collect.link.paused, collect.link.published, collect.payment.exception, collect.payment.paid, collect.refund.awaiting_decision, collect.refund.honored, collect.refund.required, commerce.account_entry_credit.received, commerce.account_entry_debit.received, commerce.account_launch_in.received, commerce.account_launch_out.received, commerce.account_status.changed, commerce.cashout.confirmed, commerce.charge.cancelled, commerce.charge.created, commerce.charge.expired, commerce.charge.expiry_notified, commerce.charge.failed, commerce.charge.paid, commerce.charge.payment_notified, commerce.charge.payment_received, commerce.dict_claim.cancelled, commerce.dict_claim.completed, commerce.dict_claim.confirmed, commerce.dict_claim.opened, commerce.dict_claim.waiting, commerce.internal_transfer_in.received, commerce.internal_transfer_out.received, commerce.mandate.expiring, commerce.mandate.granted, commerce.mandate.paused, commerce.mandate.resumed, commerce.mandate.revoked, commerce.onboarding.backgroundcheck_approved, commerce.onboarding.backgroundcheck_pending, commerce.onboarding.backgroundcheck_rejected, commerce.onboarding.documentscopy_approved, commerce.onboarding.documentscopy_pending, commerce.onboarding.documentscopy_processing, commerce.onboarding.documentscopy_rejected, commerce.onboarding.proposal_approved, commerce.onboarding.proposal_processing_documentscopy, commerce.onboarding.proposal_rejected, commerce.organization.paused, commerce.organization.resumed, commerce.payment.failed, commerce.payment.pending, commerce.payment.received, commerce.payment.refunded, commerce.payment.succeeded, commerce.payment.updated, commerce.pix_out.failed, commerce.pix_out.succeeded, commerce.pix_out.unconfirmed, commerce.pix_reversal_in.received, commerce.pix_reversal_out.received, commerce.recurrence.authorized, commerce.recurrence.cancelled, commerce.recurrence.cycle.accepted, commerce.recurrence.cycle.announced_late, commerce.recurrence.cycle.awaiting_instruction, commerce.recurrence.cycle.cancelled, commerce.recurrence.cycle.expired, commerce.recurrence.cycle.instruction_blocked, commerce.recurrence.cycle.instruction_missing, commerce.recurrence.cycle.instruction_refused, commerce.recurrence.cycle.paid, commerce.recurrence.cycle.queued_instruction_expired, commerce.recurrence.cycle.rejected, commerce.recurrence.cycle.scheduled, commerce.recurrence.cycle.settled_by_held_credit, commerce.recurrence.denied, commerce.recurrence.requested, commerce.recurrence.settlement_held, commerce.recurrence.settlement_hold_overdue, commerce.recurrence.settlement_hold_resolved, commerce.recurrence.settlement_possible_double_credit, commerce.rinne.observed, commerce.spend.failed, commerce.spend.settled, commerce.ted_in.succeeded, dda.boleto.registered, dda.subscription.activated, dda.subscription.failed, gate.paywall.charged, payable.batch.completed, payable.batch.item_executed, payable.batch.item_refused, payable.rejected, project.archived, project.unarchived, proxy_call.failed, proxy_call.succeeded, sandbox.provisioning.account_bound, sandbox.provisioning.initial_credit, sandbox.provisioning.pix_key_registered, sandbox.provisioning.resumed, session.closed, space_credential_revocation.requested, spaces_consent.accepted, spaces_customer_account.resumed, spaces_customer_account.suspended, system.health.degraded, system.health.recovered, tool_call.failed, tool_call.succeeded, trigger.delivery.failed, trigger.paused_automatically, trigger.test_fire, user.signed_up, wallet.balance.below. */ event: string; server_id?: string; /** @@ -1767,7 +1767,7 @@ export interface paths { content: { "application/json": { name: string; - /** @description The event type to subscribe to. Matching is EXACT string equality — there is no prefix and no wildcard, so `commerce.payment.succeeded` does not receive `commerce.payment.received`. A name outside the list below is accepted and recorded (`trigger.event_unknown`) rather than refused, so you can subscribe ahead of a release; until something emits it the subscription simply never fires. What this build emits: account_binding.closed, agent_autonomy.changed, approval.decided, approval.pending, collect.attempt.cancelled, collect.attempt.expired, collect.attempt.failed, collect.attempt.issued, collect.attempt.ready, collect.attempt.superseded, collect.link.archived, collect.link.paused, collect.link.published, collect.payment.exception, collect.payment.paid, collect.refund.awaiting_decision, collect.refund.honored, collect.refund.required, commerce.account_entry_credit.received, commerce.account_entry_debit.received, commerce.account_launch_in.received, commerce.account_launch_out.received, commerce.account_status.changed, commerce.cashout.confirmed, commerce.charge.cancelled, commerce.charge.created, commerce.charge.expired, commerce.charge.expiry_notified, commerce.charge.paid, commerce.charge.payment_notified, commerce.dict_claim.cancelled, commerce.dict_claim.completed, commerce.dict_claim.confirmed, commerce.dict_claim.opened, commerce.dict_claim.waiting, commerce.internal_transfer_in.received, commerce.internal_transfer_out.received, commerce.mandate.expiring, commerce.mandate.granted, commerce.mandate.paused, commerce.mandate.resumed, commerce.mandate.revoked, commerce.onboarding.backgroundcheck_approved, commerce.onboarding.backgroundcheck_pending, commerce.onboarding.backgroundcheck_rejected, commerce.onboarding.documentscopy_approved, commerce.onboarding.documentscopy_pending, commerce.onboarding.documentscopy_processing, commerce.onboarding.documentscopy_rejected, commerce.onboarding.proposal_approved, commerce.onboarding.proposal_processing_documentscopy, commerce.onboarding.proposal_rejected, commerce.organization.paused, commerce.organization.resumed, commerce.payment.failed, commerce.payment.pending, commerce.payment.received, commerce.payment.refunded, commerce.payment.succeeded, commerce.payment.updated, commerce.pix_out.failed, commerce.pix_out.succeeded, commerce.pix_out.unconfirmed, commerce.pix_reversal_in.received, commerce.pix_reversal_out.received, commerce.recurrence.authorized, commerce.recurrence.cancelled, commerce.recurrence.cycle.accepted, commerce.recurrence.cycle.announced_late, commerce.recurrence.cycle.awaiting_instruction, commerce.recurrence.cycle.cancelled, commerce.recurrence.cycle.expired, commerce.recurrence.cycle.instruction_blocked, commerce.recurrence.cycle.instruction_missing, commerce.recurrence.cycle.instruction_refused, commerce.recurrence.cycle.paid, commerce.recurrence.cycle.queued_instruction_expired, commerce.recurrence.cycle.rejected, commerce.recurrence.cycle.scheduled, commerce.recurrence.cycle.settled_by_held_credit, commerce.recurrence.denied, commerce.recurrence.requested, commerce.recurrence.settlement_held, commerce.recurrence.settlement_hold_overdue, commerce.recurrence.settlement_hold_resolved, commerce.recurrence.settlement_possible_double_credit, commerce.rinne.observed, commerce.spend.failed, commerce.spend.settled, commerce.ted_in.succeeded, dda.boleto.registered, dda.subscription.activated, dda.subscription.failed, gate.paywall.charged, payable.batch.completed, payable.batch.item_executed, payable.batch.item_refused, payable.rejected, project.archived, project.unarchived, proxy_call.failed, proxy_call.succeeded, sandbox.provisioning.account_bound, sandbox.provisioning.initial_credit, sandbox.provisioning.resumed, session.closed, space_credential_revocation.requested, spaces_consent.accepted, spaces_customer_account.resumed, spaces_customer_account.suspended, system.health.degraded, system.health.recovered, tool_call.failed, tool_call.succeeded, trigger.delivery.failed, trigger.paused_automatically, trigger.test_fire, user.signed_up, wallet.balance.below. */ + /** @description The event type to subscribe to. Matching is EXACT string equality — there is no prefix and no wildcard, so `commerce.payment.succeeded` does not receive `commerce.payment.received`. A name outside the list below is accepted and recorded (`trigger.event_unknown`) rather than refused, so you can subscribe ahead of a release; until something emits it the subscription simply never fires. What this build emits: account_binding.closed, agent_autonomy.changed, api_key.mandate_bound, api_key.mandate_unbound, approval.decided, approval.pending, collect.attempt.cancelled, collect.attempt.expired, collect.attempt.failed, collect.attempt.issued, collect.attempt.ready, collect.attempt.superseded, collect.link.archived, collect.link.paused, collect.link.published, collect.payment.exception, collect.payment.paid, collect.refund.awaiting_decision, collect.refund.honored, collect.refund.required, commerce.account_entry_credit.received, commerce.account_entry_debit.received, commerce.account_launch_in.received, commerce.account_launch_out.received, commerce.account_status.changed, commerce.cashout.confirmed, commerce.charge.cancelled, commerce.charge.created, commerce.charge.expired, commerce.charge.expiry_notified, commerce.charge.failed, commerce.charge.paid, commerce.charge.payment_notified, commerce.charge.payment_received, commerce.dict_claim.cancelled, commerce.dict_claim.completed, commerce.dict_claim.confirmed, commerce.dict_claim.opened, commerce.dict_claim.waiting, commerce.internal_transfer_in.received, commerce.internal_transfer_out.received, commerce.mandate.expiring, commerce.mandate.granted, commerce.mandate.paused, commerce.mandate.resumed, commerce.mandate.revoked, commerce.onboarding.backgroundcheck_approved, commerce.onboarding.backgroundcheck_pending, commerce.onboarding.backgroundcheck_rejected, commerce.onboarding.documentscopy_approved, commerce.onboarding.documentscopy_pending, commerce.onboarding.documentscopy_processing, commerce.onboarding.documentscopy_rejected, commerce.onboarding.proposal_approved, commerce.onboarding.proposal_processing_documentscopy, commerce.onboarding.proposal_rejected, commerce.organization.paused, commerce.organization.resumed, commerce.payment.failed, commerce.payment.pending, commerce.payment.received, commerce.payment.refunded, commerce.payment.succeeded, commerce.payment.updated, commerce.pix_out.failed, commerce.pix_out.succeeded, commerce.pix_out.unconfirmed, commerce.pix_reversal_in.received, commerce.pix_reversal_out.received, commerce.recurrence.authorized, commerce.recurrence.cancelled, commerce.recurrence.cycle.accepted, commerce.recurrence.cycle.announced_late, commerce.recurrence.cycle.awaiting_instruction, commerce.recurrence.cycle.cancelled, commerce.recurrence.cycle.expired, commerce.recurrence.cycle.instruction_blocked, commerce.recurrence.cycle.instruction_missing, commerce.recurrence.cycle.instruction_refused, commerce.recurrence.cycle.paid, commerce.recurrence.cycle.queued_instruction_expired, commerce.recurrence.cycle.rejected, commerce.recurrence.cycle.scheduled, commerce.recurrence.cycle.settled_by_held_credit, commerce.recurrence.denied, commerce.recurrence.requested, commerce.recurrence.settlement_held, commerce.recurrence.settlement_hold_overdue, commerce.recurrence.settlement_hold_resolved, commerce.recurrence.settlement_possible_double_credit, commerce.rinne.observed, commerce.spend.failed, commerce.spend.settled, commerce.ted_in.succeeded, dda.boleto.registered, dda.subscription.activated, dda.subscription.failed, gate.paywall.charged, payable.batch.completed, payable.batch.item_executed, payable.batch.item_refused, payable.rejected, project.archived, project.unarchived, proxy_call.failed, proxy_call.succeeded, sandbox.provisioning.account_bound, sandbox.provisioning.initial_credit, sandbox.provisioning.pix_key_registered, sandbox.provisioning.resumed, session.closed, space_credential_revocation.requested, spaces_consent.accepted, spaces_customer_account.resumed, spaces_customer_account.suspended, system.health.degraded, system.health.recovered, tool_call.failed, tool_call.succeeded, trigger.delivery.failed, trigger.paused_automatically, trigger.test_fire, user.signed_up, wallet.balance.below. */ event: string; server_id?: string; /** @@ -2626,7 +2626,7 @@ export interface paths { }; }; put?: never; - /** @description Post a ledger entry. Admin role. Idempotent on (wallet_id, attempt_id, kind) and (wallet_id, kind, external_ref). Returns 200 with the prior row on retry, 201 on fresh insert. `kind=fund` is accepted only in a test project; in a live project it is refused with 409 `fund_requires_test_project` and nothing is written, because a live wallet is credited only by a real Pix, TED or provider receipt. */ + /** @description Post a ledger entry. Admin role. Idempotent on (wallet_id, attempt_id, kind) and (wallet_id, kind, external_ref). Returns 200 with the prior row on retry, 201 on fresh insert. `kind=fund` is accepted only in a test project; in a live project it is refused with 409 `fund_requires_test_project` and nothing is written, because a live wallet is credited only by a real Pix, TED or provider receipt. A `reverse` names the entry it reverses in `metadata.reverses` and a `release` the hold it releases in `metadata.hold_ref` (ledger ids of this wallet, same currency, with the sign that undoes it, and an `attempt_id`); without one it is refused with 400 `ledger_entry_reference_required`. In a live project a `reverse` that would raise the available balance is refused with 409 `reverse_requires_test_project`. */ post: { parameters: { query?: never; @@ -2660,6 +2660,26 @@ export interface paths { "application/json": components["schemas"]["WalletLedgerEntry"]; }; }; + /** @description A `reverse` or `release` that names no entry; nothing was written. */ + 400: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "ledger_entry_reference_required"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; /** @description Not Found */ 404: { headers: { @@ -2672,7 +2692,7 @@ export interface paths { }; }; }; - /** @description A `fund` in a live project, posted with an API key; nothing was written. */ + /** @description A `fund`, or a `reverse` that would raise available, in a live project; a reverse or release whose named entry is not this wallet's or whose amount does not undo it; nothing was written. */ 409: { headers: { [name: string]: unknown; @@ -2681,7 +2701,7 @@ export interface paths { "application/json": { error: { /** @enum {string} */ - code: "fund_requires_test_project"; + code: "fund_requires_test_project" | "reverse_requires_test_project" | "ledger_entry_reference_invalid" | "ledger_entry_reference_mismatch" | "reverse_exceeds_original" | "hold_already_resolved"; message: string; details?: { [key: string]: unknown; @@ -3246,6 +3266,8 @@ export interface paths { * Account balances, per currency * @description The sum of the balance caches of every non-closed wallet in the caller's project, one row per currency. `held_minor` is `balance_minor − available_minor`, the money open holds reserve. `open_holds` counts HOLD entries that no release or debit settles yet, paired by `metadata.hold_ref`, by `withdrawal_id` for owner withdrawals, or by `attempt_id` — the same pairing the hold sweeper uses. * + * `currencies` is the ACCOUNT's money (`account`): every wallet in Live and where the own Test account rule does not apply; that account's wallet for a Test project with its own bound account; none (an empty list, never a zero) for a Test project the rule reaches with no account yet. The simulator's residue there is `simulator_legacy`, apart, with its totals. + * * Scoped to the organization AND the project: another project's wallets are in no sum. */ get: { @@ -3265,9 +3287,23 @@ export interface paths { content: { "application/json": { project_id: string; + /** @description Managed USDC addresses for the wallets included in this account's balance; absent on older APIs. */ + usdc_accounts?: { + wallet_id: string; + display_name?: string; + /** @enum {string} */ + network: "base" | "base-sepolia"; + address: string | null; + /** @enum {string} */ + state: "queued" | "syncing" | "ready" | "needs_attention"; + faucet: string | null; + reason: string | null; + checked_at: string | null; + }[]; + /** @description The account's money only. Empty when `account.exists` is false (a Test project with no own account yet): the simulator's residue is never presented as the account's balance, nor as a zero one; it is in `simulator_legacy`. */ currencies: { currency: string; - /** @description Σ wallet_balances.balance_minor over the project's non-closed wallets; for a Test project with its own bound account, over that account's wallet only (the simulator's legacy balance stays in the ledger, out of the sum). */ + /** @description Σ wallet_balances.balance_minor over the ACCOUNT's non-closed wallets: every wallet of the project in Live and where `account.applies` is false; for a Test project with its own bound account, that account's wallet only. */ balance_minor: string; /** @description Σ wallet_balances.available_minor over the same wallets. */ available_minor: string; @@ -3276,6 +3312,32 @@ export interface paths { /** @description HOLD entries no release or debit settles yet. */ open_holds: number; }[]; + /** @description Which money `currencies` is (Fabiano 21/10, 02/11): the same cut as the ledger's running balance and the statement document. */ + account: { + /** @description The own Test account rule reaches this project: Test, the switch reaching its org, not a proof project. */ + applies: boolean; + /** @description There is an account whose money `currencies` shows. False only where the rule applies and no account is bound yet. */ + exists: boolean; + /** @description The wallets `currencies` sums: the source of this figure. Another answer naming one of these wallets (the Shop chat's `wallet_id`) reads the same money; one naming another wallet reads another source, never to be added to this one. */ + wallet_ids: string[]; + /** @description With its own bound account: that account's consumer. Null otherwise. */ + consumer_id: string | null; + /** @description With its own bound account: that account's funding source. Null otherwise. */ + funding_source_id: string | null; + }; + /** @description Where the rule applies: the project's other wallets (the simulator's residue, its legacy test funding among it), per currency, apart from the account's. Detail to consult, never available money of the account. Null where the rule does not apply or there is none. No entry is changed. */ + simulator_legacy: { + /** @enum {string} */ + origin: "simulator"; + /** @description The wallets of the residue: its source, apart from `account.wallet_ids`. */ + wallet_ids: string[]; + currencies: { + currency: string; + balance_minor: string; + available_minor: string; + held_minor: string; + }[]; + } | null; /** Format: date-time */ as_of: string; }; @@ -3312,7 +3374,7 @@ export interface paths { * * `reverses`, on a REVERSE entry, is the id of the entry it reverses when that entry is in this project; null on every other kind. * - * `agent_id` is resolved through the entry's consumer mandate, else, on the FUND of a Pix charge a receive proposal sent, that proposal's agent, else the wallet's agent. `balance_after_minor` is the running BOOKED balance of the project in the entry's currency, over every entry and not only the filtered ones: holds and releases leave it unchanged, as they leave `balance_minor` unchanged. At the newest entry it equals the sum of `balance_minor` over the project's wallets in that currency. + * `agent_id` is resolved through the entry's consumer mandate, else, on the FUND of a Pix charge a receive proposal sent, that proposal's agent, else the wallet's agent. `balance_after_minor` is the running BOOKED balance in the entry's currency over the same wallets as GET /v1/account/balances, over every entry and not only the filtered ones: holds and releases leave it unchanged, as they leave `balance_minor` unchanged. At the newest entry it equals the sum of `balance_minor` over those wallets. For a Test project with its own bound account only that account's wallet counts, and for one with no account yet none does: an entry of another wallet (the simulator's, its legacy test funding among it) is listed with its origin, `outside_account_balance` true, and the simulator's own running balance at that point. */ get: { parameters: { @@ -3389,364 +3451,404 @@ export interface paths { /** @description metadata.phase as the writer stamped it: which step of that writer posted the entry. With `source`, it names the entry: `consumer-payments` + `settle-fund` is a payment's settlement FUND, `+ settle-debit` its DEBIT. A phase is only unique within its source. Open vocabulary; null when the writer stamped none. */ phase: string | null; /** - * @description "codespar_simulator" on the hold and the debit of a demonstration payment, settled on the CodeSpar simulator ("Simulado pela CodeSpar"); "celcoin_sandbox" on those of a payment of the restricted integrated proof, made at the Celcoin sandbox ("Integrado (sandbox Celcoin)"); null on every other entry. + * @description "codespar_simulator" on the hold and the debit of a demonstration payment, settled on the CodeSpar simulator ("Simulado pela CodeSpar"); "provider_sandbox" on those of a payment made at a provider's sandbox (`executor_provider` names it); null on every other entry. Test only: no real money either way. * @enum {string|null} */ - executor: "codespar_simulator" | "celcoin_sandbox" | null; - /** @description Running BOOKED balance of the project in this currency right after this entry: Σ amount_minor of every fund/debit/fee/reverse entry up to and including it, in id order; hold, release and reconcile entries repeat the previous value. Equals Σ balance_minor at the head (= available + held). */ - balance_after_minor: string; - }[]; - next_before: string | null; - }; - }; - }; - /** @description The query did not match the schema. `details.issues` carries the Zod issues. */ - 400: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": { - error: { - /** @enum {string} */ - code: "invalid_query"; - message: string; - details?: { - [key: string]: unknown; - }; - }; - /** @description Echoes the `X-Request-Id` header when the request carried one. */ - request_id: string | null; - }; - }; - }; - }; - }; - put?: never; - post?: never; - delete?: never; - options?: never; - head?: never; - patch?: never; - trace?: never; - }; - "/v1/account/summary": { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - /** - * BRL money in, agent spend, tool calls and sessions over a window - * @description BRL only. `received_minor` sums the funding entries stamped as money received (category `recebivel`): test funding and the fund legs that mirror a payment on its way out are not received. A TEST project's body also carries, apart, the test funding the account received (initial test balance, Adicionar fundos, refills; never a transfer between the project's wallets): `test_funding_minor` in the totals, in `previous` and in each `series` bucket; it is not a receipt rail and never appears in `received_by_rail`. A live project's body has no such field. `spent_by_agents_minor` sums debits attributed to an agent. The window is N whole buckets ending with the current, partial one: 24 hours for `24h`, 7 or 30 São Paulo calendar days for `7d` and `30d`. `series` has exactly those N buckets, oldest first, and sums to the two totals; `previous` covers the N buckets immediately before. `received_by_rail` groups that received funding by rail (`pix`, `boleto`, `ted`): `metadata.rail`, or for an entry written before the rail was stamped, the rail its source fixes (a BolePix charge-in: its Collect payment's rail, else `pix`); null where neither says. `tool_calls` and `sessions` are counts over the same window and scope (tool calls by `called_at`, sessions by creation); `sessions.active_now` counts the sessions open at the time of the read that were created or made a tool call in the last 15 minutes, whatever the window: nothing closes an idle session, so an open session idle for longer is not counted. `sessions.active_idle_ms` states that threshold (900000). `window` defaults to `7d`. - */ - get: { - parameters: { - query?: { - window?: "24h" | "7d" | "30d"; - }; - header?: never; - path?: never; - cookie?: never; - }; - requestBody?: never; - responses: { - /** @description OK */ - 200: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": { - /** @enum {string} */ - window: "24h" | "7d" | "30d"; - /** @enum {string} */ - currency: "BRL"; - received_minor: string; - spent_by_agents_minor: string; - /** @description TEST projects only: the test funding the account received (initial test balance, Adicionar fundos, refills; never a transfer between the project's wallets). Never part of `received_minor`. Absent in a live project. */ - test_funding_minor?: string; - previous: { - received_minor: string; - spent_by_agents_minor: string; - /** @description TEST projects only: the test funding the account received (initial test balance, Adicionar fundos, refills; never a transfer between the project's wallets). Never part of `received_minor`. Absent in a live project. */ - test_funding_minor?: string; - }; - series: { - /** Format: date-time */ - bucket_start: string; - received_minor: string; - spent_by_agents_minor: string; - /** @description TEST projects only: the test funding the account received (initial test balance, Adicionar fundos, refills; never a transfer between the project's wallets). Never part of `received_minor`. Absent in a live project. */ - test_funding_minor?: string; - }[]; - /** @description Received funding by rail (`pix`, `boleto`, `ted`): metadata.rail, or for an entry written before the rail was stamped, the rail its source fixes (a BolePix charge-in: its Collect payment's rail, else pix). Null where neither says: money received only. Test funding is not a receipt rail and never appears here; a TEST project carries it in `test_funding_minor`. */ - received_by_rail: { - rail: string | null; - received_minor: string; - }[]; - /** @description session_tool_calls rows with called_at in the window; `errors` = status 'error'. Counts, not money. */ - tool_calls: { - total: number; - errors: number; - }; - /** @description Sessions created in the window; `active_now` = sessions still open (status 'active') at the time of the read that were created, or made a tool call, in the last 15 minutes, whatever the window. A session stays 'active' until it is closed and nothing expires it, so an open session idle for longer is not counted. */ - sessions: { - total: number; - active_now: number; + executor: "codespar_simulator" | "provider_sandbox" | null; /** - * @description The idle threshold `active_now` was counted with, in milliseconds. Its presence marks the 15-minute rule: a server without it counts every open session. - * @enum {number} - */ - active_idle_ms: 900000; - }; - }; - }; - }; - /** @description The query did not match the schema. `details.issues` carries the Zod issues. */ - 400: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": { - error: { - /** @enum {string} */ - code: "invalid_query"; - message: string; - details?: { - [key: string]: unknown; - }; - }; - /** @description Echoes the `X-Request-Id` header when the request carried one. */ - request_id: string | null; - }; - }; - }; - }; - }; - put?: never; - post?: never; - delete?: never; - options?: never; - head?: never; - patch?: never; - trace?: never; - }; - "/v1/account/agent-activity": { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - /** - * BRL spent and received per agent, over a window - * @description One row per agent of the organization plus any agent id this project's entries are attributed to, most spent first. `spent_minor` and `received_minor` (money received only, as in the summary) are BRL over the window, with the summary's geometry: the last 24 hours for `24h`, the last 7 or 30 São Paulo calendar days for `7d` and `30d`. `window` defaults to `30d`. `last_activity_at` is the newest entry attributed to the agent in this project, in any currency and at any time, and null when there is none. `tool_calls` counts the tool calls made in this project over the window by the sessions the agent opened (`agent_id` at session creation); a session opened without an agent counts for nobody. `spent_within_mandate_minor` is the part of `spent_minor` the mandate itself allowed: every debit except those a person approved above the mandate's signed per-transaction cap. - */ - get: { - parameters: { - query?: { - window?: "24h" | "7d" | "30d"; - }; - header?: never; - path?: never; - cookie?: never; - }; - requestBody?: never; - responses: { - /** @description OK */ - 200: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": { - /** @enum {string} */ - window: "24h" | "7d" | "30d"; - /** @enum {string} */ - currency: "BRL"; - agents: { - agent_id: string; - spent_minor: string; - /** @description The part of `spent_minor` within the mandate: every debit except those a person approved above the mandate's signed per-transaction cap (the overage approval). spent_minor − this = spent above the cap. The dashboard computes the fraction. */ - spent_within_mandate_minor: string; - received_minor: string; - /** Format: date-time */ - last_activity_at: string | null; - /** @description session_tool_calls in the window, in this project, of the sessions the agent opened (`sessions.agent_did`). A session opened without an agent counts for nobody. */ - tool_calls: number; - }[]; - }; - }; - }; - /** @description The query did not match the schema. `details.issues` carries the Zod issues. */ - 400: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": { - error: { - /** @enum {string} */ - code: "invalid_query"; - message: string; - details?: { - [key: string]: unknown; - }; - }; - /** @description Echoes the `X-Request-Id` header when the request carried one. */ - request_id: string | null; - }; - }; - }; - }; - }; - put?: never; - post?: never; - delete?: never; - options?: never; - head?: never; - patch?: never; - trace?: never; - }; - "/v1/account/spenders": { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - /** - * The mandates that can spend from this project - * @description One row per mandate whose funding source belongs to the caller's project, active or paused and not expired, newest first: who may spend from this project's wallet. A mandate over another project's source is not listed, and neither is an agent of the organization with no mandate here. In a Test project with its own bound account, the Shop's mandates count only when signed over that account (one over another source is not in force there). `usage` is the mandate's own, from the same sums its cap gates run: `spent_minor` overall and `period_spent_minor` in the current window of its periodic cap. - */ - get: { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - requestBody?: never; - responses: { - /** @description OK */ - 200: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": { - spenders: { - mandate_id: string; - agent_id: string | null; - agent_display_name: string | null; - agent_status: string | null; - display_name: string | null; - /** @enum {string} */ - status: "active" | "paused"; - currency: string; - /** @description The rail of the mandate's funding source. */ - rail: string; - cap_minor: string; - per_tx_cap_minor: string; - periodic_cap: { - /** @enum {string} */ - window: "day" | "month"; - cap_minor: string; - } | null; - /** Format: date-time */ - expires_at: string; - usage: { - /** @description What this mandate has spent, in its own unit. */ - spent_minor: string; - /** @description What it has spent in the current periodic window; null without a periodic cap. */ - period_spent_minor: string | null; - }; - }[]; - }; - }; - }; - }; - }; - put?: never; - post?: never; - delete?: never; - options?: never; - head?: never; - patch?: never; - trace?: never; - }; - "/v1/account/payments": { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - /** - * The project's payments, newest first - * @description One row per spend attempt the payment lifecycle claimed in the caller's project, on every door (by mandate id, signed envelope, MCP, payment link, an approved execution), with its status: `settled` is paid and on the ledger (`debit_entry_id`), `failed` provably moved nothing, `uncertain` is held for reconciliation, the rest are in flight. A spend refused at a gate before any money step leaves no attempt and is not listed. `agent_id` is the agent of the mandate the payment was spent under. Page with `before` set to the previous page's `next_before`, an opaque cursor; `next_before` is null on the last page. - */ - get: { - parameters: { - query?: { - limit?: number; - before?: string; - status?: "claimed" | "dispatching" | "dispatched" | "settle_failed" | "settled" | "uncertain" | "failed"; - agent_id?: string; - mandate_id?: string; - }; - header?: never; - path?: never; - cookie?: never; - }; - requestBody?: never; - responses: { - /** @description OK */ - 200: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": { - payments: { - attempt_id: string; - mandate_id: string; - /** @description consumer_mandates.agent_id of the mandate the payment was spent under. */ - agent_id: string | null; - agent_display_name: string | null; - amount_minor: string; - currency: string; - rail: string; - payee: string | null; - /** @description What the paid document calls itself, when the payment paid a batch item read from one ("DARE-SP", "DARE-SP · Secretaria da Fazenda"; contract payables v1.1, rule 6). Null for every other payment. */ - label: string | null; - /** - * @description settled = paid and on the ledger; failed = provably nothing moved; uncertain = held for reconciliation; claimed / dispatching / dispatched / settle_failed = in flight or resuming. - * @enum {string} + * @description ent#1983: the concrete provider behind `executor` ("celcoin" for `provider_sandbox`), resolved by the server; null for the simulator and every other entry. + * @enum {string|null} */ - status: "claimed" | "dispatching" | "dispatched" | "settle_failed" | "settled" | "uncertain" | "failed"; - failure_code: string | null; - receipt_id: string | null; - /** @description The ledger DEBIT of a settled payment, the id GET /v1/account/ledger shows. */ - debit_entry_id: string | null; + executor_provider: "celcoin" | null; + /** @description On a payment's DEBIT: who it credited. From what the provider answered about the destination when the money went out (`payee_name_source` `dict` or `credit_party`), else the merchant name a paid QR Code declared (`br_code`: the QR's own words, not a confirmed payee). Null otherwise, and on a payment sealed before the provider's answer was recorded: never inferred. */ + payee_name: string | null; /** - * @description "codespar_simulator" when the payment was a demonstration settled on the CodeSpar simulator ("Simulado pela CodeSpar"); "celcoin_sandbox" when it ran in the restricted integrated proof, at the Celcoin sandbox ("Integrado (sandbox Celcoin)"); null for every other payment. What the payment recorded when it ran. + * @description Where `payee_name` came from. * @enum {string|null} */ - executor: "codespar_simulator" | "celcoin_sandbox" | null; - /** Format: date-time */ - created_at: string; - /** Format: date-time */ - updated_at: string; + payee_name_source: "dict" | "credit_party" | "br_code" | null; + /** @description On a payment's DEBIT: who triggered the tool call that made the payment (its `actor`, 0408), found by the call's own attempt or receipt id. Null when no recorded call matches: a payment from the dashboard's own buttons, or one made before 0408. Never filled in from the mandate's agent. */ + triggered_by: { + /** + * @description How the caller authenticated: an OAuth connection (an MCP client), an API key, or the platform's service key (the dashboard). + * @enum {string} + */ + via: "oauth" | "bearer" | "service"; + /** @description On `oauth`: the name the OAuth client declared about itself at dynamic registration. Self-declared, never verified. */ + client_name_declared?: string | null; + /** @description On `oauth`: the client id, last four characters only. */ + client_id_masked?: string | null; + /** @description On `bearer`: the API key id, last four characters only. */ + key_id_masked?: string | null; + } | null; + /** @description Running BOOKED balance in this currency right after this entry, over the same wallets as GET /v1/account/balances: Σ amount_minor of every fund/debit/fee/reverse entry of those wallets up to and including it, in id order; hold, release and reconcile entries repeat the previous value. Equals Σ balance_minor at the head (= available + held). Each entry runs in its own scope (Fabiano 21/10, 02/11): the account's wallets as GET /v1/account/balances cuts them, or, on an entry with `outside_account_balance` true, the simulator's residue's own running balance at that point (never the account's, never an invented 0). */ + balance_after_minor: string; + /** @description True on an entry of a wallet GET /v1/account/balances does not sum: the simulator's residue (its legacy test funding among it) of a Test project with its own bound account, or every entry of one the own-account rule reaches with no account yet. Shown with its own origin, never counted in the account's balance; false everywhere else. */ + outside_account_balance: boolean; }[]; next_before: string | null; }; }; }; - /** @description The query did not match the schema, or `before` is not a cursor this route issued. */ + /** @description The query did not match the schema. `details.issues` carries the Zod issues. */ + 400: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "invalid_query"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + }; + }; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/v1/account/summary": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * BRL money in, agent spend, tool calls and sessions over a window + * @description BRL only. `received_minor` sums the funding entries stamped as money received (category `recebivel`): test funding and the fund legs that mirror a payment on its way out are not received. A TEST project's body also carries, apart, the test funding the account received (initial test balance, Adicionar fundos, refills; never a transfer between the project's wallets): `test_funding_minor` in the totals, in `previous` and in each `series` bucket; it is not a receipt rail and never appears in `received_by_rail`. A live project's body has no such field. `spent_by_agents_minor` sums debits attributed to an agent. The window is N whole buckets ending with the current, partial one: 24 hours for `24h`, 7 or 30 São Paulo calendar days for `7d` and `30d`. `series` has exactly those N buckets, oldest first, and sums to the two totals; `previous` covers the N buckets immediately before. `received_by_rail` groups that received funding by rail (`pix`, `boleto`, `ted`): `metadata.rail`, or for an entry written before the rail was stamped, the rail its source fixes (a BolePix charge-in: its Collect payment's rail, else `pix`); null where neither says. `tool_calls` and `sessions` are counts over the same window and scope (tool calls by `called_at`, sessions by creation); `sessions.active_now` counts the sessions open at the time of the read that were created or made a tool call in the last 15 minutes, whatever the window: nothing closes an idle session, so an open session idle for longer is not counted. `sessions.active_idle_ms` states that threshold (900000). `window` defaults to `7d`. + */ + get: { + parameters: { + query?: { + window?: "24h" | "7d" | "30d"; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description OK */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + /** @enum {string} */ + window: "24h" | "7d" | "30d"; + /** @enum {string} */ + currency: "BRL"; + received_minor: string; + spent_by_agents_minor: string; + /** @description TEST projects only: the test funding the account received (initial test balance, Adicionar fundos, refills; never a transfer between the project's wallets). Never part of `received_minor`. Absent in a live project. */ + test_funding_minor?: string; + previous: { + received_minor: string; + spent_by_agents_minor: string; + /** @description TEST projects only: the test funding the account received (initial test balance, Adicionar fundos, refills; never a transfer between the project's wallets). Never part of `received_minor`. Absent in a live project. */ + test_funding_minor?: string; + }; + series: { + /** Format: date-time */ + bucket_start: string; + received_minor: string; + spent_by_agents_minor: string; + /** @description TEST projects only: the test funding the account received (initial test balance, Adicionar fundos, refills; never a transfer between the project's wallets). Never part of `received_minor`. Absent in a live project. */ + test_funding_minor?: string; + }[]; + /** @description Received funding by rail (`pix`, `boleto`, `ted`): metadata.rail, or for an entry written before the rail was stamped, the rail its source fixes (a BolePix charge-in: its Collect payment's rail, else pix). Null where neither says: money received only. Test funding is not a receipt rail and never appears here; a TEST project carries it in `test_funding_minor`. */ + received_by_rail: { + rail: string | null; + received_minor: string; + }[]; + /** @description session_tool_calls rows with called_at in the window; `errors` = status 'error'. Counts, not money. */ + tool_calls: { + total: number; + errors: number; + }; + /** @description Sessions created in the window; `active_now` = sessions still open (status 'active') at the time of the read that were created, or made a tool call, in the last 15 minutes, whatever the window. A session stays 'active' until it is closed and nothing expires it, so an open session idle for longer is not counted. */ + sessions: { + total: number; + active_now: number; + /** + * @description The idle threshold `active_now` was counted with, in milliseconds. Its presence marks the 15-minute rule: a server without it counts every open session. + * @enum {number} + */ + active_idle_ms: 900000; + }; + }; + }; + }; + /** @description The query did not match the schema. `details.issues` carries the Zod issues. */ + 400: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "invalid_query"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + }; + }; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/v1/account/agent-activity": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * BRL spent and received per agent, over a window + * @description One row per agent of the organization plus any agent id this project's entries are attributed to, most spent first. `spent_minor` and `received_minor` (money received only, as in the summary) are BRL over the window, with the summary's geometry: the last 24 hours for `24h`, the last 7 or 30 São Paulo calendar days for `7d` and `30d`. `window` defaults to `30d`. `last_activity_at` is the newest entry attributed to the agent in this project, in any currency and at any time, and null when there is none. `tool_calls` counts the tool calls made in this project over the window by the sessions the agent opened (`agent_id` at session creation); a session opened without an agent counts for nobody. `spent_within_mandate_minor` is the part of `spent_minor` the mandate itself allowed: every debit except those a person approved above the mandate's signed per-transaction cap. + */ + get: { + parameters: { + query?: { + window?: "24h" | "7d" | "30d"; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description OK */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + /** @enum {string} */ + window: "24h" | "7d" | "30d"; + /** @enum {string} */ + currency: "BRL"; + agents: { + agent_id: string; + spent_minor: string; + /** @description The part of `spent_minor` within the mandate: every debit except those a person approved above the mandate's signed per-transaction cap (the overage approval). spent_minor − this = spent above the cap. The dashboard computes the fraction. */ + spent_within_mandate_minor: string; + received_minor: string; + /** Format: date-time */ + last_activity_at: string | null; + /** @description session_tool_calls in the window, in this project, of the sessions the agent opened (`sessions.agent_did`). A session opened without an agent counts for nobody. */ + tool_calls: number; + /** @description The part of `spent_minor` that an external OAuth connection (an MCP client) paid under this agent's mandate, by the connection's declared name: the tool call that made the payment carries the connection (0408). Not this agent's own act; empty when none, and for payments made before 0408. */ + via_connections: { + /** @description The OAuth client's name as it declared it at dynamic registration; never verified. */ + client_name_declared: string | null; + spent_minor: string; + payments: number; + }[]; + }[]; + }; + }; + }; + /** @description The query did not match the schema. `details.issues` carries the Zod issues. */ + 400: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "invalid_query"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + }; + }; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/v1/account/spenders": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * The mandates that can spend from this project + * @description One row per mandate whose funding source belongs to the caller's project, active or paused and not expired, newest first: who may spend from this project's wallet. A mandate over another project's source is not listed, and neither is an agent of the organization with no mandate here. In a Test project with its own bound account, the Shop's mandates count only when signed over that account (one over another source is not in force there). `usage` is the mandate's own, from the same sums its cap gates run: `spent_minor` overall and `period_spent_minor` in the current window of its periodic cap. + */ + get: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description OK */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + spenders: { + mandate_id: string; + agent_id: string | null; + agent_display_name: string | null; + agent_status: string | null; + display_name: string | null; + /** @enum {string} */ + status: "active" | "paused"; + currency: string; + /** @description The rail of the mandate's funding source. */ + rail: string; + cap_minor: string; + per_tx_cap_minor: string; + periodic_cap: { + /** @enum {string} */ + window: "day" | "month"; + cap_minor: string; + } | null; + /** Format: date-time */ + expires_at: string; + usage: { + /** @description What this mandate has spent, in its own unit. */ + spent_minor: string; + /** @description What it has spent in the current periodic window; null without a periodic cap. */ + period_spent_minor: string | null; + }; + }[]; + }; + }; + }; + }; + }; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/v1/account/payments": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * The project's payments, newest first + * @description One row per spend attempt the payment lifecycle claimed in the caller's project, on every door (by mandate id, signed envelope, MCP, payment link, an approved execution), with its status: `settled` is paid and on the ledger (`debit_entry_id`), `failed` provably moved nothing, `uncertain` is held for reconciliation, the rest are in flight. A spend refused at a gate before any money step leaves no attempt and is not listed. `agent_id` is the agent of the mandate the payment was spent under. Page with `before` set to the previous page's `next_before`, an opaque cursor; `next_before` is null on the last page. + */ + get: { + parameters: { + query?: { + limit?: number; + before?: string; + status?: "claimed" | "dispatching" | "dispatched" | "settle_failed" | "settled" | "uncertain" | "failed"; + agent_id?: string; + mandate_id?: string; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description OK */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + payments: { + attempt_id: string; + mandate_id: string; + /** @description consumer_mandates.agent_id of the mandate the payment was spent under. */ + agent_id: string | null; + agent_display_name: string | null; + amount_minor: string; + currency: string; + rail: string; + payee: string | null; + /** @description What the paid document calls itself, when the payment paid a batch item read from one ("DARE-SP", "DARE-SP · Secretaria da Fazenda"; contract payables v1.1, rule 6). Null for every other payment. */ + label: string | null; + /** + * @description settled = paid and on the ledger; failed = provably nothing moved; uncertain = held for reconciliation; claimed / dispatching / dispatched / settle_failed = in flight or resuming. + * @enum {string} + */ + status: "claimed" | "dispatching" | "dispatched" | "settle_failed" | "settled" | "uncertain" | "failed"; + failure_code: string | null; + receipt_id: string | null; + /** @description The ledger DEBIT of a settled payment, the id GET /v1/account/ledger shows. */ + debit_entry_id: string | null; + /** + * @description "codespar_simulator" when the payment was a demonstration settled on the CodeSpar simulator ("Simulado pela CodeSpar"); "provider_sandbox" when it ran at a provider's sandbox (`executor_provider` names it); null for every other payment. What the payment recorded when it ran. Test only: no real money either way. + * @enum {string|null} + */ + executor: "codespar_simulator" | "provider_sandbox" | null; + /** + * @description ent#1983: the concrete provider behind `executor` ("celcoin" for `provider_sandbox`), resolved by the server; null for the simulator and every other entry. + * @enum {string|null} + */ + executor_provider: "celcoin" | null; + /** Format: date-time */ + created_at: string; + /** Format: date-time */ + updated_at: string; + }[]; + next_before: string | null; + }; + }; + }; + /** @description The query did not match the schema, or `before` is not a cursor this route issued. */ 400: { headers: { [name: string]: unknown; @@ -3791,7 +3893,7 @@ export interface paths { * * `target` picks the wallet. `account` (the default) is the project's account wallet, created on first use: the account Wallet shows it, but no agent spends from it. `consumer` is the consumer wallet a mandate spend reserves and debits: `mandate_id`'s consumer, else `consumer_id`, else the one consumer the organization's active BRL mandates name; none or several answer `test_funding_target_required` with the candidates. Naming `mandate_id` or `consumer_id` implies `consumer`. A consumer wallet created here starts with exactly the amount funded. * - * At most 1000000 centavos per call. `idempotency_key` is required: the same key with the same amount and wallet answers the first entry with 200 and `idempotent_replay: true`; with another amount or wallet, `idempotency_key_conflict`. Requires an admin or owner (`x-codespar-user` on the dashboard path). + * At most 1000000 centavos per call. `idempotency_key` is required: the same key with the same amount and wallet answers the first entry with 200 and `idempotent_replay: true`; with another amount or wallet, `idempotency_key_conflict`. An admin or owner performs it from the dashboard; an API key is refused with 403 `admin_session_required`, whatever its scopes. * * A Test project with its own bound provider account (`payments` active) is credited THERE instead: the amount goes to the bound account, claimed before it is sent and copied into the binding consumer's wallet ledger (`consumer_id` names it), with no platform total. An earlier credit still in flight or whose result is unknown blocks the next (`sandbox_funding_open_claim`); a platform guard's refusal before the send answers `sandbox_funding_refused` (422), a provider refusal `sandbox_funding_failed`. */ @@ -3902,7 +4004,7 @@ export interface paths { }; }; }; - /** @description The acting member is below admin, or the dashboard forwarded no member. */ + /** @description The acting member is below admin, the dashboard forwarded no member, or the credential is an API key (`admin_session_required`: this is administrative, whatever the key's scopes). */ 403: { headers: { [name: string]: unknown; @@ -4161,7 +4263,7 @@ export interface paths { }; }; }; - /** @description The acting member is below admin, or the dashboard forwarded no member. */ + /** @description The acting member is below admin, the dashboard forwarded no member, or the credential is an API key (`admin_session_required`: this is administrative, whatever the key's scopes). */ 403: { headers: { [name: string]: unknown; @@ -4327,10 +4429,15 @@ export interface paths { /** @description The dashboard assistant conversation this session belongs to (the Shop's or the Playground chat's); null otherwise. */ conversation_id: string | null; /** - * @description "codespar_simulator" when this session's payments were demonstrations settled on the CodeSpar simulator ("Simulado pela CodeSpar"); "celcoin_sandbox" when they ran in the restricted integrated proof, at the Celcoin sandbox ("Integrado (sandbox Celcoin)"); null otherwise. + * @description "codespar_simulator" when this session's payments were demonstrations settled on the CodeSpar simulator ("Simulado pela CodeSpar"); "provider_sandbox" when they ran at a provider's sandbox (`executor_provider` names it); null otherwise. Test only: no real money either way. + * @enum {string|null} + */ + executor: "codespar_simulator" | "provider_sandbox" | null; + /** + * @description ent#1983: the concrete provider behind `executor` ("celcoin" for `provider_sandbox`); null otherwise. * @enum {string|null} */ - executor: "codespar_simulator" | "celcoin_sandbox" | null; + executor_provider: "celcoin" | null; }[]; next_before: string | null; /** @description Sessions matching the filters, cursor aside. */ @@ -4377,7 +4484,7 @@ export interface paths { }; /** * The first-access guide's progress for the project - * @description Three steps, read in one call. `agent`: the organization has a registered agent other than a Playground scene's own; `in_project` says whether one of them works in this project (an active mandate funds it). `scenario`: a session of this project recorded a tool call; the first one names the session and, for a Playground session, its scene. `result`: money moved under a mandate in this project (the first debit); test funding is not a result. Read-only. `project_id`, when sent, must be the project the request resolved to, or the answer is 404. + * @description Three steps, read in one call. `agent`: the organization has a registered agent other than a Playground scene's own; `in_project` says whether one of them works in this project (an active mandate funds it). `scenario`: a session of this project recorded a tool call; the first one names the session and, for a Playground session, its scene. `result`: money moved under a mandate in this project (the first debit); test funding is not a result. Added for the new guide, each derived from the server's own records, with a `state` (done, pending, or unverified when the read failed: `done` is then null, never a false nobody read): `receive` (the first Collect payment confirmed by the provider, in the ledger, with its signed receipt; test funding, the initial credit included, never counts; the same source as the first receipt's `project_has_confirmed_receipt`), `shop_payment` (the Shop assistant's first settled, debited and receipted payment), `approval` (a person's first decision on a proposal parked above the mandate's limit) and `connect` (a valid connection from its own state: an unexpired, unrevoked OAuth grant under a live key, else an API key used at least once and not revoked). Read-only. `project_id`, when sent, must be the project the request resolved to, or the answer is 404. */ get: { parameters: { @@ -4431,6 +4538,88 @@ export interface paths { */ at: string | null; }; + receive: { + /** + * @description done: the fact is there. pending: read, and it is not. unverified: the read failed; `done` is then null. + * @enum {string} + */ + state: "done" | "pending" | "unverified"; + /** @description Null only when `state` is unverified. */ + done: boolean | null; + /** + * Format: date-time + * @description When the first confirmed Collect payment was paid. + */ + at: string | null; + charge_id: string | null; + receipt_id: string | null; + ledger_entry_id: string | null; + }; + shop_payment: { + /** + * @description done: the fact is there. pending: read, and it is not. unverified: the read failed; `done` is then null. + * @enum {string} + */ + state: "done" | "pending" | "unverified"; + /** @description Null only when `state` is unverified. */ + done: boolean | null; + /** + * @description Where the money came from. wallet_*: a Wallet debit the provider settled. external_card / store_on_file: the store's order, no Wallet leg and no settlement claimed. + * @enum {string|null} + */ + origin: "wallet_pix" | "wallet_boleto" | "external_card" | "store_on_file" | null; + /** + * Format: date-time + * @description wallet_*: when the debit posted. External: when the store's order closed the attempt. + */ + at: string | null; + proposal_id: string | null; + mandate_id: string | null; + /** @description The Wallet payment's receipt; null for an external purchase, whose receipt is its order record. */ + receipt_id: string | null; + /** @description Null when the origin does not go through the Wallet. */ + ledger_entry_id: string | null; + /** @description The store's order id, for an external purchase. */ + order_id: string | null; + }; + approval: { + /** + * @description done: the fact is there. pending: read, and it is not. unverified: the read failed; `done` is then null. + * @enum {string} + */ + state: "done" | "pending" | "unverified"; + /** @description Null only when `state` is unverified. */ + done: boolean | null; + /** + * Format: date-time + * @description When a person first decided a proposal parked above the mandate's limit. + */ + at: string | null; + proposal_id: string | null; + /** @enum {string|null} */ + decision: "approved" | "denied" | null; + /** @description The receipt of the approved payment, once it was paid. */ + receipt_id: string | null; + }; + connect: { + /** + * @description done: the fact is there. pending: read, and it is not. unverified: the read failed; `done` is then null. + * @enum {string} + */ + state: "done" | "pending" | "unverified"; + /** @description Null only when `state` is unverified. */ + done: boolean | null; + /** + * Format: date-time + * @description OAuth: when the live refresh token was issued (each refresh rotates it). A key: its last use (a key records no other). + */ + at: string | null; + /** @enum {string|null} */ + via: "oauth" | "bearer" | null; + /** @description The name the OAuth client declared at registration; never verified. */ + client_name_declared: string | null; + key_id_masked: string | null; + }; }; }; }; @@ -4484,6 +4673,150 @@ export interface paths { patch?: never; trace?: never; }; + "/v1/onboarding/first-receive": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * The project's first test receipt (the guide's Receber R$ 10) + * @description Read-only. The project's first-receive obligation is a Collect link under the reference `codespar_first_receive` (version 1), R$ 10,00, paid by the platform's Test payer. States, from Collect's records, never a clock: `not_started` (no link, or no attempt), `creating_charge` (the charge waits for its copia-e-cola), `paying` (open, the Test payer has not taken it: a POST pays it), `awaiting_confirmation` (the payer took it, or a payment is not yet confirmed with its receipt), `received` (`paid_confirmed`, in the ledger, with its signed receipt; the only state that says received), `failed` (`refusal.retriable` says whether a POST starts again, on the same link), `blocked` (a precondition is missing; nothing is created). + */ + get: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description OK */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + /** @enum {string} */ + object: "first_receive"; + /** @enum {string} */ + state: "not_started" | "creating_charge" | "paying" | "awaiting_confirmation" | "received" | "failed" | "blocked"; + /** @description Always 1000 (R$ 10,00): the server's, never the request's. */ + amount_minor: number; + link_id: string | null; + attempt_id: string | null; + charge_id: string | null; + /** @description Only in `received`: confirmed by the provider (D-A), with its ledger entry and signed receipt. */ + payment: { + payment_id: string; + /** @enum {string} */ + status: "paid_confirmed"; + receipt_id: string; + ledger_entry_id: string; + /** Format: date-time */ + paid_at: string; + } | null; + /** @description In `blocked` and `failed`. */ + refusal: { + /** @description blocked: not_test, collect_off, receive_unavailable, insufficient_role. failed: the Collect or test-pay code. */ + code: string; + message: string; + /** @description Whether a POST may start again; false needs something else first (the refusal says what). */ + retriable: boolean; + next_action?: string; + } | null; + /** @description Any confirmed Collect receipt of the project, from this link or another: the guide's first step is done. */ + project_has_confirmed_receipt: boolean; + }; + }; + }; + }; + }; + put?: never; + /** + * Take the project's first test receipt one step further + * @description No body. Idempotent: a repeated click, a refresh or a timeout resumes the same obligation, never a second link, attempt or payment. From where the records are: creates or answers the referenced link, publishes it, asks it for an attempt, or has the Test payer pay the open attempt (one payment per charge). The copia-e-cola arrives after the POST, so the answer is often `creating_charge`; once the GET reads `paying`, one more POST pays it. Test projects only; an admin's or the owner's act from the dashboard, or the project's own key. Answers the GET's view. States, from Collect's records, never a clock: `not_started` (no link, or no attempt), `creating_charge` (the charge waits for its copia-e-cola), `paying` (open, the Test payer has not taken it: a POST pays it), `awaiting_confirmation` (the payer took it, or a payment is not yet confirmed with its receipt), `received` (`paid_confirmed`, in the ledger, with its signed receipt; the only state that says received), `failed` (`refusal.retriable` says whether a POST starts again, on the same link), `blocked` (a precondition is missing; nothing is created). + */ + post: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description OK */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + /** @enum {string} */ + object: "first_receive"; + /** @enum {string} */ + state: "not_started" | "creating_charge" | "paying" | "awaiting_confirmation" | "received" | "failed" | "blocked"; + /** @description Always 1000 (R$ 10,00): the server's, never the request's. */ + amount_minor: number; + link_id: string | null; + attempt_id: string | null; + charge_id: string | null; + /** @description Only in `received`: confirmed by the provider (D-A), with its ledger entry and signed receipt. */ + payment: { + payment_id: string; + /** @enum {string} */ + status: "paid_confirmed"; + receipt_id: string; + ledger_entry_id: string; + /** Format: date-time */ + paid_at: string; + } | null; + /** @description In `blocked` and `failed`. */ + refusal: { + /** @description blocked: not_test, collect_off, receive_unavailable, insufficient_role. failed: the Collect or test-pay code. */ + code: string; + message: string; + /** @description Whether a POST may start again; false needs something else first (the refusal says what). */ + retriable: boolean; + next_action?: string; + } | null; + /** @description Any confirmed Collect receipt of the project, from this link or another: the guide's first step is done. */ + project_has_confirmed_receipt: boolean; + }; + }; + }; + /** @description A body was sent: amount, receiver and payer are the server's. */ + 400: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "invalid_body"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + }; + }; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; "/v1/account/test-balance": { parameters: { query?: never; @@ -4567,7 +4900,7 @@ export interface paths { put?: never; /** * Refill the test balance (test projects only, confirmed) - * @description Brings the project's test balance (available + held, every wallet) back up to 10000 centavos, crediting only the difference to the account wallet; a balance already there answers 200 with `refilled: false` and credits nothing. At most 3 refills per São Paulo calendar day per project; the credit and the quota use are one row in one transaction, and a refill that credits nothing uses no quota. Adicionar fundos is a separate action and never counts. An explicit, confirmed act of a person: the body must be `{ "confirm": true }`. The entry is test funding (`test_funding_kind: refill`) and never money received. Admin or owner. + * @description Brings the project's test balance (available + held, every wallet) back up to 10000 centavos, crediting only the difference to the account wallet; a balance already there answers 200 with `refilled: false` and credits nothing. At most 3 refills per São Paulo calendar day per project; the credit and the quota use are one row in one transaction, and a refill that credits nothing uses no quota. Adicionar fundos is a separate action and never counts. An explicit, confirmed act of a person: the body must be `{ "confirm": true }`. The entry is test funding (`test_funding_kind: refill`) and never money received. Admin or owner, from the dashboard; an API key is refused with 403 `admin_session_required`. * * A Test project with its own bound provider account (`payments` active) refills THAT account: its balance is read at the provider and only the difference to the target is credited there, claimed before it is sent, with NO daily quota (`refill.daily_limit` and `left_today` null). An unreadable balance credits nothing (502 `test_funding_failed`). */ @@ -4714,7 +5047,7 @@ export interface paths { }; }; }; - /** @description The acting member is below admin, or the dashboard forwarded no member. */ + /** @description The acting member is below admin, the dashboard forwarded no member, or the credential is an API key (`admin_session_required`: this is administrative, whatever the key's scopes). */ 403: { headers: { [name: string]: unknown; @@ -7080,84 +7413,2499 @@ export interface paths { }; put?: never; /** - * Initiate a bank consent - * @description Opens a consent at the bank and persists it as `pending`. `POST /v1/ofb/consents` is the legacy spelling of this same operation, kept for two releases (ent#979); new integrations use this path. + * Initiate a bank consent + * @description Opens a consent at the bank and persists it as `pending`. `POST /v1/ofb/consents` is the legacy spelling of this same operation, kept for two releases (ent#979); new integrations use this path. + * + * THE BANK IS CALLED BEFORE THE ROW IS WRITTEN, and that ordering is visible in the failure modes below: every refusal that arrives after the bank call leaves a bank-side consent with no row of ours pointing at it. Retrying opens another one. + * + * One open consent per consumer per bank per organization. A sibling project in your organization holding an open consent for this consumer at this bank is refused, and the refusal is not something a retry clears. + * + * On 201 the consent is `pending`, and `authorisation_url`, `bank_consent_id` and `expires_at` are all set: the adapter's result declares them non-nullable and the INSERT writes all three. Send the consumer to `authorisation_url`, then post the code they come back with to the callback operation. + */ + post: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: { + content: { + "application/json": { + bank_id: string; + consumer_id: string; + scopes: string[]; + /** + * Format: uri + * @description Where the bank returns the consumer after authorisation. You compose it and you host it. + */ + redirect_url: string; + /** @description Binds the consent to a wallet, so the statements it ingests carry that wallet. */ + wallet_id?: string; + }; + }; + }; + responses: { + /** @description Created. The consent is `pending` and `authorisation_url` is set. */ + 201: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + id: string; + /** @description Lowercase kebab-case, for example `itau` or `bb`. */ + bank_id: string; + consumer_id: string; + /** @description Set when the consent was bound to a wallet at initiation; null when it was not. */ + wallet_id: string | null; + /** @enum {string} */ + status: "pending" | "authorised" | "revoked" | "expired" | "consumed"; + scopes: string[]; + /** @description The bank's own identifier for the consent. Null until the bank issues one. */ + bank_consent_id: string | null; + /** @description Where the consumer authorises the consent. This is the URL to send them to. */ + authorisation_url: string | null; + /** Format: date-time */ + token_expires_at: string | null; + /** Format: date-time */ + created_at: string; + /** + * Format: date-time + * @description Spelled with a z, unlike `authorised` in `status`. Both spellings are column names, not typos. + */ + authorized_at: string | null; + /** + * Format: date-time + * @description Mirrors the bank-side consent expiry, as the bank reported it at initiation. + */ + expires_at: string | null; + /** Format: date-time */ + revoked_at: string | null; + /** Format: date-time */ + consumed_at: string | null; + metadata: { + [key: string]: unknown; + }; + }; + }; + }; + /** @description The body did not match the schema. `details.issues` carries the Zod issues. */ + 400: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "invalid_body"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** + * @description `bank_consent_held_elsewhere` when another project in this organization holds an open (`pending` or `authorised`) consent for this consumer at this bank. `details.remediation` says what to do and `details.retriable` is false: one project's bank grant is never shared with another, so re-sending this request unchanged will not clear it. + * + * `consent_active_for_consumer` when YOUR OWN project already holds one that is still inside its validity window. Revoke it first. One past its window does not refuse: it is moved to `expired` as the new consent is created. + * + * `db_error` when the consent could not be persisted for any other reason. The cause is in our logs under the request id and is deliberately not in this body, because the driver's own message names another project's key values. + */ + 409: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "bank_consent_held_elsewhere" | "consent_active_for_consumer" | "db_error"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description `ofb_not_live`: this is a LIVE project and the deployment has no real Open Finance adapter, only the stub, which serves test projects. TERMINAL for this project: use a test project. Nothing was written and no bank was contacted. */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "ofb_not_live"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description `consent_disappeared`: the row was written and could not be read back. Do not retry blind; both the row and the bank-side consent may exist. */ + 500: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "consent_disappeared"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description The bank refused the request or could not be reached, before anything was written. The message is the adapter's own. */ + 502: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "adapter_error"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** + * @description `consent_lock_timeout`: another request is issuing a consent for this consumer at this bank and the wait ended without an answer, so NOTHING WAS DECIDED. We do not know whether a sibling holds the grant, and saying so is why this is not the 409. `details.retriable` is true. No consent row was created; a bank-side consent was, and is orphaned. + * + * `ofb_adapter_unavailable`: the Open Finance adapter this deployment selects cannot serve (`details.reason`: `missing_credentials`, `not_implemented` or `unknown_mode`). Ours to fix, not yours; nothing was written and no bank was contacted. + */ + 503: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "consent_lock_timeout" | "ofb_adapter_unavailable"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + }; + }; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/v1/bank-consents/{id}": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Read one bank consent + * @description The body is the consent projection: the same shape `POST /v1/bank-consents` returns on create, and the same one the callback and revoke transitions return. The refresh-statement operation in this family is the exception, answering with a run summary rather than a consent. + * + * Resolution is scoped to the organization AND the project the credential authenticates for. A consent held by a SIBLING project in the same organization answers 404 here, indistinguishable from one that never existed. That is deliberate rather than incidental: one project's upstream bank grant is never readable from another. + * + * No token material leaves. The row carries references to the bank's access and refresh tokens; they are dropped before the body is built, and `token_expires_at` is the only thing about the bank token that is returned. + * + * Requires the `consents:read` scope. + */ + get: { + parameters: { + query?: never; + header?: never; + path: { + /** @description `ofb_`-prefixed consent id. */ + id: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description OK */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + /** @description `ofb_`-prefixed. The id every other operation in this family takes. */ + id: string; + /** @description Lowercase kebab-case, as supplied when the consent was opened: `itau`, `bradesco`, `bb`, `inter`. */ + bank_id: string; + /** @description The consumer, in the caller's own namespace. */ + consumer_id: string; + /** + * @description The wallet named on the create request, or null. Written once at creation and never rewritten: neither state transition on this consent touches the column. + * + * It is a label, not routing. A statement refresh copies this value onto every event it ingests, and nothing downstream reads it: reconciliation resolves a wallet from the funding source behind an event's `connection_id`, and the events this family publishes carry no such key. Binding a consent to a wallet therefore does not, on its own, put the ingested statement into that wallet's reconciliation. + */ + wallet_id: string | null; + /** + * @description `authorised` carries the British spelling, which is the column's own and not a typo. `revoked`, `expired` and `consumed` are terminal: no transition leaves them. Read "is this consent usable now" from `status` being `authorised`, never from `revoked_at` being null. + * @enum {string} + */ + status: "pending" | "authorised" | "revoked" | "expired" | "consumed"; + /** @description The OFB scopes the consent was opened for. */ + scopes: string[]; + /** @description The bank's own identifier for the consent, as returned when it was opened. */ + bank_consent_id: string | null; + /** @description The URL the consumer opens to authorise the consent at their bank. */ + authorisation_url: string | null; + /** + * Format: date-time + * @description Expiry of the bank access token. The token references themselves are never returned by this API. + */ + token_expires_at: string | null; + /** Format: date-time */ + created_at: string; + /** + * Format: date-time + * @description American spelling here, unlike `status: "authorised"`; both mirror their own column names. Stamped in the same statement as the transition into `authorised`. + */ + authorized_at: string | null; + /** + * Format: date-time + * @description Mirror of the bank-side consent expiry, stamped when the consent is opened. + */ + expires_at: string | null; + /** Format: date-time */ + revoked_at: string | null; + /** Format: date-time */ + consumed_at: string | null; + metadata: { + [key: string]: unknown; + }; + }; + }; + }; + /** @description Not Found. No consent with this id in the caller's project. A consent belonging to another project in the same organization answers here too. */ + 404: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "not_found"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + }; + }; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/v1/ofb/consents/{id}": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Read one bank consent + * @deprecated + * @description DEPRECATED alias of `GET /v1/bank-consents/{id}` (ent#979), kept for two releases. Same handler, same required scope; switch the path and nothing else changes. + * + * The body is the consent projection: the same shape `POST /v1/bank-consents` returns on create, and the same one the callback and revoke transitions return. The refresh-statement operation in this family is the exception, answering with a run summary rather than a consent. + * + * Resolution is scoped to the organization AND the project the credential authenticates for. A consent held by a SIBLING project in the same organization answers 404 here, indistinguishable from one that never existed. That is deliberate rather than incidental: one project's upstream bank grant is never readable from another. + * + * No token material leaves. The row carries references to the bank's access and refresh tokens; they are dropped before the body is built, and `token_expires_at` is the only thing about the bank token that is returned. + * + * Requires the `consents:read` scope. + */ + get: { + parameters: { + query?: never; + header?: never; + path: { + /** @description `ofb_`-prefixed consent id. */ + id: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description OK */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + /** @description `ofb_`-prefixed. The id every other operation in this family takes. */ + id: string; + /** @description Lowercase kebab-case, as supplied when the consent was opened: `itau`, `bradesco`, `bb`, `inter`. */ + bank_id: string; + /** @description The consumer, in the caller's own namespace. */ + consumer_id: string; + /** + * @description The wallet named on the create request, or null. Written once at creation and never rewritten: neither state transition on this consent touches the column. + * + * It is a label, not routing. A statement refresh copies this value onto every event it ingests, and nothing downstream reads it: reconciliation resolves a wallet from the funding source behind an event's `connection_id`, and the events this family publishes carry no such key. Binding a consent to a wallet therefore does not, on its own, put the ingested statement into that wallet's reconciliation. + */ + wallet_id: string | null; + /** + * @description `authorised` carries the British spelling, which is the column's own and not a typo. `revoked`, `expired` and `consumed` are terminal: no transition leaves them. Read "is this consent usable now" from `status` being `authorised`, never from `revoked_at` being null. + * @enum {string} + */ + status: "pending" | "authorised" | "revoked" | "expired" | "consumed"; + /** @description The OFB scopes the consent was opened for. */ + scopes: string[]; + /** @description The bank's own identifier for the consent, as returned when it was opened. */ + bank_consent_id: string | null; + /** @description The URL the consumer opens to authorise the consent at their bank. */ + authorisation_url: string | null; + /** + * Format: date-time + * @description Expiry of the bank access token. The token references themselves are never returned by this API. + */ + token_expires_at: string | null; + /** Format: date-time */ + created_at: string; + /** + * Format: date-time + * @description American spelling here, unlike `status: "authorised"`; both mirror their own column names. Stamped in the same statement as the transition into `authorised`. + */ + authorized_at: string | null; + /** + * Format: date-time + * @description Mirror of the bank-side consent expiry, stamped when the consent is opened. + */ + expires_at: string | null; + /** Format: date-time */ + revoked_at: string | null; + /** Format: date-time */ + consumed_at: string | null; + metadata: { + [key: string]: unknown; + }; + }; + }; + }; + /** @description Not Found. No consent with this id in the caller's project. A consent belonging to another project in the same organization answers here too. */ + 404: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "not_found"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + }; + }; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/v1/ofb/sweeping/consents": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * List sweeping consents + * @description The project's sweeping consents, most recent first, as stored: the list does not call the provider. + * + * Requires the `consents:read` scope. + */ + get: { + parameters: { + query?: { + limit?: number; + consumer_id?: string; + status?: "pending" | "authorised" | "consumed" | "revoked" | "rejected" | "expired" | "canceled" | "failed"; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description OK */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + sweep_consents: { + /** @description `ofb_`-prefixed. Also the external id the provider keeps for this authorisation. */ + id: string; + consumer_id: string; + wallet_id: string | null; + /** @description The consumer's `pix-celcoin` funding source the sweep lands in. */ + funding_source_id: string | null; + /** @description The provider's id for the consumer's bank, as passed when the consent was opened. */ + participant_id: string; + /** @enum {string} */ + provider: "iniciador" | "celcoin-itp"; + /** + * @description `pending` until the consumer approves at their bank, then `authorised`. Terminal: `consumed`, `revoked` (after approval), `rejected` (refused or rejected before approval), `expired`, `canceled` (the provider canceled it, or it failed while being opened) and `failed` (a provider error). It only moves forward. + * @enum {string} + */ + status: "pending" | "authorised" | "consumed" | "revoked" | "rejected" | "expired" | "canceled" | "failed"; + /** @description Where the consumer approves the consent at their bank. Present while `pending` only; open it once. */ + authorisation_url: string | null; + /** @description The account the bank authorised the pulls from, as the provider reports it. Null until `authorised`. */ + debtor: { + ispb: string | null; + account_masked: string | null; + } | null; + /** @description The limits as the bank stated them on approval, in centavos. Null until `authorised`. */ + limits: { + total_minor: number | null; + per_transaction_minor: number | null; + } | null; + created_at: string; + authorized_at: string | null; + expires_at: string | null; + revoked_at: string | null; + consumed_at: string | null; + }[]; + }; + }; + }; + /** @description The query did not match the schema. */ + 400: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "invalid_query"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + }; + }; + put?: never; + /** + * Open a sweeping consent + * @description Opens a sweeping authorisation at the provider for a consumer's own bank account, to be pulled into their own Celcoin account (`funding_source_id`). The consumer approves it once at their bank, at `authorisation_url`; after that, pulls need no per-payment approval within the bank's limits. + * + * The consent is written before the provider is called. If the provider fails while it is being opened, the consent is answered as an error and kept as `canceled`. + * + * Requires the `consents:write` scope. Test projects only. + */ + post: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: { + content: { + "application/json": { + consumer_id: string; + wallet_id: string; + funding_source_id: string; + /** Format: uuid */ + participant_id: string; + /** + * @default [ + * "manual" + * ] + */ + triggers?: ("manual" | "automatic")[]; + /** @default {} */ + limits?: { + total_minor?: number; + per_transaction_minor?: number; + }; + /** Format: date-time */ + expires_at?: string; + /** Format: uri */ + redirect_url?: string; + }; + }; + }; + responses: { + /** @description OK */ + 201: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + /** @description `ofb_`-prefixed. Also the external id the provider keeps for this authorisation. */ + id: string; + consumer_id: string; + wallet_id: string | null; + /** @description The consumer's `pix-celcoin` funding source the sweep lands in. */ + funding_source_id: string | null; + /** @description The provider's id for the consumer's bank, as passed when the consent was opened. */ + participant_id: string; + /** @enum {string} */ + provider: "iniciador" | "celcoin-itp"; + /** + * @description `pending` until the consumer approves at their bank, then `authorised`. Terminal: `consumed`, `revoked` (after approval), `rejected` (refused or rejected before approval), `expired`, `canceled` (the provider canceled it, or it failed while being opened) and `failed` (a provider error). It only moves forward. + * @enum {string} + */ + status: "pending" | "authorised" | "consumed" | "revoked" | "rejected" | "expired" | "canceled" | "failed"; + /** @description Where the consumer approves the consent at their bank. Present while `pending` only; open it once. */ + authorisation_url: string | null; + /** @description The account the bank authorised the pulls from, as the provider reports it. Null until `authorised`. */ + debtor: { + ispb: string | null; + account_masked: string | null; + } | null; + /** @description The limits as the bank stated them on approval, in centavos. Null until `authorised`. */ + limits: { + total_minor: number | null; + per_transaction_minor: number | null; + } | null; + created_at: string; + authorized_at: string | null; + expires_at: string | null; + revoked_at: string | null; + consumed_at: string | null; + }; + }; + }; + /** @description The body did not match the schema. */ + 400: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "invalid_body"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description This project already holds an open sweeping consent for this consumer at this bank (`consent_active_for_consumer`), or another project of the organization does (`bank_consent_held_elsewhere`). */ + 409: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "consent_active_for_consumer" | "bank_consent_held_elsewhere"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description Not live, or the destination cannot receive a sweep. */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "ofb_not_live" | "sweep_destination_unresolved"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + request_id: string | null; + }; + }; + }; + /** @description The provider refused the call. `details.provider_code` is the provider's own error code; terminal for this request. */ + 502: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "sweep_provider_refused"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description The provider gave no definite answer (`sweep_provider_ambiguous`, retriable), the platform has no active trigger of a requested kind (`sweep_trigger_unavailable`), the deployment has no sweeping provider (`ofb_adapter_unavailable`) or another request holds this grant's lock (`consent_lock_timeout`, retriable). */ + 503: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "sweep_provider_ambiguous" | "sweep_trigger_unavailable" | "ofb_adapter_unavailable" | "consent_lock_timeout"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + }; + }; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/v1/ofb/sweeping/consents/{id}": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Read one sweeping consent + * @description While the consent is `pending` or `authorised`, the provider is read and the consent moves forward with it; a terminal consent is answered as stored. + * + * Requires the `consents:read` scope. + */ + get: { + parameters: { + query?: never; + header?: never; + path: { + /** @description `ofb_`-prefixed sweeping consent id. */ + id: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description OK */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + /** @description `ofb_`-prefixed. Also the external id the provider keeps for this authorisation. */ + id: string; + consumer_id: string; + wallet_id: string | null; + /** @description The consumer's `pix-celcoin` funding source the sweep lands in. */ + funding_source_id: string | null; + /** @description The provider's id for the consumer's bank, as passed when the consent was opened. */ + participant_id: string; + /** @enum {string} */ + provider: "iniciador" | "celcoin-itp"; + /** + * @description `pending` until the consumer approves at their bank, then `authorised`. Terminal: `consumed`, `revoked` (after approval), `rejected` (refused or rejected before approval), `expired`, `canceled` (the provider canceled it, or it failed while being opened) and `failed` (a provider error). It only moves forward. + * @enum {string} + */ + status: "pending" | "authorised" | "consumed" | "revoked" | "rejected" | "expired" | "canceled" | "failed"; + /** @description Where the consumer approves the consent at their bank. Present while `pending` only; open it once. */ + authorisation_url: string | null; + /** @description The account the bank authorised the pulls from, as the provider reports it. Null until `authorised`. */ + debtor: { + ispb: string | null; + account_masked: string | null; + } | null; + /** @description The limits as the bank stated them on approval, in centavos. Null until `authorised`. */ + limits: { + total_minor: number | null; + per_transaction_minor: number | null; + } | null; + created_at: string; + authorized_at: string | null; + expires_at: string | null; + revoked_at: string | null; + consumed_at: string | null; + }; + }; + }; + /** @description Not Found. No sweeping consent with this id in the caller's project. A data-sharing consent's id answers here too. */ + 404: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "not_found"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description The project is live. Sweeping serves test projects only, against the provider's sandbox (`details.reason` `live_not_enabled`). */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "ofb_not_live"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description The provider refused the call. `details.provider_code` is the provider's own error code; terminal for this request. */ + 502: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "sweep_provider_refused"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description No definite answer: the provider did not answer, answered a status this API does not map yet (`sweep_provider_ambiguous`, retriable with the same request), or the deployment cannot reach a sweeping provider (`ofb_adapter_unavailable`). */ + 503: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "sweep_provider_ambiguous" | "ofb_adapter_unavailable"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + }; + }; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/v1/ofb/sweeping/consents/{id}/revoke": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** + * Revoke a sweeping consent + * @description Reads the provider first, then rejects a consent still awaiting approval (`rejected`) or revokes an authorised one (`revoked`). + * + * Requires the `consents:write` scope. + */ + post: { + parameters: { + query?: never; + header?: never; + path: { + /** @description `ofb_`-prefixed sweeping consent id. */ + id: string; + }; + cookie?: never; + }; + requestBody?: { + content: { + "application/json": { + reason?: string; + }; + }; + }; + responses: { + /** @description OK */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + /** @description `ofb_`-prefixed. Also the external id the provider keeps for this authorisation. */ + id: string; + consumer_id: string; + wallet_id: string | null; + /** @description The consumer's `pix-celcoin` funding source the sweep lands in. */ + funding_source_id: string | null; + /** @description The provider's id for the consumer's bank, as passed when the consent was opened. */ + participant_id: string; + /** @enum {string} */ + provider: "iniciador" | "celcoin-itp"; + /** + * @description `pending` until the consumer approves at their bank, then `authorised`. Terminal: `consumed`, `revoked` (after approval), `rejected` (refused or rejected before approval), `expired`, `canceled` (the provider canceled it, or it failed while being opened) and `failed` (a provider error). It only moves forward. + * @enum {string} + */ + status: "pending" | "authorised" | "consumed" | "revoked" | "rejected" | "expired" | "canceled" | "failed"; + /** @description Where the consumer approves the consent at their bank. Present while `pending` only; open it once. */ + authorisation_url: string | null; + /** @description The account the bank authorised the pulls from, as the provider reports it. Null until `authorised`. */ + debtor: { + ispb: string | null; + account_masked: string | null; + } | null; + /** @description The limits as the bank stated them on approval, in centavos. Null until `authorised`. */ + limits: { + total_minor: number | null; + per_transaction_minor: number | null; + } | null; + created_at: string; + authorized_at: string | null; + expires_at: string | null; + revoked_at: string | null; + consumed_at: string | null; + }; + }; + }; + /** @description The body did not match the schema. */ + 400: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "invalid_body"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description Not Found. No sweeping consent with this id in the caller's project. A data-sharing consent's id answers here too. */ + 404: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "not_found"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description The consent is already terminal, or is still being opened at the provider (`details.in_flight`). */ + 409: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "illegal_transition"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description The project is live. Sweeping serves test projects only, against the provider's sandbox (`details.reason` `live_not_enabled`). */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "ofb_not_live"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description The provider refused the call. `details.provider_code` is the provider's own error code; terminal for this request. */ + 502: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "sweep_provider_refused"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description No definite answer: the provider did not answer, answered a status this API does not map yet (`sweep_provider_ambiguous`, retriable with the same request), or the deployment cannot reach a sweeping provider (`ofb_adapter_unavailable`). */ + 503: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "sweep_provider_ambiguous" | "ofb_adapter_unavailable"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + }; + }; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/v1/ofb/sweeping/pulls": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * List sweeping pulls + * @description The project's sweeping pulls, most recent first, as stored: the list does not call the provider. + * + * Requires the `wallets:read` scope. + */ + get: { + parameters: { + query?: { + limit?: number; + consent_id?: string; + status?: "pending" | "settling" | "completed" | "rejected" | "expired" | "canceled" | "failed" | "unknown"; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description OK */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + sweep_pulls: { + /** @description `swp_`-prefixed. */ + id: string; + /** @description The `ofb_`-prefixed sweeping consent the pull ran under. */ + consent_id: string; + consumer_id: string; + wallet_id: string; + /** @enum {string} */ + provider: "iniciador" | "celcoin-itp"; + /** @description In centavos. */ + amount_minor: number; + currency: string; + /** + * @description `pending` while the provider processes it, `settling` once the Pix is on its way, then a terminal `completed`, `rejected`, `expired`, `canceled` (the provider refused it when it was sent) or `failed` (the provider reported an error). `unknown`: no definite answer yet; retry the create with the same `Idempotency-Key`. It only moves forward. + * @enum {string} + */ + status: "pending" | "settling" | "completed" | "rejected" | "expired" | "canceled" | "failed" | "unknown"; + /** @description The provider's own status, as it reported it. On a read, a status this API does not map yet is shown here while `status` stays as stored. */ + provider_status: string | null; + /** @description The Pix end-to-end id, once the provider reports it. */ + end_to_end_id: string | null; + /** @description The provider's error code, or why the pull has no definite answer. */ + error_code: string | null; + /** @description Always `false` for now: a pull `completed` at the provider is not yet credited in the wallet. */ + credited: boolean; + /** @description `true` when the answer is a pull an earlier request with the same key created. */ + replayed: boolean; + created_at: string; + updated_at: string; + }[]; + }; + }; + }; + /** @description The query did not match the schema. */ + 400: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "invalid_query"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description The key does not carry the `wallets:read` scope. Bare body; nothing was read or written. */ + 403: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + /** @enum {string} */ + error: "forbidden"; + message: string; + /** @enum {number} */ + status: 403; + }; + }; + }; + }; + }; + put?: never; + /** + * Pull Pix under a sweeping consent + * @description Pulls `amount_minor` from the consumer's bank account into their own Celcoin account, under an `authorised` sweeping consent opened with the `automatic` trigger. No user is present: the pull needs no approval at the bank within the limits the bank set on the consent. + * + * The consent is read at the provider first, and the amount is checked against the bank's per-transaction limit before the pull is sent. The pull is written before the provider is called. + * + * A pull moves money, so the `Idempotency-Key` header is required. The same key with the same body answers the pull the first request created, never a second one; when that request got no definite answer, the retry looks the pull up at the provider and sends it again only when the provider has none. + * + * Requires the `wallets:admin` scope. Test projects only. + */ + post: { + parameters: { + query?: never; + header: { + /** @description Required. Send the same key on every retry of the same pull. */ + "Idempotency-Key": string; + }; + path?: never; + cookie?: never; + }; + requestBody?: { + content: { + "application/json": { + consent_id: string; + amount_minor: number; + risk_signals: { + /** @enum {string} */ + type: "AUTOMATIC"; + /** Format: date-time */ + last_login_date_time: string; + }; + }; + }; + }; + responses: { + /** @description A replay: the same `Idempotency-Key` and body as an earlier request, answered with the pull it created (`replayed: true`). */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + /** @description `swp_`-prefixed. */ + id: string; + /** @description The `ofb_`-prefixed sweeping consent the pull ran under. */ + consent_id: string; + consumer_id: string; + wallet_id: string; + /** @enum {string} */ + provider: "iniciador" | "celcoin-itp"; + /** @description In centavos. */ + amount_minor: number; + currency: string; + /** + * @description `pending` while the provider processes it, `settling` once the Pix is on its way, then a terminal `completed`, `rejected`, `expired`, `canceled` (the provider refused it when it was sent) or `failed` (the provider reported an error). `unknown`: no definite answer yet; retry the create with the same `Idempotency-Key`. It only moves forward. + * @enum {string} + */ + status: "pending" | "settling" | "completed" | "rejected" | "expired" | "canceled" | "failed" | "unknown"; + /** @description The provider's own status, as it reported it. On a read, a status this API does not map yet is shown here while `status` stays as stored. */ + provider_status: string | null; + /** @description The Pix end-to-end id, once the provider reports it. */ + end_to_end_id: string | null; + /** @description The provider's error code, or why the pull has no definite answer. */ + error_code: string | null; + /** @description Always `false` for now: a pull `completed` at the provider is not yet credited in the wallet. */ + credited: boolean; + /** @description `true` when the answer is a pull an earlier request with the same key created. */ + replayed: boolean; + created_at: string; + updated_at: string; + }; + }; + }; + /** @description The pull was written and sent to the provider. */ + 202: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + /** @description `swp_`-prefixed. */ + id: string; + /** @description The `ofb_`-prefixed sweeping consent the pull ran under. */ + consent_id: string; + consumer_id: string; + wallet_id: string; + /** @enum {string} */ + provider: "iniciador" | "celcoin-itp"; + /** @description In centavos. */ + amount_minor: number; + currency: string; + /** + * @description `pending` while the provider processes it, `settling` once the Pix is on its way, then a terminal `completed`, `rejected`, `expired`, `canceled` (the provider refused it when it was sent) or `failed` (the provider reported an error). `unknown`: no definite answer yet; retry the create with the same `Idempotency-Key`. It only moves forward. + * @enum {string} + */ + status: "pending" | "settling" | "completed" | "rejected" | "expired" | "canceled" | "failed" | "unknown"; + /** @description The provider's own status, as it reported it. On a read, a status this API does not map yet is shown here while `status` stays as stored. */ + provider_status: string | null; + /** @description The Pix end-to-end id, once the provider reports it. */ + end_to_end_id: string | null; + /** @description The provider's error code, or why the pull has no definite answer. */ + error_code: string | null; + /** @description Always `false` for now: a pull `completed` at the provider is not yet credited in the wallet. */ + credited: boolean; + /** @description `true` when the answer is a pull an earlier request with the same key created. */ + replayed: boolean; + created_at: string; + updated_at: string; + }; + }; + }; + /** @description The body did not match the schema, the `Idempotency-Key` header is missing (`sweep_idempotency_key_required`) or longer than 255 characters (`invalid_idempotency_key`). */ + 400: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "invalid_body" | "sweep_idempotency_key_required" | "invalid_idempotency_key"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description The key does not carry the `wallets:admin` scope. Bare body; nothing was read or written. */ + 403: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + /** @enum {string} */ + error: "forbidden"; + message: string; + /** @enum {number} */ + status: 403; + }; + }; + }; + /** @description Not Found. No sweeping consent with this id in the caller's project. */ + 404: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "not_found"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description The consent cannot carry a pull now (`sweep_consent_not_authorised`), the key already created a pull with another consent or amount (`idempotency_key_conflict`), or another request with this key is still sending it (`sweep_pull_in_flight`, retriable). */ + 409: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "sweep_consent_not_authorised" | "idempotency_key_conflict" | "sweep_pull_in_flight"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description Not live, above one of the bank's limits (`details.limit`: `per_transaction`, or `total` counted over the consent's earlier pulls that may move money; `details.reason` `limit_unreadable` when a limit exists and cannot be read), or the consent has no automatic trigger. */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "ofb_not_live" | "sweep_limit_exceeded" | "sweep_trigger_not_on_consent"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + request_id: string | null; + }; + }; + }; + /** @description The provider refused the pull. `details.provider_code` is the provider's own error code; the pull is kept as `canceled` and terminal for this key. */ + 502: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "sweep_provider_refused"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description No definite answer from the provider (`sweep_provider_ambiguous`): the pull is kept as `unknown`; retry the same request with the same `Idempotency-Key`. A refused re-send of a pull whose first answer was lost is answered this way too (`details.resend_refused`). Or the deployment cannot reach a sweeping provider (`ofb_adapter_unavailable`). */ + 503: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "sweep_provider_ambiguous" | "ofb_adapter_unavailable"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + }; + }; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/v1/ofb/sweeping/pulls/{id}": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Read one sweeping pull + * @description While the pull is not terminal, the provider is read and the pull moves forward with it; a terminal pull is answered as stored. A read never sends a pull again: that is the create retry's job. + * + * Requires the `wallets:read` scope. + */ + get: { + parameters: { + query?: never; + header?: never; + path: { + /** @description `swp_`-prefixed sweeping pull id. */ + id: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description OK */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + /** @description `swp_`-prefixed. */ + id: string; + /** @description The `ofb_`-prefixed sweeping consent the pull ran under. */ + consent_id: string; + consumer_id: string; + wallet_id: string; + /** @enum {string} */ + provider: "iniciador" | "celcoin-itp"; + /** @description In centavos. */ + amount_minor: number; + currency: string; + /** + * @description `pending` while the provider processes it, `settling` once the Pix is on its way, then a terminal `completed`, `rejected`, `expired`, `canceled` (the provider refused it when it was sent) or `failed` (the provider reported an error). `unknown`: no definite answer yet; retry the create with the same `Idempotency-Key`. It only moves forward. + * @enum {string} + */ + status: "pending" | "settling" | "completed" | "rejected" | "expired" | "canceled" | "failed" | "unknown"; + /** @description The provider's own status, as it reported it. On a read, a status this API does not map yet is shown here while `status` stays as stored. */ + provider_status: string | null; + /** @description The Pix end-to-end id, once the provider reports it. */ + end_to_end_id: string | null; + /** @description The provider's error code, or why the pull has no definite answer. */ + error_code: string | null; + /** @description Always `false` for now: a pull `completed` at the provider is not yet credited in the wallet. */ + credited: boolean; + /** @description `true` when the answer is a pull an earlier request with the same key created. */ + replayed: boolean; + created_at: string; + updated_at: string; + }; + }; + }; + /** @description The key does not carry the `wallets:read` scope. Bare body; nothing was read or written. */ + 403: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + /** @enum {string} */ + error: "forbidden"; + message: string; + /** @enum {number} */ + status: 403; + }; + }; + }; + /** @description Not Found. No sweeping pull with this id in the caller's project. */ + 404: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "not_found"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description The project is live. Sweeping serves test projects only, against the provider's sandbox (`details.reason` `live_not_enabled`). */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "ofb_not_live"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description The provider refused the read. */ + 502: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "sweep_provider_refused"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description No definite answer from the provider (`sweep_provider_ambiguous`, retriable), or the deployment cannot reach a sweeping provider (`ofb_adapter_unavailable`). */ + 503: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "sweep_provider_ambiguous" | "ofb_adapter_unavailable"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + }; + }; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/v1/ofb/jsr/enrollments": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * List JSR enrollments + * @description The project's enrollments, most recent first, as stored. + * + * Requires the `consents:read` scope. + */ + get: { + parameters: { + query?: { + limit?: number; + consumer_id?: string; + status?: "pending" | "authorised" | "revoked" | "rejected" | "expired" | "canceled"; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description OK */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + jsr_enrollments: { + /** @description `ofb_`-prefixed. */ + id: string; + consumer_id: string; + wallet_id: string | null; + funding_source_id: string | null; + /** @description The bank, as the provider's participant id. */ + participant_id: string; + /** @enum {string} */ + provider: "iniciador"; + /** + * @description `pending` until the person registers the passkey on the hosted page, then `authorised`; terminal `rejected` (not registered in its window, or revoked before it was), `revoked`, `expired`, or `canceled` (the provider failed while it was being opened). It only moves forward. + * @enum {string} + */ + status: "pending" | "authorised" | "revoked" | "rejected" | "expired" | "canceled"; + /** @description The bank account the enrollment is bound to, once authorised. */ + debtor: { + ispb: string | null; + account_masked: string | null; + } | null; + /** @description The bank's per-transaction limit in centavos, as the provider reports it. The bank enforces it. */ + bank_transaction_limit_minor: number | null; + created_at: string; + authorized_at: string | null; + expires_at: string | null; + revoked_at: string | null; + }[]; + }; + }; + }; + /** @description The query did not match the schema. */ + 400: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "invalid_query"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description The key does not carry the `consents:read` scope. Bare body; nothing was read or written. */ + 403: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + /** @enum {string} */ + error: "forbidden"; + message: string; + /** @enum {number} */ + status: 403; + }; + }; + }; + }; + }; + put?: never; + /** + * Register a passkey for Pix com biometria + * @description Opens an enrollment at the bank for the consumer's own account and answers `approval_url`, the hosted page where the person registers a passkey on their device. The page expires about a minute after it is made: call this only with the person about to open it, and open a new enrollment if it expired (the old one ends `rejected` on its own). It carries a credential of its own: hand it to the person and to no log. The API keeps it nowhere. + * + * Requires the `consents:write` scope. Test projects only. + */ + post: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: { + content: { + "application/json": { + consumer_id: string; + wallet_id: string; + funding_source_id: string; + /** Format: uuid */ + participant_id: string; + device_context: { + os_version: string; + user_time_zone_offset: string; + language: string; + screen_dimensions: { + width: number; + height: number; + }; + /** Format: date */ + account_tenure: string; + }; + }; + }; + }; + responses: { + /** @description The enrollment, `pending`, with the page to open now. */ + 201: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + /** @description `ofb_`-prefixed. */ + id: string; + consumer_id: string; + wallet_id: string | null; + funding_source_id: string | null; + /** @description The bank, as the provider's participant id. */ + participant_id: string; + /** @enum {string} */ + provider: "iniciador"; + /** + * @description `pending` until the person registers the passkey on the hosted page, then `authorised`; terminal `rejected` (not registered in its window, or revoked before it was), `revoked`, `expired`, or `canceled` (the provider failed while it was being opened). It only moves forward. + * @enum {string} + */ + status: "pending" | "authorised" | "revoked" | "rejected" | "expired" | "canceled"; + /** @description The bank account the enrollment is bound to, once authorised. */ + debtor: { + ispb: string | null; + account_masked: string | null; + } | null; + /** @description The bank's per-transaction limit in centavos, as the provider reports it. The bank enforces it. */ + bank_transaction_limit_minor: number | null; + created_at: string; + authorized_at: string | null; + expires_at: string | null; + revoked_at: string | null; + /** @description It carries a credential of its own: hand it to the person and to no log. The API keeps it nowhere. */ + approval_url: string; + }; + }; + }; + /** @description The body did not match the schema. */ + 400: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "invalid_body"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description The key does not carry the `consents:write` scope. Bare body; nothing was read or written. */ + 403: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + /** @enum {string} */ + error: "forbidden"; + message: string; + /** @enum {number} */ + status: 403; + }; + }; + }; + /** @description Not live, or the destination cannot receive a payment (`jsr_destination_unresolved`, `details.reason`). */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "ofb_not_live" | "jsr_destination_unresolved"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + request_id: string | null; + }; + }; + }; + /** @description The provider refused (`jsr_provider_refused`). `details.provider_code` is its own code; its free text is never relayed. */ + 502: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "jsr_provider_refused"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description No definite answer from the provider (`jsr_provider_ambiguous`), or the deployment has no JSR provider credentials (`ofb_adapter_unavailable`). */ + 503: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "jsr_provider_ambiguous" | "ofb_adapter_unavailable"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + }; + }; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/v1/ofb/jsr/enrollments/{id}": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Read one JSR enrollment + * @description While not terminal, the provider is read and the enrollment moves forward with it. + * + * Requires the `consents:read` scope. + */ + get: { + parameters: { + query?: never; + header?: never; + path: { + id: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description OK */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + /** @description `ofb_`-prefixed. */ + id: string; + consumer_id: string; + wallet_id: string | null; + funding_source_id: string | null; + /** @description The bank, as the provider's participant id. */ + participant_id: string; + /** @enum {string} */ + provider: "iniciador"; + /** + * @description `pending` until the person registers the passkey on the hosted page, then `authorised`; terminal `rejected` (not registered in its window, or revoked before it was), `revoked`, `expired`, or `canceled` (the provider failed while it was being opened). It only moves forward. + * @enum {string} + */ + status: "pending" | "authorised" | "revoked" | "rejected" | "expired" | "canceled"; + /** @description The bank account the enrollment is bound to, once authorised. */ + debtor: { + ispb: string | null; + account_masked: string | null; + } | null; + /** @description The bank's per-transaction limit in centavos, as the provider reports it. The bank enforces it. */ + bank_transaction_limit_minor: number | null; + created_at: string; + authorized_at: string | null; + expires_at: string | null; + revoked_at: string | null; + }; + }; + }; + /** @description The key does not carry the `consents:read` scope. Bare body; nothing was read or written. */ + 403: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + /** @enum {string} */ + error: "forbidden"; + message: string; + /** @enum {number} */ + status: 403; + }; + }; + }; + /** @description No JSR enrollment with this id in the caller's project. */ + 404: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "not_found"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description The project is live. JSR serves test projects only, against the provider's sandbox (`details.reason` `live_not_enabled`). */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "ofb_not_live"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description The provider refused (`jsr_provider_refused`). `details.provider_code` is its own code; its free text is never relayed. */ + 502: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "jsr_provider_refused"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description No definite answer from the provider (`jsr_provider_ambiguous`), or the deployment has no JSR provider credentials (`ofb_adapter_unavailable`). */ + 503: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "jsr_provider_ambiguous" | "ofb_adapter_unavailable"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + }; + }; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/v1/ofb/jsr/enrollments/{id}/revoke": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** + * Revoke a JSR enrollment + * @description Revokes the enrollment at the provider, then here: `revoked`, or `rejected` for one never authorised. Deleting the passkey on the device does not revoke it. + * + * Requires the `consents:write` scope. + */ + post: { + parameters: { + query?: never; + header?: never; + path: { + id: string; + }; + cookie?: never; + }; + requestBody?: { + content: { + "application/json": { + /** @description Recorded on this API's own consent event. Not sent to the provider: no reason field of its revoke is known. */ + reason?: string; + }; + }; + }; + responses: { + /** @description OK */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + /** @description `ofb_`-prefixed. */ + id: string; + consumer_id: string; + wallet_id: string | null; + funding_source_id: string | null; + /** @description The bank, as the provider's participant id. */ + participant_id: string; + /** @enum {string} */ + provider: "iniciador"; + /** + * @description `pending` until the person registers the passkey on the hosted page, then `authorised`; terminal `rejected` (not registered in its window, or revoked before it was), `revoked`, `expired`, or `canceled` (the provider failed while it was being opened). It only moves forward. + * @enum {string} + */ + status: "pending" | "authorised" | "revoked" | "rejected" | "expired" | "canceled"; + /** @description The bank account the enrollment is bound to, once authorised. */ + debtor: { + ispb: string | null; + account_masked: string | null; + } | null; + /** @description The bank's per-transaction limit in centavos, as the provider reports it. The bank enforces it. */ + bank_transaction_limit_minor: number | null; + created_at: string; + authorized_at: string | null; + expires_at: string | null; + revoked_at: string | null; + }; + }; + }; + /** @description The body did not match the schema. */ + 400: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "invalid_body"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description The key does not carry the `consents:write` scope. Bare body; nothing was read or written. */ + 403: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + /** @enum {string} */ + error: "forbidden"; + message: string; + /** @enum {number} */ + status: 403; + }; + }; + }; + /** @description No JSR enrollment with this id in the caller's project. */ + 404: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "not_found"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description Terminal already, or still being opened (`details.in_flight`). */ + 409: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "illegal_transition"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description The project is live. JSR serves test projects only, against the provider's sandbox (`details.reason` `live_not_enabled`). */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "ofb_not_live"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description The provider refused (`jsr_provider_refused`). `details.provider_code` is its own code; its free text is never relayed. */ + 502: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "jsr_provider_refused"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description No definite answer from the provider (`jsr_provider_ambiguous`), or the deployment has no JSR provider credentials (`ofb_adapter_unavailable`). */ + 503: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "jsr_provider_ambiguous" | "ofb_adapter_unavailable"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + }; + }; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/v1/ofb/jsr/payments": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * List JSR payments + * @description The project's JSR payments, most recent first, as stored; no signing page. + * + * Requires the `wallets:read` scope. + */ + get: { + parameters: { + query?: { + limit?: number; + enrollment_id?: string; + status?: "pending" | "settling" | "completed" | "rejected" | "expired" | "canceled" | "failed" | "unknown"; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description OK */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + jsr_payments: { + /** @description `swp_`-prefixed: a JSR payment is a pull, credited as one. */ + id: string; + enrollment_id: string; + consumer_id: string; + wallet_id: string; + /** @enum {string} */ + provider: "iniciador"; + /** @description In centavos. */ + amount_minor: number; + currency: string; + /** + * @description `pending` until the person signs it and the bank settles it, then `completed`; `rejected` when nobody signed it in time (`signature_timed_out`) or the bank refused it; `canceled` when the provider refused the create. `unknown`: no definite answer, or bound to another enrollment (`needs_human`). + * @enum {string} + */ + status: "pending" | "settling" | "completed" | "rejected" | "expired" | "canceled" | "failed" | "unknown"; + provider_status: string | null; + /** @description The Pix end-to-end id. Assigned at create, so a rejected payment has one too: only `completed` moved money. */ + end_to_end_id: string | null; + error_code: string | null; + /** @description The bank ended it because the person did not sign within about ten minutes (TIMEOUT_CONSENTIMENTO). */ + signature_timed_out: boolean; + /** @description A person must check it at the provider: it is never sent again. */ + needs_human: boolean; + /** @description The hosted page where the person signs this payment with the passkey, while it waits for that. Handed only to a key with `wallets:admin`. It carries a credential of its own: hand it to the person and to no log. The API keeps it nowhere. */ + approval_url: string | null; + /** @description The payment waits for a signature, and the key reading it lacks `wallets:admin`: the signing page authorises a debit, so it is not handed to a read-only key. */ + approval_url_withheld: boolean; + /** @description Always `false` for now: a completed payment is not yet credited in the wallet. */ + credited: boolean; + replayed: boolean; + created_at: string; + updated_at: string; + }[]; + }; + }; + }; + /** @description The query did not match the schema. */ + 400: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "invalid_query"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description The key does not carry the `wallets:read` scope. Bare body; nothing was read or written. */ + 403: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + /** @enum {string} */ + error: "forbidden"; + message: string; + /** @enum {number} */ + status: 403; + }; + }; + }; + }; + }; + put?: never; + /** + * Pay from the consumer's bank with Pix com biometria + * @description Creates a Pix from the consumer's bank account into their own Celcoin account under an `authorised` enrollment, and answers `approval_url`, the hosted page where the person signs it with the passkey. Unsigned, the bank ends it `rejected` in about ten minutes (`signature_timed_out`); it is never sent again, and a new approval is a new payment with a new key. * - * THE BANK IS CALLED BEFORE THE ROW IS WRITTEN, and that ordering is visible in the failure modes below: every refusal that arrives after the bank call leaves a bank-side consent with no row of ours pointing at it. Retrying opens another one. + * The provider binds a payment to the holder's newest authorised enrollment at that bank. A payment is refused before it is sent unless the named enrollment is that one (`jsr_enrollment_not_newest`), and one bound to another anyway is kept with `needs_human`, its page withheld (`jsr_enrollment_mismatch`). * - * One open consent per consumer per bank per organization. A sibling project in your organization holding an open consent for this consumer at this bank is refused, and the refusal is not something a retry clears. + * The `Idempotency-Key` header is required. It carries a credential of its own: hand it to the person and to no log. The API keeps it nowhere. * - * On 201 the consent is `pending`, and `authorisation_url`, `bank_consent_id` and `expires_at` are all set: the adapter's result declares them non-nullable and the INSERT writes all three. Send the consumer to `authorisation_url`, then post the code they come back with to the callback operation. + * Requires the `wallets:admin` scope. Test projects only. */ post: { parameters: { query?: never; - header?: never; + header: { + /** @description Required. The same key on every retry of the same payment. */ + "Idempotency-Key": string; + }; path?: never; cookie?: never; }; requestBody?: { content: { "application/json": { - bank_id: string; - consumer_id: string; - scopes: string[]; - /** - * Format: uri - * @description Where the bank returns the consumer after authorisation. You compose it and you host it. - */ - redirect_url: string; - /** @description Binds the consent to a wallet, so the statements it ingests carry that wallet. */ - wallet_id?: string; + enrollment_id: string; + amount_minor: number; + description?: string; }; }; }; responses: { - /** @description Created. The consent is `pending` and `authorisation_url` is set. */ - 201: { + /** @description A replay of the payment the same key created (`replayed: true`). */ + 200: { headers: { [name: string]: unknown; }; content: { "application/json": { + /** @description `swp_`-prefixed: a JSR payment is a pull, credited as one. */ id: string; - /** @description Lowercase kebab-case, for example `itau` or `bb`. */ - bank_id: string; + enrollment_id: string; consumer_id: string; - /** @description Set when the consent was bound to a wallet at initiation; null when it was not. */ - wallet_id: string | null; + wallet_id: string; /** @enum {string} */ - status: "pending" | "authorised" | "revoked" | "expired" | "consumed"; - scopes: string[]; - /** @description The bank's own identifier for the consent. Null until the bank issues one. */ - bank_consent_id: string | null; - /** @description Where the consumer authorises the consent. This is the URL to send them to. */ - authorisation_url: string | null; - /** Format: date-time */ - token_expires_at: string | null; - /** Format: date-time */ - created_at: string; + provider: "iniciador"; + /** @description In centavos. */ + amount_minor: number; + currency: string; /** - * Format: date-time - * @description Spelled with a z, unlike `authorised` in `status`. Both spellings are column names, not typos. + * @description `pending` until the person signs it and the bank settles it, then `completed`; `rejected` when nobody signed it in time (`signature_timed_out`) or the bank refused it; `canceled` when the provider refused the create. `unknown`: no definite answer, or bound to another enrollment (`needs_human`). + * @enum {string} */ - authorized_at: string | null; + status: "pending" | "settling" | "completed" | "rejected" | "expired" | "canceled" | "failed" | "unknown"; + provider_status: string | null; + /** @description The Pix end-to-end id. Assigned at create, so a rejected payment has one too: only `completed` moved money. */ + end_to_end_id: string | null; + error_code: string | null; + /** @description The bank ended it because the person did not sign within about ten minutes (TIMEOUT_CONSENTIMENTO). */ + signature_timed_out: boolean; + /** @description A person must check it at the provider: it is never sent again. */ + needs_human: boolean; + /** @description The hosted page where the person signs this payment with the passkey, while it waits for that. Handed only to a key with `wallets:admin`. It carries a credential of its own: hand it to the person and to no log. The API keeps it nowhere. */ + approval_url: string | null; + /** @description The payment waits for a signature, and the key reading it lacks `wallets:admin`: the signing page authorises a debit, so it is not handed to a read-only key. */ + approval_url_withheld: boolean; + /** @description Always `false` for now: a completed payment is not yet credited in the wallet. */ + credited: boolean; + replayed: boolean; + created_at: string; + updated_at: string; + }; + }; + }; + /** @description The payment was written and created at the provider; the person signs it at `approval_url`. */ + 202: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + /** @description `swp_`-prefixed: a JSR payment is a pull, credited as one. */ + id: string; + enrollment_id: string; + consumer_id: string; + wallet_id: string; + /** @enum {string} */ + provider: "iniciador"; + /** @description In centavos. */ + amount_minor: number; + currency: string; /** - * Format: date-time - * @description Mirrors the bank-side consent expiry, as the bank reported it at initiation. + * @description `pending` until the person signs it and the bank settles it, then `completed`; `rejected` when nobody signed it in time (`signature_timed_out`) or the bank refused it; `canceled` when the provider refused the create. `unknown`: no definite answer, or bound to another enrollment (`needs_human`). + * @enum {string} */ - expires_at: string | null; - /** Format: date-time */ - revoked_at: string | null; - /** Format: date-time */ - consumed_at: string | null; - metadata: { - [key: string]: unknown; - }; + status: "pending" | "settling" | "completed" | "rejected" | "expired" | "canceled" | "failed" | "unknown"; + provider_status: string | null; + /** @description The Pix end-to-end id. Assigned at create, so a rejected payment has one too: only `completed` moved money. */ + end_to_end_id: string | null; + error_code: string | null; + /** @description The bank ended it because the person did not sign within about ten minutes (TIMEOUT_CONSENTIMENTO). */ + signature_timed_out: boolean; + /** @description A person must check it at the provider: it is never sent again. */ + needs_human: boolean; + /** @description The hosted page where the person signs this payment with the passkey, while it waits for that. Handed only to a key with `wallets:admin`. It carries a credential of its own: hand it to the person and to no log. The API keeps it nowhere. */ + approval_url: string | null; + /** @description The payment waits for a signature, and the key reading it lacks `wallets:admin`: the signing page authorises a debit, so it is not handed to a read-only key. */ + approval_url_withheld: boolean; + /** @description Always `false` for now: a completed payment is not yet credited in the wallet. */ + credited: boolean; + replayed: boolean; + created_at: string; + updated_at: string; }; }; }; - /** @description The body did not match the schema. `details.issues` carries the Zod issues. */ + /** @description The body did not match the schema, or the `Idempotency-Key` header is missing (`jsr_idempotency_key_required`) or too long (`invalid_idempotency_key`). */ 400: { headers: { [name: string]: unknown; @@ -7166,7 +9914,7 @@ export interface paths { "application/json": { error: { /** @enum {string} */ - code: "invalid_body"; + code: "invalid_body" | "jsr_idempotency_key_required" | "invalid_idempotency_key"; message: string; details?: { [key: string]: unknown; @@ -7177,14 +9925,23 @@ export interface paths { }; }; }; - /** - * @description `bank_consent_held_elsewhere` when another project in this organization holds an open (`pending` or `authorised`) consent for this consumer at this bank. `details.remediation` says what to do and `details.retriable` is false: one project's bank grant is never shared with another, so re-sending this request unchanged will not clear it. - * - * `consent_active_for_consumer` when YOUR OWN project already holds one that is still inside its validity window. Revoke it first. One past its window does not refuse: it is moved to `expired` as the new consent is created. - * - * `db_error` when the consent could not be persisted for any other reason. The cause is in our logs under the request id and is deliberately not in this body, because the driver's own message names another project's key values. - */ - 409: { + /** @description The key does not carry the `wallets:admin` scope. Bare body; nothing was read or written. */ + 403: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + /** @enum {string} */ + error: "forbidden"; + message: string; + /** @enum {number} */ + status: 403; + }; + }; + }; + /** @description No JSR enrollment with this id in the caller's project. */ + 404: { headers: { [name: string]: unknown; }; @@ -7192,7 +9949,7 @@ export interface paths { "application/json": { error: { /** @enum {string} */ - code: "bank_consent_held_elsewhere" | "consent_active_for_consumer" | "db_error"; + code: "not_found"; message: string; details?: { [key: string]: unknown; @@ -7203,8 +9960,8 @@ export interface paths { }; }; }; - /** @description `ofb_not_live`: this is a LIVE project and the deployment has no real Open Finance adapter, only the stub, which serves test projects. TERMINAL for this project: use a test project. Nothing was written and no bank was contacted. */ - 422: { + /** @description The enrollment cannot carry a payment (`jsr_enrollment_not_authorised`), is not the one the provider would bind it to (`jsr_enrollment_not_newest`), the provider bound it to another (`jsr_enrollment_mismatch`, `needs_human`), the key created another payment (`idempotency_key_conflict`), is still sending it (`jsr_payment_in_flight`), or sent it with no definite answer (`jsr_payment_unresolved`, `needs_human`). */ + 409: { headers: { [name: string]: unknown; }; @@ -7212,7 +9969,7 @@ export interface paths { "application/json": { error: { /** @enum {string} */ - code: "ofb_not_live"; + code: "jsr_enrollment_not_authorised" | "jsr_enrollment_not_newest" | "jsr_enrollment_mismatch" | "idempotency_key_conflict" | "jsr_payment_in_flight" | "jsr_payment_unresolved"; message: string; details?: { [key: string]: unknown; @@ -7223,8 +9980,8 @@ export interface paths { }; }; }; - /** @description `consent_disappeared`: the row was written and could not be read back. Do not retry blind; both the row and the bank-side consent may exist. */ - 500: { + /** @description Not live, above a limit (`jsr_limit_exceeded`: the test ceiling of R$ 100 per payment and R$ 1.000 per enrollment, `details.source` `platform_test`, or the bank's per-transaction limit, `bank`), or the destination cannot receive it (`jsr_destination_unresolved`). */ + 422: { headers: { [name: string]: unknown; }; @@ -7232,18 +9989,17 @@ export interface paths { "application/json": { error: { /** @enum {string} */ - code: "consent_disappeared"; + code: "ofb_not_live" | "jsr_limit_exceeded" | "jsr_destination_unresolved"; message: string; details?: { [key: string]: unknown; }; }; - /** @description Echoes the `X-Request-Id` header when the request carried one. */ request_id: string | null; }; }; }; - /** @description The bank refused the request or could not be reached, before anything was written. The message is the adapter's own. */ + /** @description The provider refused (`jsr_provider_refused`). `details.provider_code` is its own code; its free text is never relayed. */ 502: { headers: { [name: string]: unknown; @@ -7252,7 +10008,7 @@ export interface paths { "application/json": { error: { /** @enum {string} */ - code: "adapter_error"; + code: "jsr_provider_refused"; message: string; details?: { [key: string]: unknown; @@ -7263,11 +10019,7 @@ export interface paths { }; }; }; - /** - * @description `consent_lock_timeout`: another request is issuing a consent for this consumer at this bank and the wait ended without an answer, so NOTHING WAS DECIDED. We do not know whether a sibling holds the grant, and saying so is why this is not the 409. `details.retriable` is true. No consent row was created; a bank-side consent was, and is orphaned. - * - * `ofb_adapter_unavailable`: the Open Finance adapter this deployment selects cannot serve (`details.reason`: `missing_credentials`, `not_implemented` or `unknown_mode`). Ours to fix, not yours; nothing was written and no bank was contacted. - */ + /** @description No definite answer from the provider (`jsr_provider_ambiguous`), or the deployment has no JSR provider credentials (`ofb_adapter_unavailable`). */ 503: { headers: { [name: string]: unknown; @@ -7276,7 +10028,7 @@ export interface paths { "application/json": { error: { /** @enum {string} */ - code: "consent_lock_timeout" | "ofb_adapter_unavailable"; + code: "jsr_provider_ambiguous" | "ofb_adapter_unavailable"; message: string; details?: { [key: string]: unknown; @@ -7295,7 +10047,7 @@ export interface paths { patch?: never; trace?: never; }; - "/v1/bank-consents/{id}": { + "/v1/ofb/jsr/payments/{id}": { parameters: { query?: never; header?: never; @@ -7303,21 +10055,16 @@ export interface paths { cookie?: never; }; /** - * Read one bank consent - * @description The body is the consent projection: the same shape `POST /v1/bank-consents` returns on create, and the same one the callback and revoke transitions return. The refresh-statement operation in this family is the exception, answering with a run summary rather than a consent. - * - * Resolution is scoped to the organization AND the project the credential authenticates for. A consent held by a SIBLING project in the same organization answers 404 here, indistinguishable from one that never existed. That is deliberate rather than incidental: one project's upstream bank grant is never readable from another. - * - * No token material leaves. The row carries references to the bank's access and refresh tokens; they are dropped before the body is built, and `token_expires_at` is the only thing about the bank token that is returned. + * Read one JSR payment + * @description While not terminal, the provider is read and the payment moves forward with it. While the payment waits for the signature, `approval_url` is the signing page again for a key with `wallets:admin`; a key with only `wallets:read` gets `approval_url: null` and `approval_url_withheld: true`. A payment left `pending` with no provider id past the longest a create can take is parked `unknown` with `error_code` `lost_send` and `needs_human`. * - * Requires the `consents:read` scope. + * Requires the `wallets:read` scope. */ get: { parameters: { query?: never; header?: never; path: { - /** @description `ofb_`-prefixed consent id. */ id: string; }; cookie?: never; @@ -7331,57 +10078,57 @@ export interface paths { }; content: { "application/json": { - /** @description `ofb_`-prefixed. The id every other operation in this family takes. */ + /** @description `swp_`-prefixed: a JSR payment is a pull, credited as one. */ id: string; - /** @description Lowercase kebab-case, as supplied when the consent was opened: `itau`, `bradesco`, `bb`, `inter`. */ - bank_id: string; - /** @description The consumer, in the caller's own namespace. */ + enrollment_id: string; consumer_id: string; + wallet_id: string; + /** @enum {string} */ + provider: "iniciador"; + /** @description In centavos. */ + amount_minor: number; + currency: string; /** - * @description The wallet named on the create request, or null. Written once at creation and never rewritten: neither state transition on this consent touches the column. - * - * It is a label, not routing. A statement refresh copies this value onto every event it ingests, and nothing downstream reads it: reconciliation resolves a wallet from the funding source behind an event's `connection_id`, and the events this family publishes carry no such key. Binding a consent to a wallet therefore does not, on its own, put the ingested statement into that wallet's reconciliation. - */ - wallet_id: string | null; - /** - * @description `authorised` carries the British spelling, which is the column's own and not a typo. `revoked`, `expired` and `consumed` are terminal: no transition leaves them. Read "is this consent usable now" from `status` being `authorised`, never from `revoked_at` being null. + * @description `pending` until the person signs it and the bank settles it, then `completed`; `rejected` when nobody signed it in time (`signature_timed_out`) or the bank refused it; `canceled` when the provider refused the create. `unknown`: no definite answer, or bound to another enrollment (`needs_human`). * @enum {string} */ - status: "pending" | "authorised" | "revoked" | "expired" | "consumed"; - /** @description The OFB scopes the consent was opened for. */ - scopes: string[]; - /** @description The bank's own identifier for the consent, as returned when it was opened. */ - bank_consent_id: string | null; - /** @description The URL the consumer opens to authorise the consent at their bank. */ - authorisation_url: string | null; - /** - * Format: date-time - * @description Expiry of the bank access token. The token references themselves are never returned by this API. - */ - token_expires_at: string | null; - /** Format: date-time */ + status: "pending" | "settling" | "completed" | "rejected" | "expired" | "canceled" | "failed" | "unknown"; + provider_status: string | null; + /** @description The Pix end-to-end id. Assigned at create, so a rejected payment has one too: only `completed` moved money. */ + end_to_end_id: string | null; + error_code: string | null; + /** @description The bank ended it because the person did not sign within about ten minutes (TIMEOUT_CONSENTIMENTO). */ + signature_timed_out: boolean; + /** @description A person must check it at the provider: it is never sent again. */ + needs_human: boolean; + /** @description The hosted page where the person signs this payment with the passkey, while it waits for that. Handed only to a key with `wallets:admin`. It carries a credential of its own: hand it to the person and to no log. The API keeps it nowhere. */ + approval_url: string | null; + /** @description The payment waits for a signature, and the key reading it lacks `wallets:admin`: the signing page authorises a debit, so it is not handed to a read-only key. */ + approval_url_withheld: boolean; + /** @description Always `false` for now: a completed payment is not yet credited in the wallet. */ + credited: boolean; + replayed: boolean; created_at: string; - /** - * Format: date-time - * @description American spelling here, unlike `status: "authorised"`; both mirror their own column names. Stamped in the same statement as the transition into `authorised`. - */ - authorized_at: string | null; - /** - * Format: date-time - * @description Mirror of the bank-side consent expiry, stamped when the consent is opened. - */ - expires_at: string | null; - /** Format: date-time */ - revoked_at: string | null; - /** Format: date-time */ - consumed_at: string | null; - metadata: { - [key: string]: unknown; - }; + updated_at: string; }; }; }; - /** @description Not Found. No consent with this id in the caller's project. A consent belonging to another project in the same organization answers here too. */ + /** @description The key does not carry the `wallets:read` scope. Bare body; nothing was read or written. */ + 403: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + /** @enum {string} */ + error: "forbidden"; + message: string; + /** @enum {number} */ + status: 403; + }; + }; + }; + /** @description No JSR payment with this id in the caller's project. */ 404: { headers: { [name: string]: unknown; @@ -7401,107 +10148,48 @@ export interface paths { }; }; }; - }; - }; - put?: never; - post?: never; - delete?: never; - options?: never; - head?: never; - patch?: never; - trace?: never; - }; - "/v1/ofb/consents/{id}": { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - /** - * Read one bank consent - * @deprecated - * @description DEPRECATED alias of `GET /v1/bank-consents/{id}` (ent#979), kept for two releases. Same handler, same required scope; switch the path and nothing else changes. - * - * The body is the consent projection: the same shape `POST /v1/bank-consents` returns on create, and the same one the callback and revoke transitions return. The refresh-statement operation in this family is the exception, answering with a run summary rather than a consent. - * - * Resolution is scoped to the organization AND the project the credential authenticates for. A consent held by a SIBLING project in the same organization answers 404 here, indistinguishable from one that never existed. That is deliberate rather than incidental: one project's upstream bank grant is never readable from another. - * - * No token material leaves. The row carries references to the bank's access and refresh tokens; they are dropped before the body is built, and `token_expires_at` is the only thing about the bank token that is returned. - * - * Requires the `consents:read` scope. - */ - get: { - parameters: { - query?: never; - header?: never; - path: { - /** @description `ofb_`-prefixed consent id. */ - id: string; + /** @description The project is live. JSR serves test projects only, against the provider's sandbox (`details.reason` `live_not_enabled`). */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "ofb_not_live"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; }; - cookie?: never; - }; - requestBody?: never; - responses: { - /** @description OK */ - 200: { + /** @description The provider refused (`jsr_provider_refused`). `details.provider_code` is its own code; its free text is never relayed. */ + 502: { headers: { [name: string]: unknown; }; content: { "application/json": { - /** @description `ofb_`-prefixed. The id every other operation in this family takes. */ - id: string; - /** @description Lowercase kebab-case, as supplied when the consent was opened: `itau`, `bradesco`, `bb`, `inter`. */ - bank_id: string; - /** @description The consumer, in the caller's own namespace. */ - consumer_id: string; - /** - * @description The wallet named on the create request, or null. Written once at creation and never rewritten: neither state transition on this consent touches the column. - * - * It is a label, not routing. A statement refresh copies this value onto every event it ingests, and nothing downstream reads it: reconciliation resolves a wallet from the funding source behind an event's `connection_id`, and the events this family publishes carry no such key. Binding a consent to a wallet therefore does not, on its own, put the ingested statement into that wallet's reconciliation. - */ - wallet_id: string | null; - /** - * @description `authorised` carries the British spelling, which is the column's own and not a typo. `revoked`, `expired` and `consumed` are terminal: no transition leaves them. Read "is this consent usable now" from `status` being `authorised`, never from `revoked_at` being null. - * @enum {string} - */ - status: "pending" | "authorised" | "revoked" | "expired" | "consumed"; - /** @description The OFB scopes the consent was opened for. */ - scopes: string[]; - /** @description The bank's own identifier for the consent, as returned when it was opened. */ - bank_consent_id: string | null; - /** @description The URL the consumer opens to authorise the consent at their bank. */ - authorisation_url: string | null; - /** - * Format: date-time - * @description Expiry of the bank access token. The token references themselves are never returned by this API. - */ - token_expires_at: string | null; - /** Format: date-time */ - created_at: string; - /** - * Format: date-time - * @description American spelling here, unlike `status: "authorised"`; both mirror their own column names. Stamped in the same statement as the transition into `authorised`. - */ - authorized_at: string | null; - /** - * Format: date-time - * @description Mirror of the bank-side consent expiry, stamped when the consent is opened. - */ - expires_at: string | null; - /** Format: date-time */ - revoked_at: string | null; - /** Format: date-time */ - consumed_at: string | null; - metadata: { - [key: string]: unknown; + error: { + /** @enum {string} */ + code: "jsr_provider_refused"; + message: string; + details?: { + [key: string]: unknown; + }; }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; }; }; }; - /** @description Not Found. No consent with this id in the caller's project. A consent belonging to another project in the same organization answers here too. */ - 404: { + /** @description No definite answer from the provider (`jsr_provider_ambiguous`), or the deployment has no JSR provider credentials (`ofb_adapter_unavailable`). */ + 503: { headers: { [name: string]: unknown; }; @@ -7509,7 +10197,7 @@ export interface paths { "application/json": { error: { /** @enum {string} */ - code: "not_found"; + code: "jsr_provider_ambiguous" | "ofb_adapter_unavailable"; message: string; details?: { [key: string]: unknown; @@ -12255,7 +14943,7 @@ export interface paths { * * EVERY CHECK SAYS WHAT IT MEASURED AND WHAT THAT MEANS HERE. Its own `status` keeps its vocabulary; beside it, `state` separates a real failure from pending configuration, from no activity, and from a feature not in use, with `required`, a `reason` code and, where something has to be set up, an `action`. A new account with no integration, no provider call and no FX quote reads `healthy`, with `connections` pending configuration. * - * GRADE ON `status`, AND READ THE RULE BEFORE WRITING THE ALERT. Only `state: failure` grades. `down` means `db` or `vault` fails. `degraded` means any other check fails, which today is one of: the tool catalog is not loaded (`tool_catalog`), a USD/BRL quote the router needs is missing, stale or unreadable (`fx_rates`; no deployment needs one until the router normalizes cost across currencies, and until then the quote is `not_in_use` whatever its age), a live Celcoin connection lacks a webhook subscription (`celcoin_webhook_subscriptions`), or a Pix Automático worker with work to do is stale, failing or never ran (`recurrence_holds`, `recurrence_scheduler`, including a hold past its time), or a BolePix paid twice has had its refund owed for longer than 3 days (`bolepix_refunds`), or this production process has no working tool strategy and refuses every meta-tool call with 503 `tool_strategy_unavailable` (`tool_strategy`; reads, authentication and webhooks keep working). Everything else grades `healthy`. `attention` lists the failing checks and the ones pending configuration by name. + * GRADE ON `status`, AND READ THE RULE BEFORE WRITING THE ALERT. Only `state: failure` grades. `down` means `db` or `vault` fails. `degraded` means any other check fails, which today is one of: the tool catalog is not loaded (`tool_catalog`), a USD/BRL quote the router needs is missing, stale or unreadable (`fx_rates`; no deployment needs one until the router normalizes cost across currencies, and until then the quote is `not_in_use` whatever its age), a live Celcoin connection lacks a webhook subscription (`celcoin_webhook_subscriptions`), or a Pix Automático worker with work to do is stale, failing or never ran (`recurrence_holds`, `recurrence_scheduler`, including a hold past its time), or a BolePix paid twice has had its refund owed for longer than 3 days (`bolepix_refunds`), or a Live money state is waiting on a person (`money_reconcile`: an accepted cash-out the provider failed later, a hold whose dispatch outcome is unknown, a dispatch whose process died, or a return or inbound credit that could not be applied), or this production process has no working tool strategy and refuses every meta-tool call with 503 `tool_strategy_unavailable` (`tool_strategy`; reads, authentication and webhooks keep working). Everything else grades `healthy`. `attention` lists the failing checks and the ones pending configuration by name. * * `metrics` IS READ, NEVER GRADED. `metrics.recurrence_instruction_alarms` counts the Pix Automático instruction alarms still open on a cycle still ahead, per kind and reason, for the calling org: a cycle not announced, an instruction refused, held back by a ceiling, or queued and expired. Each alarm already reached its tenant as an event in the recurrence's project; this is the standing number, and it never moves `status`. * @@ -13133,6 +15821,8 @@ export interface paths { * `link_token` is the same value as the `state` parameter inside `authorize_url`. It is single use and expires at `expires_at`, ten minutes out. * * The refusals are bare `{ error, ... }` bodies, not the nested envelope the rest of this document mostly uses. A provider with no OAuth configuration is 404. A missing platform client credential is 500 — that is our seeding defect, not a caller error, and no change to the request fixes it. + * + * The exception is a person's own Google account (`server_id` `google-calendar`, `google-drive` or `gmail`), described on the canonical path: its refusals use the `error.code` envelope, an API key or an OAuth token carries no person (403 `bearer_token_has_no_person`), `user_id` must be the signed-in person, `scopes` is refused because the connector's scopes are fixed, and the connectors switched off answer 503 `connector_disabled`. */ post: { parameters: { @@ -13189,6 +15879,26 @@ export interface paths { }; }; }; + /** @description Google connectors only: no verified person rides on the request, the session token does not verify or names someone else, `user_id` is not the signed-in person, or the person is not a member of the organization. */ + 403: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "bearer_token_has_no_person" | "user_token_required" | "user_token_invalid" | "user_token_identity_mismatch" | "not_a_member"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; /** @description The provider has no OAuth configuration in the catalog. */ 404: { headers: { @@ -13232,6 +15942,26 @@ export interface paths { }; }; }; + /** @description Google connectors only: they are switched off on this deployment, or it cannot verify a person's session. */ + 503: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "connector_disabled" | "user_token_verification_unconfigured"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; }; }; delete?: never; @@ -13899,7 +16629,7 @@ export interface paths { * * THE MONEY IS AUTHORIZED BY THE CONSUMER'S SIGNED MANDATE, NOT BY WHO IS CALLING. `mandate`, `signature`, `agent_id` and `purpose` are all four required in practice: the schema marks them optional only so that omitting them produces a typed `mandate_required` refusal instead of a shapeless 400. No key, no role and no header substitutes for them, and the attribution recorded on the withdrawal is derived from the verified mandate rather than from anything the caller wrote. The destination must be NAMED in the mandate's signed withdrawal allowlist — its own field, separate from the list of merchants the agent may pay, so that a shopping grant is not also a cash-out grant. * - * AND YET THE PATH DOES READ AN IDENTITY HEADER, BEFORE ANY OF THAT. The route carries an `admin` role gate as a preHandler, and that gate reads `x-codespar-user` and answers 403 on its own, before the mandate is looked at. Send the header, naming a member who holds `admin` or `owner` in the organization. On a dashboard-forwarded credential a missing header is refused immediately. On an API key the gate is being rolled out and currently lets the request through while recording it, so a key that works today without the header will stop working when the rollout completes — this is the one sentence to act on if you are integrating now. + * THE ROLE GATE DOES NOT AUTHORIZE THIS. With an API key holding `wallets:admin` the mandate above is the whole authorization; `x-codespar-user` is not read. On the dashboard the gate also asks for a member who holds `admin` or `owner`. * * Read the two gates as two different questions. The role gate asks who may ASK for a withdrawal; the mandate asks whether the money's owner AGREED to it. Passing the first does not weaken the second. * @@ -14005,7 +16735,7 @@ export interface paths { /** * @description Forbidden, from one of THREE gates, in THREE different body shapes. Parse defensively: `error` is a string on two of them and an object on the third. * - * (a) THE ROLE GATE, bare body: `{ error, required: "admin", message?, status? }`. `error` is `insufficient_role` when the acting member is not senior enough, `bearer_admin_role_missing` when no `x-codespar-user` was forwarded, `bearer_admin_user_not_member` when the forwarded user is not in the organization, or `bearer_admin_role_unresolved` when the role could not be looked up. The last three carry a `message` and `status`. + * (a) THE ROLE GATE, bare body: `{ error: "insufficient_role", required: "admin" }`, when the dashboard's acting member is not senior enough or the credential is an OAuth token. An API key is not refused by this gate. * * (b) THE MANDATE GATE, `apiError` envelope. `mandate_required` (one of the four proof fields is missing), `mandate_consumer_mismatch`, `mandate_currency_mismatch`, `mandate_` for a mandate that is not active, `mandate_sig_invalid` (the STORED row failed its own integrity check), `expired`, `agent_mismatch`, `purpose_mismatch`, `per_tx_cap_exceeded`, `total_cap_exceeded`, `currency_not_authorized`, `merchant_not_allowed`, and `withdrawal_destination_unpinned` — which carries `error.details` naming what the mandate DID authorize, so an agent can open a re-consent flow rather than stopping at a refusal it cannot interpret. * @@ -14020,12 +16750,9 @@ export interface paths { content: { "application/json": { /** @enum {string} */ - error: "insufficient_role" | "bearer_admin_role_missing" | "bearer_admin_user_not_member" | "bearer_admin_role_unresolved"; + error: "insufficient_role"; /** @enum {string} */ required: "admin"; - message?: string; - /** @enum {number} */ - status?: 403; } | { error: { code: string; @@ -14193,7 +16920,7 @@ export interface paths { * * THE 202 IS AN ACKNOWLEDGEMENT, NOT A RECONCILIATION. The entries are stored; the matching happens on the next cycle, and `next_recon_cycle_within_seconds` is how long that is at most. Nothing here reports a match. * - * Scope: `wallets:admin`, and the route additionally requires the `admin` role: send `x-codespar-user` naming an admin or owner of the organization. + * Administrative: an admin or owner performs it from the dashboard. An API key is refused with 403 `admin_session_required`, whatever its scopes. */ post: { parameters: { @@ -14260,7 +16987,7 @@ export interface paths { }; }; }; - /** @description Forbidden, from the role gate, in a BARE body — not the `apiError` envelope the 400 and 404 use. `insufficient_role` when the acting member is not senior enough; on an API key, `bearer_admin_role_missing`, `bearer_admin_user_not_member` or `bearer_admin_role_unresolved`, each with a `message` and `status`. */ + /** @description Forbidden, from the role gate, in a BARE body — not the `apiError` envelope the 400 and 404 use. `insufficient_role` when the acting member is not senior enough (with `required: "admin"`); on an API key, `admin_session_required`, with a `message` and `status`, whatever its scopes. */ 403: { headers: { [name: string]: unknown; @@ -14268,9 +16995,9 @@ export interface paths { content: { "application/json": { /** @enum {string} */ - error: "insufficient_role" | "bearer_admin_role_missing" | "bearer_admin_user_not_member" | "bearer_admin_role_unresolved"; + error: "insufficient_role" | "admin_session_required"; /** @enum {string} */ - required: "admin"; + required?: "admin"; message?: string; /** @enum {number} */ status?: 403; @@ -16698,7 +19425,7 @@ export interface paths { * * `POST /v1/connect/start` is the same handler on a second path. A provider with no OAuth configuration is 404; a missing platform client credential is 500, which is our seeding defect and not the caller's error. Both bodies are bare `{ error, … }`, not the `error.code` envelope. * - * **A person's own Google account** (`server_id` `google-calendar`, `google-drive` or `gmail`) is connected for its owner only. The owner is the signed-in person whose session token the dashboard forwards (`x-codespar-user-token`), and `user_id` must name that person; an API key or an OAuth token carries no person and is refused `bearer_token_has_no_person` (403). The connector asks for its own scopes, so `scopes` is refused (400 `invalid_body`). The consent asks for offline access, always shows Google's consent screen and keeps earlier grants. Test and Live projects both use the real Google: there is no Google sandbox, and the data is the person's own. These refusals use the `error.code` envelope. Off on the deployment, the three answer `connector_disabled` (503). + * **A person's own Google account** (`server_id` `google-calendar`, `google-drive` or `gmail`) is connected for its owner only. The owner is the signed-in person whose session token the dashboard forwards (`x-codespar-user-token`), and `user_id` must name that person; an API key or an OAuth token carries no person and is refused `bearer_token_has_no_person` (403). The connector asks for its own fixed scopes, so `scopes` is refused (400 `invalid_body`): `openid`, `https://www.googleapis.com/auth/userinfo.email` and `https://www.googleapis.com/auth/userinfo.profile` (which Google account it is), plus one product scope, `https://www.googleapis.com/auth/calendar` for `google-calendar`, `https://www.googleapis.com/auth/drive` for `google-drive` and `https://www.googleapis.com/auth/gmail.modify` for `gmail`. The person may untick the product scope at Google; the connection then reads where a narrower grant allows it and a write answers `connector_scope_insufficient`. The consent asks for offline access, always shows Google's consent screen and keeps earlier grants. A Test project uses the real Google: there is no Google sandbox, and the data is the person's own. A Live project is refused `google_connectors_live_disabled` (409), here and at the callback, before anything is sent to Google. These refusals use the `error.code` envelope. Off on the deployment, the three answer `connector_disabled` (503). */ post: { parameters: { @@ -16818,7 +19545,7 @@ export interface paths { }; }; }; - /** @description Google connectors only: they are switched off on this deployment. */ + /** @description Google connectors only: they are switched off on this deployment, or it cannot verify a person's session. */ 503: { headers: { [name: string]: unknown; @@ -17285,6 +20012,8 @@ export interface paths { * @enum {string} */ surface?: "hosted" | "partner"; + /** @enum {string} */ + executor?: "codespar_simulator" | "provider_sandbox"; }; }; }; @@ -17307,10 +20036,29 @@ export interface paths { surface: "hosted" | "partner"; /** @description The hosted page for this token, composed from the server's configured base. Hand it to the consumer on the `hosted` surface. It is returned on `partner` too, where it is a usable fallback: the same token also answers on the page. */ consent_url: string; + /** + * @description Who executes (or executed) the payment, by the same name the integrator chooses with on POST /v1/consents. `codespar_simulator` ("Simulado pela CodeSpar": no provider is called) or `provider_sandbox` (the provider's sandbox, over the account the server bound to this consumer); both Test only. Null when no executor applies, Live included. The name is the MODE: the provider, account, project, consumer and environment are resolved by the server before the signature and checked again when the payment runs; no request field chooses them (`executor_provider_not_selectable`), and a provider failure is never turned into a simulation. Records written before this name existed keep their stored value and are read in these words. + * @enum {string|null} + */ + executor: "codespar_simulator" | "provider_sandbox" | null; + /** + * @description The concrete provider behind `executor`, as the server resolved it: `celcoin` for `provider_sandbox`; null for `codespar_simulator` (no provider is called) and when `executor` is null. Read-only. + * @enum {string|null} + */ + executor_provider: "celcoin" | null; + /** @description The executor's label as the consent screen, the dashboard and the receipt show it. In Test it ends "· sem dinheiro real". */ + executor_label: string | null; + /** + * @description The project's environment. + * @enum {string|null} + */ + environment: "test" | "live" | null; + /** @description False in Test, always: no real money moves, including when the provider's sandbox CONFIRMED the operation (`moneyMoved: true` / `settlement: "confirmed"` then mean the sandbox settled it). True in Live. */ + real_money: boolean | null; }; }; }; - /** @description The body did not match the schema. `details.issues` carries the Zod issues; the refusals with their own message are a `"*"` entry in `intent.withdrawal_allowlist` and a `intent.dda_allowlist` entry that is not a CPF (11 digits) or a CNPJ (14 digits). */ + /** @description The body did not match the schema (`invalid_body`), `executor` was sent for a mandate that is not single-currency BRL Pix (`executor_requires_brl_pix`), or the body named a provider (`provider` / `executor_provider`, top level or in `intent`: `executor_provider_not_selectable`, `details.field`): the provider behind `provider_sandbox` is resolved by the server. Nothing was created. */ 400: { headers: { [name: string]: unknown; @@ -17319,7 +20067,47 @@ export interface paths { "application/json": { error: { /** @enum {string} */ - code: "invalid_body"; + code: "invalid_body" | "executor_requires_brl_pix" | "executor_provider_not_selectable"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description `executor: "provider_sandbox"` and the project's provider sandbox is not ready (`provider_sandbox_not_ready`): `details.missing` names each gap, `details.next_steps` says who does what, and `details.alternative` names the simulator. Nothing was created. */ + 409: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "provider_sandbox_not_ready"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description `executor` in a Live project: `simulation_refused_live` for `codespar_simulator` (Live never simulates) and `executor_test_only` for `provider_sandbox`. Nothing was created. */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "simulation_refused_live" | "executor_test_only"; message: string; details?: { [key: string]: unknown; @@ -17422,6 +20210,8 @@ export interface paths { * @enum {string} */ surface?: "hosted" | "partner"; + /** @enum {string} */ + executor?: "codespar_simulator" | "provider_sandbox"; }; }; }; @@ -17444,10 +20234,29 @@ export interface paths { surface: "hosted" | "partner"; /** @description The hosted page for this token, composed from the server's configured base. Hand it to the consumer on the `hosted` surface. It is returned on `partner` too, where it is a usable fallback: the same token also answers on the page. */ consent_url: string; + /** + * @description Who executes (or executed) the payment, by the same name the integrator chooses with on POST /v1/consents. `codespar_simulator` ("Simulado pela CodeSpar": no provider is called) or `provider_sandbox` (the provider's sandbox, over the account the server bound to this consumer); both Test only. Null when no executor applies, Live included. The name is the MODE: the provider, account, project, consumer and environment are resolved by the server before the signature and checked again when the payment runs; no request field chooses them (`executor_provider_not_selectable`), and a provider failure is never turned into a simulation. Records written before this name existed keep their stored value and are read in these words. + * @enum {string|null} + */ + executor: "codespar_simulator" | "provider_sandbox" | null; + /** + * @description The concrete provider behind `executor`, as the server resolved it: `celcoin` for `provider_sandbox`; null for `codespar_simulator` (no provider is called) and when `executor` is null. Read-only. + * @enum {string|null} + */ + executor_provider: "celcoin" | null; + /** @description The executor's label as the consent screen, the dashboard and the receipt show it. In Test it ends "· sem dinheiro real". */ + executor_label: string | null; + /** + * @description The project's environment. + * @enum {string|null} + */ + environment: "test" | "live" | null; + /** @description False in Test, always: no real money moves, including when the provider's sandbox CONFIRMED the operation (`moneyMoved: true` / `settlement: "confirmed"` then mean the sandbox settled it). True in Live. */ + real_money: boolean | null; }; }; }; - /** @description The body did not match the schema. `details.issues` carries the Zod issues; the refusals with their own message are a `"*"` entry in `intent.withdrawal_allowlist` and a `intent.dda_allowlist` entry that is not a CPF (11 digits) or a CNPJ (14 digits). */ + /** @description The body did not match the schema (`invalid_body`), `executor` was sent for a mandate that is not single-currency BRL Pix (`executor_requires_brl_pix`), or the body named a provider (`provider` / `executor_provider`, top level or in `intent`: `executor_provider_not_selectable`, `details.field`): the provider behind `provider_sandbox` is resolved by the server. Nothing was created. */ 400: { headers: { [name: string]: unknown; @@ -17456,7 +20265,47 @@ export interface paths { "application/json": { error: { /** @enum {string} */ - code: "invalid_body"; + code: "invalid_body" | "executor_requires_brl_pix" | "executor_provider_not_selectable"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description `executor: "provider_sandbox"` and the project's provider sandbox is not ready (`provider_sandbox_not_ready`): `details.missing` names each gap, `details.next_steps` says who does what, and `details.alternative` names the simulator. Nothing was created. */ + 409: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "provider_sandbox_not_ready"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + /** @description `executor` in a Live project: `simulation_refused_live` for `codespar_simulator` (Live never simulates) and `executor_test_only` for `provider_sandbox`. Nothing was created. */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "simulation_refused_live" | "executor_test_only"; message: string; details?: { [key: string]: unknown; @@ -17528,6 +20377,25 @@ export interface paths { * @enum {string} */ surface: "hosted" | "partner"; + /** + * @description Who executes (or executed) the payment, by the same name the integrator chooses with on POST /v1/consents. `codespar_simulator` ("Simulado pela CodeSpar": no provider is called) or `provider_sandbox` (the provider's sandbox, over the account the server bound to this consumer); both Test only. Null when no executor applies, Live included. The name is the MODE: the provider, account, project, consumer and environment are resolved by the server before the signature and checked again when the payment runs; no request field chooses them (`executor_provider_not_selectable`), and a provider failure is never turned into a simulation. Records written before this name existed keep their stored value and are read in these words. + * @enum {string|null} + */ + executor: "codespar_simulator" | "provider_sandbox" | null; + /** + * @description The concrete provider behind `executor`, as the server resolved it: `celcoin` for `provider_sandbox`; null for `codespar_simulator` (no provider is called) and when `executor` is null. Read-only. + * @enum {string|null} + */ + executor_provider: "celcoin" | null; + /** @description The executor's label as the consent screen, the dashboard and the receipt show it. In Test it ends "· sem dinheiro real". */ + executor_label: string | null; + /** + * @description The project's environment. + * @enum {string|null} + */ + environment: "test" | "live" | null; + /** @description False in Test, always: no real money moves, including when the provider's sandbox CONFIRMED the operation (`moneyMoved: true` / `settlement: "confirmed"` then mean the sandbox settled it). True in Live. */ + real_money: boolean | null; }; }; }; @@ -17692,10 +20560,41 @@ export interface paths { signature: string; /** @description The `callback_url` given at creation, echoed so the caller can post the mandate on. */ callback_url: string | null; + /** + * @description Who executes (or executed) the payment, by the same name the integrator chooses with on POST /v1/consents. `codespar_simulator` ("Simulado pela CodeSpar": no provider is called) or `provider_sandbox` (the provider's sandbox, over the account the server bound to this consumer); both Test only. Null when no executor applies, Live included. The name is the MODE: the provider, account, project, consumer and environment are resolved by the server before the signature and checked again when the payment runs; no request field chooses them (`executor_provider_not_selectable`), and a provider failure is never turned into a simulation. Records written before this name existed keep their stored value and are read in these words. + * @enum {string|null} + */ + executor: "codespar_simulator" | "provider_sandbox" | null; + /** + * @description The concrete provider behind `executor`, as the server resolved it: `celcoin` for `provider_sandbox`; null for `codespar_simulator` (no provider is called) and when `executor` is null. Read-only. + * @enum {string|null} + */ + executor_provider: "celcoin" | null; + /** @description The executor's label as the consent screen, the dashboard and the receipt show it. In Test it ends "· sem dinheiro real". */ + executor_label: string | null; + /** + * @description The project's environment. + * @enum {string|null} + */ + environment: "test" | "live" | null; + /** @description False in Test, always: no real money moves, including when the provider's sandbox CONFIRMED the operation (`moneyMoved: true` / `settlement: "confirmed"` then mean the sandbox settled it). True in Live. */ + real_money: boolean | null; + /** @description Test only: present when the mandate was signed over a `pix-consent` source with no executor. A payment under it is refused with `funding_source_executor_required`; open a new consent naming `executor`. */ + executor_guidance?: { + /** @enum {string} */ + code: "funding_source_executor_required"; + message: string; + next: { + /** @enum {string} */ + action: "reconsent_with_executor"; + endpoint: string; + executor_choices: ("codespar_simulator" | "provider_sandbox")[]; + }; + }; }; }; }; - /** @description The body did not match the schema (`invalid_body`, with the Zod issues in `details.issues`), the attestation does not match the token's surface (`attestation_required` on `partner` without one, `attestation_not_accepted` on `hosted` with one), or the evidence carries a key its channel cannot expose or one the object does not declare (`attestation_evidence_invalid`, `details.key`). */ + /** @description The body did not match the schema (`invalid_body`, with the Zod issues in `details.issues`), the attestation does not match the token's surface (`attestation_required` on `partner` without one, `attestation_not_accepted` on `hosted` with one), or the evidence carries a key its channel cannot expose or one the object does not declare (`attestation_evidence_invalid`, `details.key`), or a consent opened with `executor` was submitted with a rail other than `pix-consent` (`executor_rail_mismatch`), or the body named a provider (`executor_provider_not_selectable`, `details.field`): the source signed is the one the server resolved for the consent's executor. */ 400: { headers: { [name: string]: unknown; @@ -17704,7 +20603,7 @@ export interface paths { "application/json": { error: { /** @enum {string} */ - code: "invalid_body" | "attestation_required" | "attestation_not_accepted" | "attestation_evidence_invalid"; + code: "invalid_body" | "attestation_required" | "attestation_not_accepted" | "attestation_evidence_invalid" | "executor_rail_mismatch" | "executor_provider_not_selectable"; message: string; details?: { [key: string]: unknown; @@ -17755,7 +20654,7 @@ export interface paths { }; }; }; - /** @description The token was already submitted, or a concurrent submit won the race (nothing was created twice: the loser rolls back whole); or `method: "verified_code"` was claimed without a contact verification for this consumer in the last 24h, in which case nothing was created at all and the token is still pending. */ + /** @description The token was already submitted, or a concurrent submit won the race (nothing was created twice: the loser rolls back whole); or `method: "verified_code"` was claimed without a contact verification for this consumer in the last 24h, in which case nothing was created at all and the token is still pending; or the consent was opened with `executor: "provider_sandbox"` and the project has no sandbox account bound to THIS consumer (`provider_sandbox_not_ready`, `details.missing`/`next_steps`): nothing was signed, the token is still pending and no other source is used. */ 409: { headers: { [name: string]: unknown; @@ -17764,7 +20663,7 @@ export interface paths { "application/json": { error: { /** @enum {string} */ - code: "consent_already_resolved" | "consent_race" | "contact_verification_required"; + code: "consent_already_resolved" | "consent_race" | "contact_verification_required" | "provider_sandbox_not_ready"; message: string; details?: { [key: string]: unknown; @@ -17795,6 +20694,26 @@ export interface paths { }; }; }; + /** @description The consent was opened with `executor` and its project is not a Test project (`simulation_refused_live`, `executor_test_only`). Nothing was signed. */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "simulation_refused_live" | "executor_test_only"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; }; }; delete?: never; @@ -17929,7 +20848,7 @@ export interface paths { }; }; }; - /** @description Local state refuses. `psp_attempt_in_flight`: the same attempt is already in flight; retry the SAME `attempt_id` once it has answered, never a new one. `psp_attempt_uncertain`: an earlier attempt ended with an unknown outcome and this intent is PINNED to it, so present the same `attempt_id` again, never a new one. `psp_attempt_conflict`: the earlier attempt was already compensated. `attempt_id_conflict`: this `attempt_id` was already used for a different payment (`mismatched_fields` names what differs); nothing was held or sent. `attempt_id_unavailable`: another project of this organization holds this `attempt_id`; use a new one. */ + /** @description Local state refuses. `psp_attempt_in_flight`: the same attempt is already in flight; retry the SAME `attempt_id` once it has answered, never a new one. `psp_attempt_uncertain`: an earlier attempt ended with an unknown outcome and this intent is PINNED to it, so present the same `attempt_id` again, never a new one. `psp_attempt_conflict`: the earlier attempt was already compensated. `attempt_id_conflict`: this `attempt_id` was already used for a different payment (`mismatched_fields` names what differs); nothing was held or sent. `attempt_id_unavailable`: another project of this organization holds this `attempt_id`; use a new one. `funding_source_executor_required` (Test only, ent#1983): the mandate's `pix-consent` source was signed without an executor; nothing was sent and the mandate is unchanged; `details.next` says to open a new consent naming `executor` (`codespar_simulator` or `provider_sandbox`). */ 409: { headers: { [name: string]: unknown; @@ -17938,7 +20857,7 @@ export interface paths { "application/json": { error: { /** @enum {string} */ - code: "psp_attempt_in_flight" | "psp_attempt_uncertain" | "psp_attempt_conflict" | "attempt_id_conflict" | "attempt_id_unavailable"; + code: "funding_source_executor_required" | "psp_attempt_in_flight" | "psp_attempt_uncertain" | "psp_attempt_conflict" | "attempt_id_conflict" | "attempt_id_unavailable"; message: string; details?: { [key: string]: unknown; @@ -18140,7 +21059,7 @@ export interface paths { }; }; }; - /** @description Local state refuses, on the same five conditions as the by-id route. */ + /** @description Local state refuses, on the same conditions as the by-id route, `funding_source_executor_required` included. */ 409: { headers: { [name: string]: unknown; @@ -18149,7 +21068,7 @@ export interface paths { "application/json": { error: { /** @enum {string} */ - code: "psp_attempt_in_flight" | "psp_attempt_uncertain" | "psp_attempt_conflict" | "attempt_id_conflict" | "attempt_id_unavailable"; + code: "funding_source_executor_required" | "psp_attempt_in_flight" | "psp_attempt_uncertain" | "psp_attempt_conflict" | "attempt_id_conflict" | "attempt_id_unavailable"; message: string; details?: { [key: string]: unknown; @@ -18391,7 +21310,7 @@ export interface paths { get: { parameters: { query?: { - /** @description Our own row status: `pending`, `settled`, `expired`. */ + /** @description Our own row status: `pending`, `settled`, `expired`, `failed`. */ status?: string; /** @description Filters on the same three facts the field is derived from, in SQL. */ settlement?: "confirmed" | "pending" | "unconfirmable" | "none"; @@ -18422,6 +21341,11 @@ export interface paths { created_at: string; /** @enum {string|null} */ settlement: "confirmed" | "pending" | "unconfirmable" | null; + failure?: { + code: string; + provider_status: string | null; + failed_at: string | null; + }; /** @description When we last knew the issuer's state. Null means we never did. */ settlement_as_of: string | null; }[]; @@ -18456,7 +21380,7 @@ export interface paths { * Issue a charge * @description Issues an inbound charge: the buyer pays the merchant. The RAIL IS A FIELD, not a path. `method: "pix"` mints an immediate Pix that hands back its copy-and-paste string right away and expires in about an hour. `method: "boleto"` WITH a `due_date` issues a cobrança com vencimento: ONE receivable the payer settles either as a boleto (barcode and linha digitável) or by Pix. One debt, two payable legs, never two documents. * - * **The cobrança com vencimento answers `PROCESSING` with `payable: false` and no document.** The instrument registers with the clearing house first. Subscribe to `commerce.charge.created` rather than polling for a barcode that is not late, only not made yet. `commerce.charge.paid` is the event that means the funds arrived, by either leg. + * **The cobrança com vencimento answers `PROCESSING` with `payable: false` and no document.** The instrument registers with the clearing house first. Subscribe to `commerce.charge.created` rather than polling for a barcode that is not late, only not made yet. `commerce.charge.paid` is the event that means the funds arrived, by either leg: it is published only after CodeSpar settled the charge and credited the wallet, never on the provider's word alone, and once per charge. A charge the issuer refuses to register closes as `local_status: "failed"` and publishes `commerce.charge.failed` once instead. * * **`idempotency_key` is REQUIRED for that combination**, and it is checked before anything reaches the issuer. A repeat with the same key returns the charge already issued, or its still-open reservation, instead of a second receivable the same debtor could pay twice. Send it as the `Idempotency-Key` header, as the body's `idempotency_key`, or as both with the SAME value; two different values are refused rather than one silently winning. * @@ -18533,9 +21457,18 @@ export interface paths { * **A charge settled by the sandbox payer answers `CONFIRMED` here**, the same value a real payment leaves a live read answering — so a client that polls `status` sees the test payment exactly where it would see a live one. The issuer's homolog account never sees that money and keeps answering PENDING (EXPIRED after the due date); that answer stays in `raw` and is not reported as `status` or as a `status_conflict`, because for a test charge the fixture is the issuer's truth. `settlement: "confirmed"` and `local_status: "settled"` say the same thing from our side. Any other issuer answer (ERROR, CANCELLED, PROCESSING) is reported as the issuer said it, with `status_conflict: true`. */ status: string; - /** @description What CodeSpar recorded, which is a different question from `status`. */ + /** @description What CodeSpar recorded, which is a different question from `status`: `pending`, `settled`, `expired` (cancelled or expired unpaid) or `failed`. `failed` is terminal: the issuer refused to register the charge (`status: "ERROR"`, no boleto and no Pix ever issued), so nothing was ever payable and nothing was charged; `failure` says why. Create a new charge. PROCESSING, a slow registration or a missing callback are never `failed`. */ local_status: string; - /** @description True whenever the issuer's known state and ours disagree, instead of one of them silently winning. They agree only as follows: our `pending` beside the issuer's PENDING or PROCESSING; our `settled` beside CONFIRMED or PENDING (the issuer's read can lag a payment); our `expired` beside CANCELLED or PENDING (lag after a cancel). Every other pair is a conflict, including an issuer ERROR, an issuer terminal state on a charge we still hold open, and a status spelling we do not recognise. False when no issuer state is known at all. `settlement: "unconfirmable"` is the narrower case of both sides terminal and different. */ + /** @description Present only when `local_status` is `failed`. The charge's history, ids and correlation stay readable; `commerce.charge.failed` was published once when it closed. */ + failure?: { + /** @description `issuer_rejected`: the issuer refused to register the charge. */ + code: string; + /** @description The issuer's own word, preserved (`ERROR`). */ + provider_status: string | null; + /** @description When CodeSpar closed the charge as failed. */ + failed_at: string | null; + }; + /** @description True whenever the issuer's known state and ours disagree, instead of one of them silently winning. They agree only as follows: our `pending` beside the issuer's PENDING or PROCESSING; our `settled` beside CONFIRMED or PENDING (the issuer's read can lag a payment); our `expired` beside CANCELLED or PENDING (lag after a cancel); our `failed` beside ERROR (the refusal it records). Every other pair is a conflict, including an issuer ERROR, an issuer terminal state on a charge we still hold open, and a status spelling we do not recognise. False when no issuer state is known at all. `settlement: "unconfirmable"` is the narrower case of both sides terminal and different. */ status_conflict: boolean; method: string; currency: string; @@ -18696,9 +21629,18 @@ export interface paths { * **A charge settled by the sandbox payer answers `CONFIRMED` here**, the same value a real payment leaves a live read answering — so a client that polls `status` sees the test payment exactly where it would see a live one. The issuer's homolog account never sees that money and keeps answering PENDING (EXPIRED after the due date); that answer stays in `raw` and is not reported as `status` or as a `status_conflict`, because for a test charge the fixture is the issuer's truth. `settlement: "confirmed"` and `local_status: "settled"` say the same thing from our side. Any other issuer answer (ERROR, CANCELLED, PROCESSING) is reported as the issuer said it, with `status_conflict: true`. */ status: string; - /** @description What CodeSpar recorded, which is a different question from `status`. */ + /** @description What CodeSpar recorded, which is a different question from `status`: `pending`, `settled`, `expired` (cancelled or expired unpaid) or `failed`. `failed` is terminal: the issuer refused to register the charge (`status: "ERROR"`, no boleto and no Pix ever issued), so nothing was ever payable and nothing was charged; `failure` says why. Create a new charge. PROCESSING, a slow registration or a missing callback are never `failed`. */ local_status: string; - /** @description True whenever the issuer's known state and ours disagree, instead of one of them silently winning. They agree only as follows: our `pending` beside the issuer's PENDING or PROCESSING; our `settled` beside CONFIRMED or PENDING (the issuer's read can lag a payment); our `expired` beside CANCELLED or PENDING (lag after a cancel). Every other pair is a conflict, including an issuer ERROR, an issuer terminal state on a charge we still hold open, and a status spelling we do not recognise. False when no issuer state is known at all. `settlement: "unconfirmable"` is the narrower case of both sides terminal and different. */ + /** @description Present only when `local_status` is `failed`. The charge's history, ids and correlation stay readable; `commerce.charge.failed` was published once when it closed. */ + failure?: { + /** @description `issuer_rejected`: the issuer refused to register the charge. */ + code: string; + /** @description The issuer's own word, preserved (`ERROR`). */ + provider_status: string | null; + /** @description When CodeSpar closed the charge as failed. */ + failed_at: string | null; + }; + /** @description True whenever the issuer's known state and ours disagree, instead of one of them silently winning. They agree only as follows: our `pending` beside the issuer's PENDING or PROCESSING; our `settled` beside CONFIRMED or PENDING (the issuer's read can lag a payment); our `expired` beside CANCELLED or PENDING (lag after a cancel); our `failed` beside ERROR (the refusal it records). Every other pair is a conflict, including an issuer ERROR, an issuer terminal state on a charge we still hold open, and a status spelling we do not recognise. False when no issuer state is known at all. `settlement: "unconfirmable"` is the narrower case of both sides terminal and different. */ status_conflict: boolean; method: string; currency: string; @@ -18881,9 +21823,18 @@ export interface paths { * **A charge settled by the sandbox payer answers `CONFIRMED` here**, the same value a real payment leaves a live read answering — so a client that polls `status` sees the test payment exactly where it would see a live one. The issuer's homolog account never sees that money and keeps answering PENDING (EXPIRED after the due date); that answer stays in `raw` and is not reported as `status` or as a `status_conflict`, because for a test charge the fixture is the issuer's truth. `settlement: "confirmed"` and `local_status: "settled"` say the same thing from our side. Any other issuer answer (ERROR, CANCELLED, PROCESSING) is reported as the issuer said it, with `status_conflict: true`. */ status: string; - /** @description What CodeSpar recorded, which is a different question from `status`. */ + /** @description What CodeSpar recorded, which is a different question from `status`: `pending`, `settled`, `expired` (cancelled or expired unpaid) or `failed`. `failed` is terminal: the issuer refused to register the charge (`status: "ERROR"`, no boleto and no Pix ever issued), so nothing was ever payable and nothing was charged; `failure` says why. Create a new charge. PROCESSING, a slow registration or a missing callback are never `failed`. */ local_status: string; - /** @description True whenever the issuer's known state and ours disagree, instead of one of them silently winning. They agree only as follows: our `pending` beside the issuer's PENDING or PROCESSING; our `settled` beside CONFIRMED or PENDING (the issuer's read can lag a payment); our `expired` beside CANCELLED or PENDING (lag after a cancel). Every other pair is a conflict, including an issuer ERROR, an issuer terminal state on a charge we still hold open, and a status spelling we do not recognise. False when no issuer state is known at all. `settlement: "unconfirmable"` is the narrower case of both sides terminal and different. */ + /** @description Present only when `local_status` is `failed`. The charge's history, ids and correlation stay readable; `commerce.charge.failed` was published once when it closed. */ + failure?: { + /** @description `issuer_rejected`: the issuer refused to register the charge. */ + code: string; + /** @description The issuer's own word, preserved (`ERROR`). */ + provider_status: string | null; + /** @description When CodeSpar closed the charge as failed. */ + failed_at: string | null; + }; + /** @description True whenever the issuer's known state and ours disagree, instead of one of them silently winning. They agree only as follows: our `pending` beside the issuer's PENDING or PROCESSING; our `settled` beside CONFIRMED or PENDING (the issuer's read can lag a payment); our `expired` beside CANCELLED or PENDING (lag after a cancel); our `failed` beside ERROR (the refusal it records). Every other pair is a conflict, including an issuer ERROR, an issuer terminal state on a charge we still hold open, and a status spelling we do not recognise. False when no issuer state is known at all. `settlement: "unconfirmable"` is the narrower case of both sides terminal and different. */ status_conflict: boolean; method: string; currency: string; @@ -19013,7 +21964,7 @@ export interface paths { put?: never; /** * Pay a charge in the sandbox - * @description Plays the DEBTOR of a test charge: settles it through the SAME path a Celcoin `charge-in` webhook takes (translate, publish `commerce.charge.paid`, reconcile, ledger `fund()` with the `pending -> settled` claim). It is not a status write, so the event fans out to your triggers exactly as a real payment would, and the ledger and receipt side effects are the ones production produces. + * @description Plays the DEBTOR of a test charge: settles it through the SAME path a Celcoin `charge-in` webhook takes (translate, reconcile, ledger `fund()` with the `pending -> settled` claim, and `commerce.charge.paid` written by that same settling transaction). It is not a status write, so the event fans out to your triggers exactly as a real payment would, and the ledger and receipt side effects are the ones production produces. * * **Test-mode only, fail-closed.** A live-environment key or project answers 403 `sandbox_pay_not_permitted` before the body is read or any query runs. * @@ -19146,7 +22097,7 @@ export interface paths { }; }; }; - /** @description The charge exists and cannot be paid, and nothing was settled, credited or published: `issuance_unconfirmed` is a reservation whose create never got an answer; `charge_not_payable` is a charge with no document a debtor could pay, and `details.reason` says which: `issuer_rejected` (the issuer left it in ERROR, no boleto or Pix ever existed — terminal, create a new charge), `charge_closed` (expired or cancelled, ours or the issuer's — terminal, create a new charge), `instrument_not_registered` (the issuer has not handed over a boleto or Pix yet — read the charge and pay once it answers `payable: true`); `charge_reference_ambiguous` is a reference that is one charge's id and another's idempotency key — pay by the charge id; `collect_simulated_settle_refused` is a Collect link's charge, issued on a real rail: in Test it is paid with POST /v1/collect/attempts/{attemptId}/test-pay (`details.next_action`), never by this simulation. */ + /** @description The charge exists and cannot be paid, and nothing was settled, credited or published: `issuance_unconfirmed` is a reservation whose create never got an answer; `charge_not_payable` is a charge with no document a debtor could pay, and `details.reason` says which: `issuer_rejected` (the issuer left it in ERROR, no boleto or Pix ever existed, and the charge reads `local_status: "failed"` once closed — terminal, create a new charge), `charge_closed` (expired or cancelled, ours or the issuer's — terminal, create a new charge), `instrument_not_registered` (the issuer has not handed over a boleto or Pix yet — read the charge and pay once it answers `payable: true`); `charge_reference_ambiguous` is a reference that is one charge's id and another's idempotency key — pay by the charge id; `collect_simulated_settle_refused` is a Collect link's charge, issued on a real rail: in Test it is paid with POST /v1/collect/attempts/{attemptId}/test-pay (`details.next_action`), never by this simulation. */ 409: { headers: { [name: string]: unknown; @@ -19208,7 +22159,7 @@ export interface paths { * @deprecated * @description Alias of `POST /v1/test/charges/{chargeId}/pay` (ent#979 contract: one handler, two paths, one scope). Same body, same answers. * - * Plays the DEBTOR of a test charge: settles it through the SAME path a Celcoin `charge-in` webhook takes (translate, publish `commerce.charge.paid`, reconcile, ledger `fund()` with the `pending -> settled` claim). It is not a status write, so the event fans out to your triggers exactly as a real payment would, and the ledger and receipt side effects are the ones production produces. + * Plays the DEBTOR of a test charge: settles it through the SAME path a Celcoin `charge-in` webhook takes (translate, reconcile, ledger `fund()` with the `pending -> settled` claim, and `commerce.charge.paid` written by that same settling transaction). It is not a status write, so the event fans out to your triggers exactly as a real payment would, and the ledger and receipt side effects are the ones production produces. * * **Test-mode only, fail-closed.** A live-environment key or project answers 403 `sandbox_pay_not_permitted` before the body is read or any query runs. * @@ -19341,7 +22292,7 @@ export interface paths { }; }; }; - /** @description The charge exists and cannot be paid, and nothing was settled, credited or published: `issuance_unconfirmed` is a reservation whose create never got an answer; `charge_not_payable` is a charge with no document a debtor could pay, and `details.reason` says which: `issuer_rejected` (the issuer left it in ERROR, no boleto or Pix ever existed — terminal, create a new charge), `charge_closed` (expired or cancelled, ours or the issuer's — terminal, create a new charge), `instrument_not_registered` (the issuer has not handed over a boleto or Pix yet — read the charge and pay once it answers `payable: true`); `charge_reference_ambiguous` is a reference that is one charge's id and another's idempotency key — pay by the charge id; `collect_simulated_settle_refused` is a Collect link's charge, issued on a real rail: in Test it is paid with POST /v1/collect/attempts/{attemptId}/test-pay (`details.next_action`), never by this simulation. */ + /** @description The charge exists and cannot be paid, and nothing was settled, credited or published: `issuance_unconfirmed` is a reservation whose create never got an answer; `charge_not_payable` is a charge with no document a debtor could pay, and `details.reason` says which: `issuer_rejected` (the issuer left it in ERROR, no boleto or Pix ever existed, and the charge reads `local_status: "failed"` once closed — terminal, create a new charge), `charge_closed` (expired or cancelled, ours or the issuer's — terminal, create a new charge), `instrument_not_registered` (the issuer has not handed over a boleto or Pix yet — read the charge and pay once it answers `payable: true`); `charge_reference_ambiguous` is a reference that is one charge's id and another's idempotency key — pay by the charge id; `collect_simulated_settle_refused` is a Collect link's charge, issued on a real rail: in Test it is paid with POST /v1/collect/attempts/{attemptId}/test-pay (`details.next_action`), never by this simulation. */ 409: { headers: { [name: string]: unknown; @@ -28119,6 +31070,25 @@ export interface paths { detail: string; at: string; }[]; + /** + * @description Who executes (or executed) the payment, by the same name the integrator chooses with on POST /v1/consents. `codespar_simulator` ("Simulado pela CodeSpar": no provider is called) or `provider_sandbox` (the provider's sandbox, over the account the server bound to this consumer); both Test only. Null when no executor applies, Live included. The name is the MODE: the provider, account, project, consumer and environment are resolved by the server before the signature and checked again when the payment runs; no request field chooses them (`executor_provider_not_selectable`), and a provider failure is never turned into a simulation. Records written before this name existed keep their stored value and are read in these words. + * @enum {string|null} + */ + executor: "codespar_simulator" | "provider_sandbox" | null; + /** + * @description The concrete provider behind `executor`, as the server resolved it: `celcoin` for `provider_sandbox`; null for `codespar_simulator` (no provider is called) and when `executor` is null. Read-only. + * @enum {string|null} + */ + executor_provider: "celcoin" | null; + /** @description The executor's label as the consent screen, the dashboard and the receipt show it. In Test it ends "· sem dinheiro real". */ + executor_label: string | null; + /** + * @description The project's environment. + * @enum {string|null} + */ + environment: "test" | "live" | null; + /** @description False in Test, always: no real money moves, including when the provider's sandbox CONFIRMED the operation (`moneyMoved: true` / `settlement: "confirmed"` then mean the sandbox settled it). True in Live. */ + real_money: boolean | null; }[]; }; }; @@ -28267,6 +31237,25 @@ export interface paths { detail: string; at: string; }[]; + /** + * @description Who executes (or executed) the payment, by the same name the integrator chooses with on POST /v1/consents. `codespar_simulator` ("Simulado pela CodeSpar": no provider is called) or `provider_sandbox` (the provider's sandbox, over the account the server bound to this consumer); both Test only. Null when no executor applies, Live included. The name is the MODE: the provider, account, project, consumer and environment are resolved by the server before the signature and checked again when the payment runs; no request field chooses them (`executor_provider_not_selectable`), and a provider failure is never turned into a simulation. Records written before this name existed keep their stored value and are read in these words. + * @enum {string|null} + */ + executor: "codespar_simulator" | "provider_sandbox" | null; + /** + * @description The concrete provider behind `executor`, as the server resolved it: `celcoin` for `provider_sandbox`; null for `codespar_simulator` (no provider is called) and when `executor` is null. Read-only. + * @enum {string|null} + */ + executor_provider: "celcoin" | null; + /** @description The executor's label as the consent screen, the dashboard and the receipt show it. In Test it ends "· sem dinheiro real". */ + executor_label: string | null; + /** + * @description The project's environment. + * @enum {string|null} + */ + environment: "test" | "live" | null; + /** @description False in Test, always: no real money moves, including when the provider's sandbox CONFIRMED the operation (`moneyMoved: true` / `settlement: "confirmed"` then mean the sandbox settled it). True in Live. */ + real_money: boolean | null; /** @description On this point read only: who was paid, as the receipt document prints it under "Para". Read-side, outside the sealed fields. Fields the payment did not record are null, never backfilled. */ payee: { name: string | null; @@ -33448,7 +36437,7 @@ export interface paths { }; }; }; - /** @description Forbidden. The operation requires the `admin` role in the organization, resolved from the acting user forwarded in `x-codespar-user`. Known values of `error`: `insufficient_role`, `bearer_admin_role_missing`, `bearer_admin_user_not_member`, `bearer_admin_role_unresolved`. The same status and body shape also carry the scope gate's refusals, which reach every route in this subtree including the two reads: `forbidden` when the credential lacks the scope the route is mapped to, and the two alarms `scopes_unresolved` and `route_scope_unresolved`. */ + /** @description Forbidden. On the dashboard the operation requires the `admin` role in the organization, resolved from the acting user forwarded in `x-codespar-user` (`insufficient_role`). An API key carrying `mcp-servers:write` is not refused by that gate; an OAuth access token is (`insufficient_role`). The fee sweep is administrative: an API key gets `admin_session_required` there, whatever its scopes. The same status and body shape also carry the scope gate's refusals, which reach every route in this subtree including the two reads: `forbidden` when the credential lacks the scope the route is mapped to, and the two alarms `scopes_unresolved` and `route_scope_unresolved`. */ 403: { headers: { [name: string]: unknown; @@ -33712,7 +36701,7 @@ export interface paths { }; }; }; - /** @description Forbidden. The operation requires the `admin` role in the organization, resolved from the acting user forwarded in `x-codespar-user`. Known values of `error`: `insufficient_role`, `bearer_admin_role_missing`, `bearer_admin_user_not_member`, `bearer_admin_role_unresolved`. The same status and body shape also carry the scope gate's refusals, which reach every route in this subtree including the two reads: `forbidden` when the credential lacks the scope the route is mapped to, and the two alarms `scopes_unresolved` and `route_scope_unresolved`. */ + /** @description Forbidden. On the dashboard the operation requires the `admin` role in the organization, resolved from the acting user forwarded in `x-codespar-user` (`insufficient_role`). An API key carrying `mcp-servers:write` is not refused by that gate; an OAuth access token is (`insufficient_role`). The fee sweep is administrative: an API key gets `admin_session_required` there, whatever its scopes. The same status and body shape also carry the scope gate's refusals, which reach every route in this subtree including the two reads: `forbidden` when the credential lacks the scope the route is mapped to, and the two alarms `scopes_unresolved` and `route_scope_unresolved`. */ 403: { headers: { [name: string]: unknown; @@ -33903,7 +36892,7 @@ export interface paths { }; content?: never; }; - /** @description Forbidden. The operation requires the `admin` role in the organization, resolved from the acting user forwarded in `x-codespar-user`. Known values of `error`: `insufficient_role`, `bearer_admin_role_missing`, `bearer_admin_user_not_member`, `bearer_admin_role_unresolved`. The same status and body shape also carry the scope gate's refusals, which reach every route in this subtree including the two reads: `forbidden` when the credential lacks the scope the route is mapped to, and the two alarms `scopes_unresolved` and `route_scope_unresolved`. */ + /** @description Forbidden. On the dashboard the operation requires the `admin` role in the organization, resolved from the acting user forwarded in `x-codespar-user` (`insufficient_role`). An API key carrying `mcp-servers:write` is not refused by that gate; an OAuth access token is (`insufficient_role`). The fee sweep is administrative: an API key gets `admin_session_required` there, whatever its scopes. The same status and body shape also carry the scope gate's refusals, which reach every route in this subtree including the two reads: `forbidden` when the credential lacks the scope the route is mapped to, and the two alarms `scopes_unresolved` and `route_scope_unresolved`. */ 403: { headers: { [name: string]: unknown; @@ -34069,7 +37058,7 @@ export interface paths { }; }; }; - /** @description Forbidden. The operation requires the `admin` role in the organization, resolved from the acting user forwarded in `x-codespar-user`. Known values of `error`: `insufficient_role`, `bearer_admin_role_missing`, `bearer_admin_user_not_member`, `bearer_admin_role_unresolved`. The same status and body shape also carry the scope gate's refusals, which reach every route in this subtree including the two reads: `forbidden` when the credential lacks the scope the route is mapped to, and the two alarms `scopes_unresolved` and `route_scope_unresolved`. */ + /** @description Forbidden. On the dashboard the operation requires the `admin` role in the organization, resolved from the acting user forwarded in `x-codespar-user` (`insufficient_role`). An API key carrying `mcp-servers:write` is not refused by that gate; an OAuth access token is (`insufficient_role`). The fee sweep is administrative: an API key gets `admin_session_required` there, whatever its scopes. The same status and body shape also carry the scope gate's refusals, which reach every route in this subtree including the two reads: `forbidden` when the credential lacks the scope the route is mapped to, and the two alarms `scopes_unresolved` and `route_scope_unresolved`. */ 403: { headers: { [name: string]: unknown; @@ -34197,7 +37186,7 @@ export interface paths { }; }; }; - /** @description Forbidden. The operation requires the `admin` role in the organization, resolved from the acting user forwarded in `x-codespar-user`. Known values of `error`: `insufficient_role`, `bearer_admin_role_missing`, `bearer_admin_user_not_member`, `bearer_admin_role_unresolved`. The same status and body shape also carry the scope gate's refusals, which reach every route in this subtree including the two reads: `forbidden` when the credential lacks the scope the route is mapped to, and the two alarms `scopes_unresolved` and `route_scope_unresolved`. */ + /** @description Forbidden. On the dashboard the operation requires the `admin` role in the organization, resolved from the acting user forwarded in `x-codespar-user` (`insufficient_role`). An API key carrying `mcp-servers:write` is not refused by that gate; an OAuth access token is (`insufficient_role`). The fee sweep is administrative: an API key gets `admin_session_required` there, whatever its scopes. The same status and body shape also carry the scope gate's refusals, which reach every route in this subtree including the two reads: `forbidden` when the credential lacks the scope the route is mapped to, and the two alarms `scopes_unresolved` and `route_scope_unresolved`. */ 403: { headers: { [name: string]: unknown; @@ -34262,7 +37251,7 @@ export interface paths { * * 503 `payto_provisioning_unavailable` is broader than its name: the handler maps EVERY error thrown by the pass to that one code, so it covers a database failure during the sweep as well as a platform wallet that could not be provisioned. * - * This operation needs the `platform-fees:sweep` scope, which the other seven do not. + * Administrative, unlike the other seven: an admin or owner performs it from the dashboard, and an API key is refused with 403 `admin_session_required`, whatever its scopes. */ post: { parameters: { @@ -34299,7 +37288,7 @@ export interface paths { }; }; }; - /** @description Forbidden. The operation requires the `admin` role in the organization, resolved from the acting user forwarded in `x-codespar-user`. Known values of `error`: `insufficient_role`, `bearer_admin_role_missing`, `bearer_admin_user_not_member`, `bearer_admin_role_unresolved`. The same status and body shape also carry the scope gate's refusals, which reach every route in this subtree including the two reads: `forbidden` when the credential lacks the scope the route is mapped to, and the two alarms `scopes_unresolved` and `route_scope_unresolved`. */ + /** @description Forbidden. On the dashboard the operation requires the `admin` role in the organization, resolved from the acting user forwarded in `x-codespar-user` (`insufficient_role`). An API key carrying `mcp-servers:write` is not refused by that gate; an OAuth access token is (`insufficient_role`). The fee sweep is administrative: an API key gets `admin_session_required` there, whatever its scopes. The same status and body shape also carry the scope gate's refusals, which reach every route in this subtree including the two reads: `forbidden` when the credential lacks the scope the route is mapped to, and the two alarms `scopes_unresolved` and `route_scope_unresolved`. */ 403: { headers: { [name: string]: unknown; @@ -37060,27 +40049,20 @@ export interface paths { }; }; }; - /** @description Forbidden. The acting user does not satisfy the org-role guard in front of this route. With an OAuth access token this is the live behaviour when `x-codespar-user` is absent or names a user below admin; with an API key it appears only where the deployment enforces the same guard. */ + /** @description Forbidden. The org-role guard in front of this route refused. It refuses an OAuth access token, which is not the dashboard, whatever `x-codespar-user` says. An API key is not refused by this guard: its grant is its scope. */ 403: { headers: { [name: string]: unknown; }; content: { "application/json": { - /** @description `insufficient_role` on the ordinary path. */ - error: string; + /** @enum {string} */ + error: "insufficient_role"; /** * @description The minimum org role this route asks for. * @enum {string} */ required: "admin"; - /** @description Present only on the enforced API-key path. */ - message?: string; - /** - * @description Present only on the enforced API-key path. - * @enum {number} - */ - status?: 403; }; }; }; @@ -37226,11 +40208,7 @@ export interface paths { * * The slug returns to the global namespace and any other tenant may then claim it, so a delete-and-recreate is not guaranteed to get the same gateway URL back. * - * AUTHORIZATION, as deployed rather than as named, and it is NOT the same for the two credentials this document describes. - * - * With an OAUTH ACCESS TOKEN the org-role guard in front of this route is ordinary and live: the acting user must be forwarded in `x-codespar-user` and must hold at least the admin role in the organization. No header, or a user who is not an admin, is 403 `insufficient_role` before the handler runs. - * - * With an API KEY the same guard is in a measurement window: it resolves the forwarded user, RECORDS the request when that user would not have sufficed, and lets it through anyway. So today a key carrying `paywalls:write` deletes without forwarding anybody. A deployment that closes the window refuses those calls with 403 as well, so forward `x-codespar-user` if you have it: it is already required on the token path, it is inert on the key path while the window is open, and it is what keeps the call working when the window closes. + * AUTHORIZATION. With an API KEY the grant is the key's scope: a key carrying `paywalls:write` deletes, and `x-codespar-user` is not read. Only an admin mints a key. An OAUTH ACCESS TOKEN is refused with 403 `insufficient_role` before the handler runs: this write belongs to a key or to the dashboard. */ delete: { parameters: { @@ -37250,27 +40228,20 @@ export interface paths { }; content?: never; }; - /** @description Forbidden. The acting user does not satisfy the org-role guard in front of this route. With an OAuth access token this is the live behaviour when `x-codespar-user` is absent or names a user below admin; with an API key it appears only where the deployment enforces the same guard. */ + /** @description Forbidden. The org-role guard in front of this route refused. It refuses an OAuth access token, which is not the dashboard, whatever `x-codespar-user` says. An API key is not refused by this guard: its grant is its scope. */ 403: { headers: { [name: string]: unknown; }; content: { "application/json": { - /** @description `insufficient_role` on the ordinary path. */ - error: string; + /** @enum {string} */ + error: "insufficient_role"; /** * @description The minimum org role this route asks for. * @enum {string} */ required: "admin"; - /** @description Present only on the enforced API-key path. */ - message?: string; - /** - * @description Present only on the enforced API-key path. - * @enum {number} - */ - status?: 403; }; }; }; @@ -37425,27 +40396,20 @@ export interface paths { }; }; }; - /** @description Forbidden. The acting user does not satisfy the org-role guard in front of this route. With an OAuth access token this is the live behaviour when `x-codespar-user` is absent or names a user below admin; with an API key it appears only where the deployment enforces the same guard. */ + /** @description Forbidden. The org-role guard in front of this route refused. It refuses an OAuth access token, which is not the dashboard, whatever `x-codespar-user` says. An API key is not refused by this guard: its grant is its scope. */ 403: { headers: { [name: string]: unknown; }; content: { "application/json": { - /** @description `insufficient_role` on the ordinary path. */ - error: string; + /** @enum {string} */ + error: "insufficient_role"; /** * @description The minimum org role this route asks for. * @enum {string} */ required: "admin"; - /** @description Present only on the enforced API-key path. */ - message?: string; - /** - * @description Present only on the enforced API-key path. - * @enum {number} - */ - status?: 403; }; }; }; @@ -45289,6 +48253,26 @@ export interface paths { }; }; }; + /** @description A Test project the own-account rule reaches has no own account yet: there is no account to state, so no statement (never the simulator's residue as the account's, nor an empty one closing at 0). */ + 409: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + /** @enum {string} */ + code: "statement_account_missing"; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; /** @description The ledger of the period does not reconcile; logged, nothing served. */ 500: { headers: { @@ -45975,6 +48959,82 @@ export interface paths { patch?: never; trace?: never; }; + "/v1/shop/agent/capabilities": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * What the Shop can do in this project and mode + * @description Scope `shop:purchases:read`. The seven tasks, always all seven and in this order: `research`, `purchase`, `reserve`, `pay_pix`, `pay_boleto`, `pay_dda`, `receive_pix`. Each is `available` (an executable path is wired and on for the key's project in its mode; `scope` narrows what it covers, e.g. `test_store`: the synthetic test store only), `needs_step` (it waits for a person's act, named by `step`: `resume_shop_mandate`, `rebind_integrated_proof`, `confirm_shop_mandate`) or `unavailable` (`reason`, a code for logs and mapping). Derived from the gates the Shop's own paths read, the same answer the Shop's dashboard reads: researching is not reserving, and reserving is not paying (`reserve` has no executor). A mandate never signed is not a step in Test; it is confirmed by a person when a payment first needs it. Reads only: nothing is provisioned, signed or enabled, in Test or in Live. Served whatever `SHOP_PURCHASES_ENABLED` says: a switch that is off is answered as the reason of the tasks it gates. + */ + get: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description OK */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + project_id: string; + /** @enum {string} */ + environment: "test" | "live"; + capabilities: { + /** @enum {string} */ + task: "research" | "purchase" | "reserve" | "pay_pix" | "pay_boleto" | "pay_dda" | "receive_pix"; + /** @enum {string} */ + state: "available" | "needs_step" | "unavailable"; + /** @description Only with needs_step: the person's act it waits for. */ + step: string | null; + /** @description Only with unavailable: a code for logs and mapping, never shown raw. */ + reason: string | null; + /** @description What available covers, e.g. test_store: the synthetic test store only. */ + scope: string | null; + }[]; + /** @description When the gates were read (ISO 8601). */ + as_of: string; + }; + }; + }; + /** @description The key does not hold `shop:purchases:read`. */ + 403: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + error: { + code: string; + message: string; + details?: { + [key: string]: unknown; + }; + }; + /** @description Echoes the `X-Request-Id` header when the request carried one. */ + request_id: string | null; + }; + }; + }; + }; + }; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; "/v1/shop/agent/instruments": { parameters: { query?: never; @@ -46112,9 +49172,7 @@ export interface paths { * Create a project * @description Creates a project in the organization this credential resolves to. * - * ROLE. This is an administrative operation and it carries the `admin` role gate. On a credential of the kind this document describes — an API key or an OAuth access token — that gate does NOT refuse today. It resolves the user forwarded in the `x-codespar-user` header against this organization's members, records the outcome when no user was forwarded, the user is not a member of the organization, or the user ranks below `admin`, and then lets the request through. Refusal is behind a server-side rollout flag that is currently off. Forward an `admin` or `owner` user in `x-codespar-user` now: when the flag is turned on, a call that does not carry one starts being answered with 403 instead of being served. - * - * SCOPE. A key created with an explicit scope list needs `projects:write` and is answered with 403 without it. A wildcard key passes: the wildcard is what a key gets when it is created without an explicit list, which is every key by default. + * ROLE. This is an administrative operation: an `admin` or `owner` performs it from the dashboard. An API key is refused with 403 `admin_session_required`, whatever its scopes and even on the project it was issued in. `x-codespar-user` is not read for an API key. An OAuth access token is refused with 403 `insufficient_role`. * * `slug` is unique per organization, lowercase alphanumerics plus `_` and `-`, at most 64 characters, and `default` is reserved because the auto-seeded first project already holds it. A slug already taken in the organization is refused with 400 and code `slug_conflict`, not 409, and `details.slug` echoes the value that collided. * @@ -46297,9 +49355,7 @@ export interface paths { * Delete a project * @description A hard delete, not a soft one: the project row is removed and most of what hangs off it goes with it. 204 with no body on success. * - * ROLE. This is an administrative operation and it carries the `admin` role gate. On a credential of the kind this document describes — an API key or an OAuth access token — that gate does NOT refuse today. It resolves the user forwarded in the `x-codespar-user` header against this organization's members, records the outcome when no user was forwarded, the user is not a member of the organization, or the user ranks below `admin`, and then lets the request through. Refusal is behind a server-side rollout flag that is currently off. Forward an `admin` or `owner` user in `x-codespar-user` now: when the flag is turned on, a call that does not carry one starts being answered with 403 instead of being served. - * - * SCOPE. A key created with an explicit scope list needs `projects:write` and is answered with 403 without it. A wildcard key passes: the wildcard is what a key gets when it is created without an explicit list, which is every key by default. + * ROLE. This is an administrative operation: an `admin` or `owner` performs it from the dashboard. An API key is refused with 403 `admin_session_required`, whatever its scopes and even on the project it was issued in. `x-codespar-user` is not read for an API key. An OAuth access token is refused with 403 `insufficient_role`. * * Four refusals, all 409 because the request is well formed and conflicts with an invariant the organization relies on: * @@ -46378,9 +49434,7 @@ export interface paths { * Rename a project, change its slug, or promote it to default * @description At least one field must be present; an empty body is refused with 400. * - * ROLE. This is an administrative operation and it carries the `admin` role gate. On a credential of the kind this document describes — an API key or an OAuth access token — that gate does NOT refuse today. It resolves the user forwarded in the `x-codespar-user` header against this organization's members, records the outcome when no user was forwarded, the user is not a member of the organization, or the user ranks below `admin`, and then lets the request through. Refusal is behind a server-side rollout flag that is currently off. Forward an `admin` or `owner` user in `x-codespar-user` now: when the flag is turned on, a call that does not carry one starts being answered with 403 instead of being served. - * - * SCOPE. A key created with an explicit scope list needs `projects:write` and is answered with 403 without it. A wildcard key passes: the wildcard is what a key gets when it is created without an explicit list, which is every key by default. + * ROLE. This is an administrative operation: an `admin` or `owner` performs it from the dashboard. An API key is refused with 403 `admin_session_required`, whatever its scopes and even on the project it was issued in. `x-codespar-user` is not read for an API key. An OAuth access token is refused with 403 `insufficient_role`. * * `is_default` accepts `true` and nothing else. A project cannot be un-defaulted, and the only way to move the default is to promote a different project: the previous default is cleared and the new one set in one transaction, so no committed state ever shows two defaults. Promoting a project that is already the default is a no-op. * @@ -46492,9 +49546,9 @@ export interface paths { * Archive a project * @description The way out for a project that cannot be deleted because it holds records: nothing is deleted, moved or revoked. It is refused while the project has open money obligations (409 `project_has_open_operations`), so nothing recurring stops in silence. An archived project leaves `GET /v1/projects` (list it with `?include_archived=1`), its API keys and OAuth tokens are refused with 403 `project_archived`, the dashboard's writes in it too, and the workers start nothing for it; provider events of objects created before keep being recorded. The organization's default project is not archived (409 `cannot_archive_default`). Asking for the state the project is already in answers 200 with `changed: false`. Recorded in the organization's audit log. * - * ROLE. This is an administrative operation and it carries the `admin` role gate. On a credential of the kind this document describes — an API key or an OAuth access token — that gate does NOT refuse today. It resolves the user forwarded in the `x-codespar-user` header against this organization's members, records the outcome when no user was forwarded, the user is not a member of the organization, or the user ranks below `admin`, and then lets the request through. Refusal is behind a server-side rollout flag that is currently off. Forward an `admin` or `owner` user in `x-codespar-user` now: when the flag is turned on, a call that does not carry one starts being answered with 403 instead of being served. + * ROLE. This is an administrative operation: an `admin` or `owner` performs it from the dashboard. An API key is refused with 403 `admin_session_required`, whatever its scopes and even on the project it was issued in. `x-codespar-user` is not read for an API key. An OAuth access token is refused with 403 `insufficient_role`. + * * - * SCOPE. A key created with an explicit scope list needs `projects:write` and is answered with 403 without it. A wildcard key passes: the wildcard is what a key gets when it is created without an explicit list, which is every key by default. * * A cross-tenant id is 404, not 403. */ @@ -46586,9 +49640,9 @@ export interface paths { * Unarchive a project * @description Restores an archived project as it was: listed again, its keys and operations accepted. Asking for the state the project is already in answers 200 with `changed: false`. Recorded in the organization's audit log. * - * ROLE. This is an administrative operation and it carries the `admin` role gate. On a credential of the kind this document describes — an API key or an OAuth access token — that gate does NOT refuse today. It resolves the user forwarded in the `x-codespar-user` header against this organization's members, records the outcome when no user was forwarded, the user is not a member of the organization, or the user ranks below `admin`, and then lets the request through. Refusal is behind a server-side rollout flag that is currently off. Forward an `admin` or `owner` user in `x-codespar-user` now: when the flag is turned on, a call that does not carry one starts being answered with 403 instead of being served. + * ROLE. This is an administrative operation: an `admin` or `owner` performs it from the dashboard. An API key is refused with 403 `admin_session_required`, whatever its scopes and even on the project it was issued in. `x-codespar-user` is not read for an API key. An OAuth access token is refused with 403 `insufficient_role`. + * * - * SCOPE. A key created with an explicit scope list needs `projects:write` and is answered with 403 without it. A wildcard key passes: the wildcard is what a key gets when it is created without an explicit list, which is every key by default. * * A cross-tenant id is 404, not 403. */ @@ -46660,7 +49714,7 @@ export interface paths { * * SCOPE. A key created with an explicit scope list needs `projects:settings` and is answered with 403 without it. A wildcard key passes: the wildcard is what a key gets when it is created without an explicit list, which is every key by default. * - * This read alone carries NO role gate. The write and the history read below both do, and what that gate currently does is described on each of them. + * This read alone carries NO role gate. The write and the history read below both do, and what that gate does is described on each of them. An API key reads only the project it was issued in: another `{id}` is 403 `api_key_other_project`. * * The list is filtered by environment: a setting declared test-only does not appear on a live project at all, so an empty list is a normal answer rather than an error. A stored value whose key is no longer declared is omitted too. Every setting the registry declares as this is written applies to `test` only, which makes an empty list what a `live` project returns — a fact about the current declarations, not about this route. * @@ -46740,9 +49794,7 @@ export interface paths { * Set or reset a project's settings * @description The body is `{ "settings": { : } }`. A `null` value RESETS that key to default-tracking; it does not store null. Multiple keys in one call are applied together. * - * ROLE. This is an administrative operation and it carries the `admin` role gate. On a credential of the kind this document describes — an API key or an OAuth access token — that gate does NOT refuse today. It resolves the user forwarded in the `x-codespar-user` header against this organization's members, records the outcome when no user was forwarded, the user is not a member of the organization, or the user ranks below `admin`, and then lets the request through. Refusal is behind a server-side rollout flag that is currently off. Forward an `admin` or `owner` user in `x-codespar-user` now: when the flag is turned on, a call that does not carry one starts being answered with 403 instead of being served. - * - * SCOPE. A key created with an explicit scope list needs `projects:settings` and is answered with 403 without it. A wildcard key passes: the wildcard is what a key gets when it is created without an explicit list, which is every key by default. + * ROLE. This is an administrative operation: an `admin` or `owner` performs it from the dashboard. An API key is refused with 403 `admin_session_required`, whatever its scopes and even on the project it was issued in. `x-codespar-user` is not read for an API key. An OAuth access token is refused with 403 `insufficient_role`. * * The whole batch is validated against the settings registry before anything is written, so one bad entry rejects the entire call and nothing changes. An unknown key, a value of the wrong type, or a key that does not apply to the project's environment is 400 `invalid_body` with `details.key` naming the offender. An empty `settings` object is 400 as well, with no `details`. * @@ -46860,9 +49912,7 @@ export interface paths { * Read a project's settings audit log * @description The ordered change history for this project's settings, oldest first. * - * ROLE. This is an administrative operation and it carries the `admin` role gate. On a credential of the kind this document describes — an API key or an OAuth access token — that gate does NOT refuse today. It resolves the user forwarded in the `x-codespar-user` header against this organization's members, records the outcome when no user was forwarded, the user is not a member of the organization, or the user ranks below `admin`, and then lets the request through. Refusal is behind a server-side rollout flag that is currently off. Forward an `admin` or `owner` user in `x-codespar-user` now: when the flag is turned on, a call that does not carry one starts being answered with 403 instead of being served. - * - * SCOPE. A key created with an explicit scope list needs `projects:settings` and is answered with 403 without it. A wildcard key passes: the wildcard is what a key gets when it is created without an explicit list, which is every key by default. + * ROLE. This is an administrative operation: an `admin` or `owner` performs it from the dashboard. An API key is refused with 403 `admin_session_required`, whatever its scopes and even on the project it was issued in. `x-codespar-user` is not read for an API key. An OAuth access token is refused with 403 `insufficient_role`. * * One entry per key that actually changed, so a call that wrote a value an already-explicit key was already holding leaves no trace here. Note what does leave a trace: writing a key's own default value while it is still tracking that default is a change, and it lands here with `old_value` equal to `new_value`. `explicit_before` and `explicit_after` are what separate a reset from a write: a reset ends with `explicit_after: false` and a `new_value` equal to the declared default. * @@ -46973,11 +50023,13 @@ export interface paths { /** @enum {string} */ environment: "live" | "test"; /** - * @description `confirm_each`: a person confirms every payment. `confirm_exceptions`: a payment above `exception_amount_minor`, or to a payee never paid, waits for a person. `within_mandate`: the agent pays inside the mandate unconfirmed. No level widens a mandate. A project that never changed it is at `confirm_each`. - * @enum {string} + * @description The level the payment step applies. `confirm_each`: a person confirms every payment. `confirm_exceptions`: a payment above `exception_amount_minor`, or to a payee never paid, waits for a person. `within_mandate`: the agent pays inside the mandate unconfirmed. No level widens a mandate. A test project that never changed it is at `confirm_each`. Null where no level applies (a live project, or a deployment that releases none): there the agent pays within the mandate and the project's approval rules, with no per-payment confirmation. + * @enum {string|null} */ - level: "confirm_each" | "confirm_exceptions" | "within_mandate"; - /** @description The threshold of `confirm_exceptions`, in minor units; null at the other levels. */ + level: "confirm_each" | "confirm_exceptions" | "within_mandate" | null; + /** @description Whether the agent's autonomy applies to this project's payments now. False on a live project, where `level` is null. */ + applies: boolean; + /** @description The threshold of `confirm_exceptions`, in minor units; null at the other levels and where no level applies. */ exception_amount_minor: number | null; /** @description Send it back on the PUT. 0 for a project that never changed its level. */ version: number; @@ -46991,6 +50043,15 @@ export interface paths { * @enum {string|null} */ live_activation: "pending" | null; + /** @description The organization's approval rules that hold a payment for a person, in the engine's order and by its first-match scan. They apply in every environment; in a live project, where no autonomy level applies, these and the mandate's limits are what stand before a payment. */ + payment_approval_rules: { + id: string; + name: string; + /** @description The agents it applies to (`*` for all). */ + agents: string[]; + /** @description The payment tools it holds for a person: `consumer_payment:execute` (every consumer payment door), `codespar_pay`, `codespar_crypto_pay`, `codespar_shop`. */ + payment_tools: string[]; + }[]; }; }; }; @@ -47058,11 +50119,13 @@ export interface paths { /** @enum {string} */ environment: "live" | "test"; /** - * @description `confirm_each`: a person confirms every payment. `confirm_exceptions`: a payment above `exception_amount_minor`, or to a payee never paid, waits for a person. `within_mandate`: the agent pays inside the mandate unconfirmed. No level widens a mandate. A project that never changed it is at `confirm_each`. - * @enum {string} + * @description The level the payment step applies. `confirm_each`: a person confirms every payment. `confirm_exceptions`: a payment above `exception_amount_minor`, or to a payee never paid, waits for a person. `within_mandate`: the agent pays inside the mandate unconfirmed. No level widens a mandate. A test project that never changed it is at `confirm_each`. Null where no level applies (a live project, or a deployment that releases none): there the agent pays within the mandate and the project's approval rules, with no per-payment confirmation. + * @enum {string|null} */ - level: "confirm_each" | "confirm_exceptions" | "within_mandate"; - /** @description The threshold of `confirm_exceptions`, in minor units; null at the other levels. */ + level: "confirm_each" | "confirm_exceptions" | "within_mandate" | null; + /** @description Whether the agent's autonomy applies to this project's payments now. False on a live project, where `level` is null. */ + applies: boolean; + /** @description The threshold of `confirm_exceptions`, in minor units; null at the other levels and where no level applies. */ exception_amount_minor: number | null; /** @description Send it back on the PUT. 0 for a project that never changed its level. */ version: number; @@ -47076,6 +50139,15 @@ export interface paths { * @enum {string|null} */ live_activation: "pending" | null; + /** @description The organization's approval rules that hold a payment for a person, in the engine's order and by its first-match scan. They apply in every environment; in a live project, where no autonomy level applies, these and the mandate's limits are what stand before a payment. */ + payment_approval_rules: { + id: string; + name: string; + /** @description The agents it applies to (`*` for all). */ + agents: string[]; + /** @description The payment tools it holds for a person: `consumer_payment:execute` (every consumer payment door), `codespar_pay`, `codespar_crypto_pay`, `codespar_shop`. */ + payment_tools: string[]; + }[]; }; }; }; @@ -48102,9 +51174,9 @@ export interface paths { }; }; /** - * @description Forbidden. This write is gated on an organization role, and the guard refused. It is reachable with an OAuth access token or a service credential: either no acting user was forwarded in the `x-codespar-user` header, or the user it named does not hold at least `admin` in the organization. Re-sending the same header will not help in the second case — promote that user, or forward one who already qualifies. + * @description Forbidden. This write is gated on an organization role, and the guard refused. It refuses an OAuth access token, which is not the dashboard, whatever `x-codespar-user` says. * - * AN API KEY IS NOT REFUSED HERE TODAY. The role requirement is not enforced for that credential at this version, so a key alone completes the write and a 200 is not evidence that anyone holding `admin` authorized it. Plan for the header: it is the arm that will be closed. + * An API key is not refused by this guard: a key carries no role, its grant is its scope (`payment-links:write`), and only an admin mints a key. `x-codespar-user` is not read for a key. */ 403: { headers: { @@ -48535,9 +51607,9 @@ export interface paths { content?: never; }; /** - * @description Forbidden. This write is gated on an organization role, and the guard refused. It is reachable with an OAuth access token or a service credential: either no acting user was forwarded in the `x-codespar-user` header, or the user it named does not hold at least `admin` in the organization. Re-sending the same header will not help in the second case — promote that user, or forward one who already qualifies. + * @description Forbidden. This write is gated on an organization role, and the guard refused. It refuses an OAuth access token, which is not the dashboard, whatever `x-codespar-user` says. * - * AN API KEY IS NOT REFUSED HERE TODAY. The role requirement is not enforced for that credential at this version, so a key alone completes the write and a 200 is not evidence that anyone holding `admin` authorized it. Plan for the header: it is the arm that will be closed. + * An API key is not refused by this guard: a key carries no role, its grant is its scope (`payment-links:write`), and only an admin mints a key. `x-codespar-user` is not read for a key. */ 403: { headers: { @@ -48698,9 +51770,9 @@ export interface paths { }; }; /** - * @description Forbidden. This write is gated on an organization role, and the guard refused. It is reachable with an OAuth access token or a service credential: either no acting user was forwarded in the `x-codespar-user` header, or the user it named does not hold at least `admin` in the organization. Re-sending the same header will not help in the second case — promote that user, or forward one who already qualifies. + * @description Forbidden. This write is gated on an organization role, and the guard refused. It refuses an OAuth access token, which is not the dashboard, whatever `x-codespar-user` says. * - * AN API KEY IS NOT REFUSED HERE TODAY. The role requirement is not enforced for that credential at this version, so a key alone completes the write and a 200 is not evidence that anyone holding `admin` authorized it. Plan for the header: it is the arm that will be closed. + * An API key is not refused by this guard: a key carries no role, its grant is its scope (`payment-links:write`), and only an admin mints a key. `x-codespar-user` is not read for a key. */ 403: { headers: { @@ -52494,6 +55566,25 @@ export interface components { called_at: string; routing?: unknown; failover_trail?: unknown; + /** @description Who triggered the call, as its authentication knew it (0408). Null when not recorded; never inferred from a mandate or a session. */ + actor?: { + /** + * @description How the caller authenticated: an OAuth connection (an MCP client), an API key, or the platform's service key (the dashboard). + * @enum {string} + */ + via: "oauth" | "bearer" | "service"; + /** @description On `oauth`: the name the OAuth client declared about itself at dynamic registration. Self-declared, never verified. */ + client_name_declared?: string | null; + /** @description On `oauth`: the client id, last four characters only. */ + client_id_masked?: string | null; + /** @description On `bearer`: the API key id, last four characters only. */ + key_id_masked?: string | null; + } | null; + /** @description The agent the call's session belongs to, when the session is a registered agent's. Null on the shared remote-MCP session, whose callers are told apart by `actor`, never by a mandate's agent. */ + agent?: { + id: string; + name: string | null; + } | null; }; Trigger: { id: string; @@ -52647,6 +55738,25 @@ export interface components { */ settlement?: "confirmed" | "pending" | "failed"; adapter: string; + /** + * @description Who executes (or executed) the payment, by the same name the integrator chooses with on POST /v1/consents. `codespar_simulator` ("Simulado pela CodeSpar": no provider is called) or `provider_sandbox` (the provider's sandbox, over the account the server bound to this consumer); both Test only. Null when no executor applies, Live included. The name is the MODE: the provider, account, project, consumer and environment are resolved by the server before the signature and checked again when the payment runs; no request field chooses them (`executor_provider_not_selectable`), and a provider failure is never turned into a simulation. Records written before this name existed keep their stored value and are read in these words. + * @enum {string|null} + */ + executor: "codespar_simulator" | "provider_sandbox" | null; + /** + * @description The concrete provider behind `executor`, as the server resolved it: `celcoin` for `provider_sandbox`; null for `codespar_simulator` (no provider is called) and when `executor` is null. Read-only. + * @enum {string|null} + */ + executor_provider: "celcoin" | null; + /** @description The executor's label as the consent screen, the dashboard and the receipt show it. In Test it ends "· sem dinheiro real". */ + executor_label: string | null; + /** + * @description The project's environment. + * @enum {string|null} + */ + environment: "test" | "live" | null; + /** @description False in Test, always: no real money moves, including when the provider's sandbox CONFIRMED the operation (`moneyMoved: true` / `settlement: "confirmed"` then mean the sandbox settled it). True in Live. */ + real_money: boolean | null; }; wallet: { walletId: string; diff --git a/packages/core/src/generated/operations.ts b/packages/core/src/generated/operations.ts index ec863a6..094f8f3 100644 --- a/packages/core/src/generated/operations.ts +++ b/packages/core/src/generated/operations.ts @@ -1,5 +1,5 @@ // GENERATED FILE — do not edit. -// Source: openapi-snapshot.json (sha256 4ae3274e16aa0655cacab1b3a1f0c1fbe8ad710fe2c0184c9b0aa816fdd0095c, fetched 2026-10-31T00:54:41.356Z +// Source: openapi-snapshot.json (sha256 b9b057565a31502b762e37b6c0c713984543f48a2425e34729bf1332afa34cfb, fetched 2026-11-11T11:18:25.811Z // from https://api.codespar.dev/openapi.json, API 0.3.0). // Regenerate: npm run spec:generate (in packages/core) import type { ApiOperationRef } from "../api/types.js"; @@ -76,6 +76,8 @@ export const API_OPERATIONS = [ { method: "post", path: "/v1/account/fund/sandbox/initial", body: null, accept: "application/json", requiredQuery: [], deprecated: false }, { method: "get", path: "/v1/account/sessions", body: null, accept: "application/json", requiredQuery: [], deprecated: false }, { method: "get", path: "/v1/onboarding", body: null, accept: "application/json", requiredQuery: [], deprecated: false }, + { method: "get", path: "/v1/onboarding/first-receive", body: null, accept: "application/json", requiredQuery: [], deprecated: false }, + { method: "post", path: "/v1/onboarding/first-receive", body: null, accept: "application/json", requiredQuery: [], deprecated: false }, { method: "get", path: "/v1/account/test-balance", body: null, accept: "application/json", requiredQuery: [], deprecated: false }, { method: "post", path: "/v1/account/fund/sandbox/refill", body: "application/json", accept: "application/json", requiredQuery: [], deprecated: false }, { method: "get", path: "/v1/approvals", body: null, accept: "application/json", requiredQuery: [], deprecated: false }, @@ -100,6 +102,20 @@ export const API_OPERATIONS = [ { method: "post", path: "/v1/bank-consents", body: "application/json", accept: "application/json", requiredQuery: [], deprecated: false }, { method: "get", path: "/v1/bank-consents/{id}", body: null, accept: "application/json", requiredQuery: [], deprecated: false }, { method: "get", path: "/v1/ofb/consents/{id}", body: null, accept: "application/json", requiredQuery: [], deprecated: true }, + { method: "get", path: "/v1/ofb/sweeping/consents", body: null, accept: "application/json", requiredQuery: [], deprecated: false }, + { method: "post", path: "/v1/ofb/sweeping/consents", body: "application/json", accept: "application/json", requiredQuery: [], deprecated: false }, + { method: "get", path: "/v1/ofb/sweeping/consents/{id}", body: null, accept: "application/json", requiredQuery: [], deprecated: false }, + { method: "post", path: "/v1/ofb/sweeping/consents/{id}/revoke", body: "application/json", accept: "application/json", requiredQuery: [], deprecated: false }, + { method: "get", path: "/v1/ofb/sweeping/pulls", body: null, accept: "application/json", requiredQuery: [], deprecated: false }, + { method: "post", path: "/v1/ofb/sweeping/pulls", body: "application/json", accept: "application/json", requiredQuery: [], deprecated: false }, + { method: "get", path: "/v1/ofb/sweeping/pulls/{id}", body: null, accept: "application/json", requiredQuery: [], deprecated: false }, + { method: "get", path: "/v1/ofb/jsr/enrollments", body: null, accept: "application/json", requiredQuery: [], deprecated: false }, + { method: "post", path: "/v1/ofb/jsr/enrollments", body: "application/json", accept: "application/json", requiredQuery: [], deprecated: false }, + { method: "get", path: "/v1/ofb/jsr/enrollments/{id}", body: null, accept: "application/json", requiredQuery: [], deprecated: false }, + { method: "post", path: "/v1/ofb/jsr/enrollments/{id}/revoke", body: "application/json", accept: "application/json", requiredQuery: [], deprecated: false }, + { method: "get", path: "/v1/ofb/jsr/payments", body: null, accept: "application/json", requiredQuery: [], deprecated: false }, + { method: "post", path: "/v1/ofb/jsr/payments", body: "application/json", accept: "application/json", requiredQuery: [], deprecated: false }, + { method: "get", path: "/v1/ofb/jsr/payments/{id}", body: null, accept: "application/json", requiredQuery: [], deprecated: false }, { method: "get", path: "/v1/fees", body: null, accept: "application/json", requiredQuery: [], deprecated: false }, { method: "get", path: "/v1/fees/movimentar", body: null, accept: "application/json", requiredQuery: [], deprecated: false }, { method: "get", path: "/v1/fees/governar", body: null, accept: "application/json", requiredQuery: [], deprecated: false }, @@ -325,6 +341,7 @@ export const API_OPERATIONS = [ { method: "get", path: "/v1/shop/agent/purchases/{id}", body: null, accept: "application/json", requiredQuery: [], deprecated: false }, { method: "post", path: "/v1/shop/agent/research", body: "application/json", accept: "application/json", requiredQuery: [], deprecated: false }, { method: "get", path: "/v1/shop/agent/research/{id}", body: null, accept: "application/json", requiredQuery: [], deprecated: false }, + { method: "get", path: "/v1/shop/agent/capabilities", body: null, accept: "application/json", requiredQuery: [], deprecated: false }, { method: "get", path: "/v1/shop/agent/instruments", body: null, accept: "application/json", requiredQuery: [], deprecated: false }, { method: "get", path: "/v1/projects", body: null, accept: "application/json", requiredQuery: [], deprecated: false }, { method: "post", path: "/v1/projects", body: "application/json", accept: "application/json", requiredQuery: [], deprecated: false }, From 50d2be52eca17ea346f1717c900195e0e5e7fe3f Mon Sep 17 00:00:00 2001 From: Fabiano Cruz Date: Wed, 11 Nov 2026 09:01:40 -0300 Subject: [PATCH 2/3] feat(cli): publish the ofb group, live again in the served document The 390-operation refresh brings live /v1/ofb routes (sweeping consents and pulls, Pix com biometria enrollments and payments, Test only). The coverage gate asks for a published group, not an exception. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01RmCN2L9X5C6vdDBLVJ5Fuq --- packages/cli/src/surface.ts | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/packages/cli/src/surface.ts b/packages/cli/src/surface.ts index f459e0b..a48c897 100644 --- a/packages/cli/src/surface.ts +++ b/packages/cli/src/surface.ts @@ -229,6 +229,14 @@ export const PUBLISHED_GROUPS: readonly GroupSpec[] = [ prefix: "/v1/onboarding", description: "Onboarding: the first-access guide's progress for the project", }, + { + // Live again at the 390-operation refresh (2026-11-11): the older ofb + // routes were all deprecated, and the served document now declares the + // sweeping consents/pulls and the Pix com biometria (JSR) family, Test only. + name: "ofb", + prefix: "/v1/ofb", + description: "Open Finance (Test): sweeping consents and pulls, Pix com biometria enrollments and payments", + }, { name: "webhook-deliveries", prefix: "/v1/webhook-deliveries", From cf99ba25ada8748b5fd9c9165424755787768893 Mon Sep 17 00:00:00 2001 From: Fabiano Cruz Date: Wed, 11 Nov 2026 09:07:13 -0300 Subject: [PATCH 3/3] test(cli): derived commands of the 390-operation document (cli 0.22.7) ofb (sweeping, Pix com biometria, bank consents), onboarding first-receive and shop capabilities, as the served document declares them. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01RmCN2L9X5C6vdDBLVJ5Fuq --- package-lock.json | 2 +- packages/cli/CHANGELOG.md | 10 +++++++++ packages/cli/package.json | 2 +- .../src/__tests__/resource-commands.test.ts | 22 +++++++++++++++++++ 4 files changed, 34 insertions(+), 2 deletions(-) diff --git a/package-lock.json b/package-lock.json index ad5e335..d80fb87 100644 --- a/package-lock.json +++ b/package-lock.json @@ -3020,7 +3020,7 @@ }, "packages/cli": { "name": "@codespar/cli", - "version": "0.22.6", + "version": "0.22.7", "license": "MIT", "dependencies": { "@codespar/sdk": "^0.16.26", diff --git a/packages/cli/CHANGELOG.md b/packages/cli/CHANGELOG.md index 2c95af2..7ac5e73 100644 --- a/packages/cli/CHANGELOG.md +++ b/packages/cli/CHANGELOG.md @@ -1,5 +1,15 @@ # @codespar/cli — changelog +## 0.22.7 — 2026-11-11 + +### Added + +- **`codespar ofb`**, derived from the served document like every resource group. The `/v1/ofb` family is live again, Test only. Its commands cover: + - sweeping consents and pulls (`list-`/`create-`/`get-sweeping-consents`, `sweeping-consents-revoke`, `list-`/`create-`/`get-sweeping-pulls`); + - Pix com biometria (`list-`/`create-`/`get-jsr-enrollments`, `jsr-enrollments-revoke`, `list-`/`create-`/`get-jsr-payments`); + - the bank-consent routes (`create-`/`get-consents`, `consents-callback`, `consents-refresh-statement`, `consents-revoke`). +- `codespar onboarding list-first-receive` / `create-first-receive` (`/v1/onboarding/first-receive`) and `codespar shop capabilities` (`GET /v1/shop/agent/capabilities`) are derived from the same refresh, alongside @codespar/sdk 0.16.29. + ## 0.22.6 — 2026-11-01 ### Fixed diff --git a/packages/cli/package.json b/packages/cli/package.json index db78c14..388a149 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -1,6 +1,6 @@ { "name": "@codespar/cli", - "version": "0.22.6", + "version": "0.22.7", "description": "CodeSpar CLI. The agentic OS for money movement in Latin America, from your terminal: authenticate, browse servers, mint mandates, execute tools, manage sessions, stream logs.", "type": "module", "bin": { diff --git a/packages/cli/src/__tests__/resource-commands.test.ts b/packages/cli/src/__tests__/resource-commands.test.ts index b0cf5c1..64253cb 100644 --- a/packages/cli/src/__tests__/resource-commands.test.ts +++ b/packages/cli/src/__tests__/resource-commands.test.ts @@ -163,11 +163,33 @@ const PINNED_COMMANDS = [ "meters adjustments → GET /v1/meters/adjustments", "meter-events create → POST /v1/meter-events", "onboarding list → GET /v1/onboarding", + "onboarding list-first-receive → GET /v1/onboarding/first-receive", + "onboarding create-first-receive → POST /v1/onboarding/first-receive", + "ofb get-consents → GET /v1/ofb/consents/{id}", + "ofb list-sweeping-consents → GET /v1/ofb/sweeping/consents", + "ofb create-sweeping-consents → POST /v1/ofb/sweeping/consents", + "ofb get-sweeping-consents → GET /v1/ofb/sweeping/consents/{id}", + "ofb sweeping-consents-revoke → POST /v1/ofb/sweeping/consents/{id}/revoke", + "ofb list-sweeping-pulls → GET /v1/ofb/sweeping/pulls", + "ofb create-sweeping-pulls → POST /v1/ofb/sweeping/pulls", + "ofb get-sweeping-pulls → GET /v1/ofb/sweeping/pulls/{id}", + "ofb list-jsr-enrollments → GET /v1/ofb/jsr/enrollments", + "ofb create-jsr-enrollments → POST /v1/ofb/jsr/enrollments", + "ofb get-jsr-enrollments → GET /v1/ofb/jsr/enrollments/{id}", + "ofb jsr-enrollments-revoke → POST /v1/ofb/jsr/enrollments/{id}/revoke", + "ofb list-jsr-payments → GET /v1/ofb/jsr/payments", + "ofb create-jsr-payments → POST /v1/ofb/jsr/payments", + "ofb get-jsr-payments → GET /v1/ofb/jsr/payments/{id}", + "ofb create-consents → POST /v1/ofb/consents", + "ofb consents-callback → POST /v1/ofb/consents/{id}/callback", + "ofb consents-refresh-statement → POST /v1/ofb/consents/{id}/refresh-statement", + "ofb consents-revoke → POST /v1/ofb/consents/{id}/revoke", "webhook-deliveries list → GET /v1/webhook-deliveries", "shop create-purchases → POST /v1/shop/agent/purchases", "shop get-purchases → GET /v1/shop/agent/purchases/{id}", "shop create-research → POST /v1/shop/agent/research", "shop get-research → GET /v1/shop/agent/research/{id}", + "shop capabilities → GET /v1/shop/agent/capabilities", "shop instruments → GET /v1/shop/agent/instruments", "collect list-links → GET /v1/collect/links", "collect create-links → POST /v1/collect/links",