API DE IP ADICIONAL PARA REVENDA

Visão geral

A API de IP adicional é para revendas Cloud da Vitt Host. Com ela, o seu sistema pede um IPv4 adicional, recebe a cobrança (PIX ou crédito da conta) e, depois do pagamento, o IP entra sozinho na sua conta Cloud do Virtualizor, pronto para usar numa VPS. Cada IP é um serviço mensal: a API também mostra o vencimento, as faturas de renovação, a suspensão por atraso e avisa cada etapa por webhook.

• Pedido e entrega automáticos: paga a fatura, o IP é comprado, configurado e entregue sem intervenção.
• PIX na resposta: o pedido já volta com o copia e cola e o QR Code.
• Renovação: vencimento, valor e fatura em aberto em cada IP, com filtros para o que vence ou está em atraso.
• Renovação automática com crédito: adicione crédito por PIX e as renovações se pagam sozinhas.
• Webhooks assinados para pagamento, ativação, vencimento, suspensão e encerramento.

Início rápido

1. Confira a chave e veja o preço e o seu crédito:

curl -s https://vitthost.com.br/central/api_ips.php/v1/conta \
  -H "Authorization: Bearer $VITT_IP_KEY"

2. Peça um IP. O Idempotency-Key é um valor único seu para este pedido: se a rede cair, reenvie com o mesmo valor e você recebe o mesmo pedido, sem duplicar.

curl -s -X POST https://vitthost.com.br/central/api_ips.php/v1/ips \
  -H "Authorization: Bearer $VITT_IP_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-cliente-1234-001" \
  -d '{"referencia": "cliente-1234", "pagamento": "pix"}'

3. A resposta (201) traz o pedido com status: "aguardando_pagamento" e o objeto pix. Mostre o copia e cola ou o QR Code ao seu cliente.

4. Quando o PIX for pago, você recebe os webhooks ip.pago e depois ip.ativo. Sem webhook, consulte GET /v1/ips/{id} a cada poucos minutos até status: "ativo". O campo rede traz IP, máscara, gateway e MAC.

Endereço e autenticação

Todas as rotas ficam em:

https://vitthost.com.br/central/api_ips.php/v1/…

Se o seu cliente HTTP ou proxy não repassar o caminho depois do .php, use o parâmetro rota, que funciona igual: https://vitthost.com.br/central/api_ips.php?rota=/v1/ips. Só HTTPS.

A chave tem o formato vip_<prefixo>_<segredo> e vai em um destes cabeçalhos:

Authorization: Bearer vip_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# ou, se o seu servidor remove o Authorization:
X-Api-Key: vip_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

GET /v1 é público e responde {"api": "ips", "versao": 1, …}. Serve para testar se o endereço e a rota chegam até a API.

Convenções

• JSON em UTF-8 no corpo das requisições e respostas. Envie Content-Type: application/json nos POST.
• Valores em dinheiro são texto com duas casas e ponto: "17.00". Moeda em moeda (hoje, BRL).
• Datas e horas (campos *_em) são ISO 8601 em UTC: 2026-10-17T01:54:10Z.
• Datas de vencimento (vencimento, suspensao_prevista_em, encerramento_previsto_em) são só a data, AAAA-MM-DD, no horário de Brasília.
• Erros sempre no formato {"erro": {"codigo": "…", "mensagem": "…"}} com o status HTTP certo. Programe em cima do codigo, que é estável; a mensagem é para pessoas e pode mudar. Veja a lista.
• Listas vêm em {"dados": [...]}. GET /v1/ips também traz pagina, por_pagina e total.
• Limites: hoje, 60 requisições por minuto por chave (acima disso, 429 muitas_requisicoes com Retry-After) e um limite de pedidos por 24 horas, que aparece em GET /v1/conta.
• Idempotência: as rotas que criam cobrança (POST /v1/ips e POST /v1/credito) exigem o cabeçalho Idempotency-Key (1 a 100 caracteres: letras, números, _ - : .). Mesmo valor e mesmo corpo devolvem a mesma resposta (com Idempotent-Replayed: true) por 7 dias; mesmo valor com outro corpo dá 422 idempotencia_conflito. Respostas 5xx não ficam gravadas: repita com a mesma chave.

Ciclo de vida do IP

Rede do IP: sem vps_id, o IP vem com um MAC virtual próprio (rede.mac): use esse MAC na placa de rede da VPS que for receber o IP. Com vps_id, o IP entra no MAC da própria VPS (rede.mac_da_vps: true): basta adicionar o IP à VPS, sem trocar a placa de rede.

Renovação e vencimento

Cada IP ativo é cobrado por mês. Todo IP ativo ou suspenso traz o campo vencimento e o objeto renovacao:

1. Alguns dias antes do vencimento (hoje, 7) é gerada a fatura de renovação: webhook fatura.gerada, e ela aparece em renovacao.fatura_em_aberto.
2. Perto do vencimento (hoje, a partir de 3 dias antes): webhook fatura.vencendo.
3. Passou do vencimento sem pagamento: webhook fatura.vencida; renovacao.em_atraso fica true.
4. Na data de renovacao.suspensao_prevista_em, o IP é suspenso (ip.suspenso). Conforme a configuração da sua conta, a suspensão também bloqueia todo o tráfego de entrada do IP na rede (ip.bloqueado; campo bloqueio).
5. Um dia antes de renovacao.encerramento_previsto_em: webhook ip.encerramento_proximo, o último aviso.
6. Na data de encerramento, o IP é encerrado e devolvido ao data center (ip.cancelado). Isso não tem volta: o mesmo endereço não pode ser recuperado.

Pagar a fatura em qualquer ponto antes do encerramento resolve tudo: o IP volta a ativo (ip.reativado), o bloqueio sai (ip.desbloqueado) e o vencimento passa para o mês seguinte (fatura.paga). Pague pelo PIX (GET /v1/ips/{id}/pix) ou com crédito (POST /v1/faturas/{id}/pagar-com-credito).

Para montar a sua rotina de cobrança, use os filtros:

# IPs que vencem nos próximos 7 dias (ordenados pelo vencimento)
GET /v1/ips?vence_em_ate=7

# IPs com renovação em atraso
GET /v1/ips?em_atraso=1

# Faturas vencidas e não pagas
GET /v1/faturas?vencidas=1

Renovação automática com crédito

Com saldo de crédito na conta, as renovações dos IPs se pagam sozinhas:

1. Crie uma fatura de crédito com POST /v1/credito e pague o PIX que volta na resposta.
2. Quando o pagamento cai, o valor entra como crédito e, em até 5 minutos, quita as faturas de renovação de IP já em aberto, da que vence primeiro para a última (só as que o saldo cobre por inteiro). Você recebe credito.adicionado com a lista em faturas_pagas, e fatura.paga para cada uma.
3. As próximas faturas de renovação já nascem pagas com o crédito disponível.

O saldo atual está em GET /v1/credito e em GET /v1/conta.

Conta e locais

GET /v1/conta#

Dados da revenda, crédito, preço do IP e limites.

{
  "revenda": "Sua Empresa LTDA",
  "credito": "34.00",
  "moeda": "BRL",
  "preco_mensal_ip": "17.00",
  "pedidos_24h": 2,
  "limite_diario": 100,
  "webhook": "https://seu-sistema.com.br/webhooks/vitt",
  "validade_pedido_h": 24
}

GET /v1/locais#

Os locais (data centers) que vendem IP adicional. Use o codigo no campo local do pedido; sem local, vale o marcado como padrao.

{
  "dados": [
    { "codigo": "ca-1", "nome": "Canadá 1", "padrao": true }
  ]
}

IPs

POST /v1/ips#

Pede um IP adicional. Exige Idempotency-Key. Cria o pedido e a fatura e responde 201 com o pedido (com o PIX, se pagamento for pix) e o cabeçalho Location: /v1/ips/{id}.

{ "referencia": "cliente-1234-vps-88", "pagamento": "pix", "vps_id": 88 }

GET /v1/ips#

Lista os seus pedidos de IP, do mais novo para o mais antigo (com filtro de vencimento, do que vence primeiro).

{ "dados": [ { …pedido… } ], "pagina": 1, "por_pagina": 25, "total": 4 }

GET /v1/ips/{id}#

Um pedido. Se estiver aguardando pagamento por PIX, vem com o PIX.

GET /v1/ips/{id}/pix#

O PIX da fatura em aberto do pedido: a do próprio pedido, se ainda não pago, ou a de renovação que vence primeiro, se o IP está ativo ou suspenso. Chame de novo quando o PIX anterior expirar: um novo é gerado. Sem fatura em aberto: 409 sem_fatura_aberta.

{
  "fatura": { "id": 301, "status": "em_aberto", "total": "17.00", "a_pagar": "17.00", "moeda": "BRL", "vencimento": "2026-11-16" },
  "pix": {
    "copia_e_cola": "00020126…6304ABCD",
    "qr_code_png_base64": "iVBORw0KGgo…",
    "valor": "17.00",
    "expira_em": "2026-11-16T15:30:00Z"
  }
}

DELETE /v1/ips/{id}#

Antes do pagamento, cancela o pedido e a fatura (cancelado). Com o IP ativo ou suspenso, encerra o IP (cancelando → cancelado): ele sai da sua conta e é devolvido ao data center, sem volta. Se o IP ainda estiver em uso numa VPS, o encerramento para em em_analise até ele ser retirado. Em outros status: 409 estado.

Faturas

GET /v1/faturas#

As faturas dos seus IPs (a primeira de cada pedido e as renovações) e as faturas de crédito, da mais nova para a mais antiga (até 100).

{
  "dados": [
    { "id": 301, "status": "em_aberto", "total": "17.00", "a_pagar": "17.00", "moeda": "BRL",
      "vencimento": "2026-11-16", "tipo": "ip", "servicos": [217] }
  ]
}

GET /v1/faturas/{id}#

Uma fatura, com tipo e servicos.

GET /v1/faturas/{id}/pix#

O PIX de uma fatura em aberto (de IP ou de crédito). Mesma resposta de GET /v1/ips/{id}/pix.

POST /v1/faturas/{id}/pagar-com-credito#

Paga a fatura inteira com o crédito da conta e devolve a fatura atualizada. Crédito menor que o valor: 402 credito_insuficiente (nada é debitado). Fatura de crédito: 409 fatura_de_credito.

Crédito

GET /v1/credito#

Saldo de crédito e as últimas 20 faturas de crédito.

{
  "credito": "34.00",
  "moeda": "BRL",
  "faturas": [
    { "id": 310, "status": "paga", "total": "50.00", "a_pagar": "0.00", "moeda": "BRL", "vencimento": "2026-11-10", "tipo": "credito" }
  ]
}

POST /v1/credito#

Cria uma fatura de crédito e responde 201 com a fatura e o PIX. Exige Idempotency-Key. Paga, o valor vira crédito e quita as renovações em aberto (veja Renovação automática).

curl -s -X POST https://vitthost.com.br/central/api_ips.php/v1/credito \
  -H "Authorization: Bearer $VITT_IP_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: credito-2026-11-001" \
  -d '{"valor": "50.00"}'

{
  "fatura": { "id": 310, "status": "em_aberto", "total": "50.00", "a_pagar": "50.00", "moeda": "BRL", "vencimento": "2026-11-10", "tipo": "credito" },
  "pix": { "copia_e_cola": "00020126…", "qr_code_png_base64": "iVBORw0KGgo…", "valor": "50.00", "expira_em": null }
}

Se o PIX não puder ser gerado na hora, pix vem null com pix_erro: peça depois em GET /v1/faturas/{id}/pix.

Objetos

Pedido (IP)

{
  "id": 42,
  "referencia": "cliente-1234-vps-88",
  "status": "ativo",
  "etapa": null,
  "pagamento": "pix",
  "local": "ca-1",
  "vps_id": null,
  "ip": "203.0.113.10",
  "rede": {
    "ip": "203.0.113.10",
    "mascara": "255.255.255.0",
    "gateway": "203.0.113.254",
    "mac": "00:50:56:00:ab:cd",
    "mac_da_vps": false
  },
  "servico_id": 217,
  "vencimento": "2026-11-16",
  "renovacao": {
    "vencimento": "2026-11-16",
    "dias_para_vencer": 3,
    "em_atraso": false,
    "valor_renovacao": "17.00",
    "ciclo": "mensal",
    "fatura_em_aberto": {
      "id": 301, "status": "em_aberto", "total": "17.00", "a_pagar": "17.00",
      "moeda": "BRL", "vencimento": "2026-11-16"
    },
    "suspensao_prevista_em": "2026-11-17",
    "encerramento_previsto_em": "2026-11-22"
  },
  "bloqueio": null,
  "fatura": { "id": 260, "status": "paga", "total": "17.00", "a_pagar": "0.00", "moeda": "BRL", "vencimento": "2026-10-16" },
  "pix": null,
  "mensagem": "IP ativo na sua conta Cloud. Use-o ao criar ou editar uma VPS.",
  "criado_em": "2026-10-17T01:54:10Z",
  "pago_em": "2026-10-17T01:55:06Z",
  "ativado_em": "2026-10-17T02:03:41Z",
  "encerrado_em": null
}

Renovação

Fatura

PIX

Webhooks

Com uma URL cadastrada, cada evento é enviado como POST em JSON. Responda com qualquer status 2xx em até 10 segundos para confirmar. Sem confirmação, reenviamos depois de 1 min, 5 min, 30 min, 2 h, 12 h e 24 h; depois disso o evento é descartado (o estado continua consultável pela API). A entrega é "pelo menos uma vez": use o id do evento para ignorar repetições.

POST /sua-url HTTP/1.1
Content-Type: application/json
User-Agent: VittHost-Webhooks/1.0
X-Vitt-Evento: ip.ativo
X-Vitt-Evento-Id: evt_3f9a1c0b7d2e4a6b8c9d0e1f
X-Vitt-Assinatura: t=1792200000,v1=5b2c…e91

{
  "id": "evt_3f9a1c0b7d2e4a6b8c9d0e1f",
  "tipo": "ip.ativo",
  "criado_em": "2026-10-17T02:03:41Z",
  "dados": { …pedido… }
}

Conferindo a assinatura

X-Vitt-Assinatura tem o horário do envio (t, Unix) e v1 = HMAC-SHA256 do texto "<t>.<corpo cru>" com o segredo do webhook, em hexadecimal. Confira com o corpo cru (antes de decodificar o JSON) e recuse envios com mais de 5 minutos.

<?php
$segredo = getenv('VITT_WEBHOOK_SECRET');
$corpo = file_get_contents('php://input');
$partes = [];
foreach (explode(',', $_SERVER['HTTP_X_VITT_ASSINATURA'] ?? '') as $p) {
    [$k, $v] = array_pad(explode('=', trim($p), 2), 2, '');
    $partes[$k] = $v;
}
$t = (int) ($partes['t'] ?? 0);
$esperada = hash_hmac('sha256', $t . '.' . $corpo, $segredo);
if ($t <= 0 || abs(time() - $t) > 300 || !hash_equals($esperada, $partes['v1'] ?? '')) {
    http_response_code(401);
    exit;
}
$evento = json_decode($corpo, true);
// ignore se $evento['id'] já foi processado; senão, trate $evento['tipo']
http_response_code(200);

const crypto = require('crypto');

// use o corpo cru: app.use(express.raw({ type: 'application/json' }))
function assinaturaValida(segredo, cabecalho, corpoCru) {
  const partes = Object.fromEntries(String(cabecalho || '').split(',').map(p => p.trim().split('=')));
  const t = Number(partes.t || 0);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300 || !partes.v1) return false;
  const esperada = crypto.createHmac('sha256', segredo).update(t + '.' + corpoCru).digest('hex');
  return esperada.length === partes.v1.length &&
    crypto.timingSafeEqual(Buffer.from(esperada), Buffer.from(partes.v1));
}

Eventos

• Pedido: o pedido completo, com renovacao quando o IP está ativo ou suspenso.
• Fatura: {"pedido_id", "servico_id", "ip", "fatura"}.
• Aviso de renovação: {"pedido_id", "servico_id", "ip", "fatura", "renovacao"}. Cada aviso sai uma vez por fatura e IP.
• Crédito: {"fatura", "valor", "faturas_pagas", "credito", "moeda"}: a fatura de crédito paga, as faturas quitadas com o crédito e o saldo depois disso.

POST /v1/webhooks/teste#

Envia um evento teste para a sua URL e responde 202 com {"evento_id", "url"}. Sem URL cadastrada: 409 sem_webhook.

Erros

HTTP/1.1 422 Unprocessable Entity

{ "erro": { "codigo": "valor", "mensagem": "\"valor\" vai de 2.00 a 2000.00 por fatura de crédito." } }

Boas práticas

• Uma Idempotency-Key por operação, gerada e guardada antes de enviar. Em timeout ou erro 5xx, reenvie com a mesma chave: nunca crie um pedido "novo" para tentar de novo.
• Use referencia com o id do seu cliente ou serviço, para achar o pedido depois com GET /v1/ips?referencia=….
• Prefira webhooks a consultas repetidas. Se consultar, espere pelo menos 1 minuto entre chamadas do mesmo pedido.
• Rotina diária de renovação: GET /v1/ips?vence_em_ate=7 para avisar seus clientes, e GET /v1/ips?em_atraso=1 para agir antes de encerramento_previsto_em.
• Mantenha crédito na conta para que as renovações se paguem sozinhas e nenhum IP em uso seja suspenso.
• Mostre a mensagem do pedido ao seu cliente: ela já está escrita para isso.

Dúvidas ou pedido de chave: abra um ticket na central do cliente. Para gerenciar VPS da conta Cloud, veja também a API do Virtualizor para revenda.