# Votre domaine et votre marque

> Servez le portail de vos vendeurs sur un domaine à vous, et envoyez-leur les e-mails de Wajub à votre marque.

Vos vendeurs doivent voir votre plateforme, pas la nôtre. Leur portail peut répondre sur un domaine
à vous, `vendeurs.maplateforme.com`, au lieu de `votrenom.wajub.app`, et les e-mails que Wajub leur
envoie portent votre nom, votre logo et votre couleur.

## Votre propre domaine

| Règle                              |                                                                                                                                                                                               |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Un domaine par plateforme          | Un **sous-domaine** seulement, jamais la racine d'une zone : une racine ne peut pas porter de `CNAME`                                                                                         |
| Test et live à la fois             | Le domaine n'est pas lié à un environnement : il sert le portail dans les deux. Une clé de test le lit ; le déclarer et le retirer demandent une **clé live** (sinon `403 live_key_required`) |
| Tout le suit                       | Une fois actif, le portail, les [composants embarqués](https://docs.wajub.com/fr/sync/embedded-components) et tous les liens que Wajub envoie à vos vendeurs l'utilisent                                               |
| L'ancienne adresse marche toujours | `votrenom.wajub.app` répond encore : un lien déjà envoyé s'ouvre toujours                                                                                                                     |

### Le mettre en place

1. **Déclarez le domaine**

   Sous **Paramètres, Sync, Plateforme**, dans **Votre propre domaine**, ou avec
   `PUT /sync/portal_domain`.

2. **Créez deux enregistrements DNS**

   Chez votre fournisseur DNS, les deux enregistrements que la réponse liste (ci-dessous).

3. **Attendez la vérification**

   Wajub les vérifie toutes les 10 minutes pendant 72 heures ; **Vérifier maintenant** dans le
   Dashboard le fait tout de suite. Quand les deux sont bons, Wajub route le domaine et obtient son
   certificat TLS : le statut passe `active`.

```bash title="Déclarer le domaine"
curl -X PUT https://api.wajub.com/sync/portal_domain \
  -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
  -H "Content-Type: application/json" \
  -d '{"domain":"vendeurs.maplateforme.com"}'
```

| Type    | Nom                                       | Valeur                                   |
| ------- | ----------------------------------------- | ---------------------------------------- |
| `CNAME` | `vendeurs.maplateforme.com`               | `portals.wajub.app`                      |
| `TXT`   | `_wajub-verify.vendeurs.maplateforme.com` | Le jeton de la réponse, `wajub-portal-…` |

Gardez les deux enregistrements tant que vous utilisez le domaine. Une fois actif, Wajub les revérifie **chaque jour** : un échec isolé ne coupe rien et affiche un avertissement sous **Paramètres, Sync, Plateforme**, pas plus qu'une vérification dont la lecture DNS n'obtient aucune réponse, sauf si cela dure : quand les résolveurs de Wajub n'obtiennent aucune réponse de votre zone pendant **plus de 72 heures d'affilée**, le domaine est retiré comme après trois échecs. Après **trois échecs d'affilée**, environ 72 heures, le domaine passe `failed`, le portail cesse d'y répondre, tous les liens reviennent à `votrenom.wajub.app`, et le propriétaire et les administrateurs de votre organisation reçoivent un e-mail. Corrigez les enregistrements, puis déclarez de nouveau le domaine : le jeton ne change pas.

Wajub ne reprend jamais un hôte déjà routé ailleurs sur Wajub, le domaine de paiement d'un marchand par exemple : la vérification reste alors `verifying` avec `routing_failed`.

> [!WARNING]
> **Trois pièges**
>
> Si votre DNS passe par un proxy (un nuage orange, par exemple), mettez le `CNAME` en **DNS seul** :
> un enregistrement proxifié cache le `CNAME` (`cname_missing`) et empêche le certificat. Certains
> panneaux DNS ajoutent votre domaine au nom tout seuls : saisissez-y `vendeurs` et
> `_wajub-verify.vendeurs`. Les guillemets autour de la valeur `TXT` sont acceptés.

### Les statuts

| `status`      | Signifie                                                                                                                                                                                                                                                                                |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pending_dns` | Déclaré ; les enregistrements ne sont pas encore bons. `last_error` dit pourquoi                                                                                                                                                                                                        |
| `verifying`   | Les enregistrements sont bons ; Wajub route le domaine et obtient son certificat, en quelques minutes                                                                                                                                                                                   |
| `active`      | Servi. Tous les liens du portail l'utilisent                                                                                                                                                                                                                                            |
| `failed`      | Pas vérifié en 72 heures ; ou actif, puis en échec à trois vérifications quotidiennes d'affilée, ou sans réponse de votre zone pendant plus de 72 heures d'affilée. Déclarez-le de nouveau pour relancer 72 heures, **avec le même jeton** : l'enregistrement `TXT` déjà posé reste bon |
| `removed`     | Retiré par vous                                                                                                                                                                                                                                                                         |
| `blocked`     | Bloqué par Wajub, qui dit pourquoi dans `removal_reason` : un domaine en service, retiré, en échec, ou jamais déclaré. Aucune plateforme ne peut le déclarer tant que Wajub n'a pas levé le blocage ; il passe alors `removed`                                                          |

| `last_error`         | Signifie                                                                                                    |
| -------------------- | ----------------------------------------------------------------------------------------------------------- |
| `cname_missing`      | Aucun `CNAME` sur le domaine, ou un `CNAME` proxifié                                                        |
| `cname_wrong_target` | Le `CNAME` pointe ailleurs que sur `portals.wajub.app`                                                      |
| `txt_missing`        | Aucun enregistrement `TXT` sur `_wajub-verify.<domaine>`                                                    |
| `txt_mismatch`       | L'enregistrement `TXT` ne porte pas le jeton                                                                |
| `dns_unavailable`    | Le DNS n'a pas pu être lu : rien n'est conclu, Wajub réessaie 10 minutes plus tard                          |
| `routing_failed`     | Les enregistrements sont bons mais le routage n'est pas encore en place : nouvel essai 10 minutes plus tard |
| `expired`            | Les 72 heures sont passées sans autre erreur connue                                                         |

### Le gérer

| Appel                        | Fait                                                                                                                                                                                                |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /sync/portal_domain`    | Votre domaine, en vérification ou actif ; après un retrait ou un échec, le dernier déclaré ; `null` si vous n'en avez jamais déclaré                                                                |
| `PUT /sync/portal_domain`    | Le déclare : `201`. Le même domaine de nouveau ne change rien : `200`, même jeton. Un autre domaine remplace celui encore en vérification ; un domaine `active` doit d'abord être retiré            |
| `DELETE /sync/portal_domain` | Le retire : le portail cesse aussitôt d'y répondre et les liens reviennent à `votrenom.wajub.app`. Le routage disparaît dans les 10 minutes ; vous pouvez ensuite supprimer les enregistrements DNS |

Tous trois s'appellent avec votre propre clé, jamais avec `X-Sync`. `PUT` et `DELETE` demandent une clé live.
Retirer un domaine puis le déclarer de nouveau ne coupe jamais le portail sur la nouvelle
déclaration : l'ancien routage n'est retiré que si aucune déclaration ne revendique l'hôte.

| `error_code`              | Statut | Quand                                                                        |
| ------------------------- | ------ | ---------------------------------------------------------------------------- |
| `invalid_domain`          | `422`  | Pas un nom d'hôte : un chemin, un port, un joker, une adresse IP, une espace |
| `apex_domain`             | `422`  | La racine d'une zone, comme `maplateforme.com` ou `shop.co.uk`               |
| `reserved_domain`         | `422`  | Un domaine de Wajub                                                          |
| `live_key_required`       | `403`  | `PUT` ou `DELETE` avec une clé de test                                       |
| `domain_blocked`          | `409`  | Wajub a bloqué ce domaine                                                    |
| `domain_taken`            | `409`  | Déclaré par une autre plateforme, ou domaine de paiement d'un marchand       |
| `portal_domain_active`    | `409`  | Vous avez déjà un domaine actif : retirez-le d'abord                         |
| `portal_domain_not_found` | `404`  | `DELETE` sans domaine déclaré                                                |

## Ce que voient vos vendeurs

Sous **Paramètres, Sync, Plateforme**, **Ce que voient vos vendeurs** fixe votre marque pour eux.
Laissé vide, chaque champ reprend **Paramètres, Image de marque** : le nom de votre organisation, sa
couleur principale et son logo.

| Champ             |                                                                                                                                                                                                        |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Nom affiché       | 60 caractères au plus                                                                                                                                                                                  |
| E-mail de support | Les réponses des vendeurs y arrivent (`Reply-To`), une fois l'adresse confirmée par le code que Wajub y envoie (**Envoyer un code**, puis **Confirmer**). La changer demande une nouvelle confirmation |
| Couleur           | `#rrggbb`                                                                                                                                                                                              |
| Logo              | PNG, JPEG ou WebP, 1 Mo au plus, 32 à 2 000 pixels de côté. Le SVG est refusé                                                                                                                          |

Le portail, les composants embarqués, les e-mails ci-dessous et les relevés annuels de vos vendeurs
l'utilisent. Dans les e-mails, votre nom affiché et votre logo apparaissent une fois votre plateforme
approuvée par Wajub pour Lite ou Relay ; avant, le nom de votre organisation et pas de logo.

### Les comptes de versement sur votre domaine

Sur votre domaine, vos vendeurs voient leur compte de versement mais le changent sur leur adresse
Wajub, `votrenom.wajub.app/payout-account` : vous tenez le certificat de votre domaine, Wajub n'y
laisse donc jamais confirmer un changement de destination de l'argent. La page du portail montre les
comptes en lecture seule avec un lien qui ouvre cette adresse dans un nouvel onglet, et le
[composant embarqué `account`](https://docs.wajub.com/fr/sync/embedded-components#changing-the-payout-account) fait de même.
Là, le vendeur se connecte avec son propre code, envoyé au propriétaire de son espace, et reste sur
l'adresse Wajub. L'e-mail du code de connexion nomme l'hôte où il a été demandé : le vendeur n'entre
le code que là.

### Les e-mails à votre marque

Ces e-mails parviennent à vos vendeurs Lite, et à vos vendeurs Relay pour leur invitation, à votre
marque :

- le code de connexion au portail ;
- l'invitation à une connexion `lite` ou `relay` (une invitation `direct` reste celle de Wajub : le
  marchand ouvre un compte Wajub) ;
- leur vérification d'identité : action requise, échéance dépassée, nouvelle vérification, statut
  changé ;
- paiements suspendus ou réactivés, et fin de la connexion ;
- un litige ouvert sur leur vente, et son rappel ([Litiges sur les ventes de vos vendeurs](https://docs.wajub.com/fr/sync/disputes)).

| Partie             | Ce qu'elle dit                                                                                                                                                                                                                                         |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Expéditeur         | « votrenom via Wajub », `votrenom` étant le nom d'espace validé par Wajub (`votrenom.wajub.app`), jamais le nom affiché libre ; « Wajub » seul tant qu'aucun nom n'est validé. Depuis l'adresse d'envoi de Wajub : pas de domaine d'envoi personnalisé |
| Reply-To           | Votre e-mail de support, une fois confirmé                                                                                                                                                                                                             |
| En-tête et boutons | Votre logo, ou votre nom ; votre couleur, sauf si elle est trop claire pour un texte blanc                                                                                                                                                             |
| Pied               | « Vous recevez cet e-mail au sujet de votre compte vendeur sur Votre plateforme. », puis « Paiements traités par Wajub » et le lien de confidentialité de Wajub                                                                                        |
| Liens              | Sur votre domaine actif                                                                                                                                                                                                                                |

Deux e-mails restent à la voix de Wajub, quelle que soit votre marque : le code pour changer de
compte de versement, qui nomme le nouveau compte (l'opérateur, les 4 derniers chiffres), et l'avis
que le compte de versement a changé (4 derniers chiffres, date, reprise des versements, que faire si
le vendeur n'en est pas l'auteur). Leur expéditeur est « votrenom via Wajub », leur en-tête ne porte
que votre nom d'espace validé, sans votre logo, votre couleur ni votre Reply-To, et leur lien mène à
l'adresse Wajub du vendeur, jamais à votre domaine.

- [Onboarding](https://docs.wajub.com/fr/sync/onboarding#a-lite-sellers-own-portal): Le portail, son adresse, et le portail dans vos propres pages.
- [Composants embarqués](https://docs.wajub.com/fr/sync/embedded-components): Des morceaux de l'espace vendeur dans vos pages.
- [Déclarer le domaine du portail](https://docs.wajub.com/fr/api/subaccounts/declare-portal-domain): La spécification de l'endpoint.
