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.

Ouvrez l’ecran Profil dans l’application Inventory
Trouvez la section Cle API
Appuyez sur le bouton Generer la cle
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}/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",
       "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”
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)

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}/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

Proteger les cles API: Ne jamais exposer les cles API dans des depots publics ou du code client
Utiliser HTTPS: Toutes les requetes sont transmises via HTTPS
Rotation des cles: Regenerer periodiquement les cles API
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.