# Guide — Connecter une application externe à la Core-API

Ce guide couvre les deux côtés de l'intégration :
- **Côté Core-API** : enregistrer l'app, déclarer ses routes, autoriser les scopes
- **Côté App externe** : configurer l'authentification et appeler la Core-API

---

## Vue d'ensemble

```
App externe (ex: ManageApp)
  │
  │  X-API-Key + X-API-Secret (headers)
  ▼
Core-API
  └── Vérifie les scopes autorisés pour cette app
  └── Exécute la requête et retourne la réponse
```

La Core-API utilise un système de clés publique/secrète par application. Chaque app externe doit :
1. Être enregistrée dans la Core-API (obtenir ses clés)
2. Déclarer les routes qu'elle expose (pour la découverte)
3. Se voir accorder les scopes (routes Core-API) qu'elle a le droit d'appeler

---

## Côté Core-API — Configuration de l'application

### Étape 1 — Enregistrer l'application externe

```
POST /external-applications
```

**Body :**
```json
{
  "name": "K-Shop",
  "description": "...",
  "organization": "...",
  "website": "..."
}
```

**Réponse :**
```json
{
  "success": true,
  "message": "Application externe créée avec succès. Conservez les clés en sécurité.",
  "data": {
    "id": "cfd9cdd1-a410-4949-a9d8-b765823ea345",
    "name": "K-Shop",
    "public_key": "pk_ffd682047cd2e8c0b4ecfe87fc7577553d485cc1d553263e32afcb71d926",
    "secret_key": "sk_52b8b3112a1ee703b6461c9f89773169ffac1c8bc5177148dc4fd7f50ca1d2f2",
    "status": "active",
    "created_at": "2026-05-04T10:06:16.000000Z"
  }
}
```

> **Important :** conserver `public_key` et `secret_key` immédiatement. La `secret_key` ne sera plus accessible après cette réponse.

---

### Étape 2 — Déclarer les routes exposées par l'application

Cette étape documente les endpoints que l'application externe expose elle-même, afin qu'ils soient découvrables depuis la Core-API.

```
POST /external-api-configurations
```

**Body :**
```json
{
  "endpoints": [
    {
      "endpoint": "GET:/api/v1/licenses",
      "method": "GET",
      "path": "/api/v1/licenses",
      "module": "licenses"
    },
    {
      "endpoint": "GET:/api/v1/licenses/{license}/show/jwtKey",
      "method": "GET",
      "path": "/api/v1/licenses/{license}/show/jwtKey",
      "module": "licenses"
    },
    {
      "endpoint": "POST:/api/v1/licenses",
      "method": "POST",
      "path": "/api/v1/licenses",
      "module": "licenses"
    }
  ]
}
```

**Découvrir les routes disponibles par module :**

```
GET /external-api-configurations/discover
```

**Query params :**
```
?module=licenses
```

---

### Étape 3 — Accorder les scopes à l'application

Un scope = une route Core-API que l'application externe est autorisée à appeler.

```
POST /external-applications/{applicationId}/scopes
```

**Body :**
```json
{
  "scopes": [
    "GET:/api/v1/licenses",
    "POST:/api/v1/licenses",
    "GET:/api/v1/licenses/datatables",
    "GET:/api/v1/licenses/{license}/show",
    "PUT:/api/v1/licenses/{license}/update"
  ],
  "description": "Endpoints licences autorisés pour cette app"
}
```

> Le champ `applicationId` est le `data.id` retourné à l'étape 1.

---

## Côté Application externe — Configuration

### Headers requis sur chaque requête

Toutes les requêtes vers la Core-API doivent inclure les headers suivants :

```
X-API-Key: <public_key>
X-API-Secret: <secret_key>
```

### Variables d'environnement (exemple ManageApp)

```env
BY_PLUS_API_URL=https://core.example.com/api
BY_PLUS_PUBLIC_KEY=pk_ffd682047cd2e8c0b4ecfe87fc7577553d485cc1d553263e32afcb71d926
BY_PLUS_SECRET_KEY=sk_52b8b3112a1ee703b6461c9f89773169ffac1c8bc5177148dc4fd7f50ca1d2f2
```

Ces variables sont lues dans `config/services.php` :

```php
'by_plus_api' => [
    'url'        => env('BY_PLUS_API_URL'),
    'key'        => env('BY_PLUS_PUBLIC_KEY'),
    'secret_key' => env('BY_PLUS_SECRET_KEY'),
],
```

### Implémentation dans ManageApp

ManageApp encapsule tous les appels Core-API dans `App\Services\LicenceApiService`. Le client HTTP est configuré une seule fois :

```php
private function http(): PendingRequest
{
    return Http::withHeader('X-API-KEY', config('services.by_plus_api.key'))
        ->baseUrl(config('services.by_plus_api.url'))
        ->timeout(30)
        ->acceptJson();
}
```

Pour les détails des méthodes disponibles, voir [`connect-app-to-core.md`](./connect-app-to-core.md).

---

## Checklist d'intégration

### Côté Core-API (à faire une fois par application)
- [ ] Enregistrer l'app via `POST /external-applications`
- [ ] Conserver `public_key` et `secret_key` en lieu sûr
- [ ] Déclarer les routes exposées via `POST /external-api-configurations`
- [ ] Accorder les scopes nécessaires via `POST /external-applications/{id}/scopes`

### Côté Application externe
- [ ] Renseigner `BY_PLUS_API_URL`, `BY_PLUS_PUBLIC_KEY`, `BY_PLUS_SECRET_KEY` dans `.env`
- [ ] Vérifier que chaque requête envoie bien les headers `X-API-Key` et `X-API-Secret`
- [ ] Tester la connexion en appelant un endpoint simple (ex: `GET /applications/collection`)