Migreren van Telserv naar Bird

Deze handleiding is voor integraties die de Telserv-partner-API aanroepen, V1 of V2, om nummers te kopen, te routeren en vrij te geven, en die nu overstappen naar de Bird API.

De Bird API bedient elk Bird-product, dus de nummers en spraakbewerkingen volgen de eigen conventies van Bird in plaats van die van Telserv. De meeste mogelijkheden die je integratie gebruikt, hebben een Bird-aanroep. De endpoints, payloads, identifiers en authenticatie verschillen, dus plan een herschrijving van de integratie. Waar Bird een taak anders uitvoert, laat deze handleiding zien hoe.

Deze handleiding is nog in ontwikkeling. Hij beschrijft wat Bird nu kan, en groeit mee met de migratie. Als een Telserv-bewerking die je gebruikt hier niet vermeld staat, moet die nog worden geëvalueerd en uitgewerkt voordat hij kan worden toegevoegd; vraag je migratiecontactpersoon ernaar.

Voordat je begint

• Een Bird-organisatie met voltooide identiteitsverificatie, die vereist is voor de eerste nummeraankoop.
• Een API-key met de scopes die de recepten gebruiken: numbers op schrijfniveau voor nummers en orders, compliance op schrijfniveau voor de losse bewerkingen voor eigendomspapierwerk, en voice_management op schrijfniveau voor SIP-trunks, spraaknummers en geverifieerde nummers. De testoproep heeft ook voice:write nodig, en het lezen van oproeplegs vereist voice:read.
• Walletsaldo. Orders worden betaald vanuit de wallet. Wanneer een order wordt geweigerd legt de 402- en 412-weigeringen uit.

De nummers die je integratie in Telserv beheert, hoeven niet opnieuw te worden gekocht. Zodra je nummers zijn verplaatst naar je Bird-werkruimte, verschijnen ze in GET /v1/numbers. Je migratiecontactpersoon bevestigt wanneer dat is gebeurd. Om de nda_-identifier van een verplaatst nummer op te halen, zoek je het op met GET /v1/numbers?number=<digits>, geef je de cijfers met hun landcode mee en bewaar je de id als NUMBER_ID.

De voorbeelden lezen je key uit BIRD_API_KEY en de bijbehorende regionale host uit BIRD_API_URL: https://eu1.platform.bird.com voor een bk_eu1_-key, of https://us1.platform.bird.com voor een bk_us1_-key. De overige variabelen, zoals TRUNK_ID en NUMBER_ID, bevatten een identifier uit een eerdere respons; elke stap vermeldt welke hij instelt.

Wat er verandert in het contract

De Bird API weigert een queryparameter die het niet herkent met 422 en E01029. Verwijder Telserv-specifieke filters zoals city uit je verzoeken in plaats van ze mee te sturen.

Twee identifiers voor één nummer

Een spraakgeschikt nummer dat aan je werkruimte is toegewezen heeft twee records, elk met een eigen identifier:

• De toewijzing, geretourneerd door GET /v1/numbers. De id begint met nda_ voor een dedicated nummer en met nal_ voor een gedeeld nummer, en de number_id van een bestelling is de nda_-identifier van het gekochte nummer. Gebruik deze om het nummer te lezen, te benoemen en te refereren, en om een dedicated nummer vrij te geven.
• Het spraakrecord, vnu_, geretourneerd door GET /v1/voice/numbers. Gebruik dit om te lezen en te wijzigen waar de inkomende oproepen van het nummer naartoe gaan. Een nummer zonder spraakmogelijkheid, zoals een SMS-only nummer, heeft geen spraakrecord.

De spraakbewerkingen weigeren een nda_- of nal_-identifier met 422. Om het spraakrecord van een nummer te vinden, lijst je spraaknummers op met search ingesteld op de cijfers van het nummer en neem je de vermelding waarvan provider.number_id overeenkomt met de id van de toewijzing. Een nummer routeren naar je SIP-trunk toont het verzoek, en Je telefoonnummers beheren behandelt het opzoeken.

Telserv's GET /numbers/{dnisId} wordt twee reads in Bird: de toewijzing voor status en eigendomspapierwerk, en het spraakrecord voor de route.

Telserv-bewerkingen koppelen aan Bird

Elke tabel vermeldt een taak, de Telserv-aanroep die het deed, en de Bird-aanroep die het nu doet. De opmerkingen onder elke tabel beschrijven wat er verandert in het verzoek of het antwoord.

Kopen

• Zoeken. country_code is verplicht, dus een zoekopdracht bestrijkt één land. prefix verwacht de nationale cijfers na de landcode: Telserv prefix=3170 wordt country_code=NL&prefix=70. Verfijn op netnummer met prefix in plaats van city, en op number_type en capabilities in plaats van productId.
• Eigendomspapierwerk in zoekresultaten. Elk resultaat bevat ownership_registration_required in plaats van het excludeNumbersRequireVerification-filter. Een waarde true betekent dat het nummer vanaf aankoop wordt gefactureerd, maar geen SMS verstuurt en geen inkomende of uitgaande spraakoproepen verwerkt totdat het papierwerk is goedgekeurd.
• Eén nummer controleren. Het wordt aangesproken op zijn E.164-nummer.
• Prijzen. Telserv gaf pricing.staticPricing terug bij de gedetailleerde reads van een nummer en van een product. In Bird bevat elk zoekresultaat de prijs voor je organisatie in pricing: setup_price in plaats van nrc, en recurring_price per recurring_period in plaats van mrc, met intervals_per_charge voor het aantal perioden dat één heffing dekt. Een nummer zoeken en kopen met je referentie beschrijft de prijsvelden.
• Kopen. Stuur number en een optionele reference. De bestelling wordt betaald vanuit je wallet. De meeste bestellingen antwoorden met 201; een bestelling die op een carrier wacht antwoordt met 202, en je pollt deze.
• Reserveren. Het bestellen van het nummer reserveert het. Controleer eerst een kandidaat en bestel het dan.

Nummers

• Lijst. De lijst bevat de nummers die nu aan je zijn toegewezen. Een vrijgegeven nummer dat je in Bird hebt besteld, blijft zichtbaar via de bestelling in GET /v1/numbers/orders. Je nummers afstemmen beschrijft de filters.
• Lezen. Status, eigendomspapierwerk en de prijs staan op de toewijzing, en de route staat op het spraakrecord. Het pricing-object van de toewijzing, met recurring_price per recurring_period en intervals_per_charge, vervangt pricing.staticPricing.mrc, en de lijst bevat het ook, waar Telserv's GET /numbers dat niet deed.
• Wijzigen. name en reference staan op de toewijzing, en de route staat op het spraakrecord. Stel een afgedwongen codec en een limiet op gelijktijdige gesprekken in op je SIP-apparatuur. destinationDistributionType wordt gateway priority op de SIP-trunk: FailOver geeft elke gateway een andere priority, en RoundRobin geeft ze dezelfde.
• Vrijgeven. DELETE houdt het nummer aan tot het einde van de periode waarvoor je al hebt betaald en geeft het dan vrij. POST …/release geeft het direct vrij. Geen van beide accepteert een datum. Een nummer vrijgeven toont beide verzoeken.

Bestemmingen en profielen

• SIP-apparatuur. Een gateway hoort bij de trunk en bedient elk nummer dat ernaartoe gerouteerd is, dus nummers die verschillende bestemmingslijsten nodig hebben, hebben verschillende trunks nodig. sortOrder wordt priority. Pas beltijd en tijdvensters toe op je SIP-apparatuur.
• Doorschakelen. Stel forward_to en forward_as in. forward_to moet een van je geverifieerde nummers zijn; een niet-geverifieerd nummer geeft 412 met E21053. forward_as bepaalt welk nummer het doorgeschakelde gesprek toont als beller. Een nummer heeft één route tegelijk, dus om terug te vallen van SIP-apparatuur naar een telefoonnummer schakel je het gesprek door vanaf je SIP-apparatuur.
• Geen oproepen meer aannemen. Het nummer weigert oproepen totdat je het opnieuw routeert. Om een vaste standaard te behouden in plaats van een standaardprofiel, routeer je het nummer naar een trunk die je standaardgateways bevat.
• Profielen. distributionType wordt priority: FailOver geeft elke gateway een andere priority, en RoundRobin geeft ze dezelfde. Distributie wordt per trunk ingesteld, dus nummers die een andere distributie nodig hebben, hebben andere trunks nodig. De {dnis}-placeholder wordt {number} in destination_format, en een prefixCLIP wordt de tekst vóór {number} in origination_format.
• Een profiel toepassen. Een trunk wordt aangesproken met zijn spt_-identifier, terwijl Telserv een profiel op naam aansprak.

Documenten en eindgebruikersgegevens

• Vereisten. De voorwaardencatalogus van Telserv besloeg alle producten tegelijk; Bird leest één formulier per keer. Vraag de vereisten van één nummer op met subject_kind=number, de nda_-identifier ervan als subject_id en de country_code ervan, of lees een formulier vóór de aankoop met program ingesteld op het nummertype en zonder subject_id. Elke vermelding in fields vervangt een Telserv-voorwaarde of eindgebruikerslabel: de key ervan is de sleutel waaronder je antwoordt, en data_type document markeert een vermelding die een bestand verwacht.
• Documenten. Upload het bestand als multipart/form-data in plaats van een base64-fileContent; Elk document uploaden vermeldt de geaccepteerde bestanden. Als je hetzelfde bestand twee keer uploadt, krijg je dezelfde bijlage terug. Een upload alleen dient niets in: dat doet de indiening die de attachment_id ervan vermeldt.
• Eindgebruikersgegevens en documenten samen. Telserv nam elk document in een eigen aanroep aan, en de eindgebruikersgegevens als één lijst labels in een andere. Bird neemt elk antwoord, getypt en document, in één indiening aan, en er zijn geen concepten: het verzoek dient de antwoorden in ter beoordeling. Volg daarna ownership.next, dat resupply noemt voor correcties en alleen een nieuwe indiening als die nodig is (Elk antwoord indienen).
• Vervangingen. Stuur alleen de antwoorden die je vervangt; de andere behouden hun beoordeling. Telserv accepteerde een nieuw bestand voor een voorwaarde zolang het nummer op verificatie wachtte, en dat bestand zette de beoordeling van die voorwaarde opnieuw in gang; Bird vervangt een antwoord dat is afgewezen, verlopen of nog niet aangeleverd, en weigert een antwoord dat nog wordt beoordeeld of al is geaccepteerd, behalve een antwoord gemarkeerd als editable_for_verifier_repair zolang een door ons gevraagde correctie openstaat (Een afgewezen antwoord corrigeren).
• Voortgang. ownership.status en ownership.next melden waar het nummer staat. Elk antwoord heeft een eigen state, en een afgewezen antwoord bevat de reason van de beoordelaar. Bird mailt elk resultaat ook naar de eigenaren van je organisatie en naar de persoon die de indiening het laatst heeft ingediend of gecorrigeerd. ownership is meestal null als het nummer geen papierwerk vereist.

Het eigendomspapierwerk indienen toont de verzoeken, en Het eigendomspapierwerk van een nummer indienen behandelt de hele flow, inclusief indienen vanuit het dashboard en samen met de bestelling.

Producten en stamgegevens

Elk zoekresultaat beschrijft het product met number_type, capabilities en ownership_registration_required, en bevat de prijs voor je organisatie in plaats van de pricing.staticPricing van het product (nrc en mrc). De standaardprijzen van Bird staan op de pagina telefoonnummerprijzen. De sessionPricing per minuut van Telserv heeft geen equivalent bij deze reads; spraaktarieven staan op de pagina spraakprijzen.

Telserv-nummertypen komen als volgt overeen met number_type van Bird:

Wat werkt er anders

Deze Telserv-taken werken anders in Bird. Houd er rekening mee voordat je een integratie verplaatst die van een van deze taken afhankelijk is.

• Papierwerk. Dien de documenten en eindgebruikersgegevens van een nummer in één inzending in, zonder concepten, en corrigeer afgewezen antwoorden met een nieuwe aanlevering.
• Reserveringen. Bestel het nummer zodra je het gekozen hebt; de bestelling reserveert het.
• Belinstellingen per nummer. Stel een afgedwongen codec, een limiet op gelijktijdige gesprekken, beltijd en tijdvensters in op je SIP-apparatuur.
• Een vrijgavedatum. Bird geeft een nummer vrij aan het einde van de betaalde periode of direct, niet op een datum die je kiest. Bewaar de annuleringsdatums die je naar Telserv stuurde aan jouw kant, en voer ze uit wanneer ze actueel worden.
• Walletsaldo. Controleer het saldo en vul het aan in het dashboard.

Een nummer zoeken en kopen met je referentie

Zoek in één land. Combineer number_type, capabilities en prefix om de resultaten te verfijnen:

curl "$BIRD_API_URL/v1/numbers/available?country_code=NL&number_type=mobile&capabilities=voice&limit=10" \
  --header "Authorization: Bearer $BIRD_API_KEY"

Elk resultaat bevat een pricing-object met de prijs die je organisatie voor het nummer betaalt, exclusief belasting en in je factureringsvaluta, met eventuele prijzen die je met Bird hebt afgesproken:

• setup_price wordt eenmalig in rekening gebracht wanneer je het nummer bestelt. Een gepubliceerd bedrag van nul heeft een amount van "0". Het veld zelf is null als er geen installatiekosten van toepassing zijn, en ook altijd wanneer recurring_price null is, omdat dat nummer niet kan worden besteld.
• recurring_price is het tarief per recurring_period.
• intervals_per_charge is het aantal recurring_periods dat één heffing dekt. De terugkerende kosten vóór belasting zijn recurring_price vermenigvuldigd met intervals_per_charge, afgeschreven wanneer het nummer aan je werkruimte wordt toegewezen en bij elke verlenging; de installatiekosten staan apart. Bij een bestelling die op een carrier wacht, vindt de toewijzing plaats wanneer de bestelling voltooid is.

De API-referentie toont een voorbeeldresultaat. Een resultaat met pricing.recurring_price: null geeft geen terugkerende prijs op. Neem contact op met sales om vóór het bestellen een prijs voor dat land en nummertype te laten vaststellen.

Het dashboard en API gebruiken dezelfde organisatieprijs, inclusief omrekening naar je factureringsvaluta. Een prijsopvraging legt geen offerte vast: tarief- of wisselkoerswijzigingen vóór een latere afschrijving kunnen het bedrag veranderen. Als de opvraging mislukt, geeft de zoekopdracht 503 terug met E14009. Probeer de opvraging opnieuw met exponentiële backoff; een mislukte opvraging betekent nooit dat het nummer niets kost.

Om een kandidaat en de prijs ervan te bevestigen voordat je bestelt, lees je het nummer op met GET /v1/numbers/available/{number}. Een 404 betekent dat het niet meer te koop is.

Bestel het nummer met de referentie die je in Telserv gebruikte, en kies een idempotentiesleutel die je bewaart voor als je deze aankoop opnieuw moet proberen:

curl --request POST "$BIRD_API_URL/v1/numbers/orders" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: order-CUST-778812" \
  --data '{"number": "+31612345678", "reference": "CUST-778812"}'

Een 201-antwoord bevat status: completed en een number_id, de nda_-identifier van het nummer. Bewaar deze als NUMBER_ID. Een 202-antwoord betekent dat de bestelling wacht op een carrier: poll de bestelling tot de status ervan completed of failed is. Een al afgeschreven installatiekost wordt niet terugbetaald als de bestelling daarna mislukt. De referentie wordt op het nummer gezet wanneer de bestelling voltooid is. Ze bevat maximaal 100 tekens en hoeft niet uniek te zijn.

Als je een bestelling opnieuw probeert voor een nummer dat al aan je werkruimte is toegewezen, krijg je de bestaande bestelling terug, dus een nieuwe poging brengt niet dubbel in rekening. Een nummer kopen en vrijgeven legt de weigeringen uit.

Om een referentie later in te stellen of te wijzigen, stuur je reference (en optioneel name) naar PATCH /v1/numbers/{number_id}. Stuur null om een veld te wissen.

Controleer of een nummer gesprekken kan voeren

Een nummer waarvan status de waarde pending_ownership_registration heeft, is toegewezen en wordt gefactureerd, maar het verstuurt geen SMS en weigert inkomende en uitgaande spraakoproepen totdat het eigendomspapierwerk is goedgekeurd. Lees het nummer op met GET /v1/numbers/{number_id} en controleer dat status gelijk is aan active voordat je het routeert of er een testoproep naartoe plaatst. Als het in behandeling is, dien je het eigendomspapierwerk in. De status van een toegewezen nummer licht elke waarde toe.

De voorbeelden hieronder gebruiken een Nederlands mobiel nummer. Controleer de status van je eigen nummer op dezelfde manier, ongeacht het land.

Het eigendomspapierwerk indienen

Telserv nam het papierwerk van een nummer aan met één POST /numbers/{dnisId}/documents per document en één POST /numbers/{dnisId}/enduserdata voor alle labels. Bird neemt beide aan in één inzending, nadat je de documenten hebt geüpload.

1. Lees de country_code van het nummer op en bewaar deze als COUNTRY_CODE. Het commando haalt deze eruit met jq; lees hem handmatig af als je jq niet gebruikt:

   Codevoorbeeld

   COUNTRY_CODE=$(curl -s "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \
     --header "Authorization: Bearer $BIRD_API_KEY" | jq -r .country_code)

2. Lees op wat het land van het nummer vraagt. Elke vermelding in fields heeft de key waaronder je antwoordt, een data_type en required, dat aangeeft of je de vermelding moet beantwoorden. Bewaar de program die het antwoord noemt als PROGRAM:

   Codevoorbeeld

   curl "$BIRD_API_URL/v1/compliance/requirements?subject_kind=number&subject_id=$NUMBER_ID&country_code=$COUNTRY_CODE" \
     --header "Authorization: Bearer $BIRD_API_KEY"

   Een 422 met E19001 betekent dat er voor dat land geen eigendomsformulier bestaat.

3. Upload elk document waar een document-veld om vraagt, als bestand in plaats van base64-fileContent. Bewaar de id uit het antwoord, de tca_-identifier van de bijlage, als ATTACHMENT_ID:

   Codevoorbeeld

   curl --request POST "$BIRD_API_URL/v1/compliance/attachments" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --form "file=@registration-certificate.pdf"

4. Dien alle antwoorden tegelijk in: één vermelding voor elk veld waarvan required true is, en voor elk optioneel veld waarvoor je een echt antwoord hebt, met de eindgebruikersgegevens als value en elk document als attachment_id. Laat een optioneel veld weg in plaats van er een waarde voor te verzinnen. Het voorbeeld toont twee antwoorden; voeg de overige verplichte antwoorden toe voordat je het verstuurt. Dit verzoek dient de antwoorden in ter beoordeling. Bewaar de id uit het antwoord, de csb_-identifier van de inzending, als SUBMISSION_ID:

   Codevoorbeeld

   curl --request POST "$BIRD_API_URL/v1/compliance/submissions" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --header "Idempotency-Key: ownership-CUST-778812" \
     --data '{"subject_kind": "number", "subject_id": "'"$NUMBER_ID"'", "program": "'"$PROGRAM"'", "country_code": "'"$COUNTRY_CODE"'", "answers": [{"key": "business_registration_number", "value": "90012768"}, {"key": "business_registration_certificate", "attachment_id": "'"$ATTACHMENT_ID"'"}]}'

   Een 201-antwoord geeft de inzending terug. Een 422 dient niets in: corrigeer de body en verstuur deze met een nieuwe idempotentiesleutel, omdat de oude sleutel de weigering opnieuw afspeelt. Alle antwoorden indienen legt elke weigering uit.

5. Als een beoordelaar een antwoord afwijst, vervang je alleen dat antwoord, zoals Een afgewezen antwoord corrigeren beschrijft:

   Codevoorbeeld

   curl --request POST "$BIRD_API_URL/v1/compliance/submissions/$SUBMISSION_ID/resupply" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --header "Idempotency-Key: ownership-fix-1-CUST-778812" \
     --data '{"answers": [{"key": "business_registration_number", "value": "90012769"}]}'

Om in te dienen terwijl je koopt, stuur je dezelfde answers in het compliance-blok van POST /v1/numbers/orders. Die bestelling gebruikt de bestaande numbers-scope op schrijfniveau, ook wanneer ze papierwerk bevat.

Volg de beoordeling met ownership.status op GET /v1/numbers/{number_id}. De antwoorden zijn een juridische verklaring namens je bedrijf, dus dien alleen antwoorden in die zijn bevestigd door iemand die er verantwoordelijk voor is. Het eigendomspapierwerk van een nummer indienen beschrijft elk verzoek, de beoordeling en het indienen bij de bestelling.

Routeer een nummer naar je SIP-trunk

Een nieuw nummer heeft geen eigen route en volgt dus de standaardroute van je werkruimte. Die standaardroute begint als reject, maar in een werkruimte die er al een heeft ingesteld, worden de oproepen naar een nieuw nummer volgens die route afgehandeld zodra het nummer is toegewezen. Om de oproepen bij je apparatuur af te leveren, maak je een SIP-trunk aan met inkomende oproepen ingeschakeld, geef je deze een gateway en laat je het nummer naar de trunk verwijzen. SIP-trunks behandelt het verbinden van je apparatuur met de trunk.

1. Maak de trunk aan met inkomende oproepen ingeschakeld. Bewaar de id uit het antwoord, de spt_-identifier van de trunk, als TRUNK_ID:

   Codevoorbeeld

   curl --request POST "$BIRD_API_URL/v1/voice/trunks" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --header "Idempotency-Key: trunk-production-pbx" \
     --data '{"name": "Production PBX", "inbound_enabled": true}'

2. Voeg een gateway toe. Standaard ontvangt de gateway de gekozen en bellende nummers in E.164 met hun +. Als je apparatuur nummers zonder de + verwacht, zoals de {dnis}-placeholder van Telserv deed, stel dan destination_format voor het gekozen nummer en origination_format voor het bellende nummer in op {number}:

   Codevoorbeeld

   curl --request POST "$BIRD_API_URL/v1/voice/trunks/$TRUNK_ID/gateways" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --header "Idempotency-Key: gateway-pbx-primary" \
     --data '{"sip_uri": "sip:pbx.example.com:5060", "priority": 0, "destination_format": "{number}", "origination_format": "{number}"}'

   Voeg voor failover een tweede gateway toe; Wat een gateway nodig heeft legt priority en de nummerformaten uit. Dezelfde gateway opnieuw aanmaken zonder idempotentiesleutel geeft 409 met E21047 als antwoord.

3. Zoek het spraakrecord van het nummer. Zoek op de cijfers van het nummer en neem de id van de vermelding waarvan provider.number_id de id van de toewijzing is. Bewaar deze als VOICE_NUMBER_ID:

   Codevoorbeeld

   curl "$BIRD_API_URL/v1/voice/numbers?search=31612345678" \
     --header "Authorization: Bearer $BIRD_API_KEY"

4. Laat het nummer naar de trunk verwijzen:

   Codevoorbeeld

   curl --request PATCH "$BIRD_API_URL/v1/voice/numbers/$VOICE_NUMBER_ID" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{"inbound_configuration": {"route": {"type": "trunk", "trunk_id": "'"$TRUNK_ID"'"}}}'

   Een 200-antwoord toont de nieuwe route. Een trunk met inkomende oproepen uitgeschakeld geeft 412 met E21052 als antwoord.

Als je inkomende oproepen op een trunk uitschakelt of de trunk verwijdert, keert elk nummer dat ernaar routeert terug naar de standaardroute van je werkruimte, en opnieuw inschakelen herstelt die routes niet. Oproepen afleveren op een SIP-trunk legt dit uit, samen met de trunk-, forward- en reject-routes.

Je nummers afstemmen

Doorloop de lijst met de grootste paginagrootte. Geef de next_cursor van elke pagina door als NEXT_CURSOR om de volgende pagina op te halen, totdat next_cursor gelijk is aan null. De lijst geeft geen totaalaantal terug.

curl "$BIRD_API_URL/v1/numbers?limit=100" \
  --header "Authorization: Bearer $BIRD_API_KEY"

curl "$BIRD_API_URL/v1/numbers?limit=100&starting_after=$NEXT_CURSOR" \
  --header "Authorization: Bearer $BIRD_API_KEY"

De lijstfilters van Telserv komen als volgt overeen met die van Bird:

Zoek een nummer in je lijst behandelt elk filter in detail.

Elke vermelding bevat pricing, met recurring_price per recurring_period en intervals_per_charge. Tenzij een prijs voor het nummer vaststaat, is recurring_price het huidige tarief van je organisatie, en elke verlenging brengt het tarief in rekening dat geldt op het moment van verlenging, dus een al gefactureerd bedrag kan ervan afwijken. Alle nummers in je bezit opvragen legt uit in welke valuta elk nummer wordt gefactureerd, wanneer pricing of de prijzen ervan null zijn, en wat je doet als pricing.error is ingesteld.

Een vrijgegeven nummer verdwijnt uit deze lijst, en opvragen op number_id geeft 404. Als je het in Bird hebt besteld, blijft de voltooide bestelling zichtbaar in GET /v1/numbers/orders.

Een nummer vrijgeven

Beide verzoeken gelden voor een dedicated nummer, op basis van zijn nda_-identifier; een gedeeld nummer wordt geweigerd met E14002. Om het nummer te behouden tot het einde van de periode waarvoor je al hebt betaald, annuleer je het:

curl --request DELETE "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Idempotency-Key: cancel-CUST-778812"

Een 202-antwoord geeft het nummer terug met releases_at, het einde van de betaalde periode. Het nummer behoudt zijn huidige status tot dat moment, het abonnement wordt niet verlengd en het nummer wordt dan vrijgegeven. Nogmaals opvragen geeft dezelfde releases_at, en een annulering kan niet ongedaan worden gemaakt. Een nummer zonder onderliggend abonnement wordt direct vrijgegeven, en het antwoord is 200 met status van het nummer ingesteld op released.

Om het nummer nu vrij te geven, ook als er al een annulering gepland is:

curl --request POST "$BIRD_API_URL/v1/numbers/$NUMBER_ID/release" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Idempotency-Key: release-CUST-778812"

Een 204-antwoord betekent dat het nummer is vrijgegeven, met onmiddellijke ingang. De rest van de huidige periode wordt niet terugbetaald.

Zolang een verlengingsbetaling voor het nummer achterstallig is, beantwoorden beide verzoeken 409 met E03015 totdat deze is voldaan.

Geen van beide verzoeken accepteert een datum, dus bewaar het schema dat je naar Telserv hebt gestuurd als requestedCancelDate aan je eigen kant. Om een nummer tot zijn datum te behouden, annuleer je het zodra de datum binnen de huidige factureringsperiode valt: het wordt vrijgegeven wanneer die periode eindigt, op of na de datum. Om het precies op de datum op te geven, geef je het die dag vrij. Een nummer vrijgeven beschrijft wat elk verzoek doet met het nummer, de kosten en een nieuwe poging.

Plaats een testoproep naar je nummer

Om een route end-to-end te controleren, plaats je een oproep naar het nummer vanaf een ander nummer dat je werkruimte als beller-ID mag presenteren. Het land van het nummer moet ingeschakeld zijn in je spraakbestemmingen, anders gaat de oproep niet door. Het onderstaande verzoek voert een inline-reeks uit die ophangt zodra de oproep wordt beantwoord, dus een opgeslagen reeks is niet nodig. Het plaatst een echte oproep, en de normale gesprekskosten zijn van toepassing.

Sla het verzoek op als test-call.json. Zet het beller-ID dat je presenteert in from, een eigen of geverifieerd nummer van je werkruimte, en het nummer dat je test in to:

{
  "from": "+31612345679",
  "to": "+31612345678",
  "sequence": {
    "definition": {
      "schema_version": 1,
      "expression_environment": "bird.cel.v1",
      "nodes": [
        {
          "id": "entry",
          "type": "trigger.start_call",
          "type_version": 1,
          "config": {},
          "input": {},
          "connections": { "event": { "node_id": "end", "port": "input" } }
        },
        { "id": "end", "type": "voice.hangup", "type_version": 1, "config": {}, "input": {} }
      ]
    },
    "entry_node_id": "entry",
    "trigger_data": {}
  }
}

Verstuur het:

curl --request POST "$BIRD_API_URL/v1/voice/calls" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: ${TEST_CALL_KEY:?Set TEST_CALL_KEY once for this test call}" \
  --data-binary @test-call.json

Stel TEST_CALL_KEY in op een nieuwe waarde voor elke test, en hergebruik het wanneer je dezelfde test opnieuw probeert na een time-out of een onduidelijk resultaat: dezelfde sleutel en hetzelfde verzoek binnen drie uur spelen de eerste acceptatie opnieuw af in plaats van een tweede oproep te plaatsen. Een 202-antwoord accepteert de oproep en retourneert het initial_leg_id. Acceptatie bewijst niet dat de oproep verbonden is: lees de leg met GET /v1/voice/legs/{leg_id}, of bekijk de legs die naar het nummer zijn geplaatst met GET /v1/voice/legs en het to-filter, en controleer of je apparatuur de oproep heeft ontvangen. Een spraakoproep aanmaken beschrijft de vereisten voor beller-ID en bestemming en de regels voor opnieuw proberen.

Volgende stappen

• Een nummer kopen en vrijgeven
• Je telefoonnummers beheren
• Het eigendomspapierwerk van een nummer indienen
• Oproepen ontvangen
• SIP-trunks
• Idempotentie