Documentación de la API

Descripción general

URL base

Todas las rutas siguientes usan esta URL base y devuelven JSON UTF-8.

https://master-sms.shop/api/v1

Inicio rápido

Crea una clave en el panel, guarda el secret solo en el servidor y realiza la primera consulta de saldo.

Gestionar claves

Usa el API Secret solo en el backend. Nunca pongas credenciales en el navegador, una aplicación distribuida o un repositorio público.

Autenticación

Envía ambas credenciales en cada ruta protegida.

Headers

Accept: application/json
Content-Type: application/json
X-API-Key: your_api_key
X-API-Secret: your_api_secret

Formato de respuesta

Los éxitos devuelven success=true y data. Los errores devuelven success=false, error y el estado HTTP correspondiente.

{
    "success": true,
    "data": {
        "example": "value"
    },
    "timestamp": 1785078000
}

{
    "success": false,
    "error": "Descripción del error",
    "code": 400
}

Referencia de endpoints

Las rutas documentadas corresponden al front controller público de la API v1.

GET /health Ruta pública

Estado de la API

Confirma que la API está operativa e informa su versión.

Ejemplo de respuesta

{
    "success": true,
    "data": {
        "version": "4.2.0",
        "status": "operational",
        "timestamp": 1785078000,
        "server_time": "2026-07-26 12:00:00",
        "request_id": "req_01K123EXAMPLE"
    },
    "timestamp": 1785078000
}

GET /balance Requiere autenticación

Consultar saldo

Devuelve saldo total, bloqueado, disponible y moneda de la cuenta.

Ejemplo de respuesta

{
    "success": true,
    "data": {
        "balance": 1250.5,
        "blocked": 50,
        "available": 1200.5,
        "currency": "BRL",
        "limit": 0
    },
    "timestamp": 1785078000
}

GET /services Requiere autenticación

Listar servicios

Lista países, servicios, operadores, proveedores, precios calculados y stock.

Filtros opcionales

Parámetro	Tipo	Descripción	Ejemplo
`country`	string	Código numérico del país.	`73`
`service`	string	Código del servicio, por ejemplo wa.	`wa`
`operator`	string	Operador específico. También puede ser una lista aceptada por el proveedor.	`claro`
`available`	boolean	Cuando es true, devuelve solo elementos con stock.	`true`
`provider`	string	Nombre o identificador del proveedor.	`Hero SMS`
`search`	string	Búsqueda textual por servicio.	`WhatsApp`

Ejemplo de solicitud

GET https://master-sms.shop/api/v1/services?country=73&available=true

Ejemplo de respuesta

{
    "success": true,
    "data": [
        {
            "country_id": "73",
            "country_name": "Brasil",
            "services": [
                {
                    "code": "wa",
                    "name": "WhatsApp",
                    "operator": "claro",
                    "price": 2.5,
                    "stock": 150,
                    "provider": "Hero SMS",
                    "category": "messenger",
                    "markup": 10
                }
            ]
        }
    ],
    "timestamp": 1785078000
}

POST /buy Requiere autenticación

Comprar número

Compra un número virtual y crea una activación SMS.

Cuerpo JSON

Campo	Tipo	Obligatorio	Descripción
`service`	string	Sí	Código del servicio, por ejemplo wa.
`country`	string	Sí	Código numérico del país.
`request_id`	string	Sí	Identificador único del intento de compra para evitar duplicados.
`operator`	string	No	Operador específico. También puede ser una lista aceptada por el proveedor.
`provider`	string	No	Nombre o identificador del proveedor.
`max_price`	number	No	Precio máximo aceptado en la moneda devuelta por la API.

request_id: Genera un request_id nuevo por intención de compra y reutiliza el mismo valor solo al repetir esa intención tras un fallo de red.

max_price: La compra falla antes del cobro si el precio calculado supera max_price.

Ejemplo de solicitud

{
    "service": "wa",
    "country": "73",
    "operator": "claro",
    "provider": "Hero SMS",
    "max_price": 5,
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Ejemplo de respuesta

{
    "success": true,
    "data": {
        "activation_id": "ACT17850780001234",
        "phone": "5511999999999",
        "operator": "claro",
        "price": 2.5,
        "currency": "BRL",
        "request_id": "550e8400-e29b-41d4-a716-446655440000",
        "service_name": "WhatsApp"
    },
    "timestamp": 1785078000
}

GET /status?activation_id={id} Requiere autenticación

Consultar activación

Actualiza y devuelve estado, número y código SMS de una activación.

Parámetro	Obligatorio	Descripción
`activation_id`	Sí	ID devuelto por la compra.

Estados posibles

Status	Descripción
`pending`	Esperando SMS.
`received`	SMS recibido; code contiene el código.
`canceled`	Activación cancelada.
`expired`	Activación expirada.

Ejemplo de respuesta

{
    "success": true,
    "data": {
        "activation_id": "ACT17850780001234",
        "status": "received",
        "phone": "5511999999999",
        "created_at": 1785078000,
        "code": "123456",
        "received_at": 1785078060
    },
    "timestamp": 1785078060
}

POST /cancel Requiere autenticación

Cancelar activación

Cancela una activación elegible e informa el reembolso.

La cancelación depende del tiempo mínimo, estado de activación y reglas del proveedor. No se puede cancelar si ya llegó un SMS.

Cuerpo JSON

{ "activation_id": "ACT17850780001234" }

Ejemplo de respuesta

{
    "success": true,
    "data": {
        "activation_id": "ACT17850780001234",
        "status": "canceled",
        "refunded": true,
        "refund_amount": 2.5
    },
    "timestamp": 1785078300
}

POST GET DELETE /webhook Requiere autenticación

Webhooks

Registra, lista y elimina destinos para eventos asíncronos.

Eventos disponibles

Evento	Descripción
`sms.received`	SMS recibido.
`sms.purchased`	Número comprado.
`sms.status`	Estado de activación modificado.
`balance.low`	Saldo por debajo del límite configurado.

POST /webhook · Cuerpo JSON

Campo	Obligatorio	Descripción
`event`	Sí	Nombre del evento firmado.
`url`	Sí	URL HTTPS pública que recibirá un POST JSON.
`secret`	No	Secret usado para generar la firma HMAC SHA-256.

{
    "event": "sms.received",
    "url": "https://example.com/webhooks/master-sms",
    "secret": "replace_with_a_random_secret"
}

GET /webhook

La lista nunca devuelve el secret almacenado.

DELETE /webhook · Cuerpo JSON

{ "webhook_id": 1 }

Payload enviado por el webhook

{
    "event": "sms.received",
    "timestamp": 1785078060,
    "data": {
        "activation_id": "ACT17850780001234",
        "code": "123456",
        "phone": "5511999999999",
        "service": "wa",
        "received_at": 1785078060
    },
    "signature": "legacy_body_signature"
}

GET /stats Requiere autenticación

Estadísticas

Devuelve totales de compras, SMS recibidos, cancelaciones, gastos y reembolsos.

{
    "success": true,
    "data": {
        "total_compras": 42,
        "total_recebidos": 31,
        "total_cancelados": 11,
        "total_gasto": 79.5,
        "total_estornado": 21
    },
    "timestamp": 1785078000
}

GET /commissions Requiere autenticación

Comisiones

Devuelve comisiones pendientes, pagadas y el historial del revendedor autenticado.

{
    "success": true,
    "data": {
        "pending_total": 15.3,
        "paid_total": 120,
        "commissions": []
    },
    "timestamp": 1785078000
}

Seguridad de webhooks

El cuerpo bruto se firma con HMAC SHA-256. Compara X-Webhook-Signature en tiempo constante antes de procesar JSON.

Responde rápidamente con HTTP 2xx. La cola reintenta los envíos fallidos con esperas progresivas.

$rawBody = file_get_contents('php://input');
$received = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $rawBody, getenv('MASTER_SMS_WEBHOOK_SECRET'));

if ($received === '' || !hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}

$event = json_decode($rawBody, true, flags: JSON_THROW_ON_ERROR);
http_response_code(204);

Ejemplos de integración

Clientes mínimos para backend. Adapta timeouts, logs y almacenamiento de secrets a tu entorno.

<?php
final class MasterSmsClient
{
    public function __construct(
        private string $apiKey,
        private string $apiSecret,
        private string $baseUrl = 'https://master-sms.shop/api/v1'
    ) {}

    public function request(string $method, string $path, ?array $body = null): array
    {
        $ch = curl_init(rtrim($this->baseUrl, '/') . $path);
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CUSTOMREQUEST => $method,
            CURLOPT_TIMEOUT => 30,
            CURLOPT_HTTPHEADER => [
                'Accept: application/json',
                'Content-Type: application/json',
                'X-API-Key: ' . $this->apiKey,
                'X-API-Secret: ' . $this->apiSecret,
            ],
            CURLOPT_POSTFIELDS => $body === null ? null : json_encode($body),
        ]);
        $raw = curl_exec($ch);
        $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        if ($raw === false) {
            throw new RuntimeException(curl_error($ch));
        }
        curl_close($ch);
        $result = json_decode($raw, true, flags: JSON_THROW_ON_ERROR);
        if ($status < 200 || $status >= 300 || empty($result['success'])) {
            throw new RuntimeException($result['error'] ?? "HTTP {$status}", $status);
        }
        return $result['data'] ?? [];
    }
}

$client = new MasterSmsClient(
    getenv('MASTER_SMS_API_KEY'),
    getenv('MASTER_SMS_API_SECRET')
);
$balance = $client->request('GET', '/balance');
$services = $client->request('GET', '/services?country=73&available=true');
$purchase = $client->request('POST', '/buy', [
    'service' => 'wa',
    'country' => '73',
    'request_id' => bin2hex(random_bytes(16)),
]);

import os
import uuid
import requests

class MasterSmsClient:
    def __init__(self):
        self.base_url = "https://master-sms.shop/api/v1"
        self.session = requests.Session()
        self.session.headers.update({
            "Accept": "application/json",
            "Content-Type": "application/json",
            "X-API-Key": os.environ["MASTER_SMS_API_KEY"],
            "X-API-Secret": os.environ["MASTER_SMS_API_SECRET"],
        })

    def request(self, method, path, *, params=None, json=None):
        response = self.session.request(
            method, self.base_url + path, params=params, json=json, timeout=30
        )
        payload = response.json()
        if not response.ok or not payload.get("success"):
            raise RuntimeError(payload.get("error", f"HTTP {response.status_code}"))
        return payload.get("data", {})

client = MasterSmsClient()
balance = client.request("GET", "/balance")
services = client.request("GET", "/services", params={
    "country": "73", "available": "true"
})
purchase = client.request("POST", "/buy", json={
    "service": "wa",
    "country": "73",
    "request_id": str(uuid.uuid4()),
})

import crypto from "node:crypto";

const baseUrl = "https://master-sms.shop/api/v1";
const headers = {
  Accept: "application/json",
  "Content-Type": "application/json",
  "X-API-Key": process.env.MASTER_SMS_API_KEY,
  "X-API-Secret": process.env.MASTER_SMS_API_SECRET,
};

async function request(method, path, body) {
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), 30_000);
  try {
    const response = await fetch(baseUrl + path, {
      method,
      headers,
      body: body ? JSON.stringify(body) : undefined,
      signal: controller.signal,
    });
    const payload = await response.json();
    if (!response.ok || !payload.success) {
      throw new Error(payload.error ?? `HTTP ${response.status}`);
    }
    return payload.data ?? {};
  } finally {
    clearTimeout(timeout);
  }
}

const balance = await request("GET", "/balance");
const purchase = await request("POST", "/buy", {
  service: "wa",
  country: "73",
  request_id: crypto.randomUUID(),
});

export MASTER_SMS_API_KEY="your_api_key"
export MASTER_SMS_API_SECRET="your_api_secret"
export MASTER_SMS_BASE_URL="https://master-sms.shop/api/v1"

curl --fail-with-body --silent --show-error \
  "$MASTER_SMS_BASE_URL/balance" \
  -H "Accept: application/json" \
  -H "X-API-Key: $MASTER_SMS_API_KEY" \
  -H "X-API-Secret: $MASTER_SMS_API_SECRET"

curl --fail-with-body --silent --show-error \
  "$MASTER_SMS_BASE_URL/buy" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $MASTER_SMS_API_KEY" \
  -H "X-API-Secret: $MASTER_SMS_API_SECRET" \
  --data '{"service":"wa","country":"73","request_id":"550e8400-e29b-41d4-a716-446655440000"}'

Prompt de integración con IA

Copia este prompt, indica tu stack y envíalo a una IA de programación. Sustituye solo los placeholders; nunca pegues tu API Secret.

Stack deseada

Eres una persona ingeniera de software sénior. Implementa una integración de producción con la API Master SMS usando esta stack: [ej.: Laravel, Node.js, Django, Flutter con backend].

Contrato obligatorio:
- URL base: https://master-sms.shop/api/v1
- Autenticación solo en el backend mediante X-API-Key y X-API-Secret.
- Las credenciales deben venir de variables de entorno y nunca aparecer en logs, frontend, aplicaciones distribuidas o control de código.
- Todas las respuestas son JSON. Trata success, data, error, estado HTTP y timeouts.

Implementa:
1. Cliente reutilizable con timeout, reintentos solo para operaciones seguras, logs sanitizados y errores tipados.
2. GET /balance.
3. GET /services con filtros country, service, operator, available, provider y search.
4. POST /buy con service, country y request_id obligatorios; operator, provider y max_price opcionales. Genera request_id como UUID y consérvalo al repetir la misma intención tras un timeout.
5. GET /status?activation_id=... con polling limitado y backoff.
6. POST /cancel con activation_id.
7. POST, GET y DELETE /webhook.
8. GET /stats y GET /commissions.
9. Receptor de webhook que lea el cuerpo bruto y valide X-Webhook-Signature con HMAC SHA-256 y comparación en tiempo constante antes de procesar JSON.

Calidad:
- No inventes endpoints ni campos.
- Nunca llames la API directamente desde navegador o app móvil con el Secret.
- No repitas POST /buy con otro request_id tras una respuesta incierta.
- Trata HTTP 400, 401, 402, 403, 404, 405, 409, 429 y 500.
- Usa backoff exponencial con jitter para 429 y fallos transitorios.
- Valida inputs y normaliza URLs.
- Incluye tests unitarios, tests de integración con mocks, .env.example sin secretos, README y ejemplo de uso.
- Entrega archivos completos, explica credenciales y enumera decisiones de seguridad.

Antes del código, muestra una lista corta de archivos. Después implementa todo sin TODOs.

Errores y tratamiento

Código	Significado	Tratamiento recomendado
`400`	Solicitud inválida	Corrige JSON, campos obligatorios o reglas.
`401`	No autenticado	Comprueba X-API-Key y X-API-Secret.
`402`	Saldo insuficiente	Recarga la cuenta antes de comprar.
`403`	Sin permiso	Activa el permiso o revisa la lista blanca de IP.
`404`	No encontrado	Revisa ruta, servicio, stock o activation_id.
`405`	Método inválido	Usa el método HTTP documentado.
`409`	Conflicto de idempotencia	No reutilices request_id para otra compra.
`429`	Límite excedido	Espera y reintenta con backoff.
`500`	Error interno	Registra request_id y reintenta sin duplicar la compra.

Rate limit

El límite por minuto depende de la clave y aparece en X-RateLimit-Limit. Ante HTTP 429, usa backoff exponencial con jitter.

Lista de seguridad

Guarda API Key y Secret en variables de entorno o un almacén de secretos.
Llama la API solo desde el backend; apps y navegadores deben llamar a tu servidor.
Usa HTTPS, timeout, logs sin credenciales y validación estricta de JSON.
Usa request_id idempotente y no repitas una compra con otro identificador tras un timeout.
Valida la firma del webhook sobre el cuerpo bruto antes de modificar saldo o estado.

Master sms API

Descripción general

URL base

Inicio rápido

Autenticación

Headers

Formato de respuesta

Referencia de endpoints

Estado de la API

Ejemplo de respuesta

Consultar saldo

Ejemplo de respuesta

Listar servicios

Filtros opcionales

Ejemplo de solicitud

Ejemplo de respuesta

Comprar número

Cuerpo JSON

Ejemplo de solicitud

Ejemplo de respuesta

Consultar activación

Estados posibles

Ejemplo de respuesta

Cancelar activación

Cuerpo JSON

Ejemplo de respuesta

Webhooks

Eventos disponibles

POST /webhook · Cuerpo JSON

GET /webhook

DELETE /webhook · Cuerpo JSON

Payload enviado por el webhook

Estadísticas

Comisiones

Seguridad de webhooks

Ejemplos de integración

Prompt de integración con IA

Errores y tratamiento

Rate limit

Lista de seguridad