> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kycert.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboarding completo via Customers

> Fluxo fim-a-fim: cadastrar cliente, anexar documento, disparar bureau e consultar o resultado

Este guia cobre o caminho mais comum para quem integra onboarding real: cadastro do cliente, upload de documento, verificação de bureau e consulta do resultado final. Se você só precisa de uma verificação pontual sem manter um cadastro permanente, veja o [Quick Start](/quickstart) (`POST /bureau/runs` direto).

## Visão geral

```mermaid theme={null}
sequenceDiagram
    participant I as Seu backend
    participant K as API kycert
    participant W as Seu endpoint de webhook

    I->>K: POST /customers (run_bureau: true)
    K-->>I: 201 — customer_id, run_id, bureau_status: queued
    I->>K: POST /customers/:id/documents
    K-->>I: 201 — document_id, status: pendente
    K->>W: POST run.completed (status: completed, decision: approved)
    W-->>K: 200
    I->>K: GET /customers/:id
    K-->>I: 200 — status conforme política do tenant, latest_run, documents[]
```

***

## Passo 1 — Criar o cliente e disparar o bureau

Envie `run_bureau: true` para dispensar uma segunda chamada — o bureau roda imediatamente após o cadastro. Veja [Campo `run_bureau`](/api-reference/createCustomer#campo-run_bureau) para o comportamento completo, incluindo resolução de template padrão.

```bash theme={null}
curl -X POST https://admin.kycert.com.br/api/v1/customers \
  -H "x-api-key: $KYCERT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "pf", "doc": "12345678901", "name": "João Silva", "email": "joao@example.com", "run_bureau": true, "template_id": "f716ee22-3933-407b-9bf3-d82ab391ef94" }'
```

```json theme={null}
{
  "customer_id": "661e9511-f3ac-52e5-b827-557766551111",
  "object": "customer",
  "status": "em_analise",
  "type": "pf",
  "name": "João Silva",
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "bureau_status": "queued",
  "livemode": true
}
```

Guarde `customer_id` (para os próximos passos) e `run_id` (para correlacionar com o evento de webhook no Passo 3).

<Note>
  Use `Idempotency-Key` nesta chamada — retry de rede sem a chave pode disparar um segundo bureau run para o mesmo cliente, cobrado em dobro. Veja [Idempotência](/guias/idempotencia).
</Note>

***

## Passo 2 — Anexar o documento

Com o `customer_id` do passo anterior, envie o documento via `multipart/form-data`:

```bash theme={null}
curl -X POST https://admin.kycert.com.br/api/v1/customers/661e9511-f3ac-52e5-b827-557766551111/documents \
  -H "x-api-key: $KYCERT_API_KEY" \
  -F "type=comprovante_endereco" \
  -F "file=@/caminho/para/comprovante.pdf"
```

```json theme={null}
{
  "document_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "object": "document",
  "type": "comprovante_endereco",
  "status": "pendente",
  "file_name": "comprovante.pdf",
  "mime_type": "application/pdf",
  "created_at": "2026-06-12T14:00:00Z",
  "livemode": true
}
```

Este passo é independente do bureau — pode rodar em paralelo ao Passo 1, não precisa esperar o `run.completed`. Detalhes completos (catálogo de `type`, limite de 4MB, reenvio) em [Anexar documento](/api-reference/uploadCustomerDocument).

***

## Passo 3 — Receber o resultado via webhook

Quando o bureau concluir, seu endpoint de webhook recebe `run.completed`. O `data.id` é o mesmo `run_id` retornado no Passo 1 — use-o para correlacionar o evento com o cliente.

```json theme={null}
{
  "id": "evt_01J4ZR...",
  "object": "event",
  "event": "run.completed",
  "created": 1718200818,
  "livemode": true,
  "data": {
    "object": "run",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "decision": "approved",
    "risk_band": "baixo",
    "subject_type": "pf",
    "template_id": "f716ee22-3933-407b-9bf3-d82ab391ef94",
    "external_id": null,
    "metadata": {},
    "checks_summary": { "total": 12, "valid": 12, "invalid": 0, "no_data": 0, "error": 0 },
    "created_at": "2026-06-12T14:00:00Z",
    "completed_at": "2026-06-12T14:00:18Z"
  }
}
```

<Warning>
  Sempre verifique o header `kycert-signature` antes de processar — qualquer servidor pode fazer POST para o seu endpoint. Veja [Segurança de Webhooks](/webhooks/seguranca).
</Warning>

Payload completo, todos os eventos disponíveis e política de retry em [Visão geral de webhooks](/webhooks/overview).

***

## Passo 4 — Consultar o cliente

Com o run concluído, `GET /customers/:id` já reflete a decisão. O `status` do cliente **não** é um mapeamento fixo do `decision`/`risk_band` do run — é decidido pela política de decisão automática do tenant (**Configurações → Decisão KYC**), configurável por faixa de risco. No exemplo abaixo, o tenant tem essa política configurada para aprovar automaticamente risco `baixo` — por isso o cliente sai como `aprovado`. Sem essa política configurada, o cliente permanece `em_analise` independente do resultado do run. Veja [Status de bureau run vs status de cliente](/conceitos#status-de-bureau-run-vs-status-de-cliente) para a regra completa.

```bash theme={null}
curl https://admin.kycert.com.br/api/v1/customers/661e9511-f3ac-52e5-b827-557766551111 \
  -H "x-api-key: $KYCERT_API_KEY"
```

```json theme={null}
{
  "customer_id": "661e9511-f3ac-52e5-b827-557766551111",
  "object": "customer",
  "status": "aprovado",
  "type": "pf",
  "name": "João Silva",
  "email": "joao@example.com",
  "doc": "***456789**",
  "latest_run": {
    "run_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "decision": "approved",
    "risk_band": "baixo",
    "completed_at": "2026-06-12T14:00:18Z"
  },
  "documents": [
    { "type": "comprovante_endereco", "status": "pendente", "created_at": "2026-06-12T14:00:00Z" }
  ],
  "livemode": true
}
```

`documents[].status` fica `pendente` até revisão manual no dashboard — anexar o documento não depende do resultado do bureau nem é aprovado automaticamente. Detalhes completos em [Buscar cliente](/api-reference/getCustomer).

***

## Próximos passos

* [Segurança de Webhooks](/webhooks/seguranca) — verificação de assinatura HMAC-SHA256 com exemplos em 3 linguagens
* [Idempotência](/guias/idempotencia) — retries seguros em qualquer chamada de escrita
* [Sandbox](/autenticacao#sandbox) — chaves `sk_test_...` e `livemode: false`
* [Tratamento de erros](/guias/erros) — catálogo completo de códigos, incluindo os de `createCustomer` e `uploadCustomerDocument`