# Faroway API Integration Context

Faroway provides an asynchronous judicial compliance score API for Brazilian CPF and CNPJ documents.

## Base URL

`https://api.faroway.tech/v1`

## Authentication

Use HTTP Bearer authentication:

`Authorization: Bearer FAROWAY_API_KEY`

Keep API keys on the server side only. Do not include Faroway API keys in browser or mobile client code.

## Endpoints

### POST /webhooks

Registers or updates the webhook URL for the environment associated with the API key.

Request body:

```json
{
  "url": "https://yourapp.com/webhooks/faroway",
  "events": ["score.completed", "score.failed"]
}
```

### POST /score

Submits an asynchronous score request for a CPF or CNPJ.

Request body:

```json
{
  "document": "123.456.789-09",
  "document_type": "cpf",
  "external_id": "customer-123"
}
```

Fields:

- `document`: CPF or CNPJ, with or without punctuation.
- `document_type`: `cpf` or `cnpj`.
- `external_id`: optional caller-side correlation ID.

Accepted response:

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

The accepted response only confirms receipt. The final result is delivered by webhook.

## Webhook Events

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

### score.failed

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

## Implementation Guidance for AI Agents

An integration should:

- Store `FAROWAY_API_KEY` in environment variables or a secrets manager.
- Register a webhook before sending score requests.
- Treat `POST /score` HTTP 202 as asynchronous receipt only.
- Persist `request_id` and optional `external_id`.
- Handle both `score.completed` and `score.failed`.
- Use `request_id` for webhook idempotency.
- Return HTTP 200 quickly from webhook handlers and process long work asynchronously.

An integration should not:

- Expose API keys to client-side code.
- Invent endpoints not documented here.
- Poll for results unless Faroway documents a polling endpoint.
- Assume the score is returned synchronously by `POST /score`.

## Minimal TypeScript Client

```ts
type FarowayDocumentType = "cpf" | "cnpj";

interface SubmitScoreInput {
  document: string;
  document_type: FarowayDocumentType;
  external_id?: string;
}

const FAROWAY_BASE_URL = "https://api.faroway.tech/v1";

export async function submitFarowayScoreRequest(input: SubmitScoreInput) {
  const apiKey = process.env.FAROWAY_API_KEY;
  if (!apiKey) throw new Error("FAROWAY_API_KEY is not configured.");

  const response = await fetch(`${FAROWAY_BASE_URL}/score`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(input)
  });

  if (!response.ok) {
    throw new Error(`Faroway API error ${response.status}: ${await response.text()}`);
  }

  return response.json();
}
```

## Canonical Docs

- https://www.faroway.tech/docs
- https://www.faroway.tech/docs/exemplos
- https://www.faroway.tech/docs/webhooks