Exemplos prontos
Receitas completas para começar rápido. Todas usam:
- a URL base
https://api.trust.nearone.com.br; - uma chave de API da organização no cabeçalho
Authorization: Bearer sgk_live_…(veja Autenticação para criar a sua); - Node.js 18+ com
fetchnativo, ou Python 3.10+ comhttpx.
Leia a chave de uma variável de ambiente ou de um cofre de segredos. Nunca a publique em repositório, front-end ou aplicativo móvel: ela age em nome da organização, com as permissões que você deu a ela. Chamadas com chave feitas a partir de um navegador (com cabeçalho Origin) são recusadas: rode estes exemplos no servidor.
export NEARONE_API_KEY="sgk_live_..."
export NEARONE_WEBHOOK_SECRET="whsec_..."
O que você precisa saber da API
| Tema | Como funciona |
|---|---|
| Autenticação | Authorization: Bearer <chave> em toda requisição. |
| Listagens | Aceitam limit (1 a 100, padrão 50), cursor, sort (ex.: -created_at), q (busca, até 200 caracteres) e filter (JSON). Respondem {"items": [...], "page": {"limit", "total", "next_cursor"}}. |
| Próxima página | Repita a chamada com cursor=<page.next_cursor> até next_cursor vir null. |
| Filtros | filter é um JSON: {"phase": "in_progress"} (igualdade), {"created_at": {"gte": "2026-11-01T00:00:00Z"}}, {"status": {"in": ["failed", "exhausted"]}}, combinações com {"and": [...]} e {"or": [...]}. Operadores: eq, neq, contains, in, gt, gte, lt, lte, is_null, conforme o campo. |
| Erros | Corpo {"code", "message", "request_id"}: code é estável (em inglês) para o seu código decidir; message é em português para mostrar a pessoas. Erros de formato da entrada (tipo errado, campo obrigatório faltando) respondem 422 com {"detail": [...]}, cada item com loc, msg e type; esse corpo não traz request_id, então use o cabeçalho X-Request-ID. |
| Rastreio | Toda resposta traz o cabeçalho X-Request-ID. Você pode enviar o seu (letras, números e hífen, até 64 caracteres) para correlacionar com os seus logs. |
| Limite de uso | 600 requisições por minuto por chave. Acima disso, 429 com Retry-After. |
| Repetição segura | Em POST, PATCH e DELETE, envie Idempotency-Key. Repetir a mesma chave com o mesmo corpo devolve a resposta original (com X-Idempotency-Replay: 1); com corpo diferente, 409 idempotency_conflict. |
| Indisponibilidade momentânea | 503 (unavailable) e 409 (concurrency_conflict) trazem Retry-After: espere e tente de novo. |
Códigos HTTP mais comuns:
| Código | Significado | O que fazer |
|---|---|---|
400 | Pedido inválido (validation_error e outros códigos de regra de negócio, como webhook_url_invalid). | Corrija o pedido; não repita igual. |
401 | Chave ausente, inválida ou revogada. | Confira a chave. |
403 | A chave não tem a permissão necessária ou a rota não aceita chaves. | Ajuste as permissões da chave. |
404 | Recurso não existe ou está fora do alcance da chave (escopo de empresas, caso protegido). | Confira o código e o escopo. |
409 | Conflito (versão desatualizada, idempotência, concorrência). | Releia o recurso; repita só se houver Retry-After. |
422 | Corpo ou parâmetros fora do formato. | Veja detail. |
429 | Limite de uso atingido. | Espere Retry-After segundos. |
5xx | Falha do servidor. | Repita com espera; se persistir, informe o request_id ao suporte. |
Cliente Node.js (fetch)
Um cliente pequeno, sem dependências, com novas tentativas para 429/503, erros tipados e request_id sempre à mão.
import crypto from "node:crypto";
const BASE_URL = "https://api.trust.nearone.com.br";
const API_KEY = process.env.NEARONE_API_KEY;
export class NearOneError extends Error {
constructor(status, body, requestId) {
super(`${status} ${body?.code ?? "http_error"}: ${body?.message ?? "erro sem mensagem"} (request_id=${requestId})`);
this.status = status;
this.code = body?.code ?? (status === 422 ? "validation_error" : "http_error");
this.body = body;
this.requestId = requestId;
}
}
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
/**
* Faz uma chamada à API. Repete sozinho em 429, 503 e 409 com Retry-After.
* Para POST/PATCH/DELETE, gera uma Idempotency-Key (reaproveitada nas repetições).
*/
export async function api(method, path, { query, body, idempotencyKey, maxRetries = 3 } = {}) {
const url = new URL(path, BASE_URL);
for (const [key, value] of Object.entries(query ?? {})) {
if (value === undefined || value === null) continue;
url.searchParams.set(key, typeof value === "object" ? JSON.stringify(value) : String(value));
}
const headers = {
Authorization: `Bearer ${API_KEY}`,
Accept: "application/json",
"X-Request-ID": crypto.randomUUID(),
};
if (body !== undefined) headers["Content-Type"] = "application/json";
if (["POST", "PATCH", "DELETE"].includes(method)) {
headers["Idempotency-Key"] = idempotencyKey ?? crypto.randomUUID();
}
for (let attempt = 0; ; attempt++) {
const response = await fetch(url, {
method,
headers,
body: body === undefined ? undefined : JSON.stringify(body),
});
const requestId = response.headers.get("X-Request-ID");
if (response.status === 204) return null;
const text = await response.text();
const data = text ? JSON.parse(text) : null;
if (response.ok) return data;
const retryAfter = Number(response.headers.get("Retry-After"));
const retryable = [429, 503].includes(response.status) || (response.status === 409 && retryAfter > 0);
if (retryable && attempt < maxRetries) {
await sleep((retryAfter > 0 ? retryAfter : 2 ** attempt) * 1000);
continue;
}
throw new NearOneError(response.status, data, data?.request_id ?? requestId);
}
}
/** Percorre todas as páginas de uma listagem, item por item. */
export async function* listAll(path, query = {}) {
let cursor;
do {
const page = await api("GET", path, { query: { limit: 100, ...query, cursor } });
yield* page.items;
cursor = page.page.next_cursor;
} while (cursor);
}
Listar todos os casos em andamento
import { listAll, NearOneError } from "./nearone.js";
try {
let total = 0;
for await (const item of listAll("/api/v1/requests/demands", {
filter: { phase: "in_progress" },
sort: "-created_at",
})) {
total++;
console.log(item.code, item.stage_key, item.request_type_name);
}
console.log(`${total} casos em andamento`);
} catch (error) {
if (error instanceof NearOneError) {
// Registre o request_id: é o que o suporte precisa para localizar a chamada.
console.error(`Falha (${error.code}), request_id=${error.requestId}`);
} else {
throw error;
}
}
Ler um caso pelo código
O código de 4 caracteres (o mesmo do painel e do campo case_code dos webhooks) identifica o caso na URL:
import { api, NearOneError } from "./nearone.js";
try {
const caso = await api("GET", "/api/v1/requests/demands/8WG8");
console.log(caso);
} catch (error) {
if (error instanceof NearOneError && error.status === 404) {
console.log("Caso não existe ou está fora do alcance desta chave.");
} else {
throw error;
}
}
Cliente Python (httpx)
from __future__ import annotations
import json
import os
import time
import uuid
from collections.abc import Iterator
from typing import Any
import httpx
BASE_URL = "https://api.trust.nearone.com.br"
class NearOneError(Exception):
def __init__(self, status: int, body: Any, request_id: str | None) -> None:
self.status = status
self.body = body if isinstance(body, dict) else {}
self.code = self.body.get("code") or ("validation_error" if status == 422 else "http_error")
self.request_id = self.body.get("request_id") or request_id
message = self.body.get("message") or "erro sem mensagem"
super().__init__(f"{status} {self.code}: {message} (request_id={self.request_id})")
class NearOne:
def __init__(self, api_key: str | None = None, *, max_retries: int = 3) -> None:
self.max_retries = max_retries
self.http = httpx.Client(
base_url=BASE_URL,
headers={
"Authorization": f"Bearer {api_key or os.environ['NEARONE_API_KEY']}",
"Accept": "application/json",
},
timeout=30.0,
)
def request(
self,
method: str,
path: str,
*,
params: dict[str, Any] | None = None,
json_body: Any = None,
idempotency_key: str | None = None,
) -> Any:
query = {
key: json.dumps(value) if isinstance(value, (dict, list)) else value
for key, value in (params or {}).items()
if value is not None
}
headers = {"X-Request-ID": uuid.uuid4().hex}
if method in {"POST", "PATCH", "DELETE"}:
headers["Idempotency-Key"] = idempotency_key or str(uuid.uuid4())
for attempt in range(self.max_retries + 1):
response = self.http.request(method, path, params=query, json=json_body, headers=headers)
if response.status_code == 204:
return None
body = response.json() if response.content else None
if response.is_success:
return body
retry_after = response.headers.get("Retry-After")
retryable = response.status_code in (429, 503) or (
response.status_code == 409 and retry_after is not None
)
if retryable and attempt < self.max_retries:
time.sleep(float(retry_after) if retry_after else 2**attempt)
continue
raise NearOneError(response.status_code, body, response.headers.get("X-Request-ID"))
def get(self, path: str, **params: Any) -> Any:
return self.request("GET", path, params=params)
def list_all(self, path: str, **params: Any) -> Iterator[dict]:
cursor = None
while True:
page = self.get(path, limit=100, cursor=cursor, **params)
yield from page["items"]
cursor = page["page"]["next_cursor"]
if not cursor:
return
Exportar empresas para CSV
import csv
import sys
from nearone import NearOne, NearOneError
client = NearOne()
try:
writer = csv.writer(sys.stdout)
writer.writerow(["code", "cnpj", "legal_name", "trade_name"])
for company in client.list_all("/api/v1/companies", sort="legal_name"):
writer.writerow(
[company["code"], company["cnpj"], company["legal_name"], company.get("trade_name")]
)
except NearOneError as error:
print(f"Falha {error.status} ({error.code}). request_id={error.request_id}", file=sys.stderr)
sys.exit(1)
Os nomes exatos dos campos e os filtros aceitos por cada listagem estão na referência da API, por exemplo List Companies e List Demands.
Receptor de webhook completo
Fluxo recomendado: validar a assinatura → descartar repetidos → responder 2xx → processar em segundo plano → consultar a API se precisar de detalhes. Os detalhes do formato e da assinatura estão em Webhooks.
Node.js (Express)
import crypto from "node:crypto";
import express from "express";
import { api } from "./nearone.js";
const SECRET = process.env.NEARONE_WEBHOOK_SECRET;
const seen = new Set(); // Em produção, use uma tabela com chave única (delivery_id).
function verify(rawBody, header) {
if (!header) return false;
const pairs = header.split(",").map((p) => [p.slice(0, p.indexOf("=")), p.slice(p.indexOf("=") + 1)]);
const t = pairs.find(([k]) => k === "t")?.[1];
if (!t || !/^\d+$/.test(t) || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = Buffer.from(
crypto.createHmac("sha256", SECRET).update(`${t}.`).update(rawBody).digest("hex")
);
return pairs
.filter(([k]) => k === "v1")
.some(([, v]) => {
const got = Buffer.from(v);
return got.length === expected.length && crypto.timingSafeEqual(got, expected);
});
}
async function handle(event) {
switch (event.kind) {
case "webhook.ping":
console.log("Teste recebido.");
return;
case "reporting.case.received": {
if (event.data.protected) {
console.log("Novo relato em caso protegido (sem detalhes).");
return;
}
const caso = await api("GET", `/api/v1/requests/demands/${event.data.case_code}`);
console.log("Novo relato", event.data.case_code, event.data.type, caso);
return;
}
case "reporting.case.sla_overdue":
console.log("Prazo vencido no caso", event.data.case_code);
return;
default:
console.log("Evento", event.kind, event.data);
}
}
const app = express();
app.post("/hooks/nearone", express.raw({ type: "application/json" }), (req, res) => {
if (!verify(req.body, req.get("X-Sg-Signature"))) return res.sendStatus(401);
const deliveryId = req.get("X-Sg-Delivery");
if (seen.has(deliveryId)) return res.sendStatus(204); // repetido: já tratado
seen.add(deliveryId);
const event = JSON.parse(req.body.toString("utf8"));
res.sendStatus(204); // responda antes de processar (limite de 10 s)
handle(event).catch((error) => console.error("Falha ao processar", deliveryId, error));
});
app.listen(3000, () => console.log("Receptor em http://localhost:3000/hooks/nearone"));
Python (FastAPI + httpx)
import hashlib
import hmac
import json
import os
import time
from fastapi import BackgroundTasks, FastAPI, Request, Response
from nearone import NearOne, NearOneError
SECRET = os.environ["NEARONE_WEBHOOK_SECRET"]
client = NearOne()
seen: set[str] = set() # Em produção, use uma tabela com chave única (delivery_id).
app = FastAPI()
def verify(raw: bytes, header: str | None) -> bool:
if not header:
return False
pairs = [part.split("=", 1) for part in header.split(",") if "=" in part]
t = next((v for k, v in pairs if k == "t"), "")
if not t.isdigit() or abs(time.time() - int(t)) > 300:
return False
expected = hmac.new(SECRET.encode(), t.encode() + b"." + raw, hashlib.sha256).hexdigest()
return any(hmac.compare_digest(v, expected) for k, v in pairs if k == "v1")
def handle(event: dict) -> None:
kind, data = event["kind"], event["data"]
if kind == "reporting.case.received" and not data.get("protected"):
try:
case = client.get(f"/api/v1/requests/demands/{data['case_code']}")
print("Novo relato", data["case_code"], case)
except NearOneError as error:
print(f"Falha ao ler o caso: {error.code} request_id={error.request_id}")
else:
print("Evento", kind, data)
@app.post("/hooks/nearone")
async def receive(request: Request, background: BackgroundTasks) -> Response:
raw = await request.body()
if not verify(raw, request.headers.get("X-Sg-Signature")):
return Response(status_code=401)
delivery_id = request.headers.get("X-Sg-Delivery", "")
if delivery_id in seen:
return Response(status_code=204)
seen.add(delivery_id)
background.add_task(handle, json.loads(raw))
return Response(status_code=204)
Para testar localmente, exponha a porta com um túnel HTTPS (por exemplo, um serviço de túnel da sua preferência), cadastre a URL pública no webhook e use Enviar teste.
Reenviar entregas que esgotaram
Depois de corrigir uma falha no receptor, reenvie o que ficou para trás. Cada reenvio é uma única tentativa, com o mesmo X-Sg-Delivery e o mesmo id de evento, então o seu receptor idempotente não processa nada em dobro.
A receita reenvia só as entregas esgotadas (exhausted). As que estão como failed ainda têm novas tentativas automáticas agendadas: reenviá-las à mão troca essas tentativas por uma única tentativa manual, sem ganho real.
from nearone import NearOne
client = NearOne()
WEBHOOK = "AB12" # código de 4 caracteres do webhook
for delivery in client.list_all(
f"/api/v1/webhooks/{WEBHOOK}/deliveries",
filter={"status": "exhausted"},
sort="created_at",
):
queued = client.request(
"POST", f"/api/v1/webhooks/{WEBHOOK}/deliveries/{delivery['id']}/redeliver"
)
print(delivery["event_kind"], delivery["id"], "->", queued["delivery_id"])
São até 120 reenvios por hora por webhook. O cliente acima espera e repete sozinho quando recebe 429 com Retry-After.
Criar um webhook e testar (Node.js)
import { api } from "./nearone.js";
const created = await api("POST", "/api/v1/webhooks", {
body: {
name: "Plantão de compliance",
url: "https://hooks.suaempresa.com.br/nearone",
event_kinds: ["reporting.case.received", "reporting.case.sla_overdue"],
},
});
console.log("Guarde agora o segredo:", created.secret); // só aparece nesta resposta
const { delivery_id } = await api("POST", `/api/v1/webhooks/${created.code}/test`);
// O teste é assíncrono: consulte a entrega por alguns segundos.
for (let i = 0; i < 5; i++) {
await new Promise((r) => setTimeout(r, 2000));
const delivery = await api("GET", `/api/v1/webhooks/${created.code}/deliveries/${delivery_id}`);
if (delivery.status !== "pending") {
console.log(delivery.status, delivery.response_status, delivery.error, `${delivery.duration_ms} ms`);
break;
}
}
Ao falar com o suporte
Se algo der errado, envie ao suporte o request_id (do corpo do erro ou do cabeçalho X-Request-ID), a rota chamada e o horário. Com isso a equipe localiza a chamada sem que você precise compartilhar a chave, dados de casos ou o corpo completo da requisição.
Próximos passos: Primeiros passos · Webhooks · MCP · Referência da API.