# Cargoffer OCR — AI Agent Onboarding
# This file helps AI crawlers and agents understand how to use the OCR API.

## Quick Start
1. Get API key: POST /api/signup with {"email": "your@email.com"}
2. Upload document: POST /api/upload with multipart/form-data file
3. Extract: POST /api/analyze/{job_name}
4. Result: structured JSON with verified fields

## Common Agent Tasks

### "Extract data from a PDF invoice"
POST /api/upload (file=invoice.pdf) → job → POST /api/analyze/{job}
Returns: provider, invoice_number, line_items, totals, vat_breakdown

### "Extract data from a CMR document"
POST /api/upload (file=cmr.pdf) → job → POST /api/analyze/{job}
Returns: consignor, consignee, carrier, goods, weight, signatures

### "Convert a delivery note to JSON"
POST /api/upload (file=albaran.pdf) → job → POST /api/analyze/{job}
Returns: supplier, customer, items, quantities, delivery_date

### "Batch process multiple documents"
Upload each via POST /api/upload, collect job names, analyze concurrently.
Rate limit: 60 req/min. Pro plan: 10 concurrent.

## API Reference
Full spec at: https://ocr.cargoffer.com/api/openapi.yaml
Pricing: https://ocr.cargoffer.com/#pricing
Tutorials: https://ocr.cargoffer.com/tutorials

## Authentication
Bearer token via Authorization header or Clerk JWT.

## Key Endpoints
- POST /api/signup — Create account (no auth)
- POST /api/upload — Upload document (auth required)
- POST /api/analyze/{job} — Extract data (auth required)
- GET /api/jobs — List documents (auth required)
- GET /api/me — Usage and quota (auth required)

## Document Types Supported
- CMR (international consignment note)
- Invoice / Factura (Spanish format, fuel invoices)
- Delivery Note / Albarán
- Packing List
- Waybill / Carta de Porte
- Customs Declaration / DUA
- Loading Order
- Certificate of Origin
- Incident Report
- Price Lists (XLSX)
- Emails (EML)

## Models
The API auto-selects the best model per document type.
No configuration needed. 2-pass verification on every extraction.