# Best Practices

Best practices for verifying digital signatures, processing documents, and generating compliance reports with the Skribble Validation API.

## Base URLs

- **Production (CH)**: `https://document-validation.skribble.com/v1`
- **Production (DE)**: `https://document-validation.skribble.de/v1`

## Validation Workflow

### Basic Validation Flow

```
Upload → Validate → Get Details → (Optional) Generate Report → Cleanup
```

1. **Submit document** for validation
2. **Receive validation ID** and quick assessment
3. **Query detailed information** using the validation ID
4. **Generate reports** if needed
5. **Resources auto-cleanup** after 10 minutes

### Quick Validation Example

```bash
# Validate a signed PDF
curl -X POST "https://document-validation.skribble.com/v1/validate/document" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "'"$(base64 -i signed-document.pdf)"'"
  }'
```

**Response:**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "valid": true,
  "signatures": 2,
  "validSignatures": 2,
  "quality": "QES",
  "legislation": "CH_EU"
}
```

## Understanding Validation Results

### Key Response Fields

| Field | Description |
|-------|-------------|
| `valid` | Overall signature validity (boolean) |
| `signatures` | Total number of signatures found |
| `validSignatures` | Number of valid signatures |
| `quality` | Highest signature quality (SES/AES/QES) |
| `legislation` | Applicable legislation (CH/EU/CH-EU). Only present when `quality` is `QES` |
| `longTermValidation` | Whether long-term validation is preserved |
| `visualDifferences` | Indicates visual tampering |
| `undefinedChanges` | Indicates unauthorized modifications |

### Signature Quality Levels

| Quality | Description | Trust Level |
|---------|-------------|-------------|
| `QES` | Qualified Electronic Signature | Highest |
| `AES` | Advanced Electronic Signature | High |
| `SES` | Simple Electronic Signature | Basic |

### Legislation Codes

| Code | Region |
|------|--------|
| `CH` | Switzerland only |
| `EU` | European Union only |
| `CH_EU` | Valid in both |

Legislation applies only to qualified signatures (QES). For SES and AES signatures, the response does not contain `legislation`. The `legislation` query parameter has an effect only when you also set `quality=QES`.

## Getting Detailed Information

After validation, use the validation ID to get more details:

### Validation Details

```bash
GET /infos/{id}/validation
```

Returns detailed ETSI EN 319 102-1 compliant validation information.

### Signer Information

```bash
GET /infos/{id}/signers
```

Returns:
- Signer names and contact information
- Certificate details (subject, issuer, serial number)
- Signature timestamps
- Quality level per signature

### Format Information

```bash
GET /infos/{id}/format
```

Returns document format specifications and PDF/A conformance level.

## Generating Reports

### Skribble Report

```bash
GET /reports/{id}/skribble?lang=en
```

Generates a digitally signed PDF validation report. The report is generated once per validation ID, language and ETSI attachment flag, then cached for subsequent requests.

| Parameter | Type | Description |
|-----------|------|-------------|
| `lang` | string | Report language: `en` (default), `de`, `fr` |
| `attachetsi` | boolean | Embed the ETSI XML report as an attachment in the PDF |

### ETSI Compliance Report

```bash
GET /reports/{id}/etsi
```

Generates an XML report compliant with the [ETSI TS 119 102-2 V1.4.1 (2023-06)](https://www.etsi.org/deliver/etsi_ts/119100_119199/11910202/01.04.01_60/ts_11910202v010401p.pdf) standard.

## Resource Management

1. **Auto-cleanup**: Validation resources are automatically deleted after 10 minutes
2. **Explicit deletion**: Use `DELETE /validate/{id}` if you're done earlier

## Performance Tips

1. **Batch wisely**: Process multiple documents in parallel when possible
2. **Cache results**: Store validation IDs if you need to query details multiple times
3. **Use appropriate endpoints**: Use `/validate/signature` for standalone signature validation
4. **Size limits**: Maximum document size is 50 MB