Manual Consignado do Exército - Crédito Novo

---

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 EXÉRCITO

O sistema de consignações do Exército, 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 no item 2. Consulta de Margem Consignável.

2. Simulação de Cenários de Sucesso nas Consultas de Saldos 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_number	registration_code
45507529710	146254221
10945455038	146262711
14081064180	026403232

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

3. Consulta de Margem Consignável

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

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

informação

O CPF deve ser informado em formato de texto, com no máximo 11 caracteres, sem ".", sem "-" e alinhado com zeros à esquerda.

Request Body Params

Campo	Tipo	Descrição
document_number	string	CPF do militar.
registration_code	string	Matrícula do militar.
authorization_document_key	uuid	document_key do termo de autorização.
token	string	Token de autenticação.

Response

ENDPOINT

/military_payroll/balance

MÉTODO

POST

STATUS

201

Response Body

{
	"balance_key": "81da8afb-e1b2-4215-8093-c4b5feab8a9f",
	"status": "pending_search"
}

Os dados da consulta de margem serão retornados via webhook.

Response Body Params

Campo	Tipo	Descrição
balance_key	string	Chave de identificação da consulta de Margem Consignável.
status	enum	Enumeradores de status de consulta de margem consignável.

Enumeradores de Status de Consulta de Margem Consignável

Enumerador	Descrição
pending_search	Consulta de margem consignável pendente de resposta do sistema do exército.
failed	Falha na consulta de margem consignável.
succeeded	Sucesso na consulta de margem consignável.

Consulta com sucesso

O webhook de sucesso será retornado da seguinte forma:

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 Params

Campo	Tipo	Descrição
webhook_type	string	Tipo do webhook.
key	uuid	Chave de referência do webhook. Neste caso, se trata da balance_key
event_datetime	string	Data e hora do envio do webhook.
status	enum	Status da consulta de margem consignável.
military_unit	string	Estabelecimento que o militar está cadastro no sistema eConsig. Opções:"Exército brasileiro", "Sistema de Retribuição do Exterior".
military_branch	string	Orgão/organização militar que o militar está. A tabela completa com todos os possíveis órgãos se encontra logo a baixo.
category	string	Categoria do militar. A tabela completa com todas as possíveis categorias se encontra logo a baixo.
name	string	Nome do militar.
document_number	string	CPF do militar.
registration_code	string	Matrícula do militar.
birth_date	string	Data de nascimento do militar.
grant_date	string	Data de admissão do militar.
balance	string	Margem disponível para contratação de empréstimo consignado.
allowed_installment_numbers	string	Número limite de parcelas de um empréstimo consignado para o militar consultado.

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

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

Consulta com falha

O webhook de falha será retornado da seguinte forma:

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

Cada enumerator tem uma descrição mais detalhada e, para facilitar a consulta, a tabela abaixo relaciona ambas as coisas para cada caso.

Enumeradores failure_reason

Enumerador	Descrição	Código Zetra
invalid_registration_code	Matrícula informada não é válida	210
military_not_found	Nenhum servidor encontrado para os dados informados	293
military_blocked	Consulta não pode ser concluída pois o militar está bloqueado	352

---

4. Simulação de um Crédito Consignado

Atenção

Em caso de refinanciamento, a simulação da Operação de Crédito Consignado, deverá simular a quitação do contrato original e o calculo do valor do troco liberado para o cliente em função da margem disponível e taxa do contrato.

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 // PINHO - Aqui (e todo lugar que tá workday) vai ser workdays mesmo? considerando que o exercito funciona todos os dias?
      },
      {
        "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. Emissão de Crédito Consignado

IMPORTANTE

Em requisições do tipo refinanciamento, é fundamental considerar qual chave de integração está sendo enviada, assegurando que corresponda ao tipo de contrato que será enviado.

Request

ENDPOINT

/debt

MÉTODO

POST

Digitação Margem Livre

Request Body

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

Digitação Refinanciamento

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

Detalhamento de campos no objeto collateral_data

Campo	Descrição	Valores
reservation_type	Tipo da reserva	Enumeradores
registration_code	Matrícula do militar	123456789
reservation_method	Determina 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

Tabela de tipos de reserva

Enumerador	Descrição
new_credit	Crédito Novo
refinancing	Refinanciamento

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.

Enumerator	Descrição
creation	A tentativa de averbação começará quando a operação de crédito for criada.
issuing	A tentativa de averbação começará quando a operação de crédito for emitida, ou seja, após a formalização da mesma.

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

Em caso de sucesso na averbação, o parceiro receberá o seguinte webhook:

Webhook de Averbação

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. Modelos de formalização da operação

Por padrão a QI Tech realiza a coleta de assinaturas através da QISign e o contrato é enviado para os assinantes no momento da emissão, porém ainda existe a possibilidade de o parceiro realizar a coleta de assinaturas de forma independente e enviar o documento assinado ou as evidencias de assinatura para a QI Tech para seguir com a operação.

Segue abaixo a descrição de cada modelo aceito pela QI:

Assinar via QISign

A assinatura através da QI Sign ocorre de forma automática na plataforma QI Tech, uma vez que a operação é criada o documento é disparado pela QI Sign para coleta de assinaturas, após assinado a operação automaticamente ira do status "waiting_signature" para o status "issued" (Emitida).

Enviar PDF assinado

Esse tipo indica que o PDF emitido através da "/debt" será assinado e link com o PDF assinado será enviado através da API 4.1 como forma de autenticação.

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

Enviar evidências de assinatura

Esse tipo indica que o PDF emitido através da "/debt" será assinado através de um hash anexado em sua ultima pagina.

A autenticação através do envio de evidências da assinatura, pode ter 3 tipos:

Evidência de Opt-in:

A assinatura através de opt-in significa que o cliente vai dar o aceite do contrato através da aplicação do parceiro (front).

Para que essa assinatura seja válida, alguns dados devem ser enviados obrigatoriamente.

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

Evidência em arquivo .zip:

A assinatura através de zip contempla o envio de um arquivo de comprovação, tal como uma ligação gravada.

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

Evidência através do envio de uma Selfie:

A autenticação através de selfie é disponibilizada para os parceiros que utilizam os serviços de CaaS QI Tech, onde a autenticação através de selfie é validada e um id de comprovação é gerado.

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

informação

O Response é o mesmo para todas as operações realizadas através do endpoint debt/[DEBT_KEY]/signed.

7. 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": "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. 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

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

Tabela de enumeradores

Enumerador	Descrição	Detalhes	Status da reserva
successfully_accepted	Reservation request accepted	O pedido de averbação foi aceito e está aguardando confirmação	pending_confirmation
successfully_reserved	Reservation made successfully	A reserva foi averbada com sucesso	reserved
successfully_deleted	Reservation successfully deleted	A reserva foi desaverbada com sucesso	deleted

Casos de erro

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

Tabela de enumeradores

Enumerador	Descrição	Ação QI	Código correspondente da Zetra
waiting_confirmation	Waiting Confirmation on Portability	retry
communication_error	Communication Error with Zetra	retry	241
consignable_margin_excceded	Exceeded consignable margin	retry	359