Een SMS-afzender registreren via de API

Sommige landen leveren SMS alleen af van een afzender die voor dat land is geregistreerd. Via de API claim je de afzender, maak je er een registratie voor het bestemmingsland voor aan en dien je de documenten in die de registratie vraagt. Dat zijn dezelfde stappen die het dashboard uitvoert. Een registratie kan direct bij het aanmaken instapkosten in rekening brengen, dus controleer eerst de prijs en je wallet.

Voordat je begint

• Een API-sleutel met sms_management op schrijfniveau om afzenders en registraties aan te maken, en compliance op schrijfniveau om de bijbehorende documenten in te dienen.
• Om eerst prijzen en het tegoed in je wallet te controleren, heb je een gedelegeerd OAuth-token van een gebruiker nodig, zoals beschreven in Registratieprijzen en wallettegoed controleren. Een API-sleutel kan de facturatiegegevens van de organisatie niet lezen.

De voorbeelden lezen je sleutel uit BIRD_API_KEY, de bijbehorende regionale host uit BIRD_API_URL, het bestemmingsland uit COUNTRY_CODE en, zodra je die hebt, de scr_-identifier van de registratie uit REGISTRATION_ID.

Registratieprijzen en wallettegoed controleren

Gebruik GET /v1/organization/billing/prices/resolve en GET /v1/organization/billing/wallets om dezelfde prijs- en walletgegevens te tonen als het dashboard. Voor deze leesacties heb je een gedelegeerd OAuth-token van een gebruiker nodig met org:billing:read. API-sleutels van een werkruimte, hoofdsleutels van een organisatie en tokens van serviceaccounts kunnen deze facturatierechten voor de organisatie niet verlenen.

Gebruik OAuth-discovery van beschermde resources en metadata van de autorisatieserver om issuer, registration_endpoint, authorization_endpoint en token_endpoint op te halen, zoals beschreven in OAuth-discovery. Registreer je eigen openbare OAuth-client bij de gevonden registration_endpoint en geef daarbij client_name, redirect_uris en token_endpoint_auth_method: "none" op. Stuur de gebruiker naar de gevonden authorization_endpoint met die client_id, response_type=code, je geregistreerde redirect_uri, een nieuwe state, scope=org:billing:read, een code_challenge die is afgeleid van je verifier, en code_challenge_method=S256. Op het toestemmingsscherm kiest de gebruiker een werkruimte in de bedoelde organisatie en verleent org:billing:read als de rol van de gebruiker dat toestaat. Controleer state tegen de waarde die je hebt verzonden en iss tegen de issuer uit de discovery. Wissel daarna de code in bij de gevonden token_endpoint met grant_type=authorization_code, de teruggegeven code, client_id, dezelfde redirect_uri en de oorspronkelijke code_verifier. Gebruik het verkregen toegangstoken als BIRD_OAUTH_TOKEN. Houd je aan de expires_in ervan. Bewaar het refreshtoken veilig en vervang het na elke geslaagde vernieuwing. Voer vernieuwingen na elkaar uit, omdat elk refreshtoken maar één keer bruikbaar is. Autoriseer opnieuw als de refresh-grant verloopt of wordt ingetrokken.

Het token is gekoppeld aan de gekozen werkruimte en de bijbehorende organisatie. Facturatiegegevens worden voor die organisatie gelezen. Met X-Organization-Id kun je niet naar een andere organisatie overschakelen; doorloop de autorisatie opnieuw voor die organisatie. Stel de regionale host expliciet in wanneer je een SDK met dit token configureert.

Bepaal voor een alfanumerieke SMS-afzender de instelprijs van de registratie op basis van het land van bestemming:

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"

Bepaal product_slug=sms_sender met dezelfde dimensies voor de terugkerende prijs. Voor dezelfde saldocontrole als het dashboard tel je de gross_price.amount uit het antwoord voor de instelprijs op bij de eerste terugkerende kosten: de gross_price.amount uit het antwoord voor de terugkerende prijs, vermenigvuldigd met de bijbehorende intervals_per_charge. Vergelijk dat totaal met balance van de wallet in data waarvan de currency_code overeenkomt met de gross_price.currency_code van beide prijzen. Reken decimaal en rond de geretourneerde bedragen niet af. Is het totaal hoger dan het saldo, dan is het verschil het tekort. Waardeer in dat geval je wallet op of controleer de kredietafspraak van je organisatie voordat je de registratie aanmaakt. De server houdt bij de laatste controle of je de kosten kunt betalen ook rekening met een eventuele kredietlimiet. Deze leesacties tonen de actuele prijzen en middelen; ze reserveren geen geld en keuren geen registratie goed.

De registratie ophalen waarvoor je documenten indient

1. Zoek de afzender op met GET /v1/sms/senders of GET /v1/sms/senders/{sender_id}. Maak er zo nodig een aan met POST /v1/sms/senders.
2. Lees GET /v1/sms/senders/{sender_id}/requirements voor de bestemming. Volg de bijbehorende next-stappen. Vraagt het je een registratie aan te maken, controleer dan eerst de prijs zoals beschreven in Registratieprijzen en walletsaldo controleren en roep daarna POST /v1/sms/senders/{sender_id}/registrations aan met country_code.
3. Lees de afzendervereisten opnieuw en bewaar de registration_id (scr_) van de rij als REGISTRATION_ID en de program ervan als PROGRAM. Dien alleen documenten in als de has_compliance_requirements van de rij true is. Is die false, dan heeft de registratie geen indiening nodig of valt die onder een eigen programma; volg dan in plaats daarvan de next van de rij. Eigen programma's zoals toll-free-verificatie en 10DLC hebben hun eigen stappen.

Voor het lezen van afzenders heb je sms_management:read nodig; voor het aanmaken van afzenders en registraties sms_management:write. Voor het indienen van de bijbehorende documenten heb je ook compliance:write nodig.

De documenten van de registratie indienen

Deze sectie geldt voor een registratie waarvan de has_compliance_requirements true is.

Lees met GET /v1/compliance/requirements wat de registratie vraagt, met sms_sender als subject_kind en de registratie 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"

De velden werken net als bij een nummer. Lezen wat het land vraagt legt elk veld uit, en Elk document uploaden behandelt de bestanden waar een document-veld om vraagt. Dien elk antwoord in met POST /v1/compliance/submissions en geef de registratie op als onderwerp:

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

Het voorbeeld toont één antwoord. Stuur één item voor elk veld waarvan de required true is, en voor elk optioneel veld waarvoor je een echt antwoord hebt, zoals Elk antwoord indienen uitlegt. Een 201-antwoord retourneert de indiening; bewaar de csb_ id ervan. Een afzender heeft geen ownership-veld. Volg de beoordeling daarom door de indiening te lezen met GET /v1/compliance/submissions/{submission_id}, waarvan de antwoorden hun state bevatten en bij afwijzing een reason, of door de afzendervereisten opnieuw te lezen voor de status van de registratie. Vervang afgewezen antwoorden met POST /v1/compliance/submissions/{submission_id}/resupply, zoals Een afgewezen antwoord corrigeren laat zien.

Volgende stappen

• Dien de eigendomsdocumenten van een nummer in
• SMS-afzender-ID's