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.

Cada recurso tem duas formas: a consolidada (/fccs e /notas-fiscais), que devolve os documentos de todos os candidatos do partido paginados numa chamada só, e a por candidato (/candidatos/{cpf}/...), quando você já sabe de quem quer os arquivos.

O escopo é por campanha, não por pessoa: você recebe os documentos das campanhas que o seu partido tem na plataforma. Se um candidato seu disputou uma eleição anterior por outro partido, os documentos daquela campanha não aparecem.

Listar FCCs de todos os candidatos do partido

Copiarcurl 'https://api.queroapoiar.com.br/api/parceiros/fccs?desde=2026-09-01&limite=200' \
  -H 'X-API-Key: pt_live_...'

# Resposta
{
  "total": 143,
  "pagina": 1,
  "limite": 200,
  "items": [
    {
      "id": "67c3b8e4f1d29c5e88a0d234",
      "candidatoCpf": "12345678900",
      "candidatoNome": "Maria do Bairro",
      "url": "https://queroapoiar.com.br/api/fcc/download/exec?id=67c3b8e4f1d29c5e88a0d234&t=9f2c...",
      "nomeArquivo": "ATSEFCC00120260930000001.FCC",
      "withdrawRef": "67d4c9f5a2e3a8b9c0d1e2f3",
      "dataSolicitacao": "2026-09-30T14:00:00Z",
      "substituidoEm": null,
      "criadoEm": "2026-09-30T14:00:15Z"
    }
  ]
}

Filtros: candidatoCpf, desde, ate (data de geração do FCC), pagina e limite (padrão 200, máx. 500). Ordem: mais recente primeiro. Quando substituidoEm vem preenchido, aquele FCC virou histórico — uma doação do saque foi estornada depois da emissão e um arquivo novo foi gerado no lugar. Não envie o substituído ao TSE.

Listar NFs de todos os candidatos do partido

Copiarcurl 'https://api.queroapoiar.com.br/api/parceiros/notas-fiscais?tipo=saque' \
  -H 'X-API-Key: pt_live_...'

# Resposta
{
  "total": 88,
  "pagina": 1,
  "limite": 50,
  "items": [
    {
      "id": "67f6e1b7a4g5c0d1e2f3a4b5",
      "candidatoCpf": "12345678900",
      "candidatoNome": "Maria do Bairro",
      "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,
      "referenciaCriadaEm": "2026-09-30T14:00:00Z"
    }
  ]
}

Filtros: tipo (inscricao ou saque), candidatoCpf, desde, ate (data de emissão), pagina e limite (padrão 200, máx. 500). Só aparecem NFs já emitidas, ordenadas da mais recente para a mais antiga. Sem o filtro tipo, os dois tipos vêm intercalados por data e pagina × limite não pode passar de 5000 — para paginar fundo, informe o tipo.

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://queroapoiar.com.br/api/fcc/download/exec?id=67c3b8e4f1d29c5e88a0d234&t=9f2c...",
      "nomeArquivo": "ATSEFCC00120260930000001.FCC",
      "withdrawRef": "67d4c9f5a2e3a8b9c0d1e2f3",
      "dataSolicitacao": "2026-09-30T14:00:00Z",
      "substituidoEm": null,
      "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
    }
  ]
}

As URLs retornadas já baixam o arquivo direto, sem precisar mandar a chave de API junto: a do FCC é um link assinado do nosso endpoint de download e a da NF aponta pro provedor de notas fiscais. As duas podem expirar ou ser rotacionadas, então consulte sempre via API na hora de baixar em vez de guardar a URL.

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.