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. 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 y Port out safely — 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

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.
Firmante autorizado — una persona nombrada con cargo, autorizada a mover el número y a firmar la LOA.
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í.
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.
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.
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

Introducir los números (un E.164 por línea) → ejecutar el gate previo. Elegible, o no continúe.
Rellenar los campos de carrier + CSR — copias exactas del CSR.
Guardar como borrador — draft: true almacena la solicitud localmente con staging: "draft" y nunca toca a un carrier.
Subir la LOA en la plataforma (POST /numbers/porting/:id/loa) — PDF/imagen de menos de 10 MB.
Firmar (.../loa/sign) — nombre del firmante, email, acuse. Firmar dos veces devuelve 422.
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.
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.
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.
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.

cURL

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

Reference

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

Nota de idioma

Recorrido de su primer port-in

1. La máquina de estados que navega

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

3. Paso a paso — el orden del asistente

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

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

​Nota de idioma

​Recorrido de su primer port-in

​1. La máquina de estados que navega

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

​3. Paso a paso — el orden del asistente

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

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

Nota de idioma

Recorrido de su primer port-in

1. La máquina de estados que navega

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

3. Paso a paso — el orden del asistente

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

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