Skip to content

Jtl

service_jtl — Endpoints: JTL

Base prefix: /api/v1/jtl

Core routes for JTL integration, credential management, inbound creation and evaluation downloads.

Auth / credential management

  • GET /oauth/callback?code=...&state=...
  • Called by JTL after user consent. Exchanges code for tokens and persists them to the credential record referenced by state.

  • Example: GET /api/v1/jtl/oauth/callback?code=...&state=...

  • GET /auth_url/{credential_id}

  • Returns an authorization URL for the given credential record (user must visit it and approve access).

  • Response: {"auth_url": "https://..."}

  • POST /credentials/

  • Create a new JTL credential. Body model: JTLCredentialsCreate (see backend/service_jtl/app/models/jtl.py).

  • Example body:

    {
  "name": "Inbound JTL",
  "client_id": "<client-id>",
  "client_secret": "<secret>",
  "callback_url": "https://dashboard.example/api/v1/jtl/oauth/callback",
  "scopes": ["ffn.merchant.read"]
}

  • PUT /credentials/{credential_id} — Update credential metadata (JTLCredentialsUpdate).

  • DELETE /credentials/{credential_id} — Remove a credential.
  • GET /credentials/ — List stored credentials.
  • POST /credentials/{credential_id}/toggle-active — Toggle which credential is active for background jobs.
  • GET /credentials/{credential_id}/get_token — Ensure a bearer token exists (exchange code if necessary) and return it.
  • GET /credentials/{credential_id}/is_valid — Test token validity and attempt refresh if needed.

Processing endpoints

  • POST /run-check/
  • Run the checker processing pipeline for a provided RunCheckRequest (fields: start_date, end_date, delivery_time_add).
  • Uses Jtl_Manager.process_checkers() and writes a JSON eval result to evals/.

Example request body:

{
  "start_date": "2026-05-01T00:00:00",
  "end_date": "2026-05-31T23:59:59",
  "delivery_time_add": 2
}

  • POST /create-inbounds/ — Create inbounds for a given date (defaults to yesterday Berlin time). Accepts { "date": "YYYY-MM-DD" } in the JSON body or query.

  • GET /eval/download/{filename} — Download eval JSON files produced by run-check.

  • GET /eval/list — List available eval files in evals/.

Cron management

  • POST /cron/start?schedule=<cron_expr> — Create/replace scheduled cron job for inbound monitoring (uses CronJobManager.upsert_job).
  • POST /cron/stop — Stop the cron job.
  • GET /cron/status — Return scheduling metadata (last run, next run) persisted by CronJobManager.

WebSocket

  • WS /ws — Real-time socket used for progress and callback notifications (e.g., OAuth success alerts).

Implementation

Operational notes

  • Authentication: most endpoints are protected by JWT in main.py's middleware; callback and public routes are exempted via PUBLIC_ENDPOINTS.
  • create-inbounds and run-check are used by the scheduler and by manual API calls; returned results are stored in evals/ for auditing and download.
  • process_inbounds contains retry and error-handling heuristics: missing products are removed and retried, and the inbound number may be retried with a (2) suffix if JTL rejects it.