API-Dokumentation - Master sms

Übersicht

Basis-URL

Alle folgenden Routen verwenden diese Basis-URL und liefern UTF-8-JSON.

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

Schnellstart

Erstellen Sie einen Schlüssel, speichern Sie das Secret nur serverseitig und führen Sie die erste Guthabenabfrage aus.

Schlüssel verwalten

Verwenden Sie das API Secret nur im Backend. Zugangsdaten gehören niemals in Browser, verteilte Apps oder öffentliche Repositories.

Authentifizierung

Senden Sie beide Zugangsdaten bei jeder geschützten Route.

Headers

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

Antwortformat

Erfolge liefern success=true und data. Fehler liefern success=false, error und den passenden HTTP-Status.

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

{
    "success": false,
    "error": "Fehlerbeschreibung",
    "code": 400
}

Endpoint-Referenz

Die dokumentierten Routen entsprechen dem öffentlichen Front Controller der API v1.

GET /health Öffentliche Route

API-Status

Bestätigt die Betriebsbereitschaft und liefert die Version.

Beispielantwort

{
    "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 Authentifizierung erforderlich

Guthaben abrufen

Liefert Gesamt-, gesperrtes und verfügbares Guthaben sowie die Währung.

Beispielantwort

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

GET /services Authentifizierung erforderlich

Dienste auflisten

Listet Länder, Dienste, Betreiber, Anbieter, berechnete Preise und Bestand.

Optionale Filter

Parameter	Typ	Beschreibung	Beispiel
`country`	string	Numerischer Ländercode.	`73`
`service`	string	Dienstcode, zum Beispiel wa.	`wa`
`operator`	string	Bestimmter Betreiber oder eine vom Anbieter unterstützte Liste.	`claro`
`available`	boolean	Bei true werden nur verfügbare Einträge geliefert.	`true`
`provider`	string	Name oder Kennung des Anbieters.	`Hero SMS`
`search`	string	Textsuche nach Dienst.	`WhatsApp`

Beispielanfrage

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

Beispielantwort

{
    "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 Authentifizierung erforderlich

Nummer kaufen

Kauft eine virtuelle Nummer und erstellt eine SMS-Aktivierung.

JSON-Body

Feld	Typ	Erforderlich	Beschreibung
`service`	string	Ja	Dienstcode, zum Beispiel wa.
`country`	string	Ja	Numerischer Ländercode.
`request_id`	string	Ja	Eindeutige Kaufversuchs-ID zur Vermeidung von Duplikaten.
`operator`	string	Nein	Bestimmter Betreiber oder eine vom Anbieter unterstützte Liste.
`provider`	string	Nein	Name oder Kennung des Anbieters.
`max_price`	number	Nein	Maximal akzeptierter Preis in der von der API gelieferten Währung.

request_id: Erzeugen Sie pro Kaufabsicht eine neue request_id und verwenden Sie denselben Wert nur für die Wiederholung derselben Absicht nach einem Netzwerkfehler.

max_price: Der Kauf scheitert vor der Belastung, wenn der berechnete Preis max_price überschreitet.

Beispielanfrage

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

Beispielantwort

{
    "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} Authentifizierung erforderlich

Aktivierung abrufen

Aktualisiert und liefert Status, Nummer und SMS-Code.

Parameter	Erforderlich	Beschreibung
`activation_id`	Ja	Beim Kauf gelieferte ID.

Mögliche Status

Status	Beschreibung
`pending`	Wartet auf SMS.
`received`	SMS empfangen; code enthält den Code.
`canceled`	Aktivierung storniert.
`expired`	Aktivierung abgelaufen.

Beispielantwort

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

POST /cancel Authentifizierung erforderlich

Aktivierung stornieren

Storniert eine berechtigte Aktivierung und meldet die Erstattung.

Storno hängt von Mindestzeit, Status und Anbieterregeln ab. Aktivierungen mit bereits empfangener SMS sind nicht stornierbar.

JSON-Body

{ "activation_id": "ACT17850780001234" }

Beispielantwort

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

POST GET DELETE /webhook Authentifizierung erforderlich

Webhooks

Registriert, listet und entfernt Ziele für asynchrone Ereignisse.

Verfügbare Ereignisse

Ereignis	Beschreibung
`sms.received`	SMS empfangen.
`sms.purchased`	Nummer gekauft.
`sms.status`	Aktivierungsstatus geändert.
`balance.low`	Guthaben unter dem konfigurierten Grenzwert.

POST /webhook · JSON-Body

Feld	Erforderlich	Beschreibung
`event`	Ja	Name des signierten Ereignisses.
`url`	Ja	Öffentliche HTTPS-URL für JSON-POSTs.
`secret`	Nein	Secret zur Erzeugung der HMAC-SHA-256-Signatur.

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

GET /webhook

Die Liste liefert das gespeicherte Secret niemals zurück.

DELETE /webhook · JSON-Body

{ "webhook_id": 1 }

Webhook-Payload

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

GET /stats Authentifizierung erforderlich

Statistiken

Liefert Summen für Käufe, empfangene SMS, Stornos, Ausgaben und Erstattungen.

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

GET /commissions Authentifizierung erforderlich

Provisionen

Liefert offene und bezahlte Provisionen sowie den Verlauf des angemeldeten Resellers.

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

Webhook-Sicherheit

Der Roh-Body wird mit HMAC SHA-256 signiert. Vergleichen Sie X-Webhook-Signature in konstanter Zeit, bevor Sie JSON verarbeiten.

Antworten Sie schnell mit HTTP 2xx. Fehlgeschlagene Zustellungen werden mit steigenden Pausen wiederholt.

$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);

Integrationsbeispiele

Minimale Backend-Clients. Passen Sie Timeouts, Logs und Secret-Speicherung an.

<?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"}'

KI-Integrationsprompt

Kopieren Sie diesen Prompt, geben Sie Ihren Stack an und senden Sie ihn an eine Programmier-KI. Fügen Sie niemals Ihr API Secret ein.

Ziel-Stack

Sie sind Senior Software Engineer. Implementieren Sie eine produktionsreife Integration mit der Master SMS API in diesem Stack: [z. B. Laravel, Node.js, Django, Flutter mit Backend].

Verbindlicher Vertrag:
- Basis-URL: https://master-sms.shop/api/v1
- Authentifizierung nur im Backend mit X-API-Key und X-API-Secret.
- Zugangsdaten kommen aus Umgebungsvariablen und erscheinen nie in Logs, Frontend, verteilter App oder Quellcodeverwaltung.
- Alle Antworten sind JSON. Behandeln Sie success, data, error, HTTP-Status und Timeouts.

Implementieren Sie:
1. Wiederverwendbaren Client mit Timeout, Retries nur für sichere Operationen, bereinigten Logs und typisierten Fehlern.
2. GET /balance.
3. GET /services mit country, service, operator, available, provider und search.
4. POST /buy mit service, country und request_id als Pflichtfeldern; operator, provider und max_price optional. Erzeugen Sie eine UUID und behalten Sie sie bei Wiederholung derselben Absicht nach Timeout.
5. GET /status?activation_id=... mit begrenztem Polling und Backoff.
6. POST /cancel mit activation_id.
7. POST, GET und DELETE /webhook.
8. GET /stats und GET /commissions.
9. Webhook-Empfänger, der den Roh-Body liest und X-Webhook-Signature mit HMAC SHA-256 und zeitkonstantem Vergleich prüft, bevor JSON verarbeitet wird.

Qualität:
- Erfinden Sie keine Endpoints oder Felder.
- Rufen Sie die API nie direkt aus Browser oder mobiler App mit dem Secret auf.
- Wiederholen Sie POST /buy nach unsicherer Antwort nie mit anderer request_id.
- Behandeln Sie HTTP 400, 401, 402, 403, 404, 405, 409, 429 und 500.
- Nutzen Sie exponentielles Backoff mit Jitter für 429 und temporäre Fehler.
- Validieren Sie Eingaben und normalisieren Sie URLs.
- Liefern Sie Unit-Tests, Mock-Integrationstests, .env.example ohne Secrets, README und Beispiel.
- Liefern Sie vollständige Dateien und erklären Sie Zugangsdaten sowie Sicherheitsentscheidungen.

Listen Sie vor dem Code kurz die Dateien auf. Implementieren Sie danach alles ohne TODOs.

Fehler und Behandlung

Code	Bedeutung	Empfohlene Behandlung
`400`	Ungültige Anfrage	Korrigieren Sie JSON, Pflichtfelder oder Regeln.
`401`	Nicht authentifiziert	Prüfen Sie X-API-Key und X-API-Secret.
`402`	Guthaben unzureichend	Laden Sie das Konto vor dem Kauf auf.
`403`	Zugriff verweigert	Aktivieren Sie die Berechtigung oder prüfen Sie die IP-Liste.
`404`	Nicht gefunden	Prüfen Sie Route, Dienst, Bestand oder activation_id.
`405`	Ungültige Methode	Verwenden Sie die dokumentierte HTTP-Methode.
`409`	Idempotenzkonflikt	Nutzen Sie request_id nicht für einen anderen Kauf.
`429`	Limit überschritten	Warten Sie und versuchen Sie es mit Backoff erneut.
`500`	Interner Fehler	Bewahren Sie request_id und vermeiden Sie einen doppelten Kauf.

Rate Limit

Das Minutenlimit hängt vom Schlüssel ab und steht in X-RateLimit-Limit. Verwenden Sie bei HTTP 429 exponentielles Backoff mit Jitter.

Sicherheitscheckliste

Speichern Sie API Key und Secret in Umgebungsvariablen oder einem Secret Vault.
Rufen Sie die API nur aus dem Backend auf; Apps und Browser verwenden Ihren Server.
Verwenden Sie HTTPS, Timeouts, Logs ohne Zugangsdaten und strikte JSON-Prüfung.
Verwenden Sie eine idempotente request_id und ändern Sie sie nach einem Timeout nicht.
Prüfen Sie die Webhook-Signatur über den Roh-Body vor jeder Zustandsänderung.

Master sms API

Übersicht

Basis-URL

Schnellstart

Authentifizierung

Headers

Antwortformat

Endpoint-Referenz

API-Status

Beispielantwort

Guthaben abrufen

Beispielantwort

Dienste auflisten

Optionale Filter

Beispielanfrage

Beispielantwort

Nummer kaufen

JSON-Body

Beispielanfrage

Beispielantwort

Aktivierung abrufen

Mögliche Status

Beispielantwort

Aktivierung stornieren

JSON-Body

Beispielantwort

Webhooks

Verfügbare Ereignisse

POST /webhook · JSON-Body

GET /webhook

DELETE /webhook · JSON-Body

Webhook-Payload

Statistiken

Provisionen

Webhook-Sicherheit

Integrationsbeispiele

KI-Integrationsprompt

Fehler und Behandlung

Rate Limit

Sicherheitscheckliste