概述 - BrazilScope Docs

BrazilScope 面向中国企业出海巴西场景，将巴西政府公开数据（RFB 企业登记库、PNCP 采购、Portal da Transparência 制裁名单等）整理为标准化 REST 接口，覆盖企业搜索、企业详情、股东结构、关联关系、政府采购记录、公共处罚与制裁、AI 尽调报告。

基础信息

项目	值
生产环境基址	`https://api.brazilscope.com`
本地开发基址	`http://127.0.0.1:8034`
接口版本	`v1`，路径前缀 `/api/v1`
协议	HTTPS（生产）/ HTTP（本地）
数据格式	`application/json; charset=utf-8`
字符编码	UTF-8
时间字段	UTC，`YYYY-MM-DDTHH:mm:ssZ`；纯日期 `YYYY-MM-DD`
CNPJ 格式	14 位数字；允许传入带标点格式（如 `12.345.678/0001-95`），服务端自动清洗

鉴权

除健康检查外，所有接口需在请求头携带 API Key：

API Key 在控制台「开发者 → 项目与密钥」创建，每个项目对应一把 Key，配额按项目隔离。

Key 仅创建时完整展示一次，请立即保存；丢失后需重新创建。

禁止将 Key 写入前端代码或公开仓库；服务端调用请放入环境变量。

Key 缺失或无效返回 401 UNAUTHORIZED。

统一响应结构

成功：

{
  "success": true,
  "data": {},
  "meta": { "request_id": "req_8f3a" }
}

失败：

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "CNPJ 11222333000181 未收录",
    "request_id": "req_8f3a",
    "details": { "cnpj": "11222333000181" }
  }
}

字段	类型	说明
`success`	bool	是否成功；失败时 `data` 为空
`data`	object	业务数据，结构由具体接口决定
`meta.request_id`	string	请求唯一标识，排障时请提供
`error.code`	string	全局错误码枚举，见第 4 节
`error.message`	string	可直接展示给用户的错误描述
`error.details`	object	可选，定位问题所需的上下文

分页约定

列表接口统一使用 page（默认 1）与 page_size（默认 20，最大 100），响应返回 list、total、page、page_size。是否还有下一页以 page * page_size < total 判断。

限流与配额

计费接口（搜索、详情、报告）叠加令牌桶限流：已登录按用户、未登录按来源 IP，默认 5 QPS，突发 10。

触发限流返回 429 RATE_LIMITED，响应头含 Retry-After（秒）。

控制台查询配额按套餐：免费版 20 次/月、单次查看 100 次、月付专业版 1,000 次/月、年付专业版 10,000 次/月（以控制台「用量统计」为准）。

建议仅对 429、503 与网络超时做指数退避重试；单次请求超时建议 10 秒。

概述

基础信息#

鉴权#

统一响应结构#

分页约定#

限流与配额#

基础信息

鉴权

统一响应结构

分页约定

限流与配额