EPepilot
erp-imports

executeErpImport

Changed on

Confirm and run the write phase of a validated import. Only a READY job may be executed; any other status returns 409. The verdict is re-checked against live inputs first: if the mapping or an entity schema changed since the check, this returns 409 VALIDATION_STALE and leaves the verdict untouched for :validate to re-form.

post/v2/erp/imports/{importId}:execute

Request

  • Base URL
    https://integration-toolkit.sls.epilot.io
  • URL
    https://integration-toolkit.sls.epilot.io/v2/erp/imports/{importId}:execute
  • Auth
    HTTP bearer

Path parameters

importIdstring required

Request body

ack_warningsboolean

The caller has seen validation.issues and accepts them. Required when validation.warnings is greater than 0; ignored otherwise.

Response

Execution started

import_idstring required

imp_{ULID} — time-ordered, also used as the job's correlation_id.

org_idstring required
created_bystring
integration_idstring

The integration owning the chosen use case. Absent until the first :validate.

use_case_slugstring

The inbound use case whose mapping drives both phases. Absent until the first :validate, and MUTABLE — re-validating with a different use case replaces it.

format'csv' | 'xlsx' required
status'PENDING' | 'VALIDATING' | 'READY' | 'PROCESSING' | 'IMPORTED' | 'FAILED' | 'CANCELLING' | 'CANCELLED' required

PENDING → VALIDATING → READY → PROCESSING → IMPORTED, with FAILED reachable from any working status, and CANCELLING → CANCELLED reachable from VALIDATING or PROCESSING via :abort. Only IMPORTED and CANCELLED are terminal. READY and FAILED both accept a further :validate, which is how a wrong use case is corrected without re-uploading the file. IMPORTED means every row was handed to the platform, not that the platform finished — per-row outcomes live in monitoring, filtered by correlation_id. A file that fails validation is FAILED with error.code = VALIDATION_BLOCKED. READY is legitimately idle for as long as the user takes to confirm, so it carries no running work and never goes stale. CANCELLING is transient and cooperative: the abort has been recorded but the worker only notices at its next batch boundary. Rows already published stay published — a stop is not a rollback.

size_bytesinteger

Size of the uploaded file, recorded at registration. Present on every job registered from version 1.17.0 onwards; absent on older rows, which were written before it was captured.

column_countinteger

How many effective columns the file's header yielded — the length of the preview.columns returned at registration, kept so a job loaded later can still describe its file. The preview ROWS are deliberately not stored: they are a sample for the person about to choose a mapping, not job state. Present on every job registered from version 1.17.0 onwards.

correlation_idstring

Scopes this run in monitoring. Always equal to import_id.

activity_idstring
created_atstring date-time required
updated_atstring date-time required

Example response

{
  "validation": {
    "entity_details": [
      {
        "condition_attributes": [
          "grid_area"
        ],
        "version_attribute": "valid_from"
      }
    ]
  }
}

Changes

  • b7eb225e41b3Revision changes
    • warning

      added the new VALID_FROM_NOT_MAPPED enum value to the /// response property for the response status

  • 57a11671a74dRevision changes
    • warning

      added the new UNIQUE_ID_NOT_IN_SCHEMA enum value to the /// response property for the response status

    • info

      added the optional property ///// to the response with the status