Documentação da API

Autenticação

Todas as requisições à API devem incluir sua chave de API como parâmetro GET ou POST. Sua chave de API identifica você para o sistema e deve ser mantida em segredo.

Atenção: Nunca compartilhe sua chave de API em locais públicos como repositórios GitHub, fóruns ou códigos client-side.

Como usar

Inclua sua chave de API como parâmetro na URL ou no corpo da requisição:

GET https://virtualsms.org/api-c/endpoint?api_key=SUA_CHAVE_API

ou

POST https://virtualsms.org/api-c/endpoint
Content-Type: application/x-www-form-urlencoded

api_key=SUA_CHAVE_API&outro_parametro=valor

POST Solicitar Número

Este endpoint permite solicitar um número virtual para uso com um serviço específico.

Endpoint

POST https://virtualsms.org/api-c/compra.php?api_key=SUA_CHAVE_API

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
api_key	string	Sim	Sua chave de API (pode ser enviada via GET ou POST)
service_id	string	Sim	ID do serviço para o qual deseja solicitar o número

Exemplo de Resposta

{
    "message": "Número reservado com sucesso.",
    "color": "green",
    "numero": "5511999999999",
    "porta_com": "12345",
    "id_numero": 11433,
    "iccid": "8931080112345678901",
    "operadora": "Vivo"
}

Exemplos de Código

<?php
$apiKey = 'SUA_API_KEY';
$serviceId = 'ID_DO_SERVIÇO';

$url = "https://virtualsms.org/api-c/compra.php?api_key=$apiKey";

$data = ['service_id' => $serviceId];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if (curl_errno($ch)) {
    echo "Erro na requisição: " . curl_error($ch);
} else {
    if ($httpCode === 200) {
        $responseData = json_decode($response, true);
        if (json_last_error() === JSON_ERROR_NONE) {
            print_r($responseData);
        } else {
            echo "Erro ao decodificar JSON: " . json_last_error_msg();
        }
    } else {
        echo "Erro HTTP: $httpCode\nResposta: $response";
    }
}
curl_close($ch);
?>

import requests

data = {
    'service_id': 'ID_DO_SERVIÇO'  # Parâmetro POST
}

api_key = 'SUA_API_KEY'  # Parâmetro GET
url = f'https://virtualsms.org/api-c/compra.php?api_key={api_key}'

response = requests.post(url, data=data)
try:
    print(response.json())  # Para exibir o JSON recebido
except Exception as e:
    print(f"Erro ao processar resposta: {e}")
    print(response.text)  # Exibir o conteúdo da resposta

const axios = require('axios');

const apiKey = 'SUA_API_KEY';
const serviceId = 'ID_DO_SERVICO';

const url = `https://virtualsms.org/api-c/compra.php?api_key=${apiKey}`;

axios.post(url, {
    service_id: serviceId
}, {
    headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    if (error.response) {
        console.error('Erro na resposta:', error.response.status, error.response.data);
    } else if (error.request) {
        console.error('Erro na requisição:', error.request);
    } else {
        console.error('Erro desconhecido:', error.message);
    }
});

POST Cancelar Número

Use este endpoint para cancelar um número que foi solicitado anteriormente e ainda não recebeu SMS.

Endpoint

POST https://virtualsms.org/api-c/cancelar.php

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
api_key	string	Sim	Sua chave de API
id_compra	integer	Sim	ID da compra que deseja cancelar

Exemplo de Resposta

{
    "status": "success",
    "message": "Compra cancelada com sucesso, saldo atualizado."
}

Observação: Você só pode cancelar números que ainda não receberam SMS e que estão no status "pendente de sms".

Exemplos de Código

<?php
$url = "https://virtualsms.org/api-c/cancelar.php";
$apiKey = "SUA_API_KEY";
$idCompra = 11433;

$data = [
    'api_key' => $apiKey,
    'id_compra' => $idCompra
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

if (curl_errno($ch)) {
    echo "Erro na requisição: " . curl_error($ch);
} else {
    $httpStatus = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if ($httpStatus === 200) {
        $responseData = json_decode($response, true);
        if (json_last_error() === JSON_ERROR_NONE) {
            echo "Resposta da API: " . print_r($responseData, true);
        } else {
            echo "Erro ao decodificar JSON: " . json_last_error_msg();
            echo "Resposta bruta: " . $response;
        }
    } else {
        echo "Erro na resposta. Código de status: $httpStatus\nResposta: $response";
    }
}
curl_close($ch);
?>

import requests

url = "https://virtualsms.org/api-c/cancelar.php"
api_key = "SUA_API_KEY"
id_compra = 12345

data = {
    'api_key': api_key,
    'id_compra': id_compra
}

try:
    response = requests.post(url, data=data)
    if response.status_code == 200:
        response_json = response.json()
        print("Resposta da API:", response_json)
    else:
        print(f"Erro ao conectar à API. Código de status: {response.status_code}")
        print("Resposta:", response.text)
except requests.exceptions.RequestException as e:
    print(f"Erro ao conectar: {e}")

const axios = require('axios');

const url = "https://virtualsms.org/api-c/cancelar.php";
const apiKey = "SUA_API_KEY";
const idCompra = 11433;

axios.post(url, {
    api_key: apiKey,
    id_compra: idCompra
})
.then(response => {
    console.log("Resposta da API:", response.data);
})
.catch(error => {
    if (error.response) {
        console.error("Erro na resposta:", error.response.status, error.response.data);
    } else {
        console.error("Erro na requisição:", error.message);
    }
});

POST Solicitar Código

Use este endpoint para verificar se já foi recebido um código SMS para o número solicitado.

Endpoint

POST https://virtualsms.org/api-c/verificar_codigo.php

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
api_key	string	Sim	Sua chave de API
id_compra	integer	Sim	ID da compra que deseja verificar

Exemplo de Resposta

{
    "status": "success",
    "message": {
        "codigo": "123456"
    }
}

Dica: Recomendamos implementar um polling com intervalo de 5-10 segundos para verificar se o código foi recebido.

Exemplos de Código

<?php
$url = "https://virtualsms.org/api-c/verificar_codigo.php";
$apiKey = "SUA_API_KEY";
$idCompra = 12345;

$data = [
    'api_key' => $apiKey,
    'id_compra' => $idCompra
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$http_status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($http_status === 200) {
    $response_json = json_decode($response, true);
    echo "Resposta da API: ";
    print_r($response_json);
    file_put_contents("log.txt", "Resposta da API: " . print_r($response_json, true) . PHP_EOL, FILE_APPEND);
} else {
    echo "Erro ao conectar à API. Código de status: $http_status\n";
    echo "Resposta: $response";
}
?>

import requests

url = "https://virtualsms.org/api-c/verificar_codigo.php"
api_key = "SUA_API_KEY"
id_compra = 12345

data = {
    'api_key': api_key,
    'id_compra': id_compra
}

try:
    response = requests.post(url, data=data)
    if response.status_code == 200:
        response_json = response.json()
        print("Resposta da API:", response_json)
        with open("log.txt", "a") as log_file:
            log_file.write(f"Resposta da API: {response_json}\n")
    else:
        print(f"Erro ao conectar à API. Código de status: {response.status_code}")
        print("Resposta:", response.text)
except requests.exceptions.RequestException as e:
    print(f"Erro ao conectar: {e}")

const axios = require('axios');
const fs = require('fs');

const url = "https://virtualsms.org/api-c/verificar_codigo.php";
const apiKey = "SUA_API_KEY";
const idCompra = 12345;

const data = {
    api_key: apiKey,
    id_compra: idCompra
};

axios.post(url, data)
    .then(response => {
        console.log("Resposta da API:", response.data);
        fs.appendFileSync("log.txt", `Resposta da API: ${JSON.stringify(response.data)}\n`, 'utf8');
    })
    .catch(error => {
        if (error.response) {
            console.error(`Erro ao conectar à API. Código de status: ${error.response.status}`);
            console.error("Resposta:", error.response.data);
        } else {
            console.error("Erro na requisição:", error.message);
        }
    });

POST Solicitar Novo SMS

Use este endpoint para solicitar um novo SMS para um número já comprado, quando o serviço permite múltiplas mensagens.

Endpoint

POST https://virtualsms.org/api-c/novo_sms.php

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
api_key	string	Sim	Sua chave de API
id_compra	integer	Sim	ID da compra que deseja solicitar novo SMS

Exemplo de Resposta

{
    "status": "success",
    "message": "Código resetado e quant_sms incrementado com sucesso!"
}

Observação: Este endpoint só funciona para serviços que permitem múltiplos SMS. Verifique as características do serviço antes de usar.

Exemplos de Código

<?php
$url = "https://virtualsms.org/api-c/novo_sms.php";
$apiKey = "SUA_API_KEY";
$idCompra = 12345;

$data = [
    'api_key' => $apiKey,
    'id_compra' => $idCompra
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$http_status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($http_status === 200) {
    $responseData = json_decode($response, true);
    echo "Resposta da API: ";
    print_r($responseData);
} else {
    echo "Erro ao conectar à API. Código de status: $http_status\n";
    echo "Resposta: $response";
}
?>

import requests

url = "https://virtualsms.org/api-c/novo_sms.php"
api_key = "SUA_API_KEY"
id_compra = 12345

data = {
    'api_key': api_key,
    'id_compra': id_compra
}

try:
    response = requests.post(url, data=data)
    if response.status_code == 200:
        print("Resposta da API:", response.json())
    else:
        print(f"Erro ao conectar à API. Código de status: {response.status_code}")
        print("Resposta:", response.text)
except requests.exceptions.RequestException as e:
    print(f"Erro ao conectar: {e}")

const axios = require('axios');

const url = "https://virtualsms.org/api-c/novo_sms.php";
const apiKey = "SUA_API_KEY";
const idCompra = 12345;

axios.post(url, {
    api_key: apiKey,
    id_compra: idCompra
})
.then(response => {
    console.log("Resposta da API:", response.data);
})
.catch(error => {
    if (error.response) {
        console.error(`Erro ao conectar à API. Código de status: ${error.response.status}`);
        console.error("Resposta:", error.response.data);
    } else {
        console.error("Erro na requisição:", error.message);
    }
});

POST Reativar Número

Use este endpoint para reativar um número que foi utilizado anteriormente para o mesmo serviço.

Endpoint

POST https://virtualsms.org/api-c/reativar.php?api_key=SUA_CHAVE_API

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
api_key	string	Sim	Sua chave de API (pode ser enviada via GET ou POST)
numero	string	Sim	Número que deseja reativar
id_servico	string	Sim	ID do serviço para o qual deseja reativar o número

Exemplo de Resposta

{
    "error": false,
    "message": "Número reativado com sucesso!"
}

Observação: O valor da reativação pode ser diferente do valor original do serviço. Verifique o valor atual na listagem de serviços.

Exemplos de Código

<?php
$apiKey = "SUA_CHAVE_API_AQUI";
$numero = "NUMERO_A_REATIVAR";
$idServico = "ID_DO_SERVICO";

$url = "https://virtualsms.org/api-c/reativar.php?api_key=" . urlencode($apiKey);

$data = [
    'numero' => $numero,
    'id_servico' => $idServico
];

$options = [
    'http' => [
        'header'  => "Content-type: application/x-www-form-urlencoded\r\n",
        'method'  => 'POST',
        'content' => http_build_query($data),
    ],
];

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);

if ($result === FALSE) {
    echo "Erro ao chamar a API.";
} else {
    $response = json_decode($result, true);
    print_r($response);
}
?>

import requests

api_key = "SUA_CHAVE_API_AQUI"
numero = "NUMERO_A_REATIVAR"
id_servico = "ID_DO_SERVICO"

url = f"https://virtualsms.org/api-c/reativar.php?api_key={requests.utils.quote(api_key)}"

data = {
    'numero': numero,
    'id_servico': id_servico
}

response = requests.post(url, data=data)

if response.status_code == 200:
    print(response.json())
else:
    print("Erro ao chamar a API:", response.text)

const axios = require('axios');

const apiKey = "SUA_CHAVE_API_AQUI";
const numero = "NUMERO_A_REATIVAR";
const idServico = "ID_DO_SERVICO";

const url = `https://virtualsms.org/api-c/reativar.php?api_key=${encodeURIComponent(apiKey)}`;

axios.post(url, {
    numero: numero,
    id_servico: idServico
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error("Erro ao chamar a API:", error.response ? error.response.data : error.message);
});

POST Listar Serviços

Este endpoint retorna a lista completa de serviços disponíveis na plataforma com seus respectivos detalhes.

Endpoint

POST https://virtualsms.org/api-c/servicos.php

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
api_key	string	Sim	Sua chave de API

Exemplo de Resposta

{
    "status": "success",
    "message": "Serviços recuperados com sucesso.",
    "data": [
        {
            "id": 1,
            "id_servico": "twitter",
            "nome": "Twitter",
            "valor": "1.50",
            "valor_reativacao": "1.00",
            "is_verificacao": 0,
            "status": 1,
            "quant_sms": 1,
            "estoque": 150,
            "is_servico_bancario_exclusivo": 0,
            "link_imagem": "/img/twitter.png"
        },
        {
            "id": 2,
            "id_servico": "whatsapp",
            "nome": "WhatsApp",
            "valor": "2.00",
            "valor_reativacao": "1.50",
            "is_verificacao": 1,
            "status": 1,
            "quant_sms": 1,
            "estoque": 200,
            "is_servico_bancario_exclusivo": 0,
            "link_imagem": "/img/whatsapp.png"
        }
    ]
}

Exemplos de Código

<?php
$url = "https://virtualsms.org/api-c/servicos.php";
$api_key = "SUA_CHAVE_API";

$data = array('api_key' => $api_key);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

if ($response === false) {
    echo 'Erro na requisição: ' . curl_error($ch);
} else {
    $responseData = json_decode($response, true);
    echo "Resposta da API: ";
    print_r($responseData);
}

curl_close($ch);
?>

import requests

url = 'https://virtualsms.org/api-c/servicos.php'
data = {'api_key': 'SUA_CHAVE_API'}

response = requests.post(url, data=data)

if response.status_code == 200:
    try:
        response_data = response.json()
        print('Resposta da API:', response_data)
    except ValueError:
        print('Erro ao decodificar a resposta JSON:', response.text)
else:
    print(f'Erro na requisição. Código de status: {response.status_code}')

const axios = require('axios');

const url = 'https://virtualsms.org/api-c/servicos.php';
const data = { api_key: 'SUA_CHAVE_API' };

axios.post(url, data)
    .then(response => {
        console.log('Resposta da API:', response.data);
    })
    .catch(error => {
        console.error('Erro ao conectar à API:', error.response ? error.response.data : error.message);
    });

POST Verificar Status

Use este endpoint para verificar o status atual de um número (pendente, expirado, cancelado, etc.).

Endpoint

POST https://virtualsms.org/api-c/verificar_status.php

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
api_key	string	Sim	Sua chave de API
id_compra	integer	Sim	ID da compra que deseja verificar

Exemplo de Resposta

{
    "status": "success",
    "message": "Status da compra recuperado com sucesso.",
    "data": {
        "status": "pendente de sms"
    }
}

Possíveis Status

pendente de sms: Aguardando recebimento do código
finalizado: Código recebido com sucesso
cancelado: Número cancelado pelo usuário
expirado: Tempo esgotado para receber o código

Exemplos de Código

<?php
$url = "https://virtualsms.org/api-c/verificar_status.php";
$apiKey = "SUA_API_KEY";
$idCompra = 12345;

$data = [
    'api_key' => $apiKey,
    'id_compra' => $idCompra
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$http_status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($http_status === 200) {
    $responseData = json_decode($response, true);
    echo "Status do número: " . $responseData['data']['status'];
} else {
    echo "Erro ao verificar status: " . $response;
}
?>

import requests

url = "https://virtualsms.org/api-c/verificar_status.php"
api_key = "SUA_API_KEY"
id_compra = 12345

data = {
    'api_key': api_key,
    'id_compra': id_compra
}

try:
    response = requests.post(url, data=data)
    if response.status_code == 200:
        print("Status do número:", response.json()['data']['status'])
    else:
        print(f"Erro ao verificar status: {response.text}")
except requests.exceptions.RequestException as e:
    print(f"Erro na requisição: {e}")

const axios = require('axios');

const url = "https://virtualsms.org/api-c/verificar_status.php";
const apiKey = "SUA_API_KEY";
const idCompra = 12345;

axios.post(url, {
    api_key: apiKey,
    id_compra: idCompra
})
.then(response => {
    console.log("Status do número:", response.data.data.status);
})
.catch(error => {
    console.error("Erro ao verificar status:", error.response ? error.response.data : error.message);
});

Respostas da API

Todas as respostas da API são retornadas no formato JSON com uma estrutura consistente.

Estrutura Básica

{
    "status": "success" | "error",
    "message": "Mensagem descritiva do resultado",
    "data": { ... } // Dados adicionais quando aplicável
}

Códigos de Status HTTP

Código	Significado	Descrição
200	OK	Requisição bem-sucedida
400	Bad Request	Parâmetros inválidos ou faltando
401	Unauthorized	Chave de API inválida ou ausente
403	Forbidden	Acesso negado (usuário bloqueado, etc.)
404	Not Found	Recurso não encontrado
500	Internal Server Error	Erro no servidor

Tratamento de Erros

A API retorna mensagens de erro descritivas para ajudar na identificação e resolução de problemas.

Erros Comuns

Mensagem de Erro	Causa Provável	Solução
Chave de API inválida	Chave de API incorreta ou não fornecida	Verifique sua chave de API no painel administrativo
Saldo insuficiente	Saldo na conta é menor que o valor do serviço	Recarregue seu saldo
Serviço não encontrado	ID do serviço não existe ou está inativo	Verifique a lista de serviços disponíveis
Nenhum número disponível	Todos os números estão em uso para o serviço solicitado	Tente novamente mais tarde ou contate o suporte
Compra não encontrada	ID da compra não existe ou não pertence ao usuário	Verifique o histórico de compras

Importante: Sempre implemente tratamento de erros em seu código para lidar com respostas inesperadas da API.

Documentação da API - Virtual SMS

Autenticação

Como usar

POST Solicitar Número

Endpoint

Parâmetros

Exemplo de Resposta

Exemplos de Código

POST Cancelar Número

Endpoint

Parâmetros

Exemplo de Resposta

Exemplos de Código

POST Solicitar Código

Endpoint

Parâmetros

Exemplo de Resposta

Exemplos de Código

POST Solicitar Novo SMS

Endpoint

Parâmetros

Exemplo de Resposta

Exemplos de Código

POST Reativar Número

Endpoint

Parâmetros

Exemplo de Resposta

Exemplos de Código

POST Listar Serviços

Endpoint

Parâmetros

Exemplo de Resposta

Exemplos de Código

POST Verificar Status

Endpoint

Parâmetros

Exemplo de Resposta

Possíveis Status

Exemplos de Código

Respostas da API

Estrutura Básica

Códigos de Status HTTP

Tratamento de Erros

Erros Comuns