跳到主要内容

离线余额查询

即时查询受益人最新的已保存数据。

技术优势
  • 同步返回 — 无需处理队列或等待 webhook；
  • 可访问已冻结的受益 — 即使受益已被冻结，仍返回系统中最新的已保存数据；
  • 缓存查询 — 不依赖 Dataprev 可用性，不消耗 API 调用次数。

请求​

ENDPOINT
/social_security/balance_request/offline
方法
GET

查询参数​

document_numberstring必填受益人 CPF（仅数字，11 位）。benefit_numberstring必填INSS 受益编号。
GET /social_security/balance_request/offline?document_number=14950479032&benefit_number=22255220

响应​

STATUS
200

属性​

last_successful_balance_requestobject | null最近一次成功的余额查询。如果从未成功查询过，则为 null。

last_successful_balance_request 的属性：

consulted_atstring查询的日期和时间（ISO 8601）。dataobject完整的受益数据。与余额查询 webhook 结构相同。参见字段详情。
last_blocked_statusobject | null最近的冻结状态。如果没有可用信息，则为 null。自动从最新来源推导 — 无论是余额查询、预约尝试还是受益检查。

last_blocked_status 的属性：

consulted_atstring最近一次检查的日期和时间（ISO 8601）。statusstring"blocked" 或 "unblocked"。
信息

200 响应中至少有一个字段会被填充。如果给定组合没有数据，端点返回 404。

{
    "last_successful_balance_request": {
        "consulted_at": "2025-01-15T14:32:10-03:00",
        "data": {
            "name": "NOME BENEFICIARIO",
            "state": "RS",
            "alimony": "not_payer",
            "birth_date": "18021978",
            "block_type": "not_blocked",
            "grant_date": "2006-05-22",
            "credit_type": "checking_account",
            "benefit_card": {
                "limit": 2259.20,
                "balance": 0
            },
            "benefit_number": "22255220",
            "benefit_status": "elegible",
            "payroll_card": {
                "limit": 2259.20,
                "balance": 0
            },
            "assistance_type": "retirement_invalidity_social_security",
            "document_number": "14950479032",
            "benefit_end_date": null,
            "consigned_credit": {
                "balance": 0
            },
            "benefit_situation": "active",
            "last_inquiry_date": "2018-06-18",
            "max_total_balance": 635.40,
            "used_total_balance": 635.40,
            "politically_exposed": {
                "type": "not_politically_exposed",
                "is_politically_exposed": false
            },
            "has_power_of_attorney": false,
            "available_total_balance": 0,
            "has_judicial_concession": false,
            "number_of_portabilities": 0,
            "disbursement_bank_account": {
                "bank_code": "748",
                "account_digit": "4",
                "account_branch": "0155",
                "account_number": "000070963"
            },
            "has_entity_representation": false,
            "social_benefit_max_balance": 635.40,
            "social_benefit_used_balance": 635.40,
            "benefit_quota_expiration_date": null,
            "number_of_active_reservations": 3,
            "number_of_suspended_reservations": 0,
            "number_of_refinanced_reservations": 0,
            "number_of_active_suspended_reservations": 3
        }
    },
    "last_blocked_status": {
        "consulted_at": "2025-01-15T14:32:10-03:00",
        "status": "unblocked"
    }
}
data 字段
namestring受益人姓名。document_numberstring受益人 CPF。benefit_numberstringINSS 受益编号。benefit_statusstring受益状态（elegible、inelegible）。block_typestring冻结类型（not_blocked、blocked_by_tbm 等）。benefit_situationstring受益情况（active、inactive 等）。assistance_typestring援助/退休类型。available_total_balancenumber可用于委托的总余额。consigned_creditobject委托贷款余额（balance）。payroll_cardobject工资卡（balance、limit）。benefit_cardobject受益卡（balance、limit）。number_of_active_reservationsinteger活跃预约数量。disbursement_bank_accountobject支付银行账户详情（bank_code、account_digit、account_branch、account_number）。

响应场景​

场景last_successful_balance_requestlast_blocked_status.status
仅成功查询最近一次查询数据"unblocked"
仅冻结查询null"blocked"
成功后被冻结最近一次查询数据"blocked"
冻结后成功查询最近一次查询数据"unblocked"

错误​

HTTP 代码QI 代码描述
401/403（标准）缺少或无效的身份验证头
404SSC000101未找到给定 document_number + benefit_number 组合的数据
404 响应示例
{
    "title": "Offline Balance Not Found",
    "description": "No balance data found for document_number {document_number} and benefit_number {benefit_number}.",
    "translation": "Nenhum dado de saldo encontrado para document_number {document_number} e benefit_number {benefit_number}",
    "code": "SSC000101"
}