Incluir saldo devedor em lote

Envia o saldo devedor de vários contratos numa requisição. É o caminho recomendado para a atualização mensal da carteira.

Endpoint: POST /econsigado/loans/debt-balances/batch
Scope: econsignado.write
Equivalente na Dataprev: /emprestimos/incluir-saldo-devedor-lote-trabalhador

curl --location 'https://secureapi.onz.finance/api/v2/econsigado/loans/debt-balances/batch' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "items": [
      {
        "cpf": "12345678901",
        "employee_id": "12345",
        "employer_registration_type": 1,
        "employer_registration_number": "12345678000199",
        "contract_number": "CTR0001",
        "debt_balance_amount": 1772.70
      },
      {
        "cpf": "98765432100",
        "employee_id": "67890",
        "employer_registration_type": 1,
        "employer_registration_number": "12345678000199",
        "contract_number": "CTR0002",
        "debt_balance_amount": 980.00
      }
    ]
  }'

Campo	Obrigatório	Descrição
items	Sim	Lista de 1 a 150 itens
items[].cpf	Sim	CPF do trabalhador
items[].employee_id	Sim	Matrícula do trabalhador
items[].employer_registration_type	Sim	Código do tipo de inscrição do empregador
items[].employer_registration_number	Sim	Número de inscrição do empregador
items[].contract_number	Sim	Contrato averbado
items[].debt_balance_amount	Sim	Saldo devedor em NUMERO(16,2)

Acima de 150 itens a Dataprev recusa a requisição inteira.

A chave de duplicidade é o contrato mais o vínculo, não o contrato isolado — o mesmo contract_number pode aparecer em dois itens se a matrícula for diferente. Itens realmente repetidos são recusados com 400 antes do envio, porque a Dataprev descartaria a lista completa.

Processamento parcial

Um 200 não significa que todos os itens passaram. É obrigatório conferir failures[].

Antes de chamar a Dataprev, a Onz filtra os itens cujo contrato não está averbado aqui, pertence a outra conta ou tem vínculo divergente. Só o restante é enviado. O campo source diz onde o item foi recusado:

source	Significado
ATLAS	Recusado pela Onz, antes do envio
DATAPREV	Enviado e recusado pela Dataprev

Resposta

{
  "data": {
    "submitted_count": 1,
    "success_count": 1,
    "failure_count": 2,
    "recorded_count": 1,
    "successes": [
      {
        "contract_number": "CTR0001",
        "code": "BD",
        "message": "Inclusão efetuada com sucesso"
      }
    ],
    "failures": [
      {
        "contract_number": "CTR0002",
        "code": "HY",
        "message": "Contrato não averbado nesta plataforma.",
        "source": "ATLAS"
      },
      {
        "contract_number": "CTR9999",
        "code": "HY",
        "message": "Contrato não averbado nesta plataforma.",
        "source": "ATLAS"
      }
    ]
  }
}

Campo	Descrição
submitted_count	Itens efetivamente enviados à Dataprev
success_count	Itens aceitos
failure_count	Itens recusados, somando os dois source
recorded_count	Itens gravados no histórico dos contratos

Se todos os itens forem recusados no filtro local, a Dataprev não é chamada: successes vem vazio e tudo aparece em failures.

Erros relevantes

HTTP	Situação
400	Lista vazia, acima de 150 itens ou com item duplicado
403	Conta sem a liberação de empréstimo consignado