# Proxy PISTE pour Tropratik e-Facture — Guide d'installation

Ce kit installe un **proxy HTTP dédié** sur un serveur (VPS) afin de relayer les
appels du module **Tropratik e-Facture** vers les API **PISTE / Chorus Pro**.

Il est destiné aux sites dont l'hébergement est **bloqué par le pare-feu
applicatif (WAF) de PISTE**, ce qui se traduit par une **erreur HTTP 403** lors
des appels directs à PISTE.

Le proxy installé est :

- **restreint** aux seuls domaines `*.piste.gouv.fr` (ce n'est pas un proxy ouvert) ;
- **protégé par authentification** (utilisateur + mot de passe) ;
- basé sur **Squid**, un logiciel libre et largement éprouvé.

---

## 1. Prérequis

Avant de lancer l'installation, assurez-vous de disposer de :

| Élément | Détail |
|---------|--------|
| **Un VPS / serveur dédié** | Distribution **Debian 11/12** ou **Ubuntu 20.04/22.04/24.04**. |
| **Un accès root** | Connexion SSH avec un compte `root` ou un utilisateur disposant de `sudo`. |
| **Une adresse IP publique** | Idéalement **non bloquée** par PISTE. C'est tout l'intérêt du proxy : disposer d'une IP « propre » différente de celle de votre hébergement. |
| **Un port disponible** | Par défaut `3128` (modifiable). Il devra être ouvert dans le pare-feu du serveur **et** dans l'éventuel groupe de sécurité de votre fournisseur (OVH, Scaleway, Hetzner, AWS…). |
| **Les paquets de base** | `curl` et `bash` (présents sur la plupart des distributions). Squid et `apache2-utils` sont installés automatiquement par le script. |
| **Une connexion sortante** | Le serveur doit pouvoir joindre `*.piste.gouv.fr` sur le port `443`. |

> ⚠️ **Important :** n'installez pas ce proxy sur le même hébergement que votre
> site WordPress si celui-ci est justement bloqué par PISTE — l'objectif est
> d'utiliser une **machine et une IP distinctes**.

---

## 2. Installation pas à pas

### Étape 1 — Transférer le script sur le serveur

Décompressez l'archive téléchargée, puis envoyez le script sur votre VPS, par
exemple avec `scp` depuis votre poste :

```bash
scp setup-piste-proxy.sh root@VOTRE_IP_VPS:/root/
```

Ou bien copiez-collez son contenu dans un fichier directement sur le serveur.

### Étape 2 — Lancer le script

Connectez-vous en SSH puis exécutez :

```bash
sudo bash setup-piste-proxy.sh
```

Le script vous demandera :

1. le **port** d'écoute (défaut : `3128`) ;
2. un **nom d'utilisateur** pour le proxy ;
3. un **mot de passe** (saisi deux fois, masqué).

Il installe ensuite Squid, configure l'authentification, restreint l'accès aux
domaines PISTE, redémarre le service et — si `ufw` est présent — ouvre le port.

### Étape 3 — Noter les informations affichées

À la fin, le script affiche un **récapitulatif** :

```
Hôte proxy   : 203.0.113.45
Port proxy   : 3128
Utilisateur  : monuser
Mot de passe : (celui que vous avez saisi)
```

---

## 3. Configuration côté WordPress

Dans l'administration WordPress :

1. Allez dans **WooCommerce → Tropratik e-Facture → onglet « Chorus Pro »**.
2. Pour « Connexion à PISTE », choisissez **« Via proxy VPS »**.
3. Renseignez **Hôte proxy**, **Port proxy**, **Utilisateur** et **Mot de passe**
   avec les valeurs du récapitulatif.
4. Cliquez sur **« Tester la connexion au proxy »**. Un message vert confirme
   que le proxy relaie bien les requêtes vers PISTE.
5. **Enregistrez** les réglages.

---

## 4. Vérification manuelle (optionnelle)

Depuis n'importe quelle machine, vous pouvez tester le proxy avec `curl` :

```bash
curl -x "http://UTILISATEUR:MOTDEPASSE@IP_VPS:PORT" -I https://oauth.piste.gouv.fr/api/oauth/token
```

- Une **réponse HTTP de PISTE** (par ex. `405`, `400`…) signifie que le proxy
  fonctionne.
- Une erreur **407** indique un problème d'identifiants proxy.
- Un **timeout** ou un refus de connexion indique un problème de port / pare-feu.

---

## 5. Dépannage

| Symptôme | Piste de résolution |
|----------|---------------------|
| **407 Proxy Authentication Required** | Vérifiez l'utilisateur / mot de passe ; régénérez-les en relançant le script. |
| **Connexion impossible / timeout** | Le port n'est pas ouvert : vérifiez `ufw status` et le **groupe de sécurité** de votre fournisseur. |
| **403 persistant** | L'IP du VPS est peut-être également bloquée par PISTE. Essayez une autre IP / un autre fournisseur. |
| **`squid -k parse` échoue** | Une configuration précédente entre en conflit. Une sauvegarde a été créée : `/etc/squid/squid.conf.tropratik.bak`. |
| **Voir les journaux** | `tail -f /var/log/squid/access.log` |

---

## 6. Sécurité

- Le proxy **n'autorise que** les domaines `*.piste.gouv.fr` : il ne peut pas
  être détourné comme proxy générique.
- L'accès est **authentifié** ; choisissez un mot de passe fort.
- Le fichier de mots de passe (`/etc/squid/passwd`) est en lecture restreinte.
- Pensez à maintenir votre VPS à jour : `sudo apt update && sudo apt upgrade`.

---

## 7. Désinstallation

Pour retirer le proxy :

```bash
sudo systemctl stop squid
sudo apt-get remove --purge -y squid
sudo rm -f /etc/squid/passwd
```

---

_Distribué avec le module Tropratik e-Facture — licence GPLv2 or later._
_Support : https://www.tropratik.fr_
