129 lines
4.6 KiB
Markdown
129 lines
4.6 KiB
Markdown
# nyora-doc-api — Guide d'usage pour Hermes (v3 Premium)
|
|
|
|
Service : `http://nyora-doc-api:8000` (interne réseau `n8n`) ou `http://172.17.0.1:3050` (depuis un container hors réseau n8n).
|
|
Auth : header `x-api-key: nyora-doc-2026`.
|
|
Endpoint unique : `POST /v1/generate` (multipart/form-data).
|
|
|
|
## Formats disponibles sans aucun fichier joint (mode "données pures")
|
|
|
|
XLSX, PPTX, DOCX et PDF peuvent tous être générés à partir de JSON seul,
|
|
sans template Word/Excel préexistant. C'est le mode à utiliser par défaut
|
|
pour tout Hermes qui génère un rapport, une note ou un tableau à la volée.
|
|
|
|
Champs de formulaire communs :
|
|
- `format` : `xlsx` | `docx` | `pptx` | `pdf`
|
|
- `data` : JSON (voir schémas ci-dessous)
|
|
- `options` : JSON, ex. `{"theme": "nyora"}` (ou `"tt"` pour la palette Tunisie Telecom)
|
|
- `output_name` : nom de fichier sans extension
|
|
|
|
## Schéma unifié DOCX / PDF ("sections")
|
|
|
|
Le même JSON produit un DOCX ou un PDF selon le `format` demandé — pas besoin
|
|
de réécrire le contenu deux fois.
|
|
|
|
```json
|
|
{
|
|
"title": "Titre du document",
|
|
"subtitle": "Sous-titre optionnel",
|
|
"date": "01/07/2026",
|
|
"sections": [
|
|
{"heading": "Titre de section", "level": 1, "text": "Paragraphe.\n\nDeuxième paragraphe (séparer par une ligne vide)."},
|
|
{"bullet_list": ["Point 1", "Point 2"]},
|
|
{"numbered_list": ["Étape 1", "Étape 2"]},
|
|
{"table": {
|
|
"headers": ["Region", "Budget", "Réalisé"],
|
|
"rows": [["Sfax", 1250000, 987654.321]],
|
|
"totals": true
|
|
}}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Schéma XLSX ("sheets")
|
|
|
|
```json
|
|
{
|
|
"title": "Titre optionnel (affiché en en-tête fusionné de la feuille)",
|
|
"sheets": [
|
|
{
|
|
"name": "Budget",
|
|
"totals": true,
|
|
"headers": ["Region", "Budget", "Réalisé", "Ecart %"],
|
|
"rows": [["Sfax", 1250000, 987654.321, -21.048]]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Schéma PPTX ("slides")
|
|
|
|
```json
|
|
{
|
|
"title": "Titre (génère une slide de couverture automatique)",
|
|
"subtitle": "Sous-titre optionnel",
|
|
"cover": true,
|
|
"slides": [
|
|
{"title": "Titre de slide", "kpis": [{"label": "Budget", "value": 1250000}]},
|
|
{"title": "Détail", "table": {"headers": [...], "rows": [...], "totals": true}},
|
|
{"title": "Texte", "content": "Paragraphe de contenu libre."}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Formatage numérique automatique
|
|
|
|
Toute valeur numérique dans un tableau ou un KPI est automatiquement
|
|
formatée en convention française premium : séparateur de milliers
|
|
(espace insécable) + 3 décimales, ex. `1 250 000,000`.
|
|
Si l'en-tête de colonne contient `%`, `pourcent` ou `taux`, un suffixe
|
|
`%` est ajouté automatiquement : `-21,048 %`.
|
|
Pas besoin de pré-formater les nombres côté Hermes — envoyer les valeurs
|
|
brutes (int ou float).
|
|
|
|
Pour XLSX, le format Excel natif est appliqué (`#,##0.000`), donc le
|
|
séparateur affiché suit la langue d'Excel de l'utilisateur — c'est le
|
|
comportement standard et correct.
|
|
|
|
## Totaux automatiques
|
|
|
|
Ajouter `"totals": true` sur un `sheet` (xlsx), un `table` (docx/pdf/pptx)
|
|
calcule et affiche automatiquement la somme de chaque colonne numérique,
|
|
avec un style visuellement distinct (fond gris-or, gras).
|
|
|
|
## Mode template (documents officiels TT)
|
|
|
|
Pour les documents avec en-tête officiel (lettre TT, note interne), utiliser
|
|
`template_name` au lieu de laisser DOCX en mode données :
|
|
- `template_name=papier-entete-tt`
|
|
- `template_name=note-tt-template`
|
|
|
|
Dans ce cas, `data` doit correspondre aux variables Jinja du template
|
|
(`{{ destinataire }}`, `{{ objet }}`, etc. — voir le contenu du template
|
|
pour la liste exacte), pas au schéma "sections" ci-dessus.
|
|
|
|
## Exemple d'appel curl (référence pour construire l'appel HTTP depuis n8n/Hermes)
|
|
|
|
```bash
|
|
curl -X POST http://nyora-doc-api:8000/v1/generate \
|
|
-H "x-api-key: nyora-doc-2026" \
|
|
-F "format=pdf" \
|
|
-F 'data={"title":"Note","sections":[{"heading":"Contexte","text":"..."}]}' \
|
|
-F "output_name=ma_note" \
|
|
-o ma_note.pdf
|
|
```
|
|
|
|
## Limitations connues (non bloquantes)
|
|
|
|
- `generate_csv` a une signature incompatible avec l'appel générique dans
|
|
`main.py` (`GENERATORS[fmt](template_path, ...)` passe 4 arguments à une
|
|
fonction qui n'en attend que 3) — le format `csv` échoue actuellement.
|
|
Non corrigé à ce stade (hors périmètre de la mise à niveau premium du
|
|
01/07/2026), à traiter séparément si `csv` devient nécessaire.
|
|
- Mode template DOCX/PPTX (fichier Word/PPTX existant) : le restyle de
|
|
police ne s'applique qu'aux styles de paragraphe, pas au formatage direct
|
|
des runs déjà présents dans le template (limitation structurelle de
|
|
Word/PowerPoint, déjà documentée en mémoire depuis le 30/06/2026).
|
|
|
|
---
|
|
*Document créé le 01/07/2026 lors de la mise à niveau premium v3 de nyora-doc-api.*
|