> For the complete documentation index, see [llms.txt](https://guideadmin.margipro.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guideadmin.margipro.com/support/import-et-telechargement-documents.md). # Import et téléchargement des documents Cette fiche décrit le comportement à connaître pour accompagner un utilisateur qui importe une photo ou télécharge plusieurs factures. ## Format enregistré à l'import La page **Importer** accepte les fichiers PDF, JPG et PNG. * Un **PDF** est envoyé et conservé sans conversion. * Une image **JPG ou PNG** est redressée si nécessaire, puis incorporée dans un véritable PDF avant son envoi au Storage et à l'analyse OCR. * Plusieurs photos représentant les pages d'un même document sont réunies dans un seul PDF. * Dans un lot, chaque image devient son propre PDF et reste un document indépendant dans la file d'attente. La conversion est réalisée dans le navigateur de l'utilisateur. Les documents d'un lot sont préparés et envoyés séquentiellement pour limiter la consommation de mémoire sur tablette. {% hint style="info" %} Le PDF produit contient l'image préparée du document, mais pas de couche de texte sélectionnable. La lecture des informations reste assurée par l'OCR MargiPro. {% endhint %} ## Limite de taille La limite est de **20 Mo par document**. Elle est vérifiée sur le fichier choisi, puis de nouveau sur le PDF généré. Si la conversion produit un PDF supérieur à 20 Mo, seul ce document échoue ; les autres éléments du lot continuent leur import. ## Suivre la file d'attente OCR Chaque document importé apparaît dans la file avec son état : **En attente**, **Analyse OCR**, **À vérifier** ou **Erreur**. La progression affichée est une estimation : les fournisseurs OCR ne transmettent pas de pourcentage réel. Elle se base sur la durée médiane des documents déjà terminés, séparément pour les factures, les bons de livraison et les tickets de traçabilité. En l'absence d'historique, l'application utilise une estimation de 20 secondes. Le compteur part de la création du document et couvre donc l'attente comme l'analyse. Une carte prête à vérifier affiche, lorsque l'OCR les a reconnus : * le numéro de facture, de bon de livraison ou de traçabilité ; * le fournisseur résolu à partir des correspondances apprises et du référentiel ; * le site concerné ; * l'utilisateur ayant importé le document ; * la durée totale du traitement. Le fournisseur affiché dans la file utilise exactement la même méthode de rapprochement que les pages de vérification. Une correspondance enregistrée est prioritaire ; sinon l'application compare le nom OCR aux fournisseurs connus. Aucun fournisseur n'est créé depuis la file : l'éventuelle création reste effectuée lors de la vérification du document. {% hint style="info" %} La progression peut rester plusieurs dizaines de secondes sur une grosse facture. Une analyse de 60 secondes reste normale et n'est pas interrompue par les délais techniques configurés. {% endhint %} ## Fonctionnement du pipeline OCR Le document reste dans le bucket privé `invoices-files`. La fonction de file transmet uniquement son chemin Storage au processor : le PDF encodé en base64 ne circule plus entre deux Edge Functions. Pour une facture ou un bon de livraison : 1. Gemini analyse directement le document. 2. L'application reconstitue le total TTC d'une facture, ou le total HT d'un bon de livraison. 3. Si l'écart dépasse **1 €**, une seconde invocation exécute Mistral OCR puis Gemini sur le texte obtenu. 4. La file conserve le résultat dont l'écart de contrôle est le plus faible. 5. Le pipeline et les modèles retenus sont enregistrés dans la trace technique du JSON OCR. Si le fallback Mistral puis Gemini échoue, le résultat Gemini direct est conservé. Il n'est pas recalculé et refacturé uniquement à cause de cette panne. Les tickets de traçabilité conservent leur traitement spécialisé : Mistral lit le document, puis Gemini structure les informations de traçabilité. ## Délais et relances automatiques Les limites sont volontairement compatibles avec les grosses factures pouvant demander environ 60 secondes : * chaque appel Google ou Mistral dispose de **90 secondes** ; * un processor dispose d'un budget global de **140 secondes** ; * l'appel entre la file et un processor est arrêté après **145 secondes** ; * une seule relance locale est autorisée après une erreur rapide, avec une attente de 2 secondes ou la valeur `Retry-After` du fournisseur plafonnée à 5 secondes ; * un appel ayant expiré ou répondu lentement n'est jamais relancé dans la même invocation. Si le traitement principal échoue, la file relance automatiquement le job après 5 secondes, puis 15 secondes. Après la troisième tentative, le document passe en **Erreur**. Si la programmation de la relance échoue elle-même, le document passe également en **Erreur** au lieu de rester indéfiniment en attente. Gemini direct et le fallback utilisent deux invocations différentes. Ils disposent ainsi chacun de leur propre fenêtre HTTP, sans raccourcir le délai accordé aux documents volumineux. ## Sécurité des fonctions OCR Dans l'environnement de test actuel, le front appelle `ocr-queue_dev`, qui distribue ensuite les documents à `rapid-processor_dev` ou `ticket-processor_dev`. * L'appel initial est autorisé avec la session de l'utilisateur puis contrôlé par les règles RLS de `import_queue`. * Les communications internes utilisent uniquement la clé secrète nommée `ocr_internal`. * Les processors refusent une clé publique, une session utilisateur et la clé secrète `default`. * La clé `ocr_internal` ne doit jamais être copiée dans le front, dans une variable `VITE_*`, dans un journal ou dans Git. * Le front utilise la clé publique `VITE_SUPABASE_PUBLISHABLE_KEY` ; l'ancienne clé anonyme reste seulement un repli temporaire pendant la migration des environnements. Les trois fonctions de test doivent être déployées avec **Verify JWT désactivé** : la session utilisateur est validée explicitement par la queue et la clé interne est validée par `@supabase/server`. Lors d'un déploiement, mettre à jour les processors avant la queue afin d'éviter une incompatibilité temporaire du contrat `storagePath`. ## Téléchargement depuis la liste Factures Le téléchargement groupé crée une archive ZIP avec des noms lisibles et dédupliqués. Les nouveaux imports sont normalement tous des PDF. Pour préserver les documents historiques, l'application vérifie cependant le contenu réel de chaque fichier avant de lui attribuer une extension : * signature PDF → `.pdf` ; * signature JPEG → `.jpg` ; * signature PNG → `.png` ; * métadonnée MIME ou extension Storage utilisée uniquement en repli. Cette détection empêche une ancienne image d'être livrée sous un faux nom `.pdf` et de paraître illisible dans le logiciel du client. ## Diagnostic support Si un utilisateur signale un problème : 1. Vérifiez si le document est un nouvel import ou un fichier historique. 2. Pour une analyse OCR, vérifiez l'état, le nombre de tentatives et le message affiché dans la file. 3. Une erreur après environ 90 secondes indique généralement un timeout fournisseur ; utilisez alors l'action de relance proposée dans la file. 4. Un document resté anormalement longtemps en analyse devient relançable sans recharger la page. 5. Pour un problème de téléchargement, demandez-lui de télécharger à nouveau le ZIP depuis **Factures**. 6. Contrôlez que l'extension correspond au contenu (`.pdf`, `.jpg` ou `.png`). 7. Si un nouvel import d'image échoue, vérifiez d'abord la taille annoncée et testez avec une photo nette plus légère. Ne demandez jamais à l'utilisateur de renommer manuellement une image en `.pdf` : changer l'extension ne convertit pas le contenu. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://guideadmin.margipro.com/support/import-et-telechargement-documents.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.