Consulta de Margem Consignável

Endpoint que consulta a margem disponível do militar no Zetra (eConsig). É o primeiro passo operacional depois do upload da autorização — sem o balance_key desse passo, não dá pra simular nem emitir.

Pré-requisitos

1. Upload do consentimento feito (POST /upload → document_key). → Upload de Documentos
2. Token Zetra do militar em mãos (senha do sistema militar).

Endpoint

POST /military_payroll/balance

Campo	Tipo	Descrição
document_number	string	CPF do militar — 11 dígitos, sem . e sem -, zero-padded
registration_code	string	Matrícula do militar
authorization_document_key	uuid	document_key retornado no upload
token	string	Token de autenticação Zetra (senha)

Resposta síncrona:

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

Webhook de resultado

Tipo: military_payroll.balance.status_change

Campos no payload de sucesso:

• balance — margem disponível (Decimal)
• allowed_installment_numbers — array de prazos válidos (ex: [24, 36, 48])
• military_unit — unidade do militar
• military_branch — força (string longa, dezenas de valores possíveis: AMAN, Sistema de Retribuição do Exterior, etc.)
• category — ATIVO, INATIVO, PENSIONISTA
• name, document_number, registration_code, birth_date, grant_date

Enumeradores de falha

Enumerador	Zetra code	Significado	Ação
invalid_registration_code	210	Matrícula inválida ou inexistente	Verificar matrícula
military_not_found	293	Militar não encontrado pelo CPF+matrícula	Verificar dados
military_blocked	352	Militar com bloqueio em folha	Não há ação imediata
communication_error	241	Zetra indisponível	QI retenta automaticamente

Sandbox

A sandbox militar conecta na Zetra real de homologação (central_homologa.econsig.com.br) — não há whitelist local de CPFs no military-payroll-api. Os dados de teste (CPFs, matrículas, tokens) são fornecidos pela Zetra.

Solicite ao time de Integrações QI Tech a lista de servidores fictícios disponíveis. CPFs fora dessa lista retornam military_not_found (Zetra 293) ou invalid_registration_code (Zetra 210).

→ Mocks (Sandbox) — detalhes completos

Próximo passo

Após o webhook succeeded com balance retornado, escolha a modalidade:

• Margem Livre — crédito novo com margem disponível
• Portabilidade + Refinanciamento — refin de operação QI ou compra de dívida externa