Margem Livre (Crédito Novo)

Esteira de originação direta quando o servidor federal tem margem consignável disponível no SIAPE/SIGEPE. 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

• Servidor pré-autorizou QI SCD no Portal do Servidor (válida 30 dias).
• balance_key recebido na Consulta de Margem, com webhook federal_payroll.balance em status: succeeded.
• available_balance retornado > parcela desejada × prazo.

1. Simulação

ENDPOINT

/debt_simulation

MÉTODO

POST

Request Body

{
  "borrower": {
    "person_type": "natural",
    "individual_document_number": "25256363506"
  },
  "financial": {
    "first_due_date": "2026-07-01",
    "installment_face_value": 500.00,
    "disbursement_date": "2026-06-02",
    "number_of_installments": 72,
    "monthly_interest_rate": 0.0185,
    "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": "federal_payroll",
      "percentage": 1,
      "collateral_data": {
        "reservation_type": "new_credit",
        "authority_code": "17000",
        "registration_code": "1354387"
      }
    }
  ]
}

Campos chave

Campo	Descrição
collaterals[].collateral_type	federal_payroll (obrigatório)
collaterals[].collateral_data.reservation_type	new_credit — sempre pra margem livre
collaterals[].collateral_data.authority_code	Código da Unidade Pagadora (UPAG)
collaterals[].collateral_data.registration_code	Matrícula SIAPE
financial.installment_face_value	Parcela — ≤ available_balance
financial.number_of_installments	Prazo (geralmente até 96 meses pra SIAPE)

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

Janela operacional

Pra disbursement_date, lembre que o SIAPE só processa em dias úteis das 07:00 às 00:00. Datas em fim de semana ou feriados são empurradas pro próximo dia útil.

2. Emissão

ENDPOINT

/debt

MÉTODO

POST

Request Body

{
  "borrower": {
    "name": "MARIA DOS SANTOS",
    "email": "maria@email.com",
    "phone": { "number": "900000000", "area_code": "11", "country_code": "+55" },
    "address": {
      "city": "Brasília", "state": "DF", "number": "100",
      "street": "Esplanada", "complement": "",
      "postal_code": "70000000", "neighborhood": "Centro"
    },
    "role_type": "issuer",
    "birth_date": "1978-09-22",
    "mother_name": "JOSEFINA DOS SANTOS",
    "person_type": "natural",
    "individual_document_number": "25256363506",
    "gender": "female",
    "nationality": "brasileiro",
    "is_pep": false,
    "marital_status": "married"
  },
  "financial": { /* idem simulação */ },
  "simplified": true,
  "collaterals": [
    {
      "collateral_type": "federal_payroll",
      "percentage": 1,
      "collateral_data": {
        "reservation_type": "new_credit",
        "reservation_method": "creation",
        "authority_code": "17000",
        "registration_code": "1354387"
      }
    }
  ],
  "disbursement_bank_account": {
    "name": "MARIA DOS SANTOS",
    "bank_code": "001",
    "account_type": "checking_account",
    "account_digit": "8",
    "branch_number": "1234",
    "account_number": "00098765",
    "document_number": "25256363506",
    "transfer_method": "ted"
  },
  "purchaser_document_number": "32402502000135"
}

reservation_method

creation (averbação imediata)

Averbação no SIGEPE dispara junto com a criação do /debt.

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

Averbação só dispara após a formalização (POST /debt/{KEY}/signed).

Etapa-chave: confirmação do servidor no Portal

Servidor precisa confirmar

Após o /debt, o webhook chega com status: pending_consent. O servidor precisa entrar no Portal do Servidor e confirmar a operação dentro da janela do SIGEPE. Se não confirmar, expira com consent_expired e cancela. Comunique o servidor imediatamente após o /debt.

Webhooks pós /debt

Webhook	Status	Quando
debt	waiting_signature	Operação criada
credit_operation.collateral	pending_consent	Aguardando servidor confirmar no Portal
credit_operation.collateral	success (collateral_constituted: true)	Servidor confirmou; averbação ativa
debt	disbursed	Desembolso PIX/TED enviado

→ Próximo passo: Formalização

Falhas comuns

Webhook / Erro	Enumerador	Significado	Ação
federal_payroll.balance	unauthorized_institution	Servidor não pré-autorizou QI SCD	Solicitar autorização
federal_payroll.balance	inexistent_relationship	Sem vínculo federal	Verificar dados
credit_operation.collateral	invalid_balance	Margem insuficiente	Reduzir parcela
credit_operation.collateral	consent_refused	Servidor recusou no Portal	Conversar com servidor
credit_operation.collateral	consent_expired	Janela do SIGEPE fechou	Re-emitir

→ Lista completa de enumeradores

Sandbox

Sucesso

document_number	authority_code	registration_code
25256363506	17000	1354387

Falha

document_number	failure_reason
71987878353	unauthorized_institution

→ Mocks completos