API et webhooks

Via l'API allverto, les boutiques, prestataires logistiques, logiciels de comptabilité ou vos propres programmes échangent des données avec allverto : articles, stocks, clients, commandes, paiements, expédition, retours, canaux de vente, factures et achats. Les webhooks signalent immédiatement les modifications à l'adresse de votre choix – par exemple « Commande créée » ou « Stock modifié ».

Vous configurez tout sous Paramètres → API et webhooks. Vous y trouverez aussi la Documentation complète de tous les points d'accès.

#Avant de commencer

• Les clés API et les webhooks sont gérés par les rôles disposant du droit Gérer les clés API et les webhooks – en général Propriétaire et Administration. Voir Utilisateurs et rôles.
• Une clé reçoit au maximum les droits dont vous disposez vous-même. Si vous perdez ultérieurement un droit, la clé le perd aussi.
• Il en va de même pour les webhooks : vous ne pouvez vous abonner qu'aux événements dont vous pouvez lire vous-même les données – « Client modifié » par exemple uniquement avec « Voir les clients », « Facture créée » uniquement avec « Voir les documents ». allverto masque les événements sans le droit correspondant.

#Créer une clé API

1. Ouvrez Paramètres → API et webhooks, onglet Clés API.
2. Cliquez sur Créer la clé.
3. Saisissez un Nom qui vous permet de reconnaître le système tiers (par ex. « Connexion Shopify »).
4. Choisissez les Droits, par ex. « Lire les commandes » et « Importer des commandes ». Ne prenez que ce dont le système tiers a réellement besoin.
5. Facultatif : limitez la clé à une Société (elle ne voit et n'écrit alors que les commandes et documents de cette société), définissez une Date d'expiration et la Limite de requêtes par minute.
6. Cliquez sur Créer la clé. allverto affiche la clé (av_…) une seule fois – copiez-la avec Copier et enregistrez-la dans le système tiers.

Dans le menu de la ligne, vous pouvez Copier le préfixe (pour retrouver la clé dans le système tiers) et Révoquer la clé à tout moment. L'API la refuse alors immédiatement. La liste indique quand une clé a été utilisée pour la dernière fois (Dernière utilisation) et depuis quelle adresse IP.

#Requêtes à l'API

Chaque requête porte la clé dans l'en-tête Authorization: Bearer av_…. Les points d'accès se trouvent sous /api/v1, par exemple :

curl https://deine-firma.allverto.cloud/api/v1/orders?status=paid \
  -H "Authorization: Bearer av_…"

• Les listes renvoient { data, page: { nextCursor, hasMore } }. Vous obtenez la page suivante avec cursor=<nextCursor>. Avec updatedSince=2026-10-01T00:00:00Z, seules les entrées créées ou modifiées depuis sont renvoyées – idéal pour des synchronisations régulières.
• Les erreurs ont toujours la forme { error, message, fields } avec le statut HTTP correspondant (400 saisie, 401 clé, 403 droit manquant, 404 introuvable, 409 conflit, 429 limite).
• Idempotence : pour les requêtes POST, envoyez un en-tête Idempotency-Key unique. Si vous répétez la requête (par ex. après une erreur réseau), allverto n'enregistre rien en double et renvoie la même réponse pendant 24 heures.
• Limite de requêtes : par défaut, 120 requêtes par minute et par clé. En cas de dépassement, l'API répond avec 429 et Retry-After (en secondes).
• Retours et canaux de vente : GET /api/v1/returns et /returns/{id} renvoient les retours avec lignes, motifs et remboursement (droit « Lire les retours »), GET /api/v1/channels les canaux de vente – le pendant de channelId dans les commandes et les retours.

Les modifications effectuées via l'API apparaissent dans le Journal des modifications sous la forme « API : nom de la clé ».

#Configurer des webhooks

1. Onglet Webhooks, cliquez sur Ajouter un webhook.
2. Saisissez le nom et l'Adresse (https://…) du destinataire et choisissez les Événements, par ex. « Commande créée », « Paiement reçu », « Stock modifié ». Avec plusieurs sociétés, vous pouvez limiter le webhook à une société – les commandes, documents, retours et commandes fournisseurs des autres sociétés ne sont alors pas envoyés à cette adresse.
3. Cliquez sur Enregistrer. allverto affiche le Secret permettant de vérifier la signature – lui aussi une seule fois.
4. Avec Envoyer un test, vous vérifiez la connexion. Le résultat figure dans le Journal de livraison.
5. Les nouveaux webhooks sont inactifs. Ce n'est qu'avec Activer qu'allverto envoie de vrais événements – comme pour toutes les synchronisations.

Les événements sont générés dans la même transaction que la modification : si un enregistrement est interrompu, aucun webhook n'est envoyé non plus. Le contenu (data) a le même format que l'API (par ex. GET /api/v1/orders/{id}, pour les retours GET /api/v1/returns/{id}).

À chaque livraison, allverto vérifie les droits actuels de la personne qui a créé ou modifié en dernier le webhook. S'il lui manque le droit de lecture pour un événement ou si elle n'a plus d'accès actif, aucune donnée n'est envoyée ; le journal de livraison indique la livraison comme échouée avec le motif. La personne qui enregistre ensuite le webhook en devient responsable.

#Vérifier la signature

Chaque appel porte l'en-tête allverto-signature: t=<heure Unix>,v1=<signature>. La signature est un HMAC-SHA256 calculé avec le secret sur t + "." + Body. Vérifiez-la sur le corps non modifié et rejetez les appels dont l'heure diffère de plus de 5 minutes.

#Livraisons en échec

Si le destinataire ne répond pas avec un code 2xx, allverto réessaie – après 1 minute, 5 minutes, 30 minutes, 2, 6, 12 et 24 heures. Après 20 échecs consécutifs, le webhook est automatiquement désactivé ; vous recevez une notification. Dans le Journal de livraison (période par défaut « 30 derniers jours »), vous voyez le statut, le code de réponse et la durée de chaque livraison et pouvez la Renvoyer.

Les webhooks ne peuvent appeler que des adresses publiques – les cibles internes comme localhost ou les réseaux privés sont bloquées.