# API Integration

Use this when integrating `ai-documents-validation` into another application.

## Service Model

Default to a separate FastAPI microservice. Do not import `docvalidator` Python modules directly into the consumer unless explicitly requested and controlled in a monorepo.

Reasons:

- shared models load once at startup;
- API is the public contract;
- validation runs through a shared executor;
- model runtime can live on CPU/GPU host separate from the consumer.

## Endpoints

- `GET /api/v1/health`
- `GET /api/v1/supported-types`
- `POST /api/v1/validate`
- Swagger UI: `/docs`
- OpenAPI JSON: `/openapi.json`

## Auth And CORS

Auth:

- without `DOCVALIDATOR_API_KEY`, dev mode allows calls without `X-API-Key`;
- with `DOCVALIDATOR_API_KEY`, protected endpoints require `X-API-Key`.

CORS:

- disabled if `DOCVALIDATOR_API_CORS_ALLOW_ORIGINS` is unset;
- enabled for CSV origins when configured;
- exposes `X-Request-ID` when configured.

## Validate Request

`POST /api/v1/validate` uses multipart form data:

- `file`: PDF to validate;
- `doc_type`: expected document type, currently `DURC` or `DOCUMENTO_IDENTITA`;
- `context_cf`: optional, used only for DURC company tax-code matching.

Example:

```bash
curl \
  -X POST \
  -H "X-API-Key: secret-key" \
  -F "file=@./durc.pdf;type=application/pdf" \
  -F "doc_type=DURC" \
  -F "context_cf=03176620601" \
  http://localhost:8000/api/v1/validate
```

## Validate Response

Consumer logic should use machine-readable fields:

- `schema_version`;
- `doc_type_expected`;
- `doc_type_predicted`;
- `classification_confidence`;
- `document_reliability_score`;
- `document_reliability_status`;
- `status`;
- `issues`;
- `extracted_fields`;
- `field_diagnostics`;
- `llm_message_for_user`;
- `metadata`.

Do not drive workflow only from `llm_message_for_user`.

Status mapping:

| Status | Consumer behavior |
| --- | --- |
| `OK` | Accept automatically unless stricter business policy applies. |
| `WARNING` | Route to manual check or confirmation. |
| `KO` | Block acceptance or request a new upload. |

## Error Handling

HTTP error envelope:

```json
{
  "error": {
    "code": "STABLE_CODE",
    "message": "Human-readable error summary.",
    "request_id": "correlation-id",
    "details": {}
  }
}
```

Consumer must:

- log `request_id`;
- handle `401`, `422`, and `500`;
- distinguish HTTP failures from validation `status = "KO"`;
- show consumer-owned user messages, not raw technical errors by default.

## Consumer Flow

1. Check `GET /api/v1/health`.
2. Use `GET /api/v1/supported-types` to populate UI and validate `doc_type`.
3. Upload PDF via `POST /api/v1/validate`.
4. Persist complete response or audit subset according to privacy policy.
5. Drive workflow from `status` and `issues`.
6. Use `field_diagnostics` and `metadata` for audit/debug UI.

## New Document Type Impact

When exposing a new document type to consumers, update:

- API enum/schema if hard-coded;
- `SUPPORTED_TYPES_CATALOG`;
- `GET /api/v1/supported-types` tests;
- validate API tests;
- OpenAPI/Postman examples if helpful;
- consumer docs when new context fields are required.

If a new document needs new context beyond `context_cf`, prefer explicit tested form fields over opaque generic payloads.

## Security And Privacy

Check:

- API key outside dev mode;
- restricted CORS origins;
- HTTPS or protected internal network outside local dev;
- no app logs containing extracted personal data;
- PDF and response retention policy;
- input size/page guardrails match consumer expectations.

## Consumer Tests

Minimum tests:

- health endpoint reachable;
- supported-types includes expected document type;
- validate valid PDF;
- validate missing/wrong `doc_type`;
- auth missing/wrong key when enabled;
- CORS if browser-based consumer.