Documentación de la API

Descargar la documentación de la API (Markdown)

kartesim ofrece a los partners números de teléfono reales e IP móviles mediante dos servicios: alquiler de números y proxies de larga duración y sesiones OTP por uso. Ambos están disponibles a través del protocolo HANDLER_API y de la API REST nativa.

Sesiones OTPpor uso

Solicita un número temporal, espera un SMS y recibe el código OTP, todo en un solo ciclo de llamadas a la API. Se cobra por sesión y se reembolsa si cancelas antes de que llegue el código.

Alquiler de númerosTarjetas SIM

Alquila un número de teléfono dedicado por días, semanas o meses. Todos los SMS que recibe ese número se reenvían a tu cuenta en tiempo real.

Alquiler de proxiesIP móviles

Alquila un proxy móvil HTTP/SOCKS5 con una IP real de operador. Cada proxy funciona en un dispositivo dedicado (Android o módem 4G) con una tarjeta SIM activa.

Tu gestor de cuenta se encarga de aprovisionar los alquileres. Contacta con nosotros para configurar tu alquiler; una vez activo, tu número de teléfono y las credenciales del proxy aparecen en el portal de partners y se pueden consultar mediante la API. Las sesiones OTP son de autoservicio mediante la API, sin necesidad de configuración.

Autenticación

Todas las solicitudes a la API requieren tu clave API de partner. La forma de enviarla depende del protocolo.

Handler API — parámetro de consulta

GET /api/stubs/handler_api.php
  ?api_key=YOUR_KEY
  &action=getBalance

API REST nativa — encabezado HTTP

curl https://www.kartesim.com/api/v1/otp/request \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service": "telegram"}'

Mantén tu clave API en secreto. Tu clave está visible en el portal de partners, en API. Usa allí el botón Regenerar clave para rotarla al instante.

Referencia de la Handler API

URL base: /api/stubs/handler_api.php — Todas las solicitudes usan GET. Todas las respuestas son texto plano.

GET/api/stubs/handler_api.php?action=getBalance

Devuelve tu saldo prepago actual en USD.

Parámetros

Nombre	Tipo	Obligatorio	Descripción
api_key	string	obligatorio	Tu clave API
action	string	obligatorio	Debe ser "getBalance"

Respuestas

45.00Tu saldo en USD

999999Valor fijo que se devuelve para las cuentas con saldo ilimitado; no es un saldo real y no cambia con el uso

BAD_KEYClave API no válida o revocada

Ejemplo de solicitud

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getBalance'

Ejemplo de respuesta

45.00

GET/api/stubs/handler_api.php?action=getCountries

Lista los países disponibles con sus códigos numéricos.

Parámetros

Nombre	Tipo	Obligatorio	Descripción
api_key	string	obligatorio	Tu clave API
action	string	obligatorio	Debe ser "getCountries"

Respuestas

JSON array[{ "id": 7, "name": "Russia" }, ...]

Ejemplo de solicitud

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getCountries'

Ejemplo de respuesta

[
  { "id": 7,   "name": "Russia" },
  { "id": 212, "name": "Morocco" }
]

GET/api/stubs/handler_api.php?action=getPrices

Obtén los precios actuales y el stock activo disponible por país y servicio.

Parámetros

Nombre	Tipo	Obligatorio	Descripción
api_key	string	obligatorio	Tu clave API
action	string	obligatorio	Debe ser "getPrices"
country	number	opcional	Filtrar por ID numérico de país
hide_empty	integer	opcional	Pon 1 para excluir de la respuesta los países sin stock

Respuestas

JSON object{ "countryId": { "serviceId": { "cost": 0.1, "count": 10 } } }

Ejemplo de solicitud

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getPrices&hide_empty=1'

Ejemplo de respuesta

{
  "212": {
    "wa": { "cost": 0.15, "count": 12 },
    "tg": { "cost": 0.15, "count": 12 }
  }
}

GET/api/stubs/handler_api.php?action=getNumber

Solicita un número de teléfono temporal para una verificación OTP. Devuelve un ID de sesión y el número asignado. La sesión caduca a los 10 minutos si no llega ningún SMS.

Parámetros

Nombre	Tipo	Obligatorio	Descripción
api_key	string	obligatorio	Tu clave API
action	string	obligatorio	Debe ser "getNumber"
service	string	opcional	Nombre del servicio (p. ej., "telegram", "whatsapp"); solo informativo
country	integer	opcional	Prefijo telefónico del país (p. ej., 212 para Marruecos). Omítelo o usa 0 para cualquier país.

Respuestas

ACCESS_NUMBER:id:numberSesión creada: id se usa en getStatus/setStatus y number es el número de teléfono asignado

NO_NUMBERSNo hay puertos en línea que coincidan con tu solicitud

NO_BALANCESaldo insuficiente para cubrir la tarifa OTP

Ejemplo de solicitud

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getNumber&service=telegram&country=212'

Ejemplo de respuesta

ACCESS_NUMBER:cma4x9k3b0000abc123:212661234567

GET/api/stubs/handler_api.php?action=getStatus

Consulta periódicamente el código OTP de una sesión activa. Consulta cada 5–10 segundos hasta recibir STATUS_OK o STATUS_CANCEL.

Parámetros

Nombre	Tipo	Obligatorio	Descripción
api_key	string	obligatorio	Tu clave API
action	string	obligatorio	Debe ser "getStatus"
id	string	obligatorio	ID de sesión de la respuesta ACCESS_NUMBER

Respuestas

STATUS_WAIT_CODELa sesión está activa; aún no ha llegado el SMS. Sigue consultando.

STATUS_OK:84729OTP recibido; el código va después de los dos puntos

STATUS_CANCELLa sesión ha caducado o se ha cancelado

Ejemplo de solicitud

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getStatus&id=cma4x9k3b0000abc123'

Ejemplo de respuesta

STATUS_OK:84729

GET/api/stubs/handler_api.php?action=setStatus

Confirma la recepción del OTP (status=1) o cancela la sesión para obtener un reembolso completo (status=8). Solo se pueden cancelar las sesiones PENDING.

Parámetros

Nombre	Tipo	Obligatorio	Descripción
api_key	string	obligatorio	Tu clave API
action	string	obligatorio	Debe ser "setStatus"
id	string	obligatorio	ID de la sesión sobre la que actuar
status	integer	obligatorio	1 = confirmar recepción, 8 = cancelar y reembolsar

Respuestas

ACCESS_READYConfirmado: sesión reconocida

ACCESS_CANCELCancelado: saldo reembolsado

BAD_ACTIONSesión no encontrada o ya completada

Ejemplo de solicitud

# Cancel and refund
curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=setStatus&id=cma4x9k3b0000abc123&status=8'

Ejemplo de respuesta

ACCESS_CANCEL

API REST nativa

Para integraciones modernas, usa nuestra API REST nativa en lugar de la antigua Handler API. Envía tu clave API en el encabezado HTTP x-api-key.

Sesiones OTP

por uso

Las sesiones OTP te permiten solicitar un número de teléfono temporal, recibir un código de un solo uso y liberar el número, todo mediante la API. Cada sesión se cobra una sola vez al crearse. Si cancelas antes de que llegue el código, se reembolsa la tarifa completa.

POST/api/v1/otp/request

Solicita un número de teléfono temporal para una verificación OTP. Devuelve un sessionId y el número asignado. Cobra la tarifa OTP_PER_USE de inmediato.

Parámetros

Nombre	Tipo	Obligatorio	Descripción
country	integer	opcional	Prefijo telefónico del país para filtrar (p. ej., 212). Omítelo para cualquiera.
service	string	opcional	Nombre del servicio, p. ej., "telegram"; se guarda en la sesión como referencia
webhookUrl	string	opcional	URL HTTPS a la que enviar un POST cuando llegue el OTP (en lugar de consultar)
expiresIn	integer	opcional	Duración de la sesión en segundos (60–1800, 600 por defecto)

Respuestas

200 OKSesión creada: el cuerpo contiene sessionId, number y expiresAt

402 Payment RequiredSaldo insuficiente

503 Service UnavailableNo hay números en línea disponibles

Ejemplo de solicitud

curl -X POST https://www.kartesim.com/api/v1/otp/request \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service": "telegram", "country": 212}'

Ejemplo de respuesta

{ "sessionId": "cma4x9k3b0000abc123", "number": "212661234567", "status": "PENDING", "expiresAt": "2026-06-01T00:20:00.000Z" }

GET/api/v1/otp/:sessionId

Consulta el estado y el código de una sesión OTP. Devuelve el código OTP extraído en cuanto llega el SMS. Consulta cada 5–10 segundos.

Respuestas

200 OK — PENDINGstatus: "PENDING", otp: null — aún en espera

200 OK — RECEIVEDstatus: "RECEIVED", otp: "84729" — código listo

200 OK — EXPIREDstatus: "EXPIRED" — no llegó ningún SMS dentro del plazo

200 OK — CANCELLEDstatus: "CANCELLED" — cancelaste la sesión

Ejemplo de solicitud

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/v1/otp/cma4x9k3b0000abc123

Ejemplo de respuesta

{ "sessionId": "cma4x9k3b0000abc123", "status": "RECEIVED", "number": "212661234567", "otp": "84729", "smsBody": "Your code is 84729" }

POST/api/v1/otp/:sessionId/cancel

Cancela una sesión PENDING. Reembolsa íntegramente la tarifa OTP. Las sesiones que ya han recibido un OTP no se pueden cancelar.

Respuestas

200 OKstatus: "CANCELLED", refunded: 0.10 — saldo abonado

409 ConflictLa sesión no está en estado PENDING; no se puede cancelar

404 Not FoundSesión no encontrada o perteneciente a otra cuenta

Ejemplo de solicitud

curl -X POST -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/v1/otp/cma4x9k3b0000abc123/cancel

Ejemplo de respuesta

{ "sessionId": "cma4x9k3b0000abc123", "status": "CANCELLED", "refunded": "0.1000" }

POSTTu URL de webhook (envío desde el servidor)

Cuando llega un OTP, enviamos un POST al webhookUrl que indicaste al crear la sesión. Es una alternativa a las consultas periódicas: tu servidor recibe el OTP automáticamente sin necesidad de llamar a getStatus.

Contenido

POST a tu webhookUrl

{
  "event":      "otp.received",
  "sessionId":  "cma4x9k3b0000abc123",
  "status":     "RECEIVED",
  "number":     "212661234567",
  "otp":        "84729",
  "smsBody":    "Your Telegram code is 84729",
  "receivedAt": "2026-06-21T12:00:00.000Z"
}

Seguridad

En producción, tu URL de webhook debe usar HTTPS; las URL HTTP se rechazan.
Enviamos un encabezado X-Webhook-Signature: sha256=... (HMAC-SHA256). Verifícalo para confirmar que la solicitud es auténtica.
Ante un 5xx reintentamos una vez a los 2 segundos. Tu endpoint debe devolver 200 rápidamente.
Tu endpoint debe ser idempotente: puede haber entregas duplicadas al reintentar.

GET/api/partner/rentals

Obtiene todos los alquileres de números activos de tu cuenta.

Respuestas

200 OKArray JSON de alquileres de números activos

401 UnauthorizedClave API no válida o ausente

Ejemplo de solicitud

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/partner/rentals

Ejemplo de respuesta

[
  {
    "id": "cuid...",
    "phoneNumber": "1234567890",
    "countryCode": 1,
    "expiresAt": "2026-06-25T10:00:00.000Z",
    "daysRemaining": 26
  }
]

GET/api/partner/proxies

Obtiene todos los alquileres de proxies activos de tu cuenta, con su dirección IP actual y sus credenciales.

Respuestas

200 OKArray JSON de alquileres de proxies activos

401 UnauthorizedClave API no válida o ausente

Ejemplo de solicitud

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/partner/proxies

Ejemplo de respuesta

[
  {
    "id": "cuid...",
    "port": "Port A",
    "host": "192.168.1.10",
    "socks5Port": 1080,
    "username": "user",
    "password": "pwd",
    "expiresAt": "2026-06-25T10:00:00.000Z"
  }
]

GET/api/partner/sms?simNumber=1234567890

Obtiene los últimos SMS recibidos en tus números alquilados. Opcionalmente, filtra por un simNumber concreto.

Parámetros

Nombre	Tipo	Obligatorio	Descripción
simNumber	string	opcional	Filtrar los SMS de un número alquilado concreto

Respuestas

200 OKArray JSON de SMS recientes

401 UnauthorizedClave API no válida o ausente

Ejemplo de solicitud

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/partner/sms

Ejemplo de respuesta

[
  {
    "id": "cuid...",
    "simNumber": "1234567890",
    "fromNumber": "Twilio",
    "body": "Your verification code is 49201",
    "receivedAt": "2026-05-29T15:30:00.000Z"
  }
]

Alquiler de números

El alquiler de números te da el uso exclusivo de una tarjeta SIM real durante un periodo de alquiler fijo. Cada SMS que recibe ese número se entrega en tu cuenta en tiempo real. Puedes alquilar números directamente mediante la API o el portal de partners.

Periodo	Duración	Descripción
Diario	24 horas	Ideal para campañas de verificación de corta duración
Semanal	7 días	Ideal para un acceso continuo a un número estable
Mensual	30 días	Ideal para disponer de un número dedicado a largo plazo

Cómo funciona

Llama a GET /api/v1/numbers/available para ver los números disponibles (enmascarados).
Elige un número y un ciclo de facturación y llama a POST /api/v1/numbers/rent para alquilarlo al instante.
El importe se descuenta de tu saldo de inmediato. La respuesta devuelve el número de teléfono completo, sin enmascarar.
Todos los SMS que recibe tu número alquilado aparecen en Registros de SMS en tiempo real.
Al vencer, el número se libera automáticamente. No se reembolsa el tiempo no utilizado.

GET/api/v1/numbers/available

Consulta los números disponibles para alquilar. Los números aparecen enmascarados (p. ej., +212 6** *** **7) para que puedas ver el país y el operador antes de comprometerte. Opcionalmente, filtra por prefijo de país.

Parámetros

Nombre	Tipo	Obligatorio	Descripción
country	number	opcional	Prefijo de país UIT (p. ej., 212). Omítelo o usa 0 para cualquier país.

Respuestas

200 OKJSON con la lista de números disponibles y el recuento total

401 UnauthorizedClave API no válida o ausente

429 Too Many RequestsLímite de solicitudes superado (30 solicitudes/min)

Ejemplo de solicitud

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/v1/numbers/available?country=212

Ejemplo de respuesta

{
  "available": [
    {
      "phoneId":      "clx...",
      "maskedNumber": "+212 6** *** **7",
      "countryCode":  212,
      "country":      "Morocco",
      "carrier":      "Orange",
      "pricing": { "daily": null, "weekly": 2.50, "monthly": 8.00 }
    }
  ],
  "total": 1
}

POST/api/v1/numbers/rent

Alquila un número por tu cuenta. Descuenta el saldo y crea un alquiler exclusivo en una sola operación atómica. Si tiene éxito, devuelve el número de teléfono completo (sin enmascarar).

Parámetros

Nombre	Tipo	Obligatorio	Descripción
phoneId	string	obligatorio	ID del puerto obtenido de /api/v1/numbers/available
billingCycle	string	obligatorio	DAILY \| WEEKLY \| MONTHLY
cycles	number	opcional	Número de ciclos de facturación que se pagan por adelantado (1–12, 1 por defecto)
autoRenew	boolean	opcional	Renovación automática al vencer (false por defecto)

Respuestas

200 OKAlquiler creado: número de teléfono completo en la respuesta

402 Payment RequiredSaldo insuficiente o no hay precio configurado para ese ciclo

409 ConflictOtro partner acaba de alquilar el número; vuelve a intentarlo con otro número

401 UnauthorizedClave API no válida o ausente

Ejemplo de solicitud

curl -X POST -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"phoneId":"clx...","billingCycle":"MONTHLY","cycles":1}' \
  https://www.kartesim.com/api/v1/numbers/rent

Ejemplo de respuesta

{
  "rentalId":     "cly...",
  "phoneNumber":  "+212661234567",
  "countryCode":  212,
  "carrier":      "Orange",
  "billingCycle": "MONTHLY",
  "pricePerCycle": 8.00,
  "cycles":        1,
  "totalCharged":  8.00,
  "autoRenew":     false,
  "startedAt":    "2026-06-21T20:00:00.000Z",
  "expiresAt":    "2026-07-21T20:00:00.000Z"
}

GET/api/partner/rentals

Obtiene todos los alquileres de números activos de tu cuenta.

Respuestas

200 OKArray JSON de alquileres de números activos

401 UnauthorizedClave API no válida o ausente

Ejemplo de solicitud

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/partner/rentals

Ejemplo de respuesta

[
  {
    "id": "cuid...",
    "phoneNumber": "+212661234567",
    "maskedNumber": "+212 6** *** **7",
    "countryCode": 212,
    "expiresAt": "2026-06-25T10:00:00.000Z",
    "daysRemaining": 26
  }
]

Los números son exclusivos de tu cuenta. El número nunca se comparte ni se reasigna durante tu periodo de alquiler. El saldo necesario para todo el periodo se cobra en el momento del alquiler. Si otro partner se queda con un número que solicitaste entre la consulta y el alquiler, recibirás un 409; vuelve a intentarlo con otro número.

Alquiler de proxies

Cada puerto de la flota expone un proxy HTTP y SOCKS5 sobre su conexión de datos móviles. Los partners pueden enrutar el tráfico a través de estos proxies para obtener una IP móvil real de un país concreto.

Protocolo	Puerto predeterminado	Notas
HTTP	depende del dispositivo	Proxy HTTP CONNECT; el puerto aparece en el portal de partners y en `/api/partner/proxies`
SOCKS5	1080	Proxy SOCKS5; admite túneles TCP y UDP

Proxy HTTP — curl

curl --proxy http://USER:PASS@PHONE_IP:8888 https://api.ipify.org

Proxy SOCKS5 — curl

curl --proxy socks5://USER:PASS@PHONE_IP:1080 https://api.ipify.org

Las credenciales y la IP del proxy te los facilita tu gestor de cuenta. La IP del puerto se actualiza automáticamente en cada heartbeat; el portal de partners siempre muestra la IP más reciente. El acceso al proxy requiere autenticación; las conexiones no autenticadas se rechazan.

Ver tus proxies activos

Tus suscripciones de proxy activas, con la IP actual, el puerto y la fecha de vencimiento, están visibles en el portal de partners, en Proxies. El campo IP se actualiza en directo a medida que el puerto comunica su dirección.

Países disponibles

Usa getCountries para obtener la lista actual. Prefijos de país habituales:

Código	País	Código	País
0	Cualquiera (asignación automática)	7	Russia
212	Marruecos	33	Francia
1	Estados Unidos	44	Reino Unido
49	Alemania	34	España
966	Arabia Saudí	971	Emiratos Árabes Unidos
20	Egipto	216	Túnez

Referencia de errores

Respuesta	Significado
BAD_KEY	Clave API no válida, revocada o ausente
BAD_ACTION	Acción desconocida o faltan parámetros obligatorios
TOO_MANY_REQUESTS	Límite de solicitudes superado: 120 solicitudes por minuto
NO_NUMBERS	No hay puertos en línea que coincidan con tu solicitud OTP
NO_BALANCE	Saldo insuficiente para crear una sesión OTP
STATUS_WAIT_CODE	OTP aún no recibido; sigue consultando
STATUS_OK:code	OTP recibido; el código numérico va después de los dos puntos
STATUS_CANCEL	La sesión ha caducado o se ha cancelado
ACCESS_NUMBER:id:num	Sesión OTP creada; a continuación van el ID de sesión y el número de teléfono
ACCESS_CANCEL	Sesión cancelada, saldo reembolsado
ACCESS_READY	Sesión reconocida / confirmada

Documentación para partners de kartesim. Para solicitar una clave API o consultas sobre alquileres, contacta con tu gestor de cuenta.