Einen SMS-Absender über die API registrieren

Einige Länder stellen SMS nur von einem Absender zu, der für sie registriert ist. Über die API beanspruchen Sie den Absender, erstellen seine Registrierung für das Zielland und reichen die Unterlagen ein, die diese Registrierung verlangt. Das sind dieselben Schritte, die auch das Dashboard ausführt. Eine Registrierung kann direkt nach dem Erstellen eine Einrichtungsgebühr berechnen. Prüfen Sie deshalb zuerst den Preis und Ihr Wallet.

Voraussetzungen

• Ein API-Schlüssel mit sms_management auf Schreibebene, um Absender und Registrierungen zu erstellen, und mit compliance auf Schreibebene, um ihre Unterlagen einzureichen.
• Um Preise und Wallet-Guthaben vorab zu prüfen, ein delegiertes Benutzer-OAuth-Token, wie unter Registrierungspreise und Wallet-Guthaben prüfen beschrieben. Ein API-Schlüssel kann die Abrechnungsdaten der Organisation nicht lesen.

Die Beispiele lesen Ihren Schlüssel aus BIRD_API_KEY, seinen regionalen Host aus BIRD_API_URL, das Zielland aus COUNTRY_CODE und die scr_-Kennung der Registrierung aus REGISTRATION_ID, sobald Sie diese haben.

Registrierungspreise und Wallet-Guthaben prüfen

Um dieselben Preis- und Wallet-Informationen wie das Dashboard anzuzeigen, verwenden Sie GET /v1/organization/billing/prices/resolve und GET /v1/organization/billing/wallets. Diese Abfragen erfordern ein delegiertes Benutzer-OAuth-Token mit org:billing:read. Workspace-API-Schlüssel, Master-Schlüssel der Organisation und Service-Account-Tokens können diese Abrechnungsberechtigung der Organisation nicht gewähren.

Ermitteln Sie issuer, registration_endpoint, authorization_endpoint und token_endpoint über die OAuth-Protected-Resource-Discovery und die Metadaten des Autorisierungsservers, wie unter OAuth-Discovery beschrieben. Registrieren Sie am ermittelten registration_endpoint einen eigenen öffentlichen OAuth-Client und geben Sie dabei client_name, redirect_uris und token_endpoint_auth_method: "none" an. Leiten Sie den Benutzer an den ermittelten authorization_endpoint weiter, mit dieser client_id, response_type=code, Ihrer registrierten redirect_uri, einem neuen state, scope=org:billing:read, einer aus Ihrem Verifier abgeleiteten code_challenge und code_challenge_method=S256. Auf der Zustimmungsseite wählt der Benutzer einen Workspace in der gewünschten Organisation aus und gewährt org:billing:read, sofern seine Rolle dies erlaubt. Prüfen Sie state gegen den gesendeten Wert und iss gegen den Issuer aus der Discovery. Tauschen Sie dann den Code am ermittelten token_endpoint ein, mit grant_type=authorization_code, dem zurückgegebenen code, client_id, derselben redirect_uri und dem ursprünglichen code_verifier. Verwenden Sie das erhaltene Access-Token als BIRD_OAUTH_TOKEN. Beachten Sie seinen Wert expires_in. Speichern Sie das Refresh-Token sicher und ersetzen Sie es nach jeder erfolgreichen Aktualisierung. Führen Sie Aktualisierungen nacheinander aus, da jedes Refresh-Token nur einmal verwendet werden kann. Autorisieren Sie erneut, wenn die Refresh-Berechtigung abläuft oder widerrufen wird.

Das Token ist an den ausgewählten Workspace und dessen Organisation gebunden. Abrechnungsabfragen beziehen sich auf diese Organisation. X-Organization-Id kann es nicht auf eine andere Organisation umstellen. Wiederholen Sie dafür die Autorisierung für diese Organisation. Legen Sie den regionalen Host ausdrücklich fest, wenn Sie einen SDK mit diesem Token konfigurieren.

Ermitteln Sie für einen alphanumerischen SMS-Absender den Einrichtungspreis seiner Registrierung anhand des Ziellands:

curl --get "$BIRD_API_URL/v1/organization/billing/prices/resolve" \
  --header "Authorization: Bearer $BIRD_OAUTH_TOKEN" \
  --data-urlencode 'product_slug=sms_sender_registration' \
  --data-urlencode "dimensions[country_code]=$COUNTRY_CODE" \
  --data-urlencode 'dimensions[sender_type]=alphanumeric'

curl "$BIRD_API_URL/v1/organization/billing/wallets" \
  --header "Authorization: Bearer $BIRD_OAUTH_TOKEN"

Ermitteln Sie mit denselben Dimensionen product_slug=sms_sender, um den wiederkehrenden Preis zu erhalten. Für dieselbe Guthabenprüfung wie im Dashboard addieren Sie gross_price.amount aus der Antwort zum Einrichtungspreis und die erste wiederkehrende Gebühr, also gross_price.amount aus der Antwort zum wiederkehrenden Preis multipliziert mit deren intervals_per_charge. Vergleichen Sie diese Summe mit balance der Wallet in data, deren currency_code mit gross_price.currency_code beider Preise übereinstimmt. Rechnen Sie dezimal und runden Sie die zurückgegebenen Beträge nicht. Übersteigt die Summe das Guthaben, ist die Differenz der Fehlbetrag. Laden Sie dann Guthaben auf oder prüfen Sie die Kreditvereinbarung Ihrer Organisation, bevor Sie die Registrierung erstellen. Der Server berücksichtigt bei seiner abschließenden Prüfung der Zahlungsfähigkeit auch ein etwaiges Kreditlimit. Diese Abfragen zeigen die aktuellen Preise und Mittel. Sie reservieren keine Mittel und genehmigen keine Registrierung.

Die Registrierung abrufen, für die Sie Unterlagen einreichen

1. Suchen Sie den Absender mit GET /v1/sms/senders oder GET /v1/sms/senders/{sender_id}. Erstellen Sie bei Bedarf einen mit POST /v1/sms/senders.
2. Lesen Sie GET /v1/sms/senders/{sender_id}/requirements für das Ziel. Folgen Sie den dortigen Schritten unter next. Werden Sie aufgefordert, eine Registrierung zu erstellen, prüfen Sie deren Preis wie unter Registrierungspreise und Wallet-Guthaben prüfen beschrieben und rufen Sie dann POST /v1/sms/senders/{sender_id}/registrations mit country_code auf.
3. Lesen Sie die Absenderanforderungen erneut und übernehmen Sie registration_id (scr_) der Zeile als REGISTRATION_ID und ihr program als PROGRAM. Reichen Sie Unterlagen nur ein, wenn has_compliance_requirements der Zeile true ist. Ist der Wert false, braucht die Registrierung keine Einreichung oder ein eigenes Programm ist dafür zuständig. Folgen Sie dann stattdessen next der Zeile. Eigene Programme wie die Toll-free-Verifizierung und 10DLC haben ihre eigenen Schritte.

Zum Lesen von Absendern benötigen Sie sms_management:read, zum Erstellen von Absendern und Registrierungen sms_management:write. Zum Einreichen der zugehörigen Unterlagen benötigen Sie zusätzlich compliance:write.

Die Unterlagen der Registrierung einreichen

Dieser Abschnitt gilt für eine Registrierung, deren has_compliance_requirements true ist.

Lesen Sie mit GET /v1/compliance/requirements, was die Registrierung verlangt, mit sms_sender als subject_kind und der Registrierung als subject_id:

curl "$BIRD_API_URL/v1/compliance/requirements?subject_kind=sms_sender&subject_id=$REGISTRATION_ID&country_code=$COUNTRY_CODE&program=$PROGRAM" \
  --header "Authorization: Bearer $BIRD_API_KEY"

Die Felder sind so zu lesen wie bei einer Nummer. Lesen, was das Land verlangt erklärt jedes Feld, und Jedes Dokument hochladen behandelt die Dateien, die ein document-Feld verlangt. Reichen Sie jede Antwort mit POST /v1/compliance/submissions ein und geben Sie die Registrierung als Gegenstand an:

curl --request POST "$BIRD_API_URL/v1/compliance/submissions" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: sender-$REGISTRATION_ID" \
  --data '{
    "subject_kind": "sms_sender",
    "subject_id": "'"$REGISTRATION_ID"'",
    "program": "'"$PROGRAM"'",
    "country_code": "'"$COUNTRY_CODE"'",
    "answers": [{ "key": "legal_entity_name", "value": "Goldcrest Communications Inc" }]
  }'

Das Beispiel zeigt eine Antwort. Senden Sie einen Eintrag für jedes Feld, dessen required true ist, und für jedes optionale Feld, für das Sie eine echte Antwort haben, wie Jede Antwort einreichen erklärt. Eine 201-Antwort gibt die Einreichung zurück. Bewahren Sie deren csb_ id auf. Ein Absender hat kein Feld ownership. Verfolgen Sie die Prüfung daher, indem Sie die Einreichung mit GET /v1/compliance/submissions/{submission_id} lesen, deren Antworten ihren state und bei Ablehnung einen reason enthalten, oder indem Sie die Absenderanforderungen erneut lesen, um den Status der Registrierung zu sehen. Ersetzen Sie abgelehnte Antworten mit POST /v1/compliance/submissions/{submission_id}/resupply, wie Eine abgelehnte Antwort korrigieren zeigt.

Nächste Schritte

• Unterlagen zum Nachweis der Rufnummerninhaberschaft einreichen
• SMS-Absender-IDs