跳到主要内容

军队代扣贷款手册 - 新信用

注意！

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

Webhook 重发

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

军队系统运作方式

军队代扣系统通过 API 每天24小时、每周7天运行，包括节假日。

1. 授权​

在发送任何军队代扣请求（查询、债务发行等）之前，必须先上传军人授权同意书，授权 QI 进行查询、背书及薪资表维护操作。 上传授权书，请按照文档上传章节中的步骤进行操作。

上传后，返回字段 "document_key" 中会返回一个唯一密钥，该密钥需要在可扣额度查询请求 payload 的 "authorization_document_key" 字段中发送，详见 2. 可扣额度查询。

2. 在 Sandbox 中模拟余额查询和背书的成功场景​

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

document_numberregistration_code
45507529710146254221
10945455038146262711
14081064180026403232

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

3. 可扣额度查询​

持有军人的 CPF 和 军籍号码 后，合作伙伴可通过以下端点查询军人的可扣额度：

Request​

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

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

Request Body 参数说明​

字段类型描述
document_numberstring军人的 CPF。
registration_codestring军人的军籍号码。
authorization_document_keyuuid授权书的 document_key。
tokenstring身份验证令牌。

Response​

ENDPOINT
/military_payroll/balance
MÉTODO
POST
STATUS
201
Response Body
{
	"balance_key": "81da8afb-e1b2-4215-8093-c4b5feab8a9f",
	"status": "pending_search"
}

查询额度的数据将通过 webhook 返回。

Response Body 参数说明​

字段类型描述
balance_keystring可扣额度查询的识别密钥。
statusenum可扣额度查询状态枚举值。

可扣额度查询状态枚举值​

枚举值描述
pending_search可扣额度查询等待军队系统响应中。
failed可扣额度查询失败。
succeeded可扣额度查询成功。

查询成功​

成功 webhook 将按以下方式返回：

WEBHOOK_TYPE
military_payroll.balance
STATUS
succeeded
Body
{
	"webhook_type": "military_payroll.balance.status_change",
	"key": "81da8afb-e1b2-4215-8093-c4b5feab8a9f",
	"event_datetime": "2023-05-28T08:43:29Z",
	"status": "succeeded",
	"data": {
		"military_unit": "Exército Brasileiro",
		"military_branch": "AMAN",
		"category": "INATIVO - IND.: 3 (REFORMADO POR DECISAO JUDICIAL)", 
		"name": "Jose da silva",
		"document_number": "45507529710",
		"registration_code": "146254221",
		"birth_date": "1993-04-17",
		"grant_date": "2015-02-21",
		"balance": 8750.0,
        "allowed_installment_numbers": 24
	}
}

Response Body 参数说明​

字段类型描述
webhook_typestringwebhook 类型。
keyuuidwebhook 的参考密钥。此处为 balance_key。
event_datetimestringwebhook 发送的日期和时间。
statusenum可扣额度查询状态。
military_unitstring军人在 eConsig 系统中注册的机构。选项："Exército brasileiro"、"Sistema de Retribuição do Exterior"。
military_branchstring军人所属军事机关/组织。完整的可能机关列表见下方表格。
categorystring军人类别。完整的可能类别列表见下方表格。
namestring军人姓名。
document_numberstring军人的 CPF。
registration_codestring军人的军籍号码。
birth_datestring军人的出生日期。
grant_datestring军人的入职日期。
balancestring可用于申请代扣贷款的额度。
allowed_installment_numbersstring所查询军人代扣贷款的最大分期数。
表格 "military_branch"
MILITARY_BRANCH
7 B E CNST
CMDO FRON-ACRE/4 BIS
59 B I MTZ
54 BIS
4 B AV EX
CECMA
4 CGEO
C I G S
C M M
CMDO 12 RM
CMDO 2 GPT E
CMDO CMA
CRO/12
H GU TABATINGA
H MIL A MANAUS
21 CIA E CNST
10 CIA E CMB
CMDO FRON SOLIMOES/8 BIS
CMDO 22 BDA INF SL
4 B E CNST
35 B I
1 CIA INF
6 BPE
19 B C
CMDO 6 RM
6 D SUP
H GE SALVADOR
PQ R MNT/6
40 BI
23 B C
B ADM AP GU F
C M F
CMDO 10 RM
10 D SUP
H GE FORTALEZA
PQ R MNT / 10
1 R C GD
11 G A AAE
16 B LOG
2 CGEO
3 ESQD C MEC
32 G A C
B G P
B P E B
C M B
CMDO 11 RM
CRO/11
D E C
DECEX
COEX
D G P
11 D SUP
PQ R MNT/8
D C T
C M C
CMCG
23 ESQD C SL
P M B
GRAF EX - EGGCF
CMR
E M E
GAB CMT EX
H MIL A BRASILIA
S E F
S G EX
CITEX
38 B I
58 B I MTZ
B ADM/CMDO OP ESP
CMDO 3 BDA INF MTZ
23 CIA E CMB
41 B I MTZ
50 BIS
24 BIS
2 B FV
12 BIL MTH
4 CIA COM L MTH
CMJF
CMDO 4ª BDA INF L MTH
4 B E CMB
CMDO 4 RM
55 BI
14 G A C
11 B I MTH
4 G A AAE
ESSA
3 BIS
H GU JOÃO PESSOA
17 B FRON
CMDO 18 BDA INF FRON
47 BI
B ADM AP/CMP
CMDO 4 BDA C MEC
4 CIA ENG CMB MEC
9 GAC
11 R C MEC
2 CIA FRON
CMDO FRON JAURU/66 B I MTZ
44 B I MTZ
9 B E CNST
CMDO 13 BDA INF MTZ
18 GAC
51 BIS
2 BIS
8 D SUP
H GE BELEM
53 BIS
H GU MARABÁ
CMDO 23 BDA INF SL
8 B E CNST
16o. R C MEC
31 B I MTZ
B ADM GU JP
71 BI MTZ
14 BI MTZ
3 CGEO
7o. GAC
7ª CIA COM
72 BI MTZ
14 B LOG
B ADM QGEX
4o. B COM
7ª ICFEX
CPOR/RECIFE
B ADM AP/5 RM
B ADM AP/CMN
7 D SUP
H MIL A RECIFE
PQ R MNT/7
3 B E CNST
2 BE CNST
25 BC
30 B I MEC
3 RCC
CMDO 15 BDA INF MEC
20 BIB
27 B LOG
5 B LOG
5 CIA COM BLD
CRO/8
5 ESQD C MEC
5 GAC/AP
CMDO 5 RM
CRO/5
5 B SUP
H GE CURITIBA
PQ R MNT/5 RM/DE
BA ADM CURADO
34 B I MEC
15 CIA INF MTZ
26 GAC
15 GAC AP
15 CIA ENG CMB
13 BIB
CMDO 5 BDA CAV BLD
5 RCC
2 CIA INF
C A EX
BA AP LOG EX/RJ
H M R
9 BIA A AAE (ES)
OCEX
CMDO AD/1 DE
POLICL MIL NITEROI
D C MUN
32 BIL MTH
AMAN
1 B COM
B ES COM
1 B ENG CMB (ES)
1 B GD
1 B I MEC-ES
1 BPE
1 GAAAE
1ª ICFEX
11 GAC
111 CIA AP MB
15 R C MEC (ES)
2 B I MTZ (ES)
2 RCG
21 GAC
25 B LOG (ES)
31 GAC (ES)
57 B I MTZ (ES)
PREF MIL ZONA SUL
A G R J
BIBLIEX
CIG
CEP / FORTE DUQUE DE CAXIAS
5 CGEO
CPOR/RJ
C T EX
C M R J
CMDO 1 BDA AAAE
CMDO GUES/9 BDA INF MTZ
BA ADM / BDA INF PQDT
CMDO 1 DE
CMDO 1 RM
CMDO CML
CRO/1
B ADM AP/1 RM
B M S A
1 D SUP
ESAO
ESACOSAAE
ECEME
CCFEX / FSJ
ESIE
ES S LOG
ESSEX
ECT
H C E
H GE RIO DE JANEIRO
I B EX
I M E
L Q F EX
BCMS
POLICL MIL P VERMELHA
POLICL MIL RIO JANEIRO
DIRETORIA DE FABRICACAO
1 ESQD C L
1 B E CNST
16o. BI MTZ
B ADM GU N
7o. BE CMB
CMDO 7ª BDA INF MTZ
H GU NATAL
CMDO FRON RONDONIA/6 BIS
5 BE CNST
CMDO 17 BDA INF SL
17ª BA LOG
H GU PORTO VELHO
CMDO FRON-RORAIMA/7 BIS
6 B E CNST
10 B LOG
12 B E BLD
12 CIA COM MEC
6 RCB
H GU ALEGRETE
6 B COM
3o. B LOG
3o. R C MEC
CMDO 3 BDA C MEC
25o. GAC
H GU BAGE
13 GAC
3 B E CMB
3 B SUP
3 G A AAE
29 GAC AP
CMDO AD/3
AGGC
27 GAC
1 R C MEC
8 ESQD C MEC
16 ESQD C MEC
9 BI MTZ
CMDO 8 BDA INF MTZ
1 CGEO
12 R C MEC
18 B I MTZ
3 B COM
3 B P E
3ª ICFEX
3 R C G
8 B LOG
CPOR/PA
CMDO 3 RM
C M P A
CMDO CMS
CRO/3
H MIL A PORTO ALEGRE
POLICL MIL P ALEGRE
5 R C MEC
6 B E CMB
6 G A C
4 RCC
7 B I B
B ADM GU SM
19 R C MEC
CMDO 1 BDA C MEC
DEP SUBS SANTO ANGELO
2 R C MEC
13 CIA COM MEC
9 R C B
4 R C B
16o. GAC AP
19 BI MTZ
2 BIA A AAE
7 R C MEC
CMDO 2 BDA C MEC
23 BI
28 GAC
63 BI
CMDO 14 BDA INF MTZ
H GU FLORIANOPOLIS
62 BI
1 B FV
5 B E BLD
14 R C MEC
28 B C
20 G A C L
22 B LOG L
B ADM AP/IBIRAPUERA
B AP R BAURU
CMDO 12 BDA INF L AMV
2 B LOG L
CMDO 11 BDA INF L
ES P C EX
2 GAC L
12 GAC
37 BIL
5 BIL
2 G A AAE
4 BIL
2 B SUP
2 B E CMB
13 R C MEC
CMDO ART EX
B AP R RIBEIRAO PRETO
CMDO 1 BDA INF SL
2 BPE
3 CTA
CPOR/CMSP
CMDO 2 RM
CRO/2
2 B SUP
H MIL A SAO PAULO
2ª ICFEX
2 BIL
B AP R SOROCABA
MUSEU HISTORICO EX E FC
COUD RINCAO
CMDO 2 BDA INF SL
3 CIA INF MTZ
B AV T
23o. B LOG SI
3 BIA AAAE
C P O R/BH
15 B LOG
ES F C EX
3 CIA E CMB MEC
B ADM/C COM G E EX
AGSP
B ADM AP CMO
EASA
CMDO FRON JURUA/61 BIS
CMDO 16 BDA INF SL
H GU SGC
22 BI
C O TER
17 R C MEC
9 BE CMB
36 BI MEC
C I OP ESP
10 R C MEC
B ADM CMPL SAU RJ
MIN DEF
ESG
GSI/PR
H F A
SISTEMA DE RETRIBUIÇÃO DO EXTERIOR
ESCOLA SUPERIOR DE DEFESA
表格 "category"
CATEGORY
ATIVO
ATIVO - IND.: 1 (CARREIRA)
ATIVO - IND.: 3 (REINTEGRADO)
ATIVO - IND.: 5
ATIVO - IND.:1
ATIVO - TEMPORÁRIO
ATIVO - TEMPORÁRIO - DATA PRAÇA: DD-MM-YYYY
INATIVO
INATIVO - IND.: 1 (NA INATIVIDADE)
INATIVO - IND.: 2 (REFORMADO)
INATIVO - IND.: 3 (REFORMADO POR DECISAO JUDICIAL)
INATIVO - IND.: 4 (REFORMADO POR IDADE LIMITE)
INATIVO - IND.: 8 (ANISTIADO POLITICO)
INATIVO - IND.:1
INATIVO - IND.:2
PENSIONISTA
PENSIONISTA - IND.: 1 (JULGADA PELO TCU)
PENSIONISTA - IND.: 1 (PENSAO JULGADA PELO TCU)
PENSIONISTA - IND.: 2 (PENSAO REMETIDA E NAO JULGADA PELO TCU)
PENSIONISTA - IND.: 2 (REMETIDA E NAO JULGADA PELO TCU)
PENSIONISTA - IND.: 3 (NAO REMETIDA AO TCU)
PENSIONISTA - IND.: 3 (PENSAO NAO REMETIDA AO TCU)
PENSIONISTA - IND.: 4 (PENSAO É TERMINAL)
PENSIONISTA - IND.: 5 (PENSAO DO STM)
PENSIONISTA - IND.: 6 (PENSAO MILITAR CIVIL NIVEL INTERM.)
PENSIONISTA - IND.: 8 (PENSAO ANISTIADO POLITICO)
PENSIONISTA - IND.:1
PENSIONISTA - IND.:2
PENSIONISTA - IND.:3

查询失败​

失败 webhook 将按以下方式返回：

WEBHOOK_TYPE
military_payroll.balance
STATUS
failed
Body
{
	"webhook_type": "military_payroll.balance.status_change",
	"key": "81da8afb-e1b2-4215-8093-c4b5feab8a9f",
	"event_datetime": "2023-05-28T08:43:29Z",
	"status": "failed",
	"data": { 
		"enumerator": "military_not_found" 
	}
}

每个 enumerator 都有更详细的描述，为便于查阅，下表列出了每种情况对应的枚举值和说明。

failure_reason 枚举值​

枚举值描述Zetra 代码
invalid_registration_code提供的军籍号码无效210
military_not_found根据所提供的数据未找到任何人员293
military_blocked由于军人被封锁，查询无法完成352

4. 代扣贷款模拟​

注意

如果是再融资，代扣信贷业务的模拟应当模拟原始合同的结清，并根据可用额度和合同利率计算释放给客户的余额金额。

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": 5,
        "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": "military_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"
}

5. 代扣贷款发行​

重要

在再融资类型的请求中，必须考虑发送的是哪个集成密钥，确保其与将要发送的合同类型相对应。

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": "refinancing",
            "registration_code": "123456789",
            "reservation_method": "issuing",
            "token": "12345678"
        },
        "collateral_type": "military_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确定何时开始尝试代扣背书，是在创建信贷业务时还是在发行时。枚举值

预留类型表​

枚举值描述
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": {
                "reservation_type": "new_credit",
                "registration_code": "123456789",
                "reservation_method": "creation",
                "token": "12345678"
            },
            "collateral_key": "5e40c191-06ae-4da2-9d4b-3c0bf6eeb1a3",
            "collateral_type": "military_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​

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

6. 业务正式化模型​

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

以下是 QI 接受的每种模型描述：

通过 QISign 签名​

通过 QI Sign 签名在 QI Tech 平台上自动进行。一旦业务创建，QI Sign 将发送文件进行签名收集，签名完成后，业务将自动从"waiting_signature"状态变为"issued"（已发行）状态。

发送已签署的 PDF​

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

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 均相同。

7. 取消与解除背书：​

要对业务进行永久取消并解除可扣额度背书，请使用以下端点：

注意

值得注意的是，解除背书过程是异步的，即取消信贷业务并不一定意味着解除背书已完成。要查询解除背书状态，请参阅获取最后一次请求的响应。

注意

永久取消也可以自动发生，当业务处于"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": "military_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"
}

8. 获取最后一次请求的响应​

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

每个枚举值都有详细的描述。以下我们可以更详细地了解 last response 数据的呈现方式。

成功场景​

Request​

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

Response​

Response Body
  {
    "collateral_constituted": true,
    "collateral_type": "military_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"
    }
  }
Response Body Portability
{
    "collateral_constituted": true,
    "collateral_type": "military_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_acceptedReservation request accepted背书请求已被接受，等待确认pending_confirmation
successfully_reservedReservation made successfully预留已成功背书reserved
successfully_deletedReservation successfully deleted预留已成功解除背书deleted

错误场景​

Request​

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

Response​

Response Body
  {
    "collateral_constituted": false,
    "collateral_type": "military_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_confirmationWaiting Confirmation on Portabilityretry
communication_errorCommunication Error with Zetraretry241
consignable_margin_exccededExceeded consignable marginretry359