--- title: "Migration von Telserv zu Bird" description: "Migrieren Sie eine Telserv-Partner-API-Integration zur Bird API, ordnen Sie jede Operationsgruppe ihrem Bird-Aufruf zu und sehen Sie, wie jede Aufgabe in Bird erledigt wird." canonical: "https://bird.com/de-de/dokumentation/guides/numbers/migrate/telserv" --- # Migration von Telserv zu Bird Diese Anleitung richtet sich an Integrationen, die die Telserv-Partner-API (V1 oder V2) aufrufen, um Nummern zu kaufen, weiterzuleiten und freizugeben, und die jetzt zur Bird API wechseln. Die Bird API bedient jedes Bird-Produkt, daher folgen ihre Nummern- und Voice-Operationen den eigenen Konventionen von Bird statt denen von Telserv. Die meisten Funktionen, die Ihre Integration nutzt, haben einen Bird-Aufruf. Endpunkte, Payloads, Identifier und Authentifizierung unterscheiden sich, planen Sie also ein Neuschreiben der Integration. Wo Bird eine Aufgabe anders erledigt, zeigt diese Anleitung wie. Diese Anleitung wird laufend erweitert. Sie deckt ab, was Bird heute kann, und wächst mit der Migration. Falls eine Telserv-Operation, die Sie nutzen, hier nicht aufgeführt ist, muss sie erst bewertet und umgesetzt werden, bevor sie ergänzt werden kann; fragen Sie Ihren Migrationskontakt danach. ## Bevor Sie beginnen - Eine Bird-Organisation mit abgeschlossener Identitätsverifizierung, die für den ersten Nummernkauf erforderlich ist. - Ein [API-Schlüssel](/docs/api/authentication) mit den Scopes, die die Rezepte verwenden: `numbers` auf Schreibebene für Nummern und Bestellungen, `compliance` auf Schreibebene für die eigenständigen Operationen zur Eigentumsdokumentation und `voice_management` auf Schreibebene für SIP-Trunks, Voice-Nummern und verifizierte Nummern. Der Testanruf benötigt außerdem `voice:write`, und das Lesen von Call Legs erfordert `voice:read`. - Wallet-Guthaben. Bestellungen werden aus dem Wallet bezahlt. [Wenn eine Bestellung abgelehnt wird](/docs/guides/numbers/buying-numbers#when-an-order-is-refused) erläutert die `402`- und `412`-Ablehnungen. Die Nummern, die Ihre Integration in Telserv verwaltet, müssen nicht erneut gekauft werden. Sobald Ihre Nummern in Ihren Bird-Workspace verschoben wurden, erscheinen sie in [`GET /v1/numbers`](/docs/api/reference/list-workspace-numbers). Ihr Migrationskontakt bestätigt, wann das geschieht. Um den `nda_`-Identifier einer verschobenen Nummer zu erhalten, suchen Sie sie mit `GET /v1/numbers?number=`, geben Sie die Ziffern mit Ländervorwahl an und speichern Sie die `id` als `NUMBER_ID`. Die Beispiele lesen Ihren Schlüssel aus `BIRD_API_KEY` und seinen [regionalen Host](/docs/api/regions) aus `BIRD_API_URL`: `https://eu1.platform.bird.com` für einen `bk_eu1_`-Schlüssel oder `https://us1.platform.bird.com` für einen `bk_us1_`-Schlüssel. Die übrigen Variablen wie `TRUNK_ID` und `NUMBER_ID` enthalten einen Identifier aus einer früheren Antwort; jeder Schritt benennt den, den er setzt. ## Was sich am Vertrag ändert | Bereich | Telserv-Partner-API | Bird API | | ----------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Authentifizierung | `X-ApiKey`-Header (V2) oder `apiKey`-Parameter (V1), geprüft gegen Ihre IP-Allowlist | `Authorization: Bearer` mit einem API-Schlüssel, dessen Scopes die nutzbaren Produktbereiche benennen. Eine IP-Allowlist ist optional: Legen Sie sie unter **IP restrictions** auf dem Schlüssel in [**API keys**](https://bird.com/dashboard/w/api-keys) fest | | Bezeichner | Ganzzahlen. Beim Kauf erhält eine Nummer eine neue `id` | Präfixierte TypeIDs wie `nda_`, `nor_`, `vnu_` und `spt_`. Eine Nummer behält ihre `nda_`-ID, solange sie Ihnen zugewiesen ist | | Telefonnummern | Ziffern ohne führendes `+` | E.164 mit führendem `+` | | Paginierung | `start`- und `limit`-Offsets, bis zu 1000 pro Seite | Cursor: `limit` bis 100 (Standard 25), dann `starting_after` auf den `next_cursor`-Wert der vorherigen Seite setzen. Siehe [Paginierung](/docs/api/pagination) | | Fehler | `errorCode` benennt eine Exception-Klasse, und `403` deckt eine fehlende Ressource und viele Validierungsfehler ab | `error.code` ist ein stabiler `E`-Code mit einer Dokumentationsseite und, wenn eine Wiederherstellung bekannt ist, einem `remediation`. Eine fehlende Ressource antwortet mit `404`, eine nicht erfüllte Vorbedingung mit `412` und ungültige Eingabe mit `422` samt Felddetails. Siehe [Fehler](/docs/guides/errors) | | Umgebungen | LIVE und SANDBOX, jeweils mit eigenen Schlüsseln | Eine Umgebung. Jede Bestellung kauft und berechnet eine echte Nummer, und jeder Testanruf ist ein echter Anruf | | Wiederholungen | Kein Idempotenzschlüssel | Ein `Idempotency-Key`-Header bei Schreiboperationen. Derselbe Schlüssel und Body liefern die erste Antwort erneut mit `Idempotency-Replay: true`; derselbe Schlüssel mit einem anderen Body antwortet mit `409`. Siehe [Idempotenz](/docs/guides/idempotency) | Die Bird API lehnt einen nicht erkannten Query-Parameter mit `422` und [`E01029`](/docs/api/errors/E01029) ab. Entfernen Sie Telserv-spezifische Filter wie `city` aus Ihren Anfragen, anstatt sie weiterzugeben. ## Zwei Identifier für eine Nummer Eine sprachfähige Nummer, die Ihrem Workspace zugewiesen ist, hat zwei Datensätze mit jeweils eigenem Identifier: - Die Zuweisung, zurückgegeben von [`GET /v1/numbers`](/docs/api/reference/list-workspace-numbers). Ihr `id` beginnt bei einer dedizierten Nummer mit `nda_` und bei einer geteilten mit `nal_`, und die `number_id` einer Bestellung ist der `nda_`-Identifier der gekauften Nummer. Verwenden Sie sie, um die Nummer zu lesen, zu benennen und zu referenzieren und um eine dedizierte Nummer freizugeben. - Der Voice-Datensatz, `vnu_`, zurückgegeben von [`GET /v1/voice/numbers`](/docs/api/reference/list-voice-numbers). Verwenden Sie ihn, um zu lesen und zu ändern, wohin die eingehenden Anrufe der Nummer geleitet werden. Eine Nummer ohne Sprachfähigkeit, z. B. eine reine SMS-Nummer, hat keinen Voice-Datensatz. Die Voice-Operationen lehnen einen `nda_`- oder `nal_`-Identifier mit `422` ab. Um den Voice-Datensatz einer Nummer zu finden, listen Sie Voice-Nummern mit `search` auf, gesetzt auf die Ziffern der Nummer, und nehmen Sie den Eintrag, dessen `provider.number_id` der `id` der Zuweisung entspricht. [Eine Nummer zu Ihrem SIP-Trunk routen](#eine-nummer-zu-ihrem-sip-trunk-routen) zeigt die Anfrage, und [Ihre Telefonnummern verwalten](/docs/guides/numbers/managing-numbers#find-the-voice-record-that-routes-a-number) behandelt die Suche. Telservs `GET /numbers/{dnisId}` wird in Bird zu zwei Leseoperationen: die Zuweisung für Status und Eigentumsdokumentation und der Voice-Datensatz für die Route. ## Telserv-Operationen auf Bird abbilden Jede Tabelle listet eine Aufgabe, den Telserv-Aufruf, der sie ausführte, und den Bird-Aufruf, der sie jetzt ausführt. Die Anmerkungen unter jeder Tabelle beschreiben, was sich in der Anfrage oder Antwort ändert. ### Einkauf | Aufgabe | Telserv | Bird | | ----------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------- | | Nummern zum Kauf suchen | `GET /shop` | [`GET /v1/numbers/available`](/docs/api/reference/list-available-numbers) | | Eine Nummer prüfen | `GET /shop/{stockDnisId}` | [`GET /v1/numbers/available/{number}`](/docs/api/reference/get-available-number) | | Eine Nummer kaufen | `POST /shop/{stockDnisId}` | [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order) | | Eine Nummer sichern | `POST /shop/{stockDnisId}/reserve`, `GET /shop/reserved` | [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order) | - **Suche.** `country_code` ist erforderlich, eine Suche deckt also ein Land ab. `prefix` nimmt die nationalen Ziffern nach der Landesvorwahl entgegen: Telserv `prefix=3170` wird zu `country_code=NL&prefix=70`. Grenzen Sie nach Vorwahl mit `prefix` anstelle von `city` ein sowie nach `number_type` und `capabilities` anstelle von `productId`. - **Unterlagen in Suchergebnissen.** Jedes Ergebnis enthält `ownership_registration_required` anstelle des `excludeNumbersRequireVerification`-Filters. Ein Wert `true` bedeutet, dass die Nummer ab dem Kauf abgerechnet wird, aber keine SMS sendet und keine ein- oder ausgehenden Sprachanrufe überträgt, bis ihre Unterlagen genehmigt sind. - **Eine Nummer prüfen.** Sie wird über ihre E.164-Nummer adressiert. - **Preise.** Telserv gab `pricing.staticPricing` bei den detaillierten Abfragen einer Nummer und eines Produkts zurück. In Bird enthält jedes Suchergebnis den Preis für Ihre Organisation in `pricing`: `setup_price` anstelle von `nrc` und `recurring_price` pro `recurring_period` anstelle von `mrc`, mit `intervals_per_charge` für die Anzahl der Perioden, die eine Gebühr abdeckt. [Eine Nummer mit Ihrer Referenz suchen und kaufen](#eine-nummer-mit-ihrer-referenz-suchen-und-kaufen) beschreibt die Preisfelder. - **Kaufen.** Senden Sie `number` und eine optionale `reference`. Die Bestellung wird aus Ihrem Wallet bezahlt. Die meisten Bestellungen antworten mit `201`; eine Bestellung, die auf einen Carrier wartet, antwortet mit `202`, und Sie fragen den Status ab. - **Sichern.** Die Bestellung der Nummer sichert sie. Prüfen Sie einen Kandidaten zuerst und bestellen Sie ihn dann. ### Nummern | Aufgabe | Telserv | Bird | | ---------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Ihre Nummern auflisten | `GET /numbers` | [`GET /v1/numbers`](/docs/api/reference/list-workspace-numbers) | | Eine Nummer lesen | `GET /numbers/{dnisId}` | [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number) mit der `nda_`- oder `nal_`-ID der Zuweisung und [`GET /v1/voice/numbers/{number_id}`](/docs/api/reference/get-voice-number) mit der `vnu_`-ID des Voice-Datensatzes | | Eine Nummer ändern | `PATCH /numbers/{dnisId}` | [`PATCH /v1/numbers/{number_id}`](/docs/api/reference/update-workspace-number) mit der `nda_`- oder `nal_`-ID der Zuweisung und [`PATCH /v1/voice/numbers/{number_id}`](/docs/api/reference/update-voice-number) mit der `vnu_`-ID des Voice-Datensatzes | | Eine Nummer freigeben | `DELETE /numbers/{dnisId}?requestedCancelDate=` | [`DELETE /v1/numbers/{number_id}`](/docs/api/reference/cancel-workspace-number) am Ende des bezahlten Zeitraums oder [`POST /v1/numbers/{number_id}/release`](/docs/api/reference/release-workspace-number) sofort, beide mit der `nda_`-ID der Zuweisung | - **Auflisten.** Die Liste enthält die Ihnen aktuell zugewiesenen Nummern. Eine freigegebene Nummer, die Sie in Bird bestellt haben, bleibt über ihre Bestellung in [`GET /v1/numbers/orders`](/docs/api/reference/list-numbers-orders) sichtbar. [Ihre Nummern abgleichen](#ihre-nummern-abgleichen) ordnet die Filter zu. - **Lesen.** Status, Eigentumsdokumentation und Preis stehen auf der Zuweisung, die Route auf dem Voice-Datensatz. Das `pricing`-Objekt der Zuweisung mit `recurring_price` pro `recurring_period` und `intervals_per_charge` ersetzt `pricing.staticPricing.mrc`, und die Liste enthält es ebenfalls, wo Telservs `GET /numbers` das nicht tat. - **Ändern.** `name` und `reference` stehen auf der Zuweisung, die Route auf dem Voice-Datensatz. Legen Sie einen erzwungenen Codec und eine Obergrenze für gleichzeitige Anrufe auf Ihrem SIP-Equipment fest. `destinationDistributionType` wird zu Gateway `priority` auf dem SIP-Trunk: `FailOver` gibt jedem Gateway einen anderen `priority`, und `RoundRobin` gibt ihnen denselben. - **Freigeben.** `DELETE` behält die Nummer bis zum Ende des bereits bezahlten Zeitraums und gibt sie dann frei. `POST …/release` gibt sie sofort frei. Keiner der beiden Aufrufe akzeptiert ein Datum. [Eine Nummer freigeben](#eine-nummer-freigeben) zeigt beide Anfragen. ### Ziele und Profile | Aufgabe | Telserv | Bird | | ---------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Anrufe an SIP-Equipment senden | `POST /numbers/{dnisId}/destinations` | [`POST /v1/voice/trunks/{trunk_id}/gateways`](/docs/api/reference/create-voice-trunk-gateway), dann `trunk` routen | | Anrufe an ein Telefon weiterleiten | `POST /numbers/{dnisId}/destinations` | `forward` routen | | Keine Anrufe mehr annehmen | `DELETE /numbers/{dnisId}/destinations` | `reject` routen | | Zielprofile lesen | `GET /destinationprofiles`, `GET /destinationprofiles/{id}` | [`GET /v1/voice/trunks`](/docs/api/reference/list-voice-trunks) und [`GET /v1/voice/trunks/{trunk_id}/gateways`](/docs/api/reference/list-voice-trunk-gateways) | | Profil auf eine Nummer anwenden | `POST /numbers/{dnisId}/destinations/profile` | `trunk` mit `trunk_id` routen | - **SIP-Equipment.** Ein Gateway gehört zum Trunk und bedient jede darauf geroutete Nummer. Nummern, die unterschiedliche Ziellisten brauchen, brauchen daher unterschiedliche Trunks. `sortOrder` wird zu `priority`. Klingelzeit und Zeitfenster legen Sie auf Ihrem SIP-Equipment fest. - **Weiterleitung.** Setzen Sie `forward_to` und `forward_as`. `forward_to` muss eine Ihrer [verifizierten Nummern](/docs/guides/voice/caller-ids) sein; eine nicht verifizierte Nummer antwortet mit `412` und [`E21053`](/docs/api/errors/E21053). `forward_as` bestimmt, welche Nummer der weitergeleitete Anruf als Anrufer anzeigt. Eine Nummer hat jeweils nur eine Route. Um von SIP-Equipment auf eine Telefonnummer zurückzufallen, leiten Sie den Anruf von Ihrem SIP-Equipment weiter. - **Anrufe nicht mehr annehmen.** Die Nummer lehnt Anrufe ab, bis Sie sie erneut routen. Um einen festen Standard anstelle eines Standardprofils beizubehalten, routen Sie die Nummer zu einem Trunk, der Ihre Standard-Gateways enthält. - **Profile.** `distributionType` wird zu `priority`: `FailOver` gibt jedem Gateway eine andere `priority`, und `RoundRobin` gibt ihnen dieselbe. Die Verteilung wird pro Trunk festgelegt, daher benötigen Nummern mit unterschiedlicher Verteilung unterschiedliche Trunks. Der Platzhalter `{dnis}` wird zu `{number}` in `destination_format`, und ein `prefixCLIP` wird zum Text vor `{number}` in `origination_format`. - **Profil anwenden.** Ein Trunk wird über seinen `spt_`-Identifier adressiert, während Telserv ein Profil über seinen Namen adressierte. ### Dokumente und Endnutzerdaten | Aufgabe | Telserv | Bird | | --------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Anforderungen lesen | `GET /products/conditions`, `GET /masterdata/productconditions` | [`GET /v1/compliance/requirements`](/docs/api/reference/get-workspace-compliance-requirements) für die Nummer, oder mit `program` und ohne `subject_id` für das Formular, das ein Land verlangt, bevor Sie eine Nummer besitzen | | Ein Dokument hochladen | `POST /numbers/{dnisId}/documents` | [`POST /v1/compliance/attachments`](/docs/api/reference/create-compliance-attachment), dann den Anhang in der Einreichung angeben. Siehe [Die Eigentumsdokumentation einreichen](#eigentumsunterlagen-einreichen) | | Endnutzerdaten senden | `POST /numbers/{dnisId}/enduserdata` | [`POST /v1/compliance/submissions`](/docs/api/reference/create-workspace-compliance-submission), zusammen mit den Dokumenten, in einer Anfrage. Siehe [Eigentumsunterlagen einreichen](#eigentumsunterlagen-einreichen) | | Ein Dokument ersetzen | `POST /numbers/{dnisId}/documents` erneut | [`POST /v1/compliance/submissions/{submission_id}/resupply`](/docs/api/reference/update-workspace-compliance-submission) mit den abgelehnten oder abgelaufenen Antworten | | Fortschritt der Unterlagen prüfen | `GET /numbers/{dnisId}/documents` | `ownership` auf [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number) und die Einreichung für das Prüfergebnis jeder Antwort | - **Anforderungen.** Telservs Bedingungskatalog deckte alle Produkte auf einmal ab; Bird liest jeweils ein Formular. Fragen Sie die Anforderungen einer Nummer mit `subject_kind=number` ab, mit ihrem `nda_`-Identifier als `subject_id` und ihrem `country_code`, oder lesen Sie ein Formular vor dem Kauf, indem Sie `program` auf den Nummerntyp setzen und kein `subject_id` angeben. Jeder Eintrag in `fields` ersetzt eine Telserv-Bedingung oder ein Endnutzer-Label: Unter seinem `key` geben Sie Ihre Antwort, und `data_type` `document` kennzeichnet einen Eintrag, der eine Datei erwartet. - **Dokumente.** Laden Sie die Datei als `multipart/form-data` hoch statt als Base64-`fileContent`; [Jedes Dokument hochladen](/docs/guides/numbers/ownership-paperwork#upload-each-document) listet die akzeptierten Dateien auf. Wenn Sie dieselbe Datei zweimal hochladen, erhalten Sie denselben Anhang. Ein Upload allein reicht nichts ein: Das erledigt die Einreichung, die seine `attachment_id` angibt. - **Endnutzerdaten und Dokumente zusammen.** Telserv nahm jedes Dokument in einem eigenen Aufruf entgegen und die Endnutzerdaten als Label-Liste in einem weiteren. Bird nimmt alle Antworten, Textangaben und Dokumente, in einer Einreichung entgegen, und es gibt keine Entwürfe: Die Anfrage reicht die Antworten zur Prüfung ein. Verfolgen Sie danach `ownership.next`. Das Feld nennt eine Nachlieferung für Korrekturen und eine neue Einreichung nur dann, wenn eine nötig ist ([Alle Antworten einreichen](/docs/guides/numbers/ownership-paperwork#submit-every-answer)). - **Ersetzungen.** Senden Sie nur die Antworten, die Sie ersetzen; die übrigen behalten ihren Prüfstand. Telserv nahm eine neue Datei für eine Bedingung an, solange die Verifizierung der Nummer ausstand, und die Datei setzte die Prüfung dieser Bedingung zurück. Bird ersetzt eine Antwort, die abgelehnt, abgelaufen oder noch nicht geliefert ist. Eine Antwort, die noch geprüft wird oder bereits akzeptiert ist, lehnt es ab, außer eine als `editable_for_verifier_repair` markierte Antwort, während eine von uns angeforderte Korrektur offen ist ([Abgelehnte Antwort korrigieren](/docs/guides/numbers/ownership-paperwork#correct-a-rejected-answer)). - **Fortschritt.** `ownership.status` und `ownership.next` zeigen den Stand der Nummer. Jede Antwort hat ihren eigenen `state`, und eine abgelehnte enthält den `reason` der prüfenden Person. Bird sendet jedes Ergebnis außerdem per E-Mail an die Inhaber Ihrer Organisation und an die Person, die die Einreichung zuletzt eingereicht oder korrigiert hat. `ownership` ist in der Regel `null`, wenn die Nummer keine Unterlagen benötigt. [Eigentumsunterlagen einreichen](#eigentumsunterlagen-einreichen) zeigt die Anfragen, und [Eigentumsunterlagen einer Nummer einreichen](/docs/guides/numbers/ownership-paperwork) beschreibt den gesamten Ablauf, einschließlich der Einreichung über das Dashboard und mit der Bestellung. ### Produkte und Stammdaten | Aufgabe | Telserv | Bird | | -------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Produkte durchsuchen | `GET /products`, `GET /products/{productId}` | [`GET /v1/numbers/available`](/docs/api/reference/list-available-numbers), das `country_code` erfordert und die in diesem einen Land angebotenen Nummern zurückgibt. Bird hat keinen globalen Produktkatalog, und nichts entspricht `productId`. Keine API listet die angebotenen Länder und Nummerntypen auf; die Seite [Telefonnummern-Preise](/pricing/numbers) listet die Standardpreise von Bird nach Land. | Jedes Suchergebnis beschreibt sein Produkt mit `number_type`, `capabilities` und `ownership_registration_required` und enthält den Preis für Ihre Organisation anstelle des `pricing.staticPricing` des Produkts (`nrc` und `mrc`). Die Standardpreise von Bird finden Sie auf der Seite [Telefonnummern-Preise](/pricing/numbers). Telservs minutenbasierter `sessionPricing` hat bei diesen Abfragen kein Gegenstück; Sprachtarife finden Sie auf der Seite [Sprach-Preise](/pricing/voice). Telserv-Nummerntypen werden wie folgt auf `number_type` von Bird abgebildet: | Telserv `numberType` | Bird `number_type` | | -------------------- | --------------------------------------- | | `DID` | `local` oder `national`, je nach Nummer | | `FreePhone` | `toll_free` | | `Mobile` | `mobile` | ## Was anders funktioniert Diese Telserv-Aufgaben funktionieren in Bird anders. Planen Sie dafür, bevor Sie eine Integration umstellen, die auf eine davon angewiesen ist. - **Unterlagen.** Reichen Sie die Dokumente und Endnutzerdaten einer Nummer in einer einzigen Übermittlung ohne Entwürfe ein, und korrigieren Sie abgelehnte Antworten per Nachreichung. - **Reservierungen.** Bestellen Sie die Nummer, sobald Sie sich entschieden haben; die Bestellung sichert sie. - **Anrufeinstellungen pro Nummer.** Wenden Sie einen erzwungenen Codec, eine Obergrenze für gleichzeitige Anrufe, Klingelzeit und Zeitfenster auf Ihrem SIP-Equipment an. - **Ein Freigabedatum.** Bird gibt eine Nummer am Ende des bezahlten Zeitraums oder sofort frei, nicht zu einem von Ihnen gewählten Datum. Behalten Sie die Kündigungsdaten, die Sie an Telserv gesendet haben, auf Ihrer Seite und handeln Sie bei jedem einzelnen, wenn es fällig wird. - **Wallet-Guthaben.** Prüfen Sie das Guthaben und laden Sie es im Dashboard auf. ## Eine Nummer mit Ihrer Referenz suchen und kaufen Durchsuchen Sie ein Land. Kombinieren Sie `number_type`, `capabilities` und `prefix`, um die Ergebnisse einzugrenzen: ```bash curl "$BIRD_API_URL/v1/numbers/available?country_code=NL&number_type=mobile&capabilities=voice&limit=10" \ --header "Authorization: Bearer $BIRD_API_KEY" ``` Jedes Ergebnis enthält ein `pricing`-Objekt mit dem Preis, den Ihre Organisation für die Nummer zahlt, netto ohne Steuern und in Ihrer Abrechnungswährung, mit allen mit Bird vereinbarten Preisen: - `setup_price` wird einmalig bei der Bestellung der Nummer berechnet. Eine veröffentlichte Gebühr von null hat einen `amount` von `"0"`. Das Feld selbst ist `null`, wenn keine Einrichtungsgebühr anfällt, und ebenso immer dann, wenn `recurring_price` den Wert `null` hat, weil diese Nummer nicht bestellt werden kann. - `recurring_price` ist der Tarif pro `recurring_period`. - `intervals_per_charge` gibt an, wie viele `recurring_period` eine Abrechnung umfasst. Die wiederkehrende Gebühr vor Steuern ergibt sich aus `recurring_price` multipliziert mit `intervals_per_charge` und wird abgebucht, wenn die Nummer Ihrem Workspace zugewiesen wird, sowie bei jeder Verlängerung; die Einrichtungsgebühr ist separat. Bei einer Bestellung, die auf einen Carrier wartet, erfolgt die Zuweisung, sobald die Bestellung abgeschlossen ist. Die [API-Referenz](/docs/api/reference/list-available-numbers) zeigt ein Beispielergebnis. Ein Ergebnis mit `pricing.recurring_price: null` nennt keinen wiederkehrenden Preis. [Vertrieb kontaktieren](/contact-sales), um vor der Bestellung einen Preis für dieses Land und diesen Nummerntyp zu erhalten. Das Dashboard und API verwenden denselben Organisationspreis, einschließlich der Umrechnung in Ihre Abrechnungswährung. Ein Preisabruf sperrt kein Angebot: Tarif- oder Wechselkursänderungen vor einer späteren Belastung können deren Betrag ändern. Schlägt die Abfrage fehl, gibt die Suche `503` mit [`E14009`](/docs/api/errors/E14009) zurück. Versuchen Sie den Abruf mit exponentiellem Backoff erneut; ein Abfragefehler bedeutet nie, dass die Nummer nichts kostet. Um einen Kandidaten und seinen Preis vor der Bestellung zu prüfen, lesen Sie ihn mit `GET /v1/numbers/available/{number}`. Ein `404` bedeutet, dass die Nummer nicht mehr zum Verkauf steht. Bestellen Sie die Nummer mit der Referenz, die Sie in Telserv verwendet haben, und wählen Sie einen Idempotenzschlüssel, den Sie für jeden erneuten Versuch dieses Kaufs aufbewahren: ```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"}' ``` Eine `201`-Antwort enthält `status: completed` und eine `number_id`, den `nda_`-Bezeichner der Nummer. Speichern Sie ihn als `NUMBER_ID`. Eine `202`-Antwort bedeutet, dass die Bestellung auf einen Carrier wartet: [Fragen Sie die Bestellung ab](/docs/guides/numbers/buying-numbers#poll-an-order-that-did-not-finish), bis ihr `status` den Wert `completed` oder `failed` hat. Eine bereits berechnete Einrichtungsgebühr wird nicht erstattet, wenn die Bestellung anschließend fehlschlägt. Die Referenz wird auf der Nummer gesetzt, wenn die Bestellung abgeschlossen ist. Sie fasst bis zu 100 Zeichen und muss nicht eindeutig sein. Wenn Sie eine Bestellung für eine Nummer, die Ihrem Workspace bereits zugewiesen ist, erneut versuchen, erhalten Sie die bestehende Bestellung zurück. Ein erneuter Versuch wird also nicht doppelt berechnet. [Nummer kaufen und freigeben](/docs/guides/numbers/buying-numbers#when-an-order-is-refused) erläutert die Ablehnungen. Um eine Referenz später zu setzen oder zu ändern, senden Sie `reference` (und optional `name`) an `PATCH /v1/numbers/{number_id}`. Senden Sie `null`, um ein Feld zu leeren. ## Prüfen, ob eine Nummer Anrufe übertragen kann Eine Nummer, deren `status` den Wert `pending_ownership_registration` hat, ist zugewiesen und wird abgerechnet, sendet aber keine SMS und lehnt ein- und ausgehende Sprachanrufe ab, bis ihre Eigentumsunterlagen genehmigt sind. Bevor Sie eine Nummer routen oder einen Testanruf an sie tätigen, lesen Sie sie mit [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number) und prüfen Sie, ob `status` den Wert `active` hat. Falls der Status ausstehend ist, [reichen Sie die Eigentumsunterlagen ein](#eigentumsunterlagen-einreichen). [Der Status einer zugewiesenen Nummer](/docs/guides/numbers/overview#the-status-of-an-allocated-number) erläutert jeden Wert. Die folgenden Beispiele verwenden eine niederländische Mobilfunknummer. Prüfen Sie den `status` Ihrer eigenen Nummer auf dieselbe Weise, unabhängig vom Land. ## Eigentumsunterlagen einreichen Telserv nahm die Unterlagen einer Nummer mit einem `POST /numbers/{dnisId}/documents` pro Dokument und einem `POST /numbers/{dnisId}/enduserdata` für alle Labels entgegen. Bird nimmt beides in einer einzigen Übermittlung entgegen, nachdem Sie die Dokumente hochgeladen haben. 1. Lesen Sie die `country_code` der Nummer und speichern Sie sie als `COUNTRY_CODE`. Der Befehl extrahiert sie mit `jq`; lesen Sie sie manuell ab, wenn Sie `jq` nicht verwenden: ```bash COUNTRY_CODE=$(curl -s "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \ --header "Authorization: Bearer $BIRD_API_KEY" | jq -r .country_code) ``` 2. Lesen Sie, was das Land der Nummer verlangt. Jeder Eintrag in `fields` enthält den `key`, unter dem Sie antworten, einen `data_type` und `required`, das angibt, ob Sie ihn beantworten müssen. Speichern Sie die in der Antwort genannte `program` 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" ``` Ein `422` mit [`E19001`](/docs/api/errors/E19001) bedeutet, dass es für dieses Land kein Eigentumsformular gibt. 3. Laden Sie jedes Dokument, das ein `document`-Feld verlangt, als Datei statt als Base64-`fileContent` hoch. Speichern Sie die `id` aus der Antwort, den `tca_`-Identifier des Anhangs, 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. Übermitteln Sie alle Antworten auf einmal: einen Eintrag für jedes Feld, dessen `required` den Wert `true` hat, und für jedes optionale Feld, für das Sie eine echte Antwort haben, mit den Endnutzerdaten als `value` und jedem Dokument als `attachment_id`. Lassen Sie ein optionales Feld weg, statt einen Wert dafür zu erfinden. Das Beispiel zeigt zwei Antworten; ergänzen Sie die übrigen Pflichtantworten, bevor Sie es senden. Diese Anfrage reicht die Antworten zur Prüfung ein. Speichern Sie die `id` aus der Antwort, den `csb_`-Identifier der Übermittlung, 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"'"}]}' ``` Eine `201`-Antwort gibt die Übermittlung zurück. Ein `422` reicht nichts ein: Korrigieren Sie den Body und senden Sie ihn mit einem neuen Idempotenzschlüssel, da der alte Schlüssel die Ablehnung erneut liefert. [Alle Antworten übermitteln](/docs/guides/numbers/ownership-paperwork#submit-every-answer) erläutert jede Ablehnung. 5. Wenn ein Prüfer eine Antwort ablehnt, ersetzen Sie nur diese Antwort, wie unter [Abgelehnte Antwort korrigieren](/docs/guides/numbers/ownership-paperwork#correct-a-rejected-answer) beschrieben: ```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"}]}' ``` Um die Unterlagen gleich beim Kauf einzureichen, senden Sie dasselbe `answers` im `compliance`-Block von `POST /v1/numbers/orders`. Diese Bestellung verwendet den bestehenden `numbers`-Scope auf Schreibebene, auch wenn sie Unterlagen enthält. Verfolgen Sie die Prüfung über `ownership.status` auf [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number). Die Angaben sind eine rechtsverbindliche Erklärung im Namen Ihres Unternehmens. Reichen Sie daher nur Angaben ein, die eine dafür verantwortliche Person bestätigt hat. [Eigentumsunterlagen einer Nummer einreichen](/docs/guides/numbers/ownership-paperwork) beschreibt jede Anfrage, die Prüfung und das Einreichen mit der Bestellung. ## Eine Nummer zu Ihrem SIP-Trunk routen Eine neue Nummer hat keine eigene Route und folgt daher der [Standardroute](/docs/guides/voice/receiving-calls#set-a-default-route) Ihres Workspace. Diese Standardroute ist anfangs `reject`, doch in einem Workspace, der bereits eine festgelegt hat, beantwortet die neue Nummer Anrufe nach dieser Route, sobald sie zugewiesen ist. Um ihre Anrufe an Ihr Equipment zu liefern, erstellen Sie einen SIP-Trunk mit aktiviertem Inbound-Calling, fügen Sie ein Gateway hinzu und verweisen Sie die Nummer auf den Trunk. [SIP-Trunks](/docs/guides/voice/sip-trunks) beschreibt, wie Sie Ihr Equipment mit dem Trunk verbinden. 1. Erstellen Sie den Trunk mit aktiviertem Inbound-Calling. Speichern Sie den `id` aus der Antwort, den `spt_`-Identifier des Trunks, 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. Fügen Sie ein Gateway hinzu. Standardmäßig empfängt das Gateway die gewählte und die anrufende Nummer im E.164-Format mit ihrem `+`. Wenn Ihre Anlage Nummern ohne `+` erwartet, wie es Telservs `{dnis}`-Platzhalter tat, setzen Sie `destination_format` für die gewählte Nummer und `origination_format` für die anrufende Nummer auf `{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}"}' ``` Für Failover fügen Sie ein zweites Gateway hinzu; [Was ein Gateway benötigt](/docs/guides/voice/receiving-calls#what-a-gateway-needs) erklärt `priority` und die Nummernformate. Wenn Sie dasselbe Gateway ohne Idempotenzschlüssel erneut erstellen, lautet die Antwort `409` mit [`E21047`](/docs/api/errors/E21047). 3. Finden Sie den Voice-Datensatz der Nummer. Suchen Sie mit den Ziffern der Nummer und nehmen Sie den `id` des Eintrags, dessen `provider.number_id` die `id` der Zuweisung ist. Speichern Sie ihn als `VOICE_NUMBER_ID`: ```bash curl "$BIRD_API_URL/v1/voice/numbers?search=31612345678" \ --header "Authorization: Bearer $BIRD_API_KEY" ``` 4. Verweisen Sie die Nummer auf den Trunk: ```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"'"}}}' ``` Eine `200`-Antwort zeigt die neue Route. Ein Trunk mit deaktiviertem Inbound-Calling antwortet mit `412` und [`E21052`](/docs/api/errors/E21052). Wenn Sie Inbound-Calling auf einem Trunk deaktivieren oder den Trunk löschen, kehrt jede dorthin geroutete Nummer zur Standardroute Ihres Workspace zurück, und erneutes Aktivieren stellt diese Routen nicht wieder her. [Anrufe an einen SIP-Trunk zustellen](/docs/guides/voice/receiving-calls#deliver-calls-to-a-sip-trunk) erklärt dies sowie die Routen `trunk`, `forward` und `reject`. ## Ihre Nummern abgleichen Durchlaufen Sie die Liste mit der größten Seitengröße. Übergeben Sie den `next_cursor` jeder Seite als `NEXT_CURSOR`, um die nächste Seite zu lesen, bis `next_cursor` den Wert `null` hat. Die Liste gibt keine Gesamtanzahl zurück. ```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" ``` Telservs Listenfilter werden wie folgt auf die von Bird abgebildet: | Telserv-Filter auf `GET /numbers` | Bird-Filter auf `GET /v1/numbers` | | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `number`, stimmt mit dem Anfang der Nummer überein | `prefix` ohne `country_code`, stimmt mit den Ziffern vom Anfang der vollständigen Nummer überein | | `prefix`, entspricht der Zugangs- und Ortsnetzkennzahl wie `3170` | `country_code` mit `prefix` auf die nationalen Ziffern gesetzt: `country_code=NL&prefix=70` | | `reference` mit einem Teilwert | `search`, stimmt mit einem Teil der Nummer, des Namens oder der Referenz überein, ohne Berücksichtigung der Groß-/Kleinschreibung | | `reference` mit einem exakten Wert in Anführungszeichen | `reference`, gibt die Nummern mit genau dieser Referenz zurück. Der Abgleich unterscheidet Groß- und Kleinschreibung | | Neu in Bird | `number` gibt eine vollständige Nummer mit Landesvorwahl zurück, mit oder ohne `+` oder `00`: `+31612345678`, `31612345678` und `0031612345678` finden dieselbe Nummer | [Eine Nummer in Ihrer Liste finden](/docs/guides/numbers/managing-numbers#find-a-number-in-your-list) beschreibt jeden Filter im Detail. Jeder Eintrag enthält `pricing` mit `recurring_price` pro `recurring_period` und `intervals_per_charge`. Sofern der Preis nicht für die Nummer festgelegt ist, ist `recurring_price` der aktuelle Tarif Ihrer Organisation, und jede Verlängerung berechnet den zum Zeitpunkt der Verlängerung geltenden Tarif, sodass ein bereits abgerechneter Betrag davon abweichen kann. [Alle Ihre Nummern auflisten](/docs/guides/numbers/managing-numbers#list-every-number-you-hold) erklärt, in welcher Währung jede Nummer abgerechnet wird, wann `pricing` oder seine Preise `null` sind und was zu tun ist, wenn `pricing.error` gesetzt ist. Eine freigegebene Nummer verschwindet aus dieser Liste, und ein Lesen über `number_id` antwortet mit `404`. Wenn Sie sie in Bird bestellt haben, bleibt ihre abgeschlossene Bestellung in [`GET /v1/numbers/orders`](/docs/api/reference/list-numbers-orders) sichtbar. ## Eine Nummer freigeben Beide Anfragen gelten für eine dedizierte Nummer, adressiert über ihren `nda_`-Bezeichner; eine geteilte Nummer wird mit [`E14002`](/docs/api/errors/E14002) abgelehnt. Um die Nummer bis zum Ende des bereits bezahlten Zeitraums zu behalten, kündigen Sie sie: ```bash curl --request DELETE "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \ --header "Authorization: Bearer $BIRD_API_KEY" \ --header "Idempotency-Key: cancel-CUST-778812" ``` Eine `202`-Antwort gibt die Nummer mit `releases_at` zurück, dem Ende ihres bezahlten Zeitraums. Die Nummer behält bis dahin ihren aktuellen Status, ihr Abonnement verlängert sich nicht, und sie wird zu diesem Zeitpunkt freigegeben. Eine erneute Anfrage gibt dasselbe `releases_at` zurück, und eine Kündigung kann nicht rückgängig gemacht werden. Eine Nummer ohne zugrunde liegendes Abonnement wird sofort freigegeben, und die Antwort ist `200` mit `status` der Nummer auf `released` gesetzt. Um die Nummer jetzt freizugeben, auch wenn bereits eine Kündigung geplant ist: ```bash curl --request POST "$BIRD_API_URL/v1/numbers/$NUMBER_ID/release" \ --header "Authorization: Bearer $BIRD_API_KEY" \ --header "Idempotency-Key: release-CUST-778812" ``` Eine `204`-Antwort bedeutet, dass die Nummer sofort freigegeben ist. Der Rest des laufenden Zeitraums wird nicht erstattet. Solange eine Verlängerungszahlung für die Nummer überfällig ist, antworten beide Anfragen mit `409` und [`E03015`](/docs/api/errors/E03015), bis sie bezahlt ist. Keine der beiden Anfragen nimmt ein Datum entgegen. Behalten Sie daher den Zeitplan, den Sie an Telserv gesendet haben, als `requestedCancelDate` auf Ihrer Seite. Um eine Nummer bis zu ihrem Datum zu behalten, kündigen Sie sie, sobald das Datum in ihren aktuellen Abrechnungszeitraum fällt: Sie wird freigegeben, wenn dieser Zeitraum endet, also am oder nach dem Datum. Um sie genau am Datum aufzugeben, geben Sie sie an diesem Tag frei. [Eine Nummer freigeben](/docs/guides/numbers/managing-numbers#release-a-number) beschreibt, was jede Anfrage mit der Nummer und ihren Gebühren macht und wie ein erneuter Versuch wirkt. ## Einen Testanruf an Ihre Nummer tätigen Um eine Route durchgängig zu prüfen, rufen Sie die Nummer von einer anderen Nummer an, die Ihr Workspace als Anrufer-ID präsentieren darf. Das Land der Nummer muss in Ihren [Voice-Zielen](/docs/guides/voice/destinations) aktiviert sein, sonst kommt der Anruf nicht durch. Die folgende Anfrage führt eine Inline-Sequenz aus, die auflegt, sobald der Anruf angenommen wird. Eine gespeicherte Sequenz ist daher nicht nötig. Es handelt sich um einen echten Anruf, und die normalen Gesprächsgebühren fallen an. Speichern Sie die Anfrage als `test-call.json`. Tragen Sie in `from` die Anrufer-ID ein, die Sie präsentieren, also eine eigene oder [verifizierte Nummer](/docs/guides/voice/caller-ids) Ihres Workspace, und in `to` die zu testende Nummer: ```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": {} } } ``` Senden Sie sie ab: ```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 ``` Setzen Sie `TEST_CALL_KEY` für jeden Test auf einen neuen Wert und verwenden Sie ihn wieder, wenn Sie denselben Test nach einem Timeout oder einem unklaren Ergebnis erneut versuchen: Derselbe Schlüssel und dieselbe Anfrage innerhalb von drei Stunden wiederholen die erste Annahme, statt einen zweiten Anruf zu tätigen. Eine `202`-Antwort nimmt den Anruf an und gibt seine `initial_leg_id` zurück. Die Annahme beweist nicht, dass der Anruf verbunden wurde: Lesen Sie den Leg mit [`GET /v1/voice/legs/{leg_id}`](/docs/api/reference/get-voice-leg) aus, oder listen Sie die an die Nummer getätigten Legs mit [`GET /v1/voice/legs`](/docs/api/reference/list-voice-legs) und seinem `to`-Filter auf, und prüfen Sie, ob Ihre Anlage den Anruf empfangen hat. [Sprachanruf erstellen](/docs/guides/voice/create-calls) behandelt die Anforderungen an Anrufer-ID und Ziel sowie die Regeln für erneute Versuche. ## Nächste Schritte - [Nummer kaufen und freigeben](/docs/guides/numbers/buying-numbers) - [Ihre Telefonnummern verwalten](/docs/guides/numbers/managing-numbers) - [Eigentumsunterlagen einer Nummer einreichen](/docs/guides/numbers/ownership-paperwork) - [Anrufe empfangen](/docs/guides/voice/receiving-calls) - [SIP-Trunks](/docs/guides/voice/sip-trunks) - [Idempotenz](/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)