# Documentação da API PagPolar

URL: 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.

Esta é a página inicial do portal. Ela lista, em quatro blocos, tudo o que a documentação cobre: o que vale para toda a API, o passo a passo de cada objetivo, o contrato de cada operação e os avisos que a PagPolar envia ao seu servidor.

Para começar a integrar, vá para o [Início rápido](/docs/guias/inicio-rapido). Para descobrir qual rota chamar para um objetivo, abra [Onde começar?](/docs/guias).

## Arquivos para agentes de IA

Todos são públicos e não precisam de chave.

* [Índice do portal em texto](/docs/llms.txt) — o endereço e o resumo de cada página.
* [Conteúdo inteiro do portal em texto](/docs/llms-full.txt) — tudo num arquivo só.
* [OpenAPI da API pública](/docs/openapi.json) — todas as operações, parâmetros, corpos, respostas e erros (OpenAPI 3.0).
* [OpenAPI dos webhooks](/docs/webhooks.json) — o formato de cada evento (OpenAPI 3.1).
* [Como entregar a documentação a um assistente](/docs/guias/para-agentes-de-ia).

Qualquer página pode ser lida em markdown acrescentando `.mdx` ao endereço ou enviando o header `Accept: text/markdown`.

## Fundamentos

O que vale para toda a API: endereço, token, erros, repetição segura e formato dos valores.

* [Ambientes e URL base](/docs/guias/fundamentos/ambientes) — o endereço da API e o que muda entre Produção e Homologação.
* [Autenticação](/docs/guias/fundamentos/autenticacao) — troque a chave pelo token e envie em `Authorization`.
* [Credenciais da API](/docs/guias/fundamentos/credenciais) — crie, restrinja por IP e revogue credenciais.
* [Erros](/docs/guias/fundamentos/erros) — o formato do erro, o que pode ser repetido e o `request_id`.
* [Idempotência](/docs/guias/fundamentos/idempotencia) — repita uma cobrança sem cobrar o cliente duas vezes.
* [Limites de requisição](/docs/guias/fundamentos/limites-de-requisicao) — quantas chamadas por minuto e o que fazer no 429.
* [Paginação e filtros](/docs/guias/fundamentos/paginacao-e-filtros) — percorra qualquer listagem do começo ao fim.
* [Valores, datas e identificadores](/docs/guias/fundamentos/valores-datas-e-identificadores) — centavos, fuso e os tipos de identificador.
* [Glossário](/docs/guias/fundamentos/glossario) — o termo e o campo da API que corresponde a ele.

## Jornadas

O caminho completo de cada objetivo, da primeira chamada ao aviso de webhook.

* [Criar produto e oferta](/docs/guias/jornadas/criar-produto-e-oferta) — cadastre o produto e a oferta com preço, meios de pagamento e parcelas.
* [Vender com PIX ou boleto](/docs/guias/jornadas/vender-com-pix-ou-boleto) — cobre, mostre o código de pagamento e confirme pelo webhook.
* [Vender com cartão de crédito](/docs/guias/jornadas/vender-com-cartao) — cobre à vista ou parcelado e saiba se foi aprovado ou recusado.
* [Vender um produto físico](/docs/guias/jornadas/vender-um-produto-fisico) — consulte o frete pelo CEP, cobre com o endereço e acompanhe o pedido.
* [Vender uma assinatura](/docs/guias/jornadas/assinar-um-plano) — crie o plano, assine o cliente no cartão e acompanhe as renovações.
* [Acompanhar reembolsos](/docs/guias/jornadas/acompanhar-reembolsos-e-chargebacks) — receba o pedido, consulte na API e reaja ao estorno e ao chargeback.
* [Conciliar vendas](/docs/guias/jornadas/conciliar-vendas) — baixe as vendas e assinaturas de um período sem perder nem duplicar.

Todas as jornadas estão listadas em [Onde começar?](/docs/guias).

## Referência da API

O contrato de cada operação: caminho, parâmetros, corpo, respostas e erros.

* [Autenticação](/docs/referencia/autenticacao) — troque a chave pelo token de acesso e confira a credencial.
* [Vendas](/docs/referencia/vendas) — cobre por PIX, boleto ou cartão e consulte as vendas.
* [Produtos e ofertas](/docs/referencia/produtos) — crie e altere produtos e as ofertas com preço e parcelas.
* [Planos e assinaturas](/docs/referencia/planos) — planos, ofertas de plano, troca de plano e troca de cartão.
* [Reembolsos](/docs/referencia/reembolsos) — liste os pedidos de reembolso e peça o reembolso de uma venda.
* [Entidades](/docs/referencia/entidades) — os campos de cada objeto que a API devolve ou recebe.

## Webhooks

Os avisos que a PagPolar envia ao seu servidor quando algo muda.

* [Visão geral](/docs/webhooks) — como o aviso chega, o que ele traz e quando usar.
* [Playground](/docs/webhooks/playground) — monte um evento de teste, edite o JSON e envie para o seu webhook.
* [Configurar o webhook](/docs/webhooks/configurar) — cadastre a URL, escolha os eventos e entenda o token.
* [Formato do evento](/docs/webhooks/formato-do-evento) — o envelope e cada bloco de dados do aviso.
* [Processar sem duplicar](/docs/webhooks/processar-sem-duplicar) — trate repetições, ordem fora de sequência e envios de teste.
* [Catálogo de eventos](/docs/webhooks/eventos) — os 15 eventos, quando cada um dispara e o que fazer.