# Ambientes e URL base

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

## URL base

A URL base da API da PagPolar é:

```text
https://api.pagpolar.com/v1
```

Nesta documentação, as rotas aparecem sem a URL base, como `GET /me` ou `POST /payments/pix`. Para chamar uma rota, junte a URL base com o caminho da rota: `https://api.pagpolar.com/v1` + `/me` = `https://api.pagpolar.com/v1/me`. Não repita o `/v1` no caminho nem deixe barra dupla.

Os exemplos em cURL e Node.js já usam a URL completa.

Existe um único endereço. Produção e Homologação usam o mesmo.

## Produção e Homologação

Toda credencial pertence a um ambiente. Você escolhe o ambiente ao criar a credencial e **não consegue mudar depois**.

| Ambiente no painel | Valor em `environment` | A chave começa com | Onde a chamada é processada                     |
| ------------------ | ---------------------- | ------------------ | ----------------------------------------------- |
| Produção           | `PRODUCTION`           | `pgp_live_`        | Na sua conta. As cobranças são reais.           |
| Homologação        | `STAGING`              | `pgp_test_`        | No ambiente de testes. Nenhuma cobrança é real. |

As duas chaves usam a **mesma URL base**. A PagPolar reconhece a chave de Homologação, ou o token obtido com ela, e leva a chamada para o ambiente de testes. Para saber o ambiente de uma chave, chame [`GET /me`](/docs/referencia/autenticacao/get-current-credential) e leia `environment`.

## Ambiente de testes

Ao criar a chave de Homologação, a PagPolar prepara uma **conta de testes** separada da sua conta real, com dados fictícios e cadastro já aprovado. A chave só funciona depois que a conta de testes fica pronta. Veja as etiquetas e as regras da chave em [A chave de Homologação](/docs/guias/fundamentos/credenciais#homologacao).

* Produtos, ofertas, vendas e clientes criados com a chave de Homologação ficam **só** no ambiente de testes. Eles não aparecem na sua conta real.
* PIX, boleto e cartão criados com a chave de Homologação **não cobram ninguém**.
* Se o ambiente de testes estiver fora do ar, veja [Ambiente de testes indisponível](/docs/guias/fundamentos/erros#sandbox-indisponivel).

## Comprar no ambiente de testes

No ambiente de testes, o pagamento passa por um **gateway de testes**. Ele aceita dados fictícios e aprova o pagamento sozinho:

| Dado                        | O que usar                                                                                                                          |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| CPF do cliente e do titular | Qualquer CPF **válido** (com dígitos verificadores corretos). Não precisa ser de uma pessoa real. Geradores de CPF de teste servem. |
| Cartão de crédito           | Número `4000 0000 0000 0010`, CVV `123`, qualquer nome de titular e qualquer validade futura.                                       |
| PIX                         | Crie a cobrança normalmente. O QR Code é gerado, mas não precisa ser pago.                                                          |

PIX e cartão são **aprovados cerca de 30 segundos** depois da criação da cobrança. Nesse momento a venda passa a `PAID`, `paid_at` é preenchido e o evento [`TRANSACTION_PAID`](/docs/webhooks/eventos/transaction-paid) chega na URL do webhook da chave de Homologação. Use esse intervalo para testar o fluxo de espera do webhook e a consulta da venda.

> **Outros números de cartão**
>
> Qualquer outro número de cartão pode ser recusado ou ficar sem resposta no gateway de testes. Para simular o caminho feliz, use o cartão acima.

## Onde o ambiente faz diferença

Com a chave de Homologação, **todas** as rotas rodam no ambiente de testes. Estas cobram, mudam, cancelam ou devolvem dinheiro de verdade quando a chamada usa a chave de Produção:

* `POST /payments/pix`
* `POST /payments/boleto`
* `POST /payments/credit-card`
* `POST /plans/offer/{id}/subscribe`
* `POST /subscriptions/{id}/plan-change`
* `PATCH /subscriptions/{id}/card`
* `DELETE /subscriptions/{id}` (cancela a assinatura; não pode ser desfeito)
* `POST /refunds`

## Testar pelo portal

As páginas da [Referência da API](/docs/referencia) têm o botão **Send**, que executa a operação no ambiente de testes sem você digitar chave nem token:

1. Entre no painel da PagPolar **neste navegador**.
2. Tenha uma chave de Homologação **pronta**. IPs autorizados da chave não valem para o playground: ele passa por essa restrição.
3. Abra uma operação na referência, preencha os campos e clique em **Send**.

O portal gera sozinho um token de 15 minutos para a sua chave de Homologação e envia a requisição por ele. Por isso o playground não tem campo `Authorization`: a autenticação é feita pelo portal. O playground só alcança o ambiente de testes: não há como criar uma cobrança real por ele.

| Resposta do playground                                    | O que fazer                                               |
| --------------------------------------------------------- | --------------------------------------------------------- |
| `401` com `playground_login_required`                     | Entre no painel neste navegador e tente de novo.          |
| `404` com a mensagem "Nenhuma chave de Homologação ativa" | Crie uma chave de Homologação em **Configurações → API**. |
| `409` avisando que o ambiente ainda não está pronto       | Espere a chave aparecer como pronta.                      |

`POST /auth/token` não roda pelo playground, porque ele recebe a chave de API. Teste essa rota pelo seu servidor.

## Chame a API do seu servidor

Faça as chamadas a partir do seu servidor (back-end), nunca a partir do navegador do cliente:

* **A chave é secreta.** Quem tiver a chave consegue criar cobranças e ler os dados dos seus clientes.
* **O navegador bloqueia a chamada.** A API só libera chamadas de navegador de uma lista fixa de origens da PagPolar. Uma chamada feita pelo JavaScript do seu site é bloqueada pelo navegador.

O fluxo certo é: o seu site chama o seu servidor, e o seu servidor chama a API com o token de acesso. A chave e o token ficam no servidor, nunca no navegador.

```mermaid
sequenceDiagram
  autonumber
  participant N as Navegador do cliente
  participant S as Seu servidor
  participant A as API PagPolar
  N->>S: pedido de compra
  S->>A: POST /payments/pix com o token no header Authorization
  A-->>S: 201 com pix.qr_code
  S-->>N: QR Code para o cliente pagar
```

## Próximos passos

- [Autenticação](/docs/guias/fundamentos/autenticacao) — Troque a chave pelo token e entenda os erros 401 e 403.
- [Início rápido](/docs/guias/inicio-rapido) — Faça a primeira venda PIX.