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, 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 SVG diretamente.

Autenticação & limites de uso

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

Para autenticar, envie sua chave no cabeçalho HTTP:

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.

^* 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.

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=svg, o corpo da resposta é a imagem binária, pronta para salvar ou exibir diretamente.

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,
  "scan_count": 12,
  "image_url": "/api/v1/qrcode/qr_AbC123XyZ789/image"
}

Obter a imagem de um QR Code salvo

Retorna o PNG (padrão) ou SVG (?format=svg) do QR Code, já com estilo, cor e logotipo aplicados. Cada chamada incrementa o contador de escaneamentos (scan_count).

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

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.