Skip to main content

​
Endpoints para descargar fallos

Alias legacy CSV entidades: GET /entities/automatic/bulk/imports/{jobId}/failures.csv.
  • …/failures.csv → archivo CSV descargable (Content-Type: text/csv)
  • …/failures → JSON (Content-Type: application/json)

​
Modelo de tres capas

Cada fallo por fila incluye code (máquina) y message (humano). Jobs legacy pueden tener solo error en texto libre; la API normaliza al leer.

​
Tres resultados posibles por fila (entidades)

​
Duplicate por taxId — el caso que confunde

Bulk manual (default): duplicateTaxIdPolicy: skip_existing.
  • Mismo taxId + mismo type ya existe → skipped_existing, código SKIPPED_DUPLICATE_TAX_ID
  • No aparece en failures.csv (no es error)
  • Contador: skippedExisting en historial unificado
Bulk automático:
  • Entidad principal ya existía → skipped_existing
    • refresh: false: SKIPPED_ENTITY_ALREADY_EXISTS — sin re-enriquecimiento
    • refresh: true: SKIPPED_ENTITY_ALREADY_EXISTS_REFRESHED — creación omitida, re-enriquecimiento ejecutado
Cuándo sí es fallo (failed):

​
Códigos de fallo por fila (failures[] / failures.csv)

​
Códigos de skip (skips[] — solo entidades, no es fallo)

Matriz de riesgo / reglas de negocio: la ejecución de reglas ocurre después de crear la fila. Los resultados de reglas no aparecen en failures.csv / JSON failures[] y no revierten la fila. Usá alertas, score de riesgo y timelines de auditoría.

​
Códigos de job completo (jobFailure)

​
Matriz de escenarios (FAQ cliente)

​
Escenarios reproducibles (pruebas)

User events (fallos por fila más simples): CSV válido + mapping; una fila con campo requerido vacío → GET …/user-event-jobs/{jobId}/failures. Entidades (manual): crear entidad con external_id=X, importar otra fila con mismo external_id → DUPLICATE_EXTERNAL_ID. Transacciones (job-level): validateExistingEntity=true + originExternalId=DOES_NOT_EXIST → job failed, jobFailure.code=INVALID_ENTITY_REFERENCES. Transacciones (row-level): batchErrorHandling=continue_collect_errors + filas válidas mezcladas con violaciones de constraint → entradas en endpoint de fallos.

​
Límites

  • Máx. 500 fallos por fila persistidos por job batch de transacciones (CSV + JSON pueden truncar; JSON expone truncated + failuresTotal).
Reporte completo por email (entidades): todas las filas (created, skipped_existing, failed) con columna code. Ver también: Importaciones masivas — overview.