@jate/cli

Les outils de développement de Jate : vérifier sa clé, créer un encaissement de test, et relayer les webhooks vers sa machine sans rien déployer.

npx @jate/cli init          # ou installez : npm install -D @jate/cli

La configuration se lit dans cet ordre : arguments → variables d'environnement (JATE_API_BASE, JATE_SECRET_KEY, JATE_WEBHOOK_SECRET) → .jate.json à la racine du projet.

jate init [--base <url>] [--key <clé>]

Écrit .jate.json, vérifie la clé (GET /v1/me), affiche le mode (live ou bac à sable) et les commandes pour continuer.

.jate.json porte une clé live : init l'écrit en 0600 et ajoute la ligne à votre .gitignore si vous êtes dans un dépôt. Passer par JATE_SECRET_KEY reste préférable partout ailleurs que sur votre poste — et une clé donnée en --key reste dans l'historique du shell.

jate me [--json]

« Ma clé marche-t-elle, et sur quoi ? » — application, business, commission, portées, webhook configuré ou non, et le mode. Le mode s'affiche en toutes lettres : croire encaisser en direct alors qu'on parle au bac à sable d'Orange est l'erreur la plus coûteuse d'une intégration de paiement.

jate checkouts

# Créer une demande de paiement (--open l'ouvre chez le client)
jate checkouts create --amount 15000 --description "Test" --reference test_1 --open

# Relire un encaissement — la vérité avant de livrer
jate checkouts get jn71…

# La liste, filtrée et paginée
jate checkouts list --status paid --limit 50

create respecte l'idempotence par reference : relancez la même commande, vous récupérez la même demande (affichée « reprise »).

jate catalog — vendre vos objets depuis la vitrine

Le sens inverse du reste : le client achète dans Jate, et vous êtes prévenu pour activer. Encore faut-il que Jate sache ce que vous proposez.

# Ce que la vitrine affiche aujourd'hui, chaque ligne disant d'où elle vient
jate catalog list

# Publier — depuis un fichier, ou en tube derrière ce qui construit la liste
jate catalog publish objets.json
monscript-qui-lit-ma-base | jate catalog publish -

Construire la liste vous regarde ; l'envoyer, non. Lire vos formules dans votre base dépend de votre backend et aucun outil commun ne le fera. Envoyer, interpréter le résultat, relire pour vérifier et expliquer un refus est identique partout — c'est tout ce que fait cette commande. D'où le tube : votre moitié écrit du JSON, celle-ci le publie.

// Les deux formes sont acceptées : un tableau, ou ce que rend `catalog list`
[{ "id": "plan:42:yearly", "name": "Pro — 1 an", "price": 150000, "group": "Annuel" }]

Après l'import, la commande relit la vitrine et vous dit ce qui n'y est pas arrivé. Un import peut réussir sans que rien ne s'affiche : la vente du catalogue lié se ferme ailleurs, et sans cette vérification votre déploiement annoncerait « publié » sur une devanture vide.

⚠️ La liste est déclarative : ce qui n'y figure plus quitte la vitrine. Une liste vide retire donc tout, et c'est pourquoi elle exige --vider — le jour où votre script de construction échoue et rend [], on ne veut pas que la commande obéisse.

⚠️ Le catalogue n'a pas de bac à sable. Le mode test ne concerne que les encaissements : une clé jate_test_… réécrit la vitrine que voient les vrais clients. La commande affiche le mode avant d'écrire.

Un item_id_conflict veut dire qu'un service saisi à la main au tableau de bord porte déjà cet identifiant. La commande relit alors et nomme les lignes en cause — y compris celles qui sont retirées de la vitrine, qui réservent leur identifiant tout autant que les autres. Il faut les supprimer ou les détacher, pas seulement les retirer.

Exige la portée catalog:write. Les clés créées avant la vitrine ne l'ont pas.

jate listen — le relais de webhooks

# Le plus simple : pas d'adresse publique à déclarer
jate listen --tunnel --forward-to http://localhost:3000/jate-webhook

# Ou un relais local, exposé par un tunnel HTTPS de votre choix
jate listen --port 8787 --forward-to http://localhost:3000/jate-webhook

Il reçoit les notifications, vérifie la signature et affiche chaque événement :

✓ checkout.paid  jn71…  cmd_142  15 000 FCFA

Avec --forward-to, l'événement vérifié est renvoyé vers votre application en cours de développement, en-têtes Jate-Signature et Jate-Event-Id préservés.

Le secret (JATE_WEBHOOK_SECRET) est obligatoire : sans lui un corps ne peut pas être vérifié, et un corps non vérifié ne se traite pas. Le relais refuse alors de démarrer, plutôt que de rejeter chaque événement en 401 sans dire pourquoi.

En mode --tunnel, seuls les encaissements en mode test sont recopiés : le miroir aboutit sur une machine de développement, où les montants et références de paiements réels n'ont rien à faire. Développez avec une clé de test — avec une clé live, le tunnel reste muet et vous le dit au démarrage.

En mode relais, il faut une adresse HTTPS publique qui pointe chez vous, déclarée dans le tableau de bord. Le plus simple, sans compte :

npx cloudflared tunnel --url http://localhost:8787

Codes de sortie

0 succès, 1 erreur. Les erreurs d'API affichent leur code stable et le message ; les 429 et 503 indiquent le Retry-After.

Voir aussi

• @jate/sdk — le client backend. Il embarque toute la documentation d'intégration, sous node_modules/@jate/sdk/docs/
• @jate/expo — le parcours de paiement côté Expo / React Native
• Référence complète de l'API

MIT