# CySmS Reseller API

Documentation publique (aucun compte requis pour la lire).
HTML: https://cysms.store/api-docs
Index LLM: https://cysms.store/llms.txt

CySmS fournit des numéros virtuels pour la réception de SMS OTP. Un achat API suit **le même parcours** qu’un achat dans l’application : contrôles CySmS (maintenance, solde) puis débit du **prix de vente CySmS**, pas le coût fournisseur.

Ne jamais exposer la clé API (`cs_live_...`) dans une app mobile ou une page web. Appeler l’API depuis un backend.

## Base URL

- REST JSON: `https://cysms.store/api/reseller`
- Stubs (protocole SMS-Activate): `https://cysms.store/stubs/handler_api.php`

En local: `http://localhost:3000/api/reseller`

## Authentification

Chaque requête doit inclure la clé.

1. Header (recommandé): `X-Api-Key: cs_live_xxxxxxxx`
2. Bearer: `Authorization: Bearer cs_live_xxxxxxxx`
3. Query: `?api_key=cs_live_xxxxxxxx`

## Provider (gamme)

- `auto` — tente V2 puis bascule V1
- `v2` — premium uniquement
- `v1` — standard uniquement

Le catalogue `getServices` est **indicatif**. `buyNumber` débite le prix CySmS calculé au moment de l’achat.

## Endpoints REST

Toujours lire `success` dans le JSON, pas seulement le code HTTP. Pour axios: `validateStatus: () => true`.

### getBalance

`GET /api/reseller?action=getBalance`

Réponse: `{ "success": true, "credits": 12.50 }`

### getServices

`GET /api/reseller?action=getServices&provider=v2`

### getCountries

`GET /api/reseller?action=getCountries`

156 pays. Exemple: `77` = France, `27` = Côte d’Ivoire, `12` = États-Unis.

### buyNumber

`POST /api/reseller?action=buyNumber`

Body JSON:

```json
{ "service": "wa", "country": "77", "provider": "auto" }
```

Les paramètres `service`, `country` et `provider` peuvent aussi être passés en query string.

Succès HTTP 200:

```json
{
  "success": true,
  "orderId": "123456",
  "phone": "+336...",
  "service": "wa",
  "country": "77",
  "price": 1.20,
  "sellingPrice": 1.20,
  "chargedAmount": 1.20,
  "provider": "Service V2 (CySmS Premium)",
  "serviceType": "v2",
  "status": "PENDING"
}
```

Échecs métier:

| HTTP | error | Signification |
|------|-------|----------------|
| 200 | NO_NUMBERS | Pas de stock pour ce service/pays |
| 400 | MISSING_SERVICE / MISSING_COUNTRY | Paramètre manquant |
| 401 | BAD_KEY | Clé absente ou invalide |
| 409 | NO_BALANCE | Solde insuffisant |
| 409 | PRICE_CHANGED | Tarif actualisé, réessayer |
| 503 | MAINTENANCE / PROVIDER_UNAVAILABLE | Service indisponible |
| 504 | TIMEOUT | Fournisseur trop lent |

### getStatus

`GET /api/reseller?action=getStatus&orderId=123456`

`status`: `PENDING` | `RECEIVED` | `CANCELED` | `EXPIRED`

Si `RECEIVED`: champs `sms` et `code` (OTP extrait).

### cancelOrder

`POST /api/reseller?action=cancelOrder`

Body: `{ "orderId": "123456" }`

Rembourse le prix CySmS débité si l’annulation est acceptée.

## Webhooks

Jusqu’à 3 URL HTTPS. HMAC SHA-256 dans `X-CySms-Signature`.

Événements: `activation.created`, `activation.sms_received`, `activation.canceled`, `activation.expired`, `webhook.test`.

Actions: `getWebhook`, `setWebhook`, `testWebhook`.

Répondre HTTP 200. Timeout 3s, 1 retry.

## Stubs SMS-Activate

`GET /stubs/handler_api.php?api_key=...&action=getBalance`
Réponse texte: `ACCESS_BALANCE:12.50`

Achat: `action=getNumber&service=wa&country=77`
Réponse: `ACCESS_NUMBER:orderId:phone`

Statut: `action=getStatus&id=orderId`
Annulation: `action=setStatus&id=orderId&status=8`

## Cycle recommandé

1. `buyNumber`
2. Polling `getStatus` toutes les 3–5 s (max 15–20 min) **ou** webhook `activation.sms_received`
3. Si timeout: `cancelOrder`

## Services courants

| code | service |
|------|---------|
| wa | WhatsApp |
| tg | Telegram |
| go | Google / Gmail |
| ig | Instagram |
| tk | TikTok |
| fb | Facebook |
| tw | Twitter / X |
| ot | Autre |

## Prompt pour assistant IA

Intègre l’API CySmS (numéros virtuels OTP). Base: `https://cysms.store/api/reseller`. Auth: `X-Api-Key`. Achat: POST `buyNumber` avec `{service, country, provider}`. Identique à l’app: débit du prix de vente CySmS. Succès: `success: true` + `orderId` + `phone`. Échec stock: HTTP 200 `NO_NUMBERS`. Solde: HTTP 409 `NO_BALANCE`. Poll `getStatus` ou webhook. Timeout → `cancelOrder`. Spec complète: https://cysms.store/docs/api.md