Como criar um onboarding KYC via API?

Para iniciar o processo de KYC (Know Your Customer) de um merchant, você utiliza o endpoint POST /api/v1/kyc/onboarding.

Este endpoint cria um registro de conta (AccountRegister) e retorna um link de onboarding que deve ser enviado ao merchant para que ele preencha seus dados cadastrais.

info

Antes de usar este endpoint, garanta que sua empresa possui as features BAAS e KYC_ONBOARDING_LINK habilitadas e que sua aplicação tenha o scope KYC_ONBOARDING_POST. Veja Primeiros passos com a API de KYC Onboarding para detalhes.

Referência completa

Para o schema, parâmetros e exemplos interativos, veja a API Reference.

Campos

Obrigatórios

• taxID: CNPJ da empresa do merchant. Aceita formato com ou sem máscara (ex: XX.XXX.XXX/0001-XX ou XXXXXXXXXXXXXX). Validado como CNPJ.

Opcionais

• correlationID: Identificador único para idempotência. Se não informado, o CNPJ será usado como correlationID. Se a mesma correlationID for enviada novamente, a API retorna o link existente (200) ao invés de criar um novo.
• representatives: Array de sócios/representantes da empresa. Cada representante deve conter:
  • taxID: CPF do representante. Validado como CPF. Aceita formato com ou sem máscara.

Exemplo

O body da sua requisição será semelhante a este exemplo:

{
  "taxID": "XX.XXX.XXX/0001-XX",
  "correlationID": "my-unique-id",
  "representatives": [
    { "taxID": "XXX.XXX.XXX-XX" },
    { "taxID": "XXX.XXX.XXX-XX" }
  ]
}

Após efetuar a requisição, se tudo ocorreu bem, o status code da requisição será 201 e no body da resposta, retornaremos o link de onboarding e os dados do registro de conta.

Retornaremos a seguinte resposta de exemplo:

{
  "linkOnboarding": "https://kyc.woovi.com/onboarding/QWNjb3VudFJlZ2lzdGVyOjY5...",
  "accountRegister": {
    "status": "PENDING",
    "officialName": "RAZAO_SOCIAL_DA_EMPRESA",
    "tradeName": "NOME_FANTASIA_DA_EMPRESA",
    "taxID": {
      "taxID": "XXXXXXXXXXXXXX",
      "type": "BR:CNPJ"
    },
    "correlationID": "my-unique-id",
    "representatives": [
      {
        "name": "NOME_DO_SOCIO",
        "taxID": {
          "taxID": "XXXXXXXXXXX",
          "type": "BR:CPF"
        }
      }
    ]
  }
}

info

Os campos officialName, tradeName e representatives[].name são preenchidos automaticamente pelo enriquecimento de dados quando disponíveis.

Idempotência

A API é idempotente pelo campo correlationID. Se você enviar a mesma correlationID para a mesma empresa, a API retornará 200 OK com o link de onboarding existente, sem criar um novo registro.

# Primeira chamada → 201 Created
curl -X POST https://api.woovi.com/api/v1/kyc/onboarding \
  -H "Content-Type: application/json" \
  -H "Authorization: SEU_APPID_AQUI" \
  -d '{"taxID": "XX.XXX.XXX/0001-XX", "correlationID": "order-123"}'

# Segunda chamada com mesmo correlationID → 200 OK (mesmo link)
curl -X POST https://api.woovi.com/api/v1/kyc/onboarding \
  -H "Content-Type: application/json" \
  -H "Authorization: SEU_APPID_AQUI" \
  -d '{"taxID": "XX.XXX.XXX/0001-XX", "correlationID": "order-123"}'

Códigos de resposta

Status	Descrição
200	Onboarding já existe para este correlationID (idempotente)
201	Onboarding criado com sucesso
400	Input inválido (taxID ausente ou CNPJ inválido)
401	Credenciais inválidas
403	Empresa sem feature BAAS ou KYC_ONBOARDING_LINK habilitada
405	Método HTTP não permitido (use POST)
409	Já existe um onboarding para este CNPJ com outro correlationID

Exemplos de erro

{
  "error": "Invalid input: taxID is required"
}

{
  "error": "Invalid CNPJ"
}

{
  "error": "An onboarding already exists for this taxID"
}

{
  "error": "Method Not Allowed. Use POST to create an onboarding."
}

{
  "error": "Company does not have BaaS feature enabled"
}

Exemplos em código

Shell + cURL

curl 'https://api.woovi.com/api/v1/kyc/onboarding' -X POST \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: SEU_APPID_AQUI" \
    --data-binary '{
      "taxID": "XX.XXX.XXX/0001-XX",
      "correlationID": "my-unique-id",
      "representatives": [
        { "taxID": "XXX.XXX.XXX-XX" }
      ]
    }'

JavaScript + Fetch

const appId = 'SEU_APPID_AQUI';

const response = await fetch('https://api.woovi.com/api/v1/kyc/onboarding', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': appId,
  },
  body: JSON.stringify({
    taxID: 'XX.XXX.XXX/0001-XX',
    correlationID: 'my-unique-id',
    representatives: [
      { taxID: 'XXX.XXX.XXX-XX' },
    ],
  }),
});

const data = await response.json();

console.log(data.linkOnboarding);
// https://kyc.woovi.com/onboarding/QWNjb3VudFJlZ2lzdGVyOjY5...

Fluxo completo

1. Chamada da API → Cria o onboarding e retorna o linkOnboarding
2. Envie o link ao merchant → O merchant acessa o formulário e preenche os dados
3. Merchant preenche o cadastro → Dados da empresa, endereço, contrato social, documentos dos sócios
4. Merchant submete → O status muda para IN_REVIEW
5. Análise → A equipe analisa os documentos (pode levar até 72h)
6. Aprovação/Rejeição → O status muda para APPROVED ou REJECTED