Eine API für Bestellungen, Guthaben und den Marktplatz

Ein Vertrag, versioniert nach Datum

Jeder Endpunkt liegt unter /v1 auf dem Host des Shops, mit dem Sie integrieren. Antworten sind JSON, Geldbeträge sind Dezimalzeichenketten mit einer ISO-4217-Währung, und Zeitstempel sind ISO 8601. Jede Antwort trägt einen Header X-Api-Version mit dem Datum des Vertrags, mit dem Sie kommunizieren, und eine X-Request-Id, die Sie beim Support angeben können. Fehler haben immer denselben Body: ein Fehlerobjekt mit einem stabilen Code, einer lesbaren Meldung und optionalen Details, zusammen mit der request_id.

Die OpenAPI-3.1-Datei beschreibt jeden Pfad, jedes Schema und jeden Fehlercode. Importieren Sie sie in Ihren HTTP-Client oder Generator, und Sie erhalten typisierte Anfragen für Katalog, Bestellungen, Guthaben, Inserate, Angebote und Geschäftsübergaben.

Schlüssel, Berechtigungen und das Konto, für das sie handeln

Ein Schlüssel wird vom Kontoinhaber im Wiederverkäufer-Tarif erstellt und einmal angezeigt; gespeichert wird nur ein Hash. Bei der Erstellung wählen Sie seine Berechtigungen, eine optionale IP-Allowlist mit bis zu 20 Adressen und ein optionales Ablaufdatum. Eine Rotation erstellt einen neuen Schlüssel mit denselben Berechtigungen und widerruft den alten, sodass Sie Zugangsdaten ohne Ausfallzeit austauschen können. Mit einem Schlüssel aufgegebene Bestellungen werden vom Kontoguthaben belastet und erscheinen im selben Dashboard wie manuelle Bestellungen, mit der Quelle API.

Jeder Schlüssel erbt das Limit der Anfragen pro Minute der Kundenstufe des Kontos. Die Header RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset zeigen Ihren Stand; wird das Limit überschritten, antwortet die API mit 429 und einem Header Retry-After, und die richtige Reaktion ist, genau diese Zeit zu warten.

Idempotente Schreibvorgänge und Stapel

Die Erstellung einer Bestellung ist der einzige Aufruf, der Geld bewegt, daher ist sie doppelt geschützt. Erstens ist der Header Idempotency-Key Pflicht: Die Wiederholung einer Anfrage mit demselben Schlüssel liefert die ursprüngliche Bestellung ohne zweite Belastung, und die Wiederverwendung des Schlüssels mit einem anderen Body wird mit 409 IDEMPOTENCY_KEY_REUSE abgelehnt. Zweitens erkennt ein Doppelbestellungsfenster denselben Dienst, Link und dieselbe Menge, die in einem kurzen Intervall ohne passenden Schlüssel erneut gesendet werden, und antwortet mit 409 DUPLICATE_ORDER.

Stapel nehmen bis zu 100 Bestellungen pro Aufruf an. Jedes Element wird einzeln geprüft und belastet, identifiziert über den Stapelschlüssel plus seinen Index; die Antwort listet ein Ergebnis pro Element, sodass eine fehlerhafte Zeile nie die übrigen blockiert. Nutzen Sie zuerst POST /v1/orders/preview, wenn Sie die genaue Belastung und das Prüfergebnis ohne Anlegen wollen.

• Erzeugen Sie eine UUID pro logischer Bestellung und speichern Sie sie, bevor Sie senden.
• Bei Zeitüberschreitungen senden Sie mit demselben Schlüssel erneut; erzeugen Sie für dieselbe Bestellung nie einen neuen.
• 4xx-Codes gelten als endgültig; 5xx-Codes und 429 als wiederholbar mit steigender Wartezeit.

Webhooks, denen Sie vertrauen können

Jede Zustandsänderung wird in derselben Datenbanktransaktion wie die Änderung selbst in eine Outbox geschrieben, und ein Verteiler liefert sie an Ihren https-Endpunkt mit drei Headern: Webhook-Id, Webhook-Timestamp und Webhook-Signature. Die Signatur ist ein HMAC-SHA256 über den Zeitstempel, einen Punkt und den rohen Body, berechnet mit dem Endpunkt-Geheimnis, das bei der Erstellung einmal angezeigt wird. Prüfen Sie sie in konstanter Zeit, lehnen Sie Zeitstempel ab, die älter als fünf Minuten sind, und dedupliziere nach Webhook-Id, weil ein wiederholtes Ereignis dieselbe Id trägt.

Zustellungen ohne 2xx werden nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, 6 Stunden, 12 Stunden und 24 Stunden wiederholt, bevor sie als endgültig ausgefallen markiert werden. Antworten Sie schnell und verarbeiten Sie asynchron; ein langsamer Handler ist der häufigste Grund für doppelte Verarbeitung.

Kinder-Panels über den SMM-v2-Endpunkt

Wenn Ihr Panel bereits das verbreitete Format „SMM API v2“ spricht, können Sie diesen Shop als Anbieter hinzufügen, indem Sie die URL /api/v2 und Ihren Schlüssel einfügen. Die Aktionen services, add, status, balance, refill, refill_status und cancel werden unterstützt, Preise kommen in Ihrer Kontowährung und Ihrer Stufe zurück, und Fehler nutzen die flache Form { "error": "message" }, die solche Panels erwarten. Die Idempotenz wird aus dem Bestellinhalt und der aktuellen Minute abgeleitet, sodass versehentliche Doppelübermittlungen innerhalb derselben Minute zusammengeführt werden.