4. Cripto — cadastrar cliente

Cada cliente é uma pessoa física (CPF). Ele faz o KYC uma vez na plataforma e ganha um Pix fixo (brCode) só dele na sua loja. Pré-requisitos: empresa ativa, cripto liberado e chave SECRET com CRYPTO_READ e CRYPTO_WRITE (Primeiros passos).

sequenceDiagram
  participant S as Seu sistema
  participant G as Plataforma
  participant C as Cliente
  S->>G: POST /crypto/customers
  alt CPF novo
    G-->>S: 201 PENDING + tosLink + kycLink
    S->>C: envia os dois links
    C->>G: aceita os termos e faz o KYC
    G-->>S: webhook crypto.customer.updated (ACTIVE + brCode)
  else CPF já aprovado em outra loja
    G-->>S: 201 ACTIVE + brCode
  end

Passo 1 — Cadastrar

Use o id do cliente no seu sistema como externalRef: ele serve no lugar do customerId em todas as chamadas.

curl -X POST https://api.gestaotechnology.com/api/crypto/customers \
  -H "X-Api-Key: <SECRET_KEY>" -H "Content-Type: application/json" \
  -d '{
    "name": "Fulano da Silva",
    "email": "[email protected]",
    "document": "12345678901",
    "externalRef": "cliente-42"
  }'

{
  "customerId": "aaa61c8a-f702-4f02-aa16-0a803a232e0e",
  "status": "PENDING",
  "kycLink": "https://kyc.exemplo/…",
  "tosLink": "https://termos.exemplo/…",
  "brCode": null
}

O name precisa ser o nome completo como no documento: o KYC confere.

Passo 2 — Enviar os links ao cliente

Mande o tosLink (aceite dos termos) e o kycLink (documentos e selfie), nessa ordem. O cliente faz tudo no navegador ou no celular. Chamar o POST de novo com os mesmos dados é seguro: devolve o mesmo cadastro e os mesmos links.

Passo 3 — Aprovação → webhook `crypto.customer.updated`

{
  "event": "crypto.customer.updated",
  "occurredAt": "2026-10-15T15:12:03.000Z",
  "data": {
    "customerId": "aaa61c8a-f702-4f02-aa16-0a803a232e0e",
    "status": "ACTIVE",
    "brCode": "00020126580014br.gov.bcb.pix…6304E81E"
  }
}

Guarde o brCode: é o Pix fixo do cliente na sua loja. Ele não muda e não tem valor embutido.

Se o webhook não chegar, consulte (também aceita a externalRef):

curl -s https://api.gestaotechnology.com/api/crypto/customers/cliente-42 -H "X-Api-Key: <SECRET_KEY>"

`status`	O que fazer
`PENDING`	Cliente ainda não enviou o KYC. Reenvie os links.
`IN_REVIEW`	Em análise. Aguarde o webhook.
`ACTIVE`	Pronto: `brCode` disponível.
`REJECTED`	Recusado. O cliente pode tentar de novo pelos links.
`RESTRICTED` / `DISABLED`	Bloqueado pelo provedor. Fale com o suporte.

Cliente já aprovado em outra loja

Se o CPF já passou pelo KYC na plataforma (em qualquer loja), o POST volta ACTIVE na hora, com um brCode novo, só da sua loja. Não há links nem webhook a esperar:

{
  "customerId": "aaa61c8a-f702-4f02-aa16-0a803a232e0e",
  "status": "ACTIVE",
  "kycLink": null,
  "tosLink": null,
  "brCode": "00020126580014br.gov.bcb.pix…6304E81E"
}

Se o CPF começou o KYC por outra loja e ainda não terminou, você recebe o status com os links nulos: o cliente conclui pelo link que já recebeu.

Erros comuns

Resposta	Quando	O que fazer
`409 identity_mismatch`	A `externalRef` já foi usada com outro CPF, ou o documento tem cadastro de empresa.	Confira o CPF com o cliente. Nada foi gravado.
`409 merchant_not_ready`	Sua empresa não está ativa.	Fale com o suporte.
`403 crypto_disabled`	Cripto não liberado para a sua empresa.	Peça a liberação.
`400`	`document` sem 11 dígitos, e-mail inválido, nome curto.	Corrija o corpo.

Próximo: Receber depósito. Referência: Cadastro do cliente.