# Slflo reference connector (Kotlin)

A complete ERP connector for the Slflo integration API, small enough to read in one sitting.
It is a cleaned copy of the connector Slflo's own build runs end to end against the API (a
pilot day of orders, invoices, payments and returns; a lost answer, a 429, a revoked token and
a lost cursor), so every rule in it is one the API holds you to.

| File | What it does |
|---|---|
| `SlfloClient.kt` | Settings, and the call policy: stop on 401, wait `Retry-After` on 429, back off on 5xx and on a lost answer, an `Idempotency-Key` on every write |
| `Staging.kt` | The staging table keyed `(id, version, line)` and the per-stream watermark |
| `ErpBooks.kt` | What the connector needs from your ERP, and an in-memory stand-in |
| `OrderImportJob.kt` | Orders → one sales order each: pull by version, stage, find before create, ack; `recover()` from `filter[ack]=pending` |
| `DocumentJobs.kt` | Payments and returns into journals by version (so reversals come back); invoices by the `seq` counter |
| `MasterDataPushJob.kt` | Units, price list, items, prices and customers pushed by your keys |
| `Main.kt` | One scheduled run of all of the above |

## Run it against the sandbox

You need JDK 21 and Gradle 8 or later, and a sandbox token (`sfi_live_…`, like every token
the console issues) — see <https://docs.slflo.com/developers/sandbox/>.

```sh
export SLFLO_TOKEN='sfi_live_…'
gradle run
```

The hosted sandbox is in ERP mode API, so order acks work there; a company in another mode
answers `409 ERP_MODE_NOT_API`. Its day's two orders are already delivered, so a run books no
sales order until a new order waits — ask us for one.

## Make it yours

1. Implement `ErpBooks` with your ERP's services: find a sales order by its customer
   reference, create one, post a journal, read customers and items.
2. Replace `StagingTable` and `Watermarks` with tables in your ERP's database. Keep the unique
   index on `(order id, version, line number)`.
3. Keep the token in encrypted settings, never in source control.
4. Schedule `Main` (or each job on its own) every few minutes.

The guides at <https://docs.slflo.com/developers/guides/pull-connector/> explain each step.