docs/api-spec.md

Delivery Note OCR API Specification

Base URL: https://<backend-host>

The API is frontend-agnostic. Web apps, mobile apps, CLI tools, automations, and the Hugging Face Space all consume the same HTTP contract.

Authentication and Secrets

This backend currently protects the upstream Mistral credential by keeping it on the server side as MISTRAL_API_KEY. Clients never send the provider key.

Add caller authentication at the API gateway or with a FastAPI dependency before public internet exposure.

Endpoints

Method	Path	Purpose
GET	/health	Liveness and provider configuration status
GET	/v1/schema	JSON schema used for structured extraction
POST	/v1/ocr	Multipart image upload OCR/inference
POST	/v1/ocr/base64	JSON base64 OCR/inference for non-browser clients

Interactive OpenAPI docs are available at /docs when the backend is running.

POST /v1/ocr

Request: multipart/form-data

Field	Type	Required	Description
file	file	yes	.jpg, .jpeg, .png, or .webp image
repair	query bool	no	Defaults to true; applies deterministic repair
validate	query bool	no	Defaults to true; returns validation warnings

Example:

curl -X POST \
  -F "file=@scan.jpg" \
  "http://localhost:8000/v1/ocr?repair=true&validate=true"

POST /v1/ocr/base64

Request body:

{
  "filename": "scan.jpg",
  "content_type": "image/jpeg",
  "image_base64": "<base64-or-data-url>",
  "repair": true,
  "validate": true
}

Response Shape

{
  "filename": "scan.jpg",
  "content_type": "image/jpeg",
  "checksum_md5": "string",
  "annotation": {
    "delivery_note_full": {"value": "111565/2026", "confidence": 0.99},
    "products": []
  },
  "schema_valid": true,
  "schema_errors": [],
  "validation_warnings": [],
  "repairs": [
    {
      "path": "products[0].pharmacist_price_ttc",
      "original": 7.89,
      "value": 5.35,
      "reason": "derived from line_total_ttc / quantity"
    }
  ],
  "raw_provider_response": {},
  "parse_error": null,
  "metadata": {
    "provider": "mistral",
    "model": "mistral-ocr-latest",
    "retry_count": 0,
    "critical_retry_reasons": [],
    "retry_reasons": [],
    "duration_ms": 1234
  }
}

Field notes:

• annotation is the frontend-friendly structured extraction. Every leaf is a {value, confidence} object; value may be null when a field is absent. The annotation is always schema-clean — repair provenance never appears inside it.
• schema_valid / schema_errors report whether the (post-repair) annotation validates against /v1/schema. Each error carries path, message, and validator.
• repairs are structured, deterministic corrections applied server-side. Each record carries path, original (the OCR reading), value (the corrected number), and reason (the accounting identity used).
• validation_warnings are non-blocking consistency notes (row-count, line arithmetic, total reconciliation) for human review.
• raw_provider_response preserves the original OCR provider response for debugging and replay.

Entity resolution against a client database (supplier / pharmacy / product matching) is not performed here; it is the CRM's responsibility. See docs/client-integration-guide.md.

Deployment

Backend:

cp .env.example .env
# edit MISTRAL_API_KEY in .env
docker compose up --build

Hugging Face Space:

1. Create a Gradio Space.
2. Deploy the Gradio UI (app.py) with its dependencies.
3. Set BACKEND_API_URL to the deployed backend URL.

No backend code changes are required when the frontend URL or hosting platform changes.