# Introdução

URL: https://staging.pagpolar.com/docs/referencia

> Encontre o contrato exato de cada operação da API e baixe a especificação OpenAPI.

Esta seção mostra cada operação da API: caminho, parâmetros, corpo, respostas e erros. As páginas são geradas da especificação OpenAPI publicada pela própria API e são atualizadas a cada 5 minutos, no máximo.

## Como a referência está organizada

As operações ficam em 8 grupos:

| Grupo        | O que você faz                                                   | Comece por                                                                             |
| ------------ | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Autenticação | Obtém o token de acesso e confere a credencial usada na chamada. | [`POST /auth/token`](/docs/referencia/autenticacao/create-access-token)                |
| Produtos     | Cria, lista e altera produtos.                                   | [`POST /products`](/docs/referencia/produtos/create-product)                           |
| Ofertas      | Cria, consulta e altera ofertas de produto.                      | [`POST /offers`](/docs/referencia/ofertas/create-offer)                                |
| Planos       | Cria planos e ofertas de plano.                                  | [`POST /plans`](/docs/referencia/planos/create-plan)                                   |
| Vendas       | Cobra por PIX, boleto ou cartão e consulta vendas.               | [`POST /payments/pix`](/docs/referencia/vendas/create-pix-payment)                     |
| Reembolsos   | Lista os pedidos de reembolso e reembolsa uma venda.             | [`POST /refunds`](/docs/referencia/reembolsos/create-refund)                           |
| Assinaturas  | Assina, consulta, cancela, troca o plano e troca o cartão.       | [`POST /plans/offer/{id}/subscribe`](/docs/referencia/assinaturas/create-subscription) |
| Clientes     | Lista e consulta clientes.                                       | [`GET /customers`](/docs/referencia/clientes/list-customers)                           |

## Autenticação em todas as operações

Todas as operações, menos [`POST /auth/token`](/docs/referencia/autenticacao/create-access-token), exigem o token de acesso no header `Authorization`. Veja [Autenticação](/docs/guias/fundamentos/autenticacao#obter-o-token).

## Testar as operações

Cada operação tem o botão **Send**, que executa a chamada no **ambiente de testes**, com a sua chave de Homologação. Para usar, entre no painel neste navegador e tenha uma chave de Homologação pronta. Nenhuma cobrança feita por aqui é real. Veja [Testar pelo portal](/docs/guias/fundamentos/ambientes#playground).

## Como ler os schemas

* A resposta de sucesso traz o objeto em `data`. Nas listagens, `data` é uma lista e `meta` traz a paginação. Veja [Paginação e filtros](/docs/guias/fundamentos/paginacao-e-filtros).
* Campos que podem vir vazios estão marcados como anuláveis e chegam com `null`.
* Campos com opções fixas, como `status` e `payment_method`, listam todos os valores aceitos.
* Os valores em dinheiro das respostas são números em reais. Veja [Valores nas respostas](/docs/guias/fundamentos/valores-datas-e-identificadores#valores-nas-respostas).

## Baixar a especificação OpenAPI

| Arquivo                                       | Conteúdo                                  |
| --------------------------------------------- | ----------------------------------------- |
| `https://app.pagpolar.com/docs/openapi.json`  | Especificação da API (OpenAPI 3.0).       |
| `https://app.pagpolar.com/docs/webhooks.json` | Especificação dos webhooks (OpenAPI 3.1). |

Use esses arquivos para gerar clientes em outras linguagens ou para dar contexto a um assistente de IA. Veja [Para agentes de IA](/docs/guias/para-agentes-de-ia).

## Guias relacionados

| Grupo            | Leia antes                                                                                                                                                                                           |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Vendas           | [Idempotência](/docs/guias/fundamentos/idempotencia), [Limites de requisição](/docs/guias/fundamentos/limites-de-requisicao), [Ciclo de vida da venda](/docs/guias/conceitos/ciclo-de-vida-da-venda) |
| Ofertas e Planos | [Ofertas, planos e ofertas ocultas](/docs/guias/conceitos/ofertas-planos-e-ofertas-ocultas)                                                                                                          |
| Assinaturas      | [Ciclo de vida da assinatura](/docs/guias/conceitos/ciclo-de-vida-da-assinatura)                                                                                                                     |
| Listagens        | [Paginação e filtros](/docs/guias/fundamentos/paginacao-e-filtros)                                                                                                                                   |