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

# Su primer port-in: un recorrido para hacerlo bien (LOA, PIN y seguimiento de FOC)

> Checklist de primera vez por todo el ciclo de vida del número: documentos pre-importación y PIN de la cuenta, pasos del asistente de la solicitud a la LOA firmada, seguimiento de la fecha FOC en el corte, webhooks a suscribir y los cinco motivos de rechazo que atascan los primeros portados — con la solución de cada uno.

## Nota de idioma

Esta versión en español es una traducción abreviada: la sección «4. Status webhooks — what to subscribe» existe solo en inglés: [/en/guides/number-porting-walkthrough-first-port](https://docs.orbit.devotel.io/en/guides/number-porting-walkthrough-first-port). Los bloques de código, rutas de endpoints, nombres de campos de API y códigos de error permanecen en inglés.

# Recorrido de su primer port-in

Los dos runbooks de operador — [Port a number end-to-end](https://docs.orbit.devotel.io/guides/port-numbers.md) y [Port out safely](https://docs.orbit.devotel.io/guides/port-out-numbers.md) — cubren cada endpoint y caso límite. Esta página es la checklist más corta para la primera vez que mueve un número: ordena las decisiones, nombra lo que cada paso protege y relaciona los portados atascados con el motivo de rechazo que los causó.

## 1. La máquina de estados que navega

Ambas direcciones del portado son una máquina de estados de un solo sentido. Saber en qué estado está le dice qué acciones siguen abiertas — la mayoría de los errores de primer portado son una acción intentada un estado demasiado tarde.

**Port-in (número entrando en Orbit):** `submitted → reviewing → approved → completed`, con `rejected` y `cancelled` como ramas terminales y `supplement_submitted` como estado de espera mientras el carrier sopesa su enmienda:

* **submitted** — la orden existe. Cancelable (`DELETE /numbers/porting/:id`).
* **reviewing** — el carrier cedente tiene su orden más la LOA firmada y está comprobando los datos CSR. Aún cancelable. Nada más allá lo está.
* **approved** — el carrier cedente aceptó y (normalmente) emitió una fecha FOC. Cancelar ahora devuelve `409`; el portado se completará.
* **completed** — el número está activo en su cuenta de Orbit, exactamente una vez, con `number.ported` emitido.
* **rejected** — el carrier rechazó; `rejectionReason` lleva el código traducido. Los rechazos corregibles abren una ventana `supplement` de 7 días.
* **cancelled** — rama terminal; nada más aplica.

**Port-out (número saliendo de Orbit):** la misma progresión, limitada primero por el estado del propio número: `released`, `suspended`, `parked` o `port_out_pending` rechazan el submit con `409`. Tras el corte FOC, el carrier ganador posee el número — sin cancelación, sin vuelta atrás.

## 2. Checklist pre-importación — antes de la primera llamada API

1. **Customer Service Record (CSR)** del carrier cedente — nombre de la entidad legal, número de cuenta, billing telephone number (BTN), dirección de servicio y PIN de transferencia, copiados textualmente. No reescriba de memoria; los rechazos `NAME_MISMATCH` y `ADDRESS_MISMATCH` vienen casi siempre de campos CSR adivinados.
2. **Firmante autorizado** — una persona nombrada con cargo, autorizada a mover el número y a firmar la LOA.
3. **Escaneo de la LOA** — un PDF real a 200 dpi o más, firma fechada dentro de 30 días, todos los números portados listados. Los rechazos `LOA_INVALID` se concentran aquí.
4. **PIN de port-out ya fijado en sus números de Orbit** — proteja los que ya tiene antes de traer números nuevos. `POST /numbers/:id/port-out-protection` con un PIN de 4 a 32 caracteres.
5. **Reglas por país conocidas** — los números US/CA obtienen un control de portabilidad síncrono en vivo; en el resto el check devuelve `check-not-supported`.
6. **Veredicto de elegibilidad en mano** — ejecute `POST /numbers/porting/pre-validate` y gatee sobre `ready: true`.

Si alguna línea de la checklist queda abierta, pare. La disciplina de gate antes del primer create es lo que evita que un primer portado se convierta en un rechazo tres semanas después.

## 3. Paso a paso — el orden del asistente

1. **Introducir los números** (un E.164 por línea) → ejecutar el gate previo. Elegible, o no continúe.
2. **Rellenar los campos de carrier + CSR** — copias exactas del CSR.
3. **Guardar como borrador** — `draft: true` almacena la solicitud localmente con `staging: "draft"` y nunca toca a un carrier.
4. **Subir la LOA** en la plataforma (`POST /numbers/porting/:id/loa`) — PDF/imagen de menos de 10 MB.
5. **Firmar** (`.../loa/sign`) — nombre del firmante, email, acuse. Firmar dos veces devuelve `422`.
6. **Enviar** (`.../loa/submit`) — la única acción válida en estado `signed`. Este es el momento en que el carrier cedente inicia su revisión de 7 a 14 días hábiles.
7. **Seguir la FOC** — `GET /numbers/porting/:id/timeline` despliega el estado plano en etapas con marcas de tiempo y devuelve `focDate` en cuanto el carrier asigna una. Vigile hasta `status: completed`.
8. **En el corte, `number.ported` se dispara exactamente una vez** — el número entra en el ciclo de vida normal igual que un DID comprado.
9. **Nunca deje un borrador aparcado** — un borrador nunca llega al carrier, nunca obtiene FOC y nunca se completa. El dashboard señala exactamente ese estado como «draft — LOA pending».

## 5. Rechazos comunes — y la solución de cada uno

`GET /numbers/porting/:id/timeline` traduce los códigos de rechazo del carrier a `summary` + `recommendedAction` en claro, etiquetados con una severidad: `operator_fixable`, `needs_carrier` o `fatal`. Los cinco que atascan los primeros portados:

| Rechazo | Por qué ocurre | Solución |
| - | - | - |
| `NAME_MISMATCH` | El nombre de entidad legal de la solicitud difiere del CSR. | Saque el CSR y envíe un complemento dentro de la ventana de 7 días con el nombre copiado textualmente. |
| `ADDRESS_MISMATCH` | La dirección de servicio difiere — números de suite, ZIP+4 vs ZIP, abreviaturas. | Complemento con la dirección CSR exacta, citada sin cambios del carrier. |
| `BTN_MISMATCH` | En cuentas multilínea, el billing telephone number enviado no coincide con el registro del carrier. | Saque el BTN del CSR (es un campo distinto del número de cuenta) y complemente. |
| Rechazo de PIN | El PIN de transferencia del carrier cedente faltaba o era erróneo. | Confirme el PIN con el carrier — el portado no puede avanzar sin él. |
| `LOA_INVALID` | La LOA está incompleta, sin firmar, es una foto de pantalla, fue firmada hace más de 30 días o el escaneo es ilegible. | Rehaga la LOA como PDF real a 200 dpi o más; cancele el portado y reenvíe con el documento corregido. |

Cualquier rechazo con severidad `fatal` (`NUMBER_NOT_PORTABLE`) no merece un complemento — el número debe quedarse en el carrier cedente.

## 6. Vigilar por la API — las cuatro llamadas, ejecutables

Use una clave API con `numbers:read` para las lecturas de check y timeline, y `numbers:write` para el 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 el portado está en `submitted` o `reviewing` y algo va mal, cancélelo con `DELETE /numbers/porting/:id`. Tras `approved`, cancelar devuelve `409` — el portado se completará según el calendario del carrier.


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