Appairage d’un compte

L’appairage lie une application tierce à un compte (un Company Mon SMS Pro, ou le client d’un revendeur) et produit un connectionToken. Trois méthodes sont disponibles, de la plus automatique à la plus manuelle.

Méthode A — Provisioning serveur-à-serveur (sans QR)

Idéale lorsque votre backend connaît déjà l’identité du compte (cas revendeur). Aucun code à recopier : la connexion est créée et le connectionToken renvoyé immédiatement.

curl -X POST "https://rest.monsms.pro/v1/third-party-app/provision" \
  -H "Content-Type: application/json" \
  -d '{
    "apiSecret": "msp_…",
    "externalAccountId": "tenant_123",
    "target": "partnerCustomer",
    "partnerServerKey": "psk_…",
    "partnerCustomerId": "CUSTOMER_ID",
    "defaultSenderId": "SENDER_ID"
  }'

Réponse :

{
  "success": true,
  "data": {
    "connectionId": "…",
    "connectionToken": "ct_…",
    "status": "CONNECTED",
    "target": "partnerCustomer",
    "senderAssigned": true
  }
}

• target: "partnerCustomer" — le revendeur autorise via sa partnerServerKey (psk_…) et la connexion débite le pool de son client. Voir le scénario revendeur.
• target: "company" — le compte autorise via sa propre companyApiKey + companyId (fournis par le backend du compte lui-même).

Le provisioning est idempotent par (application, externalAccountId) : ré-appeler conserve le même connectionToken.

Méthode B — Deep-link une touche

1. Votre application appelle pairing/initiate pour obtenir un code.
2. Vous ouvrez l’application mobile Mon SMS Pro via le lien : monsmspro://pair?code=<CODE>&app=<slug> (ou le lien universel https://monsmspro.com/pair?code=<CODE>&app=<slug>).
3. L’utilisateur voit un écran « Autoriser <App> ? » et tape Autoriser.

# 1. Initier
curl -X POST "https://rest.monsms.pro/v1/third-party-app/pairing/initiate" \
  -H "Content-Type: application/json" \
  -d '{ "apiSecret": "msp_…", "externalAccountId": "tenant_123" }'
# → { "pairingCode": "A2B3C4D5", "expiresAt": "…", "qrContent": "MSPAPP_A2B3C4D5" }

L’application mobile récupère les détails de l’app pour l’écran de confirmation :

curl -X POST "https://rest.monsms.pro/v1/third-party-app/pairing/details" \
  -H "Content-Type: application/json" \
  -d '{ "apiKey": "…", "companyId": "…", "pairingCode": "A2B3C4D5" }'

Méthode C — Code / QR simplifié

L’utilisateur saisit le code (ou scanne le QR MSPAPP_<CODE>) dans son application Mon SMS Pro, puis confirme. La confirmation assigne aussi le Sender ID dans le même appel :

curl -X POST "https://rest.monsms.pro/v1/third-party-app/pairing/confirm" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "…",
    "companyId": "…",
    "pairingCode": "A2B3C4D5",
    "senderId": "SENDER_ID"
  }'

• Si senderId est omis et que le compte n’a qu’un seul Sender ID accepté, il est assigné automatiquement.
• Votre application récupère le connectionToken :
  • soit via le webhook connection.paired (recommandé, voir Webhooks),
  • soit en interrogeant pairing/status (apiSecret + externalAccountId).