Onboarding completo via Customers

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 (POST /bureau/runs direto).

Visão geral

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 para o comportamento completo, incluindo resolução de template padrão.

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" }'

{
  "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).

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.

Passo 2 — Anexar o documento

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

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"

{
  "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.

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.

{
  "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"
  }
}

Sempre verifique o header kycert-signature antes de processar — qualquer servidor pode fazer POST para o seu endpoint. Veja Segurança de Webhooks.

Payload completo, todos os eventos disponíveis e política de retry em Visão geral de webhooks.

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 para a regra completa.

curl https://admin.kycert.com.br/api/v1/customers/661e9511-f3ac-52e5-b827-557766551111 \
  -H "x-api-key: $KYCERT_API_KEY"

{
  "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.

Próximos passos

Segurança de Webhooks — verificação de assinatura HMAC-SHA256 com exemplos em 3 linguagens
Idempotência — retries seguros em qualquer chamada de escrita
Sandbox — chaves sk_test_... e livemode: false
Tratamento de erros — catálogo completo de códigos, incluindo os de createCustomer e uploadCustomerDocument

Começando

Guias

Webhooks

Referência da API

Onboarding completo via Customers

Visão geral

Passo 1 — Criar o cliente e disparar o bureau

Passo 2 — Anexar o documento

Passo 3 — Receber o resultado via webhook

Passo 4 — Consultar o cliente

Próximos passos

​Visão geral

​Passo 1 — Criar o cliente e disparar o bureau

​Passo 2 — Anexar o documento

​Passo 3 — Receber o resultado via webhook

​Passo 4 — Consultar o cliente

​Próximos passos

Visão geral

Passo 1 — Criar o cliente e disparar o bureau

Passo 2 — Anexar o documento

Passo 3 — Receber o resultado via webhook

Passo 4 — Consultar o cliente

Próximos passos