Integration flow - Connector API

Step 1. Initialize session

curl -X POST https://<host>/api/v1/uploading/initialize-session \
  -H "Authorization: <token>" \
  -H "Client-Id: 42"

Success response:

{ "status": "created", "upload_uuid": "b3f1...c9", "message": "Upload session created" }

Repeated calls

Situation	HTTP	`status`	Action
No active session	`200`	`created`	Use the returned `upload_uuid`
Session in `UPLOADING`	`409`	`already_exists`	Continue with the existing `upload_uuid`
Connector running (`STARTED`)	`409`	`workflow_running`	Wait or call `terminate`
Previous session `DONE`	`200`	`created`	New session; response includes `previous_upload_uuid`

Step 2. Upload entities

curl -X POST https://<host>/api/v1/uploading/b3f1...c9/receipt \
  -H "Authorization: <token>" \
  -H "Client-Id: 42" \
  -H "Content-Type: application/json" \
  -d @payload.json

Payload format: Entity upload.

Step 3. Check session status

curl https://<host>/api/v1/uploading/b3f1...c9/status \
  -H "Authorization: <token>" \
  -H "Client-Id: 42"

Poll GET /status after ingest until can_start_upload = true, and after start-upload until session_status = DONE.

Step 4. Start Connector

curl -X POST https://<host>/api/v1/uploading/b3f1...c9/start-upload \
  -H "Authorization: <token>" \
  -H "Client-Id: 42" \
  -H "Content-Type: application/json" \
  -d '{ "date_from": "2026-06-01", "date_to": "2026-06-29" }'

Date range rules:

date_from ≤ date_to
date_to must be before today
date_from cannot be earlier than the client minimum date configured on the server

If background S3 writes are still running → 409 Upload tasks are still in progress. Retry after upload_tasks_finished = true.

Step 5. Wait for Connector completion

No extra client requests are required. Connector notifies the service automatically. Poll GET /status until session_status = DONE.

Terminate Connector

curl -X POST https://<host>/api/v1/uploading/b3f1...c9/terminate \
  -H "Authorization: <token>" \
  -H "Client-Id: 42"

Available only in STARTED state. The API asks Connector to stop; the session returns to UPLOADING only after Connector sends the completion webhook with is_terminated=true. Poll GET /status until session_status = UPLOADING before uploading again. If the session is not STARTED:

{"detail": "Workflow is not running"}

HTTP status: 404 Not Found.

Delete upload

curl -X POST https://<host>/api/v1/uploading/b3f1...c9/delete \
  -H "Authorization: <token>" \
  -H "Client-Id: 42"

Available only in UPLOADING. File deletion is asynchronous. Start a new cycle with initialize-session. If the session is not UPLOADING (e.g. DONE or STARTED), the API returns 409 Conflict:

{
  "detail": {
    "message": "Invalid upload session status",
    "expected": "UPLOADING",
    "actual": "DONE"
  }
}

For a DONE session, use initialize-session instead of delete.

​Step 1. Initialize session

​Repeated calls

​Step 2. Upload entities

​Step 3. Check session status

​Step 4. Start Connector

​Step 5. Wait for Connector completion

​Terminate Connector

​Delete upload