API

Add-on : sécurité, signature et HTTPS

Voir en Markdown

Présentation

La Local API utilise HTTP par défaut, ce qui suffit pour un réseau sécurisé entre la caisse et le terminal. Lorsqu'un niveau de sécurité supérieur est requis, deux options sont disponibles, de la plus robuste à la plus légère :

  1. HTTPS sur le port 16126, via des noms d'hôte Yavin certifiés résolus par votre DNS local
  2. Vérification de la signature via HTTP, pour garantir que le payload de la réponse n'a pas été altéré

HTTPS

Les terminaux Yavin peuvent exposer les deux ports, ce qui permet à une caisse de choisir le protocole par point de vente :

ProtocolePort
HTTP16125
HTTPS16126

Le port 16126 est ouvert uniquement si le terminal a récupéré son certificat HTTPS auprès du backend Yavin. Cela nécessite un accès réseau au premier démarrage du terminal, et le certificat est renouvelé périodiquement. Sans certificat, le terminal démarre en HTTP uniquement, sans aucun avertissement.

Si vous implémentez HTTPS, nous vous recommandons vivement d'implémenter également HTTP, afin de pouvoir installer des points de vente qui ne peuvent pas gérer HTTPS pour des raisons opérationnelles.

Pour HTTPS, la caisse doit se connecter via l'un des noms d'hôte Yavin listés ci-dessous. Le routeur ou le serveur DNS local du partenaire associe ce nom d'hôte à l'adresse IP locale du terminal.

Noms d'hôte de production

Noms d'hôte de sandbox

Le partenaire peut connecter localement plusieurs caisses à plusieurs terminaux. Par exemple :

Aucun enregistrement DNS public A ou CNAME n'est nécessaire pour ces noms d'hôte. Ils sont conçus pour être résolus localement sur le site du partenaire.

Prérequis

  • La caisse et le terminal Yavin sont connectés au même réseau local
  • Le terminal dispose d'une adresse IP locale stable, de préférence via une réservation DHCP
  • L'appareil ou le routeur prend en charge les surcharges DNS locales / le DNS split-horizon, ou le site dispose d'un autre résolveur DNS local
  • Le partenaire a choisi un nom d'hôte disponible par terminal HTTPS
Text
tpe-local-1.p.yavin.com
tpe-local-2.p.yavin.com
...
tpe-local-20.p.yavin.com
Text
tpe-local-1.sandbox.yavin.com
tpe-local-2.sandbox.yavin.com
...
tpe-local-20.sandbox.yavin.com
Text
tpe-local-3.p.yavin.com  -> 192.168.1.103  -> Terminal A
tpe-local-7.p.yavin.com  -> 192.168.1.107  -> Terminal B

Choisir entre HTTP et HTTPS

Le logiciel de caisse peut choisir le port local à utiliser :

Utilisez HTTP lorsque l'intégration locale ne nécessite pas TLS :

Utilisez HTTPS lorsque TLS est requis. Pour HTTPS, ne vous connectez pas avec l'adresse IP brute ; utilisez le nom d'hôte choisi :

Text
http://<terminal-local-ip>:16125/
https://<chosen-hostname>:16126/
Text
http://192.168.1.103:16125/
Text
https://tpe-local-3.p.yavin.com:16126/

Configuration du routeur pour HTTPS

Pour HTTPS, le routeur doit répondre aux requêtes DNS locales pour chaque nom d'hôte choisi avec l'adresse IP LAN du terminal.

Configuration recommandée :

  1. Créez une réservation DHCP pour chaque terminal afin que son adresse IP locale reste stable
  2. Ajoutez une surcharge DNS locale pour chaque nom d'hôte choisi

Exemple avec trois terminaux :

Exemple d'entrées dnsmasq :

Ainsi, les changements DHCP sont invisibles pour les caisses : le terminal conserve la même adresse IP réservée, et le nom d'hôte se résout toujours vers cette adresse IP.

Text
tpe-local-3.p.yavin.com   -> 192.168.1.103
tpe-local-7.p.yavin.com   -> 192.168.1.107
tpe-local-12.p.yavin.com  -> 192.168.1.112
Text
address=/tpe-local-3.p.yavin.com/192.168.1.103
address=/tpe-local-7.p.yavin.com/192.168.1.107
address=/tpe-local-12.p.yavin.com/192.168.1.112

Configuration de la caisse

Pour HTTP :

Pour HTTPS :

Une caisse peut se connecter à un terminal. Plusieurs caisses peuvent aussi se connecter au même terminal en utilisant le même nom d'hôte. Plusieurs terminaux sur un même site doivent utiliser des noms d'hôte différents parmi ceux disponibles.

Text
http://192.168.1.103:16125/
Text
https://tpe-local-3.p.yavin.com:16126/

Vérification

Depuis une machine utilisant le même routeur / résolveur DNS que la caisse, vérifiez que le nom d'hôte HTTPS se résout localement :

Résultat attendu : il se résout vers l'adresse IP locale réservée du terminal.

Vérifiez la Local API en HTTP :

Vérifiez la Local API en HTTPS :

Résultat attendu :

Si le nom d'hôte est résolu sans modifier /etc/hosts, la configuration DNS du routeur fonctionne.

cURL
ping tpe-local-3.p.yavin.com
cURL
curl http://192.168.1.103:16125/localapi/v4/ping
cURL
curl https://tpe-local-3.p.yavin.com:16126/localapi/v4/ping
JSON
{"status": "ok"}

Dépannage

SymptômeCause probableSolution
HTTP fonctionne mais pas HTTPSRedirection DNS manquante ou nom d'hôte incorrectVérifiez l'entrée DNS locale et utilisez le nom d'hôte choisi sur le port 16126
tpe-local-3.p.yavin.com n'est pas résoluRedirection DNS du routeur manquanteAjoutez la redirection DNS locale
Le nom d'hôte est résolu vers une mauvaise adresse IPRedirection DNS ou réservation DHCP incorrecteVérifiez l'adresse IP réservée du terminal et l'entrée DNS du routeur
Erreur de certificatLa caisse se connecte via une adresse IP brute ou un nom d'hôte incorrectUtilisez l'un des noms d'hôte certifiés, par exemple https://tpe-local-3.p.yavin.com:16126/
Connexion refuséeService du terminal arrêté, port incorrect, pare-feu, ou (uniquement sur le port 16126) le terminal n'a pas de certificat HTTPS et fonctionne uniquement en HTTPVérifiez l'état du terminal, le port et le pare-feu local. Si HTTP sur le port 16125 fonctionne mais que le port 16126 est refusé, assurez-vous que le terminal avait accès au réseau au démarrage pour récupérer son certificat
Le nom d'hôte fonctionnait auparavant mais n'atteint plus le terminalL'adresse IP du terminal a changéAjoutez ou corrigez la réservation DHCP
Deux terminaux répondent sur le même nom d'hôteAttribution DNS en double sur le routeurAttribuez un nom d'hôte différent à chaque terminal

Solution de repli : fichier hosts

Si le routeur ne permet pas de configurer des redirections DNS locales, vous pouvez utiliser un fichier hosts sur chaque poste de caisse. Il s'agit d'une solution de repli, déconseillée pour les sites comptant plusieurs caisses ou plusieurs terminaux.

Windows (C:\Windows\System32\drivers\etc\hosts, ouvert en tant qu'administrateur) :

Vider le cache DNS :

macOS / Linux (/etc/hosts) :

Vidage du cache DNS sous macOS :

Si l'adresse IP du terminal change, toutes les entrées du fichier hosts doivent être mises à jour. Privilégiez dès que possible une réservation DHCP associée à un DNS du routeur.

Text
192.168.1.103   tpe-local-3.p.yavin.com
cURL
ipconfig /flushdns
Text
192.168.1.103   tpe-local-3.p.yavin.com
cURL
sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder

Limitations connues

  • Le certificat actuel couvre 20 noms d'hôte pour la production et 20 noms d'hôte pour le sandbox
  • Le partenaire est responsable du choix du nom d'hôte associé à chaque terminal
  • La prise en charge des redirections DNS locales varie selon le modèle de routeur
  • Les appareils iPad, iPhone et Android ne disposent pas d'un fichier hosts modifiable simplement : un DNS de routeur ou un DNS géré par MDM est nécessaire. Une autre option pour ces appareils consiste à rester en HTTP et à valider la signature des réponses (voir ci-dessous)

Signature

Si la mise en place de HTTPS est trop complexe sur un point de vente, la caisse peut utiliser la vérification de signature via HTTP. Même si un attaquant en position d'intermédiaire peut voir le trafic, la vérification de la signature garantit que le payload n'a pas été altéré.

La signature est facultative. Le terminal ajoute un en-tête Yavin-Signature uniquement lorsque :

  • la signature des réponses est activée pour votre entreprise (paramètre d'entreprise verify_local_api_signature, contactez le support Yavin pour l'activer)
  • le terminal détient la clé secrète de l'entreprise

Le paramètre est récupéré lorsque le marchand se connecte à Yavin Pay et appliqué au démarrage du serveur Local API.

Périmètre de la signature. Seuls les corps de réponse JSON sont signés. Les erreurs HTTP 400 ou 500 renvoyées sans corps JSON ne sont pas signées. Si l'en-tête Yavin-Signature est absent, la réponse n'est pas signée : ne la considérez jamais comme vérifiée. Si votre intégration exige des réponses signées, rejetez toute réponse dépourvue de cet en-tête.

La signature est calculée comme suit :

Où :

  • yavin_secret_key est la clé API de l'entreprise, disponible dans MyYavin sous Paramètres > API > Clé API (une clé par entreprise)
  • response_payload est le corps brut de la réponse JSON, sous forme de chaîne

Pour vérifier une réponse, recalculez la signature de votre côté et comparez-la avec l'en-tête Yavin-Signature.

Python
import hashlib

signature = hashlib.sha256(
    '|'.join([yavin_secret_key, response_payload]).encode('utf-8')
).hexdigest()

Paiement en magasin : Local API

Add-on : Protocole Bonjour