# Faroway

> API REST para score de compliance judicial por CPF e CNPJ no Brasil.

Use esta documentação para construir integrações com a API da Faroway:

- Visão geral: https://www.faroway.tech/docs
- Autenticação: https://www.faroway.tech/docs/autenticacao
- Consultar score: https://www.faroway.tech/docs/consultar-score-cpf-cnpj
- Webhooks: https://www.faroway.tech/docs/webhooks
- Códigos de resposta: https://www.faroway.tech/docs/codigos-de-resposta
- Exemplos: https://www.faroway.tech/docs/exemplos
- Contexto completo para LLMs: https://www.faroway.tech/llms-full.txt

## Integration Summary

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

Authentication: send `Authorization: Bearer FAROWAY_API_KEY` on every request.

Supported endpoints:

- `POST /webhooks`: register or update the webhook URL for the current API key environment.
- `POST /score`: submit an asynchronous CPF or CNPJ score request.

Workflow:

1. Register a webhook.
2. Submit `POST /score` with `document`, `document_type`, and optional `external_id`.
3. Treat `202 Accepted` as receipt only.
4. Persist `request_id`.
5. Receive final result through `score.completed` or `score.failed` webhook events.

Important constraints:

- Do not expose API keys in browser or mobile client code.
- Do not invent polling or result endpoints.
- Do not treat `POST /score` as a synchronous score result.
- Use `request_id` for webhook idempotency.
- Return HTTP 200 quickly from webhook handlers.