API Documentation - Master sms

Overview

Base URL

All routes below use this base URL and return UTF-8 JSON.

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

Quick start

Create a key in the dashboard, keep the secret server-side only, and make your first balance request.

Manage keys

Use the API Secret only on the backend. Never place credentials in a browser, distributed application, or public repository.

Authentication

Send both credentials on every protected route.

Headers

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

Response format

Success responses return success=true and data. Errors return success=false, error, and the corresponding HTTP status.

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

{
    "success": false,
    "error": "Error description",
    "code": 400
}

Endpoint reference

The routes documented below match the public API v1 front controller.

GET /health Public route

API health

Confirms that the API is operational and returns its version.

Response example

{
    "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 Authentication required

Get balance

Returns the account total, blocked and available balance, plus currency.

Response example

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

GET /services Authentication required

List services

Lists countries, services, operators, providers, calculated prices, and stock.

Optional filters

Parameter	Type	Description	Example
`country`	string	Numeric country code.	`73`
`service`	string	Service code, for example wa.	`wa`
`operator`	string	Specific operator. It may also be a provider-supported list.	`claro`
`available`	boolean	When true, returns only items in stock.	`true`
`provider`	string	Provider name or identifier.	`Hero SMS`
`search`	string	Text search by service.	`WhatsApp`

Request example

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

Response example

{
    "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 Authentication required

Buy number

Purchases a virtual number and creates an SMS activation.

JSON body

Field	Type	Required	Description
`service`	string	Yes	Service code, for example wa.
`country`	string	Yes	Numeric country code.
`request_id`	string	Yes	Unique purchase-attempt identifier used to prevent duplicates.
`operator`	string	No	Specific operator. It may also be a provider-supported list.
`provider`	string	No	Provider name or identifier.
`max_price`	number	No	Maximum accepted price in the currency returned by the API.

request_id: Generate a new request_id per purchase intent and reuse the same value only when retrying that same intent after a network failure.

max_price: The purchase fails before charging when the calculated price exceeds max_price.

Request example

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

Response example

{
    "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} Authentication required

Get activation

Refreshes and returns an activation status, number, and SMS code.

Parameter	Required	Description
`activation_id`	Yes	ID returned by the purchase.

Possible statuses

Status	Description
`pending`	Waiting for SMS.
`received`	SMS received; code contains the code.
`canceled`	Activation canceled.
`expired`	Activation expired.

Response example

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

POST /cancel Authentication required

Cancel activation

Cancels an eligible activation and reports the refund.

Cancellation depends on minimum time, activation status, and provider rules. Activations that have received an SMS cannot be canceled.

JSON body

{ "activation_id": "ACT17850780001234" }

Response example

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

POST GET DELETE /webhook Authentication required

Webhooks

Registers, lists, and removes destinations for asynchronous events.

Available events

Event	Description
`sms.received`	SMS received.
`sms.purchased`	Number purchased.
`sms.status`	Activation status changed.
`balance.low`	Balance below the configured threshold.

POST /webhook · JSON body

Field	Required	Description
`event`	Yes	Signed event name.
`url`	Yes	Public HTTPS URL that receives a JSON POST.
`secret`	No	Secret used to create the HMAC SHA-256 signature.

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

GET /webhook

The list response never returns the stored secret.

DELETE /webhook · JSON body

{ "webhook_id": 1 }

Webhook payload

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

GET /stats Authentication required

Statistics

Returns the user totals for purchases, received messages, cancellations, spending, and refunds.

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

GET /commissions Authentication required

Commissions

Returns pending and paid commissions plus the authenticated reseller history.

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

Webhook security

The raw body is signed with HMAC SHA-256. Compare X-Webhook-Signature in constant time before processing JSON.

Return HTTP 2xx quickly. Failed deliveries are retried by the queue with progressive delays.

$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);

Integration examples

Minimal backend clients. Adapt timeouts, logging, and secret storage to your environment.

<?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"}'

AI integration prompt

Copy this prompt, provide your stack, and send it to a coding AI. Replace only placeholders; never paste your API Secret into the conversation.

Target stack

You are a senior software engineer. Implement a production-grade integration with the Master SMS API using this stack: [e.g. Laravel, Node.js, Django, Flutter with a backend].

Required contract:
- Base URL: https://master-sms.shop/api/v1
- Authenticate only on the backend with X-API-Key and X-API-Secret headers.
- Credentials must come from environment variables and must never appear in logs, frontend code, distributed applications, or source control.
- Every response is JSON. Handle success, data, error, HTTP status, and timeouts.

Implement:
1. A reusable client with timeouts, retries only for safe operations, sanitized logging, and typed errors.
2. GET /balance.
3. GET /services with country, service, operator, available, provider, and search filters.
4. POST /buy with required service, country, and request_id; optional operator, provider, and max_price. Generate request_id as a UUID and preserve it when retrying the same intent after a timeout.
5. GET /status?activation_id=... with bounded polling and backoff.
6. POST /cancel with activation_id.
7. POST, GET, and DELETE /webhook.
8. GET /stats and GET /commissions.
9. A webhook receiver that reads the raw body and validates X-Webhook-Signature using HMAC SHA-256 and constant-time comparison before processing JSON.

Quality requirements:
- Do not invent endpoints or fields.
- Never call the API directly from a browser or mobile app with the Secret.
- Never retry POST /buy with a different request_id after an uncertain response.
- Handle HTTP 400, 401, 402, 403, 404, 405, 409, 429, and 500.
- Use exponential backoff with jitter for 429 and transient failures.
- Validate all inputs and normalize URLs.
- Include unit tests, mocked integration tests, a secret-free .env.example, setup README, and usage example.
- Deliver complete files, explain credential configuration, and list security decisions.

Before writing code, show a short list of files you will create. Then implement everything without TODOs.

Errors and handling

Code	Meaning	Recommended handling
`400`	Bad request	Fix JSON, required fields, or operation rules.
`401`	Unauthenticated	Check X-API-Key and X-API-Secret.
`402`	Insufficient balance	Top up the account before purchasing.
`403`	Forbidden	Enable the key permission or check the IP whitelist.
`404`	Not found	Check the route, service, stock, or activation_id.
`405`	Invalid method	Use the documented HTTP method.
`409`	Idempotency conflict	Do not reuse request_id for another purchase.
`429`	Rate limit exceeded	Wait and retry with backoff.
`500`	Internal error	Record the request_id and retry without duplicating the purchase.

Rate limit

The per-minute limit depends on the key and is returned in X-RateLimit-Limit. On HTTP 429, use exponential backoff with jitter.

Security checklist

Store the API Key and Secret in environment variables or a secret vault.
Call the API only from your backend; apps and browsers should call your own server.
Use HTTPS, timeouts, credential-free logs, and strict JSON validation.
Use an idempotent request_id and never retry a timed-out purchase with a different identifier.
Validate the webhook signature over the raw body before changing balance or state.

Master sms API

Overview

Base URL

Quick start

Authentication

Headers

Response format

Endpoint reference

API health

Response example

Get balance

Response example

List services

Optional filters

Request example

Response example

Buy number

JSON body

Request example

Response example

Get activation

Possible statuses

Response example

Cancel activation

JSON body

Response example

Webhooks

Available events

POST /webhook · JSON body

GET /webhook

DELETE /webhook · JSON body

Webhook payload

Statistics

Commissions

Webhook security

Integration examples

AI integration prompt

Errors and handling

Rate limit

Security checklist