gigafibre-fsm/docs/karrio-shipping.md

# Karrio — plateforme d'expédition multi-transporteurs (self-hosted)

Karrio est l'**EasyPost/Shippo open-source** (LGPL), auto-hébergé sur le serveur de prod.
Il fournit, sous une **API unifiée**, le **calcul de tarif d'expédition + étiquettes + suivi**
à travers de nombreux transporteurs (BYOCA : on branche nos propres comptes, **0 frais par étiquette**).

Objectif : calculer les frais de livraison au **checkout de la boutique matériel** (`/store`) et
gérer l'expédition des commandes (#54). Déployé le 2026-06-04.

> ⚠️ Ce document ne contient **aucun secret**. Les identifiants vivent sur le serveur
> (`/opt/karrio/.env`, `/opt/karrio/ADMIN_CREDS.txt`).

---

## Accès

| Quoi | URL |
|---|---|
| **Dashboard** (GUI gestion transporteurs) | https://karrio.gigafibre.ca — connexion `admin@targo.ca` (mdp : `/opt/karrio/ADMIN_CREDS.txt`) |
| **API publique** | https://api.karrio.gigafibre.ca |
| **API interne** (depuis le hub) | `http://karrio.api:5002` (réseau Docker `erpnext_erpnext`) |
| Auth API | `POST /api/token {email,password}` → JWT `access` |

DNS Cloudflare : `karrio` + `api.karrio`.gigafibre.ca → 96.125.196.67, **DNS-only** (proxied=false,
comme `msg`/`erp`, pour le challenge Let's Encrypt). TLS via Traefik (resolver `letsencrypt`).

---

## Architecture

- **Emplacement** : `/opt/karrio/` (compose) ; source clonée dans `/opt/karrio-src/` (Git).
- **Conteneurs** : `karrio.api` (5002) · `karrio.worker` · `karrio.dashboard` (3002) · `karrio.db`
  (postgres:16 dédié) · `karrio.redis` · `karrio.mail` (maildev).
- **Réseaux Docker** : `karrio_default` (interne) + `erpnext_erpnext` (pour que le hub joigne l'API)
  + `proxy` (Traefik). L'attache aux réseaux externes est dans `docker-compose.override.yml` (persistante).
- **Images** : `karrio/server` + `karrio/dashboard` **2026.1.31**. L'`api`/`worker` utilisent une
  **image custom** `karrio-server-targo:2026.1.31` (transporteurs canadiens supplémentaires, voir plus bas).

### `Dockerfile.carriers` (transporteurs canadiens opt-in)
```dockerfile
FROM karrio.docker.scarf.sh/karrio/server:2026.1.31
# Transporteurs non bundlés dans l'image OSS (paquets PyPI gratuits)
RUN /karrio/venv/bin/pip install --no-cache-dir "karrio==2026.1.31" \
      karrio_canpar karrio_nationex karrio_dicom karrio_boxknight
```
Build : `docker build -t karrio-server-targo:2026.1.31 -f Dockerfile.carriers .`

### `docker-compose.override.yml` (réseaux + image custom + labels Traefik)
```yaml
networks:
  erpnext_erpnext: { external: true }
  proxy: { external: true }
services:
  api:
    image: karrio-server-targo:2026.1.31
    networks: [default, erpnext_erpnext, proxy]
    labels:
      - traefik.enable=true
      - traefik.docker.network=proxy
      - traefik.http.routers.karrio-api.rule=Host(`api.karrio.gigafibre.ca`)
      - traefik.http.routers.karrio-api.entrypoints=websecure
      - traefik.http.routers.karrio-api.tls.certresolver=letsencrypt
      - traefik.http.services.karrio-api.loadbalancer.server.port=5002
  worker:
    image: karrio-server-targo:2026.1.31
  dashboard:
    networks: [default, proxy]
    labels:
      - traefik.enable=true
      - traefik.docker.network=proxy
      - traefik.http.routers.karrio-dash.rule=Host(`karrio.gigafibre.ca`)
      - traefik.http.routers.karrio-dash.entrypoints=websecure
      - traefik.http.routers.karrio-dash.tls.certresolver=letsencrypt
      - traefik.http.services.karrio-dash.loadbalancer.server.port=3002
```

### Variables `.env` clés (valeurs réelles sur le serveur)
```
KARRIO_TAG=2026.1.31
DATABASE_HOST=karrio.db        # nom de conteneur, PAS "db" (collision ERPNext)
REDIS_HOST=karrio.redis        # idem
USE_HTTPS=True
KARRIO_PUBLIC_URL=https://api.karrio.gigafibre.ca
DASHBOARD_URL=https://karrio.gigafibre.ca
ALLOW_SIGNUP=False
ADMIN_EMAIL=admin@targo.ca
# SECRET_KEY / JWT_SECRET / OIDC_RSA_PRIVATE_KEY / ADMIN_PASSWORD / DATABASE_PASSWORD : générés
```

---

## Transporteurs disponibles

- **Bundlés (image OSS)** : Canada Post, Purolator, UPS, FedEx, DHL (×4), GLS, USPS, DPD, Chronopost,
  La Poste, Sendle, Australia Post, **eShipper**, **Freightcom**, generic… (~29).
- **Ajoutés (image custom)** : 🇨🇦 **Canpar**, **Nationex** (QC), **Dicom / GLS Canada**, **BoxKnight** (last-mile Montréal).
- **Agrégateurs canadiens** (1 compte → multi-transporteurs à tarifs négociés, **Canpar inclus**) :
  **eShipper**, **Freightcom** (déjà bundlés).
- Dispo sur PyPI si besoin (international) : `karrio_tge, karrio_geodis, karrio_asendia, karrio_aramex`.
  Non publiés : shiptime, loomis, intelcom, ics_courier.

> Karrio OSS ne bundle qu'un sous-ensemble ; les autres transporteurs sont des paquets PyPI
> `karrio_<nom>` **gratuits** (pas une limitation de licence — du packaging). On les cuit dans
> l'image custom.

---

## Pièges rencontrés (résolus)

1. **Collision de hostname** : `api` étant sur le réseau partagé `erpnext_erpnext`, `db`/`redis`
   résolvaient vers le **Postgres/Redis d'ERPNext** (« password auth failed for user karrio »).
   → `.env` : `DATABASE_HOST=karrio.db`, `REDIS_HOST=karrio.redis` (noms de conteneurs non ambigus).
2. **Attache réseau** : `docker network connect` est perdu au recreate → réseaux dans l'`override.yml`.
3. **Admin non auto-semé** : créer manuellement —
   binaire = `/karrio/venv/bin/karrio` (absent du PATH en `bash -lc` → utiliser `docker exec ... sh -c`).
   ```
   docker exec -e KPW=<pw> karrio.api sh -c "cd /karrio/app && karrio shell < /tmp/mkadmin.py"
   # mkadmin.py : get_user_model().objects.create_superuser('admin@targo.ca', os.environ['KPW'])
   ```
4. Réinit DB si besoin : `docker compose down -v` (sinon vieux creds persistent dans le volume).

---

## Intégration prévue (hub → #54)

`services/targo-hub/lib/shipping.js` exposera `quoteRates({origin, dest, parcel})` :
1. token JWT (`POST /api/token`) → cache,
2. appel API Karrio (rates) avec origine (entrepôt) + destination (client) + colis
   (poids = `Item.weight_per_unit` ERPNext),
3. options de tarif → ligne « Frais de livraison » au checkout boutique,
4. `/store/checkout` → Sales Invoice ERPNext (`update_stock`) + Stripe via `lib/payments.js`.

---

## Sources

- Karrio — dépôt : <https://github.com/karrioapi/karrio>
- Karrio — intégrations transporteurs : <https://docs.karrio.io/carriers/>
- Karrio — Canada Post : <https://docs.karrio.io/carriers/integrations/canadapost>
- Karrio — Purolator : <https://www.karrio.io/docs/carriers/purolator>
- Karrio — plateforme / éditions : <https://www.karrio.io/platform>
- Karrio — starter Next.js (dashboard) : <https://docs.karrio.io/resources/nextjs-starter>
- Extension Canpar (PyPI) : <https://pypi.org/project/karrio_canpar/>
- Agrégateurs canadiens — eShipper : <https://www.eshipper.com/>
- Agrégateurs canadiens — Freightcom : <https://www.freightcom.com/>
- ShipTime (transporteurs/rabais, non Karrio-natif) : <https://ca.linkedin.com/company/shiptime>
- Comparatif shipping APIs 2026 : <https://revaddress.com/blog/shipping-api-comparison-2026/>
- Comparatif transporteurs Canada 2026 : <https://www.goodfirms.co/supply-chain-logistics-companies/shipping/canada>

_Mémoire interne liée : `project_karrio_shipping.md`._