Pearfy MCP

Ferramentas

33 ferramentas tipadas: 21 consultas e 12 alterações. Cada uma faz uma coisa só, com parâmetros validados antes de tocar em qualquer dado. Esta lista sai do mesmo registro que o servidor usa.

Resumo

A IA escolhe a ferramenta pela sua pergunta. Você não precisa saber os nomes: eles estão aqui para quem integra, audita ou quer entender o que cada conexão pode fazer.

TipoComo roda
ConsultaRoda direto. Só lê, nunca altera nada.
AlteraçãoA 1ª chamada devolve uma prévia; a 2ª, com o token de confirmação dessa prévia, executa. Reenviar acesso é a exceção: roda direto, com limite diário.
DinheiroReembolso pelo login: código de 6 dígitos enviado ao seu e-mail, com teto por pedido e por dia. Cancelamento de assinatura e dinheiro vindo de chave de IA: aprovação no painel.
Aprovação no painelA 2ª chamada não executa: cria um pedido que fica pendente até alguém com permissão aprovar em Pearfy MCP › Aprovações.
Detalhes da confirmação, dos limites diários e da aprovação no painel em Alterações e segurança. Formato das respostas e erros em Respostas, erros e limites.

Conta

pearfy_quem_souQuem sou eu na PearfyConsultaQualquer credencial

Mostra a conexão atual: conta da Pearfy operada, papel na Equipe, permissões, forma de acesso (login ou chave), escopos da credencial, validade, limites, perfil e ambiente. Não altera nada.

Sem parâmetros.

Vendas e reembolsos

pearfy_resumo_vendasResumo de vendasConsultaConsultar vendas

Totais de vendas da conta num período (hoje, ontem, 7d, 30d, mês atual, mês anterior ou datas): pedidos, aprovadas, reembolsos, chargebacks, faturamento bruto, líquido do produtor e ticket médio, por moeda e somado em R$. Agregado no banco, sem limite de pedidos. Opcionalmente compara com o período anterior.

ParâmetroTipo Descrição
periodoenumopc.Janela de datas no horário de Brasília. "personalizado" usa de e ate. "tudo" = desde o início da conta.
hojeontem7d30dmes_atualmes_anteriorpersonalizadotudo
padrão "30d"
dedataopc.Início (AAAA-MM-DD), só com periodo=personalizado.
AAAA-MM-DD
atedataopc.Fim inclusivo (AAAA-MM-DD), só com periodo=personalizado.
AAAA-MM-DD
compararbooleanoopc.Inclui o período anterior de mesmo tamanho, para comparação.
padrão false

Escopo vendas:ler

pearfy_ranking_produtosRanking de produtosConsultaConsultar vendas

Produtos (ou ofertas) que mais venderam num período, por faturamento bruto ou por número de vendas aprovadas, com reembolsos, chargebacks e líquido de cada um. Uma linha por produto e moeda.

ParâmetroTipo Descrição
periodoenumopc.Janela de datas no horário de Brasília. "personalizado" usa de e ate. "tudo" = desde o início da conta.
hojeontem7d30dmes_atualmes_anteriorpersonalizadotudo
padrão "30d"
dedataopc.Início (AAAA-MM-DD), só com periodo=personalizado.
AAAA-MM-DD
atedataopc.Fim inclusivo (AAAA-MM-DD), só com periodo=personalizado.
AAAA-MM-DD
porenumopc.Agrupa por produto ou por oferta.
produtooferta
padrão "produto"
ordenar_porenumopc.
faturamentoaprovadas
padrão "faturamento"
limiteinteiroopc.
1 a 20 · padrão 10

Escopo vendas:ler

pearfy_vendas_por_regiaoVendas por regiãoConsultaConsultar vendas

Vendas de um período agrupadas por país do comprador (código ISO, ex.: BR, US) ou por estado (UF). Mostra pedidos, aprovadas e faturamento de cada região. Região vazia = não informada.

ParâmetroTipo Descrição
periodoenumopc.Janela de datas no horário de Brasília. "personalizado" usa de e ate. "tudo" = desde o início da conta.
hojeontem7d30dmes_atualmes_anteriorpersonalizadotudo
padrão "30d"
dedataopc.Início (AAAA-MM-DD), só com periodo=personalizado.
AAAA-MM-DD
atedataopc.Fim inclusivo (AAAA-MM-DD), só com periodo=personalizado.
AAAA-MM-DD
nivelenumopc.País do comprador ou estado (UF) do endereço de cobrança.
paisestado
padrão "pais"

Escopo vendas:ler

pearfy_conversao_pagamentosConversão de pagamentosConsultaConsultar vendas

Taxa de aprovação por método de pagamento (Pix gerado × pago, cartão, boleto) num período e os principais motivos de recusa de cartão. Útil para diagnosticar queda de vendas.

ParâmetroTipo Descrição
periodoenumopc.Janela de datas no horário de Brasília. "personalizado" usa de e ate. "tudo" = desde o início da conta.
hojeontem7d30dmes_atualmes_anteriorpersonalizadotudo
padrão "30d"
dedataopc.Início (AAAA-MM-DD), só com periodo=personalizado.
AAAA-MM-DD
atedataopc.Fim inclusivo (AAAA-MM-DD), só com periodo=personalizado.
AAAA-MM-DD

Escopo vendas:ler

pearfy_listar_vendasListar vendasConsultaConsultar vendas

Vendas da conta, da mais recente para a mais antiga, num período (data da venda, horário de Brasília), com filtro opcional por status, método de pagamento, produto e oferta. Inclui vendas em que a conta é co-produtora ou afiliada. Cada venda traz id, datas, status, método, parcelas, valores, produto, oferta, país e o comprador mascarado. Paginada por cursor.

ParâmetroTipo Descrição
periodoenumopc.Janela de datas no horário de Brasília. "personalizado" usa de e ate. "tudo" = desde o início da conta.
hojeontem7d30dmes_atualmes_anteriorpersonalizadotudo
padrão "30d"
dedataopc.Início (AAAA-MM-DD), só com periodo=personalizado.
AAAA-MM-DD
atedataopc.Fim inclusivo (AAAA-MM-DD), só com periodo=personalizado.
AAAA-MM-DD
statuslista de enumopc.Filtra pelos status (vazio = todos).
aprovadoaguardando_pagamentorecusadoexpiradocanceladoreembolsadochargeback
metodolista de enumopc.Filtra pelos métodos de pagamento (vazio = todos).
pixboletocardapple_paygoogle_pay
produto_ididopc.Só vendas deste produto (UUID).
oferta_ididopc.Só vendas desta oferta (UUID).
limiteinteiroopc.Itens por página (1 a 50).
1 a 50 · padrão 25
cursortextoopc.O proximo_cursor da página anterior. Vale 15 minutos e só com os mesmos filtros.
até 200 caracteres

Escopo vendas:ler

pearfy_detalhar_vendaDetalhar vendaConsultaConsultar vendas

Uma venda da conta pelo id (UUID ou os 8 caracteres do painel): status, datas da linha do tempo (criada, paga, reembolsada, cancelada), método, parcelas, produto, oferta, país, comprador mascarado, UTMs da origem e a quebra dos valores (taxa da Pearfy, comissões, líquido e taxa de chargeback, quando houver). Id de venda de outra conta não é encontrado.

ParâmetroTipo Descrição
venda_ididobrig.Id da venda: UUID completo ou os 8 primeiros caracteres mostrados no painel.
papelenumopc.Escolhe a linha quando a conta aparece em mais de um papel na mesma venda.
produtorcoprodutorafiliado

Escopo vendas:ler

pearfy_buscar_compradorBuscar comprador por e-mailConsultaConsultar vendas

Vendas da conta (como produtora) feitas por um comprador, pelo e-mail completo, com igualdade exata. Mostra as compras com status, valores e produto; o comprador aparece mascarado. Limite de 30 buscas por hora por conexão.

ParâmetroTipo Descrição
emailtextoobrig.E-mail completo do comprador. Comparação exata, sem diferenciar maiúsculas.
até 254 caracteres
limiteinteiroopc.Itens por página (1 a 50).
1 a 50 · padrão 25
cursortextoopc.O proximo_cursor da página anterior. Vale 15 minutos e só com os mesmos filtros.
até 200 caracteres

Escopo vendas:ler

pearfy_listar_reembolsos_chargebacksListar reembolsos e chargebacksConsultaConsultar vendas

Vendas reembolsadas e/ou com chargeback da conta, num período pela data da venda (horário de Brasília), da mais recente para a mais antiga. Cada uma traz valores, produto, comprador mascarado, data do reembolso e a taxa de chargeback debitada, quando houver. Paginada por cursor.

ParâmetroTipo Descrição
periodoenumopc.Janela de datas no horário de Brasília. "personalizado" usa de e ate. "tudo" = desde o início da conta.
hojeontem7d30dmes_atualmes_anteriorpersonalizadotudo
padrão "30d"
dedataopc.Início (AAAA-MM-DD), só com periodo=personalizado.
AAAA-MM-DD
atedataopc.Fim inclusivo (AAAA-MM-DD), só com periodo=personalizado.
AAAA-MM-DD
tipoenumopc.
reembolsochargebackambos
padrão "ambos"
limiteinteiroopc.Itens por página (1 a 50).
1 a 50 · padrão 25
cursortextoopc.O proximo_cursor da página anterior. Vale 15 minutos e só com os mesmos filtros.
até 200 caracteres

Escopo vendas:ler

pearfy_reembolsar_vendaReembolsar vendaDinheiroPrévia e confirmaçãoReembolsar vendas

Reembolsa uma venda aprovada da conta pelo valor total. A 1ª chamada devolve só a prévia; por login, a confirmação é um código de 6 dígitos enviado ao e-mail da pessoa conectada. Por chave, acima de R$ 500 ou com mais de 7 dias, vira pedido de aprovação no painel. Remove o acesso do comprador e cancela a assinatura ligada.

ParâmetroTipo Descrição
venda_ididobrig.Id da venda: UUID completo ou os 8 primeiros caracteres mostrados no painel.
confirmacaotextoopc.Vazio na 1ª chamada (devolve a prévia). Na 2ª: o token pfy_cf_ da prévia, ou o código de 6 dígitos que a pessoa recebeu por e-mail.
até 80 caracteres
observacaotextoopc.Motivo em uma frase, só para o registro (aparece como citação).
até 300 caracteres

Escopo reembolsos

Financeiro

pearfy_ver_saldoSaldo da carteiraConsultaConsultar saldo e saques

Saldo da carteira da conta em R$: disponível para saque, a liberar, reserva de segurança, total sacado e saldo devedor, se houver. Quando a conta vende fora do Brasil, traz também o saldo internacional em dólar, separado e sem somar com o R$. Só consulta; não pede saque.

Sem parâmetros.

Escopo financeiro:ler

pearfy_listar_saquesSaques da contaConsultaConsultar saldo e saques

Lista os saques da carteira em R$ da conta, do mais recente para o mais antigo: código, status (processando, pago, rejeitado, cancelado), valor pedido, tarifa, líquido e datas do pedido e do pagamento. Filtra por status e período. Não traz dados bancários e não pede saque.

ParâmetroTipo Descrição
statusenumopc.processando (pedido ainda a caminho), pago, rejeitado ou cancelado. Sem status = todos.
processandopagorejeitadocancelado
periodoenumopc.Data do pedido, no horário de Brasília. Padrão "tudo" (desde o início da conta). "personalizado" usa de e ate.
hojeontem7d30dmes_atualmes_anteriorpersonalizadotudo
padrão "tudo"
dedataopc.Início (AAAA-MM-DD), só com periodo=personalizado.
AAAA-MM-DD
atedataopc.Fim inclusivo (AAAA-MM-DD), só com periodo=personalizado.
AAAA-MM-DD
limiteinteiroopc.Itens por página (1 a 50).
1 a 50 · padrão 25
cursortextoopc.O proximo_cursor da página anterior. Vale 15 minutos e só com os mesmos filtros.
até 200 caracteres

Escopo financeiro:ler

Assinaturas

pearfy_resumo_assinaturasResumo de assinaturasConsultaConsultar assinaturas

Fotografia atual das assinaturas da conta: ativas, inadimplentes (em atraso), canceladas, concluídas, renovações nos próximos 30 dias, MRR bruto e líquido estimado e valor em atraso, por moeda. Para o período escolhido (hoje, 7d, 30d, mês atual, mês anterior, datas ou tudo): novas, canceladas e churn. Com mais de 2.000 assinaturas, o resultado vem marcado como parcial.

ParâmetroTipo Descrição
periodoenumopc.Janela de datas no horário de Brasília. "personalizado" usa de e ate. "tudo" = desde o início da conta.
hojeontem7d30dmes_atualmes_anteriorpersonalizadotudo
padrão "30d"
dedataopc.Início (AAAA-MM-DD), só com periodo=personalizado.
AAAA-MM-DD
atedataopc.Fim inclusivo (AAAA-MM-DD), só com periodo=personalizado.
AAAA-MM-DD

Escopo assinaturas:ler

pearfy_listar_assinaturasListar assinaturasConsultaConsultar assinaturas

Assinaturas da conta, da mais nova para a mais antiga, com situação, produto, plano, valor e intervalo de cada cobrança, método, próxima cobrança, datas de início e cancelamento e o assinante (nome abreviado e e-mail mascarado). Filtros por situação e por produto; paginado por cursor.

ParâmetroTipo Descrição
statuslista de enumopc.Filtra por situação: active (ativa), trial (em teste), overdue (em atraso), canceled (cancelada), completed (concluída). Vazio = todas.
activetrialoverduecanceledcompleted
produto_ididopc.Só as assinaturas deste produto (id completo).
limiteinteiroopc.Itens por página (1 a 50).
1 a 50 · padrão 25
cursortextoopc.O proximo_cursor da página anterior. Vale 15 minutos e só com os mesmos filtros.
até 200 caracteres

Escopo assinaturas:ler

pearfy_detalhar_assinaturaDetalhar assinaturaConsultaConsultar assinaturas

Uma assinatura da conta pelo id (completo ou os 8 primeiros caracteres): situação, produto, plano, valor e intervalo, método, próxima cobrança, assinante mascarado e o histórico de cobranças (status, valor e datas), com total pago por moeda.

ParâmetroTipo Descrição
assinatura_ididobrig.Id da assinatura: UUID completo ou os 8 primeiros caracteres (como no painel).

Escopo assinaturas:ler

pearfy_cancelar_assinaturaCancelar assinaturaDinheiroAprovação no painelCancelar assinaturas

Pede o cancelamento imediato de uma assinatura da conta. Vira pedido de aprovação no painel em todos os casos (o cancelamento no fim do ciclo ainda não existe). Encerra as cobranças, anula a fatura pendente e avisa o assinante; não devolve valor.

ParâmetroTipo Descrição
assinatura_ididobrig.Id da assinatura: UUID completo ou os 8 primeiros caracteres (como no painel).
confirmacaotextoopc.Vazio na 1ª chamada (devolve a prévia). Na 2ª: o token pfy_cf_ da prévia, ou o código de 6 dígitos que a pessoa recebeu por e-mail.
até 80 caracteres
observacaotextoopc.Motivo em uma frase, só para o registro (aparece como citação).
até 300 caracteres

Escopo assinaturas:cancelar

Produtos e ofertas

pearfy_listar_produtosListar produtosConsultaConsultar produtos, ofertas e cupons

Produtos da própria conta (sem os excluídos e sem coproduções ou afiliações), mais recentes primeiro: id, ID público do painel, nome, tipo, cobrança, formas de entrega, status do produtor, moderação, preço da oferta padrão e número de ofertas ativas. Filtro opcional por status. Paginado por cursor.

ParâmetroTipo Descrição
statusenumopc.rascunho, publicado ou arquivado filtram o status do produtor (como o filtro do painel); em_analise, reprovado ou pausado filtram a moderação da Pearfy.
rascunhopublicadoarquivadoem_analisereprovadopausado
limiteinteiroopc.Itens por página (1 a 50).
1 a 50 · padrão 25
cursortextoopc.O proximo_cursor da página anterior. Vale 15 minutos e só com os mesmos filtros.
até 200 caracteres

Escopo produtos:ler

pearfy_detalhar_produtoDetalhar produtoConsultaConsultar produtos, ofertas e cupons

Um produto da própria conta: dados gerais, se vende agora, link principal de checkout, todas as ofertas (preço, moedas, pagamento único ou assinatura e intervalo, ativa, padrão, link), resumo dos cupons e as pendências para publicar, pela mesma regra do painel. Aceita o ID público do painel, o UUID ou os 8 primeiros caracteres dele.

ParâmetroTipo Descrição
produto_ididobrig.ID público do painel (6 caracteres), UUID ou os 8 primeiros caracteres do UUID.
até 36 caracteres

Escopo produtos:ler

pearfy_criar_produtoCriar produtoAlteraçãoPrévia e confirmaçãoCriar e editar produtos e ofertas

Cria um produto em RASCUNHO na própria conta, com a oferta padrão no preço informado (em centavos de real), pagamento único ou assinatura, pela mesma sequência da API v1 (triagem de conteúdo incluída). Nome e descrição com e-mail, telefone, CPF/CNPJ ou link fora da Pearfy são recusados. A 1ª chamada devolve a prévia e o token; a criação só acontece na 2ª, com o token. chave_idempotencia evita duplicar em repetição.

ParâmetroTipo Descrição
nometextoobrig.Nome do produto (2 a 120 caracteres). Sem e-mail, telefone, CPF/CNPJ ou link fora da Pearfy.
até 120 caracteres
descricaotextoopc.Descrição (até 2.000 caracteres), com as mesmas restrições do nome.
até 2000 caracteres
tipoenumopc.
cursoebookmentoriasoftwareassinatura
padrão "curso"
preco_centavosinteiroobrig.Preço da oferta padrão em centavos de real (ex.: 9700 = R$ 97,00).
até 9999900
cobrancaenumopc.assinatura = cobrança recorrente (o tipo "assinatura" também liga isto).
unicoassinatura
padrão "unico"
intervaloenumopc.Frequência da assinatura; padrão mensal. Ignorado em pagamento único.
mensaltrimestralsemestralanual
chave_idempotenciatextoopc.Opcional. Repetir a criação com a mesma chave (e os mesmos parâmetros) em até 24 h devolve o mesmo produto, sem criar outro.
até 64 caracteres
confirmacaotextoopc.Vazio na 1ª chamada (devolve a prévia). Na 2ª: o token pfy_cf_ da prévia, ou o código de 6 dígitos que a pessoa recebeu por e-mail.
até 80 caracteres
observacaotextoopc.Motivo em uma frase, só para o registro (aparece como citação).
até 300 caracteres

Escopo produtos:escrever

pearfy_criar_ofertaCriar ofertaAlteraçãoPrévia e confirmaçãoCriar e editar produtos e ofertas

Cria uma oferta (preço ou plano) num produto da própria conta, em centavos de real, com pagamento único ou assinatura (intervalo e limite de cobranças opcionais). A oferta nasce DESATIVADA e não vira a padrão: entra no checkout só quando ativada no painel ou por pedido aprovado no painel. Até 10 ofertas ativas por produto. A 1ª chamada devolve a prévia e o token; a criação só acontece na 2ª, com o token.

ParâmetroTipo Descrição
produto_ididobrig.ID público do painel (6 caracteres), UUID ou os 8 primeiros caracteres do UUID.
até 36 caracteres
preco_centavosinteiroobrig.Preço em centavos de real (ex.: 4700 = R$ 47,00).
até 9999900
nometextoopc.Nome da oferta (até 80 caracteres), sem contato nem link fora da Pearfy.
até 80 caracteres
intervaloenumopc.Frequência, se a oferta for assinatura. Vazio = segue o produto (pagamento único ou a frequência do produto de assinatura).
mensaltrimestralsemestralanual
limite_cobrancasinteiroopc.Total de cobranças da assinatura (2 a 120). Vazio = sem limite. Só com intervalo.
2 a 120
metodoslista de enumopc.Formas de pagamento; padrão pix, cartao e boleto.
pixcartaoboleto
parcelas_maxinteiroopc.Parcelas máximas no cartão (1 a 12); padrão 12.
1 a 12
confirmacaotextoopc.Vazio na 1ª chamada (devolve a prévia). Na 2ª: o token pfy_cf_ da prévia, ou o código de 6 dígitos que a pessoa recebeu por e-mail.
até 80 caracteres
observacaotextoopc.Motivo em uma frase, só para o registro (aparece como citação).
até 300 caracteres

Escopo produtos:escrever

pearfy_editar_ofertaEditar ofertaAlteraçãoPrévia e confirmaçãoCriar e editar produtos e ofertas

Altera nome, preço ou situação (ativa/desativada) de uma oferta da própria conta. A oferta padrão e a única ativa não são desativadas. Assinaturas já ativas seguem com o valor contratado. Ativar, reduzir preço com desconto acumulado acima de 50% (com o maior cupom ativo) e mudar preço de assinatura com pedido aguardando pagamento passam por aprovação no painel. A 1ª chamada devolve a prévia e o token; a alteração só acontece na 2ª, com o token.

ParâmetroTipo Descrição
oferta_ididobrig.UUID da oferta ou os 8 primeiros caracteres (ver pearfy_detalhar_produto).
nometextoopc.Nome novo da oferta (até 80 caracteres), sem contato nem link fora da Pearfy.
até 80 caracteres
preco_centavosinteiroopc.Preço novo em centavos, na moeda base da oferta. Assinaturas já ativas seguem com o valor contratado.
até 9999900
ativabooleanoopc.false = tira a oferta do checkout; true = pede a ativação (sempre com aprovação no painel).
confirmacaotextoopc.Vazio na 1ª chamada (devolve a prévia). Na 2ª: o token pfy_cf_ da prévia, ou o código de 6 dígitos que a pessoa recebeu por e-mail.
até 80 caracteres
observacaotextoopc.Motivo em uma frase, só para o registro (aparece como citação).
até 300 caracteres

Escopo produtos:escrever

pearfy_excluir_ofertaExcluir ofertaAlteraçãoPrévia e confirmaçãoCriar e editar produtos e ofertas

Remove uma oferta da própria conta pela mesma trava da API v1: a oferta padrão e a única ativa não saem, e a oferta que já teve pedidos é desativada em vez de apagada (o histórico e as assinaturas ativas não mudam). A 1ª chamada devolve a prévia e o token; a remoção só acontece na 2ª, com o token.

ParâmetroTipo Descrição
oferta_ididobrig.UUID da oferta ou os 8 primeiros caracteres (ver pearfy_detalhar_produto).
confirmacaotextoopc.Vazio na 1ª chamada (devolve a prévia). Na 2ª: o token pfy_cf_ da prévia, ou o código de 6 dígitos que a pessoa recebeu por e-mail.
até 80 caracteres
observacaotextoopc.Motivo em uma frase, só para o registro (aparece como citação).
até 300 caracteres

Escopo produtos:escrever

Cupons

pearfy_listar_cuponsListar cuponsConsultaConsultar produtos, ofertas e cupons

Cupons de desconto dos produtos da própria conta, mais recentes primeiro: código, tipo (percentual ou valor fixo em R$), valor, usos e limite, validade, se está ligado, situação no checkout agora (válido, desativado, agendado, expirado ou esgotado) e o produto. Filtros opcionais por produto e por ligado/desligado. Cupom de produto excluído não aparece.

ParâmetroTipo Descrição
produto_ididopc.Só os cupons deste produto (ID público, UUID ou 8 primeiros caracteres).
até 36 caracteres
ativobooleanoopc.true = só os ligados pelo produtor; false = só os desligados.
limiteinteiroopc.Itens por página (1 a 50).
1 a 50 · padrão 25
cursortextoopc.O proximo_cursor da página anterior. Vale 15 minutos e só com os mesmos filtros.
até 200 caracteres

Escopo produtos:ler

pearfy_criar_cupomCriar cupomAlteraçãoPrévia e confirmaçãoCriar e editar cupons

Cria um cupom de desconto num produto da própria conta: percentual (1 a 90%) ou valor fixo em centavos de real. A 1ª chamada devolve só a prévia e um token; a criação acontece na 2ª chamada, com os mesmos parâmetros e o token. Nasce ativo, com até 100 usos e até 30 dias. Mais usos, mais dias, desconto do produto acima de 50% ou chamada por chave de IA viram pedido de aprovação no painel.

ParâmetroTipo Descrição
produto_ididobrig.Produto da conta: UUID ou os 8 primeiros caracteres do id.
codigotextoobrig.Código do cupom (3 a 30: letras, números, - ou _). Fica em maiúsculas.
tipoenumobrig.percentual (1 a 90) ou fixo (centavos de real).
percentualfixo
valorinteiroobrig.percentual: de 1 a 90. fixo: desconto em centavos de real (R$ 10,00 = 1000).
até 9999900
max_usosinteiroopc.Usos no total. Padrão 100. Acima de 100 vira pedido de aprovação no painel.
1 a 1000000 · padrão 100
validade_diasinteiroopc.Dias de validade a partir de hoje (horário de Brasília). Padrão 30. Acima de 30 vira pedido de aprovação no painel.
1 a 365 · padrão 30
aplicar_em_adicionaisbooleanoopc.true = o desconto vale também sobre os adicionais (order bumps).
padrão false
chave_idempotenciatextoopc.Opcional (8 a 80 caracteres). A mesma chave em 24 h devolve o cupom já criado em vez de criar outro.
confirmacaotextoopc.Vazio na 1ª chamada (devolve a prévia). Na 2ª: o token pfy_cf_ da prévia, ou o código de 6 dígitos que a pessoa recebeu por e-mail.
até 80 caracteres
observacaotextoopc.Motivo em uma frase, só para o registro (aparece como citação).
até 300 caracteres

Escopo cupons:escrever

pearfy_editar_cupomLigar ou desligar cupomAlteraçãoPrévia e confirmaçãoCriar e editar cupons

Liga ou desliga um cupom de um produto da própria conta, achado pelo id ou pelo código exato. A 1ª chamada devolve só a prévia e um token; a alteração acontece na 2ª chamada, com os mesmos parâmetros e o token. Desligar confirma no chat. Ligar segue a regra de criação: cupom sem limite ou acima de 100 usos ou 30 dias, desconto do produto acima de 50% ou chamada por chave de IA viram pedido de aprovação no painel. Validade, usos e valor não mudam por aqui.

ParâmetroTipo Descrição
cupomtextoobrig.Cupom da conta: o id (UUID) ou o código exato (sem diferenciar maiúsculas).
até 36 caracteres
produto_ididopc.Produto do cupom (UUID ou 8 primeiros caracteres). Necessário quando o mesmo código existe em mais de um produto.
ativobooleanoobrig.true = liga o cupom; false = desliga.
confirmacaotextoopc.Vazio na 1ª chamada (devolve a prévia). Na 2ª: o token pfy_cf_ da prévia, ou o código de 6 dígitos que a pessoa recebeu por e-mail.
até 80 caracteres
observacaotextoopc.Motivo em uma frase, só para o registro (aparece como citação).
até 300 caracteres

Escopo cupons:escrever

Alunos e acesso

pearfy_listar_alunosListar alunosConsultaConsultar alunos

Alunos matriculados nas áreas de membros da conta, dos mais recentes aos mais antigos: nome curto, e-mail mascarado, produto e curso, data de matrícula, validade, situação do acesso (ativo, expirado, revogado, reembolsado), último acesso e progresso nas aulas. Filtra por produto e por situação; paginado por cursor.

ParâmetroTipo Descrição
produto_ididopc.Produto (UUID ou os 8 primeiros caracteres) cuja área de membros será listada. Sem ele, todos os produtos da conta.
statusenumopc.ativo = com acesso agora; expirado = o prazo do acesso passou; revogado = acesso cortado; reembolsado = acesso retirado por reembolso.
ativoexpiradorevogadoreembolsado
limiteinteiroopc.Itens por página (1 a 50).
1 a 50 · padrão 25
cursortextoopc.O proximo_cursor da página anterior. Vale 15 minutos e só com os mesmos filtros.
até 200 caracteres

Escopo alunos:ler

pearfy_reenviar_acessoReenviar acesso à área de membrosAlteraçãoDireta, com limiteReenviar acesso de alunos

Reenvia ao comprador de uma venda aprovada da conta o e-mail de acesso à área de membros da Pearfy (criar senha, se ainda não criou; senão, entrar). Executa direto, sem prévia. Só para produto com área de membros e acesso ativo. Limites: 3 por venda e 30 por conta por dia.

ParâmetroTipo Descrição
venda_ididobrig.Venda aprovada da conta (UUID ou os 8 primeiros caracteres), como em pearfy_listar_vendas.
confirmacaotextoopc.Vazio na 1ª chamada (devolve a prévia). Na 2ª: o token pfy_cf_ da prévia, ou o código de 6 dígitos que a pessoa recebeu por e-mail.
até 80 caracteres
observacaotextoopc.Motivo em uma frase, só para o registro (aparece como citação).
até 300 caracteres

Escopo alunos:escrever

Webhooks

pearfy_listar_webhooksListar webhooksConsultaConsultar webhooks

Webhooks de saída da conta: nome, domínio de destino (só o host), eventos assinados, se está ativo, produto a que se limita e o resumo das entregas dos últimos 7 dias (sucesso, falha, pendente) com a última entrega e o último status HTTP. Não mostra o endereço completo, o token de assinatura nem o conteúdo enviado.

ParâmetroTipo Descrição
limiteinteiroopc.Webhooks por página (1 a 20).
1 a 20 · padrão 10
cursortextoopc.O proximo_cursor da página anterior. Vale 15 minutos e só com os mesmos filtros.
até 200 caracteres

Escopo webhooks:ler

pearfy_listar_entregas_webhookListar entregas de um webhookConsultaConsultar webhooks

Histórico de entregas de um webhook da conta, das mais recentes às mais antigas: data, evento, situação (sucesso, falha, pendente), status HTTP da resposta, número de tentativas e próxima tentativa. Não mostra o conteúdo enviado nem a resposta do servidor de destino. Filtra por situação; paginado por cursor.

ParâmetroTipo Descrição
webhook_ididobrig.Webhook da conta (UUID ou os 8 primeiros caracteres), como em pearfy_listar_webhooks.
statusenumopc.sucesso = resposta 2xx; falha = esgotou as tentativas; pendente = aguardando nova tentativa.
sucessofalhapendente
limiteinteiroopc.Itens por página (1 a 50).
1 a 50 · padrão 25
cursortextoopc.O proximo_cursor da página anterior. Vale 15 minutos e só com os mesmos filtros.
até 200 caracteres

Escopo webhooks:ler

pearfy_criar_webhookCriar webhookAlteraçãoAprovação no painelCriar e remover webhooks

Cadastra um webhook de saída da conta para um endereço HTTPS público, com os eventos escolhidos. Em todos os casos depende de aprovação no painel da Pearfy: a 1ª chamada devolve a prévia e um token; a 2ª, com o token, cria o pedido de aprovação. O token de assinatura do webhook não é devolvido.

ParâmetroTipo Descrição
urltextoobrig.Endereço HTTPS público que vai receber os eventos.
até 2048 caracteres
eventoslista de enumopc.Eventos enviados. Sem eles: compra_aprovada.
boleto_geradopix_geradocompra_recusadacompra_aprovadacompra_reembolsadachargebacksubscription_canceledsubscription_latesubscription_renewed
nometextoopc.Nome para reconhecer o webhook no painel (até 60 caracteres).
até 60 caracteres
confirmacaotextoopc.Vazio na 1ª chamada (devolve a prévia). Na 2ª: o token pfy_cf_ da prévia, ou o código de 6 dígitos que a pessoa recebeu por e-mail.
até 80 caracteres
observacaotextoopc.Motivo em uma frase, só para o registro (aparece como citação).
até 300 caracteres

Escopo webhooks:escrever

pearfy_editar_webhookEditar webhookAlteraçãoPrévia e confirmaçãoCriar e remover webhooks

Muda o nome, os eventos ou liga/desliga um webhook da conta. A 1ª chamada devolve a prévia e um token; a 2ª, com o token, aplica. Trocar o endereço, religar, ou desligar (ou tirar eventos de) um webhook que entregou com sucesso nos últimos 30 dias depende de aprovação no painel.

ParâmetroTipo Descrição
webhook_ididobrig.Webhook da conta (UUID ou os 8 primeiros caracteres), como em pearfy_listar_webhooks.
nometextoopc.Nome novo (até 60 caracteres).
até 60 caracteres
eventoslista de enumopc.Lista NOVA e completa de eventos (substitui a atual).
boleto_geradopix_geradocompra_recusadacompra_aprovadacompra_reembolsadachargebacksubscription_canceledsubscription_latesubscription_renewed
ativobooleanoopc.false desliga o webhook; true religa (religar depende de aprovação no painel).
urltextoopc.Endereço HTTPS novo. Trocar o endereço depende de aprovação no painel.
até 2048 caracteres
confirmacaotextoopc.Vazio na 1ª chamada (devolve a prévia). Na 2ª: o token pfy_cf_ da prévia, ou o código de 6 dígitos que a pessoa recebeu por e-mail.
até 80 caracteres
observacaotextoopc.Motivo em uma frase, só para o registro (aparece como citação).
até 300 caracteres

Escopo webhooks:escrever

pearfy_remover_webhookRemover webhookAlteraçãoPrévia e confirmaçãoCriar e remover webhooks

Desativa um webhook ativo da conta: a Pearfy para de enviar eventos ao destino, e o webhook fica desativado no painel, de onde pode ser religado ou apagado. A 1ª chamada devolve a prévia e um token; a 2ª, com o token, aplica. Webhook que entregou com sucesso nos últimos 30 dias depende de aprovação no painel. Até 2 por dia.

ParâmetroTipo Descrição
webhook_ididobrig.Webhook da conta (UUID ou os 8 primeiros caracteres), como em pearfy_listar_webhooks.
confirmacaotextoopc.Vazio na 1ª chamada (devolve a prévia). Na 2ª: o token pfy_cf_ da prévia, ou o código de 6 dígitos que a pessoa recebeu por e-mail.
até 80 caracteres
observacaotextoopc.Motivo em uma frase, só para o registro (aparece como citação).
até 300 caracteres

Escopo webhooks:escrever