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

Automatice la ingesta de facturas, recupere resultados de auditoría a nivel de envío, envíe decisiones de revisión y reciba eventos de webhook en tiempo real. La API de Oracron está diseñada para los equipos financieros de logística que desean conectar Sentra con su ERP, su TMS o sus herramientas personalizadas. Se encuentra en desarrollo activo: la referencia siguiente describe la superficie prevista y se ofrece a los primeros socios de diseño bajo solicitud.

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

La API está en desarrollo activo y aún no está disponible de forma general: los endpoints y campos descritos aquí pueden cambiar. Las claves no son de autoservicio; durante el periodo de vista previa se emiten a petición a los socios de diseño. 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

Cargue un archivo de factura y active el pipeline completo: extracción por IA → asignación de códigos de tarifa → enriquecimiento de envíos → emparejamiento de transportista → validación de tarifas. Una factura puede resolverse en varios envíos — la unidad de auditoría —, cada uno validado contra sus tarifas contratadas. Para los archivos PDF, la detección de facturas múltiples (Sammelrechnung) es automática. Admite 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