> ## Documentation Index > Fetch the complete documentation index at: https://docs.unifokal.com/llms.txt > Use this file to discover all available pages before exploring further. # Pede uma nova análise de crédito de um titular já verificado, com outro pedido e sem nova captura > Uma análise NOVA de um titular já verificado, com outro pedido (valor, prazo, taxa) e sem nova captura: as fontes de crédito do flow são consultadas de novo para esta análise e o motor decide pela sua política. A decisão anterior continua valendo até esta decidir. Com Prefer: wait=N (RFC 7240; N até 25 segundos) a resposta espera a decisão: pronta no prazo, 201 com ela; senão 202 com Location e Retry-After, e o webhook verification.completed chega como sempre. Sem o cabeçalho, 202 na hora. Idempotency-Key é OBRIGATÓRIA: repetir com a mesma chave devolve a primeira resposta (a análise criada, 202) e nunca abre uma segunda análise nem uma segunda cobrança; a mesma chave com outro corpo é 422 idempotency_key_reuse. Enquanto o titular tiver um pedido de revisão aberto da decisão vigente, a nova análise espera a resposta da revisão (409 credit_review_open). Uma análise em andamento por verificação (409 credit_analysis_in_progress). Limite: 6 análises do mesmo titular em 30 dias (429), porque cada consulta nova pesa na nota do titular no birô; sem limite diário de volume da organização. Cobra como a primeira análise: cada fonte consultada ao preço dela (o dado reaproveitado dentro do prazo da família também) e o motor uma vez por análise. Exige uma chave secreta criada COM o escopo credit:analyses:write (chaves sem restrição não o têm) e com lista de IPs permitidos. ## OpenAPI ````yaml /api-reference/openapi.json post /credit-analyses openapi: 3.1.0 info: title: UNIFOKAL API version: v1 summary: >- Verificação de identidade: sessão criada no servidor, jornada no widget, resultado no webhook. description: >- A versão vive no caminho (/v1); não existe header de versão. Adição compatível (campo, módulo ou chave nova) NÃO sobe a versão: ignore o que não conhecer. Todo erro tem a forma { error, message }: o código é estável, a mensagem não. Ids são prefixo + ULID. Webhooks são assinados (HMAC SHA-256 no header X-IDSAAS-Signature, janela de 300s; o segredo é SEU, mínimo 32 caracteres) e o header x-idsaas-event carrega o tipo do evento. termsOfService: https://unifokal.com/termos contact: name: UNIFOKAL url: https://docs.unifokal.com/ servers: - url: https://api.unifokal.com/v1 security: [] externalDocs: description: >- Documentação completa em https://docs.unifokal.com/. Briefing para agentes de IA em https://unifokal.com/llms.txt. url: https://docs.unifokal.com/ paths: /credit-analyses: post: summary: >- Pede uma nova análise de crédito de um titular já verificado, com outro pedido e sem nova captura description: >- Uma análise NOVA de um titular já verificado, com outro pedido (valor, prazo, taxa) e sem nova captura: as fontes de crédito do flow são consultadas de novo para esta análise e o motor decide pela sua política. A decisão anterior continua valendo até esta decidir. Com Prefer: wait=N (RFC 7240; N até 25 segundos) a resposta espera a decisão: pronta no prazo, 201 com ela; senão 202 com Location e Retry-After, e o webhook verification.completed chega como sempre. Sem o cabeçalho, 202 na hora. Idempotency-Key é OBRIGATÓRIA: repetir com a mesma chave devolve a primeira resposta (a análise criada, 202) e nunca abre uma segunda análise nem uma segunda cobrança; a mesma chave com outro corpo é 422 idempotency_key_reuse. Enquanto o titular tiver um pedido de revisão aberto da decisão vigente, a nova análise espera a resposta da revisão (409 credit_review_open). Uma análise em andamento por verificação (409 credit_analysis_in_progress). Limite: 6 análises do mesmo titular em 30 dias (429), porque cada consulta nova pesa na nota do titular no birô; sem limite diário de volume da organização. Cobra como a primeira análise: cada fonte consultada ao preço dela (o dado reaproveitado dentro do prazo da família também) e o motor uma vez por análise. Exige uma chave secreta criada COM o escopo credit:analyses:write (chaves sem restrição não o têm) e com lista de IPs permitidos. operationId: createCreditAnalysis parameters: - name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 255 - name: Prefer in: header required: false schema: type: string example: wait=10 description: 'wait=N: quanto você aceita esperar pela decisão, em segundos.' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCreditAnalysisRequest' responses: '201': description: >- A análise terminou dentro do prazo do Prefer: wait (decided, failed ou canceled). headers: Location: schema: type: string description: 'O caminho da análise: /v1/credit-analyses/{id}.' Preference-Applied: schema: type: string description: wait=N, o prazo honrado. content: application/json: schema: $ref: '#/components/schemas/CreditAnalysis' '202': description: 'A análise está em andamento: leia em Location (ou espere o webhook).' headers: Location: schema: type: string description: 'O caminho da análise: /v1/credit-analyses/{id}.' Retry-After: schema: type: integer description: Em quantos segundos olhar de novo (5). content: application/json: schema: $ref: '#/components/schemas/CreditAnalysis' '400': description: >- Códigos estáveis: invalid_json, validation_error, idempotency_key_required. Ramifique pelo campo error, nunca pela mensagem. content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorEnvelope' - properties: error: enum: - invalid_json - validation_error - idempotency_key_required '401': description: >- Códigos estáveis: invalid_api_key. Ramifique pelo campo error, nunca pela mensagem. content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorEnvelope' - properties: error: enum: - invalid_api_key '403': description: >- Códigos estáveis: credential_type_not_allowed, organization_suspended, test_key_used_in_production, insufficient_scope, ip_not_allowed, credit_analyses_requires_ip_allowlist, credit_inquirer_unverified. Ramifique pelo campo error, nunca pela mensagem. content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorEnvelope' - properties: error: enum: - credential_type_not_allowed - organization_suspended - test_key_used_in_production - insufficient_scope - ip_not_allowed - credit_analyses_requires_ip_allowlist - credit_inquirer_unverified '404': description: >- Códigos estáveis: verification_not_found. Ramifique pelo campo error, nunca pela mensagem. content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorEnvelope' - properties: error: enum: - verification_not_found '409': description: >- Códigos estáveis: verification_erased, verification_not_approved, credit_analysis_in_progress, credit_review_open, idempotency_conflict. Ramifique pelo campo error, nunca pela mensagem. content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorEnvelope' - properties: error: enum: - verification_erased - verification_not_approved - credit_analysis_in_progress - credit_review_open - idempotency_conflict '413': description: >- Códigos estáveis: payload_too_large. Ramifique pelo campo error, nunca pela mensagem. content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorEnvelope' - properties: error: enum: - payload_too_large '422': description: >- Códigos estáveis: credit_decision_not_in_flow, credit_purpose_required, credit_document_missing, credit_request_invalid, idempotency_key_reuse. Ramifique pelo campo error, nunca pela mensagem. content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorEnvelope' - properties: error: enum: - credit_decision_not_in_flow - credit_purpose_required - credit_document_missing - credit_request_invalid - idempotency_key_reuse '429': description: >- Códigos estáveis: rate_limited, credit_reanalysis_subject_limit. Ramifique pelo campo error, nunca pela mensagem. content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorEnvelope' - properties: error: enum: - rate_limited - credit_reanalysis_subject_limit security: - secretKey: [] components: schemas: CreateCreditAnalysisRequest: type: object properties: verification_id: type: string pattern: ^ver_[0-9A-HJKMNP-TV-Z]{26}$ credit_relationship: type: string enum: - existing - prospective credit_request: type: object properties: product: type: string enum: - installment_loan - revolving - bnpl - rental - payroll_loan - refinancing - other amount_cents: type: integer minimum: 1 maximum: 100000000000 term_months: type: integer minimum: 1 maximum: 480 monthly_rate_bps: type: integer minimum: 0 maximum: 100000 amortization: type: string enum: - price - sac replaced_installments_cents: type: integer minimum: 0 maximum: 10000000000000 payroll_regime: type: string enum: - clt - inss - bpc declared_income_cents: type: integer minimum: 0 maximum: 10000000000000 declared_income_basis: type: string enum: - gross - net declared_revenue_cents: type: integer minimum: 0 maximum: 10000000000000 required: - product - amount_cents - term_months required: - verification_id - credit_relationship - credit_request description: >- A verificação aprovada do titular (do mesmo ambiente da chave, com o motor credit_decision no flow), a relação declarada com ele agora (Lei 12.414, art. 15) e o pedido novo, no mesmo formato do credit_request da criação de sessão. CreditAnalysis: type: object required: - id - object - verification_id - status - credit_decision - previous_analysis_id - end_reason - missing_authorizations - created_at - ended_at properties: id: type: string pattern: ^can_[0-9A-HJKMNP-TV-Z]{26}$ object: type: string enum: - credit_analysis verification_id: type: string pattern: ^ver_[0-9A-HJKMNP-TV-Z]{26}$ status: type: string enum: - running - decided - failed - canceled description: >- running: as fontes estão sendo consultadas; decided: credit_decision traz a decisão; failed: o motor não decidiu (nada cobrado, peça de novo); canceled: a identidade saiu de approved (negada ou bloqueada) antes da decisão. credit_decision: oneOf: - $ref: '#/components/schemas/CreditDecisionData' - type: 'null' description: >- A decisão, a mesma do bloco data do check credit_decision no webhook. null até decided. previous_analysis_id: type: - string - 'null' pattern: ^cda_[0-9A-HJKMNP-TV-Z]{26}$ description: >- A decisão viva quando a análise começou: ela continua valendo até esta decidir, e então é substituída. end_reason: type: - string - 'null' description: >- Por que terminou sem decisão: credit_engine_failed (o motor não decidiu), superseded_by_identity (a identidade saiu de approved), credit_requester_unverified ou credit_declaration_missing (o portão de crédito fechou) e credit_review_open (o titular pediu a revisão da decisão vigente). Em todos, a decisão anterior continua valendo. missing_authorizations: type: array description: >- As fontes não consultadas porque falta, foi revogada ou venceu a autorização do titular (a análise decide sem elas). items: type: object required: - module - reason properties: module: type: string reason: type: string enum: - credit_history_authorization_missing - credit_history_authorization_revoked - credit_history_authorization_expired created_at: type: string format: date-time ended_at: type: - string - 'null' format: date-time ErrorEnvelope: type: object description: >- Todo erro da API tem exatamente esta forma. O campo error é um código estável (contrato); message é texto livre e pode mudar sem aviso. required: - error - message properties: error: type: string description: Código estável do erro. Ramifique por ele. message: type: string description: Texto explicativo. NÃO é contrato. additionalProperties: false CreditDecisionData: type: object description: >- Bloco data do check credit_decision (análise de crédito), presente só com o check approved e todas as fontes do flow terminais; enquanto uma fonte responde, o check sai pending sem a chave data. A decisão de crédito é do campo decision, nunca do outcome do check (o módulo não reprova a identidade). Traz dois números de risco, cada um com o seu dono: o do birô (bureau_score e bureau_scores), rotulado como dele e nunca alterado, e o Score UNIFOKAL (house_score), de 0 a 1000, calculado por método publicado e versionado, que tem entre os seus fatos a probabilidade de atraso publicada pelo gestor (nunca a nota do birô), ordena o risco e não é probabilidade de inadimplência. Não traz o rastro da avaliação, os limiares e pesos das regras da política nem nome de fornecedor; do plano de fontes voltam o teto de custo, o orçamento de tempo e o critério de escolha entre birôs, que são da sua política. Campo novo pode surgir sem subir schema_version: ignore chave desconhecida. required: - analysis_id - decision - reasons - limit_cents - installment_max_cents - capacity - sources - policy_version - engine_version - explanation properties: analysis_id: type: - string - 'null' description: Identificador da análise (cda_), estável entre reentregas. decision: type: - string - 'null' enum: - approved - review - declined - null description: >- approved = a política aprovou; review = a política pede revisão sua; declined = a política recusou. reasons: type: array description: >- Os motivos da decisão, ordenados por etapa e gravidade. Vazio quando nenhum motivo se aplicou. items: type: object required: - code - text properties: code: type: - string - 'null' enum: - ineligible_age - minor_requires_emancipation_proof - registration_void - registration_irregular - identity_data_unverified - company_inactive - company_void - sanctions_listed - politically_exposed_review - bank_debt_overdue_90 - bank_debt_written_off - bankruptcy_or_reorganization - negative_record_active - protest_active - bank_debt_overdue_recent - bounced_check - income_unverified - public_debt_active - cadin_record_active - source_unavailable - source_blocked - source_declined - limit_not_computed - income_not_corroborated - income_document_inconsistent - income_document_reused - income_document_missing - group_public_debt - uploaded_report_inconsistent - certificate_positive - client_relationship_overdue - positive_record_late_payments - bureau_score_below_cutoff - bureau_score_unavailable - bureau_pd_above_cutoff - bureau_sources_disagree - scorecard_below_cutoff - matrix_outcome - client_model_below_cutoff - client_model_unavailable - house_score_below_cutoff - house_score_unavailable - employer_inactive - bureau_file_not_found - lawsuit_as_defendant - inquiries_recent_high - stopped_check - bureau_recommendation_negative - residual_income_below_minimum - capacity_insufficient - limit_above_policy - bureau_suggested_limit_below_request - term_above_policy - debt_service_high - null description: Código do catálogo fechado de motivos. text: type: - string - 'null' description: >- O motivo em português claro, para o titular. Sem limiar, sem peso. limit_cents: type: - integer - 'null' description: >- Valor sugerido que cabe na capacidade, em centavos. null quando a política não tem capacidade ou o pedido não trouxe a taxa. installment_max_cents: type: - integer - 'null' description: >- Parcela máxima que cabe na capacidade, em centavos. null quando não calculada. capacity: type: - object - 'null' required: - income_basis_source - dsr_after_bps - residual_income_cents properties: income_basis_source: type: - string - 'null' enum: - declared - presumed - documented - null description: >- declared = a renda declarada no credit_request; presumed = a renda presumida pelo birô; documented = a renda do documento do titular conferida na fonte oficial (nível A). dsr_after_bps: type: - integer - 'null' description: Comprometimento da renda com a nova parcela, em pontos-base. residual_income_cents: type: - integer - 'null' description: Renda livre depois da nova parcela, em centavos. sources: type: array description: >- As fontes de crédito do flow que a análise leu, uma entrada por família de informação de uma fonte que respondeu e uma entrada por fonte que não respondeu. state, consulted e price_cents são da FONTE: repetem-se em cada entrada do mesmo module (some por module, nunca por entrada). items: type: object required: - module - status - origin - base_date properties: module: type: - string - 'null' status: type: - string - 'null' enum: - delivered - not_found - unavailable - blocked - declined - skipped - null description: A situação desta família de informação. origin: type: - string - 'null' enum: - bureau - central_bank - notary - federal_debt - cadin - own_base - account_holder_upload - client_provided - court - state_tax - labor_court - public_registry - null base_date: type: - string - 'null' state: type: - string - 'null' enum: - delivered - not_found - unavailable - blocked - declined - skipped - null description: >- A situação da fonte: delivered (respondeu com dados), not_found (respondeu que não tem o documento), unavailable (não respondeu, ou respondeu sem dado que o motor consiga ler), blocked (não pôde ser consultada), declined (o titular não autorizou ou não enviou) ou skipped (o plano de fontes da sua política não a consultou, ver evaluation). null em decisão gravada antes do campo. consulted: type: - boolean - 'null' description: >- true quando a fonte foi de fato consultada nesta análise (respondeu ou foi perguntada e não respondeu). false quando nada foi pedido a ela nesta análise: a resposta é de uma análise anterior do mesmo titular (numa reanálise, os documentos do titular, as bases próprias e a sua base de clientes), é uma consulta que a sua organização já recebeu e foi reaproveitada dentro do prazo da família, ou o pedido nunca saiu. null em decisão gravada antes do campo. price_cents: type: - integer - 'null' description: >- O que esta análise gastou com a fonte pelo preço da sua tabela, a mesma conta de evaluation.spent_cents e do débito: o preço do módulo quando a fonte respondeu nesta análise, inclusive uma resposta que o motor não conseguiu ler (state unavailable) e uma consulta reaproveitada dentro do prazo da família; num documento do titular, o preço por documento vezes os documentos cobrados. 0 quando a fonte não respondeu, quando a resposta é de uma análise anterior, quando o fornecedor declarou o nada consta sem cobrança e quando nenhum documento foi cobrado. null quando o preço não se resolveu ou em decisão gravada antes do campo. A cobrança efetiva é a do extrato: o sandbox não cobra. bureau_score: type: - object - 'null' description: >- O score do birô que entrou na análise (Lei 12.414, art. 4, IV, a): o número do birô, rotulado como dele, nunca calculado pela UNIFOKAL. null quando nenhuma fonte do flow trouxe score. source_module diz qual fonte do flow trouxe; origin_name é o gestor do banco de dados quando conhecido. required: - source_module - score - scale_min - scale_max - pd_bps - band - origin_name - base_date properties: source_module: type: - string - 'null' description: O módulo do flow que trouxe o score. score: type: - integer - 'null' description: O score do birô, na escala dele. scale_min: type: - integer - 'null' description: Mínimo da escala, quando o birô informa. scale_max: type: - integer - 'null' description: Máximo da escala, quando o birô informa. pd_bps: type: - integer - 'null' description: >- Probabilidade de inadimplência do birô, em pontos-base, quando ele informa. band: type: - string - 'null' description: Faixa do birô, quando ele informa. origin_name: type: - string - 'null' description: >- O gestor do banco de dados (Lei 12.414, art. 2, II), nunca o intermediário. base_date: type: - string - 'null' description: Data-base da informação. bureau_scores: type: array description: >- Toda nota ou probabilidade de inadimplência que um birô entregou à análise, na ordem em que o motor lê os birôs (Lei 12.414, art. 4, IV, a). Cada uma é o número do birô, com o módulo, o modelo, o horizonte e o gestor; nunca um número da UNIFOKAL. bureau_score continua com a primeira nota entregue. Vazio quando nenhum birô entregou. items: type: object required: - source_module - score - pd_bps - pd_low_bps - pd_high_bps - horizon_months - band - model - origin_name - base_date properties: source_module: type: - string - 'null' description: O módulo do flow que trouxe a nota. score: type: - integer - 'null' description: >- A nota do birô, na escala dele; null quando ele entregou só a probabilidade. pd_bps: type: - integer - 'null' description: Probabilidade de inadimplência do birô, em pontos-base. pd_low_bps: type: - integer - 'null' description: >- Limite inferior, quando o birô entrega a probabilidade como faixa. pd_high_bps: type: - integer - 'null' description: >- Limite superior, quando o birô entrega a probabilidade como faixa. horizon_months: type: - integer - 'null' description: >- O horizonte em meses que o birô declara; null quando não declara. band: type: - string - 'null' description: Faixa do birô, quando ele informa. model: type: - string - 'null' description: O modelo do birô, quando ele informa. origin_name: type: - string - 'null' description: O gestor do banco de dados, nunca o intermediário. base_date: type: - string - 'null' bureau_pd: type: - object - 'null' description: >- De quem é cada probabilidade de inadimplência que a decisão leu: read é a que a sua política leu, classes a escolhida em cada horizonte. Cada linha nomeia UM birô (o número é dele, nunca uma média calculada pela UNIFOKAL). null quando nenhum birô entregou probabilidade. required: - read - classes properties: read: oneOf: - type: object required: - horizon_class - bps - rule - source_module - origin_name - base_date - sources_count - dispersion_bps properties: horizon_class: type: - string - 'null' enum: - 6m - 12m - unknown - null description: >- O horizonte que o birô declara para a probabilidade: 6m, 12m ou unknown (o birô não declarou). bps: type: - integer - 'null' description: >- A probabilidade exatamente como o birô escreveu, em pontos-base. rule: type: - string - 'null' enum: - max - min - median_upper - priority - null description: >- Como a sua política escolheu entre os birôs da classe: max (a maior), min (a menor), median_upper (a mediana superior) ou priority (a primeira na ordem da política). source_module: type: - string - 'null' description: O módulo do flow cujo número é este. origin_name: type: - string - 'null' description: O gestor do banco de dados, quando conhecido. base_date: type: - string - 'null' sources_count: type: - integer - 'null' description: Quantos birôs informaram probabilidade nesta classe. dispersion_bps: type: - integer - 'null' description: >- A distância entre a maior e a menor probabilidade da classe, em pontos-base. - type: 'null' classes: type: array items: type: object required: - horizon_class - bps - rule - source_module - origin_name - base_date - sources_count - dispersion_bps properties: horizon_class: type: - string - 'null' enum: - 6m - 12m - unknown - null description: >- O horizonte que o birô declara para a probabilidade: 6m, 12m ou unknown (o birô não declarou). bps: type: - integer - 'null' description: >- A probabilidade exatamente como o birô escreveu, em pontos-base. rule: type: - string - 'null' enum: - max - min - median_upper - priority - null description: >- Como a sua política escolheu entre os birôs da classe: max (a maior), min (a menor), median_upper (a mediana superior) ou priority (a primeira na ordem da política). source_module: type: - string - 'null' description: O módulo do flow cujo número é este. origin_name: type: - string - 'null' description: O gestor do banco de dados, quando conhecido. base_date: type: - string - 'null' sources_count: type: - integer - 'null' description: Quantos birôs informaram probabilidade nesta classe. dispersion_bps: type: - integer - 'null' description: >- A distância entre a maior e a menor probabilidade da classe, em pontos-base. evaluation: type: - object - 'null' description: >- Como rodou o plano de fontes da sua política: os estágios consultados, por que parou, o gasto com fontes contra o seu teto e as fontes que o plano não consultou. null quando a política não tem plano de fontes (toda fonte é consultada de uma vez) ou quando a análise foi fechada pela varredura de reserva. required: - stages_run - stop_reason - spent_cents - cost_cap_cents - latency_budget_ms - skipped properties: stages_run: type: - integer - 'null' description: Quantos estágios tiveram ao menos uma fonte consultada. stop_reason: type: - string - 'null' enum: - decided - cost_cap - latency_budget - plan_complete - null description: >- decided = a decisão ficou determinada antes das fontes restantes; cost_cap = o seu teto de custo; latency_budget = o seu orçamento de tempo; plan_complete = o plano rodou inteiro. spent_cents: type: - integer - 'null' description: >- O gasto desta análise com as fontes que responderam, pelo preço da sua tabela: a soma de price_cents por fonte. cost_cap_cents: type: - integer - 'null' description: O teto de custo por análise da sua política; null sem teto. latency_budget_ms: type: - integer - 'null' description: >- O orçamento de tempo da sua política, em milissegundos; null sem orçamento. skipped: type: array description: >- Cada fonte que o plano não consultou, com a causa. Nenhuma é cobrada. items: type: object required: - module - cause properties: module: type: - string - 'null' cause: type: - string - 'null' enum: - not_read - decided - variant_delivered - run_if - latency_budget - cost_cap_reached - null description: >- not_read = nenhuma regra da política lê a fonte; decided = a decisão já estava determinada; variant_delivered = outra variante da família já entregou; run_if = a condição do estágio não valeu; latency_budget = o orçamento de tempo; cost_cap_reached = o teto de custo. experiment: type: - object - 'null' description: >- O braço do experimento A/B da sua política que decidiu a análise. null fora de experimento. required: - id - arm properties: id: type: - string - 'null' description: O experimento. arm: type: - string - 'null' enum: - champion - challenger - challenger_1 - challenger_2 - challenger_3 - challenger_4 - null description: >- champion = a política vigente; challenger_1 a challenger_4 = as desafiantes de um teste com até cinco versões; challenger = a desafiante única de um teste anterior. bureau_recommendations: type: array description: >- A recomendação que cada birô entregou. Serve para explicação e revisão; nunca aprova, nunca recusa e nunca sobe limite (a avaliação do crédito é sua, CDC, art. 54-D, II). Vazio quando nenhum birô recomendou. items: type: object required: - source_module - level - origin_name - base_date properties: source_module: type: - string - 'null' level: type: - string - 'null' enum: - not_recommended - caution - recommended - null description: >- not_recommended = o birô não recomenda; caution = recomenda com cautela; recommended = recomenda. origin_name: type: - string - 'null' description: O gestor do banco de dados, quando conhecido. base_date: type: - string - 'null' house_score: description: >- O Score UNIFOKAL da análise (ver o schema HouseScore), com o cartão da política que decidiu. Sai em toda decisão, pontuada ou não (sem pontuação, value null e unscored_reason diz por quê). null em decisão gravada antes do campo. oneOf: - $ref: '#/components/schemas/HouseScore' - type: 'null' policy_version: type: - string - 'null' description: Versão (por conteúdo) da política que decidiu. engine_version: type: - string - 'null' description: Versão do motor que decidiu. explanation: type: - object - 'null' description: >- A explicação para o titular (LGPD, art. 20, par. 1; Lei 12.414, art. 5, IV): os motivos, as fontes usadas com a data-base e como contestar cada uma, e como pedir a revisão. Por categoria de critério, nunca a regra literal. required: - reasons - sources - review properties: reasons: type: array description: >- Os motivos principais, até quatro, do que mais pesou na decisão (recusa, depois revisão, depois corte do limite) e por etapa (referência: 12 CFR 1002.9(b)(2), comentário oficial 9(b)(2)-1). A lista completa fica em reasons, fora da explicação. Uma decisão gravada antes dessa regra mantém a explicação que tinha. items: type: object required: - code - text - contest properties: code: type: - string - 'null' enum: - ineligible_age - minor_requires_emancipation_proof - registration_void - registration_irregular - identity_data_unverified - company_inactive - company_void - sanctions_listed - politically_exposed_review - bank_debt_overdue_90 - bank_debt_written_off - bankruptcy_or_reorganization - negative_record_active - protest_active - bank_debt_overdue_recent - bounced_check - income_unverified - public_debt_active - cadin_record_active - source_unavailable - source_blocked - source_declined - limit_not_computed - income_not_corroborated - income_document_inconsistent - income_document_reused - income_document_missing - group_public_debt - uploaded_report_inconsistent - certificate_positive - client_relationship_overdue - positive_record_late_payments - bureau_score_below_cutoff - bureau_score_unavailable - bureau_pd_above_cutoff - bureau_sources_disagree - scorecard_below_cutoff - matrix_outcome - client_model_below_cutoff - client_model_unavailable - house_score_below_cutoff - house_score_unavailable - employer_inactive - bureau_file_not_found - lawsuit_as_defendant - inquiries_recent_high - stopped_check - bureau_recommendation_negative - residual_income_below_minimum - capacity_insufficient - limit_above_policy - bureau_suggested_limit_below_request - term_above_policy - debt_service_high - null text: type: - string - 'null' contest: type: array items: type: string adverse: type: - boolean - 'null' description: >- true quando o motivo recusou o pedido ou cortou o limite; false quando só mandou o caso para uma pessoa. null em decisão gravada antes do campo. elements: type: array description: >- Num motivo da tabela de pontos da sua política (abaixo do mínimo, prazo ou teto da faixa): até três categorias de informação que mais pesaram contra o titular, cada uma com como contestar o dado, nunca os pontos, o corte nem o peso (Lei 12.414, art. 5, IV). Em sanctions_listed: cada cadastro público de sanções que traz o nome do titular, com o órgão que o mantém. Num motivo da matriz de decisão da sua política (matrix_outcome, ou o prazo e o teto da célula): as duas categorias que a matriz combinou, nunca a célula nem o corte. items: type: object required: - text - contest properties: text: type: - string - 'null' contest: type: array items: type: string sources: type: array items: type: object required: - origin - origin_name - base_date - contest properties: origin: type: - string - 'null' enum: - bureau - central_bank - notary - federal_debt - cadin - own_base - account_holder_upload - client_provided - court - state_tax - labor_court - public_registry - null origin_name: type: - string - 'null' base_date: type: - string - 'null' contest: type: - string - 'null' free_access: type: - string - 'null' description: >- Quando um banco de dados de crédito respondeu à consulta (entregou dados ou disse que não tem cadastro do titular): o direito do titular de consultar de graça, no gestor, as informações e a nota de crédito (Lei 12.414, art. 5, II). null quando nenhum respondeu (fonte bloqueada, recusada, pulada ou fora do ar), ou em decisão gravada antes do campo. review: type: - string - 'null' description: Como o titular pede a revisão da decisão. decided_by: type: string enum: - engine - desk description: >- A origem da decisão contada ao titular: engine = a política, desk = uma pessoa da sua equipe. desk_reason: type: - string - 'null' description: >- O motivo da decisão da mesa, em texto claro; null quando a política decidiu. elements_considered: type: array items: type: string description: >- As categorias de informação de fontes que responderam à análise (inclusive com "sem cadastro") que alguma parte da sua política leu (regra, faixa, tabela de pontos, matriz ou capacidade), sem número, peso nem corte (Lei 12.414, art. 5, IV). Vazio em decisão gravada antes do campo. inquirer: type: - string - 'null' description: >- O consulente: o nome legal da sua organização, que consultou os dados e decidiu (Lei 12.414, art. 2, V, e art. 5, VI). creditor: type: - string - 'null' description: >- O agente financiador, quem concede o crédito (CDC, art. 54-D, III). Igual ao consulente por padrão. review_terms: type: - object - 'null' description: >- Como o titular pede a revisão ao consulente e em quanto tempo recebe a resposta (Decreto 9.936/2019, art. 19; LGPD, art. 20). properties: text: type: - string - 'null' channel: type: - object - 'null' description: >- O canal de atendimento ao titular que a sua organização cadastrou; null usa o canal de atendimento da empresa, descrito em text. properties: text: type: - string - 'null' url: type: - string - 'null' email: type: - string - 'null' phone: type: - string - 'null' deadline_business_days: type: - integer - 'null' description: O prazo legal da resposta, em dias úteis (sete). notice_text: type: - string - 'null' description: >- A comunicação ao titular pronta para entregar, em português: a decisão, os motivos principais, as informações consideradas, as fontes com o gestor e a data-base, o acesso gratuito, a contestação, a revisão com o canal e o prazo, o consulente e o agente financiador. null em decisão gravada antes do campo. decided_by: type: string enum: - engine - desk description: >- Quem decidiu: engine = a política, desk = uma pessoa da sua equipe na mesa de crédito. A decisão da mesa chega como nova revisão do mesmo check, com o mesmo analysis_id. desk_reason: type: - object - 'null' description: >- O motivo da decisão da mesa, do catálogo fechado. null quando a política decidiu. properties: code: type: - string - 'null' text: type: - string - 'null' HouseScore: type: object description: >- Score UNIFOKAL: a pontuação de risco de crédito da UNIFOKAL, um inteiro de 0 a 1000 calculado por tabela de pontos publicada e versionada sobre fatos de crédito do titular (de birô, só os com gestor nomeado; para empresa, também do cadastro do CNPJ e da dívida ativa da União). Quanto maior, menor o risco na ordem do método. Ordena o risco: não é probabilidade de inadimplência e não tem horizonte; a taxa de atraso por faixa é a da sua carteira, medida por você. Nunca entram a idade da pessoa (para empresa, a idade da empresa é característica da tabela), renda, emprego, SCR, histórico positivo, dado de outra pessoa nem dado da sua base. Sai em toda decisão, ao lado do número dos birôs, sem preço novo. O cartão (version) é o da política que decidiu quando ela lê o score, e o atual do tipo de titular quando não lê. Campo novo pode surgir sem subir schema_version: ignore chave desconhecida. required: - value - band - version - method_hash - coverage_bps - factors - helped - unscored_reason properties: value: type: - integer - 'null' minimum: 0 maximum: 1000 description: >- A pontuação, de 0 a 1000. null quando o critério mínimo para pontuar não foi atendido (unscored_reason diz qual). band: type: - string - 'null' enum: - high_risk - moderate_risk - low_risk - very_low_risk - null description: >- A faixa ordinal da pontuação: high_risk = risco alto (0 a 300); moderate_risk = risco moderado (301 a 500); low_risk = risco baixo (501 a 700); very_low_risk = risco muito baixo (701 a 1000). null sem pontuação. Nenhuma faixa é um percentual de atraso. version: type: string pattern: ^house-(pf|pj)-v[0-9]{1,3}$ description: >- O cartão do método (house-pf-v1 para pessoa, house-pj-v1 para empresa). Mudar um ponto é cartão novo, nunca edição; todo cartão publicado continua valendo para a política que o prende. method_hash: type: string pattern: ^hscard_[0-9a-f]{64}$ description: >- hscard_ seguido do sha256 do cartão: o endereço por conteúdo do método que deu o número, o mesmo publicado na doc. coverage_bps: type: - integer - 'null' minimum: 0 maximum: 10000 description: >- A soma dos pesos das características com o fato entregue sobre 1000, em pontos-base (10000 = toda característica observada). null sem pontuação. factors: type: array maxItems: 4 description: >- Até quatro características que mais tiraram pontos, da maior perda para a menor (perda = pontos máximos da característica menos os obtidos; a falta do fato conta como perda), empate pela ordem da tabela. Vazio sem pontuação ou quando nada tirou pontos. items: type: object required: - code - text - points_lost - missing properties: code: type: - string - 'null' pattern: ^[PJ][1-9][0-9]?$ description: >- O código da característica na tabela publicada (P1 a P9 para pessoa, J1 a J9 para empresa). text: type: - string - 'null' description: >- A característica e o atributo lido, em português (ex.: "Pendências financeiras ativas: 2 a 3"). points_lost: type: - integer - 'null' minimum: 0 maximum: 1000 description: Os pontos que a característica tirou da pontuação. missing: type: - boolean - 'null' description: >- true quando a fonte não entregou o fato e valeram os pontos de falta da tabela. helped: type: array maxItems: 2 description: >- Até duas características no melhor atributo, observadas, das de maior peso. Vazio sem pontuação. items: type: object required: - code - text properties: code: type: - string - 'null' pattern: ^[PJ][1-9][0-9]?$ text: type: - string - 'null' unscored_reason: type: - string - 'null' enum: - registration_void - registry_unavailable - no_bureau - thin_file - null description: >- Por que não houve pontuação, o primeiro critério mínimo que falhou: registration_void = o cadastro do titular está cancelado, nulo ou indica óbito; registry_unavailable = a base de CNPJ não respondeu (empresa); no_bureau = nenhum birô com gestor nomeado respondeu sobre pendências (para empresa, nem sobre protestos); thin_file = os birôs responderam e não têm arquivo do titular (pessoa). null quando há pontuação. securitySchemes: secretKey: type: http scheme: bearer description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.