Skip to main content

​
Sprachhinweis

Diese deutsche Variante ist eine gekürzte Übersetzung: Der Abschnitt „4. Status webhooks — what to subscribe” existiert nur in der englischen Fassung: /en/guides/number-porting-walkthrough-first-port. Code-Blöcke, Endpoint-Pfade, API-Feldnamen und Fehlercodes bleiben englisch.

​
Walkthrough für Ihre erste Portierung

Die beiden Operator-Runbooks — Port a number end-to-end und Port out safely — decken jeden Endpoint und Edge Case ab. Diese Seite ist die kürzere Checkliste für das erste Mal, dass Sie eine Nummer umziehen: Sie ordnet die Entscheidungen, benennt die eine Sache, die jeder Schritt schützt, und ordnet stockende Portierungen dem Ablehnungsgrund zu, der sie verursacht hat.

​
1. Die Zustandsmaschine, in der Sie navigieren

Beide Portierungsrichtungen sind eine Einweg-Zustandsmaschine. Zu wissen, in welchem Zustand Sie sind, sagt Ihnen, welche Aktionen noch offen sind — die meisten Fehler bei ersten Portierungen sind Aktionen, die einen Zustand zu spät versucht werden. Port-In (Nummer zieht nach Orbit): submitted → reviewing → approved → completed, mit rejected und cancelled als terminalen Zweigen und supplement_submitted als Haltezustand, während der Carrier Ihre Ergänzung prüft:
  • submitted — der Auftrag existiert. Stornierbar (DELETE /numbers/porting/:id).
  • reviewing — der abgebende Carrier hält Ihren Auftrag plus signierte LOA und prüft die CSR-Daten. Noch stornierbar. Alles danach nicht mehr.
  • approved — der abgebende Carrier hat akzeptiert und (meist) ein FOC-Datum ausgestellt. Storno liefert jetzt 409; die Portierung wird vollzogen.
  • completed — die Nummer ist genau einmal live auf Ihrem Orbit-Account, mit emittiertem number.ported.
  • rejected — der Carrier hat abgelehnt; rejectionReason trägt den übersetzten Code. Behebbare Ablehnungen öffnen ein 7-Tage-supplement-Fenster.
  • cancelled — terminaler Zweig; nichts Weiteres gilt.
Port-Out (Nummer verlässt Orbit): Dieselbe Abfolge, zuerst vom Status der Nummer selbst gegattet: released, suspended, parked oder port_out_pending lehnen den Submit mit 409 ab. Nach dem FOC-Cutover gehört die Nummer dem gewinnenden Carrier — kein Storno, kein Rollback.

​
2. Pre-Import-Checkliste — vor dem ersten API-Call

  1. Customer Service Record (CSR) vom abgebenden Carrier — Name der juristischen Person, Account-Nummer, Billing Telephone Number (BTN), Service-Adresse und Transfer-PIN, wortwörtlich kopiert. Nicht aus dem Gedächtnis tippen; NAME_MISMATCH- und ADDRESS_MISMATCH-Ablehnungen stammen fast immer aus geratenen CSR-Feldern.
  2. Autorisierte:r Zeichner:in — eine benannte Person mit Titel, die berechtigt ist, die Nummer zu bewegen und die LOA zu signieren.
  3. LOA-Scan — ein echtes PDF mit mindestens 200 dpi, Signatur innerhalb von 30 Tagen datiert, jede portierte Nummer aufgeführt. LOA_INVALID-Ablehnungen häufen sich hier.
  4. Port-Out-PIN bereits auf Ihren Orbit-Nummern gesetzt — schützen Sie die Nummern, die Sie schon haben, bevor Sie neue hereinholen. POST /numbers/:id/port-out-protection mit einer 4-32-stelligen PIN.
  5. Länderregeln bekannt — US/CA-Nummern erhalten einen live synchronen Portability-Check; anderswo liefert der Check check-not-supported.
  6. Eligibility-Urteil eingeholt — POST /numbers/porting/pre-validate ausführen und auf ready: true gatten.
Wenn eine Checklist-Zeile ungeklärt ist, stoppen Sie. Gatedisziplin vor dem ersten Create verhindert, dass eine erste Portierung drei Wochen später zu einer abgelehnten wird.

​
3. Schritt für Schritt — die Wizard-Reihenfolge

  1. Nummern eingeben (eine E.164 je Zeile) → Pre-Flight-Gate ausführen. Eligible, oder nicht fortfahren.
  2. Carrier- + CSR-Felder ausfüllen — exakte CSR-Kopien.
  3. Als Entwurf sichern — draft: true speichert den Request lokal mit staging: "draft" und berührt nie einen Carrier.
  4. LOA in der Plattform hochladen (POST /numbers/porting/:id/loa) — PDF/Bild unter 10 MB.
  5. Signieren (.../loa/sign) — Name, E-Mail, Bestätigung der Zeichnerin. Zweimaliges Signieren liefert 422.
  6. Einreichen (.../loa/submit) — die einzige gültige Aktion im Zustand signed. Jetzt beginnt die 7-14-Werktage-Prüfung des abgebenden Carriers.
  7. FOC tracken — GET /numbers/porting/:id/timeline fächert den flachen Status in Stufen mit Zeitstempeln auf und gibt focDate aus, sobald der Carrier eines setzt. Beobachten bis status: completed.
  8. Beim Cutover feuert number.ported genau einmal — die Nummer tritt in den normalen Lebenszyklus ein wie eine gekaufte DID.
  9. Nie einen Entwurf parken — ein Entwurf erreicht den Carrier nie, bekommt nie ein FOC und wird nie vollzogen. Das Dashboard kennzeichnet genau diesen Zustand als „draft — LOA pending”.

​
5. Häufige Ablehnungen — und die Lösung je Fall

GET /numbers/porting/:id/timeline übersetzt Carrier-Ablehnungscodes in eine verständliche summary + recommendedAction mitSeverity: operator_fixable, needs_carrier oder fatal. Die fünf, die erste Portierungen stoppen: Jede Ablehnung mit Severity fatal (NUMBER_NOT_PORTABLE) lohnt keine Ergänzung — die Nummer muss beim abgebenden Carrier bleiben.

​
6. Über die API wachen — die vier Calls, lauffähig

Verwenden Sie einen API-Key mit numbers:read für Check- und Timeline-Lesezugriffe und numbers:write für das Create.
cURL
Bleibt die Portierung in submitted oder reviewing und stimmt etwas nicht, stornieren Sie mit DELETE /numbers/porting/:id. Nach approved liefert Storno 409 — die Portierung wird nach Carrier-Zeitplan vollzogen.