# Winerix Reference Integration Guide

Guide d integration pour consommer les produits API Winerix en Markdown, JSON et CSV.

## Endpoints prioritaires

| Produit | Markdown | JSON | CSV | Caveat |
|---|---|---|---|---|
| Reference Launch Readiness | /api/get_reference_launch_readiness.php?format=md | /api/get_reference_launch_readiness.php?format=json | /api/get_reference_launch_readiness.php?format=csv | Checklist déclarative : elle ne remplace pas les imports DB, la validation runtime ni la validation métier finale. |
| Reference API Manifest | /api/get_reference_api_manifest.php?format=md | /api/get_reference_api_manifest.php?format=json | /api/get_reference_api_manifest.php?format=csv | Manifeste déclaratif issu du catalogue : vérifier le Publication Gate et les imports avant usage externe. |
| Reference Citation Kit | /api/get_reference_citation_kit.php?format=md | /api/get_reference_citation_kit.php?format=json | /api/get_reference_citation_kit.php?format=csv | Kit éditorial : vérifier l’URL, la fraîcheur et le Publication Gate avant diffusion externe. |
| Source-KPI Lineage Matrix | /api/get_reference_source_lineage.php?format=md | /api/get_reference_source_lineage.php?format=json | /api/get_reference_source_lineage.php?format=csv | Lineage catalogue : il prouve les liens déclarés source/produit, pas l’import DB effectif ni la fraîcheur runtime. |
| Reference KPI Scorecard | /api/get_reference_kpi_scorecard.php?format=md | /api/get_reference_kpi_scorecard.php?format=json | /api/get_reference_kpi_scorecard.php?format=csv | Scorecard methode : elle structure les familles KPI mais ne remplace pas les valeurs dynamiques ni le Publication Gate. |
| Reference Dashboard Blueprint | /api/get_reference_dashboard_blueprint.php?format=md | /api/get_reference_dashboard_blueprint.php?format=json | /api/get_reference_dashboard_blueprint.php?format=csv | Blueprint UI : il structure la page mais ne remplace pas les valeurs dynamiques, les imports ni le Publication Gate. |
| Reference Narrative Deck | /api/get_reference_narrative_deck.php?format=md | /api/get_reference_narrative_deck.php?format=json | /api/get_reference_narrative_deck.php?format=csv | Deck narratif : injecter les valeurs dynamiques depuis les produits et vérifier le Publication Gate avant partage externe. |
| Data Product Index | /api/get_reference_data_product_index.php?format=md | /api/get_reference_data_product_index.php?format=json | /api/get_reference_data_product_index.php?format=csv | Index de navigation : il reflète le catalogue produit configuré, pas la fraîcheur réelle des données importées. |
| Publication Gate | /api/get_reference_publication_gate.php?format=md | /api/get_reference_publication_gate.php?format=json | /api/get_reference_publication_gate.php?format=csv | Gate de readiness : ne remplace pas les tests d’import DB ni la validation métier finale. |

## Recettes copiables

### Copier un export Markdown

Alimenter une slide, une note, un mail ou un brief partenaire.

```bash
curl -L '/api/get_reference_launch_readiness.php?format=md'
```

Caveat : Le Markdown doit garder les caveats et ne remplace pas les valeurs runtime si elles sont absentes.

### Hydrater une interface avec JSON

Construire une page ou un widget avec les donnees structurees.

```javascript
const res = await fetch('/api/get_reference_kpi_scorecard.php?format=json');
const scorecard = await res.json();
console.log(scorecard.families);
```

Caveat : Verifier `ok`, garder les caveats et prevoir un fallback si l API retourne un pack non disponible.

### Télécharger un CSV audit

Importer les endpoints, citations ou lineage dans un tableur.

```bash
curl -L '/api/get_reference_api_manifest.php?format=csv' -o winerix-reference-api-manifest.csv
```

Caveat : Le CSV est fait pour audit/documentation ; ne pas le traiter comme preuve de fraicheur runtime.

### Consommer une API depuis PHP

Construire une page serveur ou un export enrichi.

```php
<?php
$json = file_get_contents('/api/get_reference_citation_kit.php?format=json');
$pack = json_decode($json, true);
foreach ((array)($pack['citations'] ?? []) as $citation) {
    echo $citation['citation'] . PHP_EOL;
}

```

Caveat : Utiliser une URL absolue en production et gerer les echecs HTTP.

### Gate avant publication

Automatiser un go/no-go avant d afficher un chiffre public.

```javascript
const gate = await fetch('/api/get_reference_publication_gate.php?format=json').then(r => r.json());
if (gate.status === 'blocked') {
  throw new Error('Publication bloquee par le gate Winerix');
}
```

Caveat : Le gate readiness ne remplace pas la validation metier finale.

## Ordre recommande

1. Lire le `Reference API Manifest`.
2. Controler le `Launch Readiness`.
3. Consulter le `Publication Gate` avant affichage externe.
4. Garder les citations du `Citation Kit` avec les KPI.
5. Utiliser le JSON pour les interfaces et le Markdown pour les contenus copiables.