# External Student API

Use these endpoints when another student system needs to list DTS document types and submit document requests for students.

The external system does not need duplicate student accounts in DTS. DTS records each request as an external student submission and uses the fixed system role `student` for permission checks.

## Authentication

All endpoints use a shared API key header:

```http
Accept: application/json
Content-Type: application/json
X-External-Api-Key: <your-secret-key>
```

Configure the key in `.env`:

```dotenv
EXTERNAL_STUDENT_API_KEY=replace_with_strong_secret
```

## 1. List Student Document Types

```http
GET /api/external/student/document-types
```

Only active document types that have an active workflow and allow the `student` role are returned.

```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name_en": "Example Document",
      "name_kh": "ឯកសារឧទាហរណ៍"
    }
  ]
}
```

## 2. Submit Document Requests

One endpoint handles both single and multiple document requests:

```http
POST /api/external/student/document-requests
```

The body always contains a `requests` array with between 1 and 50 items. To submit one document, send an array containing one item.

```json
{
  "requests": [
    {
      "external_entry": 125,
      "document_name": "Request Academic Transcript",
      "document_code": "PORTAL-REQ-2026-0001",
      "document_path": "https://student.example/storage/transcript-001.pdf",
      "document_type": 2,
      "description": "Submitted from student portal.",
      "supporting_files": [
        "https://student.example/storage/student-id-card.pdf"
      ]
    }
  ]
}
```

Required item fields:

- `external_entry`: unique source-system row ID for one document request. DTS uses it for status sync and idempotent retries.
- `document_name`: display name for the request.
- `document_code`: external reference from the student system. This can be duplicated.
- `document_path`: HTTPS URL or allowed storage path for the main document.
- `document_type`: document type ID returned by the list endpoint.

Optional item fields:

- `description`: stored on the request.
- `supporting_files`: additional document paths or URLs.

To submit multiple documents, add more items to the same array. Each item creates an independent DTS request with its own workflow, tracking code, and status.

Response statuses:

- HTTP `201`: every item was newly created.
- HTTP `200`: every item already existed and was returned idempotently.
- HTTP `207`: one or more items failed; inspect each item in `data`.
- HTTP `422`: the top-level `requests` envelope is invalid.

```json
{
  "success": true,
  "message": "Document requests submitted successfully.",
  "summary": {
    "total": 1,
    "created": 1,
    "idempotent": 0,
    "failed": 0
  },
  "data": [
    {
      "index": 0,
      "external_entry": 125,
      "success": true,
      "status": 201,
      "idempotent": false,
      "data": {
        "id": 125,
        "external_entry": 125,
        "document_code": "PORTAL-REQ-2026-0001",
        "uhs_code": "2026-0042",
        "status": "submit",
        "public_tracking_token": "c0f1...",
        "created_at": "2026-08-10T08:12:30.000000Z"
      }
    }
  ]
}
```

Reusing an `external_entry` returns the existing request with `idempotent: true` instead of creating a duplicate.

## 3. List Submitted Requests

```http
GET /api/external/student/document-requests
```

Supported filters: `document_code`, `external_entry`, `status`, and `per_page`.

## Error Responses

Unauthorized API key:

```json
{
  "success": false,
  "message": "Unauthorized external API key."
}
```

Item-level validation and workflow errors are returned inside the unified submission response with the corresponding `index` and `external_entry`.

## cURL Example

```bash
curl -X POST "http://127.0.0.1:8000/api/external/student/document-requests" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-External-Api-Key: replace_with_strong_secret" \
  -d '{
    "requests": [
      {
        "external_entry": 125,
        "document_name": "Request Academic Transcript",
        "document_code": "PORTAL-REQ-2026-0001",
        "document_path": "https://student.example/storage/transcript-001.pdf",
        "document_type": 2
      }
    ]
  }'
```