Autenticação e segurança

# A chave secreta NUNCA sai do seu servidor. Aqui ela vem do ambiente, nunca do arquivo:
#   export UNIFOKAL_SECRET_KEY="sk_live_..."     (use sk_test_... para sandbox)
#
# O ambiente (sandbox ou producao) e definido pela CHAVE, nao por um campo do corpo.

curl -sS -i -X POST https://api.unifokal.com/v1/verification-sessions \
  -H "Authorization: Bearer $UNIFOKAL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "flow_id": "flow_01J8ZQ2R6K7T8V9W0X1Y2Z3A4B",
        "reference_id": "usr_8842"
      }'

# NAO existe campo "email" nem campo "phone": o contato do titular NUNCA entra aqui. Quem pergunta
# o e-mail e o telefone a pessoa, e dispara o codigo em seguida, e o widget. Mandar um dos dois
# devolve 422 email_not_accepted / phone_not_accepted (recusamos com nome, nunca ignoramos em
# silencio). Um flow com email_otp cria sessao com este MESMO corpo.

# O QUE ESPERAR DE VOLTA (201). Guarde o "id": e ele, e so ele, que vai para o navegador.
# A resposta vem comentada para o bloco inteiro poder ser colado no terminal sem erro de sintaxe.
#
# HTTP/1.1 201 Created
# {
#   "id": "vs_01J8ZQ4S8M2N3P4Q5R6S7T8U9V",
#   "flow_id": "flow_01J8ZQ2R6K7T8V9W0X1Y2Z3A4B",
#   "environment": "production",
#   "reference_id": "usr_8842",
#   "status": "requires_input",
#   "expires_at": "2026-08-25T18:15:00.000Z",
#   "created_at": "2026-08-25T18:00:00.000Z",
#   "modules": ["cpf_ocr", "face", "liveness"],
#   "livemode": true,
#   "expires_in": 900
# }

# "expires_in" e o prazo em SEGUNDOS: 900 = 15 minutos. Depois disso o widget nao sobe
# mais com esse id, e voce cria outra sessao.
# "modules" sao os modulos do flow, na ordem. Voce nao declara modulos no widget.
#
# A criacao NAO cobra nada: nenhum centavo sai da sua conta aqui. A cobranca acontece quando a
# verificacao TERMINA, e o saldo atualizado chega no seu webhook do desfecho.
#
# IDEMPOTENCIA: nao existe header. O "reference_id" (obrigatorio) E a chave, do nosso lado. Repetir
# a chamada com o MESMO reference_id, enquanto a sessao estiver viva, devolve a MESMA sessao, com o
# header "Idempotent-Replay: true": um retry do seu backend nao cria (nem cobra) uma segunda. Quando
# a sessao expira (900 s), o mesmo reference_id cria uma sessao NOVA, que e o que o
# titular precisa para tentar de novo.

# O envelope de erro e SEMPRE o mesmo, em toda a API:
#     { "error": "<codigo estavel>", "message": "<texto legivel>" }
# Trate pelo "error". O "message" e para humano e pode mudar; o codigo nao muda dentro de /v1.

# Reproduza um erro AGORA, com a sua chave de sandbox, e confira o formato com os proprios olhos:
curl -sS -i -X POST https://api.unifokal.com/v1/verification-sessions \
  -H "Authorization: Bearer $UNIFOKAL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"flow_id": "flow_esse_nao_existe"}'

# O QUE ESPERAR DE VOLTA: 404 com o envelope acima. Os outros que voce vai encontrar estao listados
# abaixo, comentados, para este bloco inteiro poder ser colado no terminal sem erro de sintaxe.

# 401 -> chave ausente, mal embalada, inexistente ou REVOGADA. A mensagem diz qual dos casos:
#        "Missing API key" (nao mandou nada), "API key not recognized" (mandou a chave crua no
#        Authorization, sem o "Bearer "), "API key not found" ou "This API key was revoked".
#   { "error": "invalid_api_key", "message": "API key not found: check the key and the environment it was created in." }

# 400 -> campo faltando ou malformado. E o erro mais comum do primeiro dia. A mensagem lista os
#        campos, os valores aceitos e os limites; ela NUNCA repete o valor que voce mandou.
#   { "error": "validation_error", "message": "\"flow_id\" any.required" }
#        Caso especial que vale conhecer: POST sem o header Content-Type: application/json nao chega
#        a ter corpo nenhum, e a resposta diz isso na primeira frase.

# 400 / 413 -> o corpo nem chegou a ser lido: JSON que nao se le (aspas faltando, byte de controle
#        cru, texto fora de UTF-8) ou corpo acima do teto. Valem em toda rota da chave secreta com corpo.
#   { "error": "invalid_json",      "message": "Invalid JSON body" }
#   { "error": "payload_too_large", "message": "Request body too large" }

# 403 -> a organizacao esta suspensa: TODA chamada sk_ para de funcionar de uma vez.
#   { "error": "organization_suspended", "message": "Organization suspended: every API call is blocked until it is reactivated. Sign in to the dashboard to see the reason, or contact support." }

# 403 -> a conta esta em revisao: novas operacoes de producao ficam paradas ate o fim da revisao.
#        Leitura e sandbox seguem.
#   { "error": "account_under_review", "message": "Account under review: new production operations are refused until the review ends. Reads and sandbox keep working." }

# 403 -> o prefixo da chave e o registro dela discordam de ambiente (chave guardada na variavel
#        errada do deploy e o caso classico).
#   { "error": "test_key_used_in_production", "message": "API key prefix says production but the key belongs to sandbox: use the key of the environment you want to call." }

# 403 -> a conta ainda nao confirmou o e-mail. E o tropeco mais comum do primeiro dia:
#        a chave e valida, o flow existe, e mesmo assim nenhuma sessao e criada.
#   { "error": "email_not_verified", "message": "Confirm your email address before using this resource" }

# 403 -> voce mandou a credencial do PAINEL (dsk_) nesta rota. Aqui so entra sk_.
#   { "error": "credential_type_not_allowed", "message": "This route does not accept dashboard credentials" }

# 404 -> flow_id inexistente NESTE ambiente. Chave de teste nao enxerga flow de producao,
#        e vice-versa: o mesmo id nao existe dos dois lados. E o erro do curl acima.
#   { "error": "flow_not_found", "message": "Flow not found in sandbox: check the flow id, and remember the environment is the API key you used (a flow lives in one environment only, and the same id does not exist on the other side)." }

# 422 -> o flow existe, mas nao esta live
#   { "error": "flow_not_live", "message": "Flow is not live" }

# 422 -> o flow tem um modulo sem o modulo de que ele precisa para decidir (por exemplo face sem
#        documento, cpf_ocr ou doc_global). Edite os modulos do flow; repetir nao muda nada.
#   { "error": "module_dependency_violation", "message": "flow flow_...: module face needs a document module in the same flow (cpf_ocr or doc_global) and cannot reach a decision without it; edit the flow modules before creating sessions" }

# 422 -> voce mandou "email" (ou "phone") no corpo. Contato do titular nao entra na criacao:
#        quem pergunta a pessoa e dispara o codigo e o widget. Recusado na entrada, custo zero.
#   { "error": "email_not_accepted", "message": "Email is always collected from the end user in the widget: remove email from the request." }
#   { "error": "phone_not_accepted", "message": "Phone is always collected from the end user in the widget: remove phone from the request." }

# 422 -> voce mandou "phone". Ele nao entra aqui: o telefone e sempre digitado pelo titular
#        no widget. Recusamos com nome em vez de ignorar, senao voce acharia que travou o
#        destino do SMS quando nao travou.
#   { "error": "phone_not_accepted", "message": "Phone is always collected from the end user in the widget: remove phone from the request." }

# 422 -> o reference_id nao e um id do seu sistema. Fora do conjunto (letras, digitos e . _ : @ -, sem
#        espaco nem caractere invisivel) e reference_id_charset; com forma de dado pessoal (CPF, CNPJ,
#        telefone, e-mail) e pii_shaped_value. Use o id do usuario no seu sistema; um UUID serve.
#   { "error": "reference_id_charset", "message": "Field reference_id has characters outside [A-Za-z0-9._:@-] (1..255)." }
#   { "error": "pii_shaped_value", "message": "Field reference_id looks like personal data (CPF/CNPJ/e-mail/phone/Pix key). Send an opaque id." }

# 402 -> o saldo nao cobre o maximo que a verificacao pode custar. A mensagem diz quanto falta.
#        Recarregue, ou ligue a recarga automatica no painel.
#   { "error": "insufficient_credit", "message": "Insufficient credit balance to start a production verification: balance is 0 cents and 68 more cents are needed to cover the maximum this verification can cost. Add credit in the dashboard (Cobranca), or use a sandbox key (sk_test_), which never charges." }

# 429 -> teto MENSAL de sandbox, ou teto de chamadas por minuto da conta.
#        Os dois sao 429 com codigos diferentes: nao trate 429 como um caso so.
#   { "error": "sandbox_limit_reached", "message": "Sandbox monthly limit reached." }
#   { "error": "rate_limited", "message": "Rate limit exceeded." }

# 409 / 422 -> idempotencia
#   { "error": "idempotency_conflict",  "message": "A request with this reference_id is already in progress." }
#   { "error": "idempotency_key_reuse", "message": "reference_id reused with a different request body." }

# 422 -> politica por sessao para um modulo que o flow NAO tem. Recusamos com nome em vez de
#        ignorar: politica aceita-e-ignorada faria voce acreditar que desligou algo que segue ligado.
#   { "error": "policy_module_not_in_flow", "message": "Flow has no pep_sanctions module; remove policy.allow_pep from the request." }

# 400 -> chave DESCONHECIDA dentro de "policy" ou de "monitoring". Os dois blocos sao whitelist
#        fechada: recusamos com nome em vez de descartar o campo em silencio, porque um 201 com a
#        chave engolida faria voce acreditar que a politica valeu. O nome da chave recusada vem na
#        "message". Valem os mesmos blocos tambem no link hospedado.
#   { "error": "unknown_policy_key",     "message": "\"policy.allowBettingBan\" object.unknown (unknown_policy_key)" }
#   { "error": "unknown_monitoring_key", "message": "\"monitoring.cancel\" object.unknown (unknown_monitoring_key)" }

# 400 -> o return_url e https e o host dele nao esta na lista de destinos de retorno do ambiente
#        (painel, Organizacao). Acrescente o host la; a lista de sandbox e a de producao sao separadas.
#   { "error": "return_url_not_allowed", "message": "return_url host is not on the allowlist of this environment: add it in the dashboard (Organization, return destinations)." }

# 422 -> o flow informado so recebe alertas do monitoramento transacional e nao aceita sessao de
#        verificacao. Mande os eventos com o bloco "transaction", ou crie a sessao no seu flow
#        de verificacao. Vale igual na emissao do link hospedado.
#   { "error": "session_not_supported", "message": "the flow's module transacao only receives alerts from transaction monitoring and does not accept a verification session." }

# 422 -> "policy.ubo_max_paid_nodes" acima do teto do proprio flow. O teto da sessao so APERTA o do
#        flow (gasto so sobe por decisao registrada no flow, nunca por um campo de request).
#   { "error": "policy_ubo_cap_above_flow", "message": "policy.ubo_max_paid_nodes (8) exceeds the flow limit (3); the session policy can only lower it." }

# 422 -> "policy.allow_pep" true num flow que recusa PEP, sem a permissao do flow para afrouxar pela sessao.
#   { "error": "pep_override_not_enabled", "message": "Flow does not allow loosening allow_pep per session; enable allow_pep_override_enabled on the flow (owner or admin)." }

# 422 -> o "reference_id" esta na lista de bloqueio da conta (do flow ou da conta inteira). O titular nao
#        passa pela captura; trate a pessoa como barrada no seu sistema.
#   { "error": "reference_blocklisted", "message": "reference_id is on the blocklist of this organization for this flow." }

# Nenhum destes cria sessao e nenhum e cobrado. Repetir a chamada so resolve 429 (espere) e 402
# (recarregue). Nos outros, a correcao e de configuracao: repetir devolve o mesmo erro.