External Accounts
3 operações em Quadra Core API 0.5.0.
/v1/external-accountsList External Accounts
List EXTERNAL accounts in the caller's tenant (RFC-021 §3.2).
Cursor-paginated and scoped to the calling tenant. **Page until `next_cursor` is null** — a short page is not the end of the list.
Parâmetros
| Nome | Tipo | Detalhe |
|---|---|---|
| cursor | string, opcional | query Opaque pagination cursor |
| limit | integer | query Max items per page |
Respostas
| Status | Corpo | Detalhe |
|---|---|---|
| 200 | — | Resposta bem-sucedidaO contrato não declara um modelo para esta resposta, então a forma dela não está documentada aqui. Um roteiro de demonstração mostra a forma que ela realmente devolve. |
| 422 | HTTPValidationError | Erro de validação |
/v1/external-accountsCreate an External Account
Create a non-custodial EXTERNAL account (RFC-021).
Registers an external counterparty (PIX key or phone) as a first-class, deduplicated, non-custodial account row. No Cardano address is derived and no datum file is written — the account cannot hold value, only be named.
Re-posting the same `(scheme, normalized_identifier)` within the same tenant returns the existing `account_id` with `200`. Reusing the same `Idempotency-Key` with a different body returns `409`.
Returns: 201 Created on first registration; 200 OK on identity-dedup hit.
Raises: 400: identifier could not be normalized for the given scheme 409: Idempotency-Key reused with a different request body 500: Internal error during account creation
Parâmetros
| Nome | Tipo | Detalhe |
|---|---|---|
| Idempotency-Key | string | headerobrigatório |
Corpo da requisição
ExternalAccountCreateRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.
Respostas
| Status | Corpo | Detalhe |
|---|---|---|
| 201 | ExternalAccountResponse | Resposta bem-sucedida |
| 422 | HTTPValidationError | Erro de validação |
/v1/external-accounts/{account_id}Get an External Account
Get a single EXTERNAL account by id (RFC-021 §3.2).
Returns 404 if no row exists for the id, or if the id refers to an account that is not of type EXTERNAL (e.g. a CUSTOMER or GL account). This prevents non-external account ids from leaking through this endpoint.
Parâmetros
| Nome | Tipo | Detalhe |
|---|---|---|
| account_id | string | pathobrigatório |
Respostas
| Status | Corpo | Detalhe |
|---|---|---|
| 200 | ExternalAccountResponse | Resposta bem-sucedida |
| 422 | HTTPValidationError | Erro de validação |
Esquemas
Os modelos que as operações acima aceitam e devolvem. Campos opcionais estão marcados como tal; um campo tipado como outro modelo está documentado sob o nome dele.
AccountStatus
Account lifecycle status.
Um de: ACTIVE, CLOSED
ExternalAccountCreateRequest
Request body for creating an external (non-custodial) account.
| Campo | Tipo | Detalhe |
|---|---|---|
| display_name | string | obrigatórioHuman-readable display name for this counterparty |
| identifier | string | obrigatórioRaw identifier (server normalizes per scheme) |
| scheme | ExternalIdentityScheme | obrigatórioIdentifier scheme: PIX_KEY or PHONE |
ExternalAccountResponse
Response model for external account creation and detail endpoints.
| Campo | Tipo | Detalhe |
|---|---|---|
| account_id | string | obrigatórioUnique account identifier (acc_...) |
| created_at | string | obrigatórioISO 8601 timestamp of creation |
| external_identity | ExternalIdentity | obrigatórioNormalized identity of the external counterparty |
| is_frozen | boolean | Whether the account is frozenPadrão false |
| promoted_to_account_id | string, opcional | If this external account was promoted to a CUSTOMER account, the new account_id (RFC-021 §5). Null otherwise. |
| status | AccountStatus | obrigatórioAccount lifecycle status |
| type | string | Always EXTERNALPadrão "EXTERNAL" |
| updated_at | string | obrigatórioISO 8601 timestamp of last update |
ExternalIdentity
Identity of an external (non-custodial) counterparty. The `identifier` in this model is the *normalized* form (E.164 phones, digits-only CPF/CNPJ, lowercased EVP/email) — never the raw user input.
| Campo | Tipo | Detalhe |
|---|---|---|
| display_name | string | obrigatórioHuman-readable display name |
| identifier | string | obrigatórioNormalized identifier |
| pix_subtype | "EMAIL" | "CPF" | "CNPJ" | "EVP" | "PHONE", opcional | Detected PIX sub-type (EMAIL/CPF/CNPJ/EVP/PHONE); None for non-PIX schemes |
| scheme | ExternalIdentityScheme | obrigatórioIdentifier scheme |
ExternalIdentityScheme
Scheme that an external counterparty identifier belongs to.
Um de: PIX_KEY, PHONE
HTTPValidationError
| Campo | Tipo | Detalhe |
|---|---|---|
| detail | array de ValidationError |
ValidationError
| Campo | Tipo | Detalhe |
|---|---|---|
| ctx | object | |
| input | não declarado | |
| loc | array de string ou integer | obrigatório |
| msg | string | obrigatório |
| type | string | obrigatório |