API Reference

Cria um link hospedado de verificação (o titular abre a jornada sem você montar o widget)

Para quem NÃO vai montar o widget: a UNIFOKAL hospeda a página e você entrega a url ao titular (e-mail, WhatsApp, QR). O link vive HORAS (a sessão vive 900s e só nasce no resgate), o token vlt_ volta em claro uma única vez e o link não cobra nada: quem cobra é a verificação que nascer do resgate. Sem Idempotency-Key de propósito: selar o corpo guardaria o segredo no banco; repetir a chamada só cria outro link, que expira sozinho.

curl --request POST \
  --url https://api.unifokal.com/v1/verification-links \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "flow_id": "<string>",
  "reference_id": "<string>",
  "metadata": {},
  "email": "<unknown>",
  "phone": "<unknown>",
  "expires_in": 61,
  "policy": {
    "allow_pep": true,
    "allow_betting_ban": true,
    "ubo_max_paid_nodes": 5
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    flow_id: '<string>',
    reference_id: '<string>',
    metadata: {},
    email: '<unknown>',
    phone: '<unknown>',
    expires_in: 61,
    policy: {allow_pep: true, allow_betting_ban: true, ubo_max_paid_nodes: 5}
  })
};

fetch('https://api.unifokal.com/v1/verification-links', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.unifokal.com/v1/verification-links"

payload = {
    "flow_id": "<string>",
    "reference_id": "<string>",
    "metadata": {},
    "email": "<unknown>",
    "phone": "<unknown>",
    "expires_in": 61,
    "policy": {
        "allow_pep": True,
        "allow_betting_ban": True,
        "ubo_max_paid_nodes": 5
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "<string>",
  "environment": "sandbox",
  "flow_id": "<string>",
  "reference_id": "<string>",
  "contact_masked": "<string>",
  "created_via": "api",
  "created_by_member_id": "<string>",
  "status": "pending",
  "expires_at": "2023-11-07T05:31:56Z",
  "opened_at": "2023-11-07T05:31:56Z",
  "consumed_at": "2023-11-07T05:31:56Z",
  "session_id": "<string>",
  "revoked_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "url": "<string>",
  "token": "<string>",
  "purpose": "verification",
  "act_kind": "<string>",
  "act_digest": "<string>",
  "expires_in": 123,
  "livemode": true
}

{
  "error": "invalid_json",
  "message": "<string>"
}

{
  "error": "invalid_api_key",
  "message": "<string>"
}

{
  "error": "email_not_verified",
  "message": "<string>"
}

{
  "error": "flow_not_found",
  "message": "<string>"
}

{
  "error": "confirmation_unavailable",
  "message": "<string>"
}

{
  "error": "payload_too_large",
  "message": "<string>"
}

{
  "error": "flow_not_live",
  "message": "<string>"
}

{
  "error": "confirmation_rate_limited",
  "message": "<string>"
}

Autorizações

Authorization

string

header

obrigatório

Chave secreta (unifokal_live_ em produção, unifokal_test_ no sandbox: 64 hex mais CRC-32) 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

application/json

flow_id

string

obrigatório

Id do flow que define os módulos da verificação (prefixo flow_). O flow precisa estar live no ambiente da credencial.

Minimum string length: 1

reference_id

string

obrigatório

Seu identificador do titular/da tentativa. Volta EM CLARO na resposta e no webhook da verificação: 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.

Required string length: 1 - 255

metadata

object

OPCIONAL. Até 20 pares de texto SEUS (o número do pedido, a filial, o canal) que voltam exatos no webhook da verificação (data.metadata) e no dossiê do painel. Chave de 1 a 40 caracteres (letra ou dígito na frente, depois letra, dígito, ponto, sublinhado, dois-pontos e hífen); valor de 1 a 500 caracteres, só texto, sem caractere de controle e sem =, +, - ou @ na frente. Nunca decide nada. O conjunto serializado em JSON UTF-8 vai até 15872 bytes, senão 422 metadata_too_large. Nunca coloque dado pessoal aqui: chave ou valor com forma de CPF, CNPJ, e-mail, telefone ou chave Pix, inteiro ou no meio do texto, é recusado com 422 pii_shaped_value. A sessão que o link abre herda o mesmo metadata.

Show child attributes

any

RECUSADO com 422 email_not_accepted: a página hospedada PEDE o e-mail ao titular e dispara o código em seguida, igual ao telefone. Nunca envie o endereço na emissão.

phone

any

RECUSADO com 422 phone_not_accepted: o telefone é sempre digitado pelo titular no widget, nunca enviado na emissão.

expires_in

integer

Validade do LINK em segundos (mínimo 60; acima do teto da casa é 422 expires_in_too_long, nunca um clamp silencioso). Não confunda com a vida da sessão, que só nasce no resgate.

Intervalo obrigatório: x >= 60

policy

object

Override de política por sessão, validado JÁ NA EMISSÃO (a sessão do resgate herda). Política de módulo que o flow não tem é 422 policy_module_not_in_flow, e o teto ubo_max_paid_nodes só APERTA o do flow (acima dele é 422 policy_ubo_cap_above_flow).

Show child attributes

environment

enum<string>

SÓ para a superfície de painel. Com a chave secreta o ambiente É a chave: mandar um diferente é 422 environment_mismatch (aceitar e ignorar faria você acreditar que trocou de ambiente).

Opções disponíveis:

sandbox,

production

purpose

enum<string>

verification (padrão, o link de sempre) ou confirmation: o pedido pontual de CONFIRMAÇÃO FORA DE BANDA. A confirmação exige o bloco act, um flow com passkey ou face_reauth e uma conta com o fator (422 no_factor_enrolled); vale até 600 segundos (padrão 600; acima é 422 expires_in_too_long_for_confirmation); no máximo um pedido aberto por pessoa (o novo substitui o anterior, que é revogado) e cinco por hora (429 confirmation_rate_limited, com Retry-After). O link é transporte, não fator: quem confirma é a passkey com verificação do usuário ou a reautenticação facial com prova de vida.

Opções disponíveis:

verification,

confirmation

act

object

O ATO que a pessoa confirma, só com purpose confirmation (no link comum é 422 act_not_accepted): kind (até 40) e summary (até 140) obrigatórios; amount_cents, currency BRL e counterparty (até 80) opcionais; external_id, o id único do ato no seu sistema, obrigatório pela API. O digest act-v1 é calculado uma vez na criação e volta igual no verification.completed (data.act.digest) e no act.rejected.

Show child attributes

esignature

object

Show child attributes

Resposta

Link criado. Entregue a url ao titular; o token não é reexibido.

Resposta 201 da criação do link hospedado. O campo token (vlt_) é devolvido EM CLARO uma única vez e nunca é reexibido: guarde-o ou entregue a url ao titular na mesma resposta.

string

obrigatório

Id do link hospedado (vl_ + ULID). NÃO é o segredo: o segredo é o token vlt_.

Pattern: ^vl_[0-9A-HJKMNP-TV-Z]{26}$

environment

enum<string>

obrigatório

Opções disponíveis:

sandbox,

production

flow_id

string

obrigatório

Id de flow (flow_ + ULID). Criado no painel, nunca pela API da chave secreta.

Pattern: ^flow_[0-9A-HJKMNP-TV-Z]{26}$

reference_id

string | null

obrigatório

contact_masked

string | null

obrigatório

E-mail MASCARADO, e só quando o flow verifica e-mail: o endereço em claro fica cifrado no repouso e nunca volta por aqui.

created_via

enum<string>

obrigatório

Opções disponíveis:

api,

dashboard

created_by_member_id

string | null

obrigatório

Membro que emitiu pelo painel. Emissão pela chave secreta não tem membro: null.

status

enum<string>

obrigatório

Estado do link. consumed significa que alguém resgatou e a sessão nasceu (veja session_id).

Opções disponíveis:

pending,

opened,

consumed,

expired,

revoked

expires_at

string<date-time>

obrigatório

opened_at

string<date-time> | null

obrigatório

consumed_at

string<date-time> | null

obrigatório

session_id

string | null

obrigatório

Sessão criada no resgate do link. Null até alguém abrir e resgatar.

revoked_at

string<date-time> | null

obrigatório

created_at

string<date-time>

obrigatório

url

string<uri>

obrigatório

A página hospedada, com o token embutido. É o que você entrega ao titular.

token

string

obrigatório

Segredo do link (vlt_), em claro UMA vez. Guardamos só o hash: não há como reexibir.

purpose

enum<string>

obrigatório

verification = o link de sempre; confirmation = o pedido de confirmação fora de banda.

Opções disponíveis:

verification,

confirmation

act_kind

string | null

obrigatório

Tipo do ato da confirmação. Null no link comum.

act_digest

string | null

obrigatório

Digest act-v1 (sha256 hex) do ato, calculado uma vez na criação. O mesmo volta em data.act.digest do verification.completed. Null no link comum.

Pattern: ^[0-9a-f]{64}$

expires_in

integer

obrigatório

Segundos de validade do link (não da sessão).

livemode

boolean

obrigatório

Cria um link hospedado de verificação (o titular abre a jornada sem você montar o widget)

curl --request POST \
  --url https://api.unifokal.com/v1/verification-links \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "flow_id": "<string>",
  "reference_id": "<string>",
  "metadata": {},
  "email": "<unknown>",
  "phone": "<unknown>",
  "expires_in": 61,
  "policy": {
    "allow_pep": true,
    "allow_betting_ban": true,
    "ubo_max_paid_nodes": 5
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    flow_id: '<string>',
    reference_id: '<string>',
    metadata: {},
    email: '<unknown>',
    phone: '<unknown>',
    expires_in: 61,
    policy: {allow_pep: true, allow_betting_ban: true, ubo_max_paid_nodes: 5}
  })
};

fetch('https://api.unifokal.com/v1/verification-links', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.unifokal.com/v1/verification-links"

payload = {
    "flow_id": "<string>",
    "reference_id": "<string>",
    "metadata": {},
    "email": "<unknown>",
    "phone": "<unknown>",
    "expires_in": 61,
    "policy": {
        "allow_pep": True,
        "allow_betting_ban": True,
        "ubo_max_paid_nodes": 5
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "<string>",
  "environment": "sandbox",
  "flow_id": "<string>",
  "reference_id": "<string>",
  "contact_masked": "<string>",
  "created_via": "api",
  "created_by_member_id": "<string>",
  "status": "pending",
  "expires_at": "2023-11-07T05:31:56Z",
  "opened_at": "2023-11-07T05:31:56Z",
  "consumed_at": "2023-11-07T05:31:56Z",
  "session_id": "<string>",
  "revoked_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "url": "<string>",
  "token": "<string>",
  "purpose": "verification",
  "act_kind": "<string>",
  "act_digest": "<string>",
  "expires_in": 123,
  "livemode": true
}

{
  "error": "invalid_json",
  "message": "<string>"
}

{
  "error": "invalid_api_key",
  "message": "<string>"
}

{
  "error": "email_not_verified",
  "message": "<string>"
}

{
  "error": "flow_not_found",
  "message": "<string>"
}

{
  "error": "confirmation_unavailable",
  "message": "<string>"
}

{
  "error": "payload_too_large",
  "message": "<string>"
}

{
  "error": "flow_not_live",
  "message": "<string>"
}

{
  "error": "confirmation_rate_limited",
  "message": "<string>"
}