Consulta de Margem Consignável (SIAPE)

Endpoint que consulta a margem disponível do servidor federal no SIGEPE/SIAPE. Sem o balance_key desse passo, não dá pra simular nem emitir.

Pré-requisitos

1. Servidor pré-autorizou QI SCD no Portal do Servidor (válida 30 dias).
2. authority_code (código UPAG) — recebido na fase comercial.

[!warning] Diferente do Exército, não há upload de documento de autorização. Tudo é digital no portal.

Endpoint

POST /federal_payroll/balance

Campo	Tipo	Descrição
document_number	string	CPF do servidor (11 dígitos)
authority_code	string	Código da Unidade Pagadora (UPAG)
registration_code	string	Matrícula SIAPE

Resposta síncrona:

{
  "balance_key": "...",
  "status": "pending_search"
}

Webhook de resultado

Tipo: federal_payroll.balance

Estrutura do payload de sucesso:

{
  "balance_query": [
    {
      "available_balance": 3500.00,
      "authority_code": "17000",
      "registration_code": "1354387",
      "employment_relationship": "active",
      "consigned_credit": 1200.00,
      "consigned_card": 300.00
    }
  ]
}

• available_balance — margem disponível
• consigned_credit — quanto já está consignado em crédito
• consigned_card — quanto está em cartão consignado

Enumeradores de falha (balance)

Enumerador	Significado	Ação
unauthorized_institution	Servidor não pré-autorizou QI SCD no portal	Pedir autorização
inexistent_relationship	Sem vínculo federal	Verificar dados
invalid_document_number	CPF malformado	Verificar CPF
inactive_federal_employee	Servidor inativo	Não há ação
deceased_federal_employee	Servidor falecido	Não há ação

Cenários de Sandbox

Sucesso

document_number	authority_code	registration_code
25256363506	17000	1354387

Falha

document_number	failure_reason
71987878353	unauthorized_institution

[!info] Reset diário Reservas não-finalizadas no sandbox são encerradas todo dia às 23:59h pra manter o ambiente limpo.

Próximo passo

Após o webhook succeeded com available_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