# PagPolar Docs > Documentação da API pública da PagPolar ## Arquivos para agentes de IA - [OpenAPI da API pública](https://staging.pagpolar.com/docs/openapi.json): Todas as operações, parâmetros, corpos, respostas e erros (OpenAPI 3.0). - [OpenAPI dos webhooks](https://staging.pagpolar.com/docs/webhooks.json): Os eventos de webhook e o formato de cada payload (OpenAPI 3.1). - [Documentação completa em texto](https://staging.pagpolar.com/docs/llms-full.txt): O conteúdo inteiro do portal num arquivo só. - [Somente Guias](https://staging.pagpolar.com/docs/llms-full.txt?secao=guias): O mesmo texto completo, recortado só nesta parte do portal. - [Somente Webhooks](https://staging.pagpolar.com/docs/llms-full.txt?secao=webhooks): O mesmo texto completo, recortado só nesta parte do portal. - [Somente Referência da API](https://staging.pagpolar.com/docs/llms-full.txt?secao=referencia): O mesmo texto completo, recortado só nesta parte do portal. ## Guias - [Onde começar?](https://staging.pagpolar.com/docs/guias): Veja o que a API faz, o que você precisa antes de integrar e quais rotas e eventos usar em cada objetivo. - [Início rápido](https://staging.pagpolar.com/docs/guias/inicio-rapido): Crie uma credencial, obtenha o token de acesso e faça a sua primeira venda PIX pela API. - [Para agentes de IA](https://staging.pagpolar.com/docs/guias/para-agentes-de-ia): Entregue a especificação da API e dos webhooks a um assistente de IA para ele ajudar a escrever a sua integração. - [Ciclo de vida da assinatura](https://staging.pagpolar.com/docs/guias/conceitos/ciclo-de-vida-da-assinatura): Entenda por que a assinatura nasce DRAFT, quando fica ACTIVE, como renova e como termina. - [Ciclo de vida da venda](https://staging.pagpolar.com/docs/guias/conceitos/ciclo-de-vida-da-venda): Entenda cada status da venda, o que leva a venda até ele e qual evento de webhook avisa a mudança. - [Ofertas, planos e ofertas ocultas](https://staging.pagpolar.com/docs/guias/conceitos/ofertas-planos-e-ofertas-ocultas): Escolha entre usar o código de uma oferta e informar a oferta na hora da venda, e entenda o que é uma oferta oculta. - [Ambientes e URL base](https://staging.pagpolar.com/docs/guias/fundamentos/ambientes): Descubra o endereço da API, o que muda entre Produção e Homologação e por que a chamada deve partir do seu servidor. - [Autenticação](https://staging.pagpolar.com/docs/guias/fundamentos/autenticacao): Troque a chave de API pelo token de acesso, envie o token em Authorization e entenda cada resposta 401 e 403. - [Credenciais da API](https://staging.pagpolar.com/docs/guias/fundamentos/credenciais): Crie, restrinja por IP e revogue credenciais e veja o histórico de requisições. - [Erros](https://staging.pagpolar.com/docs/guias/fundamentos/erros): Leia o formato de erro da API, decida o que pode ser repetido e informe o request_id ao suporte. - [Glossário](https://staging.pagpolar.com/docs/guias/fundamentos/glossario): Consulte o significado de cada termo usado nesta documentação e o campo da API que corresponde a ele. - [Idempotência](https://staging.pagpolar.com/docs/guias/fundamentos/idempotencia): Envie o header Idempotency-Key e repita uma cobrança sem cobrar o cliente duas vezes. - [Limites de requisição](https://staging.pagpolar.com/docs/guias/fundamentos/limites-de-requisicao): Saiba quantas chamadas por minuto sua credencial pode fazer, como os limites se somam e o que fazer no 429 e no 503. - [Paginação e filtros](https://staging.pagpolar.com/docs/guias/fundamentos/paginacao-e-filtros): Percorra qualquer listagem da API do começo ao fim e use os filtros que cada uma realmente aplica. - [Valores, datas e identificadores](https://staging.pagpolar.com/docs/guias/fundamentos/valores-datas-e-identificadores): Envie valores em centavos, leia valores em reais, e use datas e os tipos de identificador da API sem errar. - [Acompanhar reembolsos e chargebacks](https://staging.pagpolar.com/docs/guias/jornadas/acompanhar-reembolsos-e-chargebacks): Receba o pedido de reembolso, consulte os pedidos na API e reaja ao estorno e ao chargeback de uma venda. - [Assinar um plano](https://staging.pagpolar.com/docs/guias/jornadas/assinar-um-plano): Crie um plano e uma oferta de plano, assine um cliente no cartão e acompanhe a confirmação e as renovações. - [Cancelar assinatura](https://staging.pagpolar.com/docs/guias/jornadas/cancelar-assinatura): Cancele uma assinatura pela API e saiba, pelo meio de pagamento e pelo status, quando o cancelamento vale. - [Conciliar vendas e assinaturas](https://staging.pagpolar.com/docs/guias/jornadas/conciliar-vendas): Baixe todas as vendas e assinaturas de um período e compare com o seu sistema, sem perder nem duplicar registros. - [Criar produto e oferta](https://staging.pagpolar.com/docs/guias/jornadas/criar-produto-e-oferta): Crie um produto, crie a oferta com preço, meios de pagamento e parcelas, e obtenha o código da oferta para vender. - [Trocar o cartão da assinatura](https://staging.pagpolar.com/docs/guias/jornadas/trocar-cartao-da-assinatura): Troque o cartão de crédito de uma assinatura sem cancelar, sem mudar o plano e sem cobrar o cliente. - [Trocar de plano](https://staging.pagpolar.com/docs/guias/jornadas/trocar-de-plano): Liste as ofertas disponíveis, calcule o valor e mude a assinatura para um plano mais caro ou mais barato sem cancelar. - [Vender com afiliado](https://staging.pagpolar.com/docs/guias/jornadas/vender-com-afiliado): Credite a venda ao afiliado certo enviando affiliate_identifier na cobrança, e saiba quando o código é recusado ou ignorado. - [Vender com cartão de crédito](https://staging.pagpolar.com/docs/guias/jornadas/vender-com-cartao): Cobre o cliente no cartão, à vista ou parcelado, e descubra se o pagamento foi aprovado ou recusado. - [Vender com PIX ou boleto](https://staging.pagpolar.com/docs/guias/jornadas/vender-com-pix-ou-boleto): Cobre o cliente por PIX ou boleto, mostre o código de pagamento e confirme o pagamento pelo webhook. - [Vender um produto físico](https://staging.pagpolar.com/docs/guias/jornadas/vender-um-produto-fisico): Consulte o frete pelo CEP do cliente, cobre com o endereço de entrega e a opção de frete escolhida e acompanhe a venda até a separação. ## Webhooks - [Autenticar as requisições recebidas](https://staging.pagpolar.com/docs/webhooks/autenticar-requisicoes): Valide o header Authorization antes de processar qualquer evento de webhook. - [Configurar o webhook](https://staging.pagpolar.com/docs/webhooks/configurar): Cadastre a URL, escolha os eventos e saiba o que pode ou não mudar no webhook da credencial. - [Entregas e retentativas](https://staging.pagpolar.com/docs/webhooks/entregas-e-retentativas): Saiba o que conta como entrega bem-sucedida, quantas tentativas a PagPolar faz e como reenviar avisos pelo painel. - [Formato do evento](https://staging.pagpolar.com/docs/webhooks/formato-do-evento): Leia o envelope do webhook e cada bloco de data em eventos de venda e de assinatura. - [Visão geral dos webhooks](https://staging.pagpolar.com/docs/webhooks): Entenda como a PagPolar avisa o seu servidor quando uma venda ou assinatura muda e por que o webhook também recebe as vendas do checkout. - [Playground](https://staging.pagpolar.com/docs/webhooks/playground): Monte um evento de webhook de teste, veja o JSON e envie para um webhook ativo da sua conta. - [Processar eventos sem duplicar](https://staging.pagpolar.com/docs/webhooks/processar-sem-duplicar): Processe cada evento uma única vez, mesmo quando ele chega repetido, fora de ordem ou com um status posterior. - [Catálogo de eventos](https://staging.pagpolar.com/docs/webhooks/eventos): Encontre o evento certo para cada situação de venda ou assinatura e veja o que fazer ao receber cada um. - [Venda criada](https://staging.pagpolar.com/docs/webhooks/eventos/transaction-created): **Evento:** `TRANSACTION_CREATED` Uma venda foi registrada. - [Cobrança de renovação gerada](https://staging.pagpolar.com/docs/webhooks/eventos/transaction-pending): **Evento:** `TRANSACTION_PENDING` A cobrança de renovação de uma assinatura em PIX ou boleto foi gerada e espera pagamento. - [Venda paga](https://staging.pagpolar.com/docs/webhooks/eventos/transaction-paid): **Evento:** `TRANSACTION_PAID` O pagamento da venda foi confirmado. - [Venda expirada](https://staging.pagpolar.com/docs/webhooks/eventos/transaction-expired): **Evento:** `TRANSACTION_EXPIRED` Um PIX ou boleto venceu sem pagamento. - [Venda cancelada](https://staging.pagpolar.com/docs/webhooks/eventos/transaction-canceled): **Evento:** `TRANSACTION_CANCELED` A venda foi cancelada sem ter sido paga. - [Reembolso solicitado](https://staging.pagpolar.com/docs/webhooks/eventos/transaction-ask-refunding): **Evento:** `TRANSACTION_ASK_REFUNDING` O cliente pediu reembolso. - [Venda reembolsada](https://staging.pagpolar.com/docs/webhooks/eventos/transaction-refunded): **Evento:** `TRANSACTION_REFUNDED` O estorno foi concluído e o dinheiro voltou para o cliente. - [Chargeback aprovado](https://staging.pagpolar.com/docs/webhooks/eventos/transaction-chargeback-approved): **Evento:** `TRANSACTION_CHARGEBACK_APPROVED` O banco do cliente aprovou uma contestação da compra (chargeback) e o valor foi revertido. - [Assinatura criada](https://staging.pagpolar.com/docs/webhooks/eventos/subscription-created): **Evento:** `SUBSCRIPTION_CREATED` Uma assinatura nova foi registrada. - [Assinatura confirmada](https://staging.pagpolar.com/docs/webhooks/eventos/subscription-confirmed): **Evento:** `SUBSCRIPTION_CONFIRMED` O gateway aceitou a assinatura no cartão de crédito. - [Assinatura recusada](https://staging.pagpolar.com/docs/webhooks/eventos/subscription-failed): **Evento:** `SUBSCRIPTION_FAILED` A criação da assinatura no cartão de crédito falhou no gateway. - [Assinatura renovada](https://staging.pagpolar.com/docs/webhooks/eventos/subscription-renewed): **Evento:** `SUBSCRIPTION_RENEWED` Um ciclo da assinatura no cartão, a partir do segundo, foi pago. - [Assinatura em atraso](https://staging.pagpolar.com/docs/webhooks/eventos/subscription-delayed): **Evento:** `SUBSCRIPTION_DELAYED` A renovação de uma assinatura em PIX ou boleto está atrasada, mas ainda dentro do prazo de carência. - [Assinatura expirada](https://staging.pagpolar.com/docs/webhooks/eventos/subscription-expired): **Evento:** `SUBSCRIPTION_EXPIRED` A assinatura em PIX ou boleto passou do prazo de carência sem pagar a renovação. - [Assinatura cancelada](https://staging.pagpolar.com/docs/webhooks/eventos/subscription-canceled): **Evento:** `SUBSCRIPTION_CANCELED` O cancelamento da assinatura foi efetivado. ## Referência da API - [Introdução](https://staging.pagpolar.com/docs/referencia): Encontre o contrato exato de cada operação da API e baixe a especificação OpenAPI. - [Assinaturas](https://staging.pagpolar.com/docs/referencia/assinaturas): Assine, consulte, cancele, troque o plano e troque o cartão. - [Autenticação](https://staging.pagpolar.com/docs/referencia/autenticacao): Obtenha o token de acesso e confira a credencial usada na chamada. - [Clientes](https://staging.pagpolar.com/docs/referencia/clientes): Liste e consulte clientes. - [Assinatura](https://staging.pagpolar.com/docs/referencia/entidades/assinatura): Contrato de cobrança recorrente de um cliente num plano. - [Cliente](https://staging.pagpolar.com/docs/referencia/entidades/cliente): Quem comprou. - [Cobrança por boleto](https://staging.pagpolar.com/docs/referencia/entidades/cobranca-boleto): Corpo para criar uma venda por boleto. - [Cobrança no cartão](https://staging.pagpolar.com/docs/referencia/entidades/cobranca-cartao): Corpo para criar uma venda no cartão de crédito. - [Cobrança PIX](https://staging.pagpolar.com/docs/referencia/entidades/cobranca-pix): Corpo para criar uma venda PIX. - [Credencial](https://staging.pagpolar.com/docs/referencia/entidades/credencial): Dados da credencial dona do token de acesso usado na chamada. - [Oferta](https://staging.pagpolar.com/docs/referencia/entidades/oferta): Preço de venda de um produto, com meios de pagamento, parcelas e, na oferta de plano, a periodicidade da cobrança. - [Opção de frete](https://staging.pagpolar.com/docs/referencia/entidades/opcao-de-frete): Uma forma de entrega disponível para um CEP, com valor e prazo. - [Opções de troca de plano](https://staging.pagpolar.com/docs/referencia/entidades/opcoes-de-troca-de-plano): Planos para os quais a assinatura pode ser trocada. - [Pedido de reembolso](https://staging.pagpolar.com/docs/referencia/entidades/pedido-de-reembolso): Corpo para pedir o reembolso de uma venda. - [Prévia da troca de plano](https://staging.pagpolar.com/docs/referencia/entidades/previa-da-troca-de-plano): Cálculo da troca antes de executar: direção, crédito proporcional e valor a cobrar. - [Produto](https://staging.pagpolar.com/docs/referencia/entidades/produto): Produto à venda: dados de exibição, tipo, garantia e categoria. - [Reembolso](https://staging.pagpolar.com/docs/referencia/entidades/reembolso): Pedido de reembolso de uma venda, total ou parcial, com o andamento e a venda de origem. - [Resultado da cobrança](https://staging.pagpolar.com/docs/referencia/entidades/resultado-da-cobranca): Resposta da criação de uma cobrança, com os ids das vendas e os dados para o cliente pagar. - [Resultado da operação](https://staging.pagpolar.com/docs/referencia/entidades/resultado-da-operacao): Confirmação de uma operação que não devolve outro dado. - [Token de acesso](https://staging.pagpolar.com/docs/referencia/entidades/token-de-acesso): Token que autentica as chamadas da API. - [Troca de plano](https://staging.pagpolar.com/docs/referencia/entidades/troca-de-plano): Resultado da troca executada: upgrade com cobrança da diferença ou downgrade agendado. - [Venda](https://staging.pagpolar.com/docs/referencia/entidades/venda): Uma cobrança: avulsa ou um ciclo de assinatura. - [Ofertas](https://staging.pagpolar.com/docs/referencia/ofertas): Crie, consulte e altere as ofertas de um produto. - [Planos](https://staging.pagpolar.com/docs/referencia/planos): Crie planos de assinatura e as ofertas de cada plano. - [Produtos](https://staging.pagpolar.com/docs/referencia/produtos): Crie, liste e altere produtos. - [Reembolsos](https://staging.pagpolar.com/docs/referencia/reembolsos): Liste os pedidos de reembolso e peça o reembolso de uma venda. - [Vendas](https://staging.pagpolar.com/docs/referencia/vendas): Cobre por PIX, boleto ou cartão e consulte as vendas. - [Obter o token de acesso](https://staging.pagpolar.com/docs/referencia/autenticacao/create-access-token): Troca a chave da credencial por um **token de acesso**. - [Dados da credencial autenticada](https://staging.pagpolar.com/docs/referencia/autenticacao/get-current-credential): Retorna o ambiente da credencial (PRODUCTION ou STAGING) e o limite de requisições por minuto. - [Listar produtos](https://staging.pagpolar.com/docs/referencia/produtos/list-products) - [Criar produto](https://staging.pagpolar.com/docs/referencia/produtos/create-product): Cria um produto **digital** (`type` sempre `DIGITAL` — outros tipos não são criáveis pela API pública nesta versão). - [Consultar produto](https://staging.pagpolar.com/docs/referencia/produtos/get-product) - [Editar produto](https://staging.pagpolar.com/docs/referencia/produtos/update-product): Edita campos básicos de um produto já criado. - [Criar oferta](https://staging.pagpolar.com/docs/referencia/ofertas/create-offer): Cria uma oferta (preço) avulsa para um produto já existente do seu catálogo. - [Consultar o frete de uma oferta](https://staging.pagpolar.com/docs/referencia/ofertas/list-offer-shipping): Devolve as opções de entrega de uma oferta de produto físico para um CEP. - [Consultar oferta pelo código](https://staging.pagpolar.com/docs/referencia/ofertas/get-offer) - [Listar ofertas de um produto](https://staging.pagpolar.com/docs/referencia/ofertas/list-product-offers): `id` precisa ser o id (uuid) de um produto da sua conta — produtos de outro whitelabel retornam 404. - [Editar oferta](https://staging.pagpolar.com/docs/referencia/ofertas/update-offer): Edita campos comerciais de uma oferta já criada. - [Listar planos](https://staging.pagpolar.com/docs/referencia/planos/list-plans): Um plano é um produto do tipo `SUBSCRIPTION` — aparece aqui, não em `GET /products`. - [Criar plano](https://staging.pagpolar.com/docs/referencia/planos/create-plan): Cria um plano de assinatura — internamente é um produto com `type=SUBSCRIPTION`, por isso a resposta usa o mesmo formato de `Product`. - [Consultar plano](https://staging.pagpolar.com/docs/referencia/planos/get-plan) - [Editar plano](https://staging.pagpolar.com/docs/referencia/planos/update-plan): Edita campos básicos de um plano já criado. - [Listar ofertas de um plano](https://staging.pagpolar.com/docs/referencia/planos/list-plan-offers): `id` precisa ser o id (uuid) de um plano da sua conta — planos de outro whitelabel retornam 404. - [Criar oferta de plano](https://staging.pagpolar.com/docs/referencia/planos/create-plan-offer): Cria uma oferta **recorrente** para um plano já existente do seu catálogo. - [Editar oferta de plano](https://staging.pagpolar.com/docs/referencia/planos/update-plan-offer): Edita campos comerciais de uma oferta de plano já criada. - [Assinar um plano (criar assinatura)](https://staging.pagpolar.com/docs/referencia/assinaturas/create-subscription): Cria uma assinatura de verdade para um cliente em uma oferta de plano existente. - [Listar vendas](https://staging.pagpolar.com/docs/referencia/vendas/list-sales) - [Consultar venda](https://staging.pagpolar.com/docs/referencia/vendas/get-sale): Aceita três formas de referência, testadas nesta ordem: o `id` da venda (uuid, o mesmo que volta em `transactions` na criação do pagamento), o código da venda… - [Listar reembolsos](https://staging.pagpolar.com/docs/referencia/reembolsos/list-refunds): Lista os pedidos de reembolso das suas vendas, do mais recente para o mais antigo — abertos pelo comprador ou por você. - [Reembolsar uma venda](https://staging.pagpolar.com/docs/referencia/reembolsos/create-refund): Reembolsa uma venda sua. - [Listar assinaturas](https://staging.pagpolar.com/docs/referencia/assinaturas/list-subscriptions) - [Consultar assinatura](https://staging.pagpolar.com/docs/referencia/assinaturas/get-subscription) - [Cancelar assinatura](https://staging.pagpolar.com/docs/referencia/assinaturas/cancel-subscription): Solicita o cancelamento da assinatura. - [Trocar cartão da assinatura](https://staging.pagpolar.com/docs/referencia/assinaturas/update-subscription-card): Substitui o cartão de crédito usado nas cobranças de uma assinatura paga com cartão. - [Listar opções de troca de plano](https://staging.pagpolar.com/docs/referencia/assinaturas/list-subscription-plan-options): Lista os planos do mesmo produto disponíveis para troca (upgrade ou downgrade) nesta assinatura, e se o produto permite troca de plano pelo cliente. - [Calcular preview de troca de plano](https://staging.pagpolar.com/docs/referencia/assinaturas/preview-subscription-plan-change): Calcula o crédito ou cobrança proporcional de uma troca de plano sem efetivá-la. - [Executar upgrade ou downgrade de plano](https://staging.pagpolar.com/docs/referencia/assinaturas/change-subscription-plan): Executa a troca de plano de uma assinatura. - [Listar clientes](https://staging.pagpolar.com/docs/referencia/clientes/list-customers): Documento e telefone são sempre mascarados nesta API. - [Consultar cliente](https://staging.pagpolar.com/docs/referencia/clientes/get-customer) - [Fazer uma venda no PIX](https://staging.pagpolar.com/docs/referencia/vendas/create-pix-payment): Cria uma cobrança PIX em cima de uma oferta existente. - [Fazer uma venda no boleto](https://staging.pagpolar.com/docs/referencia/vendas/create-boleto-payment): Cria uma cobrança em boleto em cima de uma oferta existente. - [Fazer uma venda no cartão de crédito](https://staging.pagpolar.com/docs/referencia/vendas/create-credit-card-payment): Cria uma cobrança em cartão de crédito em cima de uma oferta existente. - [Consultar pagamento](https://staging.pagpolar.com/docs/referencia/vendas/get-payment): Mesma consulta de `GET /sales/{identifier}`: aceita o `id` da venda (uuid), o código da venda (10 dígitos, com ou sem o prefixo, ou link terminado nele) ou a… ## Visão geral - [Documentação da API PagPolar](https://staging.pagpolar.com/docs): Guias passo a passo, a referência de cada operação e os avisos de webhook para integrar a sua loja à PagPolar.