Generated HTTP reference for the 4 operations the published OpenAPI document describes under dda.

Boletos you owe (DDA)

This page is generated from the published OpenAPI document. It is complete with respect to that document and says nothing about surfaces the document does not describe yet. See what is generated here for what that means.

Base URL: https://api.codespar.dev

Every operation below requires a Bearer token. See Authentication.

GET `/v1/consumers/{consumerId}/dda/boletos`

GEThttps://api.codespar.dev/v1/consumers/{consumerId}/dda/boletos

The boletos DDA has mirrored for this consumer

Path parameters

Name	Type	Required	Description
`consumerId`	`string`	yes	—

Query parameters

Name	Type	Required	Description
`from_date`	`string`	yes	—
`to_date`	`string`	yes	—

Responses

Status	Body	Description
`200`	object	OK
`400`	object	`from_date` or `to_date` is missing or is not YYYY-MM-DD. `details.issues` carries the validation issues.

Response 200

Field	Type	Required	Description
`boletos`	array of object	yes	—
`count`	`integer`	yes	The length of `boletos`. No pagination, so this is the total for the window.
`from_date`	`string`	yes	Echoes the validated `from_date` query parameter, so exactly `YYYY-MM-DD`.
`to_date`	`string`	yes	Echoes the validated `to_date` query parameter, so exactly `YYYY-MM-DD`.

Example request

curl -X GET https://api.codespar.dev/v1/consumers/{consumerId}/dda/boletos \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

const res = await fetch("https://api.codespar.dev/v1/consumers/{consumerId}/dda/boletos", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

Example response 200

application/json

{
  "from_date": "string",
  "to_date": "string",
  "count": 1,
  "boletos": [
    {
      "linha_digitavel": "string",
      "status": "string"
    }
  ]
}

POST `/v1/consumers/{consumerId}/dda/subscriptions`

POSThttps://api.codespar.dev/v1/consumers/{consumerId}/dda/subscriptions

Path parameters

Name	Type	Required	Description
`consumerId`	`string`	yes	—

Request body

Field	Type	Required	Description
`client_name`	`string`	no	—
`document`	`string`	yes	—
`idempotency_key`	`string`	yes	—

Responses

Status	Body	Description
`200`	object	Nothing was registered by this call: an attempt under this same key already holds the registration, or one is in flight. `replayed` is true and `status` is the row's current state.
`201`	object	This call registered the document. `replayed` is false and `status` is `pending`.
`400`	object	`invalid_body`, from three places: the body did not match the schema (and only then is `details.issues` present); `document` carries no CPF/CNPJ digits; `idempotency_key` is blank. Nothing was registered.
`403`	object	`dda_document_not_owned`: the document is not the one verified for this consumer, or the consumer entity and the funding source disagree about who this consumer is. `dda_document_unauthorized`: no active mandate names this document in its signed allowlist. Nothing was registered, and neither carries `details`.
`422`	object	`no_celcoin_account`: the consumer has no active pix-celcoin funding source in this organization — or is not this organization's consumer at all. `dda_document_not_owned` ALSO answers 422, and only for one cause: the account has no verified document on file at all, so no document can be shown to be theirs. Sending a different document will not help; finish onboarding and retry.
`500`	object \| object	NOT the usual error envelope. Three reads — the consumer's account, the verified document, and the authorizing mandate — run before the handler's own error handling, so a failure in any of them is answered by the framework's default: `\{ statusCode, error, message \}`, plus `code` when the underlying failure carried one. All three sit before the provider is called, so nothing was registered.
`502`	object	`dda_provider_unavailable`, from two conditions the response does not separate: the provider answered and the answer was not a success (the local row is marked `error`), or the call was in flight and whether it arrived is genuinely not known here. Because the caller cannot tell them apart, the guidance is the same for both — retry with the SAME `idempotency_key`, which makes the retry the same registration rather than a second one.
`503`	object	`dda_claim_unavailable`: the local claim failed and NOTHING was sent to the provider. This is stated apart from the 502 on purpose — here it is PROVEN that nothing left. Retry with the SAME `idempotency_key`.

Response 200

Field	Type	Required	Description
`client_request_id`	`string`	yes	The provider-side anchor for this registration. Derived from (organization, consumer, document, `idempotency_key`), so the SAME key against a DIFFERENT document is a DIFFERENT registration.
`document`	`string`	yes	Digits only. This is the document the consumer SIGNED in the mandate's allowlist, not the spelling that arrived in the body.
`mandate_id`	`string`	yes	The active mandate whose signed allowlist authorized this.
`replayed`	`boolean`	yes	true when this call registered nothing. Either an earlier attempt under this key already holds the registration, or one is in flight right now.
`status`	`"pending"` \| `"active"` \| `"error"` \| `"deleted"`	yes	A registration this call made is always `pending`, and becomes `active` only when the provider's confirmation webhook lands. A 200 (nothing registered by this call) reports the row's current state, which can be any of the four.

Example request

curl -X POST https://api.codespar.dev/v1/consumers/{consumerId}/dda/subscriptions \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "document": "string",
       "client_name": "Example",
       "idempotency_key": "string"
     }'

const res = await fetch("https://api.codespar.dev/v1/consumers/{consumerId}/dda/subscriptions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "document": "string",
    "client_name": "Example",
    "idempotency_key": "string"
  }),
});

const data = await res.json();

Example response 200

application/json

{
  "document": "string",
  "status": "pending",
  "client_request_id": "clientrequest_0000000000000000",
  "mandate_id": "mandate_0000000000000000",
  "replayed": true
}

GET `/v1/consumers/{consumerId}/dda/subscriptions/{document}`

GEThttps://api.codespar.dev/v1/consumers/{consumerId}/dda/subscriptions/{document}

Read a DDA registration

Path parameters

Name	Type	Required	Description
`consumerId`	`string`	yes	—
`document`	`string`	yes	CPF or CNPJ. Punctuation is accepted and stripped.

Responses

Status	Body	Description
`200`	object	OK
`400`	object	The path's document carries no CPF/CNPJ digits.
`404`	object	No DDA registration for this consumer and document. Also the answer for a consumer another organization holds.

Response 200

Field	Type	Required	Description
`celcoin_subscription_id`	`string,null`	yes	The provider's own id, null until the confirmation webhook supplies it.
`client_request_id`	`string`	yes	The idempotency correlation carried to the provider on the registration.
`document`	`string`	yes	Digits only. The stored form, which is what the provider leg was sent.
`status`	`"pending"` \| `"active"` \| `"error"` \| `"deleted"`	yes	`pending` until the provider's confirmation webhook lands. Nothing polls the provider for this: the webhook is the only source of a status change, so a registration can sit `pending` indefinitely if a delivery was lost.

Example request

curl -X GET https://api.codespar.dev/v1/consumers/{consumerId}/dda/subscriptions/{document} \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

const res = await fetch("https://api.codespar.dev/v1/consumers/{consumerId}/dda/subscriptions/{document}", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

Example response 200

application/json

{
  "document": "string",
  "status": "pending",
  "client_request_id": "clientrequest_0000000000000000"
}

DELETE `/v1/consumers/{consumerId}/dda/subscriptions/{document}`

DELETEhttps://api.codespar.dev/v1/consumers/{consumerId}/dda/subscriptions/{document}

End a DDA registration

Path parameters

Name	Type	Required	Description
`consumerId`	`string`	yes	—
`document`	`string`	yes	CPF or CNPJ. Punctuation is accepted and stripped.

Responses

Status	Body	Description
`200`	object	OK
`400`	object	The path's document carries no CPF/CNPJ digits.
`404`	object	No DDA registration for this consumer and document. Also returned when the row disappeared between the ownership read and the provider call, because in that case nothing was sent upstream.
`502`	object	The registration could not be ended upstream. Nothing about the local row changed; retry later.

Response 200

Field	Type	Required	Description
`document`	`string`	yes	—
`status`	`"deleted"`	yes	—

Example request

curl -X DELETE https://api.codespar.dev/v1/consumers/{consumerId}/dda/subscriptions/{document} \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

const res = await fetch("https://api.codespar.dev/v1/consumers/{consumerId}/dda/subscriptions/{document}", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

Example response 200

application/json

{
  "document": "string",
  "status": "deleted"
}

Boletos you owe (DDA)

Boletos you owe (DDA)

GET /v1/consumers/{consumerId}/dda/boletos

POST /v1/consumers/{consumerId}/dda/subscriptions

GET /v1/consumers/{consumerId}/dda/subscriptions/{document}

DELETE /v1/consumers/{consumerId}/dda/subscriptions/{document}

On this page

GET `/v1/consumers/{consumerId}/dda/boletos`

POST `/v1/consumers/{consumerId}/dda/subscriptions`

GET `/v1/consumers/{consumerId}/dda/subscriptions/{document}`

DELETE `/v1/consumers/{consumerId}/dda/subscriptions/{document}`