Shopify Netgsm SMS-Integration: 3 Wege für Bestell-, Versand- und Warenkorb-SMS

Die Shopify Netgsm SMS-Integration verbindet Bestell-, Versand- und Stornierungsereignisse eines Shopify-Shops mit der SMS-API von Netgsm und sendet Kunden automatische Nachrichten unter dem genehmigten SMS-Absendernamen der Marke. Sie ist Teil der E-Commerce-Kommunikationsinfrastruktur und besteht aus zwei Schichten: auf der Shopify-Seite ein Webhook oder Flow-Trigger, der das Ereignis erfasst; auf der Netgsm-Seite die API, die die Nachricht an den Mobilfunkbetreiber übergibt. In den Integrationen, die wir aufgebaut haben, entstanden die meisten Störungen nicht beim API-Aufruf selbst, sondern zwischen den beiden Schichten. Rufnummern kommen im falschen Format an, dieselbe Bestellung löst zwei SMS aus, oder eine Kampagnennachricht geht raus, ohne den İYS-Filter zu durchlaufen. Dazu kommt eine aktuelle Entwicklung: Mit Stand 13. November 2026 ist die eigene Shopify-App von Netgsm nicht im App Store gelistet. Damit wird die Wahl des Einrichtungswegs zur ersten Entscheidung des Projekts.

Was ist die Shopify Netgsm SMS-Integration und welche Nachrichten automatisiert sie?

Die Shopify Netgsm SMS-Integration ist eine Automatisierung, die ein Ereignis in Shopify (Bestellung erstellt, versendet, storniert) in eine SMS-Anfrage an die Netgsm-API umwandelt. Informationsnachrichten wie Bestellbestätigungen und Sendungsnummern sowie werbliche Nachrichten wie Warenkorb-Erinnerungen und Kampagnen laufen über dieselbe Infrastruktur. Beide unterliegen jedoch unterschiedlichen rechtlichen Regeln, und Sie müssen die Integration entlang dieser Trennung aufbauen.

Netgsm ist ein türkisches Kommunikationsunternehmen, das Massen-SMS, OTP-SMS und Sprachnachrichten anbietet. Laut der offiziellen JavaScript-SDK-Dokumentation von Netgsm besteht die aktuelle API aus zwei Teilen: /sms/v3 für den Nachrichtenversand und /iys/v1 für Einwilligungsdatensätze. Die Authentifizierung erfolgt über /auth/v3 mit einem Token. Die alte Adresse api.netgsm.com.tr funktioniert weiterhin; verwenden Sie für neue Projekte jedoch ext-api.netgsm.com.tr. Sandbox-Umgebung, Zustellbericht-Webhooks und detaillierte Fehlercodes gibt es nur in der neuen API.

Der Unterschied zwischen Informations-SMS und Werbe-SMS

Das türkische Gesetz Nr. 6563 zur Regulierung des elektronischen Handels stuft Nachrichten, die Waren oder Dienstleistungen bewerben, vermarkten oder den Verkauf fördern, als "kommerzielle elektronische Nachrichten" ein. Bevor Sie sie versenden, benötigen Sie die Einwilligung des Empfängers und müssen diese im İYS (İleti Yönetim Sistemi, dem nationalen Nachrichtenverwaltungssystem der Türkei) erfassen. Eine Nachricht über den Status einer vom Kunden aufgegebenen Bestellung ist informativ und erfordert keine İYS-Einwilligung.

Die Unterscheidung richtet sich nach dem Inhalt der Nachricht, nicht nach ihrem Typ. Deshalb birgt das Template-Design der Integration unmittelbar ein rechtliches Risiko.

Kritischer Hinweis: Sobald Sie an eine SMS mit Sendungsnummer den Satz "10 % Rabatt auf Ihre nächste Bestellung: KOD10" anhängen, gilt die Nachricht als Werbenachricht und erfordert eine İYS-Einwilligung. Halten Sie Gutscheine, Kampagnen und Produktempfehlungen aus Ihren Informations-Templates heraus.

Wie İYS-Datensätze den Shopify-Kundendaten zugeordnet werden, haben wir Schritt für Schritt in unserem Leitfaden zur Shopify İYS-Integration erklärt. Die SMS-Integration baut auf dieser Struktur auf: Sind die Einwilligungsdaten falsch, erzeugt selbst ein sauber aufgebauter SMS-Ablauf ein rechtliches Risiko.

Warum reichen die integrierten SMS-Benachrichtigungen von Shopify nicht aus?

Shopify bietet unter Einstellungen > Benachrichtigungen SMS-Templates für Bestellbestätigung und Versandupdates. In den von uns betreuten Shops haben wir diese Templates aus drei Gründen für den türkischen Markt als unzureichend eingestuft:

• Shopify sendet diese SMS nur, wenn der Kunde beim Checkout eine Telefonnummer als Kontaktmöglichkeit wählt. Ein Kunde, der per E-Mail bestellt, aber eine Telefonnummer in die Lieferadresse einträgt, erhält keine SMS.
• Der Absendername ist nicht der vom Betreiber genehmigte SMS-Absendername Ihrer Marke. Der Kunde erhält die Nachricht von einer unbekannten Nummer, und türkische Verbraucher, die an Betrugsnachrichten gewöhnt sind, klicken seltener auf Links in solchen SMS.
• Türkei-spezifische Abläufe wie die Bestätigung von Nachnahmebestellungen, Erinnerungen an Banküberweisungen oder Sendungsnummern aus einem ERP sind in den integrierten Templates nicht vorhanden.

Diese Grenzen werden sichtbar, wenn der Shop wächst. Eine Beschwerde "Ich habe keine SMS bekommen", die bei 20 Bestellungen am Tag untergeht, wird bei 300 Bestellungen am Tag zu einer täglichen Zusatzlast für den Kundenservice.

Welches Shopify-Ereignis löst welche SMS aus?

Jede SMS entspricht einem Ereignis in Shopify und dem Webhook-Thema (Topic) dieses Ereignisses. Die folgende Tabelle zeigt den Standardablauf, den wir für Shops mit Verkauf in die Türkei einrichten:

Die am häufigsten übersehene Zeile der Tabelle ist die Nachnahme. Der Webhook orders/create wird bei einer Nachnahmebestellung im selben Moment ausgelöst wie bei einer per Karte bezahlten Bestellung. Wenn Sie kein eigenes Template je Zahlungsart einrichten, erhält der Nachnahmekunde die Nachricht "Ihre Zahlung ist eingegangen". Bei Nodus Works machen wir diese SMS in Shops mit hohem Nachnahmeanteil zu einem Bestätigungsschritt: Antwortet der Kunde mit "EVET" (ja), wird die Bestellung in Shopify markiert und gelangt erst dann ins Lager. Der Webhook für eingehende Nachrichten von Netgsm (registerInboxWebhook) bringt diese Antwort zurück in die Integration.

3 Wege, Shopify mit Netgsm zu verbinden: fertige App, Shopify Flow und individuelle Integration

Sie verbinden Shopify auf einem von drei Wegen mit Netgsm: über eine fertige Shopify-App, die Netgsm unterstützt, über Shopify Flow mit einem kleinen Zwischendienst oder über eine individuelle App, die Shopify-Webhooks empfängt. Für Shops, denen Standard-Templates genügen und die weniger als einige tausend SMS im Monat versenden, reicht eine fertige App. Gibt es Nachnahmebestätigung, Versanddaten aus einem ERP oder Versand aus mehreren Lagern, ist eine individuelle Integration nötig.

Die Frage, die die Wahl entscheidet, lautet: Liegt jede Information in der SMS innerhalb von Shopify? Wenn Bestellnummer, Produktname und Tracking-Link in Shopify liegen, erledigt eine fertige App die Aufgabe. Kommt die Sendungsnummer aus Nebim, Logo oder von einem Versandaggregator, sehen die Template-Felder der App diese Daten nicht.

Weg 1: Eine fertige Shopify-App, die Netgsm unterstützt

Als wir am 13. November 2026 nachsahen, zeigte die Listing-Seite von "Netgsm SMS", der von Netgsm selbst entwickelten App, den Hinweis "derzeit nicht im Shopify App Store verfügbar". Für Shops, die die App früher installiert haben, bedeutet das: Neuinstallationen sind nicht möglich. Fragen Sie Netgsm direkt, ob die App zurückkehrt.

Eine der Apps, die Netgsm heute direkt anbindet, ist Sendzi: WhatsApp & SMS von Gurmehub. Die App verwaltet Netgsm, Kobikom, Verimor und WhatsApp in einem Panel. Die Tarife auf der Listing-Seite:

• Kostenlos: 0 $/Monat, Nutzungsgebühr von 0,05 $ pro Nachricht
• Basic: 9 $/Monat, die ersten 1.000 Nachrichten kostenlos, danach 0,03 $
• Growth: 19 $/Monat, die ersten 3.000 Nachrichten kostenlos, Shopify-Flow-Kompatibilität
• PRO: 49 $/Monat, unbegrenzte Nachrichten

Die App ist seit dem 12. August 2026 verfügbar und hat auf ihrer Listing-Seite bisher eine einzige Bewertung. Stellen Sie dem Entwickler vor der Installation einer so jungen App zwei Fragen schriftlich. Erstens: Fällt die Nachrichtengebühr aus dem Listing zusätzlich zum SMS-Guthaben in Ihrem Netgsm-Konto an? Zweitens: Mit welchem İYS-Filterwert werden Werbenachrichten gesendet?

Weg 2: Shopify Flow und ein kleiner Zwischendienst

Shopify Flow kann nach einem Trigger wie "Order created" oder "Customer abandons checkout" mit der Aktion "Send HTTP request" eine Anfrage an eine externe Adresse senden. Auf den ersten Blick wirkt eine direkte Verbindung von Flow zu Netgsm möglich. In der Praxis gibt es zwei Hindernisse:

1. Die neue API von Netgsm erwartet, dass Sie zuerst über /auth/v3 einen Token abrufen und dann senden. Eine einzelne HTTP-Anfrage in Flow kann diesen zweistufigen Ablauf nicht sauber abbilden.
2. Benutzername und Passwort für Netgsm stehen in der Flow-Aktion. Jeder Mitarbeitende mit Bearbeitungsrechten für Flow im Shop kann sie sehen.

Die Lösung ist ein Cloudflare Worker oder eine ähnliche kleine Serverless-Funktion dazwischen. Flow sendet mit einem geheimen Header (etwa X-Webhook-Secret) eine Anfrage an den Worker. Der Worker holt den Token, formatiert die Rufnummer und leitet die Nachricht an Netgsm weiter. Das offizielle SDK von Netgsm ist für Cloudflare Workers geschrieben und braucht keine zusätzlichen Abhängigkeiten. Prüfen Sie im Flow-Editor, ob die HTTP-Aktion in Ihrem Tarif verfügbar ist.

Zu vermeidendes Risiko: Legen Sie Ihr Netgsm-Passwort nicht im Theme-Code, in der Datei theme.liquid oder in einem ScriptTag ab. Genau deshalb wirft das offizielle SDK von Netgsm im Browser einen Fehler: Jeder Besucher im Browser kann Ihr Passwort sehen und über Ihr Konto SMS versenden.

Weg 3: Eine individuelle Shopify-App, die Webhooks empfängt

Eine individuelle App wird für Ihren Shop erstellt und nur dort installiert. Sie abonniert Webhook-Themen wie orders/create, fulfillments/create und orders/cancelled, verarbeitet das eingehende Ereignis auf dem eigenen Server und sendet es an Netgsm. Nur auf diesem Weg lassen sich Daten von außerhalb Shopifys in den SMS-Inhalt einbinden.

Am meisten Sorgfalt verlangt bei einer individuellen App der Schutz vor Duplikaten. Laut der Shopify-Webhook-Dokumentation sendet Shopify dasselbe Ereignis erneut, wenn Ihre App nicht innerhalb von 5 Sekunden antwortet. Die SDK-Dokumentation von Netgsm sagt es klar: Die API dedupliziert Anfragen nicht; eine zweite Anfrage eröffnet einen zweiten Versandauftrag, und der Kunde erhält die Nachricht doppelt.

Erhält Netgsm dieselbe Anfrage zweimal, sendet es zwei separate SMS; die Wiederholung zu verhindern ist Aufgabe der App auf der Shopify-Seite. Speichern Sie daher den Header X-Shopify-Webhook-Id jedes Webhooks und überspringen Sie den Versand, wenn dieselbe ID ein zweites Mal eintrifft. Tragen Sie die Shopify-Bestellnummer in das Feld referenceId der Netgsm-Anfrage ein; so sehen Sie im Zustellbericht, welche SMS zu welcher Bestellung gehört.

Bei SMS-Abläufen, die auf Daten außerhalb von Shopify beruhen, etwa Nachnahmebestätigung, Sendungsnummern aus einem ERP oder lagerbasierte Absenderwahl, reichen die Template-Felder fertiger Apps nicht aus. Unser Service für Shopify-Integrationen und individuelle App-Entwicklung baut diese Abläufe mit Webhook-Verifizierung, Duplikatschutz und Zustellberichten in einer einzigen App auf.

Die drei Wege im Vergleich

Unsere Haltung: Ist der Shop neu, starten Sie mit einer fertigen App und messen Sie in den ersten drei Monaten, welche SMS tatsächlich Beschwerden reduziert. Entscheiden Sie erst mit diesen Daten über eine individuelle Integration. Wer eine individuelle App beauftragt, ohne seine Abläufe zu kennen, bezahlt Entwicklung für fünf Templates, die niemand nutzt.

Vor der Einrichtung: Netgsm-Konto, SMS-Absendername und API-Benutzer

Um über die Netgsm-API SMS zu senden, müssen in Ihrem Konto drei Dinge bereitstehen: ein genehmigter Absendername (SMS-Header), ein zugewiesenes SMS-Paket und ein Unterbenutzer mit API-Berechtigung. Laut dem Netgsm-Wissensdatenbankartikel "SMS-Versand per API" und der Netgsm-API-Dokumentation verwendet die Integration Ihre Teilnehmernummer als Benutzernamen, das Passwort des API-Unterbenutzers als Passwort und den genehmigten Header als Absender.

Die längste dieser drei Vorbereitungen ist die Header-Genehmigung, denn Netgsm leitet den Antrag an einen Partnerbetreiber weiter, und der Betreiber verlangt Unterlagen. Webhooks und Templates sind in wenigen Tagen fertig; keines davon kann live gehen, bevor der Header genehmigt ist. Starten Sie den Header-Antrag daher am selben Tag wie die Integrationsentwicklung.

Wie wird ein SMS-Absendername genehmigt?

Der SMS-Absendername ist der Name, der auf dem Telefon des Kunden statt einer Nummer erscheint, zum Beispiel NODUSSTORE. Sie beantragen ihn im Netgsm-Panel und müssen den Bezug des Headers zu Ihrer Firmenbezeichnung oder Marke belegen. Die geforderten Unterlagen und die Genehmigungsdauer unterscheiden sich je nach Betreiber; die aktuelle Liste erhalten Sie im Antragsformular oder bei Ihrem Netgsm-Ansprechpartner.

Denken Sie bei der Header-Wahl auch an Werbenachrichten. Laut dem Quellcode des offiziellen Netgsm-Testservers lehnt die API einen Versand mit İYS-Filter mit dem Fehler REJECTED_IYS ab, wenn dem Header kein İYS-Markencode zugeordnet ist. Bitten Sie Netgsm nach der Genehmigung des Headers gesondert darum, Ihren İYS-Markencode damit zu verknüpfen.

API-Unterbenutzer und IP-Beschränkung

Schreiben Sie das Passwort Ihres Hauptkontos in keine Integration. Der von Netgsm empfohlene Ablauf:

1. Öffnen Sie im Netgsm-Panel Abonelik İşlemleri > Alt Kullanıcı Hesapları > Yeni Kayıt (Abonnement > Unterbenutzerkonten > Neuer Eintrag).
2. Wählen Sie als Benutzertyp API Kullanıcısı (API-Benutzer) und aktivieren Sie im Berechtigungsbildschirm nur den Dienst SMS.
3. Geben Sie den an Ihre registrierte Mobilnummer gesendeten Code ein und aktivieren Sie den Zugriff, indem Sie das Feld "API ile hesap erişimini onaylıyorum" (Ich bestätige den Kontozugriff per API) markieren.

Da der Unterbenutzer ein eigenes Passwort hat, schließen Sie nach Ende der Zusammenarbeit mit einer Agentur nur diesen Benutzer; Ihr Hauptkonto bleibt unberührt.

Die IP-Beschränkung erfordert eine eigene Entscheidung. Sie können die Netgsm-API so einschränken, dass sie nur von bestimmten IP-Adressen genutzt werden kann; ein gestohlenes Passwort lässt sich dann nicht von einem anderen Server verwenden. Cloudflare Workers und ähnliche Serverless-Umgebungen bieten jedoch keine feste ausgehende IP. Ist für eine Integration, die aus einem Serverless-Dienst sendet, die IP-Beschränkung aktiv, lehnt Netgsm jede Anfrage mit Fehlercode 30 ab; dieser Code bedeutet "ungültiger Benutzername, ungültiges Passwort oder keine API-Zugriffsberechtigung". Wenn Sie eine IP-Beschränkung wollen, senden Sie von einem Server mit fester IP.

Kostenlos testen in der Sandbox-Umgebung

Laut der offiziellen SDK-Dokumentation von Netgsm hat die neue API drei Umgebungen:

• Lokaler Mock (127.0.0.1:4010): Kein Abonnement nötig, sendet keine SMS. Zum Testen von Fehlerszenarien dient der Open-Source-Testserver von Netgsm.
• Sandbox (ext-sandbox.netgsm.com.tr): Läuft mit echtem Netzwerk und Token-Ablauf, nutzt Demokonten, sendet keine SMS und ist kostenlos.
• Live (ext-api.netgsm.com.tr): Echter, kostenpflichtiger Versand.

Die folgende Tabelle zeigt, wie die API reagiert, wenn eine Vorbereitung fehlt. Nutzen Sie sie vor dem Livegang als Checkliste:

Zu vermeidendes Risiko: Für İYS gibt es weder eine Sandbox noch einen Mock. Die SDK-Dokumentation von Netgsm stellt klar, dass jede in İYS gespeicherte Einwilligung ein live geführter Rechtsdatensatz ist, der sich nachträglich nicht bearbeiten lässt. Testen Sie den İYS-Ablauf nicht mit Testnummern oder erfundenen Datensätzen.

Shopify Netgsm SMS-Integration Schritt für Schritt einrichten (HowTo)

Sie richten die Shopify Netgsm SMS-Integration per Webhook in fünf Schritten ein: Bestell- und Versand-Webhooks in Shopify abonnieren, die Signatur eingehender Anfragen prüfen, das Template mit Bestelldaten füllen, an Netgsm senden und die Referenznummer speichern sowie den Zustellbericht-Webhook anbinden. Die folgenden Schritte beschreiben den Weg über eine individuelle App; nutzen Sie Flow mit Zwischendienst, gelten ab Schritt 3 dieselben Regeln.

1. Webhook-Abonnements in Shopify aktivieren

Geben Sie Ihrer individuellen App nur die Berechtigungen, die sie braucht: read_orders für Bestellungen, read_customers für die Telefonnummer des Kunden. Die Telefonnummer gehört bei Shopify zu den geschützten Kundendaten (Protected Customer Data). Wenn Sie in der App-Konfiguration keinen Zugriff auf Name, Telefon und Adressfelder beantragen, kommen diese Felder im Webhook-Payload leer an.

Abonnieren Sie dann in der ersten Phase diese Themen: orders/create, fulfillments/create, fulfillments/update und orders/cancelled. Aktivieren Sie den Ablauf für abgebrochene Warenkörbe erst, wenn die İYS-Anbindung fertig ist.

2. Webhook-Signatur prüfen

Shopify sendet jeden Webhook mit einer HMAC-Signatur im Header X-Shopify-Hmac-Sha256, erzeugt mit dem geheimen Schlüssel der App. Berechnen Sie die Signatur über den unveränderten Request-Body; wenn Sie den Body in JSON umwandeln und wieder serialisieren, stimmt die Signatur nicht. Lehnen Sie Anfragen mit ungültiger Signatur mit 401 ab. Ohne Prüfung kann jeder, der Ihre Adresse kennt, Ihren Kunden unter Ihrem Absendernamen SMS schicken.

Laut Shopify-Dokumentation gilt die Zustellung als fehlgeschlagen, wenn Ihre App nicht innerhalb von 5 Sekunden antwortet. Prüfen Sie daher die Signatur, schreiben Sie das Ereignis in eine Warteschlange und antworten Sie sofort mit 200. Senden Sie an Netgsm in einem separaten Prozess, der die Warteschlange abarbeitet.

3. Nachrichten-Template mit Bestelldaten füllen

Beispiel-Template für eine Versand-SMS (auf Türkisch, wie sie an Kunden in der Türkei geht):

Merhaba Ayşe, #1042 numaralı siparişiniz Aras Kargo ile yola çıktı. Takip: https://kargotakip.araskargo.com.tr/?code=1234567890 Nodus Store

Dieser Text ist 139 Zeichen lang. In der türkischen Zeichenkodierung (TURKISH) zählen die Buchstaben "ş", "ı" und "ç" jeweils doppelt, daher beträgt die gewichtete Länge 145, und der Text passt in eine einzige SMS. Die Template-Variablen beziehen Sie so aus Shopify: Kundenname aus shipping_address.first_name, Bestellnummer aus name, Versanddienstleister und Tracking-Link aus den Feldern tracking_company und tracking_urls des Fulfillment-Objekts.

Testen Sie das Template mit dem längsten realen Wert. Steht in einer Bestellung "Muhammed Mustafa" statt "Ayşe", überschreitet derselbe Text 155 Zeichen und wird auf zwei SMS aufgeteilt. Die Netgsm-Operation sms.measureLength gibt vor dem Versand zurück, in wie viele Teile der Text zerlegt wird.

4. An die Netgsm-API senden und Referenznummer speichern

Senden Sie den Auftrag aus der Warteschlange an den Endpunkt POST /sms/v3/send von Netgsm. Füllen Sie im Request-Body immer vier Felder:

• sender: Ihr genehmigter SMS-Absendername
• encoding: TURKISH für türkischen Text
• iysFilter: NONE bei Informations-SMS, der İYS-Filter bei Werbe-SMS (erklärt im nächsten Abschnitt)
• referenceId: die Shopify-Bestellnummer; sie kommt im Zustellbericht und im Webhook zurück

Speichern Sie den Wert jobId aus der Antwort zusammen mit dem Bestelldatensatz. Sagt ein Kunde "Ich habe keine SMS bekommen", findet der Support mit dieser ID im Netgsm-Bericht in zwei Minuten heraus, ob die Nachricht den Betreiber erreicht hat. Eine Bestellnotiz oder ein Metafield genügt dafür.

5. Zustellbericht-Webhook anbinden

Netgsm sendet Zustellberichte an die Adresse, die Sie mit registerReportWebhook festlegen. Definieren Sie bei der Registrierung einen geheimen Header wie X-Webhook-Secret und prüfen Sie ihn bei jeder eingehenden Anfrage.

Laut der SDK-Dokumentation von Netgsm gilt ein Bericht als zugestellt, sobald Ihre Adresse irgendeine 2xx-Antwort liefert; fehlgeschlagene Zustellungen sendet Netgsm nicht erneut. Ist Ihr Berichtsempfänger kurz nicht erreichbar, gehen die Berichte dazwischen verloren. Rufen Sie daher einmal täglich mit sms.getReport die Aufträge des Vortags ab und ergänzen Sie fehlende Berichte. Die Berichtsabfrage ist pro Konto und pro Auftrag begrenzt; nutzen Sie den Webhook als Hauptquelle, statt nach jedem Versand abzufragen.

Rufnummernformat, türkische Zeichen und SMS-Länge

Der häufigste Versandfehler bei der Shopify Netgsm SMS-Integration ist das Rufnummernformat: Shopify speichert die Nummer als +905321234567, die Netgsm-SMS-API erwartet 905321234567, und die İYS-API verlangt wieder +905321234567. Der zweithäufigste Fehler entsteht durch türkische Zeichen: Derselbe Text kann je nach Kodierung auf 1 oder 3 SMS verteilt werden, und genau so viel steht dann auf der Rechnung.

Shopify liefert +90, Netgsm erwartet 90, İYS verlangt +90

Shopify speichert das Feld phone im Kundendatensatz im internationalen E.164-Format (+905321234567). Die SMS-API von Netgsm erwartet das 12-stellige Format 90XXXXXXXXXX. Für internationale Nummern setzen Sie ein - voran und schreiben die Landesvorwahl; dafür braucht Ihr Konto eine Berechtigung für Auslandsversand. İYS-Aufrufe verlangen wiederum das Format +90.

Leiten Sie die Nummer in der Integration vor jedem Versand durch eine einzige Funktion:

function netgsmNummer(roh) {
  let n = String(roh || "").replace(/\D/g, ""); // Nicht-Ziffern entfernen
  if (n.startsWith("0")) n = "9" + n;           // 0532... -> 90532...
  if (n.length === 10 && n.startsWith("5")) n = "90" + n; // 532... -> 90532...
  return /^905\d{9}$/.test(n) ? n : null;       // ungültig: nicht senden
}

Gibt die Funktion null zurück, überspringen Sie den Versand und versehen die Bestellung mit dem Tag "SMS nicht gesendet: ungültige Nummer". Eine ungültige Nummer an Netgsm zu schicken verbraucht kein SMS-Guthaben, erzeugt aber einen NO_DELIVERABLE_MESSAGES-Fehler und füllt die Logs mit Rauschen.

Wie viele Zeichen hat eine SMS mit türkischen Zeichen?

Die Längenberechnung im Open-Source-Testserver von Netgsm legt die Grenzen der drei Kodierungen so fest:

In der Kodierung TURKISH zählen die Buchstaben "ç, ğ, ı, ş, Ğ, İ, Ş" jeweils doppelt; "ö" und "ü" zählen einfach. Die 139 Zeichen lange Versandnachricht aus dem vorigen Abschnitt ist mit TURKISH eine einzige SMS. Hängen Sie an denselben Text ein einziges 📦-Emoji an, wechselt die Kodierung zu UNICODE, die Grenze pro Teil fällt auf 66, und die Nachricht wird auf 3 SMS verteilt. Bei einem Shop mit 5.000 Versand-SMS im Monat hebt dieses eine Emoji die Rechnung von 5.000 auf 15.000 SMS.

Was passiert, wenn die Nummer in der Lieferadresse statt im Kundendatensatz steht?

Bei Kunden, die in Shopify als Gast bestellen, steht die Telefonnummer oft nur im Feld shipping_address.phone. Dieses Feld wird so gespeichert, wie der Kunde es eingetippt hat: 0532 123 45 67, 5321234567 oder +90 (532) 123-4567 sind möglich. Suchen Sie die Nummer in der Integration in dieser Reihenfolge: customer.phone, shipping_address.phone, billing_address.phone. Welche Sie auch finden, leiten Sie sie durch die obige Funktion.

Wenn Sie das Telefonfeld im Checkout nicht zur Pflicht gemacht haben, fehlt bei manchen Bestellungen die Nummer ganz. Da Versanddienstleister für die Zustellung ohnehin eine Telefonnummer verlangen, sollten Shops mit Verkauf in die Türkei das Telefonfeld der Lieferadresse unter Einstellungen > Checkout zur Pflicht machen.

İYS und E-Commerce-Recht: Wie funktioniert der Einwilligungsfilter bei Werbe-SMS?

Werbe-SMS dürfen Sie nur an Empfänger senden, deren Einwilligung im İYS erfasst ist, und Netgsm prüft das beim Versand mit dem Parameter iysFilter. Bei aktivem Filter entfernt Netgsm Nummern ohne İYS-Einwilligung aus dem Versand. So geht selbst dann keine Nachricht an eine Nummer ohne Rechtsdatensatz, wenn die Marketing-Einwilligung in Shopify nicht aktuell ist.

Diese Prüfung nimmt Ihnen die rechtliche Verantwortung nicht ab. Der Filter prüft nur den Datensatz im İYS; diesen Datensatz rechtzeitig und mit der richtigen Quelle anzulegen, ist Aufgabe der Marke.

Die vier Werte des Parameters iysFilter

In der neuen API von Netgsm nimmt iysFilter vier Werte an:

• NONE: Keine İYS-Prüfung. Nur für Informationsnachrichten wie Bestellung, Versand und Erstattung verwenden.
• BRAND: Der Versand wird nach den Einwilligungen unter dem İYS-Markencode gefiltert, der mit dem Header verknüpft ist. Die meisten E-Commerce-Shops mit eigener Marke verwenden diesen Wert.
• RETAILER: Der Filter läuft gegen die Händlerdatensätze der Marke.
• BRAND_AND_RETAILER: Prüft Marken- und Händlerdatensätze gemeinsam.

In einer Shopify Netgsm SMS-Integration muss der Wert von iysFilter an den Nachrichtentyp gebunden sein, nicht an das Template. Die Informations-Warteschlange muss immer mit NONE laufen, die Kampagnen-Warteschlange immer mit BRAND. Wer beide Typen aus derselben Funktion sendet und per Parameter wählt, verschickt eines Tages eine Kampagnennachricht ohne Filter.

Wie wird die Shopify-Marketing-Einwilligung dem İYS-Datensatz zugeordnet?

Shopify speichert die SMS-Marketing-Einwilligung des Kunden im Feld sms_marketing_consent. Setzt der Kunde im Checkout das Häkchen bei "Per SMS über Kampagnen informiert werden", wird dieses Feld subscribed. Ändert sich die Einwilligung, wird der Webhook customers_marketing_consent/update ausgelöst. Dieser Datensatz gelangt jedoch nicht von selbst ins İYS.

In einer korrekten Einrichtung schreibt dieser Webhook die Einwilligung über die İYS-API von Netgsm ins İYS. Der Datensatz enthält den Empfängertyp BIREYSEL (Privatperson), den Einwilligungstyp MESAJ (Nachricht), die Quelle Website (HS_WEB) und den Zeitpunkt der Einwilligung. In umgekehrter Richtung muss ein Widerspruch, den der Kunde über İYS einlegt, die Einwilligung in Shopify über den İYS-Webhook auf unsubscribed setzen. Warum der Einwilligungstext vom ausdrücklichen Einwilligungstext nach KVKK (dem türkischen Datenschutzgesetz) getrennt sein muss, erklären wir in unserem Leitfaden zur Shopify KVKK-Integration.

Tipp: Bei einer İYS-Einwilligungsabfrage liefert eine Nummer ohne Datensatz den errorCode-Wert 81. Wenn Sie vor einer Kampagne die Nummern im Segment abfragen und diejenigen mit 81 entfernen, bereiten Sie keine Nachrichten für Nummern vor, die Netgsm ohnehin herausfiltern würde, und kennen die tatsächliche Versandmenge im Voraus.

Der Einwilligungsablauf ist keine einmalige Einrichtung. Einwilligungen ändern sich täglich auf denselben Daten wie E-Mail-Newsletter, Treueprogramm und Kampagnensegmente. Um die Einwilligungssynchronisierung zwischen Shopify, Klaviyo und Netgsm zusammen mit Segment- und Automatisierungsdesign anzugehen, führt unser Service für E-Mail-Marketing und CRM-Automatisierung SMS- und E-Mail-Einwilligungen in einem einzigen Kundendatensatz zusammen; so stoppt ein Widerspruch in einem Kanal auch den Kampagnenversand im anderen.

Zustellberichte, Fehlercodes und das Risiko doppelter SMS

Eine eingerichtete Shopify Netgsm SMS-Integration fällt meist lautlos aus: Shopify löscht ein fehlerhaftes Webhook-Abonnement, das Netgsm-Guthaben geht zur Neige, oder wiederholte Anfragen schicken dem Kunden doppelte SMS. Wenn Sie nicht alle drei ab dem ersten Tag überwachen, erfahren Sie vom Problem durch eine Kundenbeschwerde.

Warum sendet der Shopify-Webhook dieselbe Bestellung zweimal?

Laut Shopify-Dokumentation wiederholt Shopify einen Webhook, der innerhalb von 5 Sekunden keine Antwort erhält, achtmal innerhalb von vier Stunden. Halten die Fehler an, wird das Abonnement vollständig entfernt. Das hat zwei Folgen:

1. Sendet Ihre App die SMS und führt danach eine Operation aus, die länger als 5 Sekunden dauert, bevor sie antwortet, schickt Shopify dasselbe Ereignis erneut, und der Kunde erhält eine zweite SMS.
2. Ist Ihr Server einige Stunden nicht erreichbar, wird das Abonnement entfernt, und auch nach dem Neustart des Servers gehen keine SMS mehr raus. Bemerkt es niemand, läuft der Shop wochenlang ohne Benachrichtigungen.

Die Lösung hat zwei Teile. Speichern Sie den Wert X-Shopify-Webhook-Id jedes Webhooks und überspringen Sie die Verarbeitung, wenn dieselbe ID ein zweites Mal eintrifft. Führen Sie zusätzlich einmal täglich eine Prüfung aus, die die Webhook-Abonnements über die Shopify-API auflistet und fehlende neu anlegt.

Wie sind Netgsm-Fehlercodes zu deuten?

Die alte API von Netgsm liefert numerische Codes, die neue API Textcodes zusammen mit dem HTTP-Status. Die Codes, denen wir in der Praxis am häufigsten begegnen, und was zu tun ist:

Die letzte Zeile der Tabelle beschreibt den teuersten Fehler. Das SDK von Netgsm kennzeichnet diese Situation mit dem Feld mayHaveBeenProcessed: Bricht die Verbindung ab, hat Netgsm die Anfrage womöglich schon erhalten und die SMS in die Warteschlange gestellt. Eine Integration, die bei Verbindungsfehlern blind erneut sendet, schickt an jedem Tag mit Netzschwankungen einer Gruppe von Kunden doppelte Nachrichten.

Bleiben Bestellungen lautlos ohne SMS, wenn das Guthaben aufgebraucht ist?

Ja. Ist das Guthaben aufgebraucht, lehnt Netgsm den Versand ab, aber in Shopify ändert sich nichts: Die Bestellung wird angelegt, die Sendung geht raus, und der Kunde bekommt einfach keine SMS. Fragen Sie das Guthaben nicht vor jedem Versand ab. Laut Netgsm ist die Guthabenabfrage auf 60 Anfragen pro Minute begrenzt, und die Antwort wird 10 Sekunden zwischengespeichert. Eine Prüfung, die einmal täglich abfragt und eine E-Mail-Warnung sendet, sobald das Guthaben unter das Dreifache des durchschnittlichen Verbrauchs der letzten 7 Tage fällt, genügt.

Prüfung der Webhook-Abonnements, Guthabenwarnung und Ergänzung der Berichte sind drei Aufgaben, die nach dem Livegang der Integration täglich laufen müssen. Wenn in Ihrem Team niemand diese Prüfungen verfolgt, überwacht unser Service für technischen Shopify-Support und Wartung sie und greift ein, bevor ein lautloser Ausfall zur Kundenbeschwerde wird.

Aus der Praxis: die 5 häufigsten Fehler in Netgsm-Integrationen

Bei Nodus Works wiederholen sich in den SMS-Integrationen, die wir für Shopify-Shops in der Türkei aufbauen und übernehmen, dieselben fünf Fehler. Keiner davon stammt aus der Netgsm-API selbst; alle entstehen in der Schicht, in der Shopify-Daten in eine SMS umgewandelt werden.

1. Versand-SMS ohne Tracking-Link

Markiert das Lagerteam die Bestellung zuerst als "versendet" und trägt die Sendungsnummer erst einige Stunden später ein, kommt der Webhook fulfillments/create mit leerem Tracking-Feld an. Sendet die Integration die SMS sofort, erhält der Kunde eine "versendet"-Nachricht ohne Link und fragt beim Kundenservice nach der Sendungsnummer. Die Lösung: Senden Sie die SMS, sobald das Feld tracking_number gefüllt ist. Ist das Feld leer, warten Sie auf das Ereignis fulfillments/update. Den Ablauf der Sendungsnummer zwischen Versanddienstleistern und Shopify haben wir in unserem Leitfaden zur Shopify-Versandintegration für jeden Dienstleister einzeln erklärt.

2. "Ihre Zahlung ist eingegangen" an einen Nachnahmekunden

Das im ersten Abschnitt beschriebene Problem mit orders/create ist der Template-Fehler, den wir in übernommenen Integrationen am häufigsten sehen. Eine Integration, die die Zahlungsart der Bestellung (payment_gateway_names) nicht prüft, schreibt dem Nachnahmekunden "Ihre Zahlung ist eingegangen". In Shops mit hohem Nachnahmeanteil kann diese Nachricht dazu führen, dass der Kunde das Paket an der Tür mit den Worten "Ich habe schon bezahlt" ablehnt.

3. Abgelehnte Nummern mit führender Null

Die Nummer eines Kunden, der 0532... in die Lieferadresse schreibt, geht ohne Formatierung als 0532... an Netgsm und wird abgelehnt. Dieser Fehler erscheint in den Logs als NO_DELIVERABLE_MESSAGES, bleibt aber unbemerkt, weil niemand die Logs liest. Die Formatierungsfunktion aus dem vorigen Abschnitt beseitigt diesen Fehler vollständig.

4. Konflikt zwischen Serverless-Umgebung und IP-Beschränkung

Der Integrationsentwickler aktiviert aus Sicherheitsgründen die IP-Beschränkung im Netgsm-Panel, sendet aber aus einer Serverless-Umgebung ohne feste IP. Die Tests laufen vom eigenen Rechner des Entwicklers durch, im Livebetrieb kommt jede Anfrage mit Code 30 zurück. Führen Sie den Test vor dem Livegang aus der Umgebung aus, in der die Integration tatsächlich laufen wird.

5. Kampagnennachricht über die Informations-Warteschlange

Wir haben Integrationen gesehen, die Warenkorb-Erinnerungen aus derselben Funktion wie Bestell-SMS und mit derselben Einstellung iysFilter: NONE senden. Dann erhalten auch Kunden ohne İYS-Einwilligung SMS mit Rabattcodes. Dieser Fehler hat kein technisches Symptom; der Versand sieht erfolgreich aus. Rechtlich gilt er jedoch als unerlaubte Werbenachricht. Trennen Sie Werbe- und Informationsversand in getrennte Warteschlangen mit getrennten Filtereinstellungen.

Häufig gestellte Fragen zur Shopify Netgsm SMS-Integration

Kann ich mit Netgsm auf Shopify kostenlos SMS senden?

Nein, jede über Netgsm gesendete SMS wird vom Paket in Ihrem Konto abgezogen. Die einzige kostenlose Umgebung ist die Sandbox von Netgsm (ext-sandbox.netgsm.com.tr); dort testen Sie den Token- und Versandablauf durchgängig, aber es geht keine echte SMS raus. Wenn Sie eine fertige App nutzen, rechnen Sie zusätzlich zum Netgsm-Paketpreis die monatliche Gebühr oder die Gebühr pro Nachricht der App ein.

Warum lässt sich die Shopify-App von Netgsm nicht installieren?

Mit Stand 13. November 2026 zeigt die Shopify-App-Store-Seite der App "Netgsm SMS", dass die App im Store nicht verfügbar ist, und verweist für Support an Netgsm. Sie haben drei Optionen: eine andere fertige App, die Netgsm unterstützt, Shopify Flow mit einem Zwischendienst oder eine individuelle App, die Webhooks empfängt. Fragen Sie Netgsm direkt, ob die App zurückkehrt.

Brauchen Bestell- und Versand-SMS eine İYS-Einwilligung?

Nein. Bestellbestätigungen, Versand- und Erstattungsnachrichten, die über den Status einer vom Kunden aufgegebenen Bestellung informieren, sind Informationsnachrichten und erfordern keine İYS-Einwilligung. Fügen Sie diesen Nachrichten jedoch einen Rabattcode, eine Kampagne oder eine Produktempfehlung hinzu, gilt die Nachricht als Werbung und braucht einen Einwilligungsdatensatz im İYS. Senden Sie diese Nachrichten bei Netgsm mit iysFilter: NONE.

Wie viele Zeichen hat eine SMS mit türkischen Zeichen?

In der Netgsm-Kodierung TURKISH umfasst eine einzelne SMS 155 Zeichen; bei Nachrichten, die in mehrere Teile zerlegt werden, trägt jeder Teil 148 Zeichen. In dieser Kodierung zählen die Buchstaben "ç, ğ, ı, ş, Ğ, İ, Ş" jeweils doppelt. Fügen Sie der Nachricht ein Emoji hinzu, wechselt die Kodierung zu UNICODE, und die Grenze für eine SMS fällt auf 70 Zeichen.

Lassen sich SMS zu abgebrochenen Warenkörben mit Netgsm senden?

Ja. Einzige Voraussetzung ist, dass die SMS-Einwilligung des Kunden im İYS erfasst ist. Der Trigger "Customer abandons checkout" von Shopify Flow sendet über einen Zwischendienst eine Anfrage an Netgsm. Der Versand erfolgt mit iysFilter: BRAND, und Netgsm entfernt Nummern ohne Einwilligung. Da die Erinnerung als Werbenachricht gilt, aktivieren Sie diesen Ablauf erst, wenn die İYS-Anbindung steht.

Was bedeutet der Netgsm-Fehlercode 30?

Code 30 zeigt an, dass Benutzername oder Passwort falsch sind oder dem API-Unterbenutzer die API-Zugriffsberechtigung fehlt. Haben Sie eine IP-Beschränkung aktiviert und kommt die Anfrage von außerhalb der erlaubten IP, erhalten Sie denselben Code. Bei Versand aus Serverless-Umgebungen (etwa Cloudflare Workers) erzeugt die IP-Beschränkung diesen Fehler, weil es keine feste IP gibt.

Wie verhindere ich, dass derselbe Kunde zwei SMS erhält?

Shopify sendet einen Webhook erneut, wenn innerhalb von 5 Sekunden keine Antwort kommt; Netgsm wiederum dedupliziert identische Anfragen nicht. Speichern Sie den Wert X-Shopify-Webhook-Id jedes Webhooks und überspringen Sie Wiederholungen. Bricht während einer Netgsm-Anfrage die Verbindung ab, senden Sie die SMS nicht erneut, sondern fragen Sie zuerst den Bericht ab.

Sollte ich für Bestellbenachrichtigungen WhatsApp oder SMS nutzen?

Nutzen Sie beide, mit getrennten Rollen. SMS erreicht jedes Telefon ohne Internetverbindung oder App; bei Nachrichten, die nicht verpasst werden dürfen, etwa Versand und Nachnahmebestätigung, liegt sie vorn. WhatsApp spielt seine Stärken bei Abläufen mit Bildern, Buttons und zweiseitigem Dialog aus. Die Möglichkeiten, einen WhatsApp-Kanal in Ihren Shop einzubinden, haben wir in unserem Leitfaden zum Shopify-WhatsApp-Plugin verglichen.

Fazit: In welcher Reihenfolge sollten Sie die SMS-Infrastruktur aufbauen?

Bauen Sie die Shopify Netgsm SMS-Integration nicht auf einmal auf, sondern nach Risiko geordnet. Die von uns empfohlene Reihenfolge:

1. Vorbereitung: Header-Antrag und API-Unterbenutzer am ersten Tag anlegen.
2. Informationsabläufe: Bestell-, Versand- und Stornierungs-SMS mit iysFilter: NONE live schalten.
3. Überwachung: Zustellbericht-Webhook, Guthabenwarnung und Prüfung der Webhook-Abonnements einrichten.
4. Werbeabläufe: Sobald die İYS-Einwilligungssynchronisierung läuft, Warenkorb-Erinnerungen und Kampagnen-SMS in einer eigenen Warteschlange aktivieren.

Diese Reihenfolge hält rechtlich riskante Werbenachrichten heraus, bis die Infrastruktur sich bewährt hat. Ein Fehler in den Informationsabläufen erzeugt schlimmstenfalls eine Kundenbeschwerde; ein Filterfehler im Werbeablauf gilt als unerlaubte Werbenachricht. Verbringen Sie die ersten zwei Wochen nur mit Informations-SMS und beobachten Sie die Rate fehlgeschlagener Zustellungen in den Berichten. Liegt sie unter 2 Prozent und gehen keine Beschwerden über doppelte SMS ein, ist die Infrastruktur bereit für Werbeabläufe.

Nutzt Ihr Shop Abläufe, die fertige Apps nicht sehen, etwa Nachnahme, ein ERP oder Versand aus mehreren Lagern, planen wir die Einrichtung gemeinsam über unseren Service für Shopify-Integrationen und individuelle App-Entwicklung; im ersten Gespräch erfassen wir Ihren aktuellen Ablauf und legen fest, welche SMS zuerst eingerichtet werden.

Wenn Sie SMS nicht nur für Benachrichtigungen, sondern auch für die Kundenanmeldung nutzen möchten, ist der nächste Schritt die Anmeldung per Einmalcode. Unser Leitfaden zum Shopify-SMS-OTP-Login behandelt die Anmeldung mit Telefonnummer in Kundenkonten zusammen mit einem Identitätsanbieter und einem KVKK-konformen Registrierungsformular. Die Netgsm-Operation sms.sendOtp kann in diesem Ablauf als SMS-Dienst für den Codeversand dienen.