Endpoint

Consultar Score de CPF e CNPJ

Envie um documento e receba um score de risco judicial com detalhamento por tipo de processo. O resultado é entregue de forma assíncrona via webhook.

Endpoint#

POST/v1/score

Pré-requisito

É necessário ter um webhook registrado antes de enviar consultas. Sem webhook, a API retorna 428 Precondition Required.

Corpo da requisição#

Parâmetro	Tipo	Obrigatório	Descrição
`document`	string	sim	CPF (11 dígitos) ou CNPJ (14 dígitos). Aceita formatação com pontos e traços.
`document_type`	"cpf" \| "cnpj"	sim	Tipo de documento enviado.
`external_id`	string	não	Identificador externo para correlação no seu sistema. Máximo de 120 caracteres. Retornado no webhook.

Aliases aceitos

Para conveniência, a API também aceita documento como alias de document e tipo como alias de document_type.

Exemplo de requisição#

cURL

bash

curl -X POST https://api.faroway.tech/v1/score \
  -H "Authorization: Bearer sua_chave_de_api" \
  -H "Content-Type: application/json" \
  -d '{
  "document": "123.456.789-09",
  "document_type": "cpf",
  "external_id": "customer-123"
}'

Resposta: 202 Accepted#

A consulta foi aceita e está sendo processada. O resultado será entregue no seu webhook.

json

{
  "request_id": "req_8f2b4a2d",
  "status": "processing",
  "received_at": "2026-03-07T12:00:00Z"
}

Campos da resposta

Campo	Tipo	Descrição
`request_id`	string	Identificador único da consulta. Formato: req_ seguido de 32 caracteres hexadecimais.
`status`	"processing"	Status inicial da consulta. Sempre processing no 202.
`received_at`	string (ISO 8601)	Timestamp de quando a consulta foi recebida.

Resultado via webhook#

Quando a análise é concluída, a Faroway envia um POST para o webhook registrado com o evento score.completed ou score.failed.

score.completed#

Payload do webhook

json

{
  "event": "score.completed",
  "request_id": "req_8f2b4a2d",
  "external_id": "customer-123",
  "status": "completed",
  "result": {
    "document": "12345678909",
    "score": 93,
    "risk_level": "low",
    "cases": {
      "total": 1,
      "open": 0,
      "closed": 1
    },
    "case_breakdown": {
      "labor": 0,
      "civil": 1,
      "criminal": 0,
      "tax": 0
    },
    "completed_at": "2026-03-07T12:00:08Z"
  }
}

Campos do result

Campo	Tipo	Descrição
`document`	string	CPF ou CNPJ consultado (somente dígitos).
`score`	number	Score de compliance de 0 a 100. Quanto maior, menor o risco.
`risk_level`	"low" \| "medium" \| "high"	Classificação de risco. low: score ≥ 80, medium: score ≥ 50, high: score < 50.
`cases.total`	number	Total de processos judiciais encontrados.
`cases.open`	number	Processos em andamento.
`cases.closed`	number	Processos encerrados.
`case_breakdown.labor`	number	Processos trabalhistas.
`case_breakdown.civil`	number	Processos cíveis.
`case_breakdown.criminal`	number	Processos criminais.
`case_breakdown.tax`	number	Processos tributários.
`completed_at`	string (ISO 8601)	Timestamp de quando a análise foi concluída.

Níveis de risco#

risk_level	Faixa de score	Interpretação
low	80–100	Baixo risco judicial. Poucos ou nenhum processo relevante.
medium	50–79	Risco moderado. Alguns processos encontrados, recomendada análise complementar.
high	0–49	Alto risco judicial. Volume significativo de processos abertos.

score.failed#

Se a consulta não puder ser processada, o webhook recebe o evento score.failed com detalhes sobre o erro.

Payload do webhook (falha)

json

{
  "event": "score.failed",
  "request_id": "req_1ac93e44",
  "external_id": "customer-456",
  "status": "failed",
  "error": {
    "code": "mock_processing_error",
    "message": "The request could not be processed for this document."
  }
}

Erros de validação#

Se o corpo da requisição for inválido, a API retorna 400 Bad Request com uma mensagem descritiva. Exemplos:

Invalid document_type. Use cpf or cnpj.document_type não é cpf ou cnpj

Field document is required.document ausente ou vazio

Invalid CPF. Expected 11 digits.CPF com número errado de dígitos

Invalid CNPJ. Expected 14 digits.CNPJ com número errado de dígitos

Field external_id must be a string.external_id não é string

Veja a lista completa de status HTTP em códigos de resposta.