Sub-contas - Link de credenciamento (KYC)

#Visão Geral

O link de credenciamento é a forma de o vendedor completar o cadastro da sub-conta sem ter login na Selectwin: você gera o link e o envia a ele (por e-mail, WhatsApp, pelo seu próprio sistema); ele abre uma página hospedada pela Selectwin, preenche os dados da empresa e do responsável, envia os documentos e a conta de saque, e o cadastro entra em análise. Você acompanha pelos webhooks seller.* ou por consulta.

#Precauções

• O token (e a url, que o contém) aparece uma vez só, na resposta da geração. Ele não é devolvido depois e não aparece na consulta de status. Guarde-o só o tempo de enviar ao vendedor e não o registre em logs.
• Quem tem o link preenche o cadastro da sub-conta. Envie-o apenas ao vendedor, por um canal que ele controle.
• O link vale por 7 dias. Gerar um novo link revoga o anterior.
• Só uma sub-conta ainda não ativa recebe link. Para uma sub-conta active, a resposta é 422 subAccountAlreadyActive.
• Recurso de conta: gere e revogue links com uma chave sk_live_ (com sk_test_, 409 accountLevelReadOnlyInSandbox).

#Gerar o link

POST /v1/marketplace/sub-accounts/{companyId}/kyc-link

Sem corpo. Gera um link novo (e revoga o que estivesse ativo).

#Resposta (201 Created)

{
  "id": "kycl_01hqzvlink1",
  "token": "4f8c…e21b",
  "url": "https://…/marketplace/kyc/4f8c…e21b",
  "expiresAt": "2026-10-24T12:00:00.000Z",
  "status": "active"
}

#Consultar o status do link

GET /v1/marketplace/sub-accounts/{companyId}/kyc-link

#Resposta (200 OK)

{ "active": true, "id": "kycl_01hqzvlink1", "expiresAt": "2026-10-24T12:00:00.000Z" }

Sem link ativo: { "active": false, "id": null, "expiresAt": null }. O token nunca é devolvido aqui.

#Revogar o link

DELETE /v1/marketplace/sub-accounts/{companyId}/kyc-link

Invalida o link ativo na hora (um link vazado, ou enviado por engano). Gere outro quando precisar.

#Resposta (200 OK)

{ "id": "bus_01hqzvsub1", "revoked": true }

#Erros

#Depois do envio

Quando o vendedor termina, a sub-conta passa a analyzing (webhook seller.analyzing, kycSubmittedAt preenchido). O resultado chega por seller.approved (a sub-conta fica active) ou seller.refused. Se a análise pedir documentos de novo, seller.kycRequired (status awaiting-documents): gere um novo link e peça ao vendedor que reenvie.

#Exemplo

curl -X POST "https://api.selectwin.io/v1/marketplace/sub-accounts/bus_01hqzvsub1/kyc-link" \
     -H "SelectKey: sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"