身份核验

能力概述

按纳税人识别号查询巴西官方登记信息：

两个端点均为 GET：签名用的 body 为空字符串，所有路径变量（CNPJ / CPF / 出生日期）都属于签名 path，见 认证与签名。响应为裸结构（不带平台信封）；业务错误为裸 {code, message} 对象。

CPF 为何必须带出生日期

上游按 CPF 与出生日期配对核验（巴西联邦税务局语义），只给 CPF 查不到。配对不符与查无此人返回同一个错误码，不作区分：区分开来接口就成了校验他人生日的探测工具。

对接前提（一次性）

1. 应用凭证：申请应用并领取 app_secret，仅回显一次，请妥善保存。
2. 接口订阅：平台为你的应用开通所需端点的调用授权（scope 键即端点路径）。

端点

错误模型

两种错误形状

业务、请求级与上游侧错误（HTTP 400 / 422 / 428 / 451 / 503）为裸对象：

{ "code": 10016003, "message": "未找到该 CPF 的信息" }

鉴权层错误（HTTP 401 / 403 / 429）由平台网关在请求到达接口前产出，为平台信封形状：

{ "success": false, "errorType": 1, "code": 10009005, "message": "API 未订阅，请订阅后调用" }

注意： 错误处理须兼容两种形状。稳妥做法：把响应体按 JSON 解析，从任一形状读取 code，以 success=false 或 HTTP >= 400 判定失败。

业务错误码

格式与校验位错误由平台本地拦截，不会发往上游数据源，因此不消耗调用额度也不计费。

责任方约定：10016000 到 10016003、10016010 到 10016012 为调用方问题；10016004 到 10016006 为第三方依法拦截；10016020 为第三方不可用；HTTP 500 + 10001000 为平台自身异常。

计费：10016003（查无 / 出生日期不配对）、10016004（小于 16 岁）、10016005（16 到 17 岁）按次计费；10016006（年龄无法核实）、10016020（上游不可用）与本地拦截的格式 / 校验位错误不计费。年龄分档详见 CPF 查询 页。

鉴权与授权错误

重试指引：401 与 403 属配置错误，不修复就重试无意义且可能触发限流；429 与 503（10016020）可退避重试；422 / 428 / 451 是法定拦截，重试无意义；500 建议携带失败请求的 timestamp 与路径联系平台。

HTTP 状态速查

数据合规说明

CPF 属自然人个人数据，受巴西 LGPD（第 13.709/2018 号法律）约束：

• 平台不留存 CPF 查询结果，每次查询实时回源。
• CPF 全号不写入应用日志，日志中一律掩码。
• 调用日志中的路径变量经 HMAC 处理后入库，不含明文。
• 上游对未成年人依法不返回数据，平台以 451 / 422 / 428 原状态码透传、不留存；451 / 422 按次计费，428 不计费，见 CPF 查询 页的“未成年人与年龄核实”。

请对接方同样遵循最小必要原则：仅在开票等确有法律依据的业务场景下查询，不得留存超出业务需要的个人数据。

响应语言

message 字段随请求语言返回：Language 头（zh / en / pt / es）优先，其次 Accept-Language（支持 pt-BR 与 q 值）。未提供语言头时默认葡语（pt）。

程序判断一律使用 code 数字码与 situacao.codigo 等枚举值，不要匹配描述文案。LGPD 三档拦截的 message 是法定葡语文案，不随语言翻译。

联调清单

1. 领取 app_secret，确认两个端点均已订阅。
2. 用一个真实 CNPJ 调用：HTTP 200，ni 与入参一致，situacaoCadastral.codigo 为 2。
3. 用一组真实 CPF + 出生日期调用：HTTP 200，nascimento 回显与入参一致。
4. 反向用例：CPF 正确但出生日期错误，得到 400 + 10016003（与查无此人同码）。
5. 反向用例：校验位错误的 CNPJ / CPF，得到 400 + 10016011 / 10016001（本地拦截，不计费）。
6. 反向用例：出生日期传 1997-01-09 或 31021997，得到 400 + 10016002。
7. 失败路径：故意用错误 sign 得到 401 + 10009003；调用未订阅端点得到 403 + 10009005。
8. 解析器兼容性：确认你的客户端把 422 / 428 / 451 / 503 都按失败处理并能读出裸 {code, message}（这些状态码无法用测试数据主动构造，上线后遇到真实未成年 CPF 才会出现）。

排障

1. GET 请求没把 body 当作空字符串 "" 拼接（拼成了空对象、占位文本等）；
2. path 缺 /openapi 前缀，或误带查询串；
3. CPF 接口漏拼出生日期段，两个路径变量都要参与签名；
4. sign 用了大写（必须小写十六进制）；
5. 拼接用的 timestamp 与请求头不是同一个值（两次生成）；
6. CNPJ 带了格式符，/ 把路径切断了。

可先用 认证与签名 中签名示例的固定取值复算比对，确认本地实现无误后再排查线上参数。