Développeurs · API v1

    Référence de l’API EVA : analyse des notes de frais

    L'API EVA est une API REST qui soumet un justificatif de note de frais (facture, ticket, PDF ou photo) à l'analyse par IA d'EVA et renvoie un verdict de conformité, les données lues sur le justificatif et le résultat de chaque contrôle. Elle s'appelle depuis n'importe quel outil : logiciel de notes de frais, ERP, portail interne ou extension de navigateur d'un contrôleur.

    Vue d’ensemble

    Chaque client dispose de son propre espace EVA, isolé des autres. L'URL de base comporte le nom de cet espace, communiqué à l'ouverture, par exemple https://acme.tevasoft.io/api/v1. Une clé d'API ne vaut que pour l'espace qui l'a émise.

    L'analyse est asynchrone : la lecture du justificatif (OCR) et les contrôles prennent de quelques secondes à une minute. La soumission répond tout de suite avec un identifiant et une status_url, que vous interrogez jusqu'à la fin de l'analyse.

    URL de base
    https://{espace}.tevasoft.io/api/v1

    Le parcours d’une analyse

    1. 1.Catégories

      GET /categories/ renvoie les catégories de dépense de votre espace, à mettre en cache.

    2. 2.Soumission

      POST /analyses/ avec le fichier, la catégorie et le salarié : réponse 202 et status_url.

    3. 3.Analyse

      EVA lit le justificatif (statut reading), puis applique les contrôles de la catégorie (analysing).

    4. 4.Résultat

      GET sur la status_url : quand status vaut done, la réponse porte le verdict, les données lues et les contrôles.

    Conventions

    • Les URL se terminent par une barre oblique : /analyses/, /analyses/{id}/.
    • Les identifiants (analyses, catégories) sont des UUID. Les dates sont au format AAAA-MM-JJ, les horodatages en ISO 8601 avec fuseau.
    • De nouveaux champs, statuts ou contrôles peuvent être ajoutés sans changement de version : ignorez ceux que vous ne connaissez pas. Un champ ne sera ni retiré ni renommé dans la v1.
    • Les messages sont rédigés pour un humain, dans la langue de l’espace. Branchez votre logique sur status, verdict, code et severity, jamais sur les messages.

    Authentification

    Chaque appel porte une clé d'API dans l'en-tête Authorization: Bearer. Les clés commencent par eva_ et se créent dans EVA, écran Config > Accès API. Une clé est rattachée à l'utilisateur qui la crée et agit avec ses droits : il doit avoir un rôle de contrôle qui voit les notes de frais de tous les salariés.

    La clé n'est affichée qu'une fois, à sa création : EVA n'en conserve qu'une empreinte. Rangez-la dans votre gestionnaire de secrets, jamais dans du code exécuté par le navigateur. Une clé n'expire pas ; révoquez-la depuis le même écran dès qu'elle n'est plus utilisée ou qu'elle a pu fuiter. Un utilisateur a au plus 10 clés actives, et un compte désactivé perd aussitôt l'accès.

    curl https://{espace}.tevasoft.io/api/v1/categories/ \
      -H "Authorization: Bearer $EVA_API_KEY"

    Lister les catégories

    GET/categories/

    Renvoie les catégories de dépense de votre espace, triées par nom. Chaque analyse est rattachée à une catégorie : c'est elle qui détermine les contrôles appliqués et le plafond éventuel. Les catégories changent rarement : mettez la liste en cache et rafraîchissez-la une fois par jour.

    ChampTypeDescription
    iduuidIdentifiant à passer dans le champ category de la soumission.
    namestringNom de la catégorie dans EVA.
    max_amountnumber | nullPlafond réglé pour la catégorie, null s’il n’y en a pas.
    curl https://{espace}.tevasoft.io/api/v1/categories/ \
      -H "Authorization: Bearer $EVA_API_KEY"
    Réponse
    {
      "categories": [
        { "id": "1b7f0c52-9a4e-4d1f-8c2e-5f0a6b3d9e11", "name": "Hôtel", "max_amount": 180.0 },
        { "id": "4e2a9d07-3c6b-4f85-a1d9-0b8e7c5f2a64", "name": "Repas d'affaires", "max_amount": null },
        { "id": "9c3e5b18-7d2f-4a60-b4e1-6a9f0d2c8b75", "name": "Train", "max_amount": null }
      ]
    }

    Soumettre un justificatif

    POST/analyses/

    Soumet un justificatif à l'analyse. La requête est en multipart/form-data, avec des champs à plat (aucun objet JSON imbriqué).

    ChampTypeDescription
    filefichierObligatoire. PDF, JPEG ou PNG, 15 Mo au plus, images de 50 mégapixels au plus. Le type déclaré doit correspondre au contenu réel du fichier.
    categoryuuidObligatoire. Identifiant d’une catégorie renvoyée par GET /categories/.
    employee_external_idstringObligatoire, 46 caractères au plus. Votre identifiant stable du salarié : matricule, identifiant dans votre outil.
    employee_first_namestringObligatoire. Prénom du salarié.
    employee_last_namestringObligatoire. Nom du salarié.
    employee_emailstringFacultatif. E-mail du salarié.
    curl -X POST https://{espace}.tevasoft.io/api/v1/analyses/ \
      -H "Authorization: Bearer $EVA_API_KEY" \
      -F "file=@facture-hotel-lyon.pdf;type=application/pdf" \
      -F "category=1b7f0c52-9a4e-4d1f-8c2e-5f0a6b3d9e11" \
      -F "employee_external_id=E004217" \
      -F "employee_first_name=Claire" \
      -F "employee_last_name=Martin" \
      -F "employee_email=claire.martin@example.com"
    Réponse
    HTTP/1.1 202 Accepted
    Content-Type: application/json
    
    {
      "id": "6f1c2b0e-3d4a-4f7e-9a51-8c2d7e0b9f13",
      "status": "reading",
      "status_url": "https://acme.tevasoft.io/api/v1/analyses/6f1c2b0e-3d4a-4f7e-9a51-8c2d7e0b9f13/"
    }

    Le salarié

    EVA identifie le salarié par employee_external_id, jamais par son nom : deux homonymes restent distincts. Votre outil fait foi : si le nom ou l'e-mail a changé depuis la soumission précédente, EVA les met à jour. Le nom sert à vérifier qu'une facture nominative est bien au nom du salarié, et l'historique du salarié sert à détecter les doublons. Un salarié exclu de l'analyse dans EVA (Config > Employés exclus) est refusé avec une erreur 422.

    Renvoi d’un même justificatif

    Si le même fichier est soumis pour le même salarié et la même catégorie dans les 10 minutes, EVA ne crée pas de seconde analyse et ne relit pas le document : il répond 200 avec l'analyse existante. Une nouvelle soumission répond 202. Vous pouvez donc rejouer un appel interrompu sans créer de doublon ni payer une seconde analyse.

    Réponse quand le même justificatif a déjà été soumis
    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "id": "6f1c2b0e-3d4a-4f7e-9a51-8c2d7e0b9f13",
      "status": "done",
      "status_url": "https://acme.tevasoft.io/api/v1/analyses/6f1c2b0e-3d4a-4f7e-9a51-8c2d7e0b9f13/"
    }

    Où apparaît l’analyse dans EVA

    Chaque soumission crée une note de frais dans EVA, visible par les contrôleurs dans la liste des notes de frais, avec un lien direct dans le champ web_url. Elle vit hors de votre outil de notes de frais : EVA n'écrit rien dans SAP Concur ou un autre outil connecté, et ne prend aucune décision d'approbation à partir d'une analyse soumise par l'API.

    Lire une analyse

    GET/analyses/{id}/

    Renvoie l'état d'une analyse. Interrogez la status_url reçue à la soumission toutes les 2 à 5 secondes, tant que status vaut reading ou analysing. Toute clé de l'espace peut lire toute analyse soumise par l'API dans cet espace.

    curl https://{espace}.tevasoft.io/api/v1/analyses/6f1c2b0e-3d4a-4f7e-9a51-8c2d7e0b9f13/ \
      -H "Authorization: Bearer $EVA_API_KEY"
    Réponse pendant l’analyse
    {
      "id": "6f1c2b0e-3d4a-4f7e-9a51-8c2d7e0b9f13",
      "status": "analysing",
      "category": "Hôtel",
      "created_at": "2026-11-17T09:12:44.310152+01:00",
      "web_url": "https://acme.tevasoft.io/…"
    }
    Réponse quand l’analyse est terminée
    {
      "id": "6f1c2b0e-3d4a-4f7e-9a51-8c2d7e0b9f13",
      "status": "done",
      "category": "Hôtel",
      "created_at": "2026-11-17T09:12:44.310152+01:00",
      "web_url": "https://acme.tevasoft.io/…",
      "verdict": "failed",
      "extracted": {
        "total_amount": 214.6,
        "currency": "EUR",
        "invoice_date": "2026-11-12",
        "establishment": "Hôtel des Terreaux",
        "invoice_number": "F-2026-08812",
        "document_type": "invoice"
      },
      "checks": [
        {
          "code": "duplicate_check",
          "label": "Doublon",
          "passed": false,
          "severity": "failed",
          "error_code": "…",
          "message": "Justificatif déjà présenté dans une autre note de frais.",
          "warning": ""
        },
        {
          "code": "nominative_invoice_check",
          "label": "Facture nominative",
          "passed": true,
          "severity": "passed",
          "error_code": null,
          "message": "",
          "warning": ""
        }
      ]
    }
    Réponse quand le justificatif est illisible
    {
      "id": "0c9d4e21-5b7a-4c3f-8e16-2d9a7f4b1c58",
      "status": "unreadable",
      "category": "Repas d'affaires",
      "created_at": "2026-11-17T10:03:12.004871+01:00",
      "web_url": "https://acme.tevasoft.io/…"
    }

    L’objet Analyse

    Les champs verdict, extracted et checks n'apparaissent que lorsque status vaut done. Avant, ils seraient partiels et feraient passer une note incomplète pour conforme.

    ChampTypeDescription
    iduuidIdentifiant de l’analyse.
    statusstringÉtat du traitement, voir Statuts.
    categorystring | nullNom de la catégorie.
    created_atdatetimeDate de la soumission.
    web_urlstringLien vers la note de frais dans EVA, pour un contrôleur connecté.
    verdictstringSi done. passed (conforme), failed (anomalie) ou manual_review (à vérifier).
    extracted.total_amountnumber | nullMontant total lu sur le justificatif.
    extracted.currencystring | nullDevise, code ISO 4217.
    extracted.invoice_datedate | nullDate du justificatif.
    extracted.establishmentstring | nullNom de l’établissement.
    extracted.invoice_numberstring | nullNuméro de facture.
    extracted.document_typestring | nullType de document reconnu (facture, ticket…).
    checksarraySi done. Résultat de chaque contrôle, anomalies en premier.

    Statuts

    status décrit où en est le traitement. Seuls reading et analysing sont transitoires : arrêtez d'interroger l'analyse sur toutes les autres valeurs.

    statusSignificationQue faire
    readingEVA lit le justificatif (OCR).Réinterroger.
    analysingLes contrôles de la catégorie sont en cours.Réinterroger.
    doneAnalyse terminée : verdict, extracted et checks sont présents.Lire le verdict.
    unreadableLe justificatif n’a pas pu être lu (fichier vide, trop flou, illisible).Demander un meilleur justificatif et le soumettre à nouveau.
    not_applicableAucun contrôle ne s’applique à cette analyse.Traiter hors EVA.
    frozenL’analyse est suspendue côté EVA, par exemple pendant une maintenance.Réinterroger plus tard : elle reprendra.
    stalledAucun progrès depuis 15 minutes.Soumettre à nouveau ou contacter le support avec l’id.

    Contrôles et verdict

    checks liste les contrôles réglés dans EVA pour la catégorie, parmi plus de 45 : doublons, conformité du justificatif, facture nominative, plafonds, cohérence des dates et des montants, signes de falsification. Les contrôles qu'un contrôleur a ignorés ou qui ont été désactivés depuis ne sont pas renvoyés.

    ChampTypeDescription
    codestringIdentifiant stable du contrôle, par exemple duplicate_check. La liste des contrôles actifs est visible dans votre espace EVA.
    labelstringNom du contrôle.
    passedbooleanVrai si le contrôle est conforme.
    severitystringpassed, failed (anomalie avérée) ou manual_review (doute : un contrôleur doit trancher).
    error_codestring | nullMotif de l’anomalie, quand le contrôle en donne un.
    messagestringExplication de l’anomalie, vide si le contrôle est conforme.
    warningstringAvertissement complémentaire, même sur un contrôle conforme.

    Le verdict

    verdict résume l'analyse : passed quand tous les contrôles sont conformes, failed quand au moins une anomalie est avérée, manual_review quand il reste un doute qu'un contrôleur doit lever. EVA signale ; c'est votre processus qui décide d'approuver, de renvoyer ou de rejeter la dépense.

    Traduire le résultat en action

    Un exemple de correspondance entre le résultat d’EVA et l’étape suivante de votre circuit de validation :

    // One way to turn an EVA analysis into an action in your workflow.
    function nextStep(analysis) {
      switch (analysis.status) {
        case "done":
          if (analysis.verdict === "passed") return "approve";
          if (analysis.verdict === "manual_review") return "send_to_auditor";
          return "send_back_to_employee"; // failed: at least one confirmed anomaly
        case "unreadable":
          return "ask_for_a_better_receipt";
        case "frozen":
          return "retry_later";
        default: // not_applicable, stalled
          return "send_to_auditor";
      }
    }

    Exemples d’intégration

    Ces deux programmes complets soumettent un justificatif, attendent la fin de l'analyse en respectant les limites de débit, puis affichent le verdict et les anomalies. Remplacez acme par le nom de votre espace et définissez la variable d'environnement EVA_API_KEY.

    Soumettre, attendre, lire le verdict

    """Submit an expense receipt to EVA and wait for the verdict."""
    import os, time
    import requests
    
    BASE_URL = "https://acme.tevasoft.io/api/v1"
    TRANSIENT = {"reading", "analysing"}
    
    session = requests.Session()
    session.headers["Authorization"] = f"Bearer {os.environ['EVA_API_KEY']}"
    
    
    def call(method, url, **kwargs):
        """HTTP call that waits and retries on 429 (rate limit)."""
        for attempt in range(5):
            response = session.request(method, url, timeout=30, **kwargs)
            if response.status_code != 429:
                response.raise_for_status()
                return response.json()
            time.sleep(2 ** attempt)
        response.raise_for_status()
    
    
    def analyse_receipt(path, category_id, employee):
        with open(path, "rb") as receipt:
            submitted = call(
                "POST", f"{BASE_URL}/analyses/",
                files={"file": (os.path.basename(path), receipt, "application/pdf")},
                data={"category": category_id, **{f"employee_{k}": v for k, v in employee.items()}},
            )
        deadline = time.time() + 300
        while time.time() < deadline:
            analysis = call("GET", submitted["status_url"])
            if analysis["status"] not in TRANSIENT:
                return analysis
            time.sleep(3)
        raise TimeoutError(submitted["status_url"])
    
    
    analysis = analyse_receipt(
        "facture-hotel-lyon.pdf",
        "1b7f0c52-9a4e-4d1f-8c2e-5f0a6b3d9e11",
        {"external_id": "E004217", "first_name": "Claire", "last_name": "Martin"},
    )
    if analysis["status"] != "done":
        print("No verdict:", analysis["status"])
    elif analysis["verdict"] == "passed":
        print("Compliant", analysis["extracted"]["total_amount"], analysis["extracted"]["currency"])
    else:
        for check in analysis["checks"]:
            if not check["passed"]:
                print(check["severity"], check["code"], check["message"])

    Erreurs

    Les erreurs de validation renvoient un objet errors, dont chaque clé est un champ en cause et chaque valeur une liste de messages (non_field_errors pour une erreur générale). Les erreurs d'authentification, de droits et de débit par clé renvoient un objet detail.

    HTTPCause
    400Champ manquant ou invalide : catégorie inconnue, fichier non pris en charge, contenu qui ne correspond pas au type déclaré, image trop grande.
    401Clé absente, invalide ou révoquée, ou compte désactivé.
    403API non activée pour l’espace, ou utilisateur sans droit de contrôle sur toutes les notes de frais.
    404Analyse inconnue dans cet espace.
    411Requête sans en-tête Content-Length.
    413Requête de plus de 15 Mo.
    422Salarié exclu de l’analyse EVA.
    429Limite de débit ou plafond journalier atteint.
    Champ invalide (400)
    HTTP/1.1 400 Bad Request
    
    {
      "errors": {
        "category": ["Catégorie inconnue."],
        "employee_last_name": ["Ce champ est obligatoire."]
      }
    }
    Clé refusée (401)
    HTTP/1.1 401 Unauthorized
    WWW-Authenticate: Bearer
    
    { "detail": "Jeton invalide ou révoqué." }
    Salarié exclu (422)
    HTTP/1.1 422 Unprocessable Entity
    
    {
      "errors": {
        "employee_external_id": ["Cette personne est exclue de l'analyse EVA."]
      }
    }
    Plafond journalier atteint (429)
    HTTP/1.1 429 Too Many Requests
    
    {
      "errors": {
        "non_field_errors": ["Plafond journalier d'analyses atteint."]
      }
    }

    Limites

    • Soumissions : 30 par minute et par clé.
    • Lectures (catégories, analyses) : 300 par minute et par clé.
    • Plafond journalier de l’espace : 1 000 soumissions par jour par défaut, ajustable sur demande. C’est une protection contre l’usage d’une clé divulguée, pas un quota commercial.
    • Fichier : 15 Mo au plus ; PDF, JPEG ou PNG ; images de 50 mégapixels au plus.
    • Salarié : identifiant de 46 caractères au plus.

    Au-delà, l’API répond 429 : attendez avant de réessayer, avec un délai croissant (voir les exemples d’intégration).

    Sécurité et traçabilité

    • Appelez l'API depuis votre serveur. Elle n'autorise pas les appels directs depuis une page web (pas de CORS) ; une extension de navigateur l'appelle depuis son service worker.
    • Les données renvoyées (nom de l'établissement, messages) viennent du justificatif soumis : échappez-les avant de les afficher.
    • Chaque soumission est journalisée dans EVA avec le début de la clé utilisée, ainsi que chaque clé refusée et chaque création ou révocation de clé. Les changements de nom ou d'e-mail d'un salarié sont tracés, sans recopier leurs valeurs.
    • Les données personnelles des salariés sont chiffrées en base, et les justificatifs sont stockés dans l'espace isolé du client.
    Sécurité et conformité de la plateforme

    Questions fréquentes

    Qu'est-ce que l'API EVA ?

    +

    Une API REST qui soumet un justificatif de note de frais à l'analyse par IA d'EVA et renvoie un verdict de conformité (passed, failed ou manual_review), les données lues sur le justificatif (montant, devise, date, établissement, numéro de facture) et le résultat de chaque contrôle appliqué.

    Depuis quels outils peut-on appeler l'API EVA ?

    +

    Depuis tout logiciel capable d'envoyer une requête HTTPS : outil de notes de frais, ERP, portail interne, extension de navigateur ou script. Pour SAP Concur, N2F, Lucca et Cegid, EVA dispose aussi de connecteurs natifs qui analysent les notes de frais sans développement.

    Comment obtenir une clé d'API EVA ?

    +

    Un utilisateur qui a un rôle de contrôle la crée dans EVA, écran Config > Accès API. La clé commence par eva_ et n'est affichée qu'une fois. L'API est disponible avec le module de contrôle des notes de frais d'EVA.

    Combien de temps prend une analyse ?

    +

    De quelques secondes à une minute par justificatif. La soumission répond immédiatement avec une status_url, à interroger toutes les 2 à 5 secondes jusqu'à ce que status ne vaille plus reading ni analysing.

    Quels formats de justificatifs sont acceptés ?

    +

    PDF, JPEG et PNG, jusqu’à 15 Mo et 50 mégapixels par image. Le contenu du fichier doit correspondre au type déclaré.

    L'API modifie-t-elle les notes de frais dans SAP Concur ou un autre outil ?

    +

    Non. Une analyse soumise par l'API crée une note de frais dans EVA uniquement. EVA n'écrit rien dans l'outil de notes de frais et ne prend aucune décision d'approbation : c'est l'outil appelant qui décide de la suite.

    Que se passe-t-il si un justificatif est envoyé deux fois ?

    +

    Si le même fichier est soumis pour le même salarié et la même catégorie dans les 10 minutes, EVA renvoie l'analyse existante (code 200) sans en créer de nouvelle. Au-delà, la détection de doublons d'EVA signale la seconde présentation du justificatif.

    L'API EVA envoie-t-elle des webhooks ?

    +

    Pas dans la version 1. Le résultat se lit en interrogeant la status_url renvoyée à la soumission.

    Existe-t-il une spécification OpenAPI de l'API EVA ?

    +

    Oui, au format OpenAPI 3.1, téléchargeable depuis cette page. Elle permet de générer un client dans la plupart des langages ou d’importer l’API dans Postman.

    Pour aller plus loin

    Obtenir un accès à l’API

    L'API est disponible avec le module de contrôle des notes de frais d'EVA. Écrivez-nous pour ouvrir un espace de test et créer vos premières clés.

    Nous contacter