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

Validar una carga con dry-run antes de confirmar los datos

Esta receta muestra cómo usar el endpoint de importación asíncrona como validador sin efectos secundarios antes de confirmar los datos. El flujo es idéntico al de la receta de importación masiva —iniciar, cargar, confirmar, sondear— con un único parámetro cambiado: dryRun: true. El worker ejecuta todo el proceso de validación, suma las filas validadas al total de filas correctas y nunca escribe una fila.

Cuándo usarlo

El dry-run es la herramienta adecuada cuando quiere saber si un archivo que ha generado tiene la forma correcta antes de confiarle un envío diario. Usos habituales:

  • La primera vez que conecta su exportación de la cinta de préstamos y quiere confirmar que la forma del JSON coincide con lo que Waafir espera.
  • Una ejecución canario nocturna sobre las primeras 100 filas de un archivo nuevo antes de enviar el resto.
  • Tras un cambio de esquema interno por su parte, para verificar que el formato enviado se sigue analizando sin problemas.

El dry-run ejecuta los mismos validadores que la ruta de ingesta real, por lo que superar un dry-run es una garantía sólida de que el mismo archivo enviado de verdad se registrará correctamente. La asimetría: un dry-run no pone a prueba las restricciones de unicidad de la base de datos (ya que no se escribe ninguna fila), por lo que una ejecución real aún puede fallar por ID externos duplicados que el dry-run aceptó. Concilie por ID externo tras la ejecución real si necesita esa garantía.

La receta

# curl — dry-run validation
set -euo pipefail

PAT="${WAAFIR_PAT}"
BASE_URL="${WAAFIR_BASE_URL:-https://app.waafir.io}"
NDJSON_FILE="loans-canary.ndjson"

# Step 1 — start an import with dryRun=true. The query parameter and
# the body field are both accepted; the query is the curl-friendly form.
START=$(curl -fsS -X POST "${BASE_URL}/api/v1/monitoring/loan/imports?dryRun=true" \
  -H "Authorization: Bearer ${PAT}" \
  -H "Content-Type: application/json" \
  -d "$(cat <<JSON
{
  "kind": "loan",
  "filename": "${NDJSON_FILE}",
  "sizeBytes": $(stat -c%s "${NDJSON_FILE}")
}
JSON
)")

IMPORT_ID=$(echo "$START" | jq -r .importId)
UPLOAD_URL=$(echo "$START" | jq -r .uploadUrl)

# Step 2 — upload the file, applying the signed-in headers the start
# response returned (same shape as a real import — see the
# async-import recipe for the full rationale).
HEADER_ARGS=$(echo "$START" | jq -r '.headers | to_entries[] | "-H \"\(.key): \(.value)\""')
eval curl -fsS -X PUT --data-binary @"\"${NDJSON_FILE}\"" $HEADER_ARGS "\"${UPLOAD_URL}\""

# Step 3 — commit; the worker enqueues but the row processor short-circuits.
curl -fsS -X POST "${BASE_URL}/api/v1/monitoring/loan/imports/${IMPORT_ID}/commit" \
  -H "Authorization: Bearer ${PAT}"

# Step 4 — poll. Terminal status + dryRun:true means the file is structurally valid.
while :; do
  BODY=$(curl -fsS "${BASE_URL}/api/v1/monitoring/loan/imports/${IMPORT_ID}" \
    -H "Authorization: Bearer ${PAT}")
  STATUS=$(echo "$BODY" | jq -r .status)
  echo "dry-run ${IMPORT_ID}: ${STATUS}"
  case "${STATUS}" in
    succeeded|partial|failed|cancelled) break ;;
  esac
  sleep 5
done

# At terminal, inspect the row counts. `dryRun: true` should be present.
echo "$BODY" | jq '{status, dryRun, rowCountProcessed, rowCountSucceeded, rowCountFailed}'
// TypeScript — dry-run validation
import { readFileSync, statSync } from "node:fs";

const PAT = process.env.WAAFIR_PAT!;
const BASE_URL = process.env.WAAFIR_BASE_URL ?? "https://app.waafir.io";
const NDJSON_FILE = "loans-canary.ndjson";

const auth = { Authorization: `Bearer ${PAT}` };

// Step 1 — start with dryRun=true via the body. (?dryRun=true is also accepted.)
const startRes = await fetch(`${BASE_URL}/api/v1/monitoring/loan/imports`, {
    method: "POST",
    headers: { ...auth, "Content-Type": "application/json" },
    body: JSON.stringify({
        kind: "loan",
        filename: NDJSON_FILE,
        sizeBytes: statSync(NDJSON_FILE).size,
        dryRun: true,
    }),
});
if (!startRes.ok) throw new Error(`start failed: ${startRes.status} ${await startRes.text()}`);
const { importId, uploadUrl, headers: uploadHeaders } = (await startRes.json()) as {
    importId: string;
    uploadUrl: string;
    headers: Record<string, string>;
};

// Step 2 — upload, applying the signed-in headers.
const putRes = await fetch(uploadUrl, {
    method: "PUT",
    headers: uploadHeaders,
    body: readFileSync(NDJSON_FILE),
});
if (!putRes.ok) throw new Error(`upload failed: ${putRes.status}`);

// Step 3 — commit.
const commitRes = await fetch(`${BASE_URL}/api/v1/monitoring/loan/imports/${importId}/commit`, {
    method: "POST",
    headers: auth,
});
if (!commitRes.ok) throw new Error(`commit failed: ${commitRes.status} ${await commitRes.text()}`);

// Step 4 — poll until terminal.
const TERMINAL = new Set(["succeeded", "partial", "failed", "cancelled"]);
let final: { status: string; dryRun: boolean; rowCountProcessed: number; rowCountSucceeded: number; rowCountFailed: number };
while (true) {
    const statusRes = await fetch(`${BASE_URL}/api/v1/monitoring/loan/imports/${importId}`, { headers: auth });
    final = (await statusRes.json()) as typeof final;
    console.log(`dry-run ${importId}: ${final.status}`);
    if (TERMINAL.has(final.status)) break;
    await new Promise((r) => setTimeout(r, 5_000));
}

console.log({
    status: final.status,
    dryRun: final.dryRun,
    rowCountProcessed: final.rowCountProcessed,
    rowCountSucceeded: final.rowCountSucceeded,
    rowCountFailed: final.rowCountFailed,
});
# python — dry-run validation
import os
import time
import requests
from pathlib import Path

PAT = os.environ["WAAFIR_PAT"]
BASE_URL = os.environ.get("WAAFIR_BASE_URL", "https://app.waafir.io")
NDJSON_FILE = Path("loans-canary.ndjson")

auth = {"Authorization": f"Bearer {PAT}"}

# Step 1 — start with dryRun=True. The body field is the structured form;
# `?dryRun=true` on the query string is equivalent for curl ergonomics.
start = requests.post(
    f"{BASE_URL}/api/v1/monitoring/loan/imports",
    headers={**auth, "Content-Type": "application/json"},
    json={
        "kind": "loan",
        "filename": NDJSON_FILE.name,
        "sizeBytes": NDJSON_FILE.stat().st_size,
        "dryRun": True,
    },
    timeout=30,
)
start.raise_for_status()
payload = start.json()
import_id = payload["importId"]
upload_url = payload["uploadUrl"]
upload_headers = payload["headers"]

# Step 2 — upload, applying the signed-in headers.
with NDJSON_FILE.open("rb") as fh:
    requests.put(upload_url, data=fh, headers=upload_headers, timeout=300).raise_for_status()

# Step 3 — commit.
requests.post(
    f"{BASE_URL}/api/v1/monitoring/loan/imports/{import_id}/commit",
    headers=auth,
    timeout=30,
).raise_for_status()

# Step 4 — poll until terminal.
terminal = {"succeeded", "partial", "failed", "cancelled"}
while True:
    body = requests.get(
        f"{BASE_URL}/api/v1/monitoring/loan/imports/{import_id}",
        headers=auth,
        timeout=30,
    ).json()
    print(f"dry-run {import_id}: {body['status']}")
    if body["status"] in terminal:
        break
    time.sleep(5)

print({
    "status": body["status"],
    "dryRun": body["dryRun"],
    "rowCountProcessed": body["rowCountProcessed"],
    "rowCountSucceeded": body["rowCountSucceeded"],
    "rowCountFailed": body["rowCountFailed"],
})

Qué verificar

El objeto de estado final incluye dryRun: true para que pueda confirmar que el worker se ejecutó en modo dry-run. Los recuentos de filas tienen un significado específico en dry-run:

  • rowCountSucceeded es el número de filas que superaron la validación: exactamente el número que se habría registrado como filas activas en una ejecución real.
  • rowCountFailed es el número de filas que no superaron la validación. Recórralas con la receta de inspección de fallos parciales: el endpoint de errores paginados funciona exactamente igual en dry-run.
  • rowCountProcessed es la suma: todas las filas que el worker tuvo en cuenta.

Si su archivo no tiene ninguna fila fallida en dry-run, el mismo archivo enviado de verdad (sin dryRun: true) se registrará sin errores, salvo por la asimetría de unicidad de la base de datos indicada anteriormente.