Documentation API

Documentation API

Documentation API

Accedez a vos donnees de l’application Inventory de maniere programmatique via notre API externe.

Apercu

Qu’est-ce que l’API?

L’API externe fournit une interface pour acceder aux donnees de l’application Inventory depuis des programmes externes.

Cas d’utilisation

  • Automatisation: Traitement par lots de documents via des scripts
  • Integration tierce: Synchronisation des donnees avec d’autres services
  • Operations en masse: Creation et partage de modeles en masse

Demarrage

Obtenir une cle API

Pour utiliser l’API, vous avez d’abord besoin d’une cle API.

  1. Ouvrez l’ecran Profil dans l’application Inventory
  2. Trouvez la section Cle API
  3. Appuyez sur le bouton Generer la cle
  4. Votre cle API sera affichee a l’ecran

Important: La cle API n’est affichee qu’une seule fois lors de sa generation. Assurez-vous de la copier et de la conserver dans un endroit sur. En cas de perte, vous devrez la regenerer.

Format de la cle API

Les cles API suivent ce format:

inv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • Commence par le prefixe inv_
  • Chaine encodee Base64URL d’environ 50 caracteres

Gestion des cles API

  • Regenerer: Revoque la cle existante et en emet une nouvelle
  • Supprimer: Supprime completement la cle API (acces API desactive)

Authentification

Toutes les requetes API necessitent un en-tete Authorization.

Jeton Bearer

Authorization: Bearer inv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Exemple de requete

curl -H "Authorization: Bearer inv_your_api_key" \
     "https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/items"

Limitation du debit

L’utilisation de l’API est soumise a des limites.

Type de limite Seuil Description
Par minute 60 requetes Empeche les requetes excessives
Mensuel Varie selon le compte Determine par contrat

En cas de depassement de limite

  • Le code de statut HTTP 429 Too Many Requests est retourne
  • Veuillez patienter et reessayer plus tard

Points de terminaison API

URL de base

https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1

API de lecture (GET)

Point de terminaison Description
GET /items Lister vos articles
GET /items/{token} Obtenir les details d’un article
GET /templates Lister vos modeles
GET /templates/{token} Obtenir les details d’un modele
GET /templates/shared Lister les modeles partages
GET /user/stats Obtenir les statistiques utilisateur

API d’ecriture (POST)

Point de terminaison Description
POST /templates Creer un nouveau modele
POST /templates/{token}/share Partager un modele
POST /templates/revoke Revoquer le partage
POST /templates/{token}/send Envoyer un modele
POST /templates/{token}/log Ajouter des journaux, mettre a jour mots-cles/autorisations/image
POST /templates/{token}/check-ownership Vérifier la propriété des éléments clonés

Reference API detaillee

GET /items - Lister les articles

Recupere une liste des articles (documents) que vous possedez.

Requete

curl -H "Authorization: Bearer inv_xxx" \
     "https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/items?page=1&pageSize=20"

Parametres de requete

Parametre Type Defaut Description
page number 1 Numero de page
pageSize number 20 Articles par page (max 100)
status string “active” Filtre de statut (active, pending)
type string - Filtre de type (paper, stamp)

Reponse

{
  "success": true,
  "data": {
    "items": [
      {
        "token": "id_article_chiffre",
        "title": "Titre de l'article",
        "content": "Contenu de l'article",
        "type": "paper",
        "status": "active",
        "imageUrl": "https://...",
        "createdAt": "2025-01-01T00:00:00Z",
        "updatedAt": "2025-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "totalItems": 50,
      "totalPages": 3
    }
  }
}

POST /templates - Creer un modele

Cree un nouveau modele (tampon).

Requete

curl -X POST \
     -H "Authorization: Bearer inv_xxx" \
     -H "Content-Type: application/json" \
     -d '{
       "imageUrl": "https://example.com/image.png",
       "title": "Titre du modele",
       "content": "Contenu du modele",
        "commentMode": "independent",
        "logPermission": "owner",
        "keywordPermission": "owner",
        "allowEdit": true,
        "keywords": ["produit:ordinateur", "prix:$1500EUR$"]
     }' \
     "https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/templates"

Corps de la requete

Champ Type Requis Description
imageUrl string Oui URL de l’image (HTTPS recommande)
title string Oui Titre (max 32 caracteres)
content string Oui Contenu (max 1024 caracteres)
commentMode string Non Mode commentaire: “independent” ou “shared”
allowComments boolean Non Autoriser l’ajout de journaux (deprecated: remplacé par logPermission)
logPermission string Non Autorisation de journal: “owner” | “author” | “none” (par défaut : “owner”)
keywordPermission string Non Autorisation de mot-clé: “owner” | “author” | “none” (par défaut : “owner”)
allowEdit boolean Non Autoriser la modification (par défaut : true)
keywords string[] Non Tableau de mots-cles (max 128)

Format des mots-cles

Les mots-cles doivent suivre le format cle:valeur.

Type Format Exemple
General cle:valeur produit:stylo
Date cle:@AAAA-MM-JJ@ debut:@2025-01-15@
Telephone cle:#telephone# contact:#+33 6 12 34 56 78#
Lieu cle:%adresse% lieu:%Paris, 8eme%
Montant cle:$montantDevise$ prix:$50000EUR$

Reponse

{
  "success": true,
  "data": {
    "token": "id_modele_chiffre",
    "title": "Titre du modele",
    "createdAt": "2025-01-01T00:00:00Z"
  }
}

POST /templates/{token}/share - Partager un modele

Partage un modele pour que d’autres utilisateurs puissent le decouvrir.

Requete

curl -X POST \
     -H "Authorization: Bearer inv_xxx" \
     -H "Content-Type: application/json" \
     -d '{
       "durationMinutes": 1440,
       "tags": ["TAG1", "TAG2"]
     }' \
     "https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/templates/{token}/share"

Corps de la requete

Champ Type Requis Description
durationMinutes number Oui Duree de partage (minutes). 60-43200 ou 0 (illimite)
tags string[] Oui Tags de recherche (1-16, majuscules auto)
logPermission string Non Autorisation de journal: “owner” | “author” | “none” (remplace le parametre de l’element)
keywordPermission string Non Autorisation de mot-cle: “owner” | “author” | “none” (remplace le parametre de l’element)

Valeurs d’autorisation

Valeur Description
owner Toute personne qui copie ce modele peut ajouter/modifier
author Seul l’auteur du modele peut ajouter/modifier
none Desactive

Reponse

{
  "success": true,
  "data": {
    "shareToken": "id_partage_chiffre",
    "expiresAt": "2025-01-02T00:00:00Z",
    "tags": ["TAG1", "TAG2"]
  }
}

POST /templates/{token}/send - Envoyer un modele

Envoie un modele a un utilisateur specifie. L’utilisateur recevra un element clone du modele.

Requete

curl -X POST \
     -H "Authorization: Bearer inv_xxx" \
     -H "Content-Type: application/json" \
     -d '{
       "email": "destinataire@example.com",
       "keywords": ["date:2025-01-15", "montant:50000"]
     }' \
     "https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/templates/{token}/send"

Corps de la requete

Champ Type Requis Description
email string Oui Email du destinataire
keywords string[] Non Mots-clés à ajouter/remplacer

Regles de fusion des mots-cles

Le parametre keywords vous permet de remplacer les mots-cles par defaut du modele ou d’en ajouter de nouveaux.

Situation Comportement
Meme cle existe Remplacer par la valeur API
Nouvelle cle Ajouter a la liste des mots-cles

Exemple:

  • Mots-cles du modele: ["date:@date@", "prix:0"]
  • Mots-cles API: ["date:2025-01-15", "nom:Jean"]
  • Resultat: ["date:2025-01-15", "prix:0", "nom:Jean"]

Reponse

{
  "success": true,
  "data": {
    "itemToken": "id_element_chiffre",
    "recipientEmail": "destinataire@example.com",
    "sentAt": "2025-01-01T00:00:00Z"
  }
}

POST /templates/{token}/log - Ajouter des journaux et mettre a jour le modele

Ajoute des journaux, met a jour les mots-cles, modifie les autorisations ou met a jour l’image d’un modele partage. Envoie des notifications push aux utilisateurs qui ont copie ce modele.

Requete

curl -X POST \
     -H "Authorization: Bearer inv_xxx" \
     -H "Content-Type: application/json" \
     -d '{
       "logs": [
         {"content": "Nouvelle mise a jour publiee avec corrections de bugs"},
         {"content": "Blog:https://example.com/update-notes"}
       ],
       "keywordUpdates": [
         {"action": "upsert", "key": "version", "value": "2.1.0"},
         {"action": "delete", "key": "beta"}
       ],
       "permissionUpdates": {
         "logPermission": "owner",
         "keywordPermission": "author"
       },
       "imageUrl": "https://example.com/new-image.png"
     }' \
     "https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/templates/{token}/log"

Corps de la requete

Champ Type Requis Description
logs array Non* Entrees de journal a ajouter (max 10)
logs[].content string Oui Contenu du journal (1-256 caracteres)
keywordUpdates array Non* Modifications de mots-cles (max 20)
keywordUpdates[].action string Oui “upsert” ou “delete”
keywordUpdates[].key string Oui Cle du mot-cle (1-8 caracteres)
keywordUpdates[].value string Non Valeur (requise pour upsert, key:value combiné max 256 caractères)
permissionUpdates object Non* Modifications d’autorisations
permissionUpdates.logPermission string Non “owner” | “author” | “none”
permissionUpdates.keywordPermission string Non “owner” | “author” | “none”
imageUrl string Non* Nouvelle URL d’image (retraitee en 512x512 WebP)

* Au moins un parmi logs, keywordUpdates, permissionUpdates ou imageUrl doit etre fourni.

Format du contenu des journaux

Les journaux au format cle:valeur (cle de 1-8 caracteres) sont affiches sous forme de cartes info/URL dans l’application :

Format Affichage
texte simple Commentaire texte normal
cle:valeur Carte info (affichage cle-valeur)
cle:https://... Carte URL (lien cliquable)

Reponse

{
  "success": true,
  "data": {
    "logsAdded": 2,
    "keywordsUpdated": 1,
    "keywordsDeleted": 1,
    "notificationsSent": 3
  }
}

POST /templates/{token}/check-ownership - Vérifier la propriété des éléments clonés

Verifiez si un utilisateur specifique possede des elements clones a partir de ce modele.

Securite: Vous ne pouvez interroger que les modeles que vous possedez. Vous ne pouvez pas interroger les modeles d’autres utilisateurs.

Requete

curl -X POST \
     -H "Authorization: Bearer inv_xxx" \
     -H "Content-Type: application/json" \
     -d '{
       "email": "utilisateur@example.com",
       "keywordKeys": ["date", "montant"]
     }' \
     "https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/templates/{token}/check-ownership"

Corps de la requete

Champ Type Requis Description
email string Oui E-mail de l’utilisateur a verifier
keywordKeys string[] Non Liste des cles de mots-cles a recuperer

Reponse

{
  "success": true,
  "data": {
    "hasItem": true,
    "itemTokens": ["id_element_1", "id_element_2"],
    "keywords": {
      "date": "2025-01-15",
      "montant": "50000"
    }
  }
}

Champs de reponse

Champ Type Description
hasItem boolean Statut de propriete
itemTokens string[] Tokens des elements possedes (uniquement si possedes)
keywords object Valeurs des mots-cles demandes (uniquement si demandes)

Codes d’erreur

Lorsqu’une requete API echoue, les erreurs sont retournees dans ce format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Description de l'erreur"
  }
}

Liste des codes d’erreur

Code Statut HTTP Description
INVALID_API_KEY 401 Cle API invalide
API_KEY_EXPIRED 401 Cle API expiree
API_DISABLED 403 API desactivee
RATE_LIMIT_EXCEEDED 429 Limite de requetes depassee
VALIDATION_ERROR 400 Entree invalide
INVALID_TOKEN 400 Jeton invalide
NOT_FOUND 404 Ressource non trouvee
FORBIDDEN 403 Acces refuse
RECIPIENT_NOT_FOUND 404 Destinataire non trouve

Recommandations de securite

  1. Proteger les cles API: Ne jamais exposer les cles API dans des depots publics ou du code client
  2. Utiliser HTTPS: Toutes les requetes sont transmises via HTTPS
  3. Rotation des cles: Regenerer periodiquement les cles API
  4. Privilege minimal: N’effectuer que les operations necessaires

Contact

Si vous avez des problemes avec l’utilisation de l’API, veuillez nous contacter via la page Suggestions.