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

Automatisez l'ingestion des factures, récupérez les résultats d'audit au niveau de l'expédition, soumettez les décisions de vérification et recevez des événements webhook en temps réel. L'API Oracron est conçue pour les équipes financières de la logistique qui souhaitent connecter Sentra à leur ERP, leur TMS ou leurs outils sur mesure. Elle est en cours de développement actif — la référence ci-dessous décrit la surface prévue et est proposée sur demande aux premiers partenaires de conception.

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

L'API est en cours de développement actif et n'est pas encore disponible de manière générale — les points de terminaison et les champs décrits ici peuvent changer. Les clés ne sont pas en libre-service ; pendant la période d'aperçu, elles sont délivrées sur demande aux partenaires de conception. 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

Téléversez un fichier de facture et déclenchez le pipeline complet : extraction par IA → mappage des codes de frais → enrichissement des expéditions → rapprochement transporteur → validation tarifaire. Une facture peut se résoudre en plusieurs expéditions — l'unité d'audit — chacune validée par rapport à vos tarifs contractuels. Pour les fichiers PDF, la détection multi-factures (Sammelrechnung) est automatique. Accepte 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