Skip to main content
This page describes how integrations must:
  1. Detect Export Jobs that are ready for processing
  2. Claim a single Export Job to begin processing
This is the first step in the Export Integration Workflow.

​
Implementation

See the corresponding how-to article for API usage and step-by-step instructions:

​
Conceptual Model

Export processing begins in two distinct phases:
PhaseResponsibility
DetectionIdentify Export Jobs available for processing
ClaimingTake ownership of a single Export Job
These phases must remain logically separate:
  • Detection must not modify state
  • Claiming is the first state-changing action

​
Detect Export Jobs

​
Purpose

Detection identifies Export Jobs that are ready to be processed. It must:
  • Detect newly created Export Jobs
  • Identify jobs eligible for processing
  • Avoid modifying job state

​
Detection Mechanisms

Integrations may use one of the following:

​
Webhooks (preferred)

  • Subscribe to export-job.created
  • Trigger detection when event is received

​
Polling (fallback)

  • Periodically call GET /v3/export-jobs
  • Use controlled intervals (e.g. every few minutes)

​
Ad Hoc Trigger (optional)

  • Exposes a user-initiated action (e.g. a button in the integration UI) that immediately runs the same polling flow as schedule polling
  • Used in combination with scheduled polling — not as a standalone mechanisms
  • Useful when a user wants to check for pending jobs without waiting for the next scheduled interval

​
Eligible Job States

Only the following statuses are valid for detection:
  • pending
  • in_progress

​
Sequential Processing Requirement

When multiple jobs exist:
  • Always select the oldest job
  • Process jobs one at a time
  • Do not process jobs in parallel
This prevents:
  • race conditions
  • duplicate exports
  • inconsistent accounting state

​
Claim Export Job

​
Purpose

Claiming an Export Job:
  • Signals that the integration is starting processing
  • Prevents multiple workers processing the same job
  • Establishes ownership and traceability

​
When to Claim

An Export Job must only be claimed after:
  • The job has been discovered
  • Pre-processing checks (e.g. validation readiness) have completed
Claiming too early can lead to:
  • failed exports
  • stuck jobs
  • inconsistent state

​
How Claiming Works

To claim a job:
  1. Select the oldest eligible job
  2. Send a started event via:
{
  "event": "started",
  "jobId": "<jobId>"
}

​
Result of Claiming

After a successful claim:
  • Job status transitions to in_progress
  • The integration becomes responsible for processing
  • Export Items can now be fetched

​
Concurrency & Conflict Handling

In distributed systems, multiple workers may attempt to claim the same job. If claiming fails due to status conflict:
  • Treat this as expected behaviour
  • Do not retry aggressively
  • Restart detection and select the next eligible job

​
Key Rules

  • Detection must be read-only
  • Only one job may be processed at a time
  • Always process the oldest eligible job
  • Claiming is the first state-changing action
  • Claiming must be done using the started event

​
Processing Order

​
Upstream Dependencies

  • Export Items queued in Pleo Web App
  • Integration authentication configured
  • Webhooks, scheduled polling, or ad hoc trigger implemented

​
Downstream Dependencies

  • Pre-export validation
  • Export Item retrieval
  • AS/ERP processing workflow

​
What Comes Next?