# Onde começar?

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

> **É um agente de IA? Comece por aqui**
>
> Leia [/docs/llms.txt](/docs/llms.txt): é o índice desta documentação em texto, com o endereço e o resumo de cada página. O contrato completo da API está em [/docs/openapi.json](/docs/openapi.json) (OpenAPI 3.0) e o dos webhooks em [/docs/webhooks.json](/docs/webhooks.json) (OpenAPI 3.1). Qualquer página pode ser lida em markdown acrescentando `.mdx` ao endereço ou enviando o header `Accept: text/markdown`.

A API da PagPolar deixa o seu sistema vender sem passar pelo checkout da PagPolar. Com ela você:

* cria produtos, ofertas, planos e ofertas de plano;
* cobra por PIX, boleto ou cartão de crédito;
* assina um cliente em um plano, com cobrança no cartão;
* consulta vendas, pedidos de reembolso, assinaturas e clientes;
* recebe avisos no seu servidor quando uma venda ou uma assinatura muda (webhooks).

## Antes de começar

Você precisa de três coisas:

1. **Uma conta de vendedor na PagPolar** com o menu **Configurações → API** no painel. É nessa tela que você cria a credencial.
2. **Um servidor seu** para chamar a API. Veja [Chame a API do seu servidor](/docs/guias/fundamentos/ambientes#servidor).
3. **Uma URL pública** no seu servidor para receber os webhooks.

Comece pela chave de Homologação, que leva as chamadas para o [ambiente de testes](/docs/guias/fundamentos/ambientes#ambiente-de-testes), e troque pela chave de Produção quando a integração estiver pronta.

## Qual rota chamar

Cada objetivo abaixo lista as operações na ordem em que você as chama e o evento de webhook que avisa o resultado.

Antes de qualquer uma delas, [obtenha o token de acesso](/docs/guias/fundamentos/autenticacao#obter-o-token). O passo a passo de cada objetivo está no guia da jornada indicado em cada seção.

## Escolha pelo tipo de cobrança

```mermaid
flowchart TD
  A[O que você quer cobrar?] --> B{Pagamento único ou recorrente?}
  B -->|Único| C{Qual meio de pagamento?}
  C -->|PIX| D[POST /payments/pix]
  C -->|Boleto| E[POST /payments/boleto]
  C -->|Cartão| F[POST /payments/credit-card]
  B -->|Recorrente| G[POST /plans/offer/ID/subscribe, só cartão]
```

## Vender um produto avulso

1. Crie o produto: [`POST /products`](/docs/referencia/produtos/create-product). Veja [Criar produto e oferta](/docs/guias/jornadas/criar-produto-e-oferta).
2. Crie a oferta, com preço e [meios de pagamento](/docs/guias/jornadas/criar-produto-e-oferta#meios-de-pagamento): [`POST /offers`](/docs/referencia/ofertas/create-offer). Se preferir, [informe a oferta na hora da venda](/docs/guias/conceitos/ofertas-planos-e-ofertas-ocultas).
3. Cobre o cliente:
   * PIX: [`POST /payments/pix`](/docs/referencia/vendas/create-pix-payment);
   * boleto: [`POST /payments/boleto`](/docs/referencia/vendas/create-boleto-payment);
   * cartão: [`POST /payments/credit-card`](/docs/referencia/vendas/create-credit-card-payment).
4. Espere o aviso de pagamento: [`TRANSACTION_PAID`](/docs/webhooks/eventos/transaction-paid).

Se o produto é físico, a cobrança exige o endereço e a opção de frete, consultada antes em [`GET /offers/{identifier}/shipping`](/docs/referencia/ofertas/list-offer-shipping). Veja [Vender um produto físico](/docs/guias/jornadas/vender-um-produto-fisico).

Guias: [Início rápido](/docs/guias/inicio-rapido), [Vender com PIX ou boleto](/docs/guias/jornadas/vender-com-pix-ou-boleto), [Vender com cartão de crédito](/docs/guias/jornadas/vender-com-cartao) e [Vender com afiliado](/docs/guias/jornadas/vender-com-afiliado).

## Vender uma assinatura

Pela API, a assinatura é sempre cobrada no cartão de crédito.

1. Crie o plano: [`POST /plans`](/docs/referencia/planos/create-plan).
2. Crie a oferta de plano, com preço e ciclo: [`POST /plans/{id}/offers`](/docs/referencia/planos/create-plan-offer).
3. Assine o cliente: [`POST /plans/offer/{id}/subscribe`](/docs/referencia/assinaturas/create-subscription).
4. Acompanhe o status pelos webhooks e por [`GET /subscriptions/{id}`](/docs/referencia/assinaturas/get-subscription). Quando liberar o acesso está em [Ciclo de vida da assinatura](/docs/guias/conceitos/ciclo-de-vida-da-assinatura).
5. Para cancelar: [`DELETE /subscriptions/{id}`](/docs/referencia/assinaturas/cancel-subscription).

Guias: [Assinar um plano](/docs/guias/jornadas/assinar-um-plano), [Cancelar assinatura](/docs/guias/jornadas/cancelar-assinatura), [Trocar de plano](/docs/guias/jornadas/trocar-de-plano) e [Trocar o cartão da assinatura](/docs/guias/jornadas/trocar-cartao-da-assinatura).

## Acompanhar o que acontece depois da venda

* Receba os avisos no seu servidor: [Visão geral dos webhooks](/docs/webhooks).
* Veja cada status da venda e o evento que avisa: [Ciclo de vida da venda](/docs/guias/conceitos/ciclo-de-vida-da-venda).
* Liste os pedidos de reembolso: [`GET /refunds`](/docs/referencia/reembolsos/list-refunds). Veja [Acompanhar reembolsos e chargebacks](/docs/guias/jornadas/acompanhar-reembolsos-e-chargebacks).

## Conferir e conciliar dados

* Liste as vendas de um período: [`GET /sales`](/docs/referencia/vendas/list-sales). Veja [Paginação e filtros](/docs/guias/fundamentos/paginacao-e-filtros).
* Consulte uma venda pelo id, pelo código ou pela sua referência do pedido: [`GET /sales/{identifier}`](/docs/referencia/vendas/get-sale). Veja [Como a venda é encontrada](/docs/guias/fundamentos/valores-datas-e-identificadores#como-a-venda-e-encontrada).
* Liste as assinaturas: [`GET /subscriptions`](/docs/referencia/assinaturas/list-subscriptions).
* Liste os clientes: [`GET /customers`](/docs/referencia/clientes/list-customers).

Guia: [Conciliar vendas e assinaturas](/docs/guias/jornadas/conciliar-vendas).