> ## 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.

# Votre premier portage : un pas-à-pas pour bien faire (LOA, PIN et suivi FOC)

> Checklist de première fois sur tout le cycle de vie du numéro : documents pré-import et PIN du compte, étapes de l'assistant de la requête à la LOA signée, suivi de la date FOC au basculement, webhooks à abonner et les cinq motifs de rejet qui bloquent les premiers portages — avec le correctif de chacun.

## Note de langue

Cette version française est une traduction abrégée : la section « 4. Status webhooks — what to subscribe » n'existe qu'en anglais : [/en/guides/number-porting-walkthrough-first-port](https://docs.orbit.devotel.io/en/guides/number-porting-walkthrough-first-port). Les blocs de code, chemins d'endpoints, noms de champs API et codes d'erreur restent en anglais.

# Pas-à-pas de votre premier portage

Les deux runbooks opérateur — [Port a number end-to-end](https://docs.orbit.devotel.io/guides/port-numbers.md) et [Port out safely](https://docs.orbit.devotel.io/guides/port-out-numbers.md) — couvrent chaque endpoint et chaque cas limite. Cette page est la checklist plus courte pour la première fois que vous déplacez un numéro : elle ordonne les décisions, nomme ce que chaque étape protège, et rattache les portages qui stagnent au motif de rejet qui les a causés.

## 1. La machine à états que vous naviguez

Les deux sens du portage sont une machine à états à sens unique. Savoir dans quel état vous êtes dit quelles actions restent ouvertes — la plupart des erreurs de premier portage sont une action tentée un état trop tard.

**Port-in (numéro entrant sur Orbit) :** `submitted → reviewing → approved → completed`, avec `rejected` et `cancelled` comme branches terminales et `supplement_submitted` comme état d'attente pendant que le carrier examine votre complément :

* **submitted** — la commande existe. Annulable (`DELETE /numbers/porting/:id`).
* **reviewing** — le carrier perdant détient votre commande plus la LOA signée et vérifie les données CSR. Encore annulable. Rien au-delà ne l'est.
* **approved** — le carrier perdant a accepté et (en général) émis une date FOC. Annuler maintenant rend `409` ; le portage ira à son terme.
* **completed** — le numéro est en service sur votre compte Orbit, exactement une fois, avec `number.ported` émis.
* **rejected** — le carrier a refusé ; `rejectionReason` porte le code traduit. Les rejets corrigeables ouvrent une fenêtre `supplement` de 7 jours.
* **cancelled** — branche terminale ; rien d'autre ne s'applique.

**Port-out (numéro quittant Orbit) :** même progression, d'abord limitée par le statut du numéro lui-même : `released`, `suspended`, `parked` ou `port_out_pending` rejettent le submit avec `409`. Après le basculement FOC, le carrier gagnant possède le numéro — pas d'annulation, pas de retour arrière.

## 2. Checklist pré-import — avant le premier appel API

1. **Customer Service Record (CSR)** du carrier perdant — nom de l'entité légale, numéro de compte, billing telephone number (BTN), adresse de service et éventuel PIN de transfert, copiés mot pour mot. Ne retapez pas de mémoire ; les rejets `NAME_MISMATCH` et `ADDRESS_MISMATCH` viennent presque toujours de champs CSR devinés.
2. **Signataire autorisé** — une personne nommée, avec son titre, habilitée à déplacer le numéro et à signer la LOA.
3. **Scan de la LOA** — un vrai PDF à 200 dpi ou plus, signature datée de moins de 30 jours, chaque numéro porté listé. Les rejets `LOA_INVALID` se concentrent ici.
4. **PIN de port-out déjà posé sur vos numéros Orbit** — protégez ceux que vous avez déjà avant d'en faire entrer de nouveaux. `POST /numbers/:id/port-out-protection` avec un PIN de 4 à 32 caractères.
5. **Règles pays connues** — les numéros US/CA obtiennent un contrôle de portabilité synchrone en direct ; ailleurs le check rend `check-not-supported`.
6. **Verdict d'éligibilité en main** — exécutez `POST /numbers/porting/pre-validate` et gatez sur `ready: true`.

Si une ligne de la checklist reste ouverte, arrêtez-vous. La discipline de gate avant le premier create évite qu'un premier portage devienne un rejet trois semaines plus tard.

## 3. Étape par étape — l'ordre de l'assistant

1. **Saisir les numéros** (un E.164 par ligne) → exécuter le gate de pré-vol. Éligible, ou ne continuez pas.
2. **Remplir les champs carrier + CSR** — copies exactes du CSR.
3. **Jalonner en brouillon** — `draft: true` stocke la requête localement avec `staging: "draft"` et ne touche jamais un carrier.
4. **Téléverser la LOA** dans la plateforme (`POST /numbers/porting/:id/loa`) — PDF/image de moins de 10 Mo.
5. **Signer** (`.../loa/sign`) — nom du signataire, e-mail, accusé. Signer deux fois rend `422`.
6. **Soumettre** (`.../loa/submit`) — la seule action valide à l'état `signed`. C'est le moment où le carrier perdant entame sa revue de 7 à 14 jours ouvrés.
7. **Suivre la FOC** — `GET /numbers/porting/:id/timeline` déplie le statut plat en étapes horodatées et renvoie `focDate` dès que le carrier en assigne une. Surveillez jusqu'à `status: completed`.
8. **Au basculement, `number.ported` est émis exactement une fois** — le numéro entre dans le cycle de vie normal comme un DID acheté.
9. **Ne jamais laisser un brouillon en jachère** — un brouillon n'atteint jamais le carrier, n'obtient jamais de FOC et ne se termine jamais. Le dashboard signale exactement cet état comme « draft — LOA pending ».

## 5. Rejets courants — et le correctif de chacun

`GET /numbers/porting/:id/timeline` traduit les codes de rejet carrier en `summary` + `recommendedAction` en clair, tagués d'une sévérité : `operator_fixable`, `needs_carrier` ou `fatal`. Les cinq qui stoppent les premiers portages :

| Rejet | Pourquoi | Correctif |
| - | - | - |
| `NAME_MISMATCH` | Le nom d'entité légale de la requête diffère du CSR. | Tirez le CSR, soumettez un complément dans la fenêtre de 7 jours avec le nom copié mot pour mot. |
| `ADDRESS_MISMATCH` | L'adresse de service diffère — numéros de suite, ZIP+4 vs ZIP, abréviations. | Complément avec l'adresse CSR exacte, citée sans modification du carrier. |
| `BTN_MISMATCH` | Sur les comptes multilignes, le billing telephone number envoyé ne correspond pas au dossier du carrier. | Tirez le BTN du CSR (c'est un champ distinct du numéro de compte) et complétez. |
| Rejet PIN | Le PIN de transfert du carrier perdant était absent ou faux. | Confirmez le PIN avec le carrier — le portage ne peut pas avancer sans lui. |
| `LOA_INVALID` | LOA incomplète, non signée, photo d'écran, signée depuis plus de 30 jours ou scan illisible. | Refaites la LOA en vrai PDF à 200 dpi ou plus ; annulez le portage et resoumettez avec le document corrigé. |

Tout rejet de sévérité `fatal` (`NUMBER_NOT_PORTABLE`) ne vaut pas un complément — le numéro doit rester chez le carrier perdant.

## 6. Veiller via l'API — les quatre appels, exécutables

Utilisez une clé API avec `numbers:read` pour les lectures check et timeline, et `numbers:write` pour le 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_..."
```

Si le portage est en `submitted` ou `reviewing` et que quelque chose cloche, annulez-le avec `DELETE /numbers/porting/:id`. Après `approved`, l'annulation rend `409` — le portage ira à son terme au calendrier du carrier.


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