Criar dossiê

POST 
/kyc/v1/dossiers

Abre um dossiê de KYC para um CPF ou CNPJ e enfileira a consulta aos birôs. A consulta é assíncrona: a resposta é 202 com o dossiê em processing. Acompanhe pelo GET /kyc/v1/dossiers/{dossier_id} ou pelo webhook onboarding.kyc.completed.

Cada criação consome 1 unidade da cota diária da chave. O campo origin é definido pelo servidor como api; o valor enviado no corpo é ignorado.

Repetir com segurança (Idempotency-Key, opcional). Envie um identificador único por pedido, de 16 a 128 caracteres (por exemplo, um UUID). Se precisar repetir o pedido, após uma falha de rede ou timeout, reenvie com a mesma chave e o mesmo corpo: você recebe o dossiê já aberto, com o header de resposta Idempotency-Replayed: true, sem abrir outro dossiê e sem consumir cota (202 se ainda está em processamento, 200 se já terminou). Para receber o dossiê na repetição, a chave de API precisa ter permissão para consultar dossiês.

• A mesma Idempotency-Key com corpo diferente retorna 422 idempotency_key_conflict.
• Duas requisições simultâneas com a mesma chave: uma abre o dossiê e a outra recebe 409 idempotency_key_in_flight; repita com a mesma chave.
• Chave com menos de 16 ou mais de 128 caracteres retorna 400 invalid_idempotency_key.
• A chave vale por workspace. Sem o header, cada chamada abre um dossiê novo.

Request

Responses

200

Repetição com Idempotency-Key de um dossiê que já terminou: o dossiê, no mesmo formato da criação. Só ocorre com o header; sem ele a criação responde sempre 202.

Response Headers

Idempotency-Replayed

true quando a resposta é a repetição de uma Idempotency-Key já atendida: nada novo foi criado nem cobrado.

202

Dossiê aceito, com status processing. É também a resposta de uma repetição com Idempotency-Key enquanto o dossiê ainda está em processamento.

Response Headers

Idempotency-Replayed

true quando a resposta é a repetição de uma Idempotency-Key já atendida: nada novo foi criado nem cobrado.

400

Requisição inválida: documento malformado ou parâmetro inválido ou fora de faixa.

401

x-api-key ausente, desconhecida ou inválida.

403

Acesso negado. O campo error.code diz o motivo:

• forbidden: chave revogada ou desabilitada, sem permissão para a operação, ou workspace inativo;
• ip_not_allowed: a chave tem restrição por IP de origem e a requisição veio de fora da lista (origem da requisição não autorizada para esta chave de API). A resposta não informa a lista nem o IP visto;
• quota_not_configured: a chave não tem teto diário configurado, e chave sem teto não cria dossiê. Peça ao administrador do workspace para definir o teto;
• route_not_in_plan: o plano de API do workspace não inclui esta rota. É verificado a cada chamada.

409

idempotency_key_in_flight: outra requisição simultânea com a mesma Idempotency-Key acabou de abrir o dossiê, e esta não criou nada. Repita com a mesma chave.

422

idempotency_key_conflict: a mesma Idempotency-Key já foi usada neste workspace com um corpo diferente. Use outra chave para um pedido diferente. Não consome cota.

429

Limite atingido. O campo error.code diz qual:

• quota_exceeded: a cota diária da chave acabou. Volta a valer no dia seguinte (UTC);
• kyc_creation_limit_reached: limite de criação de dossiês do workspace, diário ou mensal, somando todos os canais. Os campos details.periodo e details.volta_a_valer_em informam qual limite e quando volta. Nesse caso a unidade da cota da chave já foi consumida e não é devolvida.