跳到主要内容

空军薪资代扣贷款手册

注意！

QI Tech 的 webhooks 不应以严格方式进行映射。 我们 API 返回的 webhook payload 中可能会包含额外字段。

Webhook 重发

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

空军系统运作方式

空军代扣贷款系统通过 API 运作，每周七天、每天 24 小时全天候可用，包括节假日。

1. 授权​

在提交任何空军代扣贷款请求（查询、债务发行等）之前，需要先上传军人授权同意书，授权 QI 进行查询、批注及工资扣款维护。 上传授权文件，请按照文件上传章节中的步骤进行操作。

上传后将在返回字段 "document_key" 中返回唯一密钥，该密钥需在"authorization_document_key"字段中发送于查询薪资代扣额度请求的 payload 中，详见下方**3. 查询薪资代扣额度。**

2. 在沙箱环境中模拟余额查询、合同列表查询及批注的成功场景​

出于测试目的，我们提供了一组可用于模拟沙箱中成功案例的数据，如下所示：

document_numberregistration_codetokenbirthdate
6022128463018571abc1231954-09-08
5734324140072893abc1231998-02-06
1321259069615410abc1231959-11-14

这些信息应在模拟时发送于请求的 payload 中，结果将通过相应的成功 webhook 返回。

3. 查询薪资代扣额度​

在获得 CPF、军人注册编号及授权文件密钥后，集成合作方可通过以下端点对军人的薪资代扣额度进行异步查询：

Request​

ENDPOINT
/airforce_payroll/balance
MÉTODO
POST
Request Body
{
    "document_number": "45507529710",
    "registration_code": "146254221",
    "authorization_document_key": "f2bc2369-89ea-4a80-9f64-ba7b1566cd31",
}
信息

CPF 应以文本格式填写，最多 11 个字符，不含"."、不含"-"，并在左侧以零填充。 注册编号也应以文本格式填写。

Request Body Params​

字段类型描述
document_numberstring军人的 CPF。
registration_codestring军人的注册编号。
authorization_document_keyuuid授权条款的 document_key。

Sincronous Response​

ENDPOINT
/airforce_payroll/balance
STATUS
201
Response Body
{
	"balance_key": "81da8afb-e1b2-4215-8093-c4b5feab8a9f",
	"status": "pending_search"
}

由于是异步操作，借款人薪资代扣额度查询数据将通过 webhook 返回。

Response Body Params​

字段类型描述
balance_keystring薪资代扣额度查询的标识密钥。
statusenum以下薪资代扣额度查询状态枚举值。

薪资代扣额度查询状态枚举值​

枚举值描述
pending_search薪资代扣额度查询待空军系统响应。
processed薪资代扣额度查询已处理。
信息

状态 'processed' 仅表示余额请求已有效发送并处理，但不代表请求的成功或失败，相关信息将包含在通过 Webhook 发送的 payload 中，详见下文。

成功查询​

成功 webhook 将以如下格式返回：

WEBHOOK_TYPE
airforce_payroll.balance
Body
{
	"webhook_type": "airforce_payroll.balance.status_change",
	"key": "81da8afb-e1b2-4215-8093-c4b5feab8a9f",
	"event_datetime": "2023-05-28T08:43:29Z",
	"status": "processed",
	"data": {
            "military_unit": "Aeronáutica Brasileira",
            "military_branch": "IAE",
            "category": "Ativo",
            "name": "João da Silva",
            "document_number": "12345678901",
            "registration_code": "ABC123",
            "balance": "15000.00",
            "birth_date": "1980-01-01",
            "grant_date": "2005-03-15",
            "allowed_installment_numbers": 24
     }
}

成功响应体参数​

字段类型描述
webhook_typestringWebhook 类型。
keyuuidWebhook 的参考密钥。此处指 balance_key
event_datetimestringWebhook 发送的日期和时间。
statusstring薪资代扣额度查询状态。
datajson包含查询相关数据的字段。
data.military_unitstring军人在 eConsig 系统中注册所属的机构。
data.military_branchstring军人所在的军事机关/组织。
data.categorystring军人类别。
data.namestring军人姓名。
data.document_numberstring军人的 CPF。
data.registration_codestring军人的注册编号。
data.balancestring可用于办理代扣贷款的可用额度。
data.birth_datestring军人出生日期。
data.grant_datestring军人入职日期。
data.allowed_installment_numbersstring被查询军人可办理代扣贷款的最大分期数。

查询失败​

失败 webhook 将以如下格式返回：

WEBHOOK_TYPE
airforce_payroll.balance
Body
{
    "webhook_type": "airforce_payroll.balance.status_change",
    "key": "81da8afb-e1b2-4215-8093-c4b5feab8a9f",
    "event_datetime": "2023-05-28T08:43:29Z",
    "status": "processed",
    "data": { 
            "title": "insufficient_permission",
            "description": "User Has insufficient permissions for this operation.",
            "translation": "Usuario nao possui permissoes suficientes para essa operacao.",
            "code": "ZP000329",
            "extra_fields": {} 
    }
}

每种已映射的错误类型都有标题、代码及更详细的描述。如果尚未映射，将以相同格式返回，但标题为 unknown_response。除相同字段外，下表详细描述了返回的参数。

失败响应体参数​

字段类型描述
data.titlestring发生错误的标题。
data.descriptionstring发生错误的英文详细描述。
data.translationstring错误描述的翻译。
data.codestring收到的错误代码。最后 3 位数字为 Zetra 收到的错误代码。（例如：ZP000329）
data.extra_fieldsjson用于可能的额外属性的字段。

查询薪资代扣额度请求​

如果合作方想了解已创建的 Balance 实体的进展，可以对其发起查询：

注意！

我们强烈建议使用 Webhook 作为借款人薪资代扣额度查询信息的参考依据。此功能将来可能被移除。

Request​

ENDPOINT
/airforce_payroll/balance/[balance_key]
MÉTODO
GET

Response​

ENDPOINT
/airforce_payroll/balance/[balance_key]
STATUS
200
Body
{
	"status": "processed",
	"data": {
            "military_unit": "Aeronáutica Brasileira",
            "military_branch": "IAE",
            "category": "Ativo",
            "name": "João da Silva",
            "document_number": "12345678901",
            "registration_code": "ABC123",
            "balance": "15000.00",
            "birth_date": "1980-01-01",
            "grant_date": "2005-03-15",
            "allowed_installment_numbers": 24
     }
}

4. 合同列表查询​

在获得潜在借款人的 CPF、军人注册编号及Token 后，集成合作方可通过以下端点查询可供购买的军人合同列表：

Request​

ENDPOINT
/airforce_payroll/portability_contracts_report
MÉTODO
POST
Request Body
{
    "document_number": "45507529710",
    "registration_code": "146254221",
    "token": "abc1234"
}
信息

CPF 应以文本格式填写，最多 11 个字符，不含"."、不含"-"，并在左侧以零填充。注册编号也应以文本格式填写。

Request Body Params​

字段类型描述
document_numberstring军人的 CPF。
registration_codestring军人的注册编号。
tokenstring军人的密码。

Sincronous Response​

ENDPOINT
/airforce_payroll/portability_contracts_report
STATUS
201
Response Body
{
    "portability_contracts_report_key": "3e41a8afb-e1b2-4215-8093-c4b5feab529c" ,
    "status": "pending_search"
}

由于是异步操作，借款人合同列表查询数据将通过 webhook 返回。

Response Body Params​

字段类型描述
portability_contracts_report_keystring合同列表查询的标识密钥。
statusenum合同列表查询状态枚举值。

合同列表查询状态枚举值​

枚举值描述
pending_search合同列表查询待空军系统响应。
processed合同列表查询已处理。
信息

状态 'processed' 仅表示合同列表查询请求已有效发送并处理，但不代表请求的成功或失败，相关信息将包含在通过 Webhook 发送的 payload 中，详见下文。

合同列表查询 Webhook​

成功 webhook 将以如下格式返回：

WEBHOOK_TYPE
airforce_payroll.portability_contracts_report
Body
{
    "webhook_type": "airforce_payroll.portability_contracts_report.status_change",
    "key": "3e41a8afb-e1b2-4215-8093-c4b5feab529c",
    "event_datetime": "2023-05-28T08:43:29Z",
    "status": "processed",
    "data": {
        "document_number": "45507529710",
        "contracts" : [
            {
                "econsig_id": "2361529",
                "consignatory": "BANCO XPTO", 
                "contract_date": "2022-01-03T15:01:57Z",
                "installment_amount": 10.0,
                "number_of_installments": 5,
                "number_of_paid_installments": 1,
                "contract_status":"in_progress"			
            },
            {
                "econsig_id": "2361529",
                "consignatory": "BANCO XPTO", 
                "contract_date": "2022-01-03T15:01:57Z",
                "installment_amount": 10.0,
                "number_of_installments": 5,
                "number_of_paid_installments": 1,
                "contract_status":"in_progress"			
            }
        ]
        
    }
}

Response Body Params​

字段类型描述
webhook_typestringWebhook 类型。
keyuuidWebhook 的参考密钥。此处指 balance_key
event_datetimestringWebhook 发送的日期和时间。
statusstring薪资代扣额度查询状态。
datajson包含查询相关数据的字段。
data.document_numberstring军人的 CPF。
data.contractsarray合同及其各自信息的列表。
data.contracts.econsig_idstringZetra 系统中合同的唯一标识符。
data.contracts.consignatorystring合同的代扣机构。
data.contracts.installment_amountfloat分期付款金额。
data.contracts.number_of_installmentsint合同的总分期数。
data.contracts.number_of_paid_installmentsint截至当前有效期已支付的分期数。
data.contracts.contract_statusstring合同状态。
合同可能的状态映射如下。
合同状态contract_status
"Aguard. Confirmação"waiting_confirmation
"Suspensa Pelo Gestor."suspend_by_manager
"Aguard. Liquidação"waiting_closure
"Aguard. Liquidação Portabilidade"waiting_portability_closure
"Aguard. Margem"waiting_balance
"Encerrado por Exclusão"closed_by_exclusion
"Aguard. Deferimento"waiting_approval
"Indeferida"rejected
"Deferida"accepted
"Em Andamento"in_progress
"Suspensa"suspended
"Cancelada"canceled
"Liquidada"settled
"Concluído"completed
信息

这些合同状态同样适用于内部合同的可能状态。

合同列表查询请求​

如果合作方想了解合同列表查询的进展，可以对其发起查询：

注意！

我们强烈建议使用 Webhook 作为借款人合同列表信息的参考依据。此功能将来可能被移除。

Request​

ENDPOINT
/airforce_payroll/portability_contracts_report/[portability_contracts_report_key]
MÉTODO
GET

Response​

ENDPOINT
/airforce_payroll/portability_contracts_report/[portability_contracts_report_key]
STATUS
200
Body
{
    "status": "processed",
    "data": {
        "document_number": "45507529710",
        "contracts" : [
            {
                "econsig_id": "2361529",
                "consignatory": "BANCO XPTO", 
                "contract_date": "2022-01-03T15:01:57Z",
                "installment_amount": 10.0,
                "number_of_installments": 5,
                "number_of_paid_installments": 1,
                "contract_status":"in_progress"			
            },
            {
                "econsig_id": "2361529",
                "consignatory": "BANCO XPTO", 
                "contract_date": "2022-01-03T15:01:57Z",
                "installment_amount": 10.0,
                "number_of_installments": 5,
                "number_of_paid_installments": 1,
                "contract_status":"in_progress"			
            }
        ]
        
    }
}

5. 个人信贷操作模拟​

首先需要计算清偿原始信贷操作所需的个人信贷操作金额。

原始债务的未偿余额应填写在 disbursed_amount 字段中。

注意

操作必须以 1 期分期模拟，在 D0 放款，分期付款到期日为放款日（操作支付日）后第 D+5 个工作日。

Request​

ENDPOINT
/debt_simulation
MÉTODO
POST
Request Body
{
	"borrower": {
		"person_type": "natural"
	},
	"financial": {
		"disbursed_amount": 80492.95,
		"monthly_interest_rate": 0.03,
		"credit_operation_type": "ccb",
		"disbursement_date": "2023-03-17",
		"issue_date": "2023-03-17",
		"fine_configuration": {
			"contract_fine_rate": 0,
			"interest_base": "workdays",
			"monthly_rate": 0
		},
		"interest_grace_period": 0,
		"interest_type": "pre_price_days",
		"number_of_installments": 1,
		"principal_grace_period": 0,
		"first_due_date_delay": 5
	}
}

6. 空军薪资代扣信贷操作模拟​

本次模拟中，各字段的值将按以下方式分配：

installment_face_value = 薪资代扣额度值

disbursement_date = 模拟时刻后的第 D+5 个工作日

due_balance = 个人信贷操作模拟中返回的第 1 期 total_amount

original_deadline = 个人信贷操作的总期限（天数）（5 天）

Request​

ENDPOINT
/debt_simulation
MÉTODO
POST
Request Body
{
    "borrower": {
        "person_type": "natural"
    },
    "financial": {
        "first_due_date": "2023-06-10",
        "installment_face_value": 100.0,
        "disbursement_date": "2023-03-22",
        "number_of_installments": 96,
        "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": "airforce_payroll"
    }],
    "refinanced_credit_operations": [
        {
            "due_balance": 1250.20,
            "original_deadline": 120
        }
    ]
}

模拟中返回的 data.final_disbursement_amount 字段将是支付给客户的找零金额。


查询个人信贷操作的分期金额​

Request​

ENDPOINT
/debt?key=[DEBT-KEY]&eval_present_value=True&calculate_delay=True&calculate_spread=False
MÉTODO
GET
信息

DEBT-KEY 是操作创建响应中返回的密钥（/debt 的响应）


7. 创建债务人名下账户​

在录入提案之前，需要在 QI Tech 为债务人开立账户。

该账户将用于接收个人信贷操作的放款，以及通过银行单据（Boleto）、TED 或 PIX 支付其他银行原始债务的未偿余额。

Request​

ENDPOINT
/account
MÉTODO
POST
Request Body
{
	"is_operation_account": true,
	"account_owner": {
		"address": {
			"city": "São Paulo",
			"complement": "s/c",
			"neighborhood": "Pinheiros",
			"number": "215",
			"postal_code": "12345012",
			"state": "SP",
			"street": "Gilberto Sabino"
		},
		"birth_date": "1961-01-30",
		"document_identification": "261a8fbc-d998-4dd7-8515-ddebb212ae27",
		"is_pep": false,
		"mother_name": "Nome da Mãe do Devedor",
		"nationality": "brasileiro",
		"email": "email@email.com",
		"individual_document_number": "12345678911",
		"name": "Nome do Devedor",
		"phone": {
			"area_code": "11",
			"country_code": "055",
			"number": "900000000"
		},
		"person_type": "natural"
	}
}
参数描述
account_owner债务人数据
is_operation_account表明该账户为操作账户。

Response​

ENDPOINT
/account
MÉTODO
POST
Response Body
{
	"data": {
		"account_info": {
			"account_branch": "0001",
			"account_digit": "3",
			"account_number": "1234567",
			"financial_institution_code": "329"
		},
		"account_owner": {
			"document_number": "12345678911",
			"name": "Nome do Devedor"
		}
	},
	"event_datetime": "2023-03-21 12:30:24",
	"key": "8ff1e73f-e87b-4641-99a6-3267030c6034",
	"status": "account_pending_operation",
	"webhook_type": "account"
}
信息

/account 中返回的账户数据应作为个人信贷操作的放款账户使用

5xx 错误或超时​

在账户成功开立之前，流程不应继续。 如出现失败情况，在可能重试开户之前，应先确认账户是否确实未为客户开立。

可以通过列出特定 CPF 下已开立的账户来确认账户是否已为客户开立。

Request​

ENDPOINT
/account
MÉTODO
POST
PARAMETER
owner_document_number, requester_key
参数描述
owner_document_number债务人的 CPF
requester_key集成的内部密钥。

Response​

STATUS
200
Response Body
{
	"data": [{
		...
		"account_branch": "0001",
		...
		"account_digit": "2",
		...
		"account_key": "f600a6a9-0845-454f-b25c-a6d108ea582e",
		"account_name": "Default",
		"account_number": "1467576",
		"account_status": {
			"created_at": "2019-10-11T18:58:31",
			"enumerator": "opened",
			"translation_path": "account.AccountStatus.opened"
		},
		...
		"owner_document_number": "09080702000105",
		"owner_name": "Nome do Devedor",
		...
	}],
	"pagination": {
		"current_page": 1,
		"next_page": null,
		"rows_per_page": 100,
		"total_pages": 1,
		"total_rows": 1
	}
}
信息

以上响应 payload 中仅列出了相关读取字段。


8. 操作发行​

  • 个人信贷操作：须在 D0 放款，且仅有一期分期付款，到期日为放款后第 D+5 个工作日。
注意

发行个人信贷操作时，"financial" 对象必须与其模拟时发送的信息完全相同。

信息

个人信贷操作只能在工作日放款，且放款时间取决于原始债务未偿余额的支付方式：

  • TED：放款时间为 6:30 至 17:15
  • Boleto：放款时间为 7:00 至 22:00
  • PIX：任何时间均可（但建议在工作时间内放款，因为若操作在深夜放款，例如，PIX 入账可能因涉嫌欺诈而被拒绝）

发行个人信贷操作​

发行个人信贷操作时，需发送放款后需支付的 Boleto/TED/PIX 信息。

注意

合作方必须生成操作的内部标识密钥，并在债务发行请求的 "requester_identifier_key" 字段中发送。

示例请求​

ENDPOINT
/debt
MÉTODO
POST
Request Body
{
    "borrower": {
        "name": "Nome do Devedor",
        "email": "email@email.com",
        "phone": {
            "number": "900000000",
            "area_code": "11",
            "country_code": "055"
        },
        "address": {
            "city": "São Paulo",
            "state": "SP",
            "number": "215",
            "street": "Gilberto Sabino",
            "complement": "s/c",
            "postal_code": "12345012",
            "neighborhood": "Pinheiros"
        },
        "role_type": "issuer",
        "birth_date": "1969-05-01",
        "mother_name": "Nome da Mãe do Devedor",
        "person_type": "natural",
        "individual_document_number": "12345678911",
        "gender": "male",
        "nationality": "brasileiro",
        "is_pep": false,
        "marital_status": "married"
    },
    "financial": {
        "disbursed_amount": 80492.95,
        "annual_interest_rate": 0.20983,
        "credit_operation_type": "ccb",
        "disbursement_date": "2023-03-17",
        "issue_date": "2023-03-17",
        "fine_configuration": {
            "contract_fine_rate": 0,
            "interest_base": "workdays",
            "monthly_rate": 0
        },
        "interest_grace_period": 0,
        "interest_type": "pre_price_days",
        "number_of_installments": 1,
        "principal_grace_period": 0,
        "first_due_date_delay": 5
    },
    "simplified": true,
    "additional_data": {
        "debt_payment": [{
            "bank_slip": [{
                "digitable_line": "10495419967200010004900031456924592920008049295",
                "amount": "80492,95",
                "beneficiary": "CAIXA ECONÔMICA FEDERAL",
                "due_date": "2023-03-17"
            }],
            "funds_transfer": [],
            "pix": [],
            "financial_institution_code_number": "623"
        }],
        "issuer_account": {
            "account_digit": "0",
            "account_branch": "1234",
            "account_number": "123456",
            "financial_institution_code_number": "104"
        },
        "total_af_amount": 86186.52
    },
    "requester_identifier_key": "7ac52492-61c0-4dd6-a414-b0bf940fb7ca",
    "disbursement_bank_account": {
        "bank_code": "329",
        "account_digit": "3",
        "branch_number": "0001",
        "account_number": "1234567"
    },
    "after_disbursement_actions": [{
        "action_data": {
            "digitable_line": "10495419967200010004900031456924592920008049295"
        },
        "action_type": "bankslip_payment"
    }],
    "modality": {
        "code": "0203"
    }
}

婚姻状况枚举值​

枚举值描述
single未婚
married已婚
widower丧偶
divorced离婚

5xx 错误或超时​

如果请求返回 5xx 或超时，为了确认操作确实未在 QI 中创建，建议合作方对返回 5xx 或超时的操作进行查询。

ENDPOINT
/debt?requester_identifier_key=34427233-925d-416d-93eb-c7f5084e8359
MÉTODO
GET

如果 GET 返回 200，合作方不应重试创建操作，应继续操作流程。 如果返回 404 - Not Found，合作方应重试创建操作。

STATUS
200
Response Body
{
    "data": {
        "additional_iof": 307.166388,
        "annual_cet": "60,4731%",
        "assignment_amount": 80833.26,
        "base_iof": 33.141637696905995,
        "borrower": {
            "document_number": "12345678911",
            "name": "Nome do Devedor"
        },
        "cet": "4,0200%",
        "collaterals": [],
        "contract": {
            "external_contract_key": "351eada5-a626-404c-a3a3-f91c123270ce",
            "number": "0000000001/NDD",
            "signature_information": [{
                "signature_url": "https://sign.qitech.com.br/s/hNrwjda",
                "signer_document_number": "12345678911",
                "signer_email": "email@email.com",
                "signer_external_key": "56d105f3-a7f6-4442-95e9-71f44d2ae5fc",
                "signer_name": "Nome do Devedor",
                "signer_role": "issuer"
            }],
            "urls": [
                "https://storage.googleapis.com/live-doc-api/documents/45e5b9c0-0f56-40a8-aace-d206f72c164d/QISCD-NOME_DO_DEVEDOR-CCB-0001212121-20230317194512.pdf"
            ]
        },
        "contract_fee_amount": 0,
        "contract_fees": [],
        "external_contract_fee_amount": 0,
        "external_contract_fees": [],
        "installments": [{
            "accrual_reference_date": null,
            "additional_costs": [],
            "advanced_paid_amount": 0,
            "bank_slip_key": null,
            "business_due_date": "2023-03-22",
            "calendar_days": 5,
            "digitable_line": null,
            "due_date": "2023-03-22",
            "due_interest": 0,
            "due_principal": 80833.26,
            "fine_amount": null,
            "has_interest": true,
            "installment_history": [],
            "installment_key": "75460851-2e82-4e3d-a805-b3e55b6b31d4",
            "installment_number": 1,
            "installment_payment": [],
            "installment_status": "created",
            "installment_type": "principal",
            "original_due_principal": 80833.26,
            "original_pre_fixed_amount": 183.5073246195304,
            "original_principal_amortization_amount": 80833.26267538047,
            "original_total_amount": 81016.77,
            "paid_amount": 0,
            "paid_at": null,
            "post_fixed_amount": 0,
            "pre_fixed_amount": 183.5073246195304,
            "principal_amortization_amount": 80833.26267538047,
            "qr_code_key": null,
            "qr_code_url": null,
            "renegotiation_proposal_key": null,
            "tax_amount": 33.141637696905995,
            "total_accrual_amount": null,
            "total_amount": 81016.77,
            "total_paid_amount": 0,
            "workdays": 3
        }],
        "iof_charge_method": "financed",
        "issue_amount": 80833.26,
        "net_external_contract_fee_amount": 0,
        "number_of_installments": 1,
        "prefixed_interest_rate": {
            "annual_rate": 0.20983,
            "created_at": "2023-03-17T19:45:11",
            "daily_rate": 0.00075616,
            "interest_base": "workdays",
            "monthly_rate": 0.01599997
        },
        "requester_identifier_key": "34427233-925d-416d-93eb-c7f5084e8359",
        "total_iof": 340.31,
        "total_pre_fixed_amount": 183.5073246195304
    },
    "event_datetime": "2023-03-17 19:45:19",
    "key": "052fe83c-37f6-4339-a831-127b50566745",
    "status": "waiting_signature",
    "webhook_type": "debt"
}
信息

操作创建响应中的 "key" 字段是 DEBT-KEY，即操作在 QI 中的唯一密钥。

签名​

授权放款​

操作签名后，需要授权该操作进行放款。

ENDPOINT
/debt/[DEBT-KEY]/allow_disbursement
MÉTODO
POST
Request Body
{
    "allow_disbursement": true
}

放款​

操作签名并授权放款后，将自动进入放款流程。

放款处理完成后，合作方将收到如下 webhook：

放款成功​

WEBHOOK_TYPE
debt
STATUS
Disbursed
Webhook Body
{
    "key": "052fe83c-37f6-4339-a831-127b50566745",
    "data": {
        "installments": [{
            "due_date": "2023-03-22",
            "total_amount": 81016.77,
            "installment_key": "75460851-2e82-4e3d-a805-b3e55b6b31d4",
            "pre_fixed_amount": 183.5073246195304,
            "principal_amortization_amount": 80833.26267538047
        }],
        "ted_receipt_list": []
    },
    "status": "disbursed",
    "webhook_type": "debt",
    "event_datetime": "2023-03-17 13:20:40"
}

放款后操作​

个人信贷操作在 QI 开立的债务人账户放款后，将执行 Boleto/TED/PIX 支付，用于清偿债务人原始债务未偿余额（放款后操作）。

成功​

WEBHOOK_TYPE
after_disbursement_action_update
STATUS
Success
Webhook Body
{
    "key": "3bce3113-3644-4491-b87a-fe6551edff70",
    "data": {
        "status": "done",
        "action_key": "d25097e2-09f1-47fc-8b7f-d1988b1a7669",
        "error_data": null,
        "action_data": {
            "digitable_line": "10495419967200010004900031456924592920008049295"
        },
        "action_type": "bankslip_payment",
        "execution_data": {
            "bank_slip": {
                "payer": {
                    "name": "Nome do Devedor",
                    "document_number": "12345678911",
                    "document_number_formatted": "123.456.789-11"
                },
                "beneficiary": {
                    "name": "CAIXA ECONÔMICA FEDERAL",
                    "document_number": "00360305000104",
                    "document_number_formatted": "00.360.305/0001-04"
                },
                "payment_key": "500a496e-4cca-4b12-9dc8-254932ebbcac",
                "payment_date": "2023-03-08",
                "digitable_line": "10495419967200010004900031456924592920008049295",
                "expiration_date": "2023-03-10",
                "payment_date_formatted": "08/03/2023",
                "expiration_date_formatted": "10/03/2023",
                "financial_institution_name": "CAIXA ECONÔMICA FEDERAL",
                "financial_institution_compe_number": "104"
            },
            "origin_key": "dfac205a-bdef-4820-8608-2dc81d9e10d4",
            "transacted_at": "2023-03-08 16:07:58",
            "source_account": {
                "owner_name": "Nome do Devedor",
                "account_digit": "3",
                "account_branch": "0001",
                "account_number": "1234567",
                "owner_document_number": "12345678911",
                "financial_institution_name": "QI SCD S.A.",
                "owner_document_number_formatted": "123.456.789-11",
                "financial_institution_compe_number": 329
            },
            "source_subtype": "bank_slip_payment",
            "transaction_key": "86a4320d-a69d-4c14-8300-9a6f22d35fcb",
            "transacted_at_br": "2023-03-08 13:07:58",
            "pdf_encoded_string": "\<BASE 64 DO PDF DO COMPROVANTE\>",
            "transaction_amount": 3864.95,
            "transacted_at_formatted": "08/03/2023, 16:07:58",
            "transacted_at_br_formatted": "08/03/2023, 13:07:58",
            "transaction_amount_formatted": "R$ 3.864,95",
            "source_subtype_translation_ptbr": "Pagamento de Boleto"
        }
    },
    "webhook_type": "after_disbursement_action_update",
    "event_datetime": "2023-03-08 16:08:02"
}

放款后操作错误​

如果放款后操作付款出错，合作方将通过以下 webhook 收到通知：

WEBHOOK_TYPE
after_disbursement_action_update
STATUS
Error
Webhook Body
{
    "key": "e358e7e3-17b8-4aab-9da1-92f6b78dea00",
    "data": {
        "status": "error",
        "action_key": "e2495e5a-df32-4826-b6f0-419014d3c35a",
        "error_data": {
            "error_code": "QIT000007",
            "description": "Account blocked balance cannot be negative."
        },
        "action_data": {
            "digitable_line": "10495419967200010004900031456924592920008049295"
        },
        "action_type": "bankslip_payment",
        "execution_data": null
    },
    "webhook_type": "after_disbursement_action_update",
    "event_datetime": "2023-03-22 12:06:38"
}

放款后操作 TED 退款​

如果放款后操作中执行的 TED 被目标金融机构退回，合作方将通过以下 webhook 收到通知：

WEBHOOK_TYPE
after_disbursement_action_update
STATUS
Refused
Webhook Body
{
    "key": "f4b5c36a-2aa1-4865-9678-e5a6fa585845",
    "data": {
        "status": "refused",
        "action_key": "cf3b8809-36dc-4574-8763-3600e413cf5c",
        "error_data": {
            "code": "agencia_conta_invalida",
            "description": "Agência ou Conta Destinatária do Crédito Inválida"
        },
        "action_data": {
            "destination": {
                "name": "SILVANA RAMOS DOS SANTOS",
                "account_digit": "1",
                "account_branch": "0150",
                "account_number": "301771620",
                "document_number": "30874011884",
                "financial_institution_code_number": "237"
            },
            "transaction_amount": 3200
        },
        "action_type": "funds_transfer",
        "action_amount": 3200.0
    },
    "webhook_type": "after_disbursement_action_update",
    "event_datetime": "2023-03-23 14:46:39"
}

重试失败的放款后操作​

如果放款后操作付款出错/被退回，可通过以下端点重试：/baas/action/[ACTION-KEY]


发行空军薪资代扣信贷操作​

空军代扣信贷操作必须清偿个人信贷操作，并（如有找零）向客户释放找零金额。

Request​

ENDPOINT
/debt
MÉTODO
POST
Request Body
{
    "borrower": {
        "name": "Nome do Devedor",
        "email": "email@email.com",
        "phone": {
            "number": "900000000",
            "area_code": "11",
            "country_code": "055"
        },
        "address": {
            "city": "São Paulo",
            "state": "SP",
            "number": "215",
            "street": "Gilberto Sabino",
            "complement": "s/c",
            "postal_code": "12345012",
            "neighborhood": "Pinheiros"
        },
        "role_type": "issuer",
        "birth_date": "1969-05-01",
        "mother_name": "Nome da Mãe do Devedor",
        "person_type": "natural",
        "individual_document_number": "12345678911",
        "gender": "male",
        "nationality": "brasileiro",
        "is_pep": false,
        "marital_status": "married"
    },
    "financial": {
        "first_due_date": "2023-05-07",
        "installment_face_value": 100.0,
        "disbursement_date": "2023-03-22",
        "limit_days_to_disburse": 3,
        "number_of_installments": 72,
        "monthly_interest_rate": 0.017,
        "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": "portability",
            "portability_data":{
                "token":"hw342y1h24",
                "origin_econsig_ids": [
                    "2016587",
                    "2016588",
                    "2016589",
                ]
            },
            "registration_code": "12345678",
            "reservation_method": "creation"
        },
        "collateral_type": "airforce_payroll" 
    }],
    "requester_identifier_key": "7e000c2d-d381-470e-b233-416097504866",
    "disbursement_bank_account": {
        "bank_code": "341",
        "account_digit": "3",
        "branch_number": "1234",
        "account_number": "1234567"
    },
    "purchaser_document_number": "32402502000135",
    "modality": {
        "code": "0202"
    },
    "refinanced_credit_operations": [
        {
            "operation_key": "d2fd3f63-3d11-42a8-ab5c-9a84b5c58b6c"
        }
    ]
}

collateral_data 对象字段详情​

字段描述值
reservation_type预留类型枚举值
registration_code军人注册编号123456789
reservation_method确定何时开始尝试代扣贷款批注，是在信贷操作创建时，还是在操作发行时。枚举值
portability_data可携性数据可携性对象

预留类型枚举值表​

枚举值描述
new_credit新增信贷
portability可携性
refinancing再融资

预留创建方式枚举值表​

注意

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

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

portability_data 对象字段详情​

字段描述值
token军人提供的密码1234abcd
origin_econsig_idZetra 合同标识代码1234567
origin_econsig_idsZetra 合同标识代码列表[1234567, 1234568, 1234569]

Response​

STATUS
200
Response Body
{
    "data": {
        "borrower": {
            "document_number": "12345678911",
            "name": "Nome do Devedor",
            "related_party_key": "1fe936e7-0917-4c3d-9206-87958254fa1d"
        },
        "collaterals": [{
            "absolute_amount": null,
            "collateral_constituted": false,
            "collateral_data": {
                "reservation_type": "new_credit",
                "registration_code": "123456789"
            },
            "collateral_key": "c6006572-d66a-45f6-862d-4ecb5b9b5d2d",
            "collateral_type": "airforce_payroll",
            "created_at": "2023-03-17T20:56:09.200482",
            "external_key": "1c736cd8-a4c7-43d4-8abd-c00ed0cd6450",
            "percentage": 1,
            "updated_at": "2023-03-17T20:56:09.200474"
        }],
        "contract": {
            "number": "0000000003/NDD",
            "signature_information": [{
                "signature_url": null,
                "signer_document_number": "12345678911",
                "signer_email": "email@email.com",
                "signer_external_key": null,
                "signer_name": "Nome do Devedor",
                "signer_role": "issuer"
            }],
            "urls": [
                "https://storage.googleapis.com/live-doc-api/documents/ae66d0cd-1054-4ff5-b1d6-e03aaaa2ff1b/QISCD-NOME_DO_DEVEDOR-CCB-0000000002-20230317183044.pdf"
            ]
        },
        "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": "2023-03-22",
                "external_contract_fee_amount": 0,
                "external_contract_fees": [],
                "first_due_date": "2023-05-07",
                "installments": [{
                        "additional_costs": [],
                        "business_due_date": "2022-05-08",
                        "calendar_days": 34,
                        "due_date": "2023-05-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
                    }, 
                    ... 
                    x 96
                ],
                "issue_amount": 3187.44,
                "net_external_contract_fee_amount": 0,
                "total_iof": 100.44,
                "total_pre_fixed_amount": 3225.1656904289435
            },
            ...
            x 15
        ],
        "iof_charge_method": "financed",
        "requester_identifier_key": "f7fa079e-e02f-469f-a9ba-7a550f8f665f"
    },
    "event_datetime": "2023-03-17 13:54:58",
    "key": "23c89acf-b11b-4988-b738-a0f5ba238c33",
    "status": "waiting_signature",
    "webhook_type": "debt"
}

批注​

空军代扣信贷操作创建后，QI 将启动操作的批注流程。

批注尝试流程在操作创建时开始，并将重试至操作的最后放款选项日期。

空军代扣额度批注完成后，QI 将通过以下 webhook 通知合作方：

WEBHOOK_TYPE
credit_operation.collateral
STATUS
Success
Webhook Body
{
    "key": "23c89acf-b11b-4988-b738-a0f5ba238c33",
    "data": {
        "collateral_type": "airforce_payroll",
        "collateral_constituted": true
    },
    "event_time": "2022-10-31 15:23:46",
    "webhook_type": "credit_operation.collateral"
}

如果提供的 token 无效，我们将发送以下 webhook。如果提供的 token 已被使用且需要新 token，也会发送此 webhook。

WEBHOOK_TYPE
credit_operation.collateral
STATUS
Pending Valid Token
Webhook Body
{
    "key": "23c89acf-b11b-4988-b738-a0f5ba238c33",
    "data": {
        "collateral_type": "airforce_payroll",
        "collateral_data": {
            "reservation_status": "pending_valid_token",
            "cancel_reason": "invalid_token",
        },
        "collateral_constituted": false,
    },
    "event_time": "2022-10-31 15:23:46",
    "webhook_type": "credit_operation.collateral"
}

导致自动取消的响应​

根据 Zetra 的响应，操作将被自动取消。 发生此情况时，我们将以如下格式发送 webhook，取消原因在 "cancel_reason" 字段中说明。

WEBHOOK_TYPE
credit_operation.collateral
STATUS
Canceled
Webhook Body
{
    "data": {
        "cancel_reason": "Contrato de origem não encontrato.",
        "cancel_reason_enumerator": "airforce_payroll_portability_not_found"
    },
    "event_datetime": "2023-10-10 15:45:21",
    "key": "\<UUID \>",
    "status": "canceled",
    "webhook_type": "debt"

}

枚举值表​

枚举值描述Zetra 代码
airforce_payroll_military_not_found未找到军人。293
airforce_payroll_portability_not_found未找到原始合同。294
airforce_payroll_consignable_margin_exceeded可用额度已超出。359

可携性到期​

10 天后，Zetra 将取消等待确认的可携性申请。

因此，要重新启动可携性流程，需要提供新的有效 token。如果存在新的有效 token，提案将返回到可携性意向步骤（预留状态：pending_reservation）。但如果不存在有效 token（通常是因为发送的 token 已在之前的可携性意向中使用），提案将更新为 pending_valid_token 状态，等待发送新 token。发送新的有效 token 后，提案将正常进行可携性意向和确认流程。

将发送以下 webhook 通知此情况：

WEBHOOK_TYPE
credit_operation.collateral
STATUS
Pending Reservation/Pending Valid Token
Webhook Body
{
    "key": "23c89acf-b11b-4988-b738-a0f5ba238c33",
    "data": {
        "collateral_type": "airforce_payroll",
        "collateral_data": {
            "reservation_status": "pending_reservation" ou "pending_valid_token",
            "cancel_reason": "expired_portability",
        },
    },
    "event_time": "2022-10-31 15:23:46",
    "webhook_type": "credit_operation.collateral"
}

9. 发送新的可携性 Token​

可携性 token 为一次性使用，因此当之前的 token 被使用或 token 无效时，需要发送新的 token。

发送方式为简单调用：

Request​

ENDPOINT
/debt/[DEBT-KEY]/collateral
MÉTODO
PATCH
Request Body
    {
        "portability_data": {
            "token": "12345678"
        }
    }

成功案例​

ENDPOINT
/debt/[DEBT-KEY]/collateral
STATUS
204
Response Body - No content

错误案例​

信息

此请求只应发送 token，否则流程将返回错误

Response​

ENDPOINT
/debt/[DEBT-KEY]/collateral
STATUS
400
Response Body
    {
        "title": "Bad Request",
        "description": "Additional properties are not allowed (<campo extra> was unexpected)",
        "translation": "Schema Inválido",
        "code": "QIT000001"
    }

10. 取消与注销批注：​

要永久取消操作并注销薪资代扣额度，应使用以下端点：

注意

值得注意的是，注销批注过程是异步的，即取消信贷操作并不必然意味着注销批注已完成。要查询注销批注状态，请参阅获取最后请求的响应"。

注意

永久取消也可能自动发生，这种情况发生在操作处于 "canceled" 状态超过 7 天时。

Request​

ENDPOINT
/debt/[DEBT-KEY]/cancel_permanently
MÉTODO
POST

操作取消成功：​

操作取消完成后，合作方将收到以下 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"
}

注销批注成功​

注销批注完成后，合作方将收到以下 webhook：

WEBHOOK_TYPE
debt
STATUS
Canceled Permanently
Body
{
	"key": "\<DEBT-KEY\>",
	"data": {
        "collateral_data": {
            "reservation_status": "deleted"
        },
        "collateral_type": "airforce_payroll",
        "collateral_constituted": false
    },
    "event_datetime": "2022-11-01 03:46:31",
	"webhook_type": "credit_operation.collateral",
	"event_datetime": "2022-11-01 03:46:31"
}

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

last_response 是一种简单直观地映射 QI 与 Zetra 通信响应的方式，可以了解该请求的发起时间及获取的返回结果（通过枚举值）。

每个枚举值都有详细描述。以下将更详细地介绍 last_response 的数据呈现方式。

成功案例​

Request​

ENDPOINT
/debt/[DEBT-KEY]/collateral
MÉTODO
GET

Response​

ENDPOINT
/debt/[DEBT-KEY]/collateral
STATUS
200
Response Body
  {
    "collateral_constituted": true,
    "collateral_type": "airforce_payroll",
    "updated_at": "2023-05-24 19:13:02",
    "collateral_data": {
      "status": "reserved",
      "last_response": {
        "success": [
          {
            "enumerator": "succesfully_reserved"
          }
        ]
      },
      "last_response_event_datetime": "2023-05-22T19:13:02Z"
    }
  }
可携性或再融资响应体
{
    "collateral_constituted": true,
    "collateral_type": "airforce_payroll",
    "collateral_data": {
        "status": "reserved",
        "last_response": {
            "success": [
                {
                    "enumerator": "successfully_reserved"
                }
            ]
        },
        "last_response_event_datetime": "2023-08-09T19:25:09Z",
        "portability_data": {
            "origin_econsig_id": "2016587",
            "token": "123456"
        }       
    }
}

枚举值表​

枚举值描述详情预留状态
successfully_accepted预留请求已接受批注申请已接受，等待确认pending_confirmation
successfully_reserved预留成功预留已成功批注reserved
successfully_deleted预留已成功删除预留已成功注销批注deleted

错误案例​

Request​

ENDPOINT
/debt/[DEBT-KEY]/collateral
MÉTODO
GET

Response​

ENDPOINT
/debt/[DEBT-KEY]/collateral
STATUS
200
Response Body
  {
    "collateral_constituted": false,
    "collateral_type": "airforce_payroll",
    "updated_at": "2023-05-24 19:13:02",
    "collateral_data": {
      "status": "pending_reservation",
      "last_response": {
        "errors": [
          {
            "enumerator": "invalid_portability_token"
          }
        ]
      },
      "last_response_event_datetime": "2023-05-22T19:13:02Z"
    }
  }

枚举值表​

枚举值描述QI 操作对应 Zetra 代码
waiting_confirmation等待可携性确认retry
communication_error与 Zetra 通信错误retry241
consignable_margin_excceded超出代扣额度retry359

12. 欠款余额通知​

欠款余额通知在申请日后第 5 个工作日发生，所有通知的合同将通过 webhook 发送以下信息：

WEBHOOK_TYPE
airforce_payroll.due_balance.status_change
STATUS
processed
Response Body
{
	"webhook_type": "airforce_payroll.due_balance.status_change",
	"status": "processed",
	"event_datetime": "2024-03-12T19:23:12Z",
	"data":{
			"contract_number": "0000086715/TA",
			"payment_amount": 284.28,
			"balance_limit_date": "2024-03-12"
	}
}