Créez et exploitez une intégration Alkax

La Plateforme développeur Alkax regroupe chaque intégration dans un projet. Chaque projet dispose dès le départ d’environnements Sandbox et Production isolés : activités de test, identifiants, quotas, journaux et webhooks restent propres à leur environnement.

Ouvrez la Console développeur à l’adresse https://alkax.io/developers pour créer et gérer vos projets.

Modèle de projet

Un projet appartient à votre compte ou à une organisation. La politique de l’organisation peut limiter la création de projets, les portées disponibles, le quota, la durée de validité des identifiants et l’accès à la production.

Les rôles de projet sont :

Rôle	Accès habituel
Propriétaire	Cycle de vie complet du projet, membres, identifiants et paramètres
Développeur	Création et exploitation de l’intégration
Analyste	Consultation de l’utilisation, de l’état de fonctionnement et des journaux de requêtes
Lecteur de facturation	Consultation de l’utilisation liée à la facturation

Créer votre premier projet

1. Ouvrez la Console développeur.
2. Sélectionnez New project (Nouveau projet) et choisissez un compte ou une organisation propriétaire.
3. Ouvrez Credentials (Identifiants) et émettez un identifiant Sandbox avec uniquement les portées nécessaires.
4. Copiez immédiatement le secret. Alkax ne conserve que son empreinte dérivée et ne peut pas le réafficher.
5. Appelez un jeu de données Sandbox ou utilisez l’espace d’essai de la console.
6. Consultez Usage (Utilisation) et Logs (Journaux) à l’aide de l’identifiant de requête renvoyé.

Identifiants et portées

Envoyez un identifiant côté serveur dans l’en-tête X-Alkax-Key :

X-Alkax-Key: ak_test_<key-id>.<secret>

Les clés Sandbox commencent par ak_test_ ; les clés Production par ak_live_. Les portées disponibles comprennent :

Portée	Autorise
places:read	Lire les données des lieux
geocode:read	Rechercher et géocoder
delivery:read	Lire l’état des confirmations de livraison
delivery:write	Créer et modifier les confirmations de livraison

L’encodage et le décodage Grid sont disponibles comme opérations API distinctes avec X-Alkax-Key et la portée places:read ; consultez le guide des adresses Alkax Grid.

Le renouvellement crée un identifiant de remplacement. Déployez-le avant de révoquer la clé précédente. La révocation, l’expiration, la suspension du projet et celle de l’environnement prennent effet sur les requêtes suivantes.

Abonnement et droits d’utilisation

L’utilisation de l’API développeur dépend de l’abonnement du propriétaire du projet et de la politique applicable de l’organisation.

Formule	Accès à l’API développeur
Gratuite	Sandbox uniquement, jusqu’à 1 000 requêtes par mois
Pro mensuelle ou annuelle	Sandbox et Production, jusqu’à 50 000 requêtes par mois
Entreprise	Sandbox et Production, sans limite par défaut

Le quota de la formule est partagé entre tous les projets et environnements facturés au même compte. Les limites du projet, de l’organisation et de l’environnement peuvent imposer un plafond inférieur. Elles ne peuvent pas augmenter le quota de l’abonnement.

Lorsqu’un abonnement payant expire ou devient inactif, les identifiants Production existants reçoivent 402 subscription_required. Lorsque le quota mensuel est épuisé, les requêtes reçoivent 429 quota_exceeded jusqu’à la prochaine période de facturation ou au passage à une formule supérieure.

Sandbox déterministe

Les identifiants Sandbox utilisent le même processus d’authentification et les mêmes contrats de points de terminaison que la Production, tout en isolant les effets et l’utilisation.

export ALKAX_API="https://api.alkax.io"
export ALKAX_KEY="ak_test_<key-id>.<secret>"

curl "$ALKAX_API/api/v1/sandbox/fixtures/valid-high-confidence" \
  --header "X-Alkax-Key: $ALKAX_KEY" \
  --header "Accept: application/json"

Les identifiants stables des jeux de données de test comprennent :

Jeu de données	Résultat
valid-high-confidence	Livraison possible avec une confiance élevée
ambiguous	Clarification recommandée
weak-access	Adresse valide avec une faible confiance dans l’entrée ou l’accès
not-found	Adresse inconnue
conflicting-evidence	Éléments contradictoires et faible confiance

Utilisez les scénarios d’erreur Sandbox error-403, error-404, error-409, error-429 et error-500 pour tester le traitement des échecs. Utilisez un identifiant invalide ou révoqué pour tester le véritable parcours 401.

Identifiants de requête, utilisation et journaux

Chaque réponse de l’API développeur contient X-Request-Id. Cette valeur relie la réponse aux journaux de requêtes et aux diagnostics de l’assistance.

La console enregistre des métadonnées respectueuses de la confidentialité : modèle de route, méthode, statut, latence, effet sur le quota, environnement et nom de l’identifiant. Les secrets d’authentification et les champs sensibles du corps sont exclus.

Webhooks

Ouvrez Webhooks, choisissez un environnement, saisissez une destination HTTPS publique et sélectionnez un type d’événement dans la liste. Les événements de projet pris en charge comprennent :

• delivery.confirmation.created
• delivery.confirmation.cancelled

Le secret de signature n’est affiché qu’une fois. Sandbox et Production utilisent les mêmes règles de signature, mais des secrets différents.

Les requêtes webhook contiennent :

X-Alkax-Event-Id: <UUID>
X-Alkax-Timestamp: <Unix seconds>
X-Alkax-Signature: v1=<lowercase HMAC-SHA256>

Calculez la signature attendue sur <timestamp>.<raw-body>, rejetez les horodatages trop anciens, comparez les signatures en temps constant et dédupliquez par identifiant d’événement. La console peut envoyer un événement de test, afficher les tentatives de livraison et des extraits de réponse sans données sensibles, et relancer manuellement un événement échoué.

Alkax rejette les adresses de boucle locale, privées, locales au lien et les destinations résolues par DNS vers une adresse privée. Les redirections ne sont pas suivies.

Préparation à la Production

Avant d’émettre un identifiant Production :

• confirmez votre abonnement et votre accès à la Production ;
• réduisez les portées au strict nécessaire ;
• réussissez une requête Sandbox ;
• testez le traitement des échecs et des réponses de quota ;
• vérifiez l’accessibilité et les signatures des webhooks ;
• configurez les restrictions d’accès disponibles lorsque cela est pertinent ;
• vérifiez qu’aucune clé ak_test_ ne figure dans la configuration Production.

Poursuivez avec le démarrage rapide de l’API, le guide d’authentification ou la référence API.