Documentação

API de Compliance Faroway

Consulte processos judiciais por CPF e CNPJ via uma API REST simples. Envie o documento, receba um score de risco de 0 a 100 com detalhamento por tipo de processo, tudo via webhook.

Autenticação

Chaves de API e Bearer Token

Consultar Score

POST /v1/score

Webhooks

Receba resultados em tempo real

Códigos de Resposta

Status HTTP e erros

Exemplos

cURL, Node.js, Python e mais

Como funciona

Registre um webhook

Configure a URL que receberá os resultados com um POST /v1/webhooks. Você escolhe quais eventos receber: score.completed e/ou score.failed.

Envie uma consulta de score

Faça um POST /v1/score com o CPF ou CNPJ. A API responde com 202 Accepted e um request_id para rastreio.

Receba o resultado via webhook

Quando o processamento termina, a Faroway envia um POST para o seu webhook com o score, nível de risco, total de processos e detalhamento por categoria (trabalhista, cível, criminal e tributário).

Exemplo rápido

Envie uma consulta e receba o resultado no seu webhook:

Enviar consulta

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

json

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

Webhook recebido: score.completed

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"
  }
}

URL base

https://api.faroway.tech/v1

Ambientes

Cada chave de API está vinculada a um ambiente: dev ou prod. Webhooks e consultas são isolados por ambiente. Use o ambiente dev para testes sem impacto em dados de produção.

Contexto para agentes e geradores de código

Se você usa um assistente de IA para gerar a integração, forneça este contexto junto com as páginas de autenticação, score, webhooks e exemplos. Ele resume as decisões que o modelo não deve inferir.

contexto-da-integracao.md

markdown

Faroway API integration context:
- Product: asynchronous judicial compliance score for Brazilian CPF and CNPJ.
- Base URL: https://api.faroway.tech/v1
- Auth: Authorization: Bearer FAROWAY_API_KEY
- Register webhook with POST /webhooks before sending real score requests.
- Submit scores with POST /score using document, document_type, and optional external_id.
- POST /score returns 202 Accepted with request_id only; final results arrive by webhook.
- Handle score.completed and score.failed.
- Persist request_id and external_id for correlation and idempotency.
- Do not expose API keys in browser/mobile code.
- Do not invent polling or synchronous result endpoints.

Contexto machine-readable

Agentes também podem ler /llms.txt e /llms-full.txt para encontrar a documentação e os contratos principais sem navegar pela interface.