Referencia de la API

Crea un trámite con source:"herramienta". Requiere 19:tramites:write. El consumidor sale del sub del token, nunca del cuerpo.

Idempotencia. La misma referencia_externa con el mismo teléfono devuelve el mismo folio con 200 y resumed:true, aun con el tope diario lleno. Se comparan referencia, teléfono y la petición de activación; el resto del cuerpo se valida de nuevo pero no se aplica. La misma referencia con otro teléfono, o en otro sitio, es 409 REFERENCIA_EN_CONFLICTO.

Teléfono con trámite abierto. Si es tuyo con otra referencia: 409 TRAMITE_ABIERTO con su folio. Si es de otro canal u otra herramienta: 409 TRAMITE_ABIERTO_OTRO_CANAL sin folio ni datos.

Tope. 20 altas por consumidor y día de México.

Activación automática (restringida). activacion_automatica pide que Actívate active el trámite cuando cumpla los requisitos. Solo con clase:"real", consumidor en modo real y la función habilitada (403 ACTIVACION_AUTOMATICA_NO_HABILITADA). Queda fija desde el alta.

Orden de evaluación: sitio → autenticación, consumidor dado de alta y no suspendido, permiso → referencia_externa → clase → consent → validacion_previa → activacion_automatica → aviso de privacidad → nombre, teléfono y correo → idempotencia, conflictos de teléfono y tope diario → inserción.

Cuerpo (JSON)

Ejemplo

{
  "source": "herramienta",
  "referencia_externa": "mi-herramienta-000123",
  "clase": "prueba",
  "consent": {
    "basis": "aviso_aceptado",
    "evidence": {
      "aceptado_at": "2026-10-22T09:00:00-06:00",
      "canal": "app_socio"
    }
  },
  "contact_name": "Juan Pérez López",
  "contact_phone": "5500000921",
  "contact_email": "cliente@example.com",
  "plan_ref": "libre-1",
  "modalidad": "abierta",
  "validacion_previa": {
    "request_id": "val-000123",
    "sistema": "mi-sistema"
  }
}

Respuestas

has_number_to_keep:false ⇒ línea nueva. Con número: current_carrier distinto de telcel ⇒ portabilidad; telcel (comparado sin mayúsculas, acentos ni espacios de sobra) ⇒ migración o cambio de plan, que responden 422 CAMINO_NO_DISPONIBLE. Crea el pedido del trámite (503 PEDIDOS_NO_DISPONIBLE si el servicio de pedidos no responde). Un plan_ref inexistente aquí se ignora en silencio. Rate limit: 30 por minuto por IP.

Parámetros

Cuerpo (JSON)

Respuestas

plan_ref es el campo key de GET /v1/sites/{key}/plans (ej. libre-1). A diferencia del alta y de plan_linea, un plan_ref inexistente aquí sí da 422 PLAN_NOT_FOUND. Rate limit: 30 por minuto por IP.

Parámetros

Cuerpo (JSON)

Ejemplo

{
  "source": "herramienta",
  "plan_ref": "libre-2",
  "modalidad": "controlada"
}

Respuestas

nombre_completo y home_phone son obligatorios para una herramienta (una herramienta no puede declinar el teléfono adicional: no mandes home_phone_declinado). El correo es obligatorio si el trámite aún no tiene uno (el del alta cuenta). El nombre en objeto rechaza palabras genéricas (prueba, test, demo, cliente, …) con NOMBRE_GENERICO; el nombre en texto no pasa por ese filtro. Puede traer region_avisos (avisa, nunca bloquea a una herramienta). Rate limit: 30 por minuto por IP.

Parámetros

Cuerpo (JSON)

Ejemplo

{
  "source": "herramienta",
  "contact_email": "cliente@example.com",
  "nombre_completo": {
    "nombres": "Juan",
    "apellido_paterno": "Pérez",
    "apellido_materno": "López"
  },
  "address": {
    "cp": "06600",
    "colonia": "Juárez",
    "calle": "Calle Ejemplo",
    "numero_ext": "10"
  },
  "home_phone": "5500000922"
}

Respuestas

Se requieren 2 (references_required); solo cuentan las dos primeras. Reenviar reemplaza por posición. Los teléfonos deben ser distintos entre sí y del contacto, del adicional y de la línea. Rate limit: 30 por minuto por IP.

Parámetros

Cuerpo (JSON)

Ejemplo

{
  "source": "herramienta",
  "references": [
    {
      "name": "María Gómez",
      "phone": "5500000923",
      "relationship": "amiga",
      "holder_informed": true
    },
    {
      "name": "Luis Ramos",
      "phone": "5500000924",
      "relationship": "familiar",
      "holder_informed": true
    }
  ]
}

Respuestas

Exige las dos caras de la INE ya subidas cuando el cuerpo trae nip o iccid con valor (422 DOCUMENTOS_INCOMPLETOS). Un valor vacío borra el dato y no exige INE. En línea nueva la etapa no aplica pero la ruta acepta iccid. activation_status pasa a complete cuando un trámite de portabilidad tiene NIP.

Rate limit: 30 por minuto por IP.

Parámetros

Cuerpo (JSON)

Ejemplo

{
  "source": "herramienta",
  "nip": "1234"
}

Respuestas

El cuerpo son los bytes de la imagen (no multipart), con su Content-Type real. Máximo 20 MB y 20 documentos vivos por trámite (las rechazadas cuentan). X-Funnel-Source: herramienta es obligatorio. Con X-Adjunto-Ref (tu id para este archivo, ^[A-Za-z0-9-]{1,64}$) repetir la subida del mismo kind responde 200 duplicado:true sin duplicar; un valor con otra forma se descarta en silencio. Dos subidas simultáneas con el mismo X-Adjunto-Ref todavía pueden duplicar.

Cada foto se analiza al llegar (recomendado: timeout de hasta ~90 s). En un trámite de venta real, si la revisión lee datos de identidad, inicia una consulta con el operador, también con la foto rechazada; en prueba simulada no (en pruebas sube solo fotos ficticias). Una foto que la revisión rechaza responde 422 DOCUMENTO_RECHAZADO_IA pero se guarda y cuenta contra el máximo; se corrige con otra foto. Rate limit propio: 12 por minuto por IP.

Parámetros

Cuerpo

Los bytes de la imagen, con su Content-Type real (image/jpeg, image/png, application/octet-stream). No es multipart.

Respuestas

Requiere 19:tramites:access (write no implica access). No necesita X-Funnel-Source. Sin aviso de vuelta: consulta con intervalo. Rate limit: 30 por minuto por IP. Nunca trae datos internos del proceso (folios del operador, dictámenes, consultas de crédito, notas).

Parámetros

Respuestas

Requiere 19:tramites:access y el header X-Funnel-Source: herramienta (sin él: 404). Trae datos de personas (name_check: nombre leído de la INE cuando no coincide con el declarado). Manda siempre el token.

Parámetros

Respuestas

Requiere 19:tramites:access y X-Funnel-Source: herramienta. No aplica a herramientas en la práctica: lee iccid_foto y pantalla_foto, que una herramienta no puede subir; siempre responde estado:"sin_foto". Manda siempre el token.

Parámetros

Respuestas