Margem Livre (Crédito Novo)

Esteira de originação direta quando o militar tem margem consignável disponível e não está trazendo dívida externa nem refinanciando operação ativa. Cobre simulação e emissão para reservation_type: new_credit.

Para refinanciar uma operação QI ativa ou trazer dívida de outro banco, ver Portabilidade + Refinanciamento.

Pré-requisitos

• balance_key recebido na Consulta de Margem, com webhook military_payroll.balance.status_change em status: succeeded.
• balance retornado > parcela desejada × prazo.
• token Zetra do militar disponível.

1. Simulação

Antes de emitir, simule as condições para validar margem, prazo e cronograma.

Request

ENDPOINT

/debt_simulation

MÉTODO

POST

Request Body

{
  "borrower": {
    "person_type": "natural",
    "individual_document_number": "45507529710"
  },
  "financial": {
    "first_due_date": "2026-07-01",
    "installment_face_value": 500.00,
    "disbursement_date": "2026-06-01",
    "number_of_installments": 24,
    "monthly_interest_rate": 0.0205,
    "interest_type": "pre_price_days",
    "credit_operation_type": "ccb",
    "interest_grace_period": 0,
    "principal_grace_period": 0,
    "fine_configuration": {
      "monthly_rate": 0.01,
      "interest_base": "calendar_days",
      "contract_fine_rate": 0.02
    }
  },
  "collaterals": [
    {
      "collateral_type": "military_payroll",
      "percentage": 1,
      "collateral_data": {
        "reservation_type": "new_credit",
        "registration_code": "146254221"
      }
    }
  ]
}

Campos chave

Campo	Descrição
collaterals[].collateral_type	military_payroll (obrigatório)
collaterals[].collateral_data.reservation_type	new_credit — sempre pra margem livre
collaterals[].collateral_data.registration_code	Matrícula do militar
financial.installment_face_value	Parcela — ≤ balance retornado na consulta de margem
financial.number_of_installments	Prazo — ∈ allowed_installment_numbers
financial.monthly_interest_rate	Taxa mensal (ex: 0.0205 = 2,05% a.m.)

modality.code NÃO é obrigatório em margem livre — só em refinanciamento.

Response

Síncrona — retorna o cronograma completo (disbursement_options[] com parcelas, IOF, CET).

2. Emissão

Cria a CCB e dispara a esteira de averbação → formalização → desembolso.

Request

ENDPOINT

/debt

MÉTODO

POST

Request Body

{
  "borrower": {
    "name": "JOÃO DA SILVA",
    "email": "joao@email.com",
    "phone": { "number": "900000000", "area_code": "11", "country_code": "+55" },
    "address": {
      "city": "São Paulo", "state": "SP", "number": "215",
      "street": "Gilberto Sabino", "complement": "",
      "postal_code": "12345012", "neighborhood": "Pinheiros"
    },
    "role_type": "issuer",
    "birth_date": "1985-03-12",
    "mother_name": "MARIA DA SILVA",
    "person_type": "natural",
    "individual_document_number": "45507529710",
    "gender": "male",
    "nationality": "brasileiro",
    "is_pep": false,
    "marital_status": "single"
  },
  "financial": {
    "first_due_date": "2026-07-01",
    "installment_face_value": 500.00,
    "disbursement_date": "2026-06-01",
    "number_of_installments": 24,
    "monthly_interest_rate": 0.0205,
    "interest_type": "pre_price_days",
    "credit_operation_type": "ccb",
    "interest_grace_period": 0,
    "principal_grace_period": 0,
    "fine_configuration": {
      "monthly_rate": 0.01,
      "interest_base": "calendar_days",
      "contract_fine_rate": 0.02
    }
  },
  "simplified": true,
  "collaterals": [
    {
      "collateral_type": "military_payroll",
      "percentage": 1,
      "collateral_data": {
        "reservation_type": "new_credit",
        "reservation_method": "creation",
        "registration_code": "146254221",
        "token": "12345678"
      }
    }
  ],
  "disbursement_bank_account": {
    "name": "JOÃO DA SILVA",
    "bank_code": "104",
    "account_type": "checking_account",
    "account_digit": "1",
    "branch_number": "3880",
    "account_number": "000736703806",
    "document_number": "45507529710",
    "transfer_method": "pix"
  },
  "purchaser_document_number": "32402502000135"
}

reservation_method — quando a averbação dispara

creation (averbação imediata)

Averbação no Zetra dispara junto com a criação do /debt. Feedback rápido de margem antes da assinatura — ideal pra fluxos onde o operador quer saber logo se a margem reserva.

issuing (averbação após formalização)

Averbação só dispara após a formalização (POST /debt/{KEY}/signed). Usado quando a assinatura é coletada offline ou em fluxos onde o contrato chega já assinado.

Webhooks pós /debt

Webhook	Status	Quando
debt	waiting_signature	Operação criada, aguardando assinatura
credit_operation.collateral	successfully_accepted → successfully_reserved	Averbação aceita pelo Zetra
debt	disbursed	Desembolso PIX/TED enviado

→ Próximo passo: Formalização

Falhas comuns

Webhook / Erro	Enumerador	Significado	Ação
Simulação	INSUFFICIENT_MARGIN	parcela × prazo > balance	Reduzir parcela ou prazo
Simulação	INVALID_INSTALLMENT_NUMBER	prazo fora de allowed_installment_numbers	Usar um dos prazos permitidos
credit_operation.collateral	consignable_margin_exceeded	margem insuficiente no momento da averbação (Zetra 359)	Reduzir parcela ou aguardar liberação
credit_operation.collateral	military_blocked	Militar com bloqueio em folha (Zetra 352)	Militar precisa resolver com Zetra
credit_operation.collateral	communication_error	Zetra indisponível (cod 241)	QI retenta automaticamente

→ Lista completa de enumeradores

Sandbox

A sandbox militar conecta na Zetra real de homologação — não há whitelist local. Os exemplos de CPF/matrícula/token nesta página (45507529710, 146254221, etc.) são apenas placeholders ilustrativos. Solicite ao time de Integrações QI Tech os dados reais cadastrados em central_homologa.econsig.com.br.

→ Mocks (Sandbox)