API de Parceiros

Quem usa

Dois perfis de parceiro acessam a mesma API com chaves distintas. O escopo de cada chave (criar/editar/ler) é definido pela QueroApoiar no momento da emissão.

Início rápido

1. Receba a chave

A chave é emitida pela QueroApoiar após a assinatura do contrato. Cada parceiro recebe duas: uma de homologação ({sigla}_test_…) e outra de produção ({sigla}_live_…).

2. Faça a primeira chamada

Copiar# Listar candidatos do seu partido
curl https://api.queroapoiar.com.br/api/parceiros/candidatos \
  -H "X-API-Key: {sua_chave}"

Copiarconst response = await fetch(
  "https://api.queroapoiar.com.br/api/parceiros/candidatos",
  { headers: { "X-API-Key": process.env.QA_API_KEY } }
);
const { items } = await response.json();
console.log(items);

Copiarimport os, requests

resp = requests.get(
    "https://api.queroapoiar.com.br/api/parceiros/candidatos",
    headers={"X-API-Key": os.environ["QA_API_KEY"]},
)
print(resp.json())

Copiar<?php
$ch = curl_init("https://api.queroapoiar.com.br/api/parceiros/candidatos");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: " . getenv("QA_API_KEY")]);
$resp = curl_exec($ch);
echo $resp;

3. Cadastre um candidato

Copiarcurl -X POST https://api.queroapoiar.com.br/api/parceiros/candidatos \
  -H "X-API-Key: {sua_chave}" \
  -H "Content-Type: application/json" \
  -d '{
    "cpf": "12345678900",
    "nome": "Maria Silva Santos",
    "nomeUrna": "Maria do Bairro",
    "email": "[email protected]",
    "telefone": "11999998888",
    "cargo": "deputado_federal",
    "uf": "SP",
    "municipio": "São Paulo",
    "tituloEleitor": "123456789012",
    "genero": "F",
    "slug": "maria-do-bairro"
  }'

O campo cargo tem 13 valores possíveis (enum fechado). A API rejeita qualquer valor fora dessa lista com 422 CARGO_INVALIDO. Veja a lista completa em Cargos válidos.

Os campos genero (M/F) e slug são opcionais. genero personaliza o tratamento no email de boas-vindas (Bem-vindo / Bem-vinda); se omitido, é inferido do cargo. slug define a URL pública (queroapoiar.com.br/{slug}); se omitido, é gerado de nomeUrna; se ocupado, retorna 409 SLUG_OCUPADO.

O candidato recebe um e-mail com link para definir a senha. Em seguida paga a taxa de inscrição, valida o celular e a campanha vai ao ar.

Partidos

Use a API para pré-cadastrar candidatos antes da abertura das campanhas. Substitui digitação manual e mantém o CRM interno sincronizado com a plataforma.

Endpoints disponíveis

Volume

Até 1.000 candidatos: chamadas individuais ou dois lotes de 500. Acima disso, use sempre /candidatos/lote - retorna um jobId para acompanhar o processamento.

LGPD. O acesso a doações com PII completa (nome, CPF e e-mail do doador) requer DPA assinado entre o partido e a QueroApoiar.

Contadores

Chave configurada em modo somente leitura. Permite extrair candidatos e doações do escritório para prestação de contas eleitoral, sem risco de alteração.

Endpoints disponíveis

Extrair doações do mês

Copiarcurl "https://api.queroapoiar.com.br/api/parceiros/doacoes?desde=2026-09-01&ate=2026-09-30&status=paga&limite=100" \
  -H "X-API-Key: {sua_chave}"

Resposta com doador (nome, CPF, e-mail), valor, forma de pagamento e gateway - campos suficientes para gerar o FCC e a prestação no SPCE.

Autenticação

Toda chamada inclui o cabeçalho X-API-Key. O backend identifica o parceiro pela chave e filtra os recursos automaticamente - cada parceiro só vê o próprio escopo.

CopiarX-API-Key: {sigla}_{ambiente}_{token}

# Exemplos:
X-API-Key: pt_live_a3f9b2c8d1e4f7a0b3c6d9e2f5a8b1c4
X-API-Key: pmdb_test_e5c1a8b2d6f9c3e7a0b4d8f1c5e9a2b6

Estrutura da chave

• {sigla} - código do partido em minúsculas (ex.: pt, pmdb)
• {ambiente} - live (produção) ou test (homologação)
• {token} - 48 caracteres hexadecimais aleatórios

Segurança. Armazene a chave em cofre de senhas (1Password, AWS Secrets Manager, Vault). Nunca comite no Git ou cole em planilhas. Em caso de suspeita de vazamento, solicite rotação - a chave antiga é invalidada imediatamente.

Fluxo de cadastro

Sequência disparada quando o parceiro cria um candidato via API até a campanha entrar no ar:

1. Pré-cadastro - API cria conta, perfil eleitoral e campanha em estado pendente.
2. E-mail - candidato recebe link para definir a senha.
3. Primeiro acesso - ao clicar, define a senha e entra no painel.
4. Pagamento - candidato paga a inscrição (responsabilidade dele).
5. SMS - validação do celular obrigatória por regulação.
6. Publicação - campanha vai ao ar e passa a receber doações.

Quem paga a inscrição. O partido cadastra sem custo via API. Cada candidato paga a própria taxa de inscrição ao ativar a campanha - adesão individual e em conformidade com a legislação.

Escopo e permissões

Cada chave carrega um conjunto de permissões granulares definido pela QueroApoiar no momento da emissão.

Sem a permissão necessária, a API retorna 403 PERMISSAO_NEGADA. Permissões podem ser alteradas pelo painel administrativo sem rotacionar a chave.

Rate limits

Excedido o limite por minuto, a API responde 429 RATE_LIMIT_EXCEDIDO com Retry-After em segundos. Excedida a quota diária, responde 429 QUOTA_DIARIA_EXCEDIDA e reseta às 00h UTC.

CopiarHTTP/1.1 429 Too Many Requests
Retry-After: 60
RateLimit-Limit: 600
RateLimit-Remaining: 0
RateLimit-Reset: 60
Content-Type: application/json

{
  "erro": "RATE_LIMIT_EXCEDIDO",
  "mensagem": "Limite de 600 requisições por minuto excedido para esta chave."
}

Webhooks

Configure a webhookUrl no momento de criação da chave para receber notificações assinadas (HMAC-SHA256). A URL fica amarrada à chave e não pode ser sobrescrita por requisição — pra trocar, peça atualização ao admin.

Eventos suportados

O admin define quais eventos a chave recebe via filtro webhookEventos. Vazio = todos os tipos liberados pelas permissões da chave.

Headers do POST

CopiarPOST {sua webhookUrl}
Content-Type: application/json
X-QA-Signature: t=<unix_seconds>,v1=<hmac_hex>
X-QA-Timestamp: <unix_seconds>
X-QA-Event: <type>
X-QA-Event-Id: evt_<uuid_hex>
X-QA-Api-Version: 2026-05
User-Agent: QueroApoiar-Webhook/1.0

Body (envelope padronizado)

Copiar{
  "id": "evt_a1b2c3d4...",
  "type": "donacao.confirmada",
  "apiVersion": "2026-05",
  "createdAt": "2026-05-09T15:30:00.000Z",
  "data": { ... }
}

O conteúdo de data varia conforme o type. Para eventos de doação, traz data.donacao com o objeto Doação completo. Para candidatos_lote.concluido, traz data.jobId, data.total, data.sucessos, data.erros e data.resultados[].

Validação da assinatura

1. Reconstrua a mensagem como ${'${X-QA-Timestamp}'}.${'${rawBody}'} — use exatamente os bytes recebidos, sem reparsear o JSON.
2. Calcule HMAC-SHA256(webhookSecret, mensagem) em hexadecimal.
3. Compare em tempo constante com o valor de v1 do header.
4. Rejeite se |now - X-QA-Timestamp| > 300 (5 min) — protege contra replay.

Copiarconst crypto = require("crypto");

function validarAssinatura(rawBody, headers, secret) {
  // Header vem como "t=1715274600,v1=abc123..."
  const sig = headers["x-qa-signature"] || "";
  const parts = Object.fromEntries(
    sig.split(",").map((p) => p.split("=").map((s) => s.trim()))
  );
  const ts = parseInt(parts.t, 10);
  const v1 = parts.v1;
  if (!ts || !v1) return false;

  // Replay protection: rejeita timestamps com mais de 5 minutos
  const agora = Math.floor(Date.now() / 1000);
  if (Math.abs(agora - ts) > 300) return false;

  const mensagem = `${'${ts}'}.${'${rawBody}'}`;
  const esperado = crypto
    .createHmac("sha256", secret)
    .update(mensagem)
    .digest("hex");

  // crypto.timingSafeEqual previne timing attacks
  return v1.length === esperado.length &&
    crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(esperado));
}

// IMPORTANTE no Express: use express.raw() pra preservar o body cru
// app.post("/webhook/qa",
//   express.raw({ type: "application/json" }),
//   (req, res) => {
//     if (!validarAssinatura(req.body.toString("utf8"), req.headers, SECRET)) {
//       return res.sendStatus(401);
//     }
//     const evento = JSON.parse(req.body.toString("utf8"));
//     // ... processa
//     res.sendStatus(200);
//   }
// );

Idempotência e retry

• Use id do envelope (evt_…) pra deduplicar — receber 2x o mesmo id deve descartar a 2ª.
• A QueroApoiar tenta entregar 5 vezes em caso de timeout (10s) ou resposta diferente de 2xx.
• Backoff exponencial: 1 min, 5 min, 30 min, 2h, 12h.
• Ordem dos eventos não é garantida: use data.donacao.status como source of truth, não o type.

Webhook secret. Fornecido junto com a chave de API quando a chave é criada. Não aparece em nenhuma resposta da API depois disso — guarde no cofre. Em caso de suspeita de vazamento, peça rotação ao admin (rotaciona junto com a chave por padrão).

Anti-SSRF. URLs apontando para localhost, IPs privados (10.x, 172.16-31.x, 192.168.x) ou metadata de cloud (169.254.169.254) são rejeitadas no momento do cadastro da chave. Se o admin tentar setar uma URL inválida, o bulk responde 400 WEBHOOK_INVALIDO.

Erros

A API segue convenções HTTP. Toda resposta de erro tem o mesmo formato:

Copiar{
  "erro": "CODIGO_DO_ERRO",
  "mensagem": "Mensagem amigável em português",
  "detalhes": { "campo": "cpf" }
}

Códigos por status

Endpoints

Referência completa com parâmetros, exemplos e execução interativa no Playground.

Candidatos

Doações

Documentos fiscais

Imagens

Jobs assíncronos

Cupons reservados (gratuidades e descontos)

Permite ao partido pré-aplicar um cupom no candidato no momento do cadastro. Útil para gratuidades emitidas pelo admin do QueroApoiar em parceria comercial. O candidato vê o desconto já aplicado no checkout e não precisa digitar o código.

Como funciona

1. Admin do QueroApoiar cria o cupom no painel administrativo (ex: MISSAO-VIP-2026 com gratuidade total ou desconto fixo).
2. Admin habilita a chave do partido com permissão cupons.aplicar e adiciona o cupom em cuponsPermitidos (whitelist).
3. Partido envia POST /candidatos com o campo opcional cupom: "MISSAO-VIP-2026".
4. API valida o cupom (existe, ativo, não esgotado, dentro da validade, tipo "inscrição" ou "ambos") e o associa ao candidato.
5. Quando o candidato abre o painel pra pagar, o cupom já vem pré-aplicado.

Exemplo

Copiarcurl -X POST 'https://api.queroapoiar.com.br/api/parceiros/candidatos' \
  -H 'X-API-Key: missao_live_a3f9b2c8d1e4f7a0b3c6d9e2f5a8b1c4' \
  -H 'Content-Type: application/json' \
  -d '{
    "cpf": "12345678900",
    "nome": "Maria Silva Santos",
    "email": "[email protected]",
    "telefone": "11999998888",
    "cargo": "deputado_estadual",
    "uf": "SP",
    "municipio": "São Paulo",
    "cupom": "MISSAO-VIP-2026"
  }'

Erros possíveis

Cupom é opcional. Se o partido não envia o campo, o candidato paga a inscrição padrão (R$199 ou o que estiver configurado).

Documentos fiscais (FCC + NF)

Endpoints para o partido baixar arquivos FCC (Forma de Contas de Campanha, formato ATSEFCC do TSE) e Notas Fiscais. Útil para prestação de contas e auditoria interna do partido.

Listar FCCs do candidato

Copiarcurl 'https://api.queroapoiar.com.br/api/parceiros/candidatos/12345678900/fccs' \
  -H 'X-API-Key: pt_live_...'

# Resposta
{
  "candidatoCpf": "12345678900",
  "candidatoNome": "Maria do Bairro",
  "total": 2,
  "items": [
    {
      "id": "67c3b8e4f1d29c5e88a0d234",
      "url": "https://arquivos.queroapoiar.com.br/fcc/2026/abc/ATSEFCC00120260930000001.FCC",
      "nomeArquivo": "ATSEFCC00120260930000001.FCC",
      "withdrawRef": "67d4c9f5g2e3a8b9c0d1e2f3",
      "dataSolicitacao": "2026-09-30T14:00:00Z",
      "criadoEm": "2026-09-30T14:00:15Z"
    }
  ]
}

Listar NFs do candidato

Copiarcurl 'https://api.queroapoiar.com.br/api/parceiros/candidatos/12345678900/notas-fiscais' \
  -H 'X-API-Key: pt_live_...'

# Resposta
{
  "candidatoCpf": "12345678900",
  "candidatoNome": "Maria do Bairro",
  "total": 3,
  "items": [
    {
      "id": "67e5d0a6h3f4b9c0d1e2f3a4",
      "tipo": "inscricao",
      "pdfUrl": "https://nfs.queroapoiar.com.br/pdf/...",
      "numero": "00012345",
      "emitidaEm": "2026-04-15T18:30:00Z",
      "valor": 199.00
    },
    {
      "id": "67f6e1b7i4g5c0d1e2f3a4b5",
      "tipo": "saque",
      "pdfUrl": "https://nfs.queroapoiar.com.br/pdf/...",
      "xmlUrl": "https://nfs.queroapoiar.com.br/xml/...",
      "numero": "00012346",
      "emitidaEm": "2026-09-30T15:00:00Z",
      "valor": 1500.00
    }
  ]
}

URLs retornadas são links públicos prontos pra download. URLs da NF têm prazo de validade limitado, consulte sempre via API quando precisar baixar.

Imagens (foto de perfil + capa)

Atualiza a foto de perfil do candidato ou a capa da campanha. Útil para o partido pré-popular as imagens em onboarding em massa.

Especificações

Toda imagem enviada passa por otimização automática: é convertida para WebP, redimensionada para a resolução adequada e compactada sem perda visível. O parceiro pode mandar uma foto grande (até 3 MB) sem se preocupar - a plataforma serve a versão otimizada com tempo de carregamento ideal. Em paralelo, é gerada uma miniatura (campo thumb da resposta) pronta pra listagens.

Exemplo - foto de perfil

Copiarcurl -X POST 'https://api.queroapoiar.com.br/api/parceiros/candidatos/12345678900/foto-perfil' \
  -H 'X-API-Key: pt_live_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "imagemBase64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAAAA..."
  }'

# Resposta
{
  "mensagem": "Foto de perfil atualizada",
  "mediaId": "67g7f2c8j5h6d1e2f3a4b5c6",
  "url": "https://arquivos.queroapoiar.com.br/media/2026/9/30/abc123.jpeg",
  "thumb": "https://arquivos.queroapoiar.com.br/media/2026/9/30/abc123_thumb.jpeg"
}

Exemplo - foto de capa

Copiarcurl -X POST 'https://api.queroapoiar.com.br/api/parceiros/candidatos/12345678900/foto-capa' \
  -H 'X-API-Key: pt_live_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "imagemBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  }'

Erros possíveis

Taxas e valores

A plataforma cobra duas categorias de taxa: a taxa de inscrição (paga uma vez pelo candidato) e a taxa por doação (descontada do valor que entra na conta de campanha). Esta seção é informativa para que o parceiro entenda o impacto financeiro no candidato.

Taxa de inscrição

Pago uma única vez por candidato, antes de a campanha ir ao público. Os valores acima são verificados em runtime contra o valor configurado no admin - mude lá que novos cadastros pegam o novo na próxima request, sem deploy.

Taxas por doação (campanha eleitoral)

Exemplo: doação de R$ 100 via PIX → R$ 1,99 vai pra plataforma, R$ 98,01 entra como saldo da campanha (campo netValue da doação).

Outras taxas

Prazo de liberação do dinheiro

O prazo conta a partir da confirmação do pagamento (campo paidAt da doação). Antes desse prazo, o saldo aparece como pendente. Pagar a taxa de antecipação adianta a liberação.

Valores em homologação (ambiente test): a taxa de inscrição em homologação geralmente está reduzida (R$ 5,00 ou similar) pra acelerar testes. Em produção, valor cheio.

Campos opcionais úteis

genero (M ou F)

Personaliza o tratamento no email de boas-vindas (Bem-vindo ou Bem-vinda) e em outras comunicações de gênero. Aceita "M", "F", "Masculino" ou "Feminino". Recomendado passar: sem o campo, é inferido do cargo com heurística que erra quando o nome não bate com o sexo padrão do cargo (ex: cargo "vereador" sempre vira Masculino, mesmo se for "Maria").

slug (URL pública customizada)

Define a URL onde a campanha do candidato fica acessível: https://queroapoiar.com.br/{slug}.

• 3 a 50 caracteres, apenas a-z 0-9 -
• Tem que começar com letra ou número
• Se omitido, gerado de nomeUrna (ou nome) com sufixo do partido se ocupado
• Se fornecido e já ocupado, retorna 409 SLUG_OCUPADO — parceiro decide qual outro slug usar (não adiciona sufixo silencioso)
• Se reservado pelo sistema (admin, painel, api e similares), retorna 422 SLUG_RESERVADO
• Se inválido (caracteres proibidos, fora do range), retorna 422 SLUG_INVALIDO

Recomendado: passe slug quando o candidato tiver uma identidade digital pré-existente (ex: já é conhecido como @joaodasilva) e você queira que a URL pública combine com isso.

Cargos válidos

O campo cargo aceita exatamente 13 valores. Use o slug (em snake_case minúsculo). Qualquer outro valor causa 422 CARGO_INVALIDO.

Os campos uf e municipio são sempre obrigatórios, mesmo para cargos estaduais ou federais. Para cargos sem município (presidente, governador, senador), use a capital ou município de domicílio eleitoral.

Partidos

O partido vinculado a uma chave de API é definido pela QueroApoiar no momento da emissão da chave (escolhido a partir da lista canônica abaixo). Você não envia o partido nas requisições de cadastro: ele é inferido automaticamente da chave e aplicado a todos os candidatos criados por ela.

A lista canônica segue o registro oficial do TSE. Caso seu partido tenha cancelado ou recebido novo registro, fale com nosso comercial para revisarmos a chave.

Partidos com registro ativo

Os nomes acima são case-sensitive na exibição (ex: Novo, não NOVO). Em comparações internas o sistema é tolerante a variações de caixa, mas os valores apresentados ao candidato seguem este formato.

Objeto Candidato

Copiar{
  "id": "67a3b8e4f1d29c5e88a0d234",
  "cpf": "12345678900",
  "nome": "Maria Silva Santos",
  "nomeUrna": "Maria do Bairro",
  "email": "[email protected]",
  "telefone": "11999998888",
  "cargo": "deputado_federal",
  "uf": "SP",
  "municipio": "São Paulo",
  "numeroCandidato": "12345",
  "tituloEleitor": "123456789012",
  "partido": "Partido Exemplo",
  "urlPublicaCampanha": "https://queroapoiar.com.br/maria-do-bairro",
  "status": "aguardando_senha",
  "inscricaoPaga": false,
  "celularValidado": false,
  "emailVerificado": false,
  "campanhaPublicada": false,
  "totalArrecadado": 0,
  "qtdDoacoes": 0,
  "criadoEm": "2026-09-20T15:42:18Z",
  "criadoViaApi": true
}

Estados possíveis

Objeto Doação

Copiar{
  "id": "67a3...",
  "data": "2026-09-15T14:32:00Z",
  "valor": 100.00,
  "formaPagamento": "pix",
  "status": "paga",
  "candidatoCpf": "12345678900",
  "doador": {
    "nome": "João da Silva",
    "cpf": "98765432100",
    "email": "[email protected]"
  }
}

Changelog

v1.0.0 - Maio de 2026

• Lançamento da API de Parceiros em homologação
• Endpoints para gestão de candidatos
• Endpoints de leitura de doações
• Webhooks assinados com HMAC SHA-256
• Cadastro em lote assíncrono via fila

Suporte

• E-mail: [email protected]
• Status: api.queroapoiar.com.br/api/health

Ao reportar incidentes, inclua o prefixo da chave (16 primeiros caracteres), horário, resposta recebida e volume estimado de chamadas afetadas.