4.6 KiB

Raw Blame History

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.

{
  "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")

{
  "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")

{
  "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)

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.

4.6 KiB Raw Blame History