Air Force Payroll Manual
QI Tech webhooks should not be mapped restrictively. Additional fields may be included in the webhook payloads returned by our APIs.
You can consult and resend webhooks by following the detailed instructions in the documentation: Webhook Resending.
The Air Force payroll system, via API, operates 24 hours a day, every day of the week, including holidays.
1. Authorization
Before sending any Air Force Payroll request (Query, Debt Issuance, etc.), it is necessary to upload the military personnel's consent authorizing QI to proceed with the query, registration and maintenance in payroll. To upload the authorization, follow the step-by-step process found in the Document Upload section
The upload will return a unique key in the return field "document_key" which should be sent in the Payroll Margin Query request payload as "authorization_document_key", as detailed below in item 3. Payroll Margin Query.
2. Simulation of Success Scenarios in Balance Queries, Contract List Query and Registrations in Sandbox
For testing purposes, we have a set of data that can be used to simulate success cases in sandbox:
| document_number | registration_code | token | birthdate |
|---|---|---|---|
| 60221284630 | 18571 | abc123 | 1954-09-08 |
| 57343241400 | 72893 | abc123 | 1998-02-06 |
| 13212590696 | 15410 | abc123 | 1959-11-14 |
This information should be sent in the request payload during simulation and the result will be sent through the corresponding success webhook.
3. Payroll Margin Query
With the CPF, Military registration number and Authorization Document Key data, the integrating partner can perform the asynchronous query of the military personnel's payroll margin through the following endpoint:
Request
Request Body
{
"document_number": "45507529710",
"registration_code": "146254221",
"authorization_document_key": "f2bc2369-89ea-4a80-9f64-ba7b1566cd31",
}
The CPF must be informed in text format, with a maximum of 11 characters, without ".", without "-" and left-aligned with zeros. The Registration must also be in text format.
Request Body Params
| Field | Type | Description |
|---|---|---|
document_number | string | Military personnel's CPF. |
registration_code | string | Military personnel's registration. |
authorization_document_key | uuid | document_key of the authorization term. |
Synchronous Response
Response Body
{
"balance_key": "81da8afb-e1b2-4215-8093-c4b5feab8a9f",
"status": "pending_search"
}
Since it's asynchronous, the borrower's margin query data will be returned via webhook.
Response Body Params
| Field | Type | Description |
|---|---|---|
balance_key | string | Payroll Margin query identification key. |
status | enum | Payroll margin query status enumerators below. |
Payroll Margin Query Status Enumerators
| Enumerator | Description |
|---|---|
pending_search | Payroll margin query pending response from the air force system. |
processed | Payroll margin query processed. |
The status 'processed' refers only to the fact that the balance request was effectively sent and processed, but does not refer to its success or failure, such information will be in the payload sent via Webhook explained below.
Successful Query
The success webhook will be returned as follows:
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
}
}
Response Body Params success
| Field | Type | Description |
|---|---|---|
webhook_type | string | Webhook type. |
key | uuid | Webhook reference key. In this case, it refers to the balance_key |
event_datetime | string | Webhook sending date and time. |
status | string | Payroll margin query status. |
data | json | Field that will contain data related to the query. |
data.military_unit | string | Establishment where the military personnel is registered in the eConsig system. |
data.military_branch | string | Military agency/organization where the military personnel is. |
data.category | string | Military personnel category. |
data.name | string | Military personnel name. |
data.document_number | string | Military personnel CPF. |
data.registration_code | string | Military personnel registration. |
data.balance | string | Available margin for payroll loan contracting. |
data.birth_date | string | Military personnel birth date. |
data.grant_date | string | Military personnel admission date. |
data.allowed_installment_numbers | string | Installment limit number for a payroll loan for the queried military personnel. |
Failed Query
The failure webhook will be returned as follows:
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": {}
}
}
Each mapped error type has a title, code and more detailed description. If it hasn't been mapped yet, we'll return in the same format but with the title unknown_response. Except for identical fields, the table below describes in detail the returned parameters.
Response body params failure
| Field | Type | Description |
|---|---|---|
data.title | string | Title referring to the error that occurred. |
data.description | string | Detailed description in English of the error that occurred. |
data.translation | string | Translation of the error description that occurred. |
data.code | string | Error code received. The last 3 digits refer to the error code received by Zetra. (ex: ZP000329) |
data.extra_fields | json | Field intended for possible extra attributes. |
Request for a Payroll Margin Query
If the partner wants to know about the progress of any created Balance entity, they can make a request for it:
We strongly recommend using the Webhook as a reference for the borrower's Payroll Margin Query information. Feature subject to future removal.
Request
Response
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. Contract List Query
With the CPF, Military registration and Token data of the potential borrower, the integrating partner can query the military personnel's contract list available for purchase through the following endpoint:
Request
Request Body
{
"document_number": "45507529710",
"registration_code": "146254221",
"token": "abc1234"
}
The CPF must be informed in text format, with a maximum of 11 characters, without ".", without "-" and left-aligned with zeros. The Registration must also be in text format.
Request Body Params
| Field | Type | Description |
|---|---|---|
document_number | string | Military personnel CPF. |
registration_code | string | Military personnel registration. |
token | string | Military personnel password. |
Synchronous Response
Response Body
{
"portability_contracts_report_key": "3e41a8afb-e1b2-4215-8093-c4b5feab529c" ,
"status": "pending_search"
}
Since it's asynchronous, the borrower's contract list query data will be returned via webhook.
Response Body Params
| Field | Type | Description |
|---|---|---|
portability_contracts_report_key | string | Contract list query identification key. |
status | enum | Contract list query status enumerators. |
Contract List Query Status Enumerators
| Enumerator | Description |
|---|---|
pending_search | Contract list query pending response from the air force system. |
processed | Contract list query processed. |
The status 'processed' refers only to the fact that the contract list query request was effectively sent and processed, but does not refer to its success or failure, such information will be in the payload sent via Webhook explained below.
Contract List Query Webhook
The success webhook will be returned as follows:
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
| Field | Type | Description |
|---|---|---|
webhook_type | string | Webhook type. |
key | uuid | Webhook reference key. In this case, it refers to the balance_key |
event_datetime | string | Webhook sending date and time. |
status | string | Payroll margin query status. |
data | json | Field that will contain data related to the query. |
data.document_number | string | Military personnel CPF. |
data.contracts | array | List of contracts and their respective information. |
data.contracts.econsig_id | string | Contract unique identifier in the Zetra system. |
data.contracts.consignatory | string | Contract consignatory. |
data.contracts.installment_amount | float | Installment amount. |
data.contracts.number_of_installments | int | Total number of contract installments. |
data.contracts.number_of_paid_installments | int | Number of installments paid up to the current term. |
data.contracts.contract_status | string | Contract status. |
The possible Contract Statuses are mapped here.
| Contract Status | 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 |
These contract statuses also refer to the possible statuses of internal contracts.
Request for a Contract List Query
If the partner wants to know about the progress of a Contract List Query, they can make a request for it:
We strongly recommend using the Webhook as a reference for the borrower's Contract List information. Feature subject to future removal.
Request
Response
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. Personal Credit Operation Simulation
First, it's necessary to calculate the value of the Personal Credit operation needed to settle the original credit operation.
The outstanding balance value of the original debt must be informed in the disbursed_amount field.
The operation must be simulated with only 1 installment, disbursement on D0 and the installment must have its due date for D+5 business days, counted from the operation disbursement (payment) date.
Request
{
"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. AIR FORCE Payroll Credit Operation Simulation
In this simulation the informed fields will have their values assigned as follows:
installment_face_value = Payroll margin value
disbursement_date = D+5 business days from the simulation moment
due_balance = total_amount of the 1st installment returned in the Personal Credit Operation simulation
original_deadline = Total deadline in days of the Personal Credit Operation (5 days)
Request
{
"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
}
]
}
The data.final_disbursement_amount field returned in the simulation will be the value of the change paid to the customer.
Query the installment value of the Personal Credit operation
Request
The DEBT-KEY is the key returned in the operation creation response (/debt response)
7. Creating the debtor's ownership account
Before typing the proposals, it's necessary to open an account for the debtor at QI Tech.
The account will be used to receive the Personal Credit Operation disbursement, make payments of the outstanding balance of the original debt at another bank (via Bank Slip, TED or Pix).
Request
{
"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"
}
}
| Parameter | Description |
|---|---|
| account_owner | Debtor data |
| is_operation_account | Indicator that the account is an operation account. |
Response
{
"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"
}
The account data returned in /account should be used as the disbursement account for the Personal Credit Operation
5xx Error or Timeout
The flow should not proceed while the account is not successfully opened. For failure cases, it should be checked whether the account was actually not opened for the customer, before a possible retry attempt.
It's possible to check if the account was opened for the customer by listing the accounts opened for a specific CPF.
Request
| Parameter | Description |
|---|---|
| owner_document_number | Debtor's CPF |
| requester_key | It's an internal integration key. |
Response
{
"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
}
}
In the response payload above, only the fields relevant for reading are listed.
8. Operations Issuance
- Personal Credit Operation: Must be issued with disbursement on D0 and with only one installment due on D+5 business days from disbursement.
For issuing the Personal Credit Operation, the "financial" object must be sent with exactly the same information sent in its simulation.
The Personal Credit Operation can only disburse on business days and at the following times, depending on the payment method of the outstanding balance of the original debt:
- TED: disbursement between 6:30 and 17:15
- Bank Slip: disbursement between **7: