# API Specification — AI-Assisted Translation, Approval and Secure PDF Delivery

## Purpose
This document defines the back-end API required to turn uploaded English reports into approved multilingual PDF products.

## Required server-side components
- Authentication and roles: Owner, Admin, Translator, Reviewer, Customer.
- Private source-file storage.
- AI provider abstraction: OpenAI, Claude, manual.
- Translation job queue.
- Review and approval state machine.
- PDF renderer.
- WooCommerce/order integration or custom checkout integration.
- Secure signed-download endpoint.

## Core endpoints

### POST `/api/reports`
Creates a report record and uploads the English master file.

Request fields:
- `title`
- `slug`
- `commercial_status`
- `source_rights`
- `master_language = en`
- `source_file`

Response:
- `report_id`
- `status = uploaded`
- `source_storage_key`

### POST `/api/reports/{report_id}/extract`
Extracts report structure into sections, tables, source notes and metadata.

Response:
- `status = extracted`
- `sections[]`
- `tables[]`
- `rights_warning[]`

### POST `/api/reports/{report_id}/translations`
Creates a translation job.

Request:
```json
{
  "target_language": "ru",
  "provider": "openai",
  "mode": "admin_approved",
  "glossary_id": "food_trade_v1"
}
```

Response:
- `job_id`
- `status = queued`

### GET `/api/translations/{job_id}`
Returns translation status and translated segments.

### PATCH `/api/translations/{job_id}/segments/{segment_id}`
Admin edits translated segment.

### POST `/api/translations/{job_id}/approve`
Approves translation and locks version.

Required:
- `reviewer`
- `approval_note`

### POST `/api/reports/{report_id}/pdfs`
Generates approved PDF.

Request:
```json
{
  "language": "ru",
  "template": "aquaprole_market_intelligence",
  "license_type": "corporate",
  "watermark": true
}
```

### POST `/api/downloads/create-token`
Creates secure download token after order/payment verification.

### GET `/download/{token}`
Validates token and streams file. Should not expose private storage path.

## Approval state machine
`uploaded → extracted → translation_queued → translated_draft → needs_review → approved → pdf_ready → published`

Critical reports can also be set to:
- `legal_review_required`
- `source_rights_review_required`
- `evidence_pending`

## Security controls
- API keys must never be exposed to browser.
- Source and paid PDFs must be stored outside public web root.
- Downloads must require order verification or signed expiring token.
- Every customer PDF should include license watermark where commercially appropriate.
- All admin actions should be logged.