6.0 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.

Contrôle qualité automatique (QC) — PPTX

Depuis le 01/07/2026 (commit cbe8cf1), toute génération PPTX est auto-vérifiée en fin de rendu : validate_pptx_layout() relit la présentation générée et détecte les zones de texte dont le contenu dépasse probablement la hauteur disponible du conteneur (titre, KPI, contenu libre).

C'est un correctif direct au bug historique du bandeau de titre à hauteur fixe (1.1in) qui débordait sur le contenu dès qu'un titre passait sur deux lignes — le bandeau se dimensionne maintenant dynamiquement (estimate_wrapped_lines() dans formatting.py) et le reste de la slide suit.

Le contrôle est non bloquant : le fichier part toujours. Les avertissements éventuels arrivent dans les en-têtes HTTP de la réponse :

X-QC-Status: ok | warning
X-QC-Warnings: ["Diapo 2 — texte probablement en debordement (\"...\") : besoin estime ~1.42\" pour 3 ligne(s), zone disponible 1.30\"."]

Hermes/n8n qui appellent /v1/generate en PPTX devraient lire ces deux en-têtes sur la réponse et, si X-QC-Status: warning, le signaler à l'utilisateur (ex. message Telegram) plutôt que livrer silencieusement un document potentiellement en débordement — le fichier reste utilisable, mais mérite une relecture rapide côté PowerPoint.

Limite connue de ce QC : il porte uniquement sur le mode données (JSON), pas sur le mode template — cohérent avec la limitation de restyle déjà documentée ci-dessus.

6.0 KiB Raw Blame History