Referência da API

API da Pearfy

API REST para automatizar produtos, ofertas, vendas e reembolsos, e receber eventos em tempo real por webhook. Autenticação por chave, respostas em JSON e um contrato previsível — em poucas linhas você integra a sua stack à Pearfy.

Base https://app.pearfy.com/api/v1

Introdução

URL base: https://app.pearfy.com/api/v1

Todas as respostas são JSON. Toda comunicação é sobre HTTPS. O versionamento é por caminho (/v1). Todos os valores monetários são inteiros em centavos de real (BRL) — 19700 = R$ 197,00.

A API é 100% autenticada por chave do produtor e cada chave só enxerga os dados da própria conta. Não há endpoint de sessão/JWT aqui.

Ferramentas

Especificação OpenAPI 3.1 (importe no seu gerador de client) e coleção Postman (importe e preencha a variável api_key para testar).

Autenticação

As chaves são geradas no painel em Apps → API. Elas têm o prefixo pk_live_ e são mostradas uma única vez na criação — guarde com segurança (o servidor só armazena um hash). Cada chave carrega um conjunto de escopos que definem o que ela pode fazer.

Enviando a chave

Aceitamos a chave de duas formas equivalentes, em todos os endpoints:

# Recomendado — cabeçalho Authorization
curl https://app.pearfy.com/api/v1/products \
  -H "Authorization: Bearer pk_live_sua_chave"

# Alternativa — cabeçalho x-api-key
curl https://app.pearfy.com/api/v1/products \
  -H "x-api-key: pk_live_sua_chave"

OAuth 2.0 (client credentials)

Para SDKs que falam OAuth, há um endpoint de token compatível. Ele recebe a sua chave como client_secret e devolve um access_token Bearer — que é a própria chave. Use qualquer um dos dois fluxos.

POST/oauth/tokensem escopo

Troca a chave por um access_token Bearer.

Corpo (JSON ou form-urlencoded)
CampoTipo Descrição
client_secretstringobrig.Sua chave pk_live_… (ou envie em client_id).
grant_typestringopc.Opcional. client_credentials. É ignorado.
Resposta
{
  "access_token": "pk_live_sua_chave",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "products sales stats"
}
expires_in é apenas indicativo. O token é a própria chave — ela vale enquanto não for revogada ou expirada no painel, não necessariamente 24 h. Não há refresh token.

Escopos

Cada chave concede um ou mais escopos. Os endpoints exigem:

EscopoDá acesso a
productsLer e escrever produtos e ofertas
salesListar e ler vendas (alias: orders)
sales_refundReembolsar vendas (alias: refunds)
statsLer estatísticas (alias: reports)
Fail-closed. Uma chave sem o escopo necessário recebe 403 insufficient_scope. Uma chave revogada ou expirada recebe 401 invalid_api_key. O endpoint /account-details responde a qualquer chave válida, mas os camposdocument e phone só saem para chaves com o escopoaccount — sem ele, a resposta vem sem esses campos, e não com null.

Primeira chamada

Valide sua chave e descubra os escopos dela com o endpoint de conta:

curl https://app.pearfy.com/api/v1/account-details \
  -H "Authorization: Bearer pk_live_sua_chave"
{
  "id": "a1b2c3d4-...",
  "legal_name": "Sua Empresa LTDA",
  "document": "00000000000000",
  "phone": "+5515999999999",
  "created_at": "2026-01-15T12:34:56.000Z",
  "scopes": ["products", "sales", "stats"]
}

Deu 200? Você já está integrado. Siga para Produtos ou Vendas.

Rate limits

  • 300 requisições / minuto em /api/v1/*.
  • 60 requisições / minuto em /oauth/token.

Ao exceder, a resposta é 429 com o cabeçalho Retry-After (segundos) e os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Respeite o Retry-After e use backoff exponencial.

HTTP/1.1 429 Too Many Requests
Retry-After: 42
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-07-12T12:01:00.000Z

{ "error": "Muitas requisições. Tente novamente em instantes." }

Erros

Erros retornam um JSON com um código curto em error, às vezes com detail/message ou required.

HTTPerrorQuando
401missing_api_keyNenhum cabeçalho de chave enviado
401invalid_api_keyChave inexistente, revogada ou expirada
403insufficient_scopeA chave não tem o escopo exigido (traz required)
404not_foundRecurso inexistente ou de outra conta
422invalid_requestFalha de validação do corpo (traz detail)
422not_refundableVenda não está em estado reembolsável
422insufficient_receivablesO saldo a receber da conta não cobre o estorno. A equipe financeira é avisada e cuida da devolução. Não adianta repetir
422boleto_requires_bank_accountVenda paga no boleto: o estorno precisa dos dados bancários do comprador. Fale com o suporte para concluir. Não adianta repetir
429—Rate limit excedido
500internal_errorErro interno
502gateway_errorFalha ao processar o estorno no provedor de pagamento

Paginação

As listas aceitam page_size (padrão 50, máx. 100) e page_number (padrão 1). As respostas de lista vêm num envelope:

{
  "object": "list",
  "pagination": { "page_size": 50, "page_number": 1, "count": 137 },
  "data": [ /* … */ ]
}

count é o total exato de registros (não o tamanho da página).

Conta

GET/account-detailssem escopo

Dados da conta do produtor dono da chave e os escopos concedidos a ela. Não exige escopo — serve para validar a credencial.

Resposta
{
  "id": "uuid",
  "legal_name": "Sua Empresa LTDA",
  "document": "00000000000000",
  "phone": "+5515999999999",
  "created_at": "2026-01-15T12:34:56.000Z",
  "scopes": ["products", "sales", "stats"]
}
200 OK401 chave inválida404 conta não encontrada

Produtos

Objeto Produto: id (ID curto de 6 caracteres, ex. K7M3Q9: o mesmo que aparece no navegador em /produtos/id/K7M3Q9 e o que os apps pedem), uuid (identificador longo, formato anterior), name, slug, status (publicado/rascunho/arquivado), type (curso/ebook/mentoria/software/assinatura), description, delivery, created_at, updated_at.

Nos caminhos com {id} de produto vale o ID curto ou o uuid.

delivery é um array de formas de entrega ativas: pearfy_members · external · email_access · payment_only. Um produto pode ter mais de uma. Vazio significa entrega ainda não configurada, e payment_only é exclusivo: quando aparece, é o único item.
Produto excluído (pelo painel ou por DELETE /products/{id}) deixa de existir na API: some da lista (e do count da paginação) e responde 404 not_found no detalhe, na edição, na exclusão e nas rotas de ofertas. Antes ele continuava na lista com status: "arquivado"; quem sincronizava exclusões por esse status deve tratar o sumiço (ou o 404) como exclusão. Produto arquivado sem ter sido excluído continua aparecendo normalmente.
GET/productsescopo: products

Lista os produtos da conta (mais recentes primeiro, paginado). Produtos excluídos não aparecem.

Query
CampoTipo Descrição
page_sizeintopc.Itens por página (1–100, padrão 50).
page_numberintopc.Página (padrão 1).
200 lista401 auth403 escopo
POST/productsescopo: products

Cria um produto (nasce em rascunho) já com a oferta padrão no preço informado.

Corpo
CampoTipo Descrição
namestringobrig.2–120 caracteres.
priceintobrig.Preço da oferta padrão, em centavos.
typeenumopc.curso · ebook · mentoria · software · assinatura. Padrão curso.
descriptionstringopc.Até 2000 caracteres.
payment_typeenumopc.unico · assinatura.
recurrenceenumopc.monthly · quarterly · semiannual · annual (se assinatura).
curl -X POST https://app.pearfy.com/api/v1/products \
  -H "Authorization: Bearer pk_live_..." -H "Content-Type: application/json" \
  -d '{ "name": "Meu Curso", "price": 19700, "type": "curso" }'
201 criado422 invalid_request403 escopo
GET/products/{id}escopo: products

Detalhe de um produto da conta.

200 OK404 não encontrado
PATCH/products/{id}escopo: products

Edita campos e/ou muda o status. Publicar (status: "publicado") aplica as mesmas travas do painel: produto completo + verificação de identidade (KYC) aprovada.

Corpo (todos opcionais)
CampoTipo Descrição
namestringopc.2–120 caracteres.
descriptionstringopc.Até 2000.
typeenumopc.curso · ebook · mentoria · software · assinatura.
statusenumopc.publicado · rascunho · arquivado.
delivery_typesarrayopc.Substitui as formas de entrega. pearfy_members · external · email_access · payment_only. Array vazio é recusado com 422; payment_only enviado junto com outros elimina os demais.
delivery_urlurlopc.URL de acesso. Exigida por external, e serve como link de email_access.
delivery_instructionsstringopc.Instruções enviadas ao comprador. Cobrem o que email_access exige quando não há URL.
Mexer na entrega de um produto já publicado sem enviar status reavalia a completude. Se o estado final ficar incompleto, o produto é rebaixado para rascunho em vez de a edição ser recusada, e a resposta traz unpublished: { reason, missing }.
200 OK (pode vir com unpublished)422 not_publishable / kyc_required404 não encontrado
DELETE/products/{id}escopo: products

Exclui o produto. A partir daí ele não aparece mais na API (lista, detalhe e ofertas respondem como se não existisse).

{ "id": "uuid", "deleted": true }
200 OK404 não encontrado

Ofertas

Objeto Oferta: id, product_id, name, code, checkout_url, price (centavos), currency, payment_methods (pix/credit_card/boleto), installments_max, is_default, active, recurrence, recurrence_limit, created_at.

Na entrada o cartão é card; na saída ele é serializado como credit_card.
GET/products/{id}/offersescopo: products

Lista todas as ofertas do produto (oferta padrão primeiro). Não paginado — envelope { object: "list", data: [] }.

POST/products/{id}/offersescopo: products

Cria uma oferta (máx. 10 ativas por produto).

Corpo
CampoTipo Descrição
priceintobrig.Em centavos.
namestringopc.Até 80 caracteres.
payment_methodsstring[]opc.Subconjunto de pix/card/boleto. Padrão: todos.
installments_maxintopc.1–12 (padrão 12).
recurrence_periodenumopc.monthly · quarterly · semiannual · annual (torna a oferta recorrente).
recurrence_limitintopc.2–120 cobranças (se recorrente).
is_defaultboolopc.Torna esta a oferta padrão do produto.
201 criada422 offer_limit404 produto
PATCH/products/{id}/offers/{offerId}escopo: products

Edita uma oferta (price, payment_methods, installments_max, recurrence_limit, is_default, active, name).

DELETE/products/{id}/offers/{offerId}escopo: products

Remove a oferta. Não é possível remover a última oferta ativa (422 last_offer) nem a oferta padrão (422 default_offer). Oferta que já teve pedido é desativada em vez de apagada, e a resposta traz deactivated: true.

Vendas & Reembolso

Objeto Venda: id, reference, status, payment_method, created_at, updated_at, approved_date, refunded_at, currency, charge_amount (bruto, centavos), net_amount (líquido do produtor, centavos), product, customer.

Status: paid · waiting_payment · refused · refunded · chargedback.

GET/salesescopo: sales

Lista as vendas da conta (mais recentes primeiro, paginado). Pedidos de teste não entram.

Query
CampoTipo Descrição
statusenumopc.paid · waiting_payment · refused · refunded · chargedback.
payment_methodenumopc.pix · credit_card · boleto.
product_idstringopc.Filtra por produto: ID curto (K7M3Q9) ou uuid.
start_dateISOopc.created_at ≥ start_date.
end_dateISOopc.created_at ≤ end_date.
page_size / page_numberintopc.Paginação (ver acima).
{
  "object": "list",
  "pagination": { "page_size": 50, "page_number": 1, "count": 137 },
  "data": [
    {
      "id": "a1b2...", "reference": "or_...", "status": "paid",
      "payment_method": "pix", "created_at": "...", "approved_date": "...",
      "refunded_at": null, "currency": "BRL",
      "charge_amount": 9700, "net_amount": 8588,
      "product": { "id": "K7M3Q9", "uuid": "3f8a1c2e-..." },
      "customer": { "name": "Fulano", "email": "f@x.com", "cpf": "000...", "mobile": "5511..." }
    }
  ]
}
GET/sales/{id}escopo: sales

Detalhe de uma venda. Igual ao item da lista, mas com product.name resolvido.

200 OK404 não encontrada
POST/sales/{id}/refundescopo: sales_refund

Reembolsa uma venda aprovada. O estorno é feito de verdade no provedor de pagamento e, ao concluir, revoga o acesso do comprador, cancela a assinatura vinculada, debita o saldo do produtor e dispara o webhook compra_reembolsada. Operação síncrona e idempotente.

curl -X POST https://app.pearfy.com/api/v1/sales/{id}/refund \
  -H "Authorization: Bearer pk_live_..."

# → { "id": "a1b2...", "status": "refunded" }
200 refunded422 not_refundable422 insufficient_receivables422 boleto_requires_bank_account502 gateway_error404 não encontrada
Só há estorno total. Reembolso parcial ainda não é suportado pela API.

Estatísticas

GET/statsescopo: stats

Agregado de vendas da conta num período (padrão: últimos 30 dias). Pedidos de teste não entram.

Query
CampoTipo Descrição
start_dateISOopc.Início (padrão: 30 dias atrás).
end_dateISOopc.Fim (padrão: agora).
{
  "period": { "start_date": "...", "end_date": "..." },
  "orders_count": 42,
  "sales_count": 30,
  "refunded_count": 3,
  "gross_amount": 1500000,
  "net_amount": 1275000,
  "currency": "BRL",
  "by_currency": {
    "BRL": { "orders_count": 40, "sales_count": 28, "refunded_count": 3, "gross_amount": 1500000, "net_amount": 1275000 },
    "USD": { "orders_count": 2, "sales_count": 2, "refunded_count": 0, "gross_amount": 19400, "net_amount": 17000 }
  }
}
gross_amount e net_amount vêm em centavos (apesar do nome sem _cents).orders_count conta pedidos de todos os status; sales_count só os aprovados. Os valores do topo somam só vendas em BRL; vendas em outra moeda nunca são somadas como real.by_currency traz contagens e valores de cada moeda presente no período (BRL incluso), em centavos da própria moeda.

Webhooks — eventos & payload

Cadastre endpoints em Webhooks no painel: informe uma URL HTTPS pública, escolha os eventos e (opcionalmente) restrinja a um produto. Ao salvar, você recebe um secret (whsec_…) — mostrado uma vez — usado para verificar a assinatura. A Pearfy faz um POST no seu endpoint a cada evento inscrito.

Eventos disponíveis

EventoQuando dispara
compra_aprovadaPagamento aprovado (Pix, cartão, boleto ou upsell)
pix_geradoPix criado, aguardando pagamento
boleto_geradoBoleto emitido
compra_recusadaPagamento recusado
compra_reembolsadaVenda reembolsada
chargebackChargeback recebido
subscription_renewedAssinatura renovada (nova cobrança)
subscription_canceledAssinatura cancelada
subscription_lateAssinatura em atraso (dunning)

Formato do payload

Cabeçalhos de toda entrega: x-pearfy-event, x-pearfy-delivery (id único da entrega — use para idempotência), x-pearfy-signature, user-agent: Pearfy-Webhooks/1.0.

{
  "id": "5f3c...-uuid",
  "event": "compra_aprovada",
  "webhook_event_type": "compra_aprovada",
  "created_at": "2026-07-12T12:00:00.000Z",
  "data": {
    "order": {
      "id": "ord_1", "status": "paid", "amount_cents": 9700,
      "payment_method": "pix", "gateway": "pearfy", "offer_id": "off_1",
      "is_subscription": false, "created_at": "...", "paid_at": "...", "refunded_at": null
    },
    "customer": { "email": "cli@x.com", "name": "Cliente", "document": "000...", "phone": "+55..." },
    "product": { "id": "K7M3Q9", "uuid": "3f8a1c2e-...", "name": "Curso X", "slug": "curso-x", "payment_type": "unico", "recurrence": null }
    // "subscription": { ... }  ← presente apenas em eventos de assinatura
  }
}

Verificar a assinatura

O cabeçalho x-pearfy-signature tem o formato sha256=<hex>, onde hex é o HMAC-SHA256 do corpo cru da requisição usando o secret do endpoint. Recompute e compare em tempo constante antes de confiar no evento.

import crypto from "crypto";

// Express: use o corpo CRU (raw), não o JSON já parseado.
function verify(rawBody, signatureHeader, secret) {
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody, "utf8").digest("hex");
  const a = Buffer.from(signatureHeader || "", "utf8");
  const b = Buffer.from(expected, "utf8");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post("/pearfy/webhook", express.raw({ type: "application/json" }), (req, res) => {
  if (!verify(req.body, req.header("x-pearfy-signature"), process.env.PEARFY_WEBHOOK_SECRET)) {
    return res.status(401).end();
  }
  const evt = JSON.parse(req.body.toString("utf8"));
  // idempotência: ignore se já processou evt.id (== x-pearfy-delivery)
  res.status(200).end(); // responda 2xx rápido; processe em background
});

Entrega & retry

  • Responda 2xx para confirmar. Qualquer outro status (ou timeout de 10 s) agenda nova tentativa.
  • Até 6 tentativas com backoff de 1 min · 5 min · 30 min · 2 h · 6 h · 12 h.
  • Cada entrega tem um x-pearfy-delivery único — deduplique por ele (a mesma entrega pode chegar mais de uma vez).
  • Sua URL deve ser HTTPS pública. Endereços internos/privados são bloqueados. Você acompanha as entregas (status e resposta) no painel.

Limitações conhecidas

Transparência para quem integra — o que a API ainda não faz:

  • Os escopos financial, affiliates, events e webhooks podem ser concedidos a uma chave, mas ainda não têm endpoint REST correspondente. A gestão de webhooks é feita pelo painel.
  • Ofertas criadas pela API ainda não recebem code/checkout_url automático — para o link direto de checkout, defina a oferta no painel.
  • POST /products não aceita entrega. O produto nasce sem forma de entrega e não publica até você definir delivery_types por um PATCH (ou pelo painel).
  • O reembolso é sempre total; não há reembolso parcial.
  • Existe um endpoint legado GET /orders com formato interno diferente — prefira sempre GET /sales.
Pearfy Tecnologia e Serviços LTDA · API v1 · Base https://app.pearfy.com/api/v1. Dúvidas de integração: fale com o suporte pelo painel ou escreva para produtores@pearfy.com.br.