Exemplos
Exemplos de integração
Exemplos práticos para integrar a API da Faroway na sua aplicação. Todos os exemplos assumem que você já possui uma chave de API.
Fluxo completo#
A integração tem duas etapas: (1) registrar um webhook e (2) enviar consultas. O resultado é entregue no webhook. Os exemplos abaixo mostram ambas as etapas.
cURL#
1. Registrar webhook#
Registrar webhook
curl -X POST https://api.faroway.tech/v1/webhooks \
-H "Authorization: Bearer $FAROWAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://yourapp.com/webhooks/faroway",
"events": ["score.completed", "score.failed"]
}'2. Consultar score de CPF#
Consultar CPF
curl -X POST https://api.faroway.tech/v1/score \
-H "Authorization: Bearer $FAROWAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"document": "123.456.789-09",
"document_type": "cpf",
"external_id": "customer-123"
}'3. Consultar score de CNPJ#
Consultar CNPJ
curl -X POST https://api.faroway.tech/v1/score \
-H "Authorization: Bearer $FAROWAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"document": "12.345.678/0001-90",
"document_type": "cnpj",
"external_id": "supplier-456"
}'Node.js#
Enviar consulta com fetch#
score.ts
const FAROWAY_API_KEY = process.env.FAROWAY_API_KEY;
const BASE_URL = "https://api.faroway.tech/v1";
async function consultarScore(document: string, type: "cpf" | "cnpj") {
const response = await fetch(`${BASE_URL}/score`, {
method: "POST",
headers: {
"Authorization": `Bearer ${FAROWAY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
document,
document_type: type,
}),
});
if (!response.ok) {
const error = await response.json();
throw new Error(error.error ?? "Falha na consulta");
}
// 202 Accepted — resultado virá via webhook
return response.json();
}
// Exemplo de uso
const result = await consultarScore("123.456.789-09", "cpf");
console.log("Request ID:", result.request_id);
// => "req_8f2b4a2d..."
Receber webhook (Express)#
webhook-handler.ts
import express from "express";
const app = express();
app.use(express.json());
app.post("/webhooks/faroway", (req, res) => {
const { event, request_id, status } = req.body;
switch (event) {
case "score.completed": {
const { result } = req.body;
console.log(`Score para ${result.document}: ${result.score}`);
console.log(`Risco: ${result.risk_level}`);
console.log(`Processos: ${result.cases.total} (abertos: ${result.cases.open})`);
console.log(`Detalhamento:`, result.case_breakdown);
// Salve o resultado no seu banco de dados
break;
}
case "score.failed": {
const { error } = req.body;
console.error(`Consulta ${request_id} falhou: ${error.message}`);
// Trate o erro (notifique, reprocesse, etc.)
break;
}
default:
console.warn(`Evento desconhecido: ${event}`);
}
// Sempre retorne 200 para confirmar recebimento
res.status(200).json({ received: true });
});
app.listen(3000);Python#
Enviar consulta com requests#
score.py
import os
import requests
FAROWAY_API_KEY = os.environ["FAROWAY_API_KEY"]
BASE_URL = "https://api.faroway.tech/v1"
def consultar_score(document: str, document_type: str, external_id: str = None):
"""Envia consulta de score para a API da Faroway."""
payload = {
"document": document,
"document_type": document_type,
}
if external_id:
payload["external_id"] = external_id
response = requests.post(
f"{BASE_URL}/score",
headers={
"Authorization": f"Bearer {FAROWAY_API_KEY}",
"Content-Type": "application/json",
},
json=payload,
)
response.raise_for_status()
return response.json()
# Exemplo de uso
result = consultar_score("123.456.789-09", "cpf", "customer-123")
print(f"Request ID: {result['request_id']}")
# => "req_8f2b4a2d..."
Receber webhook (Flask)#
webhook_handler.py
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route("/webhooks/faroway", methods=["POST"])
def handle_webhook():
data = request.get_json()
event = data.get("event")
request_id = data.get("request_id")
if event == "score.completed":
result = data["result"]
print(f"Score para {result['document']}: {result['score']}")
print(f"Risco: {result['risk_level']}")
print(f"Processos: {result['cases']['total']}")
# Salve no banco de dados
elif event == "score.failed":
error = data["error"]
print(f"Consulta {request_id} falhou: {error['message']}")
# Trate o erro
return jsonify({"received": True}), 200
Registrar webhook (todos os exemplos)#
Antes de enviar consultas, registre o webhook uma vez. A API usa upsert — se já existir um webhook para o ambiente, ele é atualizado.
Node.js
const response = await fetch("https://api.faroway.tech/v1/webhooks", {
method: "POST",
headers: {
"Authorization": `Bearer ${FAROWAY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
url: "https://yourapp.com/webhooks/faroway",
events: ["score.completed", "score.failed"],
}),
});
const { webhook } = await response.json();
console.log("Webhook registrado:", webhook.id);Python
response = requests.post(
f"{BASE_URL}/webhooks",
headers={
"Authorization": f"Bearer {FAROWAY_API_KEY}",
"Content-Type": "application/json",
},
json={
"url": "https://yourapp.com/webhooks/faroway",
"events": ["score.completed", "score.failed"],
},
)
webhook = response.json()["webhook"]
print(f"Webhook registrado: {webhook['id']}")
Dicas de integração#
Use variáveis de ambiente
Nunca coloque a chave de API diretamente no código. Use variáveis de ambiente como FAROWAY_API_KEY.
Idempotência no webhook
Use o campo request_id para evitar processamento duplicado. Em cenários de rede instável, o mesmo evento pode ser entregue mais de uma vez.
Correlação com external_id
Use o campo external_id para vincular a consulta ao seu sistema (ID do cliente, ID do pedido, etc.). Ele é retornado no webhook para facilitar a correlação.
Timeout do webhook
A Faroway aguarda até 10 segundos por uma resposta do seu endpoint. Para processamentos longos, confirme o recebimento com 200 OK imediatamente e processe o payload em background.
Continue aprendendo