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.
Basehttps://app.pearfy.com/api/v1Introduçã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.
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.
Troca a chave por um access_token Bearer.
| Campo | Tipo | Descrição | |
|---|---|---|---|
| client_secret | string | obrig. | Sua chave pk_live_… (ou envie em client_id). |
| grant_type | string | opc. | Opcional. client_credentials. É ignorado. |
{
"access_token": "pk_live_sua_chave",
"token_type": "Bearer",
"expires_in": 86400,
"scope": "products sales stats"
}Escopos
Cada chave concede um ou mais escopos. Os endpoints exigem:
| Escopo | Dá acesso a |
|---|---|
| products | Ler e escrever produtos e ofertas |
| sales | Listar e ler vendas (alias: orders) |
| sales_refund | Reembolsar vendas (alias: refunds) |
| stats | Ler estatísticas (alias: reports) |
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.
| HTTP | error | Quando |
|---|---|---|
| 401 | missing_api_key | Nenhum cabeçalho de chave enviado |
| 401 | invalid_api_key | Chave inexistente, revogada ou expirada |
| 403 | insufficient_scope | A chave não tem o escopo exigido (traz required) |
| 404 | not_found | Recurso inexistente ou de outra conta |
| 422 | invalid_request | Falha de validação do corpo (traz detail) |
| 422 | not_refundable | Venda não está em estado reembolsável |
| 422 | insufficient_receivables | O saldo a receber da conta não cobre o estorno. A equipe financeira é avisada e cuida da devolução. Não adianta repetir |
| 422 | boleto_requires_bank_account | Venda 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 |
| 500 | internal_error | Erro interno |
| 502 | gateway_error | Falha 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
Dados da conta do produtor dono da chave e os escopos concedidos a ela. Não exige escopo — serve para validar a credencial.
{
"id": "uuid",
"legal_name": "Sua Empresa LTDA",
"document": "00000000000000",
"phone": "+5515999999999",
"created_at": "2026-01-15T12:34:56.000Z",
"scopes": ["products", "sales", "stats"]
}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.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.Lista os produtos da conta (mais recentes primeiro, paginado). Produtos excluídos não aparecem.
| Campo | Tipo | Descrição | |
|---|---|---|---|
| page_size | int | opc. | Itens por página (1–100, padrão 50). |
| page_number | int | opc. | Página (padrão 1). |
Cria um produto (nasce em rascunho) já com a oferta padrão no preço informado.
| Campo | Tipo | Descrição | |
|---|---|---|---|
| name | string | obrig. | 2–120 caracteres. |
| price | int | obrig. | Preço da oferta padrão, em centavos. |
| type | enum | opc. | curso · ebook · mentoria · software · assinatura. Padrão curso. |
| description | string | opc. | Até 2000 caracteres. |
| payment_type | enum | opc. | unico · assinatura. |
| recurrence | enum | opc. | 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" }'Detalhe de um produto da conta.
Edita campos e/ou muda o status. Publicar (status: "publicado") aplica as mesmas travas do painel: produto completo + verificação de identidade (KYC) aprovada.
| Campo | Tipo | Descrição | |
|---|---|---|---|
| name | string | opc. | 2–120 caracteres. |
| description | string | opc. | Até 2000. |
| type | enum | opc. | curso · ebook · mentoria · software · assinatura. |
| status | enum | opc. | publicado · rascunho · arquivado. |
| delivery_types | array | opc. | 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_url | url | opc. | URL de acesso. Exigida por external, e serve como link de email_access. |
| delivery_instructions | string | opc. | Instruções enviadas ao comprador. Cobrem o que email_access exige quando não há URL. |
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 }.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 }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.
card; na saída ele é serializado como credit_card.Lista todas as ofertas do produto (oferta padrão primeiro). Não paginado — envelope { object: "list", data: [] }.
Cria uma oferta (máx. 10 ativas por produto).
| Campo | Tipo | Descrição | |
|---|---|---|---|
| price | int | obrig. | Em centavos. |
| name | string | opc. | Até 80 caracteres. |
| payment_methods | string[] | opc. | Subconjunto de pix/card/boleto. Padrão: todos. |
| installments_max | int | opc. | 1–12 (padrão 12). |
| recurrence_period | enum | opc. | monthly · quarterly · semiannual · annual (torna a oferta recorrente). |
| recurrence_limit | int | opc. | 2–120 cobranças (se recorrente). |
| is_default | bool | opc. | Torna esta a oferta padrão do produto. |
Edita uma oferta (price, payment_methods, installments_max, recurrence_limit, is_default, active, name).
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.
Lista as vendas da conta (mais recentes primeiro, paginado). Pedidos de teste não entram.
| Campo | Tipo | Descrição | |
|---|---|---|---|
| status | enum | opc. | paid · waiting_payment · refused · refunded · chargedback. |
| payment_method | enum | opc. | pix · credit_card · boleto. |
| product_id | string | opc. | Filtra por produto: ID curto (K7M3Q9) ou uuid. |
| start_date | ISO | opc. | created_at ≥ start_date. |
| end_date | ISO | opc. | created_at ≤ end_date. |
| page_size / page_number | int | opc. | 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..." }
}
]
}Detalhe de uma venda. Igual ao item da lista, mas com product.name resolvido.
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" }Estatísticas
Agregado de vendas da conta num período (padrão: últimos 30 dias). Pedidos de teste não entram.
| Campo | Tipo | Descrição | |
|---|---|---|---|
| start_date | ISO | opc. | Início (padrão: 30 dias atrás). |
| end_date | ISO | opc. | 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 }
}
}_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
| Evento | Quando dispara |
|---|---|
| compra_aprovada | Pagamento aprovado (Pix, cartão, boleto ou upsell) |
| pix_gerado | Pix criado, aguardando pagamento |
| boleto_gerado | Boleto emitido |
| compra_recusada | Pagamento recusado |
| compra_reembolsada | Venda reembolsada |
| chargeback | Chargeback recebido |
| subscription_renewed | Assinatura renovada (nova cobrança) |
| subscription_canceled | Assinatura cancelada |
| subscription_late | Assinatura 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,eventsewebhookspodem 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_urlautomático — para o link direto de checkout, defina a oferta no painel. POST /productsnão aceita entrega. O produto nasce sem forma de entrega e não publica até você definirdelivery_typespor umPATCH(ou pelo painel).- O reembolso é sempre total; não há reembolso parcial.
- Existe um endpoint legado
GET /orderscom formato interno diferente — prefira sempreGET /sales.
https://app.pearfy.com/api/v1. Dúvidas de integração: fale com o suporte pelo painel ou escreva para produtores@pearfy.com.br.