--- title: "Migreren van Telserv naar Bird" description: "Verplaats een Telserv-partner-API-integratie naar de Bird API, koppel elke bewerkingsgroep aan de bijbehorende Bird-aanroep en bekijk hoe elke taak in Bird wordt uitgevoerd." canonical: "https://bird.com/nl-nl/documentatie/guides/numbers/migrate/telserv" --- # 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](/docs/api/authentication) 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](/docs/guides/numbers/buying-numbers#when-an-order-is-refused) 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`](/docs/api/reference/list-workspace-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=`, 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](/docs/api/regions) 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 | Gebied | Telserv-partner-API | Bird API | | ---------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Authenticatie | `X-ApiKey`-header (V2) of `apiKey`-parameter (V1), gecontroleerd tegen je IP-allowlist | `Authorization: Bearer` met een API-key waarvan de scopes de productgebieden benoemen die hij mag gebruiken. Een IP-allowlist is optioneel: stel die in onder **IP restrictions** op de key in [**API-keys**](https://bird.com/dashboard/w/api-keys) | | Identifiers | Integers. Bij de aankoop van een nummer krijgt het een nieuwe `id` | TypeIDs met prefix zoals `nda_`, `nor_`, `vnu_` en `spt_`. Een nummer behoudt zijn `nda_`-id zolang het aan je is toegewezen | | Telefoonnummers | Cijfers zonder een voorloopteken `+` | E.164 met de voorloop-`+` | | Paginering | `start`- en `limit`-offsets, maximaal 1000 per pagina | Cursors: `limit` tot 100 (standaard 25), daarna `starting_after` ingesteld op de `next_cursor` van de vorige pagina. Zie [Paginering](/docs/api/pagination) | | Fouten | `errorCode` benoemt een uitzonderingsklasse, en `403` dekt zowel een ontbrekende resource als veel validatiefouten | `error.code` is een stabiele `E`-code met een documentatiepagina en, waar een herstelactie bekend is, een `remediation`. Een ontbrekende resource antwoordt met `404`, een niet-vervulde voorwaarde met `412`, en ongeldige invoer met `422` inclusief velddetails. Zie [Fouten](/docs/guides/errors) | | Omgevingen | LIVE en SANDBOX, elk met eigen keys | Eén omgeving. Elke bestelling koopt en factureert een echt nummer, en elk testgesprek is een echt gesprek | | Opnieuw proberen | Geen idempotentiesleutel | Een `Idempotency-Key`-header bij schrijfbewerkingen. Dezelfde sleutel en body spelen het eerste antwoord opnieuw af met `Idempotency-Replay: true`; dezelfde sleutel met een andere body geeft `409`. Zie [Idempotentie](/docs/guides/idempotency) | De Bird API weigert een queryparameter die het niet herkent met `422` en [`E01029`](/docs/api/errors/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`](/docs/api/reference/list-workspace-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`](/docs/api/reference/list-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](#routeer-een-nummer-naar-je-sip-trunk) toont het verzoek, en [Je telefoonnummers beheren](/docs/guides/numbers/managing-numbers#find-the-voice-record-that-routes-a-number) 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 | Taak | Telserv | Bird | | ------------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------- | | Nummers zoeken die te koop zijn | `GET /shop` | [`GET /v1/numbers/available`](/docs/api/reference/list-available-numbers) | | Eén nummer controleren | `GET /shop/{stockDnisId}` | [`GET /v1/numbers/available/{number}`](/docs/api/reference/get-available-number) | | Een nummer kopen | `POST /shop/{stockDnisId}` | [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order) | | Een nummer vastleggen | `POST /shop/{stockDnisId}/reserve`, `GET /shop/reserved` | [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order) | - **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](#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 | Taak | Telserv | Bird | | -------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Je nummers opvragen | `GET /numbers` | [`GET /v1/numbers`](/docs/api/reference/list-workspace-numbers) | | Eén nummer lezen | `GET /numbers/{dnisId}` | [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number) met de `nda_`- of `nal_`-id van de toewijzing, en [`GET /v1/voice/numbers/{number_id}`](/docs/api/reference/get-voice-number) met de `vnu_`-id van het spraakrecord | | Een nummer wijzigen | `PATCH /numbers/{dnisId}` | [`PATCH /v1/numbers/{number_id}`](/docs/api/reference/update-workspace-number) met de `nda_`- of `nal_`-id van de toewijzing, en [`PATCH /v1/voice/numbers/{number_id}`](/docs/api/reference/update-voice-number) met de `vnu_`-id van het spraakrecord | | Een nummer vrijgeven | `DELETE /numbers/{dnisId}?requestedCancelDate=` | [`DELETE /v1/numbers/{number_id}`](/docs/api/reference/cancel-workspace-number) aan het einde van de betaalde periode, of [`POST /v1/numbers/{number_id}/release`](/docs/api/reference/release-workspace-number) direct, beide met de `nda_`-id van de toewijzing | - **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`](/docs/api/reference/list-numbers-orders). [Je nummers afstemmen](#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](#een-nummer-vrijgeven) toont beide verzoeken. ### Bestemmingen en profielen | Taak | Telserv | Bird | | --------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Gesprekken naar SIP-apparatuur sturen | `POST /numbers/{dnisId}/destinations` | [`POST /v1/voice/trunks/{trunk_id}/gateways`](/docs/api/reference/create-voice-trunk-gateway), daarna `trunk` routeren | | Gesprekken doorsturen naar een telefoon | `POST /numbers/{dnisId}/destinations` | Routeer `forward` | | Geen oproepen meer aannemen | `DELETE /numbers/{dnisId}/destinations` | Routeer `reject` | | Bestemmingsprofielen lezen | `GET /destinationprofiles`, `GET /destinationprofiles/{id}` | [`GET /v1/voice/trunks`](/docs/api/reference/list-voice-trunks) en [`GET /v1/voice/trunks/{trunk_id}/gateways`](/docs/api/reference/list-voice-trunk-gateways) | | Een profiel op een nummer toepassen | `POST /numbers/{dnisId}/destinations/profile` | Routeer `trunk` met `trunk_id` | - **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](/docs/guides/voice/caller-ids) zijn; een niet-geverifieerd nummer geeft `412` met [`E21053`](/docs/api/errors/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 | Taak | Telserv | Bird | | ----------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Vereisten bekijken | `GET /products/conditions`, `GET /masterdata/productconditions` | [`GET /v1/compliance/requirements`](/docs/api/reference/get-workspace-compliance-requirements) voor het nummer, of met `program` en zonder `subject_id` voor het formulier dat een land vraagt voordat je een nummer hebt | | Een document uploaden | `POST /numbers/{dnisId}/documents` | [`POST /v1/compliance/attachments`](/docs/api/reference/create-compliance-attachment), en verwijs daarna in de inzending naar de bijlage. Zie [Het eigendomspapierwerk indienen](#het-eigendomspapierwerk-indienen) | | Eindgebruikersgegevens sturen | `POST /numbers/{dnisId}/enduserdata` | [`POST /v1/compliance/submissions`](/docs/api/reference/create-workspace-compliance-submission), samen met de documenten, in één verzoek. Zie [Het eigendomspapierwerk indienen](#het-eigendomspapierwerk-indienen) | | Een document vervangen | `POST /numbers/{dnisId}/documents` opnieuw | [`POST /v1/compliance/submissions/{submission_id}/resupply`](/docs/api/reference/update-workspace-compliance-submission) met de afgewezen of verlopen antwoorden | | Voortgang papierwerk bekijken | `GET /numbers/{dnisId}/documents` | `ownership` op [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number), en de indiening voor het oordeel over elk antwoord | - **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](/docs/guides/numbers/ownership-paperwork#upload-each-document) 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](/docs/guides/numbers/ownership-paperwork#submit-every-answer)). - **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](/docs/guides/numbers/ownership-paperwork#correct-a-rejected-answer)). - **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](#het-eigendomspapierwerk-indienen) toont de verzoeken, en [Het eigendomspapierwerk van een nummer indienen](/docs/guides/numbers/ownership-paperwork) behandelt de hele flow, inclusief indienen vanuit het dashboard en samen met de bestelling. ### Producten en stamgegevens | Taak | Telserv | Bird | | ------------------ | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Producten bekijken | `GET /products`, `GET /products/{productId}` | [`GET /v1/numbers/available`](/docs/api/reference/list-available-numbers), dat `country_code` vereist en de nummers teruggeeft die in dat ene land te koop zijn. Bird heeft geen wereldwijde productcatalogus, en niets komt overeen met `productId`. Geen enkele API geeft de landen en nummertypen weer die te koop zijn; de pagina met [telefoonnummerprijzen](/pricing/numbers) toont de standaardprijzen van Bird per land. | 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](/pricing/numbers). De `sessionPricing` per minuut van Telserv heeft geen equivalent bij deze reads; spraaktarieven staan op de pagina [spraakprijzen](/pricing/voice). Telserv-nummertypen komen als volgt overeen met `number_type` van Bird: | Telserv `numberType` | Bird `number_type` | | -------------------- | ------------------------------------------------- | | `DID` | `local` of `national`, afhankelijk van het nummer | | `FreePhone` | `toll_free` | | `Mobile` | `mobile` | ## 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: ```bash 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_period`s 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](/docs/api/reference/list-available-numbers) toont een voorbeeldresultaat. Een resultaat met `pricing.recurring_price: null` geeft geen terugkerende prijs op. [Neem contact op met sales](/contact-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`](/docs/api/errors/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: ```bash 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](/docs/guides/numbers/buying-numbers#poll-an-order-that-did-not-finish) 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](/docs/guides/numbers/buying-numbers#when-an-order-is-refused) 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}`](/docs/api/reference/get-workspace-number) 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](#het-eigendomspapierwerk-indienen). [De status van een toegewezen nummer](/docs/guides/numbers/overview#the-status-of-an-allocated-number) 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: ```bash 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`: ```bash 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`](/docs/api/errors/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`: ```bash 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`: ```bash 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](/docs/guides/numbers/ownership-paperwork#submit-every-answer) legt elke weigering uit. 5. Als een beoordelaar een antwoord afwijst, vervang je alleen dat antwoord, zoals [Een afgewezen antwoord corrigeren](/docs/guides/numbers/ownership-paperwork#correct-a-rejected-answer) beschrijft: ```bash 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}`](/docs/api/reference/get-workspace-number). 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](/docs/guides/numbers/ownership-paperwork) 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](/docs/guides/voice/receiving-calls#set-a-default-route) 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](/docs/guides/voice/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`: ```bash 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}`: ```bash 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](/docs/guides/voice/receiving-calls#what-a-gateway-needs) legt `priority` en de nummerformaten uit. Dezelfde gateway opnieuw aanmaken zonder idempotentiesleutel geeft `409` met [`E21047`](/docs/api/errors/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`: ```bash curl "$BIRD_API_URL/v1/voice/numbers?search=31612345678" \ --header "Authorization: Bearer $BIRD_API_KEY" ``` 4. Laat het nummer naar de trunk verwijzen: ```bash 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`](/docs/api/errors/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](/docs/guides/voice/receiving-calls#deliver-calls-to-a-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. ```bash 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: | Telserv-filter op `GET /numbers` | Bird-filter op `GET /v1/numbers` | | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `number`, dat overeenkomt met het begin van het nummer | `prefix` zonder `country_code`, dat overeenkomt met de cijfers vanaf het begin van het volledige nummer | | `prefix`, dat gelijk is aan het toegangs- en netnummer zoals `3170` | `country_code` met `prefix` ingesteld op de nationale cijfers: `country_code=NL&prefix=70` | | `reference` met een gedeeltelijke waarde | `search`, dat overeenkomt met een deel van het nummer, de naam of de referentie, hoofdletterongevoelig | | `reference` met een exacte waarde tussen aanhalingstekens | `reference`, dat de nummers met die exacte referentie retourneert. De overeenkomst is hoofdlettergevoelig | | Nieuw in Bird | `number` retourneert één volledig nummer opgegeven met de landcode, met of zonder `+` of `00`: `+31612345678`, `31612345678` en `0031612345678` vinden hetzelfde nummer | [Zoek een nummer in je lijst](/docs/guides/numbers/managing-numbers#find-a-number-in-your-list) 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](/docs/guides/numbers/managing-numbers#list-every-number-you-hold) 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`](/docs/api/reference/list-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`](/docs/api/errors/E14002). Om het nummer te behouden tot het einde van de periode waarvoor je al hebt betaald, annuleer je het: ```bash 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: ```bash 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`](/docs/api/errors/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](/docs/guides/numbers/managing-numbers#release-a-number) 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](/docs/guides/voice/destinations), 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](/docs/guides/voice/caller-ids) van je werkruimte, en het nummer dat je test in `to`: ```json { "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: ```bash 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}`](/docs/api/reference/get-voice-leg), of bekijk de legs die naar het nummer zijn geplaatst met [`GET /v1/voice/legs`](/docs/api/reference/list-voice-legs) en het `to`-filter, en controleer of je apparatuur de oproep heeft ontvangen. [Een spraakoproep aanmaken](/docs/guides/voice/create-calls) beschrijft de vereisten voor beller-ID en bestemming en de regels voor opnieuw proberen. ## Volgende stappen - [Een nummer kopen en vrijgeven](/docs/guides/numbers/buying-numbers) - [Je telefoonnummers beheren](/docs/guides/numbers/managing-numbers) - [Het eigendomspapierwerk van een nummer indienen](/docs/guides/numbers/ownership-paperwork) - [Oproepen ontvangen](/docs/guides/voice/receiving-calls) - [SIP-trunks](/docs/guides/voice/sip-trunks) - [Idempotentie](/docs/guides/idempotency) ## Related resources - [What is a virtual phone number (VMN)?](/explained/numbers/what-is-a-virtual-phone-number) (answer) - [SMS numbers](/sms-api/features/numbers) (product) - [Number types](/docs/guides/numbers/number-types) (docs) [Get an implementation brief](/learn/workspace?topic=phone-numbers)