Documentation de l’API

Vue d’ensemble

URL de base

Toutes les routes ci-dessous utilisent cette URL et renvoient du JSON UTF-8.

https://master-sms.shop/api/v1

Démarrage rapide

Créez une clé dans le tableau de bord, gardez le secret côté serveur et lancez une première consultation du solde.

Gérer les clés

Utilisez l’API Secret uniquement côté backend. Ne placez jamais les identifiants dans un navigateur, une application distribuée ou un dépôt public.

Authentification

Envoyez les deux identifiants sur chaque route protégée.

Headers

Accept: application/json
Content-Type: application/json
X-API-Key: your_api_key
X-API-Secret: your_api_secret

Format des réponses

Les succès renvoient success=true et data. Les erreurs renvoient success=false, error et le statut HTTP correspondant.

{
    "success": true,
    "data": {
        "example": "value"
    },
    "timestamp": 1785078000
}

{
    "success": false,
    "error": "Description de l’erreur",
    "code": 400
}

Référence des endpoints

Les routes documentées correspondent au contrôleur public de l’API v1.

GET /health Route publique

État de l’API

Confirme que l’API fonctionne et renvoie sa version.

Exemple de réponse

{
    "success": true,
    "data": {
        "version": "4.2.0",
        "status": "operational",
        "timestamp": 1785078000,
        "server_time": "2026-07-26 12:00:00",
        "request_id": "req_01K123EXAMPLE"
    },
    "timestamp": 1785078000
}

GET /balance Authentification requise

Consulter le solde

Renvoie le solde total, bloqué, disponible et la devise.

Exemple de réponse

{
    "success": true,
    "data": {
        "balance": 1250.5,
        "blocked": 50,
        "available": 1200.5,
        "currency": "BRL",
        "limit": 0
    },
    "timestamp": 1785078000
}

GET /services Authentification requise

Lister les services

Liste pays, services, opérateurs, fournisseurs, prix calculés et stock.

Filtres optionnels

Paramètre	Type	Description	Exemple
`country`	string	Code numérique du pays.	`73`
`service`	string	Code du service, par exemple wa.	`wa`
`operator`	string	Opérateur précis ou liste acceptée par le fournisseur.	`claro`
`available`	boolean	Si true, renvoie uniquement les éléments en stock.	`true`
`provider`	string	Nom ou identifiant du fournisseur.	`Hero SMS`
`search`	string	Recherche textuelle par service.	`WhatsApp`

Exemple de requête

GET https://master-sms.shop/api/v1/services?country=73&available=true

Exemple de réponse

{
    "success": true,
    "data": [
        {
            "country_id": "73",
            "country_name": "Brasil",
            "services": [
                {
                    "code": "wa",
                    "name": "WhatsApp",
                    "operator": "claro",
                    "price": 2.5,
                    "stock": 150,
                    "provider": "Hero SMS",
                    "category": "messenger",
                    "markup": 10
                }
            ]
        }
    ],
    "timestamp": 1785078000
}

POST /buy Authentification requise

Acheter un numéro

Achète un numéro virtuel et crée une activation SMS.

Corps JSON

Champ	Type	Obligatoire	Description
`service`	string	Oui	Code du service, par exemple wa.
`country`	string	Oui	Code numérique du pays.
`request_id`	string	Oui	Identifiant unique de tentative d’achat empêchant les doublons.
`operator`	string	Non	Opérateur précis ou liste acceptée par le fournisseur.
`provider`	string	Non	Nom ou identifiant du fournisseur.
`max_price`	number	Non	Prix maximal accepté dans la devise renvoyée par l’API.

request_id: Générez un nouveau request_id par intention d’achat et réutilisez-le uniquement pour répéter cette même intention après une erreur réseau.

max_price: L’achat échoue avant facturation si le prix calculé dépasse max_price.

Exemple de requête

{
    "service": "wa",
    "country": "73",
    "operator": "claro",
    "provider": "Hero SMS",
    "max_price": 5,
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Exemple de réponse

{
    "success": true,
    "data": {
        "activation_id": "ACT17850780001234",
        "phone": "5511999999999",
        "operator": "claro",
        "price": 2.5,
        "currency": "BRL",
        "request_id": "550e8400-e29b-41d4-a716-446655440000",
        "service_name": "WhatsApp"
    },
    "timestamp": 1785078000
}

GET /status?activation_id={id} Authentification requise

Consulter une activation

Actualise et renvoie le statut, le numéro et le code SMS.

Paramètre	Obligatoire	Description
`activation_id`	Oui	ID renvoyé par l’achat.

Statuts possibles

Status	Description
`pending`	En attente du SMS.
`received`	SMS reçu ; code contient le code.
`canceled`	Activation annulée.
`expired`	Activation expirée.

Exemple de réponse

{
    "success": true,
    "data": {
        "activation_id": "ACT17850780001234",
        "status": "received",
        "phone": "5511999999999",
        "created_at": 1785078000,
        "code": "123456",
        "received_at": 1785078060
    },
    "timestamp": 1785078060
}

POST /cancel Authentification requise

Annuler une activation

Annule une activation éligible et indique le remboursement.

L’annulation dépend du délai minimal, du statut et des règles du fournisseur. Une activation ayant reçu un SMS ne peut plus être annulée.

Corps JSON

{ "activation_id": "ACT17850780001234" }

Exemple de réponse

{
    "success": true,
    "data": {
        "activation_id": "ACT17850780001234",
        "status": "canceled",
        "refunded": true,
        "refund_amount": 2.5
    },
    "timestamp": 1785078300
}

POST GET DELETE /webhook Authentification requise

Webhooks

Enregistre, liste et supprime les destinations des événements asynchrones.

Événements disponibles

Événement	Description
`sms.received`	SMS reçu.
`sms.purchased`	Numéro acheté.
`sms.status`	Statut d’activation modifié.
`balance.low`	Solde sous le seuil configuré.

POST /webhook · Corps JSON

Champ	Obligatoire	Description
`event`	Oui	Nom de l’événement signé.
`url`	Oui	URL HTTPS publique recevant un POST JSON.
`secret`	Non	Secret utilisé pour la signature HMAC SHA-256.

{
    "event": "sms.received",
    "url": "https://example.com/webhooks/master-sms",
    "secret": "replace_with_a_random_secret"
}

GET /webhook

La liste ne renvoie jamais le secret enregistré.

DELETE /webhook · Corps JSON

{ "webhook_id": 1 }

Payload envoyé par le webhook

{
    "event": "sms.received",
    "timestamp": 1785078060,
    "data": {
        "activation_id": "ACT17850780001234",
        "code": "123456",
        "phone": "5511999999999",
        "service": "wa",
        "received_at": 1785078060
    },
    "signature": "legacy_body_signature"
}

GET /stats Authentification requise

Statistiques

Renvoie les totaux d’achats, SMS reçus, annulations, dépenses et remboursements.

{
    "success": true,
    "data": {
        "total_compras": 42,
        "total_recebidos": 31,
        "total_cancelados": 11,
        "total_gasto": 79.5,
        "total_estornado": 21
    },
    "timestamp": 1785078000
}

GET /commissions Authentification requise

Commissions

Renvoie les commissions en attente, payées et l’historique du revendeur authentifié.

{
    "success": true,
    "data": {
        "pending_total": 15.3,
        "paid_total": 120,
        "commissions": []
    },
    "timestamp": 1785078000
}

Sécurité des webhooks

Le corps brut est signé en HMAC SHA-256. Comparez X-Webhook-Signature en temps constant avant de traiter le JSON.

Répondez rapidement en HTTP 2xx. La file réessaie les échecs avec des délais progressifs.

$rawBody = file_get_contents('php://input');
$received = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $rawBody, getenv('MASTER_SMS_WEBHOOK_SECRET'));

if ($received === '' || !hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}

$event = json_decode($rawBody, true, flags: JSON_THROW_ON_ERROR);
http_response_code(204);

Exemples d’intégration

Clients backend minimaux. Adaptez timeouts, logs et stockage des secrets.

<?php
final class MasterSmsClient
{
    public function __construct(
        private string $apiKey,
        private string $apiSecret,
        private string $baseUrl = 'https://master-sms.shop/api/v1'
    ) {}

    public function request(string $method, string $path, ?array $body = null): array
    {
        $ch = curl_init(rtrim($this->baseUrl, '/') . $path);
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CUSTOMREQUEST => $method,
            CURLOPT_TIMEOUT => 30,
            CURLOPT_HTTPHEADER => [
                'Accept: application/json',
                'Content-Type: application/json',
                'X-API-Key: ' . $this->apiKey,
                'X-API-Secret: ' . $this->apiSecret,
            ],
            CURLOPT_POSTFIELDS => $body === null ? null : json_encode($body),
        ]);
        $raw = curl_exec($ch);
        $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        if ($raw === false) {
            throw new RuntimeException(curl_error($ch));
        }
        curl_close($ch);
        $result = json_decode($raw, true, flags: JSON_THROW_ON_ERROR);
        if ($status < 200 || $status >= 300 || empty($result['success'])) {
            throw new RuntimeException($result['error'] ?? "HTTP {$status}", $status);
        }
        return $result['data'] ?? [];
    }
}

$client = new MasterSmsClient(
    getenv('MASTER_SMS_API_KEY'),
    getenv('MASTER_SMS_API_SECRET')
);
$balance = $client->request('GET', '/balance');
$services = $client->request('GET', '/services?country=73&available=true');
$purchase = $client->request('POST', '/buy', [
    'service' => 'wa',
    'country' => '73',
    'request_id' => bin2hex(random_bytes(16)),
]);

import os
import uuid
import requests

class MasterSmsClient:
    def __init__(self):
        self.base_url = "https://master-sms.shop/api/v1"
        self.session = requests.Session()
        self.session.headers.update({
            "Accept": "application/json",
            "Content-Type": "application/json",
            "X-API-Key": os.environ["MASTER_SMS_API_KEY"],
            "X-API-Secret": os.environ["MASTER_SMS_API_SECRET"],
        })

    def request(self, method, path, *, params=None, json=None):
        response = self.session.request(
            method, self.base_url + path, params=params, json=json, timeout=30
        )
        payload = response.json()
        if not response.ok or not payload.get("success"):
            raise RuntimeError(payload.get("error", f"HTTP {response.status_code}"))
        return payload.get("data", {})

client = MasterSmsClient()
balance = client.request("GET", "/balance")
services = client.request("GET", "/services", params={
    "country": "73", "available": "true"
})
purchase = client.request("POST", "/buy", json={
    "service": "wa",
    "country": "73",
    "request_id": str(uuid.uuid4()),
})

import crypto from "node:crypto";

const baseUrl = "https://master-sms.shop/api/v1";
const headers = {
  Accept: "application/json",
  "Content-Type": "application/json",
  "X-API-Key": process.env.MASTER_SMS_API_KEY,
  "X-API-Secret": process.env.MASTER_SMS_API_SECRET,
};

async function request(method, path, body) {
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), 30_000);
  try {
    const response = await fetch(baseUrl + path, {
      method,
      headers,
      body: body ? JSON.stringify(body) : undefined,
      signal: controller.signal,
    });
    const payload = await response.json();
    if (!response.ok || !payload.success) {
      throw new Error(payload.error ?? `HTTP ${response.status}`);
    }
    return payload.data ?? {};
  } finally {
    clearTimeout(timeout);
  }
}

const balance = await request("GET", "/balance");
const purchase = await request("POST", "/buy", {
  service: "wa",
  country: "73",
  request_id: crypto.randomUUID(),
});

export MASTER_SMS_API_KEY="your_api_key"
export MASTER_SMS_API_SECRET="your_api_secret"
export MASTER_SMS_BASE_URL="https://master-sms.shop/api/v1"

curl --fail-with-body --silent --show-error \
  "$MASTER_SMS_BASE_URL/balance" \
  -H "Accept: application/json" \
  -H "X-API-Key: $MASTER_SMS_API_KEY" \
  -H "X-API-Secret: $MASTER_SMS_API_SECRET"

curl --fail-with-body --silent --show-error \
  "$MASTER_SMS_BASE_URL/buy" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $MASTER_SMS_API_KEY" \
  -H "X-API-Secret: $MASTER_SMS_API_SECRET" \
  --data '{"service":"wa","country":"73","request_id":"550e8400-e29b-41d4-a716-446655440000"}'

Prompt d’intégration par IA

Copiez ce prompt, indiquez votre stack et envoyez-le à une IA de programmation. Ne collez jamais votre API Secret.

Stack cible

Vous êtes ingénieur logiciel senior. Implémentez une intégration de production avec l’API Master SMS dans cette stack : [ex. Laravel, Node.js, Django, Flutter avec backend].

Contrat obligatoire :
- URL de base : https://master-sms.shop/api/v1
- Authentification uniquement côté backend avec X-API-Key et X-API-Secret.
- Les identifiants proviennent de variables d’environnement et n’apparaissent jamais dans les logs, le frontend, une application distribuée ou le dépôt.
- Toutes les réponses sont en JSON. Gérez success, data, error, statut HTTP et timeouts.

Implémentez :
1. Client réutilisable avec timeout, retry uniquement pour opérations sûres, logs nettoyés et erreurs typées.
2. GET /balance.
3. GET /services avec country, service, operator, available, provider et search.
4. POST /buy avec service, country et request_id obligatoires ; operator, provider et max_price optionnels. Générez un UUID et conservez-le pour la même intention après timeout.
5. GET /status?activation_id=... avec polling limité et backoff.
6. POST /cancel avec activation_id.
7. POST, GET et DELETE /webhook.
8. GET /stats et GET /commissions.
9. Récepteur de webhook lisant le corps brut et validant X-Webhook-Signature par HMAC SHA-256 et comparaison en temps constant avant le JSON.

Qualité :
- N’inventez aucun endpoint ni champ.
- N’appelez jamais l’API directement depuis un navigateur ou une app mobile avec le Secret.
- Ne répétez pas POST /buy avec un autre request_id après une réponse incertaine.
- Gérez HTTP 400, 401, 402, 403, 404, 405, 409, 429 et 500.
- Utilisez un backoff exponentiel avec jitter pour 429 et les erreurs transitoires.
- Validez les entrées et normalisez les URL.
- Incluez tests unitaires, tests avec mocks, .env.example sans secret, README et exemple.
- Livrez les fichiers complets, expliquez les identifiants et les décisions de sécurité.

Avant le code, listez brièvement les fichiers. Puis implémentez tout sans TODO.

Erreurs et traitement

Code	Signification	Traitement recommandé
`400`	Requête invalide	Corrigez JSON, champs obligatoires ou règles.
`401`	Non authentifié	Vérifiez X-API-Key et X-API-Secret.
`402`	Solde insuffisant	Rechargez le compte avant l’achat.
`403`	Accès refusé	Activez la permission ou vérifiez la liste d’IP.
`404`	Introuvable	Vérifiez route, service, stock ou activation_id.
`405`	Méthode invalide	Utilisez la méthode HTTP documentée.
`409`	Conflit d’idempotence	Ne réutilisez pas request_id pour un autre achat.
`429`	Limite dépassée	Attendez et réessayez avec backoff.
`500`	Erreur interne	Conservez request_id et réessayez sans dupliquer l’achat.

Rate limit

La limite par minute dépend de la clé et figure dans X-RateLimit-Limit. Sur HTTP 429, utilisez un backoff exponentiel avec jitter.

Checklist de sécurité

Stockez API Key et Secret dans des variables d’environnement ou un coffre.
Appelez l’API uniquement depuis le backend ; apps et navigateurs appellent votre serveur.
Utilisez HTTPS, timeouts, logs sans identifiants et validation JSON stricte.
Utilisez un request_id idempotent et ne changez jamais l’identifiant après un timeout.
Validez la signature du webhook sur le corps brut avant toute modification d’état.

Master sms API

Vue d’ensemble

URL de base

Démarrage rapide

Authentification

Headers

Format des réponses

Référence des endpoints

État de l’API

Exemple de réponse

Consulter le solde

Exemple de réponse

Lister les services

Filtres optionnels

Exemple de requête

Exemple de réponse

Acheter un numéro

Corps JSON

Exemple de requête

Exemple de réponse

Consulter une activation

Statuts possibles

Exemple de réponse

Annuler une activation

Corps JSON

Exemple de réponse

Webhooks

Événements disponibles

POST /webhook · Corps JSON

GET /webhook

DELETE /webhook · Corps JSON

Payload envoyé par le webhook

Statistiques

Commissions

Sécurité des webhooks

Exemples d’intégration

Prompt d’intégration par IA

Erreurs et traitement

Rate limit

Checklist de sécurité