Cria uma sessão de verificação (a única chamada obrigatória do integrador)
O 201 nunca traz decisão: o resultado chega no seu webhook (a fonte da verdade). IDEMPOTÊNCIA: esta rota não usa header nenhum. O reference_id (obrigatório) É a chave: a mesma organização, no mesmo ambiente, com o mesmo reference_id, recebe de volta a MESMA sessão ENQUANTO ELA VIVER (expires_in), em vez de uma segunda (o replay volta com Idempotent-Replay: true). Expirada a sessão, o mesmo reference_id abre uma sessão nova, que é o que a pessoa precisa para tentar de novo. Repetir o reference_id com um corpo DIFERENTE é 422 idempotency_key_reuse; com a primeira chamada ainda em voo, 409 idempotency_conflict. Exceto quando o corpo traz act: aí a chave é act.external_id, pelo prazo da sessão de prova.
Autorizações
Chave secreta sk_ no Authorization: Bearer. Só no seu servidor: nunca no browser ou app (o widget monta apenas com o id vs_ da sessão). Não existe chave publishable.
Corpo
Id do flow que define os módulos da verificação (prefixo flow_).
1OBRIGATÓRIO, e ele É A CHAVE DE IDEMPOTÊNCIA desta rota (não existe header), exceto quando o corpo traz act, cuja chave é act.external_id: a mesma organização, no mesmo ambiente, com o mesmo reference_id, recebe de volta a MESMA sessão enquanto ela viver, em vez de uma segunda. Volta EM CLARO no 201 e no webhook: nunca coloque dado pessoal aqui. De 1 a 255 caracteres: letras, dígitos e . _ : @ -, sem começar por - nem @. Espaço nas pontas é aparado; caractere invisível ou fora do conjunto é 422 reference_id_charset, e um valor com forma de dado pessoal (CPF, CNPJ, telefone, e-mail) é 422 pii_shaped_value. Use o id do usuário no seu sistema, por exemplo um UUID.
1 - 255OPCIONAL. Um rótulo SEU para a origem da jornada (a campanha, o canal, a tela de onde a pessoa veio), de 1 a 64 caracteres: letras, dígitos, ponto, sublinhado, dois-pontos e hífen, começando por letra ou dígito (sem espaço, arroba, barra nem interrogação, então não cabe e-mail nem URL). Volta EXATO, sem mudar a caixa, no 201 da criação e no webhook da verificação (data.origin_tag); a sessão renovada pelo widget herda o mesmo valor. Use minúsculas como convenção: ferramentas de análise tratam caixa como valor diferente. Nunca coloque dado pessoal aqui. Não é aceito junto do bloco de transação (422 origin_tag_not_supported). Como entra no corpo, a idempotência vale para ele também: repetir o reference_id com outro origin_tag é 422 idempotency_key_reuse.
64^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$RECUSADO com 422 email_not_accepted: o e-mail é sempre digitado pelo titular no widget, que também dispara o código em seguida. Nunca envie o endereço na criação.
RECUSADO com 422 phone_not_accepted: o telefone é sempre digitado pelo titular no widget, nunca enviado na criação.
Override de política por sessão (whitelist fechada; chave desconhecida vira 400, nunca é ignorada em silêncio).
Para onde o WIDGET manda o titular quando a verificação termina. Existe para o caso do APLICATIVO NATIVO: no iOS o caminho recomendado é abrir a verificação no navegador do sistema, e sem destino de volta o titular acaba e fica preso lá. Aceita https ou o esquema PRÓPRIO do seu aplicativo (meubanco://kyc/pronto); os esquemas que o navegador interpreta sozinho (javascript:, data:, blob:, file:, intent: e afins) são recusados com 400, e http também (a volta depois de uma verificação de identidade não desce para texto claro). A volta NÃO carrega desfecho, score nem nada da verificação, nem em query nem em fragmento: um redirecionamento no browser do titular é forjável por quem controla o aparelho, então quem conta o que aconteceu é o WEBHOOK, e o seu aplicativo pergunta ao próprio backend. Ausente = ninguém é redirecionado. Destino https só vale com o host na lista de destinos de retorno do ambiente (painel, Organização): comparação exata de host, curinga só na forma *.seudominio.com.br cobrindo um nível, e host fora da lista é recusado com 400 return_url_not_allowed. Sem lista no ambiente, a sessão é criada mas o titular termina na tela de conclusão, sem redirecionamento. O esquema próprio do aplicativo não tem host a comparar e não depende da lista.
2048A relação da sua empresa com o titular, como a Lei 12.414 (art. 15) exige para consultar dado de crédito: existing (você já mantém relação comercial ou de crédito com ele) ou prospective (vai iniciar uma). OBRIGATÓRIO quando o flow contém módulo de crédito (422 credit_relationship_required) e RECUSADO quando não contém (422 credit_relationship_not_supported). A finalidade da consulta vem do flow (credit_purpose, art. 7) e fica carimbada na sessão; a sua conta precisa ter CNPJ cadastrado e verificado, porque ela é o consulente (422 credit_requester_unverified). A consulta de crédito só sai com a identidade APROVADA, e cada consulta fica registrada com finalidade, relação e consulente. Os módulos de crédito estão em "Em breve".
existing, prospective Evento de transação (ingestão). Só é aceito em flow que contenha um módulo consumidor de transação; hoje esse módulo é o Gate Transacional (transaction_gate). Flow sem consumidor responde 422 transaction_not_supported. É exclusivo com transactions (os dois juntos = 422 transaction_conflict), external_id é obrigatório (idempotência durável) e, sem id natural, derive sha256(reference_id|type|amount_cents|occurred_at|posição); a resposta 201 traz a forma de ingestão (id ing_ + contadores) e, em flow com gate síncrono, o veredito do gate.
Lote de eventos (ingestão). Mesma condição do campo transaction: flow sem módulo consumidor responde 422 transaction_not_supported. Aceita 1..teto INGEST_MAX_BATCH (acima = 422 batch_too_large com o teto no corpo) e reenviar o mesmo lote não duplica nem cobra de novo (dedupe por external_id). ATENÇÃO: o lote é PROIBIDO quando o flow contém um gate síncrono, e o Gate Transacional (transaction_gate) é um, então nesse flow use transaction (singular): o lote responde 422 batch_not_supported_for_gate, porque um gate decide UM pagamento e um lote não teria veredito.
1Bloco do módulo esignature (assinatura eletrônica avançada): document_sha256 é o SHA-256, em hex, do documento que o titular vai assinar. O documento em si NUNCA é enviado: você guarda os bytes, a UNIFOKAL amarra o hash à verificação aprovada e devolve o dossiê assinado (Ed25519) no webhook. OBRIGATÓRIO quando o flow contém o módulo (422 esignature_document_required) e RECUSADO quando não contém (422 esignature_not_supported); chave desconhecida dentro do bloco vira 400 unknown_esignature_key, nunca é ignorada em silêncio. Em produção, o módulo vende quando a chave da plataforma de produção está publicada; até lá, criar flow de produção com ele responde 422.
Bloco do módulo authorization_custody (custódia da autorização de consulta ao SCR): text_sha256 é o SHA-256, em hex, do texto de autorização que o titular leu e aceitou; text_version é a versão desse texto no seu sistema; scope é o escopo autorizado (hoje, scr). O texto em si NUNCA é enviado. Com a verificação aprovada, a UNIFOKAL registra a autorização amarrada à identidade verificada e ao consentimento da sessão, com prova assinada que qualquer um confere sem depender da UNIFOKAL, e guarda o registro por cinco anos contados da última consulta que você registra no painel. OBRIGATÓRIO quando o flow contém o módulo (422 consultation_authorization_required) e RECUSADO quando não contém (422 consultation_authorization_not_supported); chave desconhecida dentro do bloco vira 400 unknown_consultation_authorization_key. Em produção, o módulo vende quando a chave de custódia de produção está publicada; até lá, criar flow de produção com ele responde 422.
Bloco do módulo kyb_foreign (empresa de fora do Brasil, sem CNPJ): lei é o identificador de entidade legal da empresa (ISO 17442, 20 caracteres); sem ele, name e country (a mesma lista fechada de países do painel), nunca os dois. beneficial_owners é opcional: até 20 beneficiários finais pessoa natural que você declara, só pelo nome, triados nas listas de sanções e de pessoas expostas politicamente; os nomes ficam cifrados e nunca vão ao índice de entidades. OBRIGATÓRIO quando o flow contém o módulo (422 foreign_entity_required) e RECUSADO quando não contém (422 foreign_entity_not_supported); LEI com dígito de controle errado vira 422 foreign_entity_lei_invalid; chave desconhecida vira 400 unknown_foreign_entity_key. O módulo está pausado no catálogo ("Em breve").
- Option 1
- Option 2
Resposta
Sessão criada (monte o widget com o id vs_; nenhum segredo vai ao browser). OU, quando o corpo traz transaction/transactions, a resposta de INGESTÃO (id ing_ + contadores; nenhum vs_).
- Option 1
- Option 2
Resposta 201 da criação. O resultado da verificação chega no seu webhook. Os blocos opcionais decision e policy aparecem só quando o flow tem o módulo que os produz.
Id da sessão de verificação (vs_ + ULID). É o único valor que vai ao browser: o widget monta só com ele.
^vs_[0-9A-HJKMNP-TV-Z]{26}$Id de flow (flow_ + ULID). Criado no painel, nunca pela API sk_.
^flow_[0-9A-HJKMNP-TV-Z]{26}$sandbox, production requires_input, processing, completed, expired Módulos do flow. Valor novo pode surgir sem subir a versão (adição compatível): ignore o que não conhecer.
Segundos até a sessão expirar. Crie a sessão com a pessoa presente; nunca em lote.
Origem da jornada que você mandou na criação, EXATA. Ausente quando você não mandou.
64^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$Veredito do evento de conta, na mesma chamada. Presente só quando o flow tem o módulo conta.
Política efetiva de compliance com que a sessão nasceu, e a origem de cada valor. Presente só quando o flow tem pep_sanctions ou betting_barred; cada par aparece só para o módulo que o flow tem.