API Documentation — Oracron Developer Preview

Authentication

All API requests must include a valid API key as a Bearer token in the Authorization header. API keys are generated per workspace in Settings → API access.

Request header

Authorization: Bearer or_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Developer preview note

API keys are not yet self-serve. During the developer preview period, keys are issued on request. Contact us to receive a sandbox key.

Errors & status codes

The API uses standard HTTP status codes. Error responses include a machine-readable error code and a human-readable message.

Error response body

{
  "error": "invoice_not_found",
  "message": "No invoice with id inv_9xk2 exists in this workspace.",
  "status": 404
}

Status	Meaning
200	Success
201	Resource created
400	Bad request — missing or invalid parameters
401	Unauthorised — missing or invalid API key
403	Forbidden — key lacks permission for this resource
404	Not found
422	Unprocessable — file could not be parsed
429	Rate limit exceeded

Rate limits

Limits apply per API key. Current limits during developer preview:

Endpoint group	Limit
Invoice ingest (upload)	60 / hour
Read endpoints (GET)	1000 / hour
Review submission	200 / hour

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Invoices

GET /invoices List all invoices

Returns a paginated list of invoices in your workspace, ordered by upload date descending.

Query parameters

status	optional	Filter by status: `pending` · `mapped` · `review` · `audited` · `dispute`
carrier_id	optional	Filter by carrier entity ID
limit	optional	Max results per page (default 50, max 200)
cursor	optional	Pagination cursor from previous response

Response 200

{
  "data": [
    {
      "id":           "inv_9xk2mR4nQp",
      "carrier_name": "DB Schenker GmbH",
      "invoice_date": "2024-03-01",
      "total_amount": 14220.40,
      "currency":     "EUR",
      "line_count":   24,
      "status":       "audited",
      "uploaded_at":  "2024-03-02T09:14:22Z"
    }
  ],
  "meta": {
    "total":        847,
    "next_cursor":  "eyJpZCI6ImludiJ9"
  }
}

GET /invoices/{id} Get a single invoice

Returns full detail for a single invoice including extracted line summary, audit flags, and processing metadata.

Response 200

{
  "id":              "inv_9xk2mR4nQp",
  "carrier_name":    "DB Schenker GmbH",
  "carrier_id":      "car_schenker_de",
  "invoice_number":  "SCH-2024-031-08841",
  "invoice_date":    "2024-03-01",
  "total_amount":    14220.40,
  "currency":        "EUR",
  "line_count":      24,
  "flagged_count":   2,
  "disputed_amount": 312.80,
  "status":          "audited",
  "file_format":     "pdf",
  "sub_invoices":    1,
  "uploaded_at":     "2024-03-02T09:14:22Z",
  "audited_at":      "2024-03-02T09:14:55Z"
}

POST /invoices/ingest Upload & extract invoice

Upload an invoice file and trigger the full pipeline: AI extraction → fee-code mapping → rate validation. For PDF files, multi-invoice (Sammelrechnung) detection is automatic. Accepts multipart/form-data.

Body (multipart/form-data)

file	required	Invoice file. Accepted: `.pdf`, `.csv`, `.edi` (Professional+ only)
carrier_hint	optional	Carrier name or ID to pre-seed detection (improves accuracy for edge cases)
metadata	optional	JSON object — arbitrary key/value pairs stored against the invoice (e.g. your internal reference)

Example request (curl)

curl -X POST https://oracron.arrow-scm.com/api/v1/invoices/ingest \
  -H "Authorization: Bearer or_live_xxxx" \
  -F "file=@schenker-march-2024.pdf" \
  -F "carrier_hint=DB Schenker" \
  -F 'metadata={"your_ref":"PO-2024-0312"}'

Response 201

{
  "id":          "inv_9xk2mR4nQp",
  "status":      "pending",
  "message":     "Invoice accepted. Extraction pipeline started.",
  "webhook_event": "invoice.audited" // fired when pipeline completes
}

Processing is asynchronous. Poll GET /invoices/{id} or listen for the invoice.audited webhook event to know when results are ready.

GET /invoices/{id}/lines Get extracted lines

Returns all extracted charge lines for an invoice, including the mapped fee code, confidence score, and any rate validation flags.

Response 200 — line object

{
  "id":                "line_7wQm3p",
  "invoice_id":        "inv_9xk2mR4nQp",
  "description":       "Kraftstoffzuschlag",
  "fee_code":          "FUEL_SURCHARGE",
  "fee_code_label":    "Fuel surcharge",
  "amount":            184.60,
  "currency":          "EUR",
  "contracted_amount": 160.00,
  "delta":             24.60,
  "confidence":        0.97,
  "status":            "flagged",
  "flag_reason":       "exceeds_contracted_rate",
  "shipment_ref":      "SHP-20240301-0041"
}

Review Queue

GET /review-queue List pending review items

Returns all invoice lines currently in the review queue — lines where mapping confidence fell below the auto-approve threshold, or where no rate was found on file.

Response 200 — item object

{
  "id":                 "rev_4pLn8w",
  "line_id":            "line_7wQm3p",
  "invoice_id":         "inv_9xk2mR4nQp",
  "carrier_name":       "DB Schenker GmbH",
  "original_description": "Sicherheitszuschlag AWB",
  "ai_suggested_code":  "SECURITY_SURCHARGE",
  "confidence":         0.61,
  "amount":             42.00,
  "queued_at":          "2024-03-02T09:15:01Z"
}

POST /review-queue/{id}/decision Submit review decision

Submit an approve, override, or dispute decision for a queued line. Override decisions automatically create an alias to improve future auto-mapping.

Body (JSON)

action	required	`approve` · `override` · `dispute`
fee_code	optional	Required when action is `override`. The correct fee code to assign.
note	optional	Free-text note stored against the decision for audit trail.

Example — override decision

{
  "action":   "override",
  "fee_code": "SECURITY_SURCHARGE",
  "note":     "Confirmed via carrier rate sheet March 2024"
}

Response 200

{
  "id":        "rev_4pLn8w",
  "status":    "resolved",
  "action":    "override",
  "alias_created": true,
  "resolved_at": "2024-03-02T11:30:00Z"
}

Fee Codes

GET /fee-codes List your fee code library

Returns all fee codes in your workspace, including your custom aliases. Useful for building integrations that map Oracron codes to your internal cost centre taxonomy.

Response 200 — fee code object

{
  "code":          "FUEL_SURCHARGE",
  "label":         "Fuel surcharge",
  "service_family": "SURCHARGE",
  "transport_mode": "ROAD",
  "aliases": [
    "Kraftstoffzuschlag",
    "KSZ",
    "Fuel adj."
  ],
  "is_custom": false
}

Webhooks

Oracron can push events to your endpoint as invoices move through the pipeline — no polling required. Register a webhook URL in Settings → Webhooks.

Webhook payload structure

{
  "event":      "invoice.audited",
  "created_at": "2024-03-02T09:14:55Z",
  "data": {
    // full invoice object
  },
  "signature":  "sha256=abcdef..." // HMAC-SHA256, verify before processing
}

Signature verification

Always verify the X-Oracron-Signature header before acting on a webhook. Compute HMAC-SHA256 of the raw request body using your webhook secret (from Settings). Reject requests where signatures don't match.

Event types

Event	Fired when
invoice.ingested	Invoice file uploaded and accepted
invoice.audited	Full pipeline complete — results ready
invoice.review_required	One or more lines entered the review queue
review.item_resolved	A review queue item was approved, overridden, or disputed
review.queue_cleared	All queue items for an invoice resolved
invoice.ingest_failed	Pipeline failed — file could not be processed

Developer Preview

Ready to connect?

API access is available on Professional and Enterprise plans. Contact us to receive a sandbox key and test the full pipeline against your own invoices.

Request API access View pricing

REST API Reference

Authentication

Errors & status codes

Rate limits

Invoices

Review Queue

Fee Codes

Webhooks

Webhooks

Ready to connect?

Sign in

Reset password