KYC

6 operações em Quadra Command API 0.2.0.

POST/v1/kyc/rescreen-sweep

Re-screen verified parties past cadence or marked due

Internal sweep trigger (D5): EventBridge → API destination in sandbox, ops-invocable everywhere. Safe to re-run; returns counters.

Corpo da requisição

RescreenSweepRequest, opcional — opcional. Os campos estão listados em Esquemas, abaixo.

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

POST/v1/kyc/webhooks/{provider_id}

KYC provider webhook receiver

Async provider verdict receiver (LaaS-17 D8, per-provider auth by LaaS-44 D2).

Unauthenticated at the API Gateway (authorization_type=NONE — providers cannot do Cognito client-credentials); authenticated in-handler against **this provider's** verification strategy, resolved from its binding through LaaS-39's registry. The fixed ``timestamped_hmac_v1`` is now the default rather than the only option, so a vendor signing with JWT or a body-only HMAC needs a binding, not route surgery.

Ordering below is load-bearing and matches the Pix receivers (``_pix_webhook_auth``):

1. **unknown or unentitled provider ⇒ 404, before any signature is examined.** One code for both, so the segment cannot be used to enumerate other tenants' vendors (``docs/authorization-policy.md``); 2. binding unreadable / unbuildable ⇒ 503, retryable — never 404, which would tell a real provider "this endpoint is not yours" during an SSM blip; 3. bad signature or stale timestamp ⇒ 401, and only the two permitted codes.

Minimal ack for ALL outcomes — engine internals never leak to the provider, and unparseable payloads are acked-and-ignored (a provider retrying them helps nobody).

Parâmetros

Nome	Tipo	Detalhe
provider_id	string	pathobrigatório

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

POST/v1/parties/{party_id}/kyc

Submit KYC verification for a party

Start verification + initial screening (D3: not_performed → pending → sync verdict, review on screening hit, or async pending via webhook).

Parâmetros

Nome	Tipo	Detalhe
party_id	string	pathobrigatório
Idempotency-Key	string	headerobrigatório

Corpo da requisição

KycSubmitRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Status	Corpo	Detalhe
201	—	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

PATCH/v1/parties/{party_id}/kyc/status

Operator KYC review resolution

Operator-only review exit (Ticket 24's consumer seam): review → verified requires all screening-sourced flags resolved (422 otherwise).

Parâmetros

Nome	Tipo	Detalhe
party_id	string	pathobrigatório

Corpo da requisição

KycStatusPatchRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

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

POST/v1/parties/{party_id}/risk-flags

Add a risk flag to a party

Parâmetros

Nome	Tipo	Detalhe
party_id	string	pathobrigatório
Idempotency-Key	string	headerobrigatório

Corpo da requisição

RiskFlagCreateRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Status	Corpo	Detalhe
201	—	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

DELETE/v1/parties/{party_id}/risk-flags/{flag_id}

Resolve a risk flag (soft-resolve; row kept for audit)

Parâmetros

Nome	Tipo	Detalhe
party_id	string	pathobrigatório
flag_id	string	pathobrigatório

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

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.

DocumentRef

Provider-hosted document reference (D4 — never bytes, only refs). The refs-only posture in ``kyc/__init__.py`` is enforced here rather than merely asserted (LaaS-44 D4), by two properties that must both survive any edit: * ``extra="forbid"`` — a ``document_bytes`` / ``content`` / ``image_b64`` field cannot be smuggled in beside the ref; * ``max_length`` — a ref is an **identifier**, so the bound is far below anything a base64 document could fit in. A caller pasting an inline payload into ``provider_ref`` gets a 422 at the schema layer, before the engine or any provider sees it. Widening either of these is a change to the published BYO contract, not a tidy-up.

Campo	Tipo	Detalhe
provider_ref	string	obrigatórioProvider-side document id — an identifier, never content
type	string	obrigatórioDocument type, e.g. 'id_front', 'selfie'

HTTPValidationError

Campo	Tipo	Detalhe
detail	array de ValidationError

KycStatusPatchRequest

Operator review resolution (Ticket 24's consumer seam).

Campo	Tipo	Detalhe
reason	string	obrigatório
to_state	"verified" \| "rejected"	obrigatório

KycSubmitRequest

Campo	Tipo	Detalhe
document_refs	array de DocumentRef
provider_id	string, opcional	KYC provider to route to. Omit to use the tenant's default provider. Must be one this tenant is entitled to.

RescreenSweepRequest

Optional body for the internal re-screen sweep trigger (D5).

Campo	Tipo	Detalhe
limit	integer	Padrão `100`

RiskFlagCreateRequest

Campo	Tipo	Detalhe
reason	string	obrigatório
source_ref	string, opcional

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

← Quadra Command API Chamar no playground →