Pular para o conteúdo principal

Manual Consignado da Aeronáutica

Atenção!

Os webhooks da QI Tech não devem ser mapeadas de forma restrita. Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.

Reenvio de Webhooks

Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: Reenvio de Webhooks.

Funcionamento AERONÁUTICA

O sistema de consignações da Aeronáutica, via API, funciona 24 horas por dia, todos dias da semana, inclusive feriados.

1. Autorização​

Antes do envio de qualquer requisição de Consignado do Exército (Consulta, Emissão da dívida, etc), é necessário fazer o upload do consentimento do militar autorizando a QI a proceder com a consulta, averbação e manutenção em folha de pagamento. Para upload da autorização, seguir o passo a passo encontrado na sessão de Upload de Documentos

O upload retornará uma chave única no campo de retorno "document_key" que deverá ser enviado no payload de requisição de Consulta de Margem Consignável em "authorization_document_key", confome melhor detalhado à seguir, no item 3. Consulta de Margem Consignável.

2. Simulação de Cenários de Sucesso nas Consultas de Saldos, Consulta de Lista de Contratos e Averbações em Sandbox​

Para fins de teste, temos um conjunto de dados que podem ser utilizados para simular os casos de sucesso em sandbox, são eles:

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

Essas informações devem ser enviadas no payload da requisição no momento da simulação e o resultado será enviado por meio do webhook de sucesso correspondente.

3. Consulta de Margem Consignável​

Em posse dos dados de CPF, Matrícula do militar e a Chave do Documento de Autorização, o parceiro integrador pode realizar a consulta assíncrona da margem consignável do militar através do seguinte endpoint:

Request​

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

O CPF deve ser informados em formato de texto, com no máximo 11 caracteres, sem ".", sem "-" e alinhado com zeros à esquerda. A Matrícula também deve ser no formato de texto.

Request Body Params​

CampoTipoDescrição
document_numberstringCPF do militar.
registration_codestringMatrícula do militar.
authorization_document_keyuuiddocument_key do termo de autorização.

Sincronous Response​

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

Por ser assíncrono, os dados da consulta de margem do tomador serão retornados via webhook.

Response Body Params​

CampoTipoDescrição
balance_keystringChave de identificação da consulta de Margem Consignável.
statusenumEnumeradores de status de consulta de margem consignável abaixo.

Enumeradores de Status de Consulta de Margem Consignável​

EnumeradorDescrição
pending_searchConsulta de margem consignável pendente de resposta do sistema do exército.
processedConsulta de margem consignável processada.
info

O status 'processed' refere-se apenas ao fato de que a requisição do saldo foi efetivamente eviada e processada, porém não diz respeito ao sucesso ou à falha da mesma, tal informação estará no payload enviado via Webhook explicado à seguir.

Consulta com sucesso​

O webhook de sucesso será retornado da seguinte forma:

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
     }
}

Response Body Params success​

CampoTipoDescrição
webhook_typestringTipo do webhook.
keyuuidChave de referência do webhook. Neste caso, se trata da balance_key
event_datetimestringData e hora do envio do webhook.
statusstringStatus da consulta de margem consignável.
datajsonCampo que irá conter os dados referentes à consulta.
data.military_unitstringEstabelecimento que o militar está cadastro no sistema eConsig.
data.military_branchstringOrgão/organização militar que o militar está.
data.categorystringCategoria do militar.
data.namestringNome do militar.
data.document_numberstringCPF do militar.
data.registration_codestringMatrícula do militar.
data.balancestringMargem disponível para contratação de empréstimo consignado.
data.birth_datestringData de nascimento do militar.
data.grant_datestringData de admissão do militar.
data.allowed_installment_numbersstringNúmero limite de parcelas de um empréstimo consignado para o militar consultado.

Consulta com falha​

O webhook de falha será retornado da seguinte forma:

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": {} 
    }
}

Cada tipo de erro mapeado possui um título, código e descrição mais detalhada. Caso ainda não tenha sido mapeado retornaremos no mesmo formato porém com o título unknown_response. Salvo os campos idênticos, a tabela abaixo descreve com detalhes os parâmetros retornados.

Response body params failure​

CampoTipoDescrição
data.titlestringTítulo referente ao erro ocorrido.
data.descriptionstringDescrição detalhada em inglês do erro ocorrido.
data.translationstringTradução da decrição do erro ocorrido.
data.codestringCódigo do erro recebido. Os 3 últimos dígitos referem-se ao código de erro recebido pela Zetra. (ex: ZP000329)
data.extra_fieldsjsonCampo destinado à possíveis atributos extras.

Requisição de uma Consulta de Margem Consignável​

Caso o parceiro queira saber sobre o andamento de alguma entidade Balance criada, ele pode realizar uma requisição da mesma:

Atenção!

Recomendamos fortemente que utilizem o Webhook como referência nas informações da Consulta de Margem Consignável do tomador. Feature passível de remoção no futuro.

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. Consulta da Lista de Contratos​

Em posse dos dados de CPF, Matrícula do militar e Token do possível tomador, o parceiro integrador pode realizar a consulta da lista de contratos do militar disponíveis para compra através do seguinte endpoint:

Request​

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

O CPF deve ser informados em formato de texto, com no máximo 11 caracteres, sem ".", sem "-" e alinhado com zeros à esquerda. A Matrícula também deve ser no formato de texto.

Request Body Params​

CampoTipoDescrição
document_numberstringCPF do militar.
registration_codestringMatrícula do militar.
tokenstringSenha do militar.

Sincronous Response​

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

Por ser assíncrono, os dados da consulta da lista de contratos do tomador serão retornados via webhook.

Response Body Params​

CampoTipoDescrição
portability_contracts_report_keystringChave de identificação da consulta da lista de contratos.
statusenumEnumeradores de status de consulta da lista de contratos.

Enumeradores de Status da Consulta da Lista de Contratos​

EnumeradorDescrição
pending_searchConsulta da lista de contratos pendente de resposta do sistema do exército.
processedConsulta da lista de contratos processada.
info

O status 'processed' refere-se apenas ao fato de que a requisição da consulta da lista de contratos foi efetivamente eviada e processada, porém não diz respeito ao sucesso ou à falha da mesma, tal informação estará no payload enviado via Webhook explicado à seguir.

Webhook da Consulta de Lista de Contratos​

O webhook de sucesso será retornado da seguinte forma:

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​

CampoTipoDescrição
webhook_typestringTipo do webhook.
keyuuidChave de referência do webhook. Neste caso, se trata da balance_key
event_datetimestringData e hora do envio do webhook.
statusstringStatus da consulta de margem consignável.
datajsonCampo que irá conter os dados referentes à consulta.
data.document_numberstringCPF do militar.
data.contractsarrayLista dos contratos e de suas respectivas informações.
data.contracts.econsig_idstringIdentificador único do contrato no sistema da Zetra.
data.contracts.consignatorystringConsignatária do contrato.
data.contracts.installment_amountfloatValor da parcela.
data.contracts.number_of_installmentsintNúmero total de parcelas do contrato.
data.contracts.number_of_paid_installmentsintNúmero de parcelas pagas até a vigência atual.
data.contracts.contract_statusstringSituação do contrato.
As possíveis Situações de Contrato estão mapeadas aqui.
Situações do Contratocontract_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
info

Estas situações de contrato referem-se também às possíveis situações dos contratos internos.

Requisição de uma Consulta de Lista de Contratos​

Caso o parceiro queira saber sobre o andamento de uma Consulta de Lista de Contratos, ele pode realizar uma requisição da mesma:

Atenção!

Recomendamos fortemente que utilizem o Webhook como referência nas informações da Lista de Contratos do tomador. Feature passível de remoção no futuro.

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. Simulação da Operação de Crédito Pessoal​

Primeiramente é preciso calcular o valor da operação de Crédtio Pessoal necessária para quitar a operação de crédito original.

O valor do saldo devedor da dívida original deve ser informado no campo disbursed_amount.

Aviso

A operação deve ser simulada com apenas 1 parcela, desembolso em D0 e a parcela deve ter seu vencimento para D+5 dias úteis, contas a partir da data de desembolso (pagamento) da operação.

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 .Simulação da Operação de Crédito Consignado da AERONÁUTICA​

Nesta simulação os campos informados terão seus valores atribuidos da seguinte forma:

installment_face_value = Valor da margem consignável

disbursement_date = D+5 dias úteis do momento da simulação

due_balance = total_amount da 1ª parcela retornada na simulação da Operação de Crédito Pessoal

original_deadline = Prazo total em dias da Operação de Crédito Pessoal (5 dias)

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
        }
    ]
}

O campo data.final_disbursement_amount retornado na simulação será o valor do troco pago ao cliente.


Consulta do valor de parcela da operação de Crédito Pessoal​

Request​

ENDPOINT
/debt?key=[DEBT-KEY]&eval_present_value=True&calculate_delay=True&calculate_spread=False
MÉTODO
GET
Informação

A DEBT-KEY é a chave retornada na resposta da criação da operação (resposta do /debt)


7. Criação da conta de titularidade do devedor​

Antes da digitação das propostas é necessário abrir uma conta para o devedor na QI Tech.

A conta será utilizada para receber o desembolso da Operação de Crédito Pessoal, realizar os pagamentos do saldo devedor da dívida original em outro banco (via Boleto, TED ou 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"
	}
}
ParâmetroDescrição
account_ownerDados do devedor
is_operation_accountIndicativo de que a conta é uma conta de operação.

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"
}
info

Os dados de conta retornados no /account deverão ser utilizados como conta de desembolso da Operação de Crédito Pessoal

Erro 5xx ou Timeout​

O fluxo não deve prosseguir enquanto a conta não estiver abertua com sucesso. Para os casos de falha, deve ser checado se a conta de fato não foi aberta para o cliente, antes de uma possível retentativa de abertura.

É possível checar se a conta foi aberta para o cliente, listando as conta abertas para um determinado CPF.

Request​

ENDPOINT
/account
MÉTODO
POST
PARAMETER
owner_document_number, requester_key
ParâmetroDescrição
owner_document_numberCPF do devedor
requester_keyÉ uma chave interna da integração.

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
	}
}
Informação

No payload de resposta acima, estão listados apenas os campos relevantes para leitura.


8. Emissão das Operações​

  • Operação de Crédito Pessoal: Deve ser emitida com desembolso em D0 e com apenas uma parcela com vencimento para D+5 dias úteis do desembolso.
Atenção

Para emissão da Operação de Crédito Pessoal o objeto "financial", deve ser enviado com exatamente as mesmas informações enviadas na sua simulação.

Informação

A Operação de Crédito Pessoal, só pode desembolsar em dias úteis e nos seguintes horários, à depender do meio de pagamento do saldo devedor da dívida original:

  • TED: desembolso entre 6:30 e 17:15
  • Boleto: desembolso entre 7:00 e 22:00
  • Pix: qualquer horário (mas é recomendado o desembolso em horário comercial, pois caso uma operação seja desembolsada de madrugada, por exemplo, a entrada do Pix pode ser rejeitada por suspeitas de fraude)

Emissão da Operação de Crédito Pessoal​

Para emitir a Operação de Crédito Pessoal, é necessário enviar a informação dos Boletos/TEDs/Pix que precisam ser pagos após o desembolso da operação.

Atenção

O parceiro deve gerar uma chave interna de identificação da operação e enviá-la na requisição de emissão de dívida no campo "requester_identifier_key"

Exemplos Resquests​

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"
    }
}

Enumeradores Marital Status​

EnumeradorDescrição
singleSolteiro(a)
marriedCasado(a)
widowerViúvo(a)
divorcedDivorciado(a)

Erro 5xx ou Timeout​

Caso seja retornado algum 5xx ou Timeout na requisição, afim de certificar que a operação de fato não foi criada na QI, é recomendado que o parceiro realize uma consulta da operação que teve retorno 5xx ou timeout.

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

Caso o retorno do GET seja um 200, o parceiro não deve retentar a criação da operação e seguir o fluxo da operação. Caso seja retornado um 404 - Not Found, o parceiro deve retentar a criação da operação.

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"
}
Informação

O campo "key" da resposta de criação da operação é a DEBT-KEY, que é a chave única da operação dentro da QI.

Assinatura​

Autorizar desembolso​

Após assinatura da operação, é necessário autorizar a operação para desembolso.

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

Desembolso​

Após ser assinada e autorizada para desembolso, a operação seguirá automaticamente para esteira de desembolso.

Após o desembolso ser processado o parceiro receberá o seguinte webhook:

Sucesso no desembolso​

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"
}

Ações pós-desembolso​

Após o desembolso da Operação de Crédito Pessoal na conta do devedor criada na QI, serão executados os pagamentos de boleto/TED/Pix referente à quitação do saldo devedor da dívida original do devedor (ações pós-desembolso)

Sucesso​

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"
}

Erro na ação pós-desembolso​

Em caso de erro no pagamento da ação pós-desembolso, o parceiro será notificado através do seguinte 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"
}

Estorno da TED da ação pós-desembolso​

Caso a TED realizada na ação pós-desembolso seja devolvida pela instituição financeira destinatária, o parceiro será notificado através do seguinte 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"
}

Retentar ação pós-desembolso com falha​

Caso ocorra um erro/estorno no pagamento da ação pós-desembolso, ela pode ser retentada através do seguinte endpoint /baas/action/[ACTION-KEY]


Emissão da Operação de Crédito Consignado da Aeronáutica​

A Operação de Crédito Consignado do Exército deve quitar a Operação de Crédito Pessoal e liberar (caso exista) o troco para o cliente

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"
        }
    ]
}

Detalhamento de campos no objeto collateral_data​

CampoDescriçãoValores
reservation_typeTipo da reservaEnumeradores
registration_codeMatrícula do militar123456789
reservation_methodDetermina quando deve-se iniciar a tentativa de averbação do consignado, seja no momento da criação da operação de crédito ou no momento da emissão da mesma.Enumeradores
portability_dataDados de portabilidadeObjeto de Portabilidade

Tabela de tipos de reserva​

EnumeradorDescrição
new_creditCrédito Novo
portabilityPortabilidade
refinancingRefinanciamento

Tabela de metodos de criação de reserva​

Atenção

Campo muito importante, pois ele determina diretamente quando o pedido de intensão de reserva na Zetra será feito.

EnumeratorDescrição
creationA tentativa de averbação começará quando a operação de crédito for criada.
issuingA tentativa de averbação começará quando a operação de crédito for emitida, ou seja, após a formalização da mesma.

Detalhamento de campos no objeto portability_data​

CampoDescriçãoValores
tokenSenha fornecida pelo militar1234abcd
origin_econsig_idCódigo identificador de contrato da Zetra1234567
origin_econsig_idsLista de códigos identificadores de contratos da Zetra[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"
}

Averbação​

Após a criação da Operação de Crédito Consignado do EXÉRCITO, a QI iniciará o processo de averbação da operação.

O processo de tentativa de averbação inicia no momento da criação da operação, e será retentado até a última data de opção de desembolso da operação.

A após a conclusão da averbação da margem consignável do exército, a QI notificará o parceiro através do seguinte 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"
}

Caso o token informado não seja válido, enviaremos o seguinte webhook. Esse webhook também será enviado caso o token informado já tenha sido utilizado e seja necessário um novo.

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"
}

Resposta que ocasionam cancelamento automático​

Dependendo da resposta da Zetra, a operação será cancelada automaticamente. Quando isso ocorrer enviaremos um webhook no formato abaixo, o motivo do cancelamento é informado no campo "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"

}

Tabela de enumeradores​

EnumeradorDescriçãoCódigo da Zetra
airforce_payroll_military_not_foundMilitar não encontrado.293
airforce_payroll_portability_not_foundContrato de origem não encontrato.294
airforce_payroll_consignable_margin_exceededMargem disponível excedida.359

Expiração da Portabilidade​

Após 10 dias, a Zetra cancela os pedidos de portabilidades que estão aguardando confirmação.

Desta forma, para reiniciar o fluxo de portabilidade, faz-se necessário um novo token válido. Caso exista um novo token válido, a proposta retorna para o passo de intenção de portabilidade (status da reserva: pending_reservation). No entanto, caso não exista um token válido, geralmente porque o token enviado já foi utilizado na intenção de portabilidade anterior, a proposta é atualizada para o status de pending_valid_token, aguardando o envio de um novo token. Com o envio de um novo token válido, a proposta segue normalmente o fluxo de intenção de portabilidade e confirmação.

Para informar a situação será enviado o seguinte 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. Envio de novo Token de Portabilidade​

O token de portabilidade é de uso único, portanto, é necessário que um novo token seja enviado quando o anterior for utilizado ou no caso de token inválido.

A forma de envio é uma chamada simples:

Request​

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

Casos de sucesso​

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

Caso de erro​

info

Somente o token deverá ser enviado nessa requisição, caso contrário o processo retornará um erro

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. Cancelamento e Desaverbação:​

Para realizar o cancelamento definitivo de uma operação, com a desaverbação da margem consignável, deve ser utilizado o seguinte endpoint:

Atenção

Vale ressaltar que o processo de desaverbação é assíncrono, ou seja, o cancelamento da operação de crédito, NÃO signifca necessáriamente que a desaverbação foi concluída. Para consultar o status da desaverbação vide Recuperar resposta da última request".

Atenção

O cancelamento definitivo também pode ocorrer de forma automática, isso acontece quando uma operação está no status "canceled" por mais de 7 dias.

Request​

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

Cancelamento da operação com sucesso:​

Após a conclusão do cancelamento da operação, o parceiro receberá o seguinte 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"
}

Desaverbação com sucesso​

Após a conclusão da desaverbação, o parceiro receberá o seguinte 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. Recuperar resposta da última Request​

O last_response é uma forma de mapear, de forma simples e objetiva, a resposta da comunicação entre a QI e a Zetra, possibilitando saber quando essa requisição foi feita e qual o retorno obtido (através de um enumerador).

Cada enumerador tem uma descrição detalhada. Podemos conferir abaixo, com mais detalhes, como serão apresentados os dados do last response.

Casos de sucesso​

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"
    }
  }
Response Body Portability or Refin
{
    "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"
        }       
    }
}

Tabela de enumeradores​

EnumeradorDescriçãoDetalhesStatus da reserva
successfully_acceptedReservation request acceptedO pedido de averbação foi aceito e está aguardando confirmaçãopending_confirmation
successfully_reservedReservation made successfullyA reserva foi averbada com sucessoreserved
successfully_deletedReservation successfully deletedA reserva foi desaverbada com sucessodeleted

Casos de erro​

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"
    }
  }

Tabela de enumeradores​

EnumeradorDescriçãoAção QICódigo correspondente da Zetra
waiting_confirmationWaiting Confirmation on Portabilityretry
communication_errorCommunication Error with Zetraretry241
consignable_margin_exccededExceeded consignable marginretry359

12. Informe de Saldo Devedor​

O informe de saldo devedor acontece no 5º dia útil após o dia da solicitação, e todos os contratos informados são enviados pelo webhook com as seguintes informações:

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"
	}
}