Pix keys (DICT)
Generated HTTP reference for the 3 operations the published OpenAPI document describes under pix-keys.
5 min read
Pix keys (DICT)
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}/pix-keys
GET
https://api.codespar.dev/v1/consumers/{consumerId}/pix-keysList the Pix keys on the consumer's account
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
consumerId | string | yes | — |
Responses
| Status | Body | Description |
|---|---|---|
200 | object | OK |
422 | object | no_celcoin_account: the consumer has no active Pix funding source, so there is no account to list. pix_key_provider_refused: the provider adjudicated and said no; details.provider_code names its business code, and retrying the same input cannot succeed. |
502 | object | The listing could not be completed upstream. The outcome is unknown and the condition is transient; retry. details.provider_code still carries whatever code the body named, so a generic provider error is visible without being called terminal. |
Response 200
| Field | Type | Required | Description |
|---|---|---|---|
account_masked | string | yes | Four mask characters followed by the account's last two digits. |
count | integer | yes | — |
keys | array of object | yes | — |
Example request
curl -X GET https://api.codespar.dev/v1/consumers/{consumerId}/pix-keys \
-H "Authorization: Bearer $CODESPAR_API_KEY"const res = await fetch("https://api.codespar.dev/v1/consumers/{consumerId}/pix-keys", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
},
});
const data = await res.json();Example response 200
{
"account_masked": "string",
"keys": [
{
"key": "string",
"key_type": "string"
}
],
"count": 1
}POST /v1/consumers/{consumerId}/pix-keys
POST
https://api.codespar.dev/v1/consumers/{consumerId}/pix-keysRegister a Pix key on the consumer's account
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
consumerId | string | yes | — |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
key | string | no | — |
key_type | "EVP" | "CPF" | "CNPJ" | "EMAIL" | "PHONE" | yes | — |
Responses
| Status | Body | Description |
|---|---|---|
201 | object | OK |
400 | object | invalid_body: the body did not match the schema (details.issues). pix_key_invalid: the value is not a valid key for the key_type asked for, or key came with an EVP request, or key was missing for every other type. Neither reached the provider. |
403 | object | pix_key_document_mismatch: a CPF/CNPJ key whose value is not the account holder's own document. Refused locally, without calling the provider. |
409 | object | pix_key_ownership_unverified: this e-mail or phone has no recent verification for this consumer. details carries the channel, the endpoint to call and the window a verification stays good for; start a contact verification, confirm the code, retry. Nothing reached the provider. pix_key_registration_uncertain: the registration was accepted and came back with no readable key, and the account's key list could not settle whether it landed. details carries retry_safe: false, inventory_known and inventory_count. LIST the keys instead of repeating the registration. |
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; nothing reached the provider. pix_key_provider_refused: the provider adjudicated and refused, with details.provider_status and details.provider_code (null when the body named no code); repeating the same input will not pass. |
500 | object | object | NOT the usual error envelope. Resolving the consumer's account runs before the handler's own error handling, so a failure there is answered by the framework's default: \{ statusCode, error, message \}, plus code when the underlying failure carried one. It happens before the provider is called, so nothing was registered. |
502 | object | pix_key_provider_unavailable, and THREE different failures produce it with THREE different details. Read the field, not the code. 1. A transient upstream failure — a 5xx, transport, credentials, a generic internal code, a codeless 429/408/404. details.provider_status and details.provider_code (null when the body named no code). 2. A registration that PROVABLY did not land: the account's key list answered and does not carry the key. details.verified_not_registered is true and details.inventory_count is the number of keys the list reported. There is NO provider_code here — no provider code was involved in reaching this conclusion. 3. Anything the handler did not classify. No details at all. All three are retriable; only the second one is retriable on evidence rather than on the absence of it. |
Response 201
| Field | Type | Required | Description |
|---|---|---|---|
account_masked | string | yes | The account, masked to its last two digits. |
cache_filled | boolean | yes | false when the key WAS registered but the local cache could not be filled. Not a registration failure. |
key | string | yes | The registered key. For EVP this is the random key the provider minted, and this response is the only place it appears in this call. |
key_type | string | yes | The type as the provider returned it. Deliberately an open string rather than the request's enum: the value comes back from upstream and is carried through untyped. |
reconciled | boolean | yes | true when the key returned here came from re-reading the account's key list, because the registration response was unreadable. The key belongs to the account; THIS call is not proven to be what created it. |
Example request
curl -X POST https://api.codespar.dev/v1/consumers/{consumerId}/pix-keys \
-H "Authorization: Bearer $CODESPAR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"key_type": "EVP",
"key": "string"
}'const res = await fetch("https://api.codespar.dev/v1/consumers/{consumerId}/pix-keys", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"key_type": "EVP",
"key": "string"
}),
});
const data = await res.json();Example response 201
{
"key": "string",
"key_type": "string",
"account_masked": "string",
"cache_filled": true,
"reconciled": true
}DELETE /v1/consumers/{consumerId}/pix-keys/{key}
DELETE
https://api.codespar.dev/v1/consumers/{consumerId}/pix-keys/{key}Delete a Pix key from the consumer's account
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
consumerId | string | yes | — |
key | string | yes | The key value. Trimmed; an empty value is 400. |
Responses
| Status | Body | Description |
|---|---|---|
200 | object | OK |
400 | object | The key in the path is empty after trimming. |
422 | object | no_celcoin_account: the consumer has no active Pix funding source. pix_key_provider_refused: the provider adjudicated and refused; retrying the same input cannot succeed. details.provider_code carries its business code. |
502 | object | The deletion could not be completed upstream. Whether the key is gone is unknown; retry, then list the keys to confirm. |
Response 200
| Field | Type | Required | Description |
|---|---|---|---|
account_masked | string | yes | — |
cache_cleared | boolean | yes | Whether the deleted key was the one this API had cached as the receiving key. |
cache_refilled_with | string,null | yes | When the cache was cleared, the account's remaining keys are re-read and one is cached back, preferring a non-EVP key. Null when nothing was cleared, nothing remains, or the inventory read did not answer. |
deleted | true | yes | — |
key | string | yes | The canonical form actually sent upstream. A punctuated CPF or CNPJ is normalized before the delete, so this can differ from the value in the path. |
Example request
curl -X DELETE https://api.codespar.dev/v1/consumers/{consumerId}/pix-keys/{key} \
-H "Authorization: Bearer $CODESPAR_API_KEY"const res = await fetch("https://api.codespar.dev/v1/consumers/{consumerId}/pix-keys/{key}", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
},
});
const data = await res.json();Example response 200
{
"key": "string",
"account_masked": "string",
"deleted": true,
"cache_cleared": true
}