Guest Accounts
2 operações em Quadra Core API 0.5.0.
/v1/guest-accountsCreate a Guest Account
Create a custody-enabled GUEST account (guest-01).
Registers an external non-KYC user (PIX key or phone) as a first-class, contact-deduplicated account with full Cardano custody: managed keypair, address, datum/redeemer — CUSTOMER-shaped, with an external identity bolted on. Guests must own a party (`owner_party_id` is required).
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 404: owner_party_id doesn't exist 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
GuestAccountCreateRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.
Respostas
| Status | Corpo | Detalhe |
|---|---|---|
| 201 | GuestAccountResponse | Resposta bem-sucedida |
| 422 | HTTPValidationError | Erro de validação |
/v1/guest-accounts/{account_id}/pix-keyRegister a Guest's PIX Key
Register (or overwrite) a guest's PIX key (guest-02; routing row LaaS-12).
Stores the key as a `pix_identity` attribute on the GUEST account row AND writes the `IDENTITY#PIX#{normalized}` routing row (RFC-022 §3.2) so inbound Pix arrivals resolve to this account. Deliberately does NOT touch `GSI4PK` — contact dedup keys the account by the original email/phone identity; the PIX key may be a different identifier class entirely (CPF, EVP, another phone/email). PUT is idempotent: re-registering the same key is a no-op; a key change re-points routing (the old row is removed).
Ordering is crash-safe (D5b): conditional-write the NEW routing row first (a 409 destroys nothing), then delete the OLD row (ownership-guarded), then overwrite the display attribute. No crash window leaves the guest unroutable or damages a row owned by another account.
Returns: 200 with the registered pix_identity.
Raises: 400: identifier is not a valid PIX key 404: account doesn't exist or is not of type GUEST 409: the key is already bound to another account (IDENTITY_ALREADY_BOUND) 500: Internal error persisting the identity
Parâmetros
| Nome | Tipo | Detalhe |
|---|---|---|
| account_id | string | pathobrigatório |
Corpo da requisição
GuestPixKeyRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.
Respostas
| Status | Corpo | Detalhe |
|---|---|---|
| 200 | GuestPixKeyResponse | 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
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
GuestAccountCreateRequest
Request body for creating a GUEST (custody-enabled, non-KYC) account. Email identifiers are expressed as ``scheme=PIX_KEY`` — the server-side normalizer classifies them as ``pix_subtype=EMAIL``.
| Campo | Tipo | Detalhe |
|---|---|---|
| display_name | string | obrigatórioHuman-readable display name for this guest |
| identifier | string | obrigatórioRaw identifier (server normalizes per scheme) |
| owner_party_id | string | obrigatórioParty that owns this guest account (required — guests must own a party) |
| scheme | ExternalIdentityScheme | obrigatórioIdentifier scheme: PIX_KEY or PHONE |
GuestAccountResponse
Response model for guest account creation.
| Campo | Tipo | Detalhe |
|---|---|---|
| account_id | string | obrigatórioUnique account identifier (acc_...) |
| address | string | obrigatórioCardano custody address (guests hold custody) |
| created_at | string | obrigatórioISO 8601 timestamp of creation |
| external_identity | ExternalIdentity | obrigatórioNormalized contact identity of the guest |
| is_frozen | boolean | Whether the account is frozenPadrão false |
| owner_party_id | string | obrigatórioParty that owns this guest account |
| pix_identity | PixIdentity, opcional | PIX identity; null until registered via guest-02 |
| status | AccountStatus | obrigatórioAccount lifecycle status |
| type | string | Always GUESTPadrão "GUEST" |
| updated_at | string | obrigatórioISO 8601 timestamp of last update |
GuestPixKeyRequest
Request body for registering a guest's PIX key (scheme is implied PIX_KEY).
| Campo | Tipo | Detalhe |
|---|---|---|
| identifier | string | obrigatórioRaw PIX key (server normalizes; sub-type auto-detected) |
GuestPixKeyResponse
Response model for PIX key registration on a GUEST account.
| Campo | Tipo | Detalhe |
|---|---|---|
| account_id | string | obrigatórioUnique account identifier (acc_...) |
| pix_identity | PixIdentity | obrigatórioThe registered PIX identity |
HTTPValidationError
| Campo | Tipo | Detalhe |
|---|---|---|
| detail | array de ValidationError |
PixIdentity
PIX identity registered on a GUEST account (guest-02). Stored as an attribute on the account row — deliberately independent of the GSI4 contact-dedup identity: the PIX key may be a different identifier class entirely (CPF, EVP, another phone/email).
| Campo | Tipo | Detalhe |
|---|---|---|
| identifier | string | obrigatórioNormalized PIX key |
| pix_subtype | "EMAIL" | "CPF" | "CNPJ" | "EVP" | "PHONE" | obrigatórioDetected PIX sub-type (EMAIL/CPF/CNPJ/EVP/PHONE) |
| scheme | string | Always PIX_KEYPadrão "PIX_KEY" |
| updated_at | string | obrigatórioISO 8601 timestamp of last registration |
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 |