SIAPE-SIGEPE API 手册

注意！

QI Tech 的 webhooks 不应被严格映射。 API 返回的 webhook 负载中可能会添加额外字段。

Webhook 重发

您可以按照文档中的详细说明查询和重发 webhooks：重发 Webhooks。

1. 成功或失败场景的模拟

为方便测试，我们提供了一组可用于在沙盒中模拟成功或失败场景的数据：

查询余额和批注的成功场景

document_number	authority_code	registration_code	origin_contract_number	financial_institution_document_number
25256363506	17000	1354387	526985/WU	00000000000191

查询余额的失败场景

document_number	failure_reason
71987878353	unauthorized_institution

注意

没有映射场景的 CPF 将收到一个包含未映射测试场景标准错误的 webhook。

枚举值描述
mock_error Informed document number is not a valid mock on test environment
每天结束时（23:59），所有尚未处于最终状态（已预留/已取消/已删除）的预留将被关闭（取消/删除），以避免测试环境过载。

枚举值	描述
mock_error	Informed document number is not a valid mock on test environment

2. 查询可扣除边际

在请求查询可扣除边际之前，公务员需要在服务人员门户网站上授权 QI Sociedade de Crédito Direto S.A. 进行代扣贷款操作（在门户中按以下路径操作："Consignações > Empréstimo Consignado > Autorizar Consignatário"）。

服务人员的授权有效期为 30 个自然日。

服务人员授权后，可通过以下端点查询可扣除边际：

SIAPE 运营时间

SIAPE 系统的运营时间为周一至周五 07:00 至 00:00，节假日除外。

Request

ENDPOINT

/federal_payroll/balance

MÉTODO

POST

Request Body

{
	"document_number": "\<CPF SERVIDOR\>"
}

信息

CPF 应以文本格式提供，最多 11 个字符，不含"."，不含"-"，并在左侧补零对齐。

Response

ENDPOINT

/federal_payroll/balance

MÉTODO

POST

Response Body

{
	"balance_key": "\<GUID DA CONSULTA DA MARGEM CONSIGNÁVEL\>",
	"status": "pending_search"
}

查询成功

查询成功后，服务人员的边际数据将通过 webhook 返回。

如果服务人员仅授权 QI SCD 办理代扣贷款，成功的 webhook 将以如下形式返回：

WEBHOOK_TYPE

federal_payroll.balance

STATUS

Success

Body

{
	"key": "\<BALANCE-KEY\>",
	"event_datetime": "2022-09-05T18:43:29Z",
	"status": "success",
	"data": {
		"reference_date": "2019-10-21T12:30:00Z",
		"name": "João José Silva e Silva",
		"balance_query": [
			{
				"institution_authorized_for_credit_balance": true,
				"employment_relationship": "attendant",
				"employment_classification": "stable",
                "pensioner_registration_code": "",
				"registration_code": "12345678",
                "pension_validity":"",
                "pension_type":"",
                "employment_functional_situation":"EST01-PERMANENT ACTIVE",
				"authority": {
					"code": "17000",
                    "authority_document_number": "29132934000134",
					"description": "MINISTERIO DA ECONOMIA"
				},
				"consigned_credit": {
					"available_balance": 4277.78,
                    "expiration_date": "2023-03-14"
				},
                "bank_account":{
                    "account":"00000111948**",
                    "bank_code":1,
                    "account_branch":"0338**"
                },
			}
		]
	}
}

如果服务人员授权 QI SCD 办理代扣贷款和代扣信用卡，成功的 webhook 将以如下形式返回：

WEBHOOK_TYPE

federal_payroll.balance

STATUS

Success

Body

{
	"key": "\<BALANCE-KEY\>",
	"event_datetime": "2022-09-05T18:43:29",
	"webhook_type": "federal_payroll_balance",
	"status": "success",
	"data": {
		"reference_date": "2019-10-21T12:30:00Z",
		"name": "João José Silva e Silva",
		"balance_query": [
			{
				"institution_authorized_for_credit_balance": true,
				"employment_relationship": "attendant",
				"employment_classification": "stable",
                "pensioner_registration_code": "",
				"registration_code": "12345678",
                "pension_validity":"",
                "pension_type":"",
                "employment_functional_situation":"EST01-PERMANENT ACTIVE",
				"authority": {
					"code": "17000",
                    "authority_document_number": "29132934000134",
					"description": "MINISTERIO DA ECONOMIA"
				},
				"consigned_credit": {
					"available_balance": 4277.78,
                    "expiration_date": "2023-03-14"
				},
				"consigned_card": {
					"available_balance": 718.26
				},
                "bank_account":{
                    "account":"00000111948**",
                    "bank_code":1,
                    "account_branch":"0338**"
                 },
			}
		]
	}
}

Federal Payroll Balance 字段定义

字段	描述
registration_code	服务人员的注册代码
data.balance_query.employment_relationship	Employment Relationship 枚举
data.balance_query.employment_classification	Employment Classification 枚举
data.balance_query.pensioner_registration_code	当 employment_relationship 为 "pensioner" 类型时，此字段将填写机构代码 + 服务人员注册号
data.balance_query.pension_type	当 employment_relationship 为 "pensioner" 类型时，此字段将填写养老金类型
data.balance_query.pension_validity	当 employment_relationship 为 "pensioner" 类型且 pension_type 为 "temporary" 时，此字段可能填写养老金有效期
data.balance_query.employment_functional_situation	功能状况类型的代码和描述，现有代码详见附件 1
data.balance_query.consigned_credit.available_balance	可用于申请代扣贷款的金额
data.balance_query.consigned_card.available_balance	可用于支付代扣信用卡账单的金额
data.balance_query.institution_authorized_for_credit_balance	用于说明机构是否有权查询借款人边际的标志（"true" 或 "false"）。

查询失败

如果余额查询失败，将返回包含以下已映射枚举值之一的 webhook：

WEBHOOK_TYPE

federal_payroll.balance

STATUS

Failure

Body

{
    "key": "\<BALANCE-KEY\>",
	"event_datetime": "2022-09-05T18:43:29Z",
	"webhook_type": "federal_payroll_balance",
	"status": "failure",
	"data": {
		"enumerator": "unauthorized_institution",
		"description": "Institution is not authorized to search for client."
	}
}

枚举值	描述
unauthorized_institution	Institution is not authorized to search for client.
inexistent_relationship	This client does not have any known federal employment relationship.
invalid_document_number	Invalid document number
inactive_federal_employee	Inactive federal employee
deceased_federal_employee	Deceased federal employee

3. 模拟代扣贷款

Request

ENDPOINT

/debt_simulation

MÉTODO

POST

Request Body

{
    "borrower": {
        "person_type": "natural"
    },
    "financial": {
        "first_due_date": "2023-04-07",
        "installment_face_value": 100.0,
        "disbursement_date": "2023-03-14",
        "limit_days_to_disburse": 3,
        "number_of_installments": 2,
        "monthly_interest_rate": 0.0205,
        "interest_type": "pre_price_days",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0
    },
    "collaterals": [{
        "collateral_type": "federal_payroll"
    }]
}

Response

ENDPOINT

/debt_simulation

MÉTODO

POST

Response Body

{
  "data": {
    "annual_cet": 0.5040756794535896,
    "assignment_amount": 196.75,
    "cet": 0.0346,
    "contract_fee_amount": 1.95,
    "contract_fees": [
      {
        "amount": 1,
        "amount_type": "percentage",
        "fee_amount": 1.95,
        "fee_type": "tac"
      }
    ],
    "credit_operation_type": "ccb",
    "disbursed_issue_amount": 191.49,
    "disbursement_date": "2023-03-14",
    "disbursement_options": [
      {
        "annual_cet": 0.5040756794535896,
        "assignment_amount": 196.75,
        "cet": 0.0346,
        "contract_fee_amount": 1.95,
        "contract_fees": [
          {
            "amount": 1,
            "amount_type": "percentage",
            "fee_amount": 1.95,
            "fee_type": "tac"
          }
        ],
        "disbursed_issue_amount": 191.49,
        "disbursement_date": "2023-03-14",
        "external_contract_fee_amount": 1.95,
        "external_contract_fees": [
          {
            "amount": 1,
            "amount_released": 1.77,
            "amount_type": "percentage",
            "cofins_amount": 0,
            "csll_amount": 0,
            "description": null,
            "fee_amount": 1.95,
            "fee_type": "spread",
            "irrf_amount": 0,
            "net_fee_amount": 1.77,
            "pis_amount": 0,
            "tax_amount": 0.18
          }
        ],
        "first_due_date": "2023-04-07",
        "installments": [
          {
            "business_due_date": "2023-04-10",
            "calendar_days": 24,
            "due_date": "2023-04-07",
            "due_principal": 194.8,
            "has_interest": true,
            "installment_number": 1,
            "post_fixed_amount": null,
            "pre_fixed_amount": 3.1882715773,
            "principal_amortization_amount": 96.8117284227,
            "tax_amount": 0.1905254815358736,
            "total_amount": 100,
            "workdays": 17
          },
          {
            "business_due_date": "2023-05-08",
            "calendar_days": 30,
            "due_date": "2023-05-07",
            "due_principal": 97.9882715773,
            "has_interest": true,
            "installment_number": 2,
            "post_fixed_amount": null,
            "pre_fixed_amount": 2.0088192272,
            "principal_amortization_amount": 97.9911807728,
            "tax_amount": 0.4339049484619584,
            "total_amount": 100,
            "workdays": 18
          }
        ],
        "iof_amount": 1.36,
        "issue_amount": 194.8,
        "net_external_contract_fee_amount": 1.77,
        "prefixed_interest_rate": {
          "annual_rate": 0.27572219,
          "daily_rate": 0.00067665,
          "interest_base": "calendar_days",
          "monthly_rate": 0.0205
        },
        "total_pre_fixed_amount": 5.1970908045
      }
    ],
    "external_contract_fee_amount": 1.95,
    "external_contract_fees": [
      {
        "amount": 1,
        "amount_released": 1.77,
        "amount_type": "percentage",
        "cofins_amount": 0,
        "csll_amount": 0,
        "description": null,
        "fee_amount": 1.95,
        "fee_type": "spread",
        "irrf_amount": 0,
        "net_fee_amount": 1.77,
        "pis_amount": 0,
        "tax_amount": 0.18
      }
    ],
    "final_disbursement_amount": 191.49,
    "installments": [
      {
        "business_due_date": "2023-04-10",
        "calendar_days": 24,
        "due_date": "2023-04-07",
        "due_principal": 194.8,
        "has_interest": true,
        "installment_number": 1,
        "post_fixed_amount": null,
        "pre_fixed_amount": 3.1882715773,
        "principal_amortization_amount": 96.8117284227,
        "tax_amount": 0.1905254815358736,
        "total_amount": 100,
        "workdays": 17
      },
      {
        "business_due_date": "2023-05-08",
        "calendar_days": 30,
        "due_date": "2023-05-07",
        "due_principal": 97.9882715773,
        "has_interest": true,
        "installment_number": 2,
        "post_fixed_amount": null,
        "pre_fixed_amount": 2.0088192272,
        "principal_amortization_amount": 97.9911807728,
        "tax_amount": 0.4339049484619584,
        "total_amount": 100,
        "workdays": 18
      }
    ],
    "interest_grace_period": 0,
    "interest_payment_month_period": 1,
    "interest_type": "pre_price_days",
    "iof_amount": 1.36,
    "issue_amount": 194.8,
    "issue_date": "2023-03-14",
    "net_external_contract_fee_amount": 1.77,
    "number_of_installments": 2,
    "operation_type": "structured_operation",
    "post_fixed_interest_base": "workdays",
    "post_fixed_interest_rate": null,
    "prefixed_interest_rate": {
      "annual_rate": 0.27572219,
      "daily_rate": 0.00067665,
      "interest_base": "calendar_days",
      "monthly_rate": 0.0205
    },
    "principal_amortization_month_period": 1,
    "principal_grace_period": 0,
    "requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
    "total_pre_fixed_amount": 5.1970908045
  },
  "event_datetime": "2023-03-15 00:26:05",
  "key": "5c7441d2-8282-45e6-aaa8-7062bb155aa3",
  "status": "finished",
  "type": "debt"
}

4. 发行代扣贷款

Request

ENDPOINT

/debt

MÉTODO

POST

自由边际录入
再融资录入

Request Body
{
	"borrower": {
		"name": "\<NOME DEVEDOR\>",
		"email": "\<EMAIL DEVEDOR\>",
		"phone": {
			"number": "\<CELUAR DO DEVEDOR\>",
			"area_code": "\<DDD DO DEVEDOR\>",
			"country_code": "+55"
		},
		"address": {
			"city": "\<CIDADE DO DEVEDOR\>",
			"state": "\<ESTADO DO DEVEDOR\>",
			"number": "\<No. DO DEVEDOR\>",
			"street": "\<RUA DO DEVEDOR\>",
			"complement": "\<COMPLEMENTO DO DEVEDOR\>",
			"postal_code": "\<CEP DO DEVEDOR\>",
			"neighborhood": "\<BAIRRO DO DEVEDOR\>"
		},
		"role_type": "issuer",
		"birth_date": "\<DATA DE NASCIMENTO DO DEVEDOR\>",
		"mother_name": "\<NOME DA MÃE DO DEVEDOR\>",
		"person_type": "natural",
		"individual_document_number": "\<CPF DO DEVEDOR\>",
		"gender": "\<SEXO DO DEVEDOR\>",
		"nationality": "\<NACIONALIDADE DO DEVEDOR\>",
		"is_pep": false,
		"marital_status": "\<ESTADO CIVIL DO DEVEDOR\>",
        "document_identification_date": "2022-08-01",
        "document_identification_type": "rg",
        "document_identification_number": "123456777"
	},
	"financial": {
		"first_due_date": "2022-12-07",
		"installment_face_value": 100.0,
		"disbursement_date": "2022-11-03",
		"number_of_installments": 24,
        "monthly_interest_rate": 0.0205,
		"interest_type": "pre_price_days",
		"fine_configuration": {
			"monthly_rate": 0.01,
			"interest_base": "calendar_days",
			"contract_fine_rate": 0.02
		},
		"credit_operation_type": "ccb",
		"interest_grace_period": 0,
		"principal_grace_period": 0
	},
	"simplified": true,
	"collaterals": [{
		"percentage": 1,
		"collateral_data": {
            "reservation_type": "new_credit",
			"reservation_method": "creation",
			"authority_code": "17000",
            "pensioner_registration_code": "",
			"registration_code": "12345678",
            "authority": {
		        "description": "teste",
		        "authority_document_number": "1234"
	        }
		},
		"collateral_type": "federal_payroll"
	}],
	"requester_identifier_key": "\<ID DE CONTROLE DO PARCEIRO\>",
	"disbursement_bank_account": {
		"name": "\<NOME DO DEVEDOR\>",
		"bank_code": "104",
		"account_type": "checking_account",
		"account_digit": "1",
		"branch_number": "3880",
		"account_number": "000736703806",
		"document_number": "\<CPF DO DEVEDOR\>",
		"transfer_method": "pix"
	},
	"purchaser_document_number": "\<CNPJ DO CESSIONÁRIO\>"
}

Request Body
{
	"borrower": {
		"name": "\<NOME DEVEDOR\>",
		"email": "\<EMAIL DEVEDOR\>",
		"phone": {
			"number": "\<CELUAR DO DEVEDOR\>",
			"area_code": "\<DDD DO DEVEDOR\>",
			"country_code": "+55"
		},
		"address": {
			"city": "\<CIDADE DO DEVEDOR\>",
			"state": "\<ESTADO DO DEVEDOR\>",
			"number": "\<No. DO DEVEDOR\>",
			"street": "\<RUA DO DEVEDOR\>",
			"complement": "\<COMPLEMENTO DO DEVEDOR\>",
			"postal_code": "\<CEP DO DEVEDOR\>",
			"neighborhood": "\<BAIRRO DO DEVEDOR\>"
		},
		"role_type": "issuer",
		"birth_date": "\<DATA DE NASCIMENTO DO DEVEDOR\>",
		"mother_name": "\<NOME DA MÃE DO DEVEDOR\>",
		"person_type": "natural",
		"individual_document_number": "\<CPF DO DEVEDOR\>",
		"gender": "\<SEXO DO DEVEDOR\>",
		"nationality": "\<NACIONALIDADE DO DEVEDOR\>",
		"is_pep": false,
		"marital_status": "\<ESTADO CIVIL DO DEVEDOR\>",
        "document_identification_date": "2022-08-01",
        "document_identification_type": "rg",
        "document_identification_number": "123456777"
	},
	"financial": {
		"first_due_date": "2022-12-07",
		"installment_face_value": 100.0,
		"disbursement_date": "2022-11-03",
		"number_of_installments": 24,
        "monthly_interest_rate": 0.0205,
		"interest_type": "pre_price_days",
		"fine_configuration": {
			"monthly_rate": 0.01,
			"interest_base": "calendar_days",
			"contract_fine_rate": 0.02
		},
		"credit_operation_type": "ccb",
		"interest_grace_period": 0,
		"principal_grace_period": 0
	},
	"simplified": true,
	"collaterals": [{
		"percentage": 1,
		"collateral_data": {
            "reservation_type": "refinancing",
			"reservation_method": "issuing",
			"authority_code": "17000",
            "pensioner_registration_code": "",
			"registration_code": "12345678",
            "authority": {
		        "description": "teste",
		        "authority_document_number": "1234"
	        }
		},
		"collateral_type": "federal_payroll"
	}],
	"requester_identifier_key": "\<ID DE CONTROLE DO PARCEIRO\>",
	"disbursement_bank_account": {
		"name": "\<NOME DO DEVEDOR\>",
		"bank_code": "104",
		"account_type": "checking_account",
		"account_digit": "1",
		"branch_number": "3880",
		"account_number": "000736703806",
		"document_number": "\<CPF DO DEVEDOR\>",
		"transfer_method": "pix"
	},
	"purchaser_document_number": "\<CNPJ DO CESSIONÁRIO\>",
    "refinanced_credit_operations": [
        {
            "operation_key": "d2fd3f63-3d11-42a8-ab5c-9a84b5c58b6c"
        }
    ]
}

collateral_data 对象字段详情

字段	描述	值
reservation_type	预留类型	枚举值
registration_code	服务人员或养老金领取者的注册号	123456789
reservation_method	确定何时开始尝试进行代扣批注，是在创建信贷操作时还是在发行时。	枚举值

预留类型表

枚举值	描述
new_credit	新信贷
refinancing	再融资

预留创建方法表

注意

此字段非常重要，因为它直接决定何时向 Zetra 发出预留意向请求。

枚举值	描述
creation	创建信贷操作时将开始尝试批注。
issuing	发行信贷操作时（即正式化后）将开始尝试批注。

Response

ENDPOINT

/debt

MÉTODO

POST

Response Body

{
	"data": {
		"borrower": {
			"document_number": "\<CPF DEVEDOR\>",
			"name": "\<NOME DEVEDOR\>"
		},
		"collaterals": [{
			"absolute_amount": null,
			"collateral_constituted": false,
			"collateral_data": {
				"authority_code": "17000",
                "pensioner_registration_code": "",
			    "registration_code": "12345678"
			},
			"collateral_key": "5e40c191-06ae-4da2-9d4b-3c0bf6eeb1a3",
			"collateral_type": "federal_payroll",
			"created_at": "2022-11-03T20:56:09.200482",
			"external_key": "\<DEBT-KEY\>",
			"percentage": 1,
			"updated_at": "2022-11-03T20:56:09.200474"
		}],
		"contract": {
			"number": "00000000001",
			"signature_information": [{
				"signature_url": null,
				"signer_document_number": "\<CPF ASSINANTE\>",
				"signer_email": "\<EMAIL ASSINANTE\>",
				"signer_external_key": null,
				"signer_name": "\<NOME ASSINANTE\>",
				"signer_role": "issuer"
			}],
			"urls": [
				"\<LINK URL DA CCB\>"
			]
		},
		"disbursement_options": [{
				"additional_iof": 24.220242,
				"annual_cet": "26.1457%",
				"assignment_amount": 3205.12,
				"base_iof": 176.6603785598479778,
				"cet": "1,9544%",
				"contract_fee_amount": 17.68,
				"contract_fees": [{
					"amount": 17.68,
					"amount_type": "absolute",
					"fee_amount": 17.68,
					"fee_type": "spread_cip_cost"
				}],
				"disbursement_date": "2022-11-03",
				"external_contract_fee_amount": 0,
				"external_contract_fees": [],
				"first_due_date": "2022-12-07"
				"installments": [{
						"additional_costs": [],
						"business_due_date": "2022-12-07",
						"calendar_days": 34,
						"due_date": "2022-12-07",
						"due_interest": 0,
						"due_principal": 3187.44,
						"fine_amount": null,
						"has_interest": true,
						"installment_number": 1,
						"installment_status": null,
						"installment_type": null,
						"post_fixed_amount": 0,
						"pre_fixed_amount": 64.20069301315790,
						"principal_amortization_amount": 35.79930698684210,
						"tax_amount": 0.10014353287723266,
						"total_amount": 100,
						"workdays": 23
					}, <... X48>
				],
				"issue_amount": 3187.44,
				"net_external_contract_fee_amount": 0,
				"total_iof": 100.44,
				"total_pre_fixed_amount": 3225.1656904289435
			},
			{
				"additional_iof": 24.220242,
				"annual_cet": "26.0057%",
				"assignment_amount": 3205.12,
				"base_iof": 176.6603785598479778,
				"cet": "1,9544%",
				"contract_fee_amount": 17.68,
				"contract_fees": [{
					"amount": 17.68,
					"amount_type": "absolute",
					"fee_amount": 17.68,
					"fee_type": "spread_cip_cost"
				}],
				"disbursement_date": "2022-11-04",
				"external_contract_fee_amount": 0,
				"external_contract_fees": [],
				"first_due_date": "2023-01-07"
				"installments": [{
						"additional_costs": [],
						"business_due_date": "2023-01-07",
						"calendar_days": 34,
						"due_date": "2022-12-07",
						"due_interest": 0,
						"due_principal": 3187.44,
						"fine_amount": null,
						"has_interest": true,
						"installment_number": 1,
						"installment_status": null,
						"installment_type": null,
						"post_fixed_amount": 0,
						"pre_fixed_amount": 64.20069301315790,
						"principal_amortization_amount": 35.79930698684210,
						"tax_amount": 0.10014353287723266,
						"total_amount": 100,
						"workdays": 23
					}, <... X48>
				],
				"issue_amount": 3187.44,
				"net_external_contract_fee_amount": 0,
				"total_iof": 100.44,
				"total_pre_fixed_amount": 3225.1656904289435
			},
			{
				"additional_iof": 24.220242,
				"annual_cet": "25.8457%",
				"assignment_amount": 3205.12,
				"base_iof": 176.6603785598479778,
				"cet": "1,9544%",
				"contract_fee_amount": 17.68,
				"contract_fees": [{
					"amount": 17.68,
					"amount_type": "absolute",
					"fee_amount": 17.68,
					"fee_type": "spread_cip_cost"
				}],
				"disbursement_date": "2022-11-05",
				"external_contract_fee_amount": 0,
				"external_contract_fees": [],
				"first_due_date": "2022-12-07"
				"installments": [{
						"additional_costs": [],
						"business_due_date": "2022-12-07",
						"calendar_days": 34,
						"due_date": "2022-12-07",
						"due_interest": 0,
						"due_principal": 3187.44,
						"fine_amount": null,
						"has_interest": true,
						"installment_number": 1,
						"installment_status": null,
						"installment_type": null,
						"post_fixed_amount": 0,
						"pre_fixed_amount": 64.20069301315790,
						"principal_amortization_amount": 35.79930698684210,
						"tax_amount": 0.10014353287723266,
						"total_amount": 100,
						"workdays": 23
					}, <... X48>
				],
				"issue_amount": 3187.44,
				"net_external_contract_fee_amount": 0,
				"total_iof": 100.44,
				"total_pre_fixed_amount": 3225.1656904289435
			},
			{
				"additional_iof": 24.220242,
				"annual_cet": "26.1457%",
				"assignment_amount": 3205.12,
				"base_iof": 176.6603785598479778,
				"cet": "1,9544%",
				"contract_fee_amount": 17.68,
				"contract_fees": [{
					"amount": 17.68,
					"amount_type": "absolute",
					"fee_amount": 17.68,
					"fee_type": "spread_cip_cost"
				}],
				"disbursement_date": "2022-11-06",
				"external_contract_fee_amount": 0,
				"external_contract_fees": [],
				"first_due_date": "2022-12-07"
				"installments": [{
						"additional_costs": [],
						"business_due_date": "2022-12-07",
						"calendar_days": 34,
						"due_date": "2022-12-07",
						"due_interest": 0,
						"due_principal": 3187.44,
						"fine_amount": null,
						"has_interest": true,
						"installment_number": 1,
						"installment_status": null,
						"installment_type": null,
						"post_fixed_amount": 0,
						"pre_fixed_amount": 64.20069301315790,
						"principal_amortization_amount": 35.79930698684210,
						"tax_amount": 0.10014353287723266,
						"total_amount": 100,
						"workdays": 23
					}, <... X48>
				],
				"issue_amount": 3187.44,
				"net_external_contract_fee_amount": 0,
				"total_iof": 100.44,
				"total_pre_fixed_amount": 3225.1656904289435
			}
		],
		"iof_charge_method": "financed",
		"requester_identifier_key": "3ed0744d-1f35-4688-aa65-739b8a3f9e89"
	},
	"event_datetime": "2022-11-07 13:54:58",
	"key": "\<DEBT-KEY\>",
	"status": "waiting_signature",
	"webhook_type": "debt"
}

录入提案后，批注流程启动：批注成功后，合作伙伴将收到以下 webhook：

待同意 Webhook

注意

此字段非常重要。我们有 pending_consent 状态和 pending_consent_with_deletion 状态（由尝试取消处于 pending_consent 状态的预留引起），两者均只能通过同意接受、拒绝或同意到期（10天后）来结束预留并释放边际。尝试取消尚未同意的预留将导致"预留未找到"错误，因为该预留尚未在 SIAPE 系统中正式化。

WEBHOOK_TYPE

credit_operation.collateral

STATUS

Pending Consent

Body

{
	"key": "\<DEBT-KEY\>",
	"data": {
        "collateral_data": {
			"reservation_status": "pending_consent"
		},
		"collateral_type": "federal_payroll",
		"collateral_constituted": false
	},
	"event_time": "2022-10-31 15:23:46",
	"webhook_type": "credit_operation.collateral"
}

批注 Webhook

债务人在服务人员门户确认合同同意并确认边际批注后，合作伙伴将收到以下 webhook：

WEBHOOK_TYPE

credit_operation.collateral

STATUS

Success

Body

{
	"key": "\<DEBT-KEY\>",
	"data": {
		"collateral_type": "federal_payroll",
		"collateral_constituted": true
	},
	"event_time": "2022-10-31 15:23:46",
	"webhook_type": "credit_operation.collateral"
}

5. 操作正式化模型

默认情况下，QI Tech 通过 QISign 收集签名，合同在发行时发送给签署人。但合作伙伴也可以独立收集签名，并将签署文件或签名证据发送给 QI Tech 以继续操作。

以下是 QI 接受的各种模型说明：

通过 QISign 签署

通过 QI Sign 签署以自动方式在 QI Tech 平台上进行，一旦创建操作，文件即由 QI Sign 发送以收集签名，签署后操作将自动从 "waiting_signature" 状态变为 "issued"（已发行）状态。

发送已签署的 PDF

此类型表示通过 "/debt" 发行的 PDF 将被签署，并将带有已签署 PDF 的链接通过 API 4.1 发送作为认证方式。

Request

ENDPOINT

debt/[DEBT_KEY]/signed

MÉTODO

POST

Request Body

{
    "type": "pdf-signature",
    "path-pdf-signed": "https://www.google.com/"
}

Response

MÉTODO

POST

ENDPOINT

debt/[DEBT_KEY]/signed

Response Body

{
  "data": {},
  "event_datetime": "2023-01-17 17:17:28",
  "key": "4630cd58-ab00-49b3-b8cb-cb0f4a5af7a4",
  "status": "signature_received",
  "webhook_type": "debt"
}

发送签名证据

此类型表示通过 "/debt" 发行的 PDF 将通过附加在最后一页的哈希值进行签署。

通过发送签名证据进行认证可有以下 3 种类型：

Opt-in 证据：

通过 opt-in 签署意味着客户将通过合作伙伴的应用程序（前端）接受合同。

为使此签名有效，必须强制发送某些数据。

Request

ENDPOINT

debt/[DEBT_KEY]/signed

MÉTODO

POST

Request Body

{
    "type": "data-signature",
    "signatures": [
        {
            "signed_object": {
                "raw_text": "Lorem ipsum dolor sit amet, consectetur a....",
                "document_key": "79003de0-2590-455d-9b73-426b8ca284eb",
                "document_md5": "7521bd5621d97af26b2c1721fc4023a8"
            },
            "authenticity": {
                "timestamp": "1970-01-01 00:00:01",
                "ip_address": "179.104.42.245",
                "session_id": "ddb1d063-4fdf-4330-af9c-3316e9142ff3"
            },
            "signer": {
                "name": "IVANILDO DE SENA LIMA",
                "email": "ivanlima2604@gmail.com",
                "phone": {
                    "country_code": "055",
                    "area_code": "11",
                    "number": "999999999"
                },
                "document_number": "61766976204"
            },
            "authentication_type": "opt_in"
        }
    ]
}

.zip 文件证据：

通过 zip 签署包含发送确认文件，例如录音电话。

Request

ENDPOINT

debt/[DEBT_KEY]/signed

MÉTODO

POST

Request Body

{
    "type": "data-signature",
    "signatures": [
        {
            "signed_object": {
                "raw_text": "Lorem ipsum dolor sit amet, consectetur a....",
                "document_key": "79003de0-2590-455d-9b73-426b8ca284eb",
                "document_md5": "7521bd5621d97af26b2c1721fc4023a8"
            },
            "authenticity": {
                "timestamp": "1970-01-01 00:00:01",
                "document_key": "\<DOCUMENT-KEY DO ARQUIVO .ZIP\>",
                "document_md5": "\<HASH MD5 DO ARQUIVO .ZIP ENVIADO\>"
            },
            "signer": {
                "name": "IVANILDO DE SENA LIMA",
                "email": "ivanlima2604@gmail.com",
                "phone": {
                    "country_code": "055",
                    "area_code": "11",
                    "number": "999999999"
                },
                "document_number": "61766976204"
            },
            "authentication_type": "zip"
        }
    ]
}

通过_自拍照_发送证据：

通过自拍照认证适用于使用 QI Tech CaaS 服务的合作伙伴，其中自拍照认证经过验证后将生成一个确认 ID。

Request

ENDPOINT

debt/[DEBT_KEY]/signed

MÉTODO

POST

Request Body

{
    "type": "data-signature",
    "signatures": [
        {
            "signed_object": {
                "raw_text": "Lorem ipsum dolor sit amet, consectetur a...."
            },
            "authenticity": {
                "timestamp": "1970-01-01 00:00:01",
                "facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb"
            },
            "signer": {
                "name": "IVANILDO DE SENA LIMA",
                "email": "ivanlima2604@gmail.com",
                "phone": {
                    "country_code": "055",
                    "area_code": "11",
                    "number": "999999999"
                },
                "document_number": "61766976204"
            },
            "authentication_type": "selfie"
        }
    ]
}

Response

MÉTODO

POST

ENDPOINT

debt/[DEBT_KEY]/signed

Response Body

{
  "data": {},
  "event_datetime": "2023-01-17 17:17:28",
  "key": "4630cd58-ab00-49b3-b8cb-cb0f4a5af7a4",
  "status": "signature_received",
  "webhook_type": "debt"
}

信息

所有通过 debt/[DEBT_KEY]/signed 端点执行的操作的 Response 均相同。

6. 取消和解除批注：

要永久取消操作并解除可扣除边际批注，应使用以下端点：

Request

ENDPOINT

/debt/[DEBT-KEY]/cancel_permanently

MÉTODO

POST

操作取消完成后，合作伙伴将收到以下 webhook：

Webhook

WEBHOOK_TYPE

debt

STATUS

Canceled Permanently

Body

{
	"key": "\<DEBT-KEY\>",
	"data": {},
	"status": "canceled_permanently",
	"webhook_type": "debt",
	"event_datetime": "2022-11-01 03:46:31"
}

7. 放款

如果操作已批注、已签署且放款日期为当天，则将进入放款流程。

成功案例

放款成功后，合作伙伴将收到以下 webhook：

Webhook

WEBHOOK_TYPE

debt

STATUS

Disbursed

Body

{
	"key": "\<DEBT-KEY\>",
	"data": {
		"installments": [],
		"ted_receipt_list": [{
			"fee": 0,
			"url": "\<URL COMPROVANTE DE TRANSFERÊNCIA\>",
			"amount": 247.66,
			"origin": {
				"name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
				"type": "payment_account",
				"branch": "0001",
				"document": "32402502000135",
				"bank_code": "329",
				"account_key": "5d068423-6094-49e4-b15b-7740038295a8",
				"branch_digit": null,
				"account_digit": "5",
				"account_branch": "0001",
				"account_number": "00002"
			},
			"timestamp": "2022-12-14T22:30:17",
			"description": "000000 0299 000011222-8 88250032934 - SUELI SIRLENE ARNDT PIAIA",
			"destination": {
				"name": "\<NOME DEVEDOR\>",
				"type": "checking_account",
				"branch": "3880",
				"purpose": "Crédito PIX em Conta",
				"document": "\<CPF DEVEDOR\>",
				"bank_ispb": "00360305",
				"branch_digit": null,
				"account_digit": "1",
				"account_number": "000736703806"
			},
			"end_to_end_id": "E32402502202212142230TY1329KNRW4",
			"transaction_key": "7f0d5b3e-aa8e-4ecf-aba4-f92593e48c95",
			"origin_transaction_key": "360fad13-f58c-442d-a771-42372ffb47d3"
		}]
	},
	"status": "disbursed",
	"webhook_type": "debt",
	"event_datetime": "2022-12-14 22:30:19"
}

TED 失败案例

Webhook

WEBHOOK_TYPE

debt

STATUS

Canceled

Body

 {
 	"status": "canceled",
 	"key": "\<DEBT-KEY\>",
 	"data": {
 		"ted_refusal": {
 			"transaction_key": "16faabfc-3876-437d-a4f6-aae17a1d68c9",
 			"description": "341 0000 000000-7 12345678900 - NOME BENEFICIÁRIO",
 			"origin": {
 				"account_key": "a1d2dea5-fa90-4676-a125-da355fdc3ed0",
 				"account_number": "00086",
 				"bank_code": "329",
 				"name": "ACCOUNT TRANSITORY",
 				"type": "payment_account",
 				"document": "32402502000135",
 				"branch_digit": null,
 				"account_digit": "8",
 				"branch": "0001"
 			},
 			"fee": 0,
 			"reason_enumerator": "agencia_conta_invalida",
 			"timestamp": "2022-11-07T14:36:05",
 			"amount": 483.6,
 			"reason": "Agência ou Conta Destinatária do Crédito Inválida",
 			"destination": {
 				"branch": "0000",
 				"account_number": "000000",
 				"name": "NOME BENEFICIÁRIO",
 				"purpose": "Crédito em Conta",
 				"type": "checking_account",
 				"branch_digit": null,
 				"document": "12345678900",
 				"bank_code": "341",
 				"account_digit": "7"
 			}
 		},
 		"cancel_reason": "ted_refusal"
 	}
 }

PIX 失败案例

Webhook

WEBHOOK_TYPE

debt

STATUS

Canceled

Body

{
        "webhook_type": "debt",
        "data": {
          "pix_refusal": {
            "reason_enumerator": "invalid_document_number",
            "reason": "CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino."
          },
          "cancel_reason": "pix_refusal"
        },
        "status": "canceled",
        "key": "\<DEBT-KEY\>",
        "event_datetime": "2022-11-07 15:29:37"
      }

8. 重试操作放款

Request

ENDPOINT

/debt/[DEBT-KEY]/change_disbursement_date

MÉTODO

POST

Request Body

{
    "disbursement_date": "2022-11-04",
    "disbursement_bank_accounts": [
        {
            "account_branch": "1232",
            "account_digit": "4",
            "account_number": "412412412",
            "account_type": "checking_account",
            "document_number": "\<CPF BENEFICIÁRIO\>",
            "financial_institutions_code_number": 184,
            "ispb": "17298092",
            "name": "\<NOME BENEFICIÁRIO\>",
            "percentage_receivable": 100,
        }
    ]
}

Response

ENDPOINT

/debt/[DEBT-KEY]/change_disbursement_date

MÉTODO

POST

Response Body

{
    "disbursement_accounts": [
        {
            "account_branch": "1232",
            "account_digit": "4",
            "account_number": "412412412",
            "account_type": "checking_account",
            "amount_receivable": null,
            "created_at": "2022-05-24T14:51:46",
            "digitable_line": null,
            "disbursement_type": "ted",
            "document_number": "37197645832",
            "financial_institutions": {
                "code_number": 184,
                "ispb": 17298092,
                "name": "BCO ITAÚ BBA S.A."
            },
            "financial_institutions_code_number": 184,
            "is_pix_disbursement": false,
            "ispb": "17298092",
            "name": "Márcio e Catarina Gráfica Ltda",
            "percentage_receivable": 50.0,
            "pix_key": null,
            "pix_transfer_key": null,
            "pix_type": null,
            "qr_code_key": null,
            "retry_counter": 0,
            "retry_vector": null,
            "transaction_key": null,
            "webhook_key": null
        },
    ],
    "disbursement_date": "2022-11-04"
}

9. 枚举值

Employment Relationship 枚举

枚举值	描述
attendant	公务员
pensioner	养老金领取者

Employment Classification 枚举

枚举值	描述
stable	与雇主机构具有稳定的功能关系
temporary	与雇主机构具有非稳定的功能关系（临时）
comissioned	委任职位

10. 获取最后请求的响应

last response 是一种简单直接地映射 QI 与 SIAPE/SIGEPE 之间通信响应的方式，能够了解请求的时间和获得的返回（通过枚举值）。枚举值直接与 SIAPE/SIGEPE 的返回代码相关，分为两种形式："errors" 和 "success"。

每个枚举值都有详细描述和 SIAPE/SIGEPE 的参考代码。以下我们将更详细地了解 last response 数据的展示方式。

成功案例

Request

ENDPOINT

/debt/[DEBT-KEY]/collateral

MÉTODO

GET

Response

Response Body

{
  "collateral_constituted": true,
  "collateral_type": "federal_payroll",
  "updated_at": "2023-05-24 19:13:02",
  "collateral_data": {
    "authority_code": "57202",
    "registration_code": "0928033",
    "pensioner_registration_code": "",
    "status": "reserved",
    "last_response": {
      "success": [
        {
          "enumerator": "succesfully_included"
        }
      ]
    },
    "last_response_event_datetime": "2023-05-22T19:13:02Z"
  }
}

枚举值表

枚举值	描述	详情
successfully_reserved	Reservation made successfully	与 SIAPE 批注确认相关的状态
successfully_included	Inclusion has been successfully done	与 SIAPE 成功录入相关的状态

错误案例

此主题枚举值表中映射的案例可能导致预留被取消，或在仍有放款选项时重新尝试。

Request

ENDPOINT

/debt/[DEBT-KEY]/collateral

MÉTODO

GET

Response

Response Body

{
  "collateral_constituted": false,
  "collateral_type": "federal_payroll",
  "updated_at": "2023-05-24 19:13:02",
  "collateral_data": {
    "authority_code": "57202",
    "registration_code": "0928033",
    "pensioner_registration_code": "",
    "status": "canceled",
    "last_response": {
      "success": [
        {
          "enumerator": "invalid_balance"
        }
      ]
    },
    "last_response_event_datetime": "2023-05-22T19:13:02Z"
  }
}

枚举值表

枚举值	描述	QI 操作
deletion_request	Deletion was requested before the reservation was completed	取消操作
consent_refused	Consent was refused by the borrower	取消操作
invalid_balance	There is no balance available for the reservation requested	取消操作
invalid_value_FIELD	Parameter filled with a field that has an invalid value mapped in the 附件 2	取消操作
document_number_does_not_match_other_information	Document number does not match other information provided	取消操作
consent_expired	The consent period has elapsed, and the contract has been voided by SIAPE	取消操作
waiting_for_origin_contract_closure	Waiting for origin contract to be finalized	继续重试
origin_contract_not_found	Origin contract number not found	取消操作
contract_not_found	Contract number not found	取消操作
unauthorized_institution	Institution isn't authorized by the client	最多重试 7 天。合作伙伴应联系客户并引导其授权 QI
expired_portability	Portability took more than 10 days to confirm	重新提交合同意向

11. 附件

附件 1

代码	描述
ANS03, CLT03, EST03	TRANSFERRED/REQUESTED
ANS08, CLT08, EST08, RMI08	TRANSFERRED
ANS09, CLT09, EST09	REDISTRIBUTED
ANS21	PERMANENT ACTIVE LAW 8878/94
ANS36	PUBLIC AMNESTY L10559
ANS37	PRIVATE AMNESTY L10559
ANS46	PUBLIC INSTITUTIONAL AMNESTY
ANS47	PRIVATE INSTITUTIONAL AMNESTY
ANS56	PARTIAL AMNESTY
ANS57	PARTIAL INSTITUTIONAL AMNESTY
CDT12, CDT40	TEMPORARY CONTRACT
CDT49, CLT49	TEMPORARY CONTRACT CLT
CDT52	SUBSTITUTE PROFESSOR CONTRACT
CDT53	VISITING PROFESSOR CONTRACT
CDT54	TEMPORARY PROFESSOR CONTRACT
CDT55	PROFESSOR/MEDICAL TUTOR CONTRACT
CDT72	TEMPORARY RETIREE
CDT73	CDT
CDT76	TEMPORARY ECONTRACT
CDT77	EXERC. DESCEN. CDT
CDT81	EMERGENCY AGU CDT
CLT04, EST04	APPOINTED TO A COMMISSIONED POSITION
CLT05, MRD05, NES05, PMM05, RMP05	NO LINK
CLT06, EST06	CLERK (SPECIAL/EMERGENCY)
CLT11, EST11	EXCESS OF ALLOCATION
CLT14, EST14	REQUEST FROM OTHER AGENCIES
CLT16, EST16	MILITARY REQUEST MILITARY
CLT20	CLT EMPLOYEE
CLT23	CLT EMPLOYEE/ EMPLOYEE
CLT24	CLT FIXED-TERM CONTRACT
CLT25	CLT ANS JUDICIAL DECISION
CLT26	CLT REQUIRED
CLT27	CLT ANS JUDICIAL TRANSFERRED
CLT28, EST65	APPOINTED TO POSITION
CLT29	CLT-PENSION SUPPLEMENT
CLT30	CLT-PENSION JUDICIAL DECISION
CLT31, EST31	INSTITUTION PENSION JUDICIAL DECISION
CLT32	PUBLIC EMPLOYMENT
CLT43	CLT ANS - DECREE 6657/08
CLT44, EST44	EXERCISE - SECTION 7, ARTICLE 93, LAW 8112
CLT48	CELETISTA JUDICIAL DECISION
CLT50	PCC EMPLOYMENT/EX-RO
CLT61	REQ. §6, 93, 8112/9012
CLT62	TRANSFERRED §6 8112/90
CLT69	APPRENTICE
CLT75	TRANSFERRED STATE CITY
CLT79, EST79	INTERIM
CLT83	SERPRO EMPLOYEE
EST01, RMI01	PERMANENT ACTIVE
EST02, RMI02	RETIRED
EST07, NES07	SPECIAL NATURE
EST10	TRANSITIONAL ACTIVE
EST13	ON AVAILABILITY
EST15, RMI15	PENSION INSTITUTOR
EST17	RETIRED - TCU733/94
EST18	DECENTRALIZED CAREER EXERCISE
EST19	PROVISIONAL EXERCISE
EST22	GRANTED AMNESTY
EST35	MILITARY REQUISETION
EST38	ACTIVE - JUDICIAL DECISION
EST39	RETIRED - JUDICIAL DECISION
EST41	COLLABORATOR PCCTAE AND MAGISTERIUM
EST42	ICT COLLABORATOR
EST45	TRASFERRED - SUS/LAW 8270
EST58	COMPLEMENTARY RETIREMENT VIFER
EST78	DESCENT EXERCISE - PGFN
EST96	QE/MRE - TRANSFERRED
EST97	SPECIAL FRAME - QE/MRE
EST98	EXCESS TO STAFFING - MRE
ETE68	COMPANY INTERN
ETG66	SIAPECAD INTERN
ETG67	PGFN INTERN
ETG70	INTERN (SIGEPE)
MRD71, PMM71, RMC71, RMP71	FOREIGN INTERNSHIP
NES59	CARF COUNSELOR
NES60	MILITARY PENSION BENEFICIARY
NES84, NES99	PENSIONER
NES91	INDEMNITY BENEFICIARY ANS57
NES92	MONTEPIO PENSION BENEFICIARY
NES93	PENSION BENEFICIARY
NES94	INDEMNITY BENEFICIARY ANS46
NES95	INDEMNITY BENEFICIARY ANS47
RMI33	CBM/PM REFORM
RMI34	CBM/PM RESERVE
RMI51	DISCIPLINARY EXCLUSION
RMI63	AGGREGATED - MILITARY
RMI64	TEMPORARY FUNCTION - FORMER EMPLOYEE

附件 2

SIAPE 返回字段	字段映射
MATRICULA DO INSTITUIDOR	pensioner_registration_code
CPF DO SERVIDOR	document_number
CPF DO PENSIONISTA	document_number
CODIGO DO ORGAO	authority_code
MATRICULA DO SERVIDOR	registration_code
MATRICULA DO PENSIONISTA	registration_code
VALOR DE DESCONTO MENSAL	reservation_amount
PRAZO EM MESES DE DESCONTO	reservation_period
NUMERO DO CONTRATO	contract_number
VALOR BRUTO DA OPERACAO	total_amount
VALOR LIQUIDO CREDITADO AO SERVIDOR	disbursed_amount
VALOR LIQUIDO CREDITADO AO PENSIONISTA	disbursed_amount
TAXA DE JUROS MENSAL DO CONTRATO	monthly_interest_rate
VALOR DO IOF COBRADO	iof
CUSTO EFETIVO ANUAL DO CONTRATO	cet
DATA DE INACIO DO PROCESSO DE PORTABILIDADE	start_date
NUMERO DO CONTRATO ALVO DA PORTABILIDADE	origin_contract_number

1. 成功或失败场景的模拟​

查询余额和批注的成功场景​

查询余额的失败场景​

2. 查询可扣除边际​

Request​

Response​

查询成功​

Federal Payroll Balance 字段定义​

查询失败​

3. 模拟代扣贷款​

Request​

Response​

4. 发行代扣贷款​

Request​

collateral_data 对象字段详情​

预留类型表​

预留创建方法表​

Response​

待同意 Webhook​

批注 Webhook​

5. 操作正式化模型​

通过 QISign 签署​

发送已签署的 PDF​

Request​

Response​

发送签名证据​

Opt-in 证据：​

Request​

.zip 文件证据：​

Request​

通过_自拍照_发送证据：​

Request​

Response​

6. 取消和解除批注：​

Request​

Webhook​

7. 放款​

成功案例​

Webhook​

TED 失败案例​

Webhook​

PIX 失败案例​

Webhook​

8. 重试操作放款​

Request​

Response​

9. 枚举值​

Employment Relationship 枚举​

Employment Classification 枚举​

10. 获取最后请求的响应​

成功案例​

Request​

Response​

枚举值表​

错误案例​

Request​

Response​

枚举值表​

11. 附件​

附件 1​

附件 2​

1. 成功或失败场景的模拟

查询余额和批注的成功场景

查询余额的失败场景

2. 查询可扣除边际

Request

Response

查询成功

Federal Payroll Balance 字段定义

查询失败

3. 模拟代扣贷款

Request

Response

4. 发行代扣贷款

Request

collateral_data 对象字段详情

预留类型表

预留创建方法表

Response

待同意 Webhook

批注 Webhook

5. 操作正式化模型

通过 QISign 签署

发送已签署的 PDF

Request

Response

发送签名证据

Opt-in 证据：

Request

.zip 文件证据：

Request

通过_自拍照_发送证据：

Request

Response

6. 取消和解除批注：

Request

Webhook

7. 放款

成功案例

Webhook

TED 失败案例

Webhook

PIX 失败案例

Webhook

8. 重试操作放款

Request

Response

9. 枚举值

Employment Relationship 枚举

Employment Classification 枚举

10. 获取最后请求的响应

成功案例

Request

Response

枚举值表

错误案例

Request

Response

枚举值表

11. 附件

附件 1

附件 2