Documentação da API - Virtual SMS

Integre facilmente com nossa plataforma de números virtuais através de nossa API robusta e documentada.

Voltar ao início

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,
            "created_at": "2023-01-01 00:00:00",
            "updated_at": "2023-01-01 00:00:00"
        },
        {
            "id": 2,
            "id_servico": "whatsapp",
            "nome": "WhatsApp",
            "valor": "2.00",
            "valor_reativacao": "1.50",
            "is_verificacao": 1,
            "status": 1,
            "quant_sms": 1,
            "created_at": "2023-01-01 00:00:00",
            "updated_at": "2023-01-01 00:00:00"
        }
    ]
}

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.
↑