Ir para o conteúdo
White page Kit
Português

Documentação da API

Crie sites whitepage, acompanhe seu progresso e baixe os arquivos a partir do seu próprio código, de uma ferramenta no-code ou simplesmente pedindo a um assistente de IA. Toda requisição é JSON via HTTPS.

Como funciona

Três passos, independentemente de como você se conecte:

  1. Crie uma chave API Entre, abra as chaves API no painel e crie uma chave. Ela funciona como uma senha para sua conta, portanto mantenha-a em sigilo.
  2. Peça um site Envie um título e um idioma, e se desejar, o tópico, o público e as palavras-chave. O preço da geração será deduzido do seu saldo e o site começará a ser construído.
  3. Colete seu site Normalmente fica pronto em alguns minutos. Verifique seu status ou permita que chamemos sua URL quando terminar, então visualize, edite e baixe os arquivos.

Escolha como você se conecta

Ferramentas no-code: qualquer coisa que possa enviar uma requisição HTTP (Zapier, Make, n8n, um script de planilha) pode executar as mesmas chamadas. POST /sites inicia um site; GET /sites/{uuid}, em um temporizador ou um callback_url, informa quando está concluído. Coloque a chave da API no cabeçalho Authorization.

Termos-chave

Site
Um site gerado com todas as suas páginas. É identificado por um uuid.
Estado
pendente enquanto está sendo construído, concluído quando está pronto, erro se falhou. Um site com falha é reembolsado automaticamente.
Chave da API
Uma string secreta que prova que uma requisição vem da sua conta. Crie e revogue chaves no painel de controle.
Saldo
Dinheiro pré-pago em sua conta. Criar um site reserva o preço da geração a partir dele.
Callback
Uma URL sua que chamamos uma vez quando um site termina, para que você não precise ficar verificando.
Chave de idempotência
Um rótulo que você anexa a uma requisição para que enviá-la duas vezes nunca crie, ou cobre por, dois sites.

Use com assistentes de IA

Conecte um assistente de IA e simplesmente pergunte: "Faça um site para minha clínica odontológica, em turco." O assistente chama a mesma API na sua conta. Você mantém o controle: criar um site custa saldo, e bons assistentes perguntam antes de fazer isso.

Coisas que você pode dizer

  • Quanto saldo eu tenho e quanto custa um site?
  • Quais kits de design são adequados para uma padaria?
  • Create a one-page site for Alder House, a quiet harbour guesthouse, in English.
  • Meu site está pronto? Envie-me o link de visualização.

Conectar via MCP (Claude, Cursor e mais)

MCP é o padrão aberto que os assistentes usam para chamar ferramentas externas. Aponte seu assistente para o URL do MCP e forneça sua chave API como token Bearer.

Claude Code

bash

claude mcp add --transport http whitepagekit https://whitepagekit.com/api/v1/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "whitepagekit": {
      "url": "https://whitepagekit.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:WPK_API_KEY}"
      }
    }
  }
}

Claude Desktop

claude_desktop_config.json

{
  "mcpServers": {
    "whitepagekit": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://whitepagekit.com/api/v1/mcp",
               "--header", "Authorization:${WPK_AUTH}"],
      "env": { "WPK_AUTH": "Bearer YOUR_API_KEY" }
    }
  }
}

JSON-RPC bruto

curl

curl -X POST https://whitepagekit.com/api/v1/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_account","arguments":{}}}'

Claude Desktop alcança servidores remotos através da ponte mcp-remote, que precisa do Node.js.

ChatGPT (GPT personalizado)

  1. No ChatGPT crie um GPT, abra Configurar e escolha Criar nova ação.
  2. Escolha Importar de URL e cole https://whitepagekit.com/api/v1/openapi.json?profile=assistant. Este esquema reduzido contém apenas as seis ferramentas do assistente.
  3. Em Autenticação escolha Chave API, defina o Tipo de Autenticação para Bearer e cole sua chave API.
  4. O ChatGPT pede que você confirme solicitações que alteram algo, para que você mantenha o controle sobre qualquer coisa que custe saldo.

Schema URL

https://whitepagekit.com/api/v1/openapi.json?profile=assistant

API OpenAI (ferramenta MCP)

A API de Respostas pode usar o URL do MCP como uma ferramenta remota. require_approval mantém um humano no processo.

Python

from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="YOUR_MODEL",
    tools=[{
        "type": "mcp",
        "server_label": "whitepagekit",
        "server_url": "https://whitepagekit.com/api/v1/mcp",
        "headers": {"Authorization": "Bearer YOUR_API_KEY"},
        "require_approval": "always",
    }],
    input="What does one site cost, and which design kits suit a bakery?",
)
print(response.output_text)

Seu próprio loop de ferramenta (chamada de função)

Se você mesmo executar o loop do modelo, obtenha esquemas de ferramentas prontos e execute cada chamada de ferramenta no endpoint REST correspondente. Formatos: openai (API de Respostas), openai-chat, anthropic e mcp.

curl

curl "https://whitepagekit.com/api/v1/ai-tools?format=openai"   # or openai-chat, anthropic, mcp

As seis ferramentas

As seis ferramentas
Ferramenta O que faz Chamada REST Custo
get_account Mostra seu saldo e quanto custa um site. GET /me Grátis
list_languages Lista os idiomas nos quais um site pode ser escrito. GET /languages Grátis
list_themes Pesquisa os kits de design por tópico ou estilo. GET /themes Grátis
create_site Inicia a geração de um site e desconta o preço da geração do seu saldo. POST /sites Usa saldo
get_site Mostra um site: progresso, link de pré-visualização e link de download. GET /sites/{uuid} Grátis
list_sites Lista seus sites, do mais novo para o mais antigo. GET /sites Grátis

Dê qualquer documentação para a IA

Esta página também está disponível em Markdown simples, ideal para colar em um chat ou entregar a um assistente de codificação:

Markdown

https://whitepagekit.com/api/v1/docs.md

Um prompt que você pode colar

Prompt

You can build websites with the White Page Kit API. Read https://whitepagekit.com/api/v1/docs.md first.
My API key is in the environment variable WPK_API_KEY.
Check my balance and the price, then create a site for my dental clinic in Izmir, in Turkish,
wait until it is ready and send me the preview link.

Segurança e custo

  • Apenas create_site consome saldo. As outras cinco ferramentas apenas leem.
  • Use uma chave separada para assistentes. Defina uma data de expiração e um limite de taxa no painel, e revogue-a a qualquer momento.
  • Assistentes não podem deletar sites, alterar configurações ou mexer em pagamentos: essas rotas não são expostas como ferramentas.
  • Defina idempotency_key em create_site para que uma nova tentativa nunca cobre duas vezes. Gerações falhadas são reembolsadas.
  • Edição de páginas, imagens de referência e downloads ZIP permanecem na API REST e no painel.

Início rápido

Três chamadas levam você de um briefing a um site para download. Substitua YOUR_API_KEY por uma chave do painel.

1. Iniciar uma geração

POST /sites valida seu briefing, reserva o preço da geração do seu saldo e retorna imediatamente.

curl

curl -X POST https://whitepagekit.com/api/v1/sites \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-attempt-1" \
  -d '{"title":"Alder House","lang":"en","sector":"guesthouse","keywords":"quiet stay, harbour","structure":"onepage"}'

A resposta é 202 Accepted com o novo site:

202 Accepted

{
  "success": true,
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "status": "pending",
    "title": "Alder House",
    "lang": "en",
    "preview_url": null,
    "download_url": null
  }
}

2. Consultar o status

Consulte GET /sites/{uuid} a cada 5–20 segundos até o status ser feito ou erro, ou use uma URL de callback em vez da consulta.

curl

curl https://whitepagekit.com/api/v1/sites/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: YOUR_API_KEY"

3. Baixar os arquivos

Um site finalizado é baixado como um ZIP. O formato é multi ou onepage; os assets são inline ou externos.

curl

curl -o site.zip \
  -H "X-API-Key: YOUR_API_KEY" \
  "https://whitepagekit.com/api/v1/sites/550e8400-e29b-41d4-a716-446655440000/download?format=multi&assets=inline"

O mesmo fluxo em código

PHP

<?php
$ch = curl_init('https://whitepagekit.com/api/v1/sites');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('WPK_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: order-1042-attempt-1',
    ],
    CURLOPT_POSTFIELDS => json_encode(['title' => 'Alder House', 'lang' => 'en']),
]);
$site = json_decode(curl_exec($ch), true)['data'];
do {
    sleep(5);
    $ch = curl_init('https://whitepagekit.com/api/v1/sites/' . $site['uuid']);
    curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('WPK_API_KEY')]]);
    $site = json_decode(curl_exec($ch), true)['data'];
} while ($site['status'] === 'pending');

Node.js

const headers = {
  Authorization: `Bearer ${process.env.WPK_API_KEY}`,
  'Content-Type': 'application/json',
  'Idempotency-Key': 'order-1042-attempt-1',
};
let { data: site } = await (await fetch('https://whitepagekit.com/api/v1/sites', {
  method: 'POST', headers,
  body: JSON.stringify({ title: 'Alder House', lang: 'en' }),
})).json();
while (site.status === 'pending') {
  await new Promise((r) => setTimeout(r, 5000));
  ({ data: site } = await (await fetch(`https://whitepagekit.com/api/v1/sites/${site.uuid}`, { headers })).json());
}

Python

import os, time, requests

headers = {"Authorization": f"Bearer {os.environ['WPK_API_KEY']}",
           "Idempotency-Key": "order-1042-attempt-1"}
site = requests.post("https://whitepagekit.com/api/v1/sites", headers=headers,
                     json={"title": "Alder House", "lang": "en"}).json()["data"]
while site["status"] == "pending":
    time.sleep(5)
    site = requests.get(f"https://whitepagekit.com/api/v1/sites/{site['uuid']}", headers=headers).json()["data"]

Autenticação

Envie uma chave API com cada requisição, exceto o documento OpenAPI. Mantenha as chaves no seu servidor; nunca as coloque no código do navegador ou URLs.

  • Cabeçalho: Authorization: Bearer YOUR_API_KEY, ou X-API-Key: YOUR_API_KEY.
  • Crie, revogue e limite a taxa de chaves no painel. As chaves podem ter data de expiração e uma lista de IPs permitidos.
  • Você vê apenas seus próprios sites. Um site pertencente a outra conta retorna 404 not_found.
  • Adicione ?lang=xx ou Accept-Language para localizar mensagens de erro.

Idempotência

Envie Idempotency-Key (8–80 caracteres: letras, dígitos, _ e -) no POST /sites. Repetir a mesma chave retorna o site original e nunca cobra duas vezes, então reenvios após um timeout são seguros. Use uma chave nova para tentar gerar novamente um pedido que falhou.

Webhooks (callbacks)

Passe callback_url para POST /sites (ou configure um webhook de conta) e receba um POST JSON quando o trabalho terminar (site.completed) ou falhar (site.failed).

POST callback_url

{
  "event": "site.completed",
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "status": "done",
  "site_title": "Alder House",
  "lang": "en",
  "domain": null,
  "created_at": "2026-01-15T09:30:00+00:00",
  "preview_url": "https://whitepagekit.com/preview?uuid=550e8400-…"
}

Quando a conta tem um segredo de webhook, cada solicitação carrega X-Webhook-Signature: sha256=<hex>, um HMAC-SHA256 do corpo bruto. Verifique-o antes de analisar o JSON, usando uma comparação em tempo constante:

PHP

$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, $webhookSecret);
if (!hash_equals($expected, $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}

Node.js

import crypto from 'node:crypto';

const expected = 'sha256=' + crypto
  .createHmac('sha256', webhookSecret).update(rawBody).digest('hex');
const received = req.get('x-webhook-signature') ?? '';
const ok = received.length === expected.length
  && crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));

Cada callback é tentado uma vez com um tempo limite de 10 segundos e não é refeito. Trate-o como uma notificação e faça a conciliação com GET /sites/{uuid}. Trate repetições de forma idempotente por uuid e evento. Destinos de rede privada são rejeitados.

Erros

Cada resposta usa um envelope. Erros carregam um código estável, uma mensagem localizada e, para erros de validação, o campo que falhou.

JSON

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "...",
    "details": { "field": "title" }
  }
}
Erros
HTTPCódigos de erro
400 validation_error, invalid_json, invalid_webhook_url
401 missing_api_key
402 insufficient_balance
403 api_disabled, invalid_api_key, forbidden
404 not_found, route_not_found
405 method_not_allowed
409 site_not_ready, conflict, edits_reset_required
413 payload_too_large
415 unsupported_media_type
429 rate_limited
500 internal_error, export_failed
502 generation_failed

Limites

Limites
Limite Valor
Requisições por chave 60 por minuto por padrão (configurável por chave, 0 = ilimitado). Chaves inválidas repetidas de um IP recebem 429 com Retry-After.
Corpo da requisição 2 MB; POST /sites com imagens de referência até 162 MB; editor salva até 4 MB.
Imagens de referência Até 12 imagens PNG, JPEG ou WEBP (base64 ou URL de dados), no máximo 10 MB cada.
Conteúdo da página do editor HTML até 500.000 caracteres, CSS até 100.000. Scripts e manipuladores de eventos são removidos.
Imagens do site PNG, JPEG, WEBP ou GIF, 5 MB cada, até 200 por site.
Título do site Título do site 1–200 caracteres.

Editor API

Tudo o que o editor do painel faz está disponível para seus sites finalizados: conteúdo da página, plano de página e seção, estilo, título/tema/layout/estrutura, rastreamento e imagens. As edições da página substituem a página; DELETE restaura a página gerada.

curl

# Load, change and save a page
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://whitepagekit.com/api/v1/sites/UUID/editor?page=index"
curl -X PATCH https://whitepagekit.com/api/v1/sites/UUID/editor \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"index","html":"<main>…</main>","css":""}'
# Restore the generated page
curl -X DELETE -H "X-API-Key: YOUR_API_KEY" \
  "https://whitepagekit.com/api/v1/sites/UUID/editor?page=index"

Editar requer um site concluído (409 site_not_ready caso contrário). Alterar tema, layout ou estrutura sobre páginas editadas retorna 409 edits_reset_required a menos que reset_edits seja true. Editar é gratuito.

Referência do endpoint

Gerado a partir do documento OpenAPI, para que sempre corresponda à API ao vivo. Os caminhos são relativos à URL base.

Conta

  • GET /me

    Get the authenticated account

  • GET /transactions

    List account balance transactions

Catálogo

  • GET /languages

    List enabled supported languages

  • GET /themes

    List site themes

  • GET /layouts

    List enabled layouts

Sites

  • GET /sites

    List the authenticated account's sites

  • POST /sites

    Start site generation

  • GET /sites/{uuid}

    Get site status and refresh generation state

  • DELETE /sites/{uuid}

    Delete a terminal site and its generated data — Pending, queued and running generation jobs cannot be deleted. Wait for done or error; active deletion returns 409 conflict without refunding or removing the job.

  • GET /sites/{uuid}/download

    Download a completed site archive

IA e automação

  • GET /ai-tools

    Function-calling tool schemas — The same six tools the MCP endpoint offers, as JSON schemas for your own tool loop. format is openai (Responses API), openai-chat (Chat Completions), anthropic or mcp. Public; no response envelope.

  • GET /docs.md

    Documentation as Markdown — The developer guide, endpoint reference and AI integration guide as one Markdown file, written for language models and quick copy-paste. Public.

  • POST /mcp

    Model Context Protocol endpoint — MCP over Streamable HTTP (JSON-RPC 2.0, one JSON reply per POST). Methods: initialize, ping, tools/list, tools/call. Tools: get_account, list_languages, list_themes, create_site (paid), get_site, list_sites. Authenticate with the same API key; point an MCP client at this URL.

Editor

  • GET /sites/{uuid}/editor

    Load a page for editing — Editor access for the site owner's API key; mirrors the dashboard editor. Only completed sites (409 site_not_ready otherwise).

  • PATCH /sites/{uuid}/editor

    Save a page's edited content — Replaces the page content and CSS. html must be non-empty (use DELETE to restore the generated page); scripts, event handlers and javascript: URLs are removed, HTML is limited to 500000 and CSS to 100000 characters, request body to 4 MB. Returns the saved page as GET does.

  • DELETE /sites/{uuid}/editor

    Restore a page's generated content — Discards the page's saved edits. Returns the regenerated page.

  • GET /sites/{uuid}/editor/canvas

    Get editing canvas data — Stylesheet, Tailwind theme, body class, direction, section blocks, icons and sample copy an external visual editor needs to render the page like the dashboard editor.

  • GET /sites/{uuid}/pages

    Get the page and section plan — Returns structure, pages with their sections and edited flag, one-page sections and the sections available to add. Same payload as the dashboard.

  • POST /sites/{uuid}/pages

    Save the page and section plan — Body: pages (list of {slug, title, nav, sections}; the first page is index) and, for onepage sites, onepage_sections. Sections of pages with saved edits are locked in the dashboard; edited pages that are removed lose their edits. At most 12 pages.

  • GET /sites/{uuid}/style

    Get style overrides — Returns stored overrides, effective colors, fonts, radius and density, and the allowed font, radius and density values.

  • POST /sites/{uuid}/style

    Save or reset style overrides — Send style ({colors, fonts: {heading, body}, radius, density}) or reset=true to return to the theme.

  • GET /sites/{uuid}/design

    Get site title, theme and layout — Returns site_title, title_suggestions, theme_variant, theme_mode, layout, structure and whether the site has saved edits.

  • POST /sites/{uuid}/design

    Change site title, theme, mode, layout or structure — theme_variant, theme_mode, layout and structure are required; site_title (1-200 characters), apply_blueprint and reset_edits are optional. Changing theme, layout or structure while pages have saved edits returns 409 edits_reset_required unless reset_edits is true; renaming alone keeps edits.

  • GET /sites/{uuid}/tracking

    Get tracking settings

  • POST /sites/{uuid}/tracking

    Save tracking settings — Body: tracking {ga4_measurement_id, google_ads_id, google_ads_conversion_label, meta_pixel_id, privacy_policy_url, terms_url}. Applied to exports; an empty object removes all tracking.

  • GET /sites/{uuid}/media

    List uploaded site images

  • POST /sites/{uuid}/media

    Upload or delete site images — multipart/form-data with one or more files in files[] (PNG, JPEG, WEBP or GIF, 5 MB each, at most 200 images per site), or JSON {"action": "delete", "name": <name>}. Returns the updated list for uploads. 409 conflict when the per-site image limit is reached.

Pagamentos externos (apenas chaves de administrador)

  • GET /payment-sites

    List external payment sites owned by the admin API account — Admin role required; payment.manage permission alone is insufficient. Webhook secrets are never returned.

  • POST /payment-sites

    Register an external payment site (admin only)

  • PATCH /payment-sites/{id}

    Update an owned external payment site (admin only)

  • DELETE /payment-sites/{id}

    Delete an owned external payment site (admin only) — Deletion is allowed only when the site has no orders. Sites with orders must be disabled instead.

  • GET /payments

    List external orders owned by the admin API account

  • POST /payments

    Create external checkout or automatic subscription (admin only) — Server-to-server only. Separate from wallet top-ups: no White Page Kit balance, bonus or referral credit. Repeated idempotency key returns the original order; a different payload or reused external order ID conflicts. Provider uncertainty never starts a second checkout automatically.

  • GET /payments/{uuid}

    Read owned external payment status (admin only)

  • POST /payments/{uuid}/cancel

    Cancel an owned subscription or locally close a pending one-time order (admin only) — Subscriptions stop future renewals. Pending one-time cancellation is a local close, not a refund; an already-open provider checkout may still accept payment. A late authenticated real payment remains recorded and notified. No payment is marked paid by a browser return.

  • POST /payments/{uuid}/approve

    Approve funds received for an owned pending or locally cancelled bank transfer (admin only) — Manual confirmation of funds received, including a transfer arriving after local cancellation; never approves a Dodo or Enigmoss order and never credits White Page Kit balance.

As descrições vêm do documento OpenAPI e estão em inglês. Esquemas de requisição e resposta estão no arquivo de esquema.

Integrações prontas

O kit de integração é uma pequena aplicação PHP com um formulário gerador, sondagem de status, orientação para callbacks assinados e um editor visual completo que se comunica com esta API através de um proxy no servidor. Crie uma conta para obter uma chave e veja os preços para o custo de cada geração.