Importação de dívidas

Visao geral

Fluxo em duas etapas:

1. Upload do CSV (staging).
2. Mapeamento e commit para criar dividas reais.

• Base: https://api.ascendteam.cloud/api/v1/debts
• Autenticacao: requer sessao/credenciais validas do Better Auth (ver /docs/api/auth).

CSV suportado

O parser aceita cabecalhos comuns de bancos. Exemplos reconhecidos:

• Emissao: data_emissao, emissao, issue_date
• Vencimento: vencimento, data_vencimento, due_date
• Valor: valor, valor_total, amount
• Descricao: descricao, historico, description
• Cliente: cliente, nome_cliente, debtor
• Servico: servico, categoria_servico, service

Campos obrigatorios para considerar a linha valida:

• data_emissao
• valor

Endpoints

POST /import-csv

Faz upload do CSV e cria o lote (staging).

Query

• source (string, opcional)
• delimiter (string, opcional; default ",")
• saveTemplate (boolean, opcional)

Body

• multipart/form-data com campo file

Resposta 201

• Lote criado com contadores (totalRows, validRows, invalidRows)

GET /imports/:id

Obtém o lote de importacao.

Resposta 200

• Dados do lote e status (PENDING, MAPPED, COMMITTED, FAILED)

GET /imports/:id/rows

Lista as linhas do lote.

Query

• status (PENDING | INVALID | MAPPED | COMMITTED | FAILED, opcional)
• page (number, opcional)
• pageSize (number, opcional)

Resposta 200

• total, page, pageSize, items

PATCH /imports/:id/map

Mapeia as linhas com cliente e servico.

Body

{
  "rows": [
    { "rowId": "uuid", "debtorId": "uuid", "serviceCategoryId": "uuid" }
  ]
}

Resposta 200

• Lote atualizado

PATCH /imports/:id/configuration

Atualiza mapeamento de colunas do lote e reprocessa as linhas.

Body

{
  "columnMapping": {
    "issueDate": "data",
    "description": "title",
    "originalAmount": "valor"
  },
  "saveTemplate": true
}

PATCH /imports/:id/rows/:rowId

Edita uma linha do staging e revalida os campos.

Body

{
  "issueDate": "2026-01-31",
  "originalAmount": 120.5,
  "description": "Consulta de retorno"
}

POST /imports/:id/commit

Cria as dividas reais a partir das linhas mapeadas.

Body

{
  "rowIds": ["uuid"]
}

Se rowIds for omitido, importa todas as linhas mapeadas.

Resposta 200

• Lote atualizado