# 📘 API Documentation – Programme Sync Manual

## 📍 Endpoint

```
GET /api-programme-sync-manual.php
```

## 📄 Description

Cet endpoint permet de déclencher manuellement et de manière synchrone une synchronisation de programme MyKey4 (eCongress).
Il exécute la même logique que le cron `synchronizeEcongressPrograms`, mais filtré sur un `operationId` spécifique.

Un système de lock empêche l'exécution simultanée de plusieurs synchronisations (API ou cron).

---

## 🔐 Authentification

| Paramètre | Type | Obligatoire | Description |
|-----------|------|-------------|-------------|
| `token` | string | Oui | Clé API d'authentification. L'adresse IP de l'appelant doit également être whitelistée. |

---

## 📥 Request Parameters

**Méthode :** `GET`

| Paramètre | Type | Obligatoire | Description |
|-----------|------|-------------|-------------|
| `token` | string | Oui | Clé API d'authentification |
| `operationId` | string | Oui | Identifiant de l'opération MyKey4 à synchroniser |

**Exemple d'appel :**

```
GET /api-programme-sync-manual.php?token=YOUR_API_KEY&operationId=12345
```

---

## ✅ Success Response

**HTTP Code :** `200 OK`

```json
{
  "status": "OK",
  "message": "Synchronization completed",
  "results": [
    {
      "synchroId": 1,
      "programId": 42,
      "status": "OK"
    }
  ]
}
```

Le tableau `results` contient une entrée par configuration de synchronisation trouvée pour l'`operationId` donné. Chaque entrée peut avoir un statut `OK` ou `ERROR`.

**Exemple avec erreur partielle :**

```json
{
  "status": "OK",
  "message": "Synchronization completed",
  "results": [
    {
      "synchroId": 1,
      "programId": 42,
      "status": "OK"
    },
    {
      "synchroId": 2,
      "programId": 43,
      "status": "ERROR",
      "message": "Connection timed out"
    }
  ]
}
```

---

## ❌ Error Responses

| HTTP Code | Cause | Exemple |
|-----------|-------|---------|
| `400 Bad Request` | Paramètre `operationId` manquant | ```json {"status": "NOK", "message": "Missing required parameter: operationId"} ``` |
| `401 Unauthorized` | Clé API invalide ou adresse IP non whitelistée | ```json {"status": "NOK", "message": "Api authentication failed, (IP not white listed or token invalid)"} ``` |
| `404 Not Found` | Aucune configuration de synchro MyKey4 trouvée pour l'`operationId` | ```json {"status": "NOK", "message": "No MyKey4 synchro configuration found for operationId: 12345"} ``` |
| `405 Method Not Allowed` | Méthode HTTP autre que GET | ```json {"status": "NOK", "message": "Bad HTTP method"} ``` |
| `409 Conflict` | Une synchronisation est déjà en cours (lock actif) | ```json {"status": "NOK", "message": "A synchronization is already in progress"} ``` |
| `500 Internal Server Error` | Erreur interne du serveur | ```json {"status": "NOK", "message": "Internal error: ..."} ``` |

---

## ⚙️ Comportement technique

| Aspect | Détail |
|--------|--------|
| **Timeout** | 30 minutes (`max_execution_time: 1800`) |
| **Mémoire** | 1024 MB |
| **Lock** | Utilise `Symfony\Component\Lock\FlockStore` avec la clé `synchronizeEcongressPrograms_licenceId::<licenceId>`. Partagé avec le cron, empêche toute exécution concurrente. |
| **Type de synchro** | Uniquement les configurations de type `SERVAPI_TYPE_MYKEY4` |
| **Exécution** | Synchrone — la réponse HTTP n'est envoyée qu'une fois la synchronisation terminée |

---

## 📝 Notes

- Cet endpoint est conçu pour un déclenchement manuel ponctuel, pas pour un usage automatisé à haute fréquence.
- Contrairement au cron, il ne vérifie pas la période active (`servapiprg_date_start` / `servapiprg_date_end`), permettant ainsi de forcer une synchronisation en dehors de la fenêtre configurée.
- Le lock est partagé avec le cron `synchronizeEcongressPrograms` : si le cron tourne, l'API retournera un `409`, et inversement.

---
---

# 📘 API Documentation – Programme Sync Manual (English)

## 📍 Endpoint

```
GET /api-programme-sync-manual.php
```

## 📄 Description

This endpoint allows you to manually trigger a synchronous MyKey4 (eCongress) programme synchronization.
It runs the same logic as the `synchronizeEcongressPrograms` cron, but filtered on a specific `operationId`.

A lock mechanism prevents multiple synchronizations from running concurrently (whether triggered via API or cron).

---

## 🔐 Authentication

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `token` | string | Yes | API authentication key. The caller's IP address must also be whitelisted. |

---

## 📥 Request Parameters

**Method:** `GET`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `token` | string | Yes | API authentication key |
| `operationId` | string | Yes | MyKey4 operation ID to synchronize |

**Example call:**

```
GET /api-programme-sync-manual.php?token=YOUR_API_KEY&operationId=12345
```

---

## ✅ Success Response

**HTTP Code:** `200 OK`

```json
{
  "status": "OK",
  "message": "Synchronization completed",
  "results": [
    {
      "synchroId": 1,
      "programId": 42,
      "status": "OK"
    }
  ]
}
```

The `results` array contains one entry per synchro configuration found for the given `operationId`. Each entry can have a status of `OK` or `ERROR`.

**Partial error example:**

```json
{
  "status": "OK",
  "message": "Synchronization completed",
  "results": [
    {
      "synchroId": 1,
      "programId": 42,
      "status": "OK"
    },
    {
      "synchroId": 2,
      "programId": 43,
      "status": "ERROR",
      "message": "Connection timed out"
    }
  ]
}
```

---

## ❌ Error Responses

| HTTP Code | Cause | Example |
|-----------|-------|---------|
| `400 Bad Request` | Missing `operationId` parameter | ```json {"status": "NOK", "message": "Missing required parameter: operationId"} ``` |
| `401 Unauthorized` | Invalid API key or IP address not whitelisted | ```json {"status": "NOK", "message": "Api authentication failed, (IP not white listed or token invalid)"} ``` |
| `404 Not Found` | No MyKey4 synchro configuration found for the given `operationId` | ```json {"status": "NOK", "message": "No MyKey4 synchro configuration found for operationId: 12345"} ``` |
| `405 Method Not Allowed` | HTTP method other than GET | ```json {"status": "NOK", "message": "Bad HTTP method"} ``` |
| `409 Conflict` | A synchronization is already running (lock active) | ```json {"status": "NOK", "message": "A synchronization is already in progress"} ``` |
| `500 Internal Server Error` | Internal server error | ```json {"status": "NOK", "message": "Internal error: ..."} ``` |

---

## ⚙️ Technical Behaviour

| Aspect | Detail |
|--------|--------|
| **Timeout** | 30 minutes (`max_execution_time: 1800`) |
| **Memory** | 1024 MB |
| **Lock** | Uses `Symfony\Component\Lock\FlockStore` with key `synchronizeEcongressPrograms_licenceId::<licenceId>`. Shared with the cron, prevents any concurrent execution. |
| **Synchro type** | Only configurations of type `SERVAPI_TYPE_MYKEY4` |
| **Execution** | Synchronous — the HTTP response is only sent once the synchronization is complete |

---

## 📝 Notes

- This endpoint is designed for one-off manual triggers, not for high-frequency automated usage.
- Unlike the cron, it does not check the active period (`servapiprg_date_start` / `servapiprg_date_end`), allowing you to force a synchronization outside the configured time window.
- The lock is shared with the `synchronizeEcongressPrograms` cron: if the cron is running, the API will return a `409`, and vice versa.