Waafir
Esta página es una traducción automática pendiente de revisión humana. Puede contener errores.

NDJSON masivo

La superficie de NDJSON masivo acepta hasta diez mil filas en una sola solicitud HTTP síncrona, aplica a cada fila la validación con los mismos esquemas que usan las rutas de registro único y devuelve un informe de errores a nivel de fila. Úsela para lotes de cierre de jornada que caben holgadamente en una sola solicitud HTTP; para cargas históricas o lotes más grandes use importaciones asíncronas.

El formato de transmisión es JSON delimitado por saltos de línea: un objeto JSON válido por línea, sin coma final, sin array envolvente y sin sobre de apertura o cierre. Las líneas en blanco entre objetos se aceptan y se omiten.

Rutas

Hay una ruta por entidad. El esquema aplicado a cada línea corresponde a la entidad de la URL.

MétodoRutaEntidad
POST/api/v1/monitoring/loan/bulk/borrowersborrower
POST/api/v1/monitoring/loan/bulk/loansloan
POST/api/v1/monitoring/loan/bulk/scheduled-repaymentsscheduled_repayment
POST/api/v1/monitoring/loan/bulk/actual-paymentsactual_payment
POST/api/v1/monitoring/loan/bulk/collateralcollateral
POST/api/v1/monitoring/loan/bulk/collateral-valuationscollateral_valuation

Cada línea del cuerpo de la solicitud debe ser un objeto JSON válido que cumpla el esquema de la entidad tal como se documenta en la página de registro único. Los esquemas son idénticos; solo cambia el sobre de transmisión.

Solicitud

POST /api/v1/monitoring/loan/bulk/loans HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/x-ndjson
Idempotency-Key: <opaque-key>

Encabezados y parámetros de consulta:

NombrePosiciónObligatorioNotas
AuthorizationencabezadosíPAT de tipo Bearer.
Content-TypeencabezadonoSe recomienda application/x-ndjson; también se acepta application/json.
Idempotency-KeyencabezadonoMuy recomendado para lotes de producción.
?dryRun=trueconsultanoEjecuta la validación y omite las escrituras.
?portfolioId=<UUID>consultasíEl ancla de inquilino del lote; si falta o está mal formado devuelve 400 portfolio_id_required.

La superficie masiva lee portfolioId únicamente de la cadena de consulta; el campo homónimo del cuerpo de cada fila se ignora en la capa envolvente del lote. Todas las filas del cuerpo deben hacer referencia a la misma cartera.

El cuerpo es la propia carga útil NDJSON — codificada en UTF-8 y terminada con un único salto de línea. Se rechazan las solicitudes con más de diez mil líneas o con cuerpos de más de diez megabytes — consulte los límites de tamaño.

Contrato por fila

Cada fila se valida de forma independiente frente al esquema de la entidad. Por fila se aplican las mismas reglas que en una escritura de registro único:

  • Cada fila debe llevar su propio UUID id y su portfolioId. Los ID proporcionados por el llamante son la clave de deduplicación por fila.
  • Todo el lote comparte la Idempotency-Key del nivel de solicitud. Consulte idempotencia más abajo.
  • metadata es por fila. Una fila puede llevar sus propios metadatos de transferencia directa; la plataforma los persiste tal cual.
  • Las reglas de moneda, fechas, enumeraciones e importes son idénticas a las de registro único. Una fila que no supera la validación aparece como una entrada en el informe de errores por fila con code: "validation_failed".

Una fila que no supera la validación no interrumpe el lote — el fallo aparece como una entrada en errors[] y el resto de las filas se sigue procesando.

Respuesta

Se devuelve 200 OK para cada lote cuya solicitud se haya podido analizar, independientemente de cuántas filas individuales se hayan procesado correctamente o hayan fallado. El cuerpo de la respuesta contiene el informe completo por fila:

{
  "totalRows": 4,
  "succeeded": 3,
  "failed": 1,
  "bronzeSubmissionId": "1a2b3c4d-5e6f-7890-abcd-ef0123456789",
  "reused": false,
  "errors": [
    {
      "rowNumber": 2,
      "code": "fk_violation",
      "message": "borrowerId references a borrower that does not exist in this portfolio"
    }
  ]
}
CampoTipoDescripción
totalRowsenteroEl número de líneas no vacías del cuerpo.
succeededenteroEl número de filas almacenadas.
failedenterototalRows - succeeded.
bronzeSubmissionIdUUIDEl id del registro de envío único que abarca todo el cuerpo NDJSON. Ausente en una respuesta de ?dryRun=true.
reusedbooleanoPresente y true solo cuando una Idempotency-Key coincidió con un lote anterior y la respuesta se reconstruyó; ausente en caso contrario.
dryRunbooleanoPresente y true solo en una respuesta de ?dryRun=true; ausente en caso contrario.
errors[].rowNumberenteroÍndice de línea, empezando en 1, dentro del cuerpo de la solicitud.
errors[].codeenumvalidation_failed | unique_violation | fk_violation | check_violation | db_error.
errors[].messagecadenaResumen legible por humanos; para validation_failed, los errores de validación se condensan en una sola frase.

La forma del error por fila solo contiene rowNumber, code y message. No hay un array fieldErrors por fila ni un rawRow por fila — el NDJSON original se conserva tal cual en el registro de envío en lugar de devolverse en la respuesta.

Un valor de succeeded igual a 0 no es una respuesta de error — el lote se analizó y la plataforma procesó cada fila; el informe le indica que no se registró nada. Un lote realmente fallido (NDJSON mal formado en todo el cuerpo, cuerpo demasiado grande, cartera desconocida) devuelve 4xx según la tabla siguiente.

Códigos de estado

Los sobres de error de nivel superior de esta superficie usan valores de code en minúsculas, distintos de los códigos en mayúsculas que usan las rutas de registro único. Los dos espacios de códigos están separados de forma intencionada.

EstadoSobreDesencadenante
200 OKinforme por filaLote procesado; resultados por fila en errors[].
400 Bad Request{ error, code: "invalid_body", errors: [...] }El cuerpo de la solicitud no pudo leerse como texto.
400 Bad Request{ error, code: "portfolio_id_required", fieldErrors: [...] }Falta ?portfolioId=<UUID> o no es un UUID válido.
400 Bad Request{ error, code: "invalid_json" }Incluido dentro del informe por fila, fila a fila — una fila que no es JSON válido recibe una entrada code: "invalid_json" en errors[]. El lote en su conjunto sigue devolviendo 200.
404 Not Found{ error, code: "portfolio_not_found", fieldErrors: [...] }El ?portfolioId= no existe como cartera activa en su organización.
413 Payload Too Large{ error, code: "batch_too_large", fieldErrors: [...] }Consulte los límites de tamaño.

Límites de tamaño

La superficie masiva limita las cargas útiles al menor de estos valores:

  • Diez mil líneas no vacías. Las filas que superan ese número se rechazan antes de que comience el procesamiento.
  • Diez megabytes de cuerpo de solicitud.

Una solicitud que supera cualquiera de los dos límites recibe 413 Payload Too Large:

{
  "error": "batch payload exceeds 10485760 bytes; use the async import endpoint at /api/v1/monitoring/loan/imports",
  "code": "batch_too_large",
  "fieldErrors": [{ "path": "(body)", "message": "max 10485760 bytes" }]
}

El sobre del límite de bytes y el del límite de filas usan ambos code: "batch_too_large"; error y fieldErrors[].message distinguen el desencadenante. La vía canónica de recuperación es enviar la misma carga útil por el flujo de importaciones asíncronas, que carga el archivo directamente y lo procesa de forma asíncrona sin límite de filas.

Idempotencia

La superficie masiva deduplica frente a Idempotency-Key en el nivel del sobre del lote. El funcionamiento:

  • Primera llamada con la clave K. El cuerpo se registra como un único envío, se procesa cada fila y el informe por fila se conserva con el envío.
  • Segunda llamada con la clave K, mismo cuerpo. No hay un segundo registro ni una nueva inserción. La plataforma devuelve el informe original con reused: true.
  • Segunda llamada con la clave K, cuerpo diferente. La plataforma sigue devolviendo el informe original — el envío original es la fuente de verdad. Un nuevo POST con un cuerpo corregido debe usar una clave diferente.

Esto significa que un cliente que reintenta tras un corte de red está a salvo aunque el cuerpo de la segunda solicitud se haya truncado o modificado en tránsito — la plataforma devuelve los resultados por fila del primer procesamiento correcto.

Registro de envío

Cada solicitud masiva se registra como un solo envío que contiene todo el cuerpo NDJSON, no uno por fila. Una fila reintentada nunca se almacena dos veces, porque un externalId es único dentro de una cartera entre las filas activas.

El bronzeSubmissionId de la respuesta es el id del registro de envío; persístalo junto con su registro de envío local para la auditoría y la conciliación.

Ejemplo de cURL

cat <<'EOF' > batch.ndjson
{"id":"a1...","portfolioId":"ddf63d12-1234-5678-9abc-def012345678","borrowerId":"b1...","externalId":"L-001","principalAmount":"5000","currencyCode":"USD","interestRateApr":"0.18","disbursementDate":"2026-01-15","termMonths":12,"repaymentFrequency":"monthly","status":"active"}
{"id":"a2...","portfolioId":"ddf63d12-1234-5678-9abc-def012345678","borrowerId":"b2...","externalId":"L-002","principalAmount":"3000","currencyCode":"USD","interestRateApr":"0.20","disbursementDate":"2026-01-15","termMonths":24,"repaymentFrequency":"monthly","status":"active"}
{"id":"a3...","portfolioId":"ddf63d12-1234-5678-9abc-def012345678","borrowerId":"b3...","externalId":"L-003","principalAmount":"7500","currencyCode":"USD","interestRateApr":"0.22","disbursementDate":"2026-01-15","termMonths":18,"repaymentFrequency":"monthly","status":"active"}
EOF

curl -X POST "https://app.waafir.io/api/v1/monitoring/loan/bulk/loans?portfolioId=ddf63d12-1234-5678-9abc-def012345678" \
  -H "Authorization: Bearer $WAAFIR_PAT" \
  -H "Content-Type: application/x-ndjson" \
  -H "Idempotency-Key: nightly-2026-01-15-loans" \
  --data-binary @batch.ndjson

Cuándo elegir NDJSON masivo frente a importaciones asíncronas

Elija NDJSON masivo cuando:

  • Su lote cabe en diez mil filas y diez megabytes.
  • Desea un informe inmediato por fila en la respuesta HTTP.
  • Puede tolerar una solicitud HTTP de larga duración — los lotes masivos suelen completarse en pocos segundos, pero un lote grande con muchas búsquedas de FK en la base de datos puede tardar más.

Elija importaciones asíncronas cuando:

  • Su lote supera cualquiera de los dos límites de tamaño.
  • Está cargando un archivo histórico de pagos, reembolsos programados o prestatarios — las cargas históricas típicas alcanzan millones de filas.
  • Desea conservar la opción de cancelar una carga en curso.