docs: guide usage nyora-doc-api v3 premium pour Hermes
This commit is contained in:
parent
87087638c8
commit
60e480008f
|
|
@ -0,0 +1,128 @@
|
|||
# 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.*
|
||||
Loading…
Reference in New Issue