piv.day
Abrir app
Voltar à visão geral da APIBaixar .txt
Documentação

Primeiros passos

REST API no plano Business. Tokens Bearer, JSON, endpoints idempotentes, códigos de erro previsíveis. Cada endpoint inclui um exemplo de requisição e resposta.

Base URL

https://app.piv.day/api/v1

Todos os endpoints ficam sob este prefixo. Um único ambiente — sem hosts de staging separados.

Autenticação

Authorization: Bearer YOUR_API_KEY

As chaves são criadas no dashboard em Configurações → API Keys. Cada chave possui escopos granulares (leitura de números, envio de SMS, compra de proxies, etc.). Um token comprometido é rotacionado com um clique — sem necessidade de recadastrar o time.

Conta

GET/api/v1/account
curl https://app.piv.day/api/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"
Um único endpoint utilitário — saldo e email da conta atual. Útil para confirmar que a chave funciona e que a autenticação está configurada corretamente.
{
  "success": true,
  "data": {
    "user_id": "usr-uuid-...",
    "balance": 150.50,
    "email": "u***@example.com",
    "team_id": null,
    "is_team_member": false
  }
}

GET /api/v1/account

Formato de resposta

{
  "success": true,
  "data": { ... }
}

Todas as respostas são JSON. Em caso de erro, success é false e o corpo contém error.code e error.message.

Rate limits

100 requisições por minuto por API key. O limite é compartilhado entre todos os endpoints. Precisa de mais capacidade para um pico? Fale com o suporte no Telegram e aumentaremos o limite. Ao exceder o limite, você recebe `429 RATE_LIMITED` e o header `Retry-After` — quantos segundos aguardar antes da próxima chamada.
HTTP/1.1 429 Too Many Requests
Retry-After: 12

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded, retry in 12s"
  }
}

429 Too Many Requests

Documentação

Números

Compre, renove e restaure números. Receba e envie SMS. Inicie verificações Google QR. Assine eventos via webhooks.

Países e preços

GET/api/v1/numbers/countries

Retorna países disponíveis para compra com o preço atual e recursos de SMS. Todos os preços incluem o desconto da sua assinatura.

Campos de resposta

CampoTipoDescrição
country_codestringCódigo de país ISO de duas letras (ex.: SE).
price_per_monthnumberPreço final para seu plano — o que é cobrado na compra. Descontos Premium / Business já estão aplicados.
base_pricenumberPreço sem descontos (plano Free). Retornado para comparação para ver quanto a assinatura economiza.
can_send_smsbooleanSe o envio de SMS de saída é suportado a partir deste número.
can_receive_smsbooleanSe o recebimento de SMS de entrada é suportado.
sms_send_pricenumber|nullPreço por SMS de saída, também com o desconto do plano aplicado. null quando o envio não é suportado neste país.
GET/api/v1/numbers/countries
curl https://app.piv.day/api/v1/numbers/countries \
  -H "Authorization: Bearer YOUR_API_KEY"
200OK
{
  "success": true,
  "data": [
    {
      "country_code": "SE",
      "price_per_month": 4.00,
      "base_price": 5.00,
      "can_send_sms": true,
      "can_receive_sms": true,
      "sms_send_price": 0.25
    },
    {
      "country_code": "GB",
      "price_per_month": 3.00,
      "base_price": 3.00,
      "can_send_sms": true,
      "can_receive_sms": true,
      "sms_send_price": 0.20
    }
  ]
}

Listar números

GET/api/v1/numbers

Retorna uma página de números da conta com filtros por país, status e busca por número ou nome personalizado.

Parâmetros de consulta

CampoTipoDescrição
limitintegerTamanho da página (padrão 50, máximo 200).
offsetintegerOffset de paginação.
countrystringFiltro de código de país ISO.
statusstringUm de active, expired, pending_restore.
searchstringBusca por substring no número de telefone ou nome personalizado.
GET/api/v1/numbers
curl "https://app.piv.day/api/v1/numbers?country=SE&status=active&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
200OK
{
  "success": true,
  "data": {
    "numbers": [
      {
        "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
        "phone_number": "+46764794425",
        "country_code": "SE",
        "status": "active",
        "created_at": "2026-05-01T10:00:00Z",
        "expires_at": "2026-05-31T10:00:00Z",
        "auto_renew": false,
        "custom_name": "Office line",
        "purchased_at": "2026-05-01T10:00:00Z",
        "next_renewal_date": "2026-05-31T10:00:00Z",
        "tags": ["support"],
        "can_send_sms": true,
        "can_receive_sms": true
      }
    ],
    "pagination": { "total": 1, "limit": 10, "offset": 0 }
  }
}

Obter um número por ID

GET/api/v1/numbers/{piv_num_id}

Registro completo do número: status, datas, renovação automática, tags, direções SMS permitidas.

Erros

CódigoHTTPQuando dispara
NUMBER_NOT_FOUND404O número não existe ou não pertence à conta.
GET/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o
curl https://app.piv.day/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o \
  -H "Authorization: Bearer YOUR_API_KEY"
200OK
{
  "success": true,
  "data": {
    "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
    "phone_number": "+46764794425",
    "country_code": "SE",
    "status": "active",
    "created_at": "2026-05-01T10:00:00Z",
    "expires_at": "2026-05-31T10:00:00Z",
    "auto_renew": false,
    "custom_name": "Office line",
    "purchased_at": "2026-05-01T10:00:00Z",
    "next_renewal_date": "2026-05-31T10:00:00Z",
    "tags": ["support"],
    "can_send_sms": true,
    "can_receive_sms": true
  }
}

Comprar um número

POST/api/v1/numbers/purchase

Compra um único número no país selecionado pelo período especificado. O custo é debitado do saldo da conta. Retorna piv_num_id usado em todas as operações posteriores do número.

Corpo da requisição

CampoTipoDescrição
country_code*stringCódigo de país ISO.
duration_months*integerPeríodo de aluguel em meses (mínimo 1).
auto_renew*booleanAtivar renovação automática logo após a compra.
custom_namestringNome amigável opcional para o número.

Erros

CódigoHTTPQuando dispara
COUNTRY_NOT_AVAILABLE400País não disponível ou sem preços.
NO_NUMBERS_AVAILABLE400Não há números disponíveis no país solicitado no momento.
INSUFFICIENT_BALANCE402Saldo insuficiente para a compra.
VALIDATION_ERROR400Campos inválidos no corpo da requisição.
POST/api/v1/numbers/purchase
curl -X POST https://app.piv.day/api/v1/numbers/purchase \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country_code": "SE",
    "duration_months": 1,
    "auto_renew": false,
    "custom_name": "My Sweden Number"
  }'
200OK
{
  "success": true,
  "cost": 5.00,
  "numbers": [
    {
      "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
      "country_code": "SE",
      "phone_number": "+46764794425",
      "created_at": "2026-05-01T10:00:00Z",
      "expires_at": "2026-05-31T10:00:00Z",
      "auto_renew": false,
      "custom_name": "My Sweden Number"
    }
  ]
}

Renovar um número

POST/api/v1/numbers/{piv_num_id}/renew

Estende um número ativo pelo período especificado. O custo é debitado no momento da chamada.

Corpo da requisição

CampoTipoDescrição
duration_months*integerNúmero de meses a adicionar.

Erros

CódigoHTTPQuando dispara
NUMBER_NOT_FOUND404O número não existe ou não pertence à conta.
COUNTRY_NOT_AVAILABLE400Nenhum preço encontrado para o país do número.
INSUFFICIENT_BALANCE402Saldo insuficiente para renovar.
POST/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/renew
curl -X POST https://app.piv.day/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/renew \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "duration_months": 1 }'
200OK
{
  "success": true,
  "data": {
    "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
    "phone_number": "+46764794425",
    "old_expires_at": "2026-05-31T10:00:00Z",
    "new_expires_at": "2026-06-30T10:00:00Z",
    "cost": 5.00
  }
}

Atualizar um número

PATCH/api/v1/numbers/{piv_num_id}

Atualmente apenas o nome personalizado pode ser atualizado.

Corpo da requisição

CampoTipoDescrição
custom_name*stringNovo nome para o número.

Erros

CódigoHTTPQuando dispara
NUMBER_NOT_FOUND404O número não existe ou não pertence à conta.
VALIDATION_ERROR400Valor inválido no corpo da requisição.
PATCH/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o
curl -X PATCH https://app.piv.day/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_name": "Support line" }'
200OK
{
  "success": true,
  "data": {
    "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
    "phone_number": "+46764794425",
    "country_code": "SE",
    "status": "active",
    "custom_name": "Support line",
    "auto_renew": false,
    "expires_at": "2026-05-31T10:00:00Z",
    "tags": []
  }
}

Gerenciar renovação automática

PATCH/api/v1/numbers/{piv_num_id}/auto-renewal

Ativa ou desativa a renovação automática do número. Quando ativada, a renovação é debitada automaticamente 24 horas antes do vencimento. Se o saldo for insuficiente, o número expira; você pode recuperá-lo via POST /numbers/restore dentro de 7 dias.

Corpo da requisição

CampoTipoDescrição
auto_renew*booleanNovo valor do sinalizador de renovação automática.
PATCH/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/auto-renewal
curl -X PATCH https://app.piv.day/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/auto-renewal \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "auto_renew": true }'
200OK
{
  "success": true,
  "data": {
    "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
    "phone_number": "+46764794425",
    "auto_renew": true
  }
}

Restaurar números expirados

POST/api/v1/numbers/restore

Recupera números expirados dentro de um período de 7 dias. Passe um array de piv_num_id — os números retornam com histórico SMS e configurações preservadas. A restauração custa mais do que comprar um número novo (inclui um multiplicador de restauração) — os valores exatos aparecem no dashboard antes da confirmação. O status final de cada número chega via webhook number.restore_completed; reembolsos por números malsucedidos são creditados automaticamente.

Corpo da requisição

CampoTipoDescrição
piv_num_ids*string[]Array de IDs de números para restaurar.

Erros

CódigoHTTPQuando dispara
NO_RESTORABLE_NUMBERS404Nenhum dos números fornecidos pode ser restaurado (período de 7 dias expirou ou não são seus).
INSUFFICIENT_BALANCE402Saldo insuficiente para cobrir a restauração.
POST/api/v1/numbers/restore
curl -X POST https://app.piv.day/api/v1/numbers/restore \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "piv_num_ids": [
      "vzPA1-kHKSg-EAL7e-Jqd3o",
      "abc12-defgh-ijklm-nopqr"
    ]
  }'
200OK
{
  "success": true,
  "queued": 2,
  "skipped": 0,
  "total_charged": 9.00,
  "numbers": [
    {
      "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
      "phone_number": "+46764794425",
      "status": "pending"
    }
  ]
}

Histórico de SMS do número

GET/api/v1/numbers/{piv_num_id}/sms

Retorna mensagens de entrada e saída do número em ordem cronológica reversa.

Parâmetros de consulta

CampoTipoDescrição
limitintegerQuantas mensagens retornar (padrão 50, máximo 200).
offsetintegerOffset de paginação.
GET/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/sms
curl "https://app.piv.day/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/sms?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
200OK
{
  "success": true,
  "data": {
    "messages": [
      {
        "id": "42",
        "from_number": "+46764794425",
        "to_number": "+14155551234",
        "message_body": "Hello from piv.day",
        "direction": "outbound",
        "status": "delivered",
        "received_at": "2026-05-22T11:30:00Z"
      },
      {
        "id": "41",
        "from_number": "+14155551234",
        "to_number": "+46764794425",
        "message_body": "Hey, got your message!",
        "direction": "inbound",
        "status": "received",
        "received_at": "2026-05-22T11:35:00Z"
      }
    ],
    "pagination": { "total": 2, "limit": 20, "offset": 0 }
  }
}

Enviar SMS

POST/api/v1/numbers/{piv_num_id}/sms/send

Disponível para países onde o envio de saída é permitido (ex.: CA, GB, SE). O custo da mensagem é debitado no momento do envio.

Corpo da requisição

CampoTipoDescrição
to_number*stringNúmero do destinatário no formato internacional (E.164).
message_body*stringTexto da mensagem. GSM-7 e UCS-2 são suportados.

Erros

CódigoHTTPQuando dispara
NUMBER_NOT_FOUND404O número não existe ou não pertence à conta.
NUMBER_EXPIRED403O número já expirou.
NUMBER_NOT_ACTIVE400O número está em um estado que não permite envio.
INSUFFICIENT_BALANCE402Saldo insuficiente para enviar.
INVALID_MESSAGE_FORMAT400O corpo da mensagem excede o comprimento permitido ou contém caracteres proibidos.
POST/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/sms/send
curl -X POST https://app.piv.day/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/sms/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to_number": "+14155551234",
    "message_body": "Hello from piv.day"
  }'
200OK
{
  "success": true,
  "data": {
    "message_id": "42",
    "from_number": "+46764794425",
    "to_number": "+14155551234",
    "message_body": "Hello from piv.day",
    "status": "queued",
    "created_at": "2026-05-22T11:30:00Z"
  }
}

Iniciar verificação Google QR

POST/api/v1/numbers/{piv_num_id}/verify

Inicia uma verificação Google QR usando a URL fornecida. O resultado — sucesso ou falha — chega via webhook verify.completed ou verify.failed. O custo é debitado quando a tarefa é enfileirada.

Corpo da requisição

CampoTipoDescrição
gv_url*stringURL completa de verificação do Google (retirada da página do Google).

Erros

CódigoHTTPQuando dispara
NUMBER_NOT_FOUND404O número não existe ou não é seu.
NUMBER_NOT_ACTIVE400O número não está ativo.
SMS_DISABLED400O envio de SMS está desativado para este número.
INSUFFICIENT_BALANCE402Saldo insuficiente para a verificação.
PROXY_DEAD502Proxy indisponível — saldo reembolsado.
QUEUE_FULL503Fila cheia, tente mais tarde — saldo reembolsado.
SERVER_UNAVAILABLE503Servidor de automação indisponível — saldo reembolsado.
POST/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/verify
curl -X POST https://app.piv.day/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "gv_url": "https://gv.google.com/..." }'
202Accepted
{
  "success": true,
  "message": "Verification initiated"
}
Documentação

Proxy

IPv6 residencial em dezenas de países. Compra em massa, renovação, Restore mantendo o mesmo login e senha, exportação no formato desejado.

Lista de servidores

GET/api/v1/proxy/servers

Servidores proxy disponíveis com preços.

GET/api/v1/proxy/servers
curl https://app.piv.day/api/v1/proxy/servers \
  -H "Authorization: Bearer YOUR_API_KEY"
200OK
{
  "success": true,
  "data": {
    "servers": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "EU-DE-01",
        "country": "DE",
        "socks5_port": 1080,
        "http_port": 3128,
        "price_per_proxy": 0.50
      },
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "name": "EU-NL-01",
        "country": "NL",
        "socks5_port": 1080,
        "http_port": 3128,
        "price_per_proxy": 0.45
      }
    ]
  }
}

Lista de pedidos

GET/api/v1/proxy/orders

Lista dos seus pedidos de proxy com filtros por status ou pesquisa.

Parâmetros de consulta

CampoTipoDescrição
limitintegerTamanho da página. Padrão 100, máximo 500.
offsetintegerDeslocamento de paginação.
statusstringFiltro por status: active, expired.
searchstringPesquisa em pedidos.
GET/api/v1/proxy/orders
curl "https://app.piv.day/api/v1/proxy/orders?status=active&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
200OK
{
  "success": true,
  "data": {
    "orders": [
      {
        "id": "ord-uuid-...",
        "country": "DE",
        "quantity": 10,
        "price_per_proxy": 0.50,
        "price_total": 5.00,
        "status": "active",
        "purchased_at": "2026-01-01T00:00:00Z",
        "expires_at": "2026-02-01T00:00:00Z"
      }
    ],
    "pagination": { "total": 1, "limit": 20, "offset": 0 }
  }
}

Obter um pedido

GET/api/v1/proxy/orders/{id}

Obter os detalhes de um pedido específico, incluindo a lista de credenciais de proxy.

GET/api/v1/proxy/orders/ord-uuid-...
curl https://app.piv.day/api/v1/proxy/orders/ord-uuid-... \
  -H "Authorization: Bearer YOUR_API_KEY"
200OK
{
  "success": true,
  "data": {
    "order": {
      "id": "ord-uuid-...",
      "country": "DE",
      "quantity": 10,
      "price_per_proxy": 0.50,
      "price_total": 5.00,
      "status": "active",
      "purchased_at": "2026-01-01T00:00:00Z",
      "expires_at": "2026-02-01T00:00:00Z",
      "created_at": "2026-01-01T00:00:00Z",
      "items": [
        {
          "login": "user1",
          "password": "pass1",
          "host": "185.1.2.3",
          "socks5_port": 1080,
          "http_port": 3128,
          "ipv6": "2a00:1:2:3::1"
        }
      ]
    }
  }
}

Comprar proxies

POST/api/v1/proxy/purchase

Comprar proxies no servidor escolhido. Uma requisição cria um pedido com N proxies (até 500). Não há pedidos em massa — chame o método novamente se precisar de mais.

Corpo da requisição

CampoTipoDescrição
server_id*stringID do servidor de GET /proxy/servers.
quantity*integerQuantos proxies comprar (1–500).
months*integerPeríodo de locação em meses (1–12).

Erros

CódigoHTTPQuando dispara
INSUFFICIENT_BALANCE402Saldo insuficiente.
NOT_FOUND404Servidor proxy não encontrado ou inativo.
VALIDATION_ERROR400Corpo da requisição inválido.
POST/api/v1/proxy/purchase
curl -X POST https://app.piv.day/api/v1/proxy/purchase \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "quantity": 5,
    "months": 1
  }'
200OK
{
  "success": true,
  "data": {
    "order": {
      "id": "ord-uuid-...",
      "country": "DE",
      "quantity": 5,
      "price_total": 2.50,
      "status": "active",
      "expires_at": "2026-02-01T00:00:00Z",
      "created_at": "2026-01-01T00:00:00Z",
      "items": [
        {
          "login": "user1",
          "password": "pass1",
          "host": "185.1.2.3",
          "socks5_port": 1080,
          "http_port": 3128,
          "ipv6": "2a00:1:2:3::1"
        },
        {
          "login": "user2",
          "password": "pass2",
          "host": "185.1.2.3",
          "socks5_port": 1080,
          "http_port": 3128,
          "ipv6": "2a00:1:2:3::2"
        }
      ]
    }
  }
}

Renovar um pedido

POST/api/v1/proxy/orders/{id}/renew

Estender um pedido de proxy ativo por um número de meses.

Corpo da requisição

CampoTipoDescrição
months*integerMeses a adicionar.
POST/api/v1/proxy/orders/ord-uuid-.../renew
curl -X POST https://app.piv.day/api/v1/proxy/orders/ord-uuid-.../renew \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "months": 1 }'
200OK
{
  "success": true,
  "data": {
    "order_id": "ord-uuid-...",
    "cost": 5.00,
    "new_expires_at": "2026-03-01T00:00:00Z"
  }
}

Restore de pedido vencido

POST/api/v1/proxy/orders/{id}/restore

Recuperar um pedido de proxy vencido sem recompra. Login, senha, endereços IPv6, país e vinculações — os mesmos. O prazo é estendido por 1 mês. Sem necessidade de reconfigurar o antidetect.

POST/api/v1/proxy/orders/ord-uuid-.../restore
curl -X POST https://app.piv.day/api/v1/proxy/orders/ord-uuid-.../restore \
  -H "Authorization: Bearer YOUR_API_KEY"
200OK
{
  "success": true,
  "data": {
    "order_id": "ord-uuid-...",
    "quantity": 10,
    "total_cost": 5.00,
    "expires_at": "2026-03-01T00:00:00Z"
  }
}

Exportar proxies

GET/api/v1/proxy/orders/{id}/export

Exportar as credenciais de proxy do pedido como uma lista de texto (login:password@host:port).

Parâmetros de consulta

CampoTipoDescrição
formatstringFormato de exportação: socks5, http ou both (padrão socks5).
GET/api/v1/proxy/orders/ord-uuid-.../export
curl "https://app.piv.day/api/v1/proxy/orders/ord-uuid-.../export?format=socks5" \
  -H "Authorization: Bearer YOUR_API_KEY"
200OK
{
  "success": true,
  "data": {
    "content": "user1:[email protected]:1080\nuser2:[email protected]:1080",
    "filename": "piv-day-proxy-ord-uuid--socks5.txt",
    "format": "socks5",
    "count": 2
  }
}
Documentação

Domínios

Pesquisa e registro sem KYC, Cloudflare e SSL automáticos, gerenciamento de registros DNS e servidores NS via API.

Listar domínios

GET/api/v1/domains

Lista dos seus domínios registrados com filtragem.

Parâmetros de consulta

CampoTipoDescrição
limitintegerTamanho da página. Padrão 100, máximo 500.
offsetintegerOffset de paginação.
statusstringStatus do domínio: active, pending, expired.
cloudflarestringFiltrar por status do Cloudflare: true ou false.
auto_renewstringFiltrar por renovação automática: true ou false.
searchstringPesquisar por nome de domínio.
GET/api/v1/domains
curl "https://app.piv.day/api/v1/domains?status=active&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
200OK
{
  "success": true,
  "data": {
    "domains": [
      {
        "id": "dom-uuid-...",
        "domain_name": "mysite.com",
        "status": "active",
        "registered_at": "2026-01-01T00:00:00Z",
        "expires_at": "2027-01-01T00:00:00Z",
        "auto_renew": true,
        "cloudflare_enabled": true,
        "cloudflare_status": "active",
        "ssl_type": "lets_encrypt",
        "ssl_status": "active",
        "ssl_mode": "full",
        "ssl_expires_at": "2026-04-01T00:00:00Z",
        "created_at": "2026-01-01T00:00:00Z",
        "updated_at": "2026-01-01T00:00:00Z"
      }
    ],
    "pagination": { "total": 1, "limit": 20, "offset": 0 }
  }
}

Registrar um domínio

POST/api/v1/domains

Registrar um novo domínio. A requisição é assíncrona — retorna queue_id para rastreamento. Cloudflare ATIVADO: não passe nameservers; opcionalmente pode passar dns_records e ssl_mode. Cloudflare DESATIVADO: não passe dns_records nem ssl_mode; nameservers é obrigatório (mínimo 2). Nunca expomos os nameservers do Cloudflare.

Corpo da requisição

CampoTipoDescrição
domain*stringNome de domínio a registrar, ex.: mysite.com.
period*integerPeríodo de registro em anos (1–10).
cloudflare*booleanConectar o domínio ao Cloudflare automaticamente.
auto_renew*booleanAtivar renovação automática.
ssl_modestringflexible | full | strict. Somente com cloudflare: true.
nameserversstring[]Obrigatório com cloudflare: false (≥2 NS). Proibido com cloudflare: true.
dns_recordsobject[]Registros DNS iniciais. Somente com cloudflare: true.

Erros

CódigoHTTPQuando dispara
DOMAIN_NOT_AVAILABLE400O domínio não está disponível para registro.
INSUFFICIENT_BALANCE402Saldo insuficiente.
VALIDATION_ERROR400Corpo da requisição inválido.
POST/api/v1/domains
curl -X POST https://app.piv.day/api/v1/domains \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "mysite.com",
    "period": 1,
    "cloudflare": true,
    "auto_renew": true,
    "ssl_mode": "full",
    "dns_records": [
      { "type": "A", "name": "@", "content": "1.2.3.4", "proxied": true }
    ]
  }'
POST/api/v1/domains
curl -X POST https://app.piv.day/api/v1/domains \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "mysite.com",
    "period": 1,
    "cloudflare": false,
    "auto_renew": false,
    "nameservers": ["ns1.myhost.com", "ns2.myhost.com"]
  }'
202Accepted
{
  "success": true,
  "data": {
    "queue_id": "que-uuid-...",
    "domain": {
      "id": "dom-uuid-...",
      "domain_name": "mysite.com",
      "status": "purchasing",
      "period": 1,
      "cloudflare_enabled": true,
      "auto_renew": true,
      "ssl_mode": "full",
      "created_at": "2026-01-01T00:00:00Z"
    }
  }
}

Status da fila de registro

GET/api/v1/domains/queue/{id}

Verificar o status de uma entrada na fila de registro ou renovação de domínio. No status completed, a resposta já traz o cartão completo do domínio — não é necessária uma chamada separada a /domains/{id}.

GET/api/v1/domains/queue/que-uuid-...
curl https://app.piv.day/api/v1/domains/queue/que-uuid-... \
  -H "Authorization: Bearer YOUR_API_KEY"
pending / processing
{
  "success": true,
  "data": {
    "queue_id": "que-uuid-...",
    "domain": "mysite.com",
    "status": "pending"
  }
}
completed — cartão completo
{
  "success": true,
  "data": {
    "queue_id": "que-uuid-...",
    "status": "completed",
    "domain": {
      "id": "dom-uuid-...",
      "domain_name": "mysite.com",
      "status": "active",
      "registered_at": "2026-01-01T12:00:00Z",
      "expires_at": "2027-01-01T12:00:00Z",
      "auto_renew": true,
      "cloudflare_enabled": true,
      "cloudflare_status": "active",
      "ssl_type": "lets_encrypt",
      "ssl_status": "active",
      "ssl_mode": "full",
      "ssl_expires_at": "2026-04-01T00:00:00Z",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T12:00:00Z",
      "dns_records": [
        { "name": "@", "type": "A", "content": "1.2.3.4", "ttl": 1, "priority": null, "proxied": true }
      ]
    }
  }
}

Obter um domínio

GET/api/v1/domains/{id}

Obter informações completas sobre um domínio registrado. O campo nameservers está presente somente quando cloudflare_enabled: false.

GET/api/v1/domains/dom-uuid-...
curl https://app.piv.day/api/v1/domains/dom-uuid-... \
  -H "Authorization: Bearer YOUR_API_KEY"
200OK
{
  "success": true,
  "data": {
    "domain": {
      "id": "dom-uuid-...",
      "domain_name": "mysite.com",
      "status": "active",
      "registered_at": "2026-01-01T12:00:00Z",
      "expires_at": "2027-01-01T12:00:00Z",
      "auto_renew": true,
      "cloudflare_enabled": true,
      "cloudflare_status": "active",
      "ssl_type": "lets_encrypt",
      "ssl_status": "active",
      "ssl_mode": "full",
      "ssl_expires_at": "2026-04-01T00:00:00Z",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T12:00:00Z",
      "dns_records": [
        { "name": "@", "type": "A", "content": "1.2.3.4", "ttl": 1, "priority": null, "proxied": true },
        { "name": "www", "type": "CNAME", "content": "mysite.com", "ttl": 1, "priority": null, "proxied": true }
      ]
    }
  }
}

Renovar domínio

POST/api/v1/domains/{id}/renew

Renovar o registro do domínio. Retorna queue_id para rastreamento.

Corpo da requisição

CampoTipoDescrição
period*integerAnos a adicionar.
POST/api/v1/domains/dom-uuid-.../renew
curl -X POST https://app.piv.day/api/v1/domains/dom-uuid-.../renew \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "period": 1 }'
202Accepted
{
  "success": true,
  "data": {
    "queue_id": "que-uuid-...",
    "domain_id": "dom-uuid-...",
    "expires_at": "2027-01-01T12:00:00Z"
  }
}

Alternar renovação automática

POST/api/v1/domains/{id}/auto-renew

Ativar ou desativar a renovação automática do domínio.

Corpo da requisição

CampoTipoDescrição
auto_renew*booleanNovo valor do sinalizador.
POST/api/v1/domains/dom-uuid-.../auto-renew
curl -X POST https://app.piv.day/api/v1/domains/dom-uuid-.../auto-renew \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "auto_renew": true }'
200OK
{
  "success": true,
  "data": {
    "id": "dom-uuid-...",
    "auto_renew": true
  }
}

Registros DNS do domínio

GET/api/v1/domains/{id}/dns

Listar os registros DNS do domínio (via Cloudflare).

GET/api/v1/domains/dom-uuid-.../dns
curl https://app.piv.day/api/v1/domains/dom-uuid-.../dns \
  -H "Authorization: Bearer YOUR_API_KEY"
200OK
{
  "success": true,
  "data": {
    "records": [
      {
        "id": "rec-uuid-...",
        "type": "A",
        "name": "@",
        "content": "1.2.3.4",
        "ttl": 1,
        "priority": null,
        "proxied": true
      }
    ]
  }
}

Adicionar registro DNS

POST/api/v1/domains/{id}/dns

Criar um novo registro DNS.

Corpo da requisição

CampoTipoDescrição
type*stringTipo de registro: A, AAAA, CNAME, MX, TXT, etc.
name*stringNome do registro, ex.: @ ou subdomain.
content*stringValor do registro.
ttlintegerTTL em segundos (1 = automático).
proxiedbooleanFazer proxy pelo Cloudflare.
POST/api/v1/domains/dom-uuid-.../dns
curl -X POST https://app.piv.day/api/v1/domains/dom-uuid-.../dns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "A",
    "name": "@",
    "content": "1.2.3.4",
    "ttl": 1,
    "proxied": true
  }'
201Created
{
  "success": true,
  "data": {
    "record": {
      "id": "rec-uuid-...",
      "type": "A",
      "name": "@",
      "content": "1.2.3.4",
      "ttl": 1,
      "priority": null,
      "proxied": true
    }
  }
}

Atualizar registro DNS

PUT/api/v1/domains/{id}/dns/{recordId}

Atualizar um registro DNS existente por ID. Apenas os campos enviados são sobrescritos.

PUT/api/v1/domains/dom-uuid-.../dns/rec-uuid-...
curl -X PUT https://app.piv.day/api/v1/domains/dom-uuid-.../dns/rec-uuid-... \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content": "5.6.7.8" }'

Excluir registro DNS

DELETE/api/v1/domains/{id}/dns/{recordId}

Excluir um registro DNS por ID.

DELETE/api/v1/domains/dom-uuid-.../dns/rec-uuid-...
curl -X DELETE https://app.piv.day/api/v1/domains/dom-uuid-.../dns/rec-uuid-... \
  -H "Authorization: Bearer YOUR_API_KEY"

Ativar Cloudflare

POST/api/v1/domains/{id}/cloudflare

Ativar Cloudflare para o domínio. Não retornamos os nameservers do Cloudflare — a delegação é configurada do nosso lado. Desativar Cloudflare via este endpoint não é suportado.

POST/api/v1/domains/dom-uuid-.../cloudflare
curl -X POST https://app.piv.day/api/v1/domains/dom-uuid-.../cloudflare \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'
200OK
{
  "success": true,
  "data": {
    "domain_id": "dom-uuid-...",
    "ssl_mode": "flexible"
  }
}

Definir nameservers

POST/api/v1/domains/{id}/ns-servers

Definir nameservers personalizados para o domínio.

POST/api/v1/domains/dom-uuid-.../ns-servers
curl -X POST https://app.piv.day/api/v1/domains/dom-uuid-.../ns-servers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "nameservers": ["ns1.example.com", "ns2.example.com"] }'
200OK
{
  "success": true,
  "data": {
    "nameservers": [
      { "nameserver": "ns1.example.com", "order_index": 1 },
      { "nameserver": "ns2.example.com", "order_index": 2 }
    ]
  }
}
Documentação

Whites

Geração de white-pages por nicho e tier. Cada site é único. Troque domínio e contatos sem regenerar.

Listar tiers

GET/api/v1/whites/tiers

Tiers de geração disponíveis com preços. price é o preço por geração já ajustado à sua conta (assinatura aplicada), um único número. quality: "premium" custa mais (calculado no momento da criação). Blog apenas no v2_tier3: os primeiros 3 artigos estão incluídos; cada artigo extra (até 20) é cobrado a extra_article_price.

GET/api/v1/whites/tiers
curl https://app.piv.day/api/v1/whites/tiers \
  -H "Authorization: Bearer YOUR_API_KEY"
200OK
{
  "success": true,
  "data": {
    "tiers": [
      {
        "tier_key": "v2_tier1",
        "name": "Landing",
        "generator_version": "v2",
        "min_articles": 0,
        "max_articles": 0,
        "price": 3.00,
        "extra_article_price": null
      },
      {
        "tier_key": "v2_tier2",
        "name": "Multi-page",
        "generator_version": "v2",
        "min_articles": 0,
        "max_articles": 0,
        "price": 6.00,
        "extra_article_price": null
      },
      {
        "tier_key": "v2_tier3",
        "name": "Full + Blog",
        "generator_version": "v2",
        "min_articles": 3,
        "max_articles": 20,
        "price": 10.00,
        "extra_article_price": 1.50
      }
    ]
  }
}

Listar whites

GET/api/v1/whites

Lista dos seus jobs de geração com filtragem.

Parâmetros de consulta

CampoTipoDescrição
limitintegerTamanho da página. Padrão 100, máximo 500.
offsetintegerOffset de paginação.
statusstringqueued | processing | done | failed.
tier_keystringv2_tier1 | v2_tier2 | v2_tier3.
GET/api/v1/whites
curl "https://app.piv.day/api/v1/whites?status=done&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
200OK
{
  "success": true,
  "data": {
    "whites": [
      {
        "id": "job-uuid-...",
        "name": "My White",
        "status": 10,
        "tier_key": "v2_tier3",
        "quality": "standard",
        "niche": "IT Consulting",
        "country": "DE",
        "language": "de",
        "domain": "mysite.com",
        "result_url": null,
        "created_at": "2026-01-01T00:00:00Z"
      }
    ],
    "pagination": { "total": 1, "limit": 20, "offset": 0 }
  }
}

Iniciar geração

POST/api/v1/whites

Coloque um job de geração de white-page na fila. O pagamento é cobrado imediatamente. O status final chega via webhook white.completed / white.failed ou pode ser consultado via GET /whites/{id}.

Corpo da requisição

CampoTipoDescrição
name*stringNome do job (2–20 caracteres).
tier_key*stringv2_tier1 | v2_tier2 | v2_tier3.
niche*stringNicho do site (até 25 caracteres).
country*stringCódigo do país (ISO 3166-1 alpha-2).
language*stringIdioma principal do site (ISO 639-1).
qualitystringstandard | premium (padrão standard).
languagesstring[]Lista de idiomas. O primeiro está incluído no preço; cada idioma extra tem custo adicional.
domainstringDomínio completo (ex.: example.com). Sem autocompletar.
emailstringEmail completo (ex.: [email protected]). Sem autocompletar.
phonestringTelefone de contato.
addressstringEndereço da empresa.
legal_namestringNome jurídico.
style_hintstringEstilo de design (Random, Minimalista, Corporativo, etc.).
keywordsstring[]Palavras-chave SEO.
banned_wordsstring[]Palavras proibidas no conteúdo.
blog_countintegerQuantidade de artigos do blog 3–20. Apenas para v2_tier3. Artigos além de 3 têm custo extra.
contacts_modestringsame | template.
contacts_templatestringTemplate da página de contato (quando contacts_mode=template).
facebookstringURL completa da página do Facebook.
instagramstringURL completa do perfil do Instagram.
linkedinstringURL completa do perfil do LinkedIn.
youtubestringURL completa do canal do YouTube.
tiktokstringURL completa do perfil do TikTok.

Erros

CódigoHTTPQuando dispara
INSUFFICIENT_BALANCE402Saldo insuficiente.
INVALID_TIER400Nenhum tier encontrado com essa chave.
VALIDATION_ERROR400Corpo da requisição inválido.
POST/api/v1/whites
curl -X POST https://app.piv.day/api/v1/whites \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tech Blog DE",
    "tier_key": "v2_tier3",
    "niche": "IT Consulting",
    "country": "DE",
    "language": "de",
    "quality": "premium",
    "languages": ["de", "en"],
    "domain": "techblog-de.com",
    "email": "[email protected]",
    "phone": "+49 30 123456",
    "address": "Berliner Str. 1, 10115 Berlin",
    "legal_name": "TechBlog GmbH",
    "style_hint": "Корпоративный",
    "keywords": ["IT", "consulting", "cloud"],
    "banned_words": ["cheap", "free"],
    "blog_count": 8,
    "contacts_mode": "same",
    "facebook": "https://facebook.com/techblogde",
    "instagram": "https://instagram.com/techblogde",
    "linkedin": "https://linkedin.com/company/techblogde"
  }'
200OK
{
  "success": true,
  "data": {
    "status": "queued",
    "white": {
      "id": "job-uuid-...",
      "name": "Tech Blog DE",
      "status": 0,
      "tier_key": "v2_tier3",
      "quality": "premium",
      "niche": "IT Consulting",
      "country": "DE",
      "language": "de",
      "domain": "techblog-de.com",
      "result_url": null,
      "created_at": "2026-01-01T00:00:00Z"
    }
  }
}

Obter um white

GET/api/v1/whites/{id}

Obter o estado atual de um job de geração.

GET/api/v1/whites/job-uuid-...
curl https://app.piv.day/api/v1/whites/job-uuid-... \
  -H "Authorization: Bearer YOUR_API_KEY"
200OK
{
  "success": true,
  "data": {
    "white": {
      "id": "job-uuid-...",
      "name": "Tech Blog DE",
      "status": 10,
      "tier_key": "v2_tier3",
      "quality": "premium",
      "niche": "IT Consulting",
      "country": "DE",
      "language": "de",
      "domain": "techblog-de.com",
      "result_url": null,
      "created_at": "2026-01-01T00:00:00Z"
    }
  }
}

Baixar arquivo

GET/api/v1/whites/{id}/download

Obtenha um link assinado de curta duração para o arquivo final da white-page. O link é válido por ~5 minutos (veja expires_at). Se expirou, basta chamar /download novamente — emitiremos um novo. Se a white-page ainda não foi gerada, retorna 409 NOT_READY.

Parâmetros de consulta

CampoTipoDescrição
formatstringFormato do arquivo. Padrão php.

Erros

CódigoHTTPQuando dispara
NOT_READY409A white-page ainda está sendo gerada — tente novamente após white.completed.
GET/api/v1/whites/job-uuid-.../download
curl "https://app.piv.day/api/v1/whites/job-uuid-.../download?format=php" \
  -H "Authorization: Bearer YOUR_API_KEY"
200OK
{
  "success": true,
  "data": {
    "url": "https://strg.piv.day/download/<user_id>/<job_id>?format=php&token=<hmac>&filename=<name>.zip",
    "filename": "example.com_2026-05-28_DE_en.zip",
    "format": "php",
    "expires_at": "2026-05-28T14:46:00Z"
  }
}

Trocar domínio e contatos

POST/api/v1/whites/{id}/config

Atualize os dados de contato da empresa na white-page sem regenerá-la.

POST/api/v1/whites/job-uuid-.../config
curl -X POST https://app.piv.day/api/v1/whites/job-uuid-.../config \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company": "My Brand",
    "domain": "newdomain.com",
    "email": "[email protected]",
    "phone": "+49 30 123456",
    "address": "Berliner Str. 1, Berlin",
    "legal": "My Brand GmbH"
  }'
Documentação

Webhooks

Assine eventos da plataforma: SMS recebidos, sites prontos, pedidos expirando. O URL de notificações é definido no perfil da chave API.

Como chegam

Enviamos um POST simples com corpo JSON para sua URL. O formato é o mesmo para todos os eventos: event_type, timestamp e um bloco data. Seu servidor deve responder com qualquer 2xx em 5 segundos.

Se a entrega falhar

Em caso de não-2xx ou timeout — até 3 tentativas com espera de 1s / 2s / 4s. O histórico completo de entregas fica na página de chaves API no dashboard. Se todas as três falharem, o evento é marcado como failed e pode ser reenviado manualmente.

Segurança

Use um endpoint HTTPS. Cada requisição chega com o cabeçalho User-Agent: piv.day-webhook/1.0. A URL do webhook é configurada no perfil da chave API.

formato da requisição
POST <your webhook URL>
Content-Type: application/json
User-Agent: piv.day-webhook/1.0

{
  "event_type": "<event identifier>",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": { ... }
}

Todos os eventos

EventoQuando dispara
sms.receivedUm remetente confiável acabou de enviar uma mensagem para um dos seus números.
sms.status_updatedUm SMS de saída mudou de estado — entregue, falhou, etc.
number.restore_completedUm Restore em lote foi concluído — o resumo final chega aqui.
verify.completedA verificação da conta Google foi concluída com sucesso.
verify.failedAlgo deu errado — o Google não aceitou.
proxy.expires_soonRestam cerca de três dias no pedido de proxy.
domain.registeredO pedido de registro foi concluído com sucesso — o domínio está ativo.
domain.failedO pedido não foi concluído — causa comum: o nome acabou de ser registrado.
domain.expires_soonFalta cerca de uma semana para o domínio expirar.
white.completedA tarefa de geração do White foi concluída com sucesso.
white.failedA tarefa falhou — os fundos são reembolsados ao saldo.

SMS recebido no seu número

sms.received

Na maioria das vezes são códigos de verificação de redes de publicidade. O payload inclui o texto bruto e um código detectado automaticamente (quando presente) para que você possa passá-lo diretamente para seu fluxo de trabalho sem parsing. Mensagens de remetentes de spam conhecidos não são encaminhadas.

payload
{
  "event_type": "sms.received",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
    "text": "Your verification code is 123456",
    "code": "123456",
    "country": "SE",
    "received_at": "2026-05-22T12:34:56Z"
  }
}

Status do SMS enviado mudou

sms.status_updated

Útil quando você envia confirmações do seu próprio número e precisa saber se realmente chegaram. Se o status for failed, o código de erro e a mensagem da operadora estão no payload.

payload
{
  "event_type": "sms.status_updated",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
    "message_id": "42",
    "old_status": "sent",
    "new_status": "delivered",
    "error_code": null,
    "error_message": null
  }
}

Restauração de números concluída

number.restore_completed

Contém duas listas — quais números voltaram e quais não. O valor reembolsado pelos que falharam também está no payload. Prático para scripts que tentam novamente de forma inteligente.

payload
{
  "event_type": "number.restore_completed",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "restored": [
      {
        "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
        "phone_number": "+46764794425",
        "country": "SE"
      }
    ],
    "failed": [
      {
        "piv_num_id": "abc12-defgh-ijklm-nopqr",
        "phone_number": "+46123456789",
        "country": "SE",
        "refunded": 7.50
      }
    ],
    "total_restored": 1,
    "total_failed": 1,
    "total_refunded": 7.50
  }
}

Verificação Google QR bem-sucedida

verify.completed

Se um SMS com código chegou durante o processo, já está aqui — não é necessária uma busca extra. captured_phone e captured_message contêm o que o Google enviou.

payload
{
  "event_type": "verify.completed",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "task_id": 12,
    "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
    "status": "sms_sent",
    "captured_phone": "+14155551234",
    "captured_message": "Your Google verification code is 123456",
    "sms_message_id": 42,
    "sms_status": "queued"
  }
}

Verificação Google QR falhou

verify.failed

error_code informa o que especificamente — timeout, rejeição, URL inválida. Verificações com falha são reembolsadas ao saldo automaticamente.

payload
{
  "event_type": "verify.failed",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "task_id": 12,
    "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
    "status": "failed",
    "error_code": "VERIFY_TIMEOUT",
    "error_message": "Verification timed out"
  }
}

Proxy expirando em breve

proxy.expires_soon

Ideal para quem não renova automaticamente: você vê com antecedência e decide — estender ou encerrar a campanha. Conecte ao POST /proxy/orders/{id}/renew para renovação totalmente automática.

payload
{
  "event_type": "proxy.expires_soon",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "order_id": "ord-uuid-...",
    "country": "DE",
    "quantity": 10,
    "expires_at": "2026-05-25T00:00:00Z"
  }
}

Domínio registrado

domain.registered

Se você solicitou Cloudflare e SSL na compra, ambos já estão ativos — cloudflare_enabled reflete o status. Você pode adicionar registros DNS ou implantar o site imediatamente.

payload
{
  "event_type": "domain.registered",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "domain_id": "dom-uuid-...",
    "domain_name": "mysite.com",
    "registered_at": "2026-05-22T12:34:56Z",
    "expires_at": "2027-05-22T12:34:56Z",
    "cloudflare_enabled": true
  }
}

Registro de domínio falhou

domain.failed

O campo error tem uma razão legível por humanos. O custo é reembolsado ao saldo. Escolha outro nome e tente novamente.

payload
{
  "event_type": "domain.failed",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "domain_id": "dom-uuid-...",
    "domain_name": "mysite.com",
    "error": "Domain is no longer available"
  }
}

Domínio expirando em breve

domain.expires_soon

Útil quando a renovação automática está desativada: você tem tempo para renovar manualmente antes que o domínio entre em redenção. O sinalizador auto_renew indica se é necessária intervenção.

payload
{
  "event_type": "domain.expires_soon",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "domain_id": "dom-uuid-...",
    "domain_name": "mysite.com",
    "expires_at": "2026-05-29T00:00:00Z",
    "auto_renew": false
  }
}

White gerado

white.completed

O arquivo está disponível via GET /whites/{id}/download. Se o White tinha um domínio configurado, o sitemap e contatos já estão vinculados a ele — pronto para deploy.

payload
{
  "event_type": "white.completed",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "job_id": "job-uuid-...",
    "name": "My White",
    "tier_key": "t1",
    "country": "DE"
  }
}

Geração do White falhou

white.failed

O campo error explica o motivo. Inicie um novo trabalho via POST /whites — sem perda de dinheiro.

payload
{
  "event_type": "white.failed",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "job_id": "job-uuid-...",
    "name": "My White",
    "error": "Generation failed"
  }
}
Referência

Códigos de erro

Todos os erros seguem o mesmo formato: status HTTP + campo error.code + mensagem legível em error.message.

CódigoHTTPQuando dispara
UNAUTHORIZED401Chave ausente, expirada ou revogada.
INSUFFICIENT_PERMISSIONS403A chave não possui o scope necessário para esta ação.
PERMISSION_DENIED403O acesso no nível da conta não permite esta ação (ex.: funcionalidade desativada).
VALIDATION_ERROR400Corpo da requisição inválido. A mensagem explica qual campo falhou e por quê.
NUMBER_NOT_FOUND404O número não existe ou não pertence à conta.
NUMBER_EXPIRED403O número expirou — use Restore (dentro de 7 dias) ou compre um novo.
NUMBER_NOT_ACTIVE400O número está em um estado que não permite esta operação.
INSUFFICIENT_BALANCE402Saldo insuficiente para esta operação.
INVALID_MESSAGE_FORMAT400O corpo do SMS é muito longo ou contém caracteres não permitidos.
COUNTRY_NOT_AVAILABLE400O país não está disponível para compra ou renovação.
NO_NUMBERS_AVAILABLE400Não há números disponíveis no país escolhido no momento.
NO_RESTORABLE_NUMBERS404Nenhum dos números fornecidos pode ser restaurado.
RATE_LIMITED429Rate limit excedido. Aguarde o tempo indicado no cabeçalho Retry-After.
INTERNAL_ERROR500Algo deu errado do nosso lado. Se persistir, entre em contato com o suporte.
Exemplo de erro
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Not enough balance: required $5.00, available $1.20"
  }
}

Encontrou uma falha ou precisa de um endpoint que não está aqui? O suporte responde no Telegram em até uma hora durante o horário comercial.

Contatar suporte
piv.day Documentação da API — números, domínios, proxies, white pages