> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Ihre erste Portierung: ein Walkthrough zum Richtig-Machen (LOA, PIN und FOC-Tracking)

> Erstmal-Checkliste über den gesamten Nummern-Lebenszyklus: Dokumente und Account-PIN vor dem Import, die Wizard-Schritte vom Antrag bis zur signierten LOA, FOC-Termin-Tracking beim Cutover, die Webhooks zum Abonnieren und die fünf Ablehnungsgründe, die erste Portierungen stoppen — mit der Lösung je Fall.

## 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](https://docs.orbit.devotel.io/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](https://docs.orbit.devotel.io/guides/port-numbers.md) und [Port out safely](https://docs.orbit.devotel.io/guides/port-out-numbers.md) — 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:

| Ablehnung | Warum es passiert | Lösung |
| - | - | - |
| `NAME_MISMATCH` | Der Name der juristischen Person im Request weicht vom CSR ab. | CSR ziehen, innerhalb des 7-Tage-Fensters eine Ergänzung mit wortwörtlich kopiertem Namen einreichen. |
| `ADDRESS_MISMATCH` | Die Service-Adresse weicht ab — Hausnummernzusätze, ZIP+4 vs ZIP, Abkürzungen. | Ergänzung mit der exakten CSR-Adresse, unverändert vom Carrier zitiert. |
| `BTN_MISMATCH` | Bei Mehrzeilen-Accounts stimmt die übermittelte Billing-Nummer nicht mit der Rechnung des Carriers überein. | BTN aus dem CSR holen (eigenes Feld, nicht die Account-Nummer) und ergänzen. |
| PIN-Ablehnung | Die Transfer-PIN vom abgebenden Carrier fehlte oder war falsch. | PIN mit dem Carrier klären — ohne sie kann die Portierung nicht weiterlaufen. |
| `LOA_INVALID` | Die LOA ist unvollständig, unsigniert, ein Bildschirmfoto, älter als 30 Tage signiert oder unleserlich gescannt. | LOA als echtes PDF mit mindestens 200 dpi neu erstellen; Portierung stornieren und mit korrigiertem Dokument neu einreichen. |

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.

```bash cURL theme={null}
# 1. Pre-import check — one live carrier call (numbers:read)
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/porting/check \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumber": "+14155551234", "currentCarrier": "Acme Telecom" }'
# Gate on: eligible === true

# 2. Create the port (numbers:write) — checkpoint as a draft while the LOA is outstanding
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/porting \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "numbers": ["+14155551234"],
    "currentCarrier": "Acme Telecom",
    "country": "US",
    "accountNumber": "998877",
    "authorizedSigner": "Jane Doe"
  }'

# 7. Track the FOC
curl "https://api.orbit.devotel.io/api/v1/numbers/porting/:id/timeline" \
  -H "X-API-Key: dv_live_sk_..."
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.