> ## 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.

# Método do Score UNIFOKAL

> O método publicado do Score UNIFOKAL, de 0 a 1000: a tabela inteira de pontos de cada versão, as faixas, o critério mínimo para pontuar, o que nunca entra e por quê, como os fatores são escolhidos e como medir na sua carteira.

## Método do Score UNIFOKAL

O **Score UNIFOKAL** é um número inteiro de **0 a 1000** que **ordena** o risco de crédito do titular a partir de fatos de crédito, por uma tabela de pontos publicada e versionada. Quanto maior, menor o risco na ordem do método. **Não é probabilidade de inadimplência**: não tem horizonte e não foi ajustado a desfecho de ninguém. Ele sai em toda decisão do `credit_decision`, de pessoa e de empresa, no bloco `data.house_score`, ao lado do número de cada birô, que segue rotulado como do birô, e sem preço a mais. A sua política pode ler o score numa regra, numa tabela de faixas, num eixo da matriz de decisão ou na sua tabela de pontos.

```
// data.house_score no check credit_decision
"house_score": {
  "value": 640,                     // 0 a 1000; null quando o titular não pontua
  "band": "low_risk",               // high_risk, moderate_risk, low_risk ou very_low_risk
  "version": "house-pf-v1",         // a versão da tabela que deu o número
  "method_hash": "hscard_7e4e...",  // o endereço por conteúdo da tabela publicada
  "coverage_bps": 10000,            // peso das características observadas, sobre 1000, em pontos-base
  "factors": [ { "code": "P1", "text": "Pendências financeiras ativas: 1", "points_lost": 125, "missing": false },
               { "code": "P2", "text": "Tempo desde a pendência mais recente: menos de 180 dias", "points_lost": 100, "missing": false },
               { "code": "P9", "text": "Probabilidade de atraso publicada pelo gestor: em 12 meses, de 5% a 9,99%", "points_lost": 100, "missing": false },
               { "code": "P3", "text": "Valor das pendências ativas: até R$ 999,99", "points_lost": 35, "missing": false } ],
  "helped": [ { "code": "P7", "text": "Busca recente de crédito (consultas de terceiros em 90 dias): 0 a 1" },
              { "code": "P4", "text": "Protestos ativos: 0" } ],
  "unscored_reason": null }         // por que não pontuou, quando value é null
```

### A tabela de pontos

O score é a soma dos pontos de cada característica. Em cada uma vale o atributo em que o fato do titular cai; quando a fonte não entregou o fato, valem os pontos de **falta**, entre o mínimo e o máximo da característica, e a cobertura mostra isso. A soma dos máximos de cada tabela é 1000 e a dos mínimos é 0. Os pontos de cada atributo são julgamento de especialista sobre a importância relativa que os gestores de score de mercado publicam para cada categoria (pagamento, valor devido, tempo e busca recente de crédito): você mede na sua carteira o quanto o score ordena. Só entram informações de gestores nomeados; a probabilidade de atraso lida é a maior entre eles, na classe de 12 meses e, sem ela, na de 6 meses, nunca as duas misturadas.

**Pessoa física, `house-pf-v1`** (versão atual), hash `hscard_7e4e4bf5adff9407229a2cf587cefde8d074a8b7d758315527484f838d631ca3`

| Código | Característica | Atributos e pontos | Falta | Peso |
| - | - | - | - | - |
| `P1` | Pendências financeiras ativas | 0: 260; 1: 135; 2 a 3: 55; 4 ou mais: 0 | 130 | 260 |
| `P2` | Tempo desde a pendência mais recente. Lida só com P1 de 1 ou mais; sem isso vale o melhor atributo. | sem pendência: 100; 730 dias ou mais: 90; 365 a 729 dias: 60; 180 a 364 dias: 30; menos de 180 dias: 0 | 45 | 100 |
| `P3` | Valor das pendências ativas | R$ 0,00: 120; até R$ 999,99: 85; R$ 1.000,00 a R$ 9.999,99: 40; R\$ 10.000,00 ou mais: 0 | 60 | 120 |
| `P4` | Protestos ativos | 0: 100; 1: 40; 2 ou mais: 0 | 50 | 100 |
| `P5` | Ações de cobrança ou execução como réu | 0: 60; 1: 20; 2 ou mais: 0 | 30 | 60 |
| `P6` | Cheques sem fundos | 0: 50; 1 ou mais: 0 | 25 | 50 |
| `P7` | Busca recente de crédito (consultas de terceiros em 90 dias) | 0 a 1: 110; 2 a 3: 80; 4 a 6: 35; 7 ou mais: 0 | 55 | 110 |
| `P9` | Probabilidade de atraso publicada pelo gestor | em 12 meses, menos de 2%: 200; em 12 meses, de 2% a 4,99%: 150; em 12 meses, de 5% a 9,99%: 100; em 12 meses, de 10% a 19,99%: 55; em 12 meses, de 20% a 39,99%: 20; em 12 meses, 40% ou mais: 0. em 6 meses, menos de 1%: 200; em 6 meses, de 1% a 2,54%: 150; em 6 meses, de 2,55% a 5,14%: 100; em 6 meses, de 5,15% a 10,54%: 55; em 6 meses, de 10,55% a 22,54%: 20; em 6 meses, 22,55% ou mais: 0 | 100 | 200 |

**Pessoa jurídica, `house-pj-v1`** (versão atual), hash `hscard_28820574efe13f9185db6ad757c5ed046de81761c43447174366b268e262b9ef`

| Código | Característica | Atributos e pontos | Falta | Peso |
| - | - | - | - | - |
| `J1` | Pendências financeiras ativas da empresa | 0: 180; 1: 90; 2 a 4: 35; 5 ou mais: 0 | 90 | 180 |
| `J2` | Tempo desde a pendência mais recente. Lida só com J1 de 1 ou mais; sem isso vale o melhor atributo. | sem pendência: 70; 730 dias ou mais: 60; 365 a 729 dias: 40; 180 a 364 dias: 20; menos de 180 dias: 0 | 30 | 70 |
| `J3` | Protestos ativos | 0: 120; 1: 60; 2 a 4: 20; 5 ou mais: 0 | 60 | 120 |
| `J4` | Ações de cobrança ou execução como ré | 0: 80; 1: 40; 2 a 4: 10; 5 ou mais: 0 | 40 | 80 |
| `J5` | Dívida ativa da União (principal) | R$ 0,00: 100; até R$ 9.999,99: 60; R$ 10.000,00 a R$ 99.999,99: 25; R\$ 100.000,00 ou mais: 0 | 50 | 100 |
| `J6` | Idade da empresa | 60 meses ou mais: 120; 24 a 59 meses: 80; 12 a 23 meses: 40; menos de 12 meses: 0 | 60 | 120 |
| `J7` | Busca recente de crédito | 0 a 2: 60; 3 a 5: 40; 6 a 10: 15; 11 ou mais: 0 | 30 | 60 |
| `J8` | Falência ou recuperação judicial | não: 100; sim: 0 | 50 | 100 |
| `J9` | Probabilidade de atraso publicada pelo gestor | em 12 meses, menos de 2%: 170; em 12 meses, de 2% a 4,99%: 128; em 12 meses, de 5% a 9,99%: 85; em 12 meses, de 10% a 19,99%: 47; em 12 meses, de 20% a 39,99%: 17; em 12 meses, 40% ou mais: 0. em 6 meses, menos de 1%: 170; em 6 meses, de 1% a 2,54%: 128; em 6 meses, de 2,55% a 5,14%: 85; em 6 meses, de 5,15% a 10,54%: 47; em 6 meses, de 10,55% a 22,54%: 17; em 6 meses, 22,55% ou mais: 0 | 85 | 170 |

O código P8 fica sem uso de propósito: a característica que ele teria saiu antes da publicação, e um código nunca é reaproveitado com outro significado.

### Exemplos

Fato que o exemplo não cita é fato que a fonte não entregou. Os números abaixo são os que o motor calcula.

| Tabela | Titular | Score | Cobertura |
| - | - | - | - |
| `house-pf-v1` | Sem pendência, protesto, ação, cheque nem consulta recente; probabilidade de atraso do gestor de 1,5% em 12 meses | 1000 | 100% |
| `house-pf-v1` | O mesmo arquivo limpo, sem probabilidade de atraso informada pelo gestor | 900 | 80% |
| `house-pf-v1` | Uma pendência de R\$ 300,00 vencida há 100 dias; probabilidade de atraso de 8% em 12 meses | 640 | 100% |
| `house-pf-v1` | Cinco pendências que somam R\$ 15.000,00, a mais nova de 40 dias, 2 protestos, 3 consultas; probabilidade de atraso de 30% em 12 meses | 210 | 100% |
| `house-pj-v1` | Empresa de 7 anos sem pendência, protesto, ação, dívida ativa nem consulta recente; probabilidade de atraso de 1,5% em 12 meses | 1000 | 100% |
| `house-pj-v1` | Empresa de 18 meses com 1 protesto, R\$ 5.000,00 de dívida ativa da União e 4 consultas, sem probabilidade de atraso informada | 715 | 83% |

### As faixas

Os limites são os que o mercado brasileiro publica para a escala de 0 a 1000. O nome da faixa é só uma ordem: nenhuma faixa é um percentual de atraso. A taxa de atraso por faixa é a da sua carteira, que você mede.

| Faixa | Nome | Score |
| - | - | - |
| `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 |

### Quando o titular não pontua

Arquivo sem informação não recebe número. Os critérios são conferidos nesta ordem, e o primeiro que falha vai em `unscored_reason`, com `value`, `band` e `coverage_bps` em `null`. Uma fonte que o plano de fontes da sua política não consultou não impede o número: entra como falta, e a cobertura diz.

| Motivo | O que significa |
| - | - |
| `registration_void` | O cadastro do titular está cancelado, nulo ou indica óbito na base oficial. |
| `registry_unavailable` | A base de CNPJ não respondeu, então não se sabe se o cadastro da empresa vale. Só empresa. |
| `no_bureau` | Nenhum birô com gestor nomeado respondeu sobre pendências do titular (para empresa, nem sobre protestos). |
| `thin_file` | Os birôs responderam e não têm arquivo do titular. Só pessoa. |

### O que nunca entra, e por quê

| Fora do score | Por quê |
| - | - |
| SCR do Banco Central e histórico positivo | Servem a uma operação de crédito (Res. CMN 5.037/2022, art. 12). Um score gravado e medido entre operações seria outra finalidade. |
| O relacionamento da sua empresa com o titular e o seu modelo próprio | São dado seu, e o score é o mesmo método para todo cliente. Você usa os seus na sua política. |
| Idade | Lei 10.741/2003, art. 96. A idade só entra como capacidade civil. |
| Renda e capacidade de pagamento | A capacidade é bloco próprio da sua política (CDC, art. 54-D, II). Renda no score mediria poder aquisitivo. |
| Emprego | Estabilidade é capacidade, bloco da sua política. Os gestores de score de mercado também deixam emprego de fora. |
| Sócios e grupo econômico | Informação de outra pessoa (Lei 12.414/2011, art. 7-A, II). A sua política pode ler. |
| Setor, porte e capital da empresa | O setor é critério seu (Res. CMN 5.050/2022, art. 9, V). |
| A nota do birô na escala dele | Escalas de birôs diferentes não se comparam. A probabilidade de atraso é a medida comum. |
| Certidões e relatórios enviados pelo titular | Dependem de captura do flow e do nível de autenticidade do documento. |

### Os fatores

Em cada característica, a perda é o máximo dela menos os pontos que o titular recebeu (a falta conta como perda). Em `factors` vêm até quatro características com a maior perda acima de zero, empate pela ordem da tabela, cada uma com o atributo lido, os pontos perdidos e `missing` quando a fonte não entregou o fato. Em `helped` vêm até duas características no melhor atributo, as de maior peso. Ao titular, quando a sua política leu o score para recusar, revisar ou cortar o limite, a explicação nomeia as categorias de informação que mais pesaram e o canal de contestação de cada origem, nunca o número, o corte ou os pontos (LGPD, art. 20, par. 1).

### Versões

A tabela é código congelado pelo hash. Mudar um ponto é **versão nova** (`house-pf-v2`), nunca edição no lugar, e toda versão publicada continua calculável para sempre. A sua política fixa a versão que lê: uma versão nova nunca muda sozinha uma decisão sua. No editor de política, a ação **atualizar a tabela** grava a troca numa versão nova da política, que passa pela bancada de testes, pela sombra e pela promoção como qualquer outra mudança. O bloco `house_score` usa a tabela da política que decidiu e, quando ela não lê o score, a versão atual do tipo de titular.

* `house-pf-v1`, pessoa física, 8 características, hash `hscard_7e4e4bf5adff9407229a2cf587cefde8d074a8b7d758315527484f838d631ca3`
* `house-pj-v1`, pessoa jurídica, 9 características, hash `hscard_28820574efe13f9185db6ad757c5ed046de81761c43447174366b268e262b9ef`

### Como medir na sua carteira

O score é o mesmo método para todo cliente, e o quanto ele ordena muda de carteira para carteira. Envie o desfecho das operações que você liberou pelo `POST /v1/credit-outcomes` e compare, nas mesmas análises, o `house_score.value` com o desfecho: a área sob a curva ROC (AUC, com empate contado pela metade), o Gini (2 x AUC menos 1), o KS entre bons e maus e a taxa de maus por faixa. Abaixo de 50 maus a medida ainda não é confiável. Só operações liberadas têm desfecho. Compare a versão de tabela com ela mesma: os pontos de versões diferentes não se somam.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.