GeradorPixDOCUMENTAÇÃO DA API
API V1 ESTÁVEL ABRIR PAINEL
API PÚBLICA · PIX · ROTAS · WEBHOOKS

INTEGRE UMA VEZ. GERE PIX EM QUALQUER FLUXO.

Conecte seu backend ao GeradorPix, gere cobranças e troque chaves ou gateways pelo painel sem reescrever sua integração.

7 OPERAÇÕESOPENAPI 3.10% GERADORPIX POR TRANSAÇÃO
COMEÇAR AGORA
GERADORPIX_API_V1● ONLINE
07OPERAÇÕES04EVENTOS04PLANOS API
> seleção: automática
> troca de rota: painel
> resposta: JSON
> status pago: manual
01 / AUTENTICAÇÃO

SUAS CHAVES FICAM NO BACKEND.

AUTH

Todas as chamadas usam a base /api/v1 e as credenciais geradas em Chave API no painel.

!

Nunca exponha a Secret Key. Use a API somente no servidor. Não coloque sk_live_... em navegador, aplicativo público, repositório, analytics ou logs.

02 / MODOS

VOCÊ ESCOLHE O MODO. O PAINEL CONTROLA A ROTA.

MODE

O request não recebe dados bancários nem credenciais do gateway. O GeradorPix usa somente os recursos ativos e compatíveis com o valor.

PREMIUM+

chave_pix

Escolhe automaticamente uma chave Pix ativa dentro da faixa configurada.

PERSONALIZADO+

personalizado

Executa os gateways configurados no servidor sem expor suas credenciais.

03 / PRIMEIRA COBRANÇA

UM POST. PIX PRONTO.

POST

Envie valor, descrição e referência do seu pedido. A resposta retorna o identificador, o Pix Copia e Cola e o status inicial PENDENTE.

POST /pixIdempotency-Key obrigatória
CURL
curl --request POST \
  --url https://api.geradorpix.com/api/v1/pix \
  --header 'User-Agent: GeradorPixB2B/1.0' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-GPix-Public-Key: pk_live_SUA_CHAVE_PUBLICA' \
  --header 'X-GPix-Secret-Key: sk_live_SUA_CHAVE_SECRETA' \
  --header 'Idempotency-Key: pedido-1842-v1' \
  --data '{"mode":"chave_pix","amount":"49.90","description":"Pedido 1842","external_reference":"pedido-1842"}'
201 CREATEDRESPOSTA
{
  "ok": true,
  "data": {
    "id": "0f62a527-0f21-4bf2-b293-8c6def06a781",
    "status": "PENDENTE",
    "mode": "chave_pix",
    "amount": "49.90",
    "copy_paste": "000201010212..."
  },
  "request_id": "7c4aa379-2d89-4d25-851e-6b4106532318"
}
04 / RETRIES

UMA INTENÇÃO. UMA COBRANÇA.

SAFE

Crie a chave antes da primeira tentativa e reutilize a mesma Idempotency-Key nos retries da mesma intenção.

01CRIEpedido-1842-v1
02REUTILIZEpedido-1842-v1
03NOVA INTENÇÃOpedido-1842-v2
05 / STATUS

PAGO É UMA MARCAÇÃO MANUAL.

STATE

PAGO significa que sua integração ou operador marcou o item. Não representa liquidação, consulta bancária ou comprovante automático.

01PENDENTEgerado e aguardando decisão
POST/pix/{id}/paidmarcar pagoPOST/pix/{id}/pendingvoltar pendente
06 / RELATÓRIOS

RESUMO PAGO EM TRÊS JANELAS.

GET

GET /reports/paid-summary retorna dia, mês e ano usando America/Sao_Paulo e apenas itens B2B marcados manualmente como PAGO.

DIA12R$ 845,50MÊS83R$ 5.930,40ANO624R$ 41.892,10
07 / WEBHOOKS

EVENTOS ASSINADOS COM HMAC.

HOOK

Configure a URL e o segredo whsec_... no painel. Valide timestamp e assinatura sobre o corpo bruto antes de interpretar o JSON.

pix.createdPix persistido
pix.paidmarcado PAGO
pix.unpaidvoltou PENDENTE
pix.deleteditem removido
VALIDAÇÃO HMAC
signed = timestamp + "." + raw_body
expected = "sha256=" + HMAC_SHA256(webhook_secret, signed)
constant_time_compare(expected, X-GPix-Webhook-Signature)
08 / ERROS

ERROS PREVISÍVEIS. DEBUG DIRETO.

ERR

Toda resposta mantém o envelope JSON. Guarde o request_id, trate o código de erro e nunca registre suas chaves.

401invalid_credentialsheaders ou chaves inválidas
409idempotency_conflictmesma chave, body diferente
422invalid_amountpayload semanticamente inválido
429rate_limitedaguarde Retry-After
REFERÊNCIA

TODAS AS OPERAÇÕES.

API

Esta tabela é renderizada diretamente do contrato OpenAPI 3.1.

EXEMPLOS

COMECE NA SUA STACK.

CODE

Use variáveis de ambiente para as chaves e preserve a Idempotency-Key entre retries.

CURL
curl -X GET 'https://api.geradorpix.com/api/v1/pix?limit=5' \
  -H 'User-Agent: GeradorPixB2B/1.0' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-GPix-Public-Key: pk_live_SUA_CHAVE_PUBLICA' \
  -H 'X-GPix-Secret-Key: sk_live_SUA_CHAVE_SECRETA'
PHP
$headers = [
  'User-Agent: GeradorPixB2B/1.0',
  'Accept: application/json',
  'Content-Type: application/json',
  'X-GPix-Public-Key: ' . getenv('GPIX_PUBLIC_KEY'),
  'X-GPix-Secret-Key: ' . getenv('GPIX_SECRET_KEY')
];
NODE.JS
const headers = {
  'User-Agent': 'GeradorPixB2B/1.0',
  'Accept': 'application/json',
  'Content-Type': 'application/json',
  'X-GPix-Public-Key': process.env.GPIX_PUBLIC_KEY,
  'X-GPix-Secret-Key': process.env.GPIX_SECRET_KEY
};
PYTHON
headers = {
    'User-Agent': 'GeradorPixB2B/1.0',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'X-GPix-Public-Key': os.environ['GPIX_PUBLIC_KEY'],
    'X-GPix-Secret-Key': os.environ['GPIX_SECRET_KEY'],
}