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)

​
Ids redondeados por planilla

Abrir un CSV en Excel o Google Sheets hace que los ids numéricos largos (CPF, CNPJ, números de cuenta) se lean como números y se re-exporten redondeados: 50400000000000 queda como 5,04E+13. Sobreviven solo tres cifras significativas, así que el id original no se puede recuperar del valor. Las filas de batch de transacciones se rechazan con SCIENTIFIC_NOTATION_ID cuando alguno de externalId, originExternalId, destinationExternalId, originTaxId o destinationTaxId coincide con ese patrón. El message del fallo nombra los campos afectados, y identifier_type en failures.csv los lista. Para evitarlo, exportá el CSV manteniendo las columnas de id como texto (en Sheets: Archivo → Descargar → CSV sin abrir las columnas como números; en Excel: poné formato Texto en la columna antes de importar, o usá Datos → Desde texto/CSV marcando las columnas de id como Texto).

​
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 abort): validateExistingEntity=true + batchErrorHandling=rollback_all + originExternalId=DOES_NOT_EXIST → job failed, jobFailure.code=INVALID_ENTITY_REFERENCES, detalle en failures.csv. Transacciones (row-level skip): batchErrorHandling=continue_collect_errors + refs inválidas mezcladas con válidas → filas válidas creadas; inválidas en ENTITY_NOT_FOUND / endpoint de fallos. Transacciones (row-level insert): batchErrorHandling=continue_collect_errors + filas válidas mezcladas con violaciones de constraint → entradas en endpoint de fallos.

​
Límites

  • El sample JSON de fallos por fila está limitado a 500 (truncated + failuresTotal), hidratado desde failures.csv en S3 cuando existe (jobs legacy pueden caer a DB). La descarga CSV es el listado completo.
Reporte completo por email (entidades): todas las filas (created, skipped_existing, failed) con columna code. Ver también: Importaciones masivas — overview.