Conventions

Les règles de cette page valent pour tous les endpoints. Les pages de référence qui suivent (en anglais, comme les noms des champs) ne les répètent pas : elles donnent, pour chaque ressource, ses filtres, ses champs et des exemples.

L'adresse#

https://votre-entreprise.evyooht.com/api/v1/{ressource}
https://votre-entreprise.evyooht.com/api/v1/{ressource}/{id}

• HTTPS uniquement. Une requête en http:// est refusée (403 https_required).
• Le nom des ressources est au pluriel, en minuscules, avec des tirets : credit-memos, sales-orders.
• {id} est un entier : le champ id d'un élément de liste.
• Toutes les ressources se lisent avec GET. Toute autre méthode répond 405 avec l'en-tête Allow: GET.

L'authentification#

Chaque requête (sauf /status et /auth/token) porte un jeton :

Authorization: Bearer evy_at_votre_jeton

Voir S'authentifier.

La forme des réponses#

Une liste :

{
  "data": [
    { "id": 4149, "number": "I1-4149", "status": "regular", "total": 1250.0 }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 1391, "total_pages": 56 }
}

Un élément (GET /invoices/4149) :

{
  "data": {
    "id": 4149,
    "number": "I1-4149",
    "status": "regular",
    "total": 1250.0,
    "lines": [],
    "payments": []
  }
}

La liste ne contient pas les lignes ni les paiements ; le détail, si.

La pagination#

Voir Parcourir de longs résultats.

Le tri#

sort prend un ou plusieurs champs séparés par des virgules, - devant pour décroissant :

GET /invoices?sort=-date,total

• Trois champs au plus.
• Seuls les champs listés dans la référence de la ressource sont triables.
• L'identifiant départage toujours les égalités, pour que deux pages consécutives ne répètent ni n'oublient rien.
• Un champ qui demande une permission que vous n'avez pas ne peut pas servir à trier.

Les filtres#

Les filtres propres à chaque ressource sont listés dans sa page de référence. Ils se combinent (« ET »). Il en existe sept types :

Les paramètres invalides sont refusés#

Un paramètre inconnu, une valeur hors liste, un entier mal formé, une date impossible (2026-02-30), une valeur vide : tout cela répond 400 invalid_parameter, avec toutes les fautes en une fois. Rien n'est ignoré en silence.

{
  "error": {
    "code": "invalid_parameter",
    "message": "One or more query parameters are invalid.",
    "request_id": "81c82f5c6e2eb5aa",
    "details": [
      { "parameter": "per_page", "message": "An integer between 1 and 100 is expected." },
      { "parameter": "stauts", "message": "Unknown parameter." }
    ]
  }
}

Les formats#

Les règles métier#

• Documents annulés (status = void) : ils gardent leur identité mais tous leurs montants sont à zéro, lignes et paiements compris. Les quantités restent.
• Brouillons (status = hold) : cachés par défaut ; status=hold les demande, status=all demande tout.
• Produits : seuls les produits actifs sont listés par défaut.
• Documents archivés : les anciennes factures et les anciens devis sont lus avec les récents, comme une seule collection. Le total, le tri et la pagination couvrent les deux.
• Totaux : le total d'un document fait foi. Une ligne donne des faits (quantité, unité, prix), pas un total calculé.

Les restrictions de votre clé#

En plus de ses permissions, une clé peut être limitée :

Les permissions#

Une permission s'écrit ressource:read. Votre clé en porte une liste ; GET /resources vous dit celles qui s'appliquent à vous.

Sans la permission d'une ressource, l'API répond 403 insufficient_scope. Sans un complément, les champs concernés sont simplement absents.

Les en-têtes de la réponse#

Les ressources#

Chacune a sa page de référence, avec ses filtres, ses champs et ses exemples.

Les quatre endpoints qui ne sont pas des données : /status, /auth/token, /ping et /resources.