EN DE FR ES RO
Skip to main content
hello@oracron.app +1 830 209 7888
Developer Preview · API access by request

REST API Reference

Automatisieren Sie das Einlesen von Rechnungen, rufen Sie sendungsbezogene Prüfergebnisse ab, übermitteln Sie Prüfentscheidungen und empfangen Sie Webhook-Ereignisse in Echtzeit. Die Oracron API ist für Fracht-Finanzteams konzipiert, die Sentra mit ihrem ERP, TMS oder eigenen Tools verbinden möchten. Sie befindet sich in aktiver Entwicklung — die folgende Referenz beschreibt den geplanten Funktionsumfang und wird frühen Design-Partnern auf Anfrage bereitgestellt.

Base URL https://oracron.app/api/v1
Auth Bearer API key
Format application/json

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

Die API befindet sich in aktiver Entwicklung und ist noch nicht allgemein verfügbar — die hier beschriebenen Endpunkte und Felder können sich ändern. Schlüssel sind nicht im Self-Service verfügbar; während der Preview-Phase werden sie auf Anfrage an Design-Partner ausgegeben. 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

Laden Sie eine Rechnungsdatei hoch und stoßen Sie die vollständige Pipeline an: KI-Extraktion → Fee-Code-Zuordnung → Sendungsanreicherung → Frachtführer-Zuordnung → Tarifvalidierung. Eine Rechnung kann sich in mehrere Sendungen auflösen — die Prüfeinheit —, die jeweils gegen Ihre vereinbarten Tarife validiert werden. Bei PDF-Dateien erfolgt die Erkennung von Mehrfachrechnungen (Sammelrechnung) automatisch. Akzeptiert 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.app/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

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