Documentação da API

A API do QRCode Pangeia é pública, aberta e gratuita para começar: gera QR Codes em múltiplos formatos padronizados (texto, URL, e-mail, telefone, SMS, WhatsApp, Lero, Wi-Fi, vCard, geolocalização, evento/calendário e Pix), com suporte a estilos visuais, gradientes e logotipo embutido.

Base URL de produção: https://qrcode.pangeialabs.com. Todas as rotas da API vivem sob o prefixo /api/v1 e respondem em JSON, exceto quando o parâmetro format pede PNG ou WEBP diretamente — ou ao usar o atalho GET, feito para funcionar direto num <img src>.

Autenticação & limites de uso

Nenhuma autenticação é obrigatória. Existem três níveis de acesso:

Para autenticar, envie sua chave sempre pelo cabeçalho HTTP, nunca na URL:

X-API-Key: qrk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Quando o limite é excedido, a API responde 429 Too Many Requests.

Tipos de QR Code suportados

Cada tipo define seus próprios campos de dados, usados no corpo data da requisição de geração (ou como parâmetros soltos na URL no atalho GET).

^* campo obrigatório. Consulte GET /api/v1/types para o schema completo e programático.

Estilos & personalização visual

Disponíveis via os campos style, fg_color, bg_color, gradient_color e gradient_type:

Gradientes disponíveis em gradient_type: radial, square, horizontal, vertical.

Um logotipo pode ser embutido no centro enviando um arquivo de imagem no campo logo (multipart/form-data) ou uma imagem em base64 no campo logo_base64 (JSON). Quando um logotipo é enviado, o nível de correção de erro é automaticamente elevado para H para preservar a leitura do QR Code.

Alguns tipos oferecem um logotipo oficial pronto para uso (hoje: Lero e Pix) — envie use_default_logo=true sem precisar enviar nenhum arquivo. Consulte o campo default_logo_url em GET /api/v1/types para saber quais tipos têm logotipo oficial disponível.

Gerar um QR Code

Aceita application/json (sem logotipo) ou multipart/form-data (com upload de logotipo via campo logo; nesse modo, o campo data deve ser enviado como uma string JSON).

Parâmetros

Exemplo de requisição

cURL

# QR Code de URL, estilo pontilhado, sem autenticação
curl -X POST https://qrcode.pangeialabs.com/api/v1/qrcode \
  -H "Content-Type: application/json" \
  -d '{
    "type": "url",
    "data": { "url": "https://pangeialabs.com" },
    "style": "dots",
    "fg_color": "#111827",
    "gradient_color": "#22d3ee"
  }'

Python

import requests

resp = requests.post(
    "https://qrcode.pangeialabs.com/api/v1/qrcode",
    json={"type": "wifi", "data": {"ssid": "MinhaRede", "security": "WPA", "password": "s3nha-forte"}},
    headers={"X-API-Key": "qrk_sua_chave_aqui"},  # opcional
)
print(resp.json()["image_base64"][:60])

JavaScript (fetch)

const resp = await fetch("https://qrcode.pangeialabs.com/api/v1/qrcode", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ type: "pix", data: {
    pix_key: "11999999999", merchant_name: "Minha Loja", merchant_city: "Sao Paulo", amount: "49.90"
  }}),
});
const { image_base64, payload } = await resp.json();

Exemplo de resposta (format=json, padrão)

{
  "type": "url",
  "payload": "https://pangeialabs.com",
  "image_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

Com format=png ou format=webp, o corpo da resposta é a imagem binária, pronta para salvar ou exibir diretamente.

Atalho GET — usar direto num <img src>

Pensado para quem não programa (ou está começando): os mesmos parâmetros de geração podem ir soltos na própria URL, como parâmetros de querystring — sem precisar de data aninhado. O campo type e os campos específicos do tipo (ver tabela de tipos) viram parâmetros de primeiro nível. O formato padrão já é png.

<img src="https://qrcode.pangeialabs.com/api/v1/qrcode?type=url&url=https://pangeialabs.com&style=dots" alt="QR Code">

# Pix com logo oficial embutido, direto na URL
<img src="https://qrcode.pangeialabs.com/api/v1/qrcode?type=pix&pix_key=11999999999&merchant_name=Minha+Loja&merchant_city=Sao+Paulo&use_default_logo=true">

Aceita os mesmos parâmetros de estilo do POST (style, fg_color, bg_color, gradient_color, gradient_type, error_correction, use_default_logo, format).

Por ser sempre anônimo, o atalho GET está sujeito ao limite de 30/hora por IP (ver limites).

Consultar um QR Code salvo

Retorna os metadados de um QR Code previamente salvo no acervo. Não requer autenticação (o public_id já funciona como um token de acesso não-adivinhável).

curl https://qrcode.pangeialabs.com/api/v1/qrcode/qr_AbC123XyZ789

{
  "id": "qr_AbC123XyZ789",
  "type": "vcard",
  "title": "Cartão de visita",
  "payload": "BEGIN:VCARD...",
  "style": "rounded",
  "has_logo": true,
  "view_count": 12,
  "image_url": "/api/v1/qrcode/qr_AbC123XyZ789/image"
}

Obter a imagem de um QR Code salvo

Retorna o PNG (padrão) ou WEBP (?format=webp) do QR Code, já com estilo, cor e logotipo aplicados. Cada chamada incrementa view_count.

<img src="https://qrcode.pangeialabs.com/api/v1/qrcode/qr_AbC123XyZ789/image" alt="QR Code">

Página pública de compartilhamento

Página HTML (não é endpoint de API) com o QR Code, o dado principal (ex.: para Pix, o nome do favorecido e a descrição do pagamento) e meta tags de SEO/Open Graph prontas pra uma prévia rica ao colar o link no WhatsApp, Twitter/X etc. Todo QR Code criado com save=true ou share=true ganha uma dessas — o campo page_url da resposta traz o caminho.

Imagem PNG 1200×630 usada como og:image da página acima — o QR Code numa moldura branca com o dado principal na base. Não precisa ser chamado diretamente.

https://qrcode.pangeialabs.com/qr_AbC123XyZ789

Editar um QR Code salvo

Requer autenticação (sessão ou API Key) e que o QR Code pertença ao usuário. Aceita os mesmos campos de criação; envie apenas os campos que deseja alterar.

curl -X PUT https://qrcode.pangeialabs.com/api/v1/qrcode/qr_AbC123XyZ789 \
  -H "Content-Type: application/json" -H "X-API-Key: qrk_sua_chave_aqui" \
  -d '{ "title": "Novo título", "fg_color": "#7c3aed" }'

Remover um QR Code salvo

Requer autenticação e propriedade do recurso. Remove o registro e o logotipo associado (se houver).

curl -X DELETE https://qrcode.pangeialabs.com/api/v1/qrcode/qr_AbC123XyZ789 \
  -H "X-API-Key: qrk_sua_chave_aqui"

Listar tipos, estilos e gradientes

Schema completo e sempre atualizado de todos os tipos suportados — ideal para montar formulários dinamicamente. Não requer autenticação.

curl https://qrcode.pangeialabs.com/api/v1/types

Histórico (acervo) do usuário

Lista os QR Codes salvos pelo usuário autenticado, com paginação via page e per_page (máx. 100).

curl "https://qrcode.pangeialabs.com/api/v1/history?page=1&per_page=20" \
  -H "X-API-Key: qrk_sua_chave_aqui"

Informações da API Key

Retorna o plano, o limite de requisições e as estatísticas de uso da API Key autenticada.

curl https://qrcode.pangeialabs.com/api/v1/me -H "X-API-Key: qrk_sua_chave_aqui"

{
  "tier": "free",
  "rate_limit": "300/hour",
  "request_count": 482,
  "last_used_at": "2026-07-27T15:30:00"
}

Gestão de API Keys

Requer login (sessão web via Pangeia ID). Cada conta pode ter até 5 API Keys ativas simultaneamente. Gerencie visualmente em /dashboard/apikeys ou via API:

curl -X POST https://qrcode.pangeialabs.com/api/v1/apikeys \
  -H "Content-Type: application/json" --cookie "session=..." \
  -d '{ "label": "Minha aplicação" }'

Códigos de erro

Erros seguem sempre o mesmo formato:

{ "error": { "code": "VALIDATION_ERROR", "message": "url é obrigatório", "field": "url" } }

Webhooks internos

O QRCode Pangeia recebe (não expõe para terceiros) dois webhooks usados na integração com a plataforma Pangeia: /webhooks/pangeia-id (eventos de conta, validados por assinatura HMAC-SHA256) e /webhooks/pangeia-pay (confirmação de pagamentos via IPN). Eles não fazem parte da API pública de consumo.

OpenAPI & SDKs

A especificação completa em formato OpenAPI 3.0 está disponível em /static/openapi.yaml — use-a para gerar clientes automaticamente (OpenAPI Generator, Swagger Codegen) ou importar em ferramentas como Postman e Insomnia.

Não há SDK oficial ainda: a API é simples o suficiente para ser usada diretamente via HTTP em qualquer linguagem.