# Início rápido URL: 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. Ao final deste guia você terá: * uma credencial com chave de API e webhook; * um token de acesso para autenticar as chamadas; * um produto e uma oferta criados pela API; * uma venda PIX com o código "copia e cola" para o cliente pagar. > **Este guia usa a chave de Homologação** > > Com a chave de Homologação, todas as chamadas vão para o [ambiente de testes](/docs/guias/fundamentos/ambientes#ambiente-de-testes). O produto, a oferta e a venda ficam só lá, e o PIX do passo 7 é aprovado sozinho cerca de 30 segundos depois de criado. Veja [Comprar no ambiente de testes](/docs/guias/fundamentos/ambientes#dados-de-teste). ## Visão geral O diagrama mostra os passos deste guia, na ordem. ```mermaid sequenceDiagram autonumber participant V as Você no painel participant S as Seu servidor participant A as API PagPolar participant W as Seu servidor de webhook V->>A: cria a credencial com nome, ambiente e URL do webhook A-->>V: chave de API e token do webhook, uma única vez S->>A: POST /auth/token com X-API-Key A-->>S: 200 com access_token válido por 24 horas S->>A: GET /me com o token no header Authorization A-->>S: 200 com os dados da credencial S->>A: POST /products e POST /offers A-->>S: 201 com o id do produto e o código da oferta S->>A: POST /payments/pix com Idempotency-Key A-->>S: 201 com transactions e pix.qr_code A-)W: TRANSACTION_CREATED ``` ## Antes de começar * Uma conta de vendedor na PagPolar com o menu **Configurações → API**. * Um terminal com `curl`, ou Node.js 18 ou mais novo. Os exemplos em Node.js usam `await` direto no arquivo: salve o código em um arquivo `.mjs` e rode com `node arquivo.mjs`. * Uma URL pública no seu servidor para receber os webhooks. 1. **Crie a credencial no painel** 1. No painel da PagPolar, abra **Configurações → API**. 2. Clique em **Nova chave**. Abre o painel lateral **Criar nova chave de integração**. 3. Preencha os campos: | Campo | O que colocar | | ---------------------- | ---------------------------------------------------------------------------------------------- | | **Nome da integração** | Um nome para você reconhecer a credencial, como `Loja virtual`. | | **Ambiente** | **Homologação**. Não dá para mudar depois. Cada conta pode ter uma chave de Homologação ativa. | | **URL do webhook** | A URL do seu servidor que vai receber os avisos. | | **Eventos** | Deixe em branco para receber todos os eventos. | | **IPs autorizados** | Deixe em branco neste teste. Assim, qualquer IP é aceito. | A imagem mostra o ambiente **Produção**, o valor inicial do campo. Troque para **Homologação**. 4. Clique em **Salvar**. A PagPolar começa a preparar a sua conta de testes. Na lista de **Configurações → API**, a chave aparece com a etiqueta **Preparando ambiente de testes**. Atualize a tela até a etiqueta mudar para **Ambiente de testes pronto** antes de seguir para o passo 3. Veja [A chave de Homologação](/docs/guias/fundamentos/credenciais#homologacao). 2. **Guarde a chave e o token do webhook** Depois de salvar, abre a janela **Chave criada com sucesso**. Ela mostra dois valores: | Valor | Para que serve | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------- | | Chave de API | Vai no header `X-API-Key` de `POST /auth/token`, a rota que devolve o token de acesso. É o único lugar em que a chave é aceita. | | Token do webhook | Chega no header `Authorization` de cada webhook, para você confirmar que o aviso é da PagPolar. | Copie os dois e guarde no seu servidor, em variáveis de ambiente ou em um cofre de segredos. > **Os dois valores aparecem uma única vez** > > Depois de fechar a janela, não há como ver a chave nem o token de novo. Se perder algum dos dois, revogue a credencial e crie outra. 3. **Troque a chave pelo token de acesso** `POST /auth/token` é a única rota que recebe a chave. Ela devolve o token que autentica todas as outras chamadas. A requisição não tem corpo. #### cURL ```bash curl -X POST "https://api.pagpolar.com/v1/auth/token" \ -H "X-API-Key: " ``` #### Node.js ```js const apiUrl = 'https://api.pagpolar.com/v1'; async function obterToken() { const response = await fetch(`${apiUrl}/auth/token`, { method: 'POST', headers: { 'X-API-Key': '' }, }); const { data } = await response.json(); return data.access_token; } const accessToken = await obterToken(); console.log(accessToken); ``` Resposta `200`: ```json { "data": { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "Bearer", "expires_in": 86400 } } ``` Guarde `data.access_token` em memória. Ele é o valor que vai no header `Authorization` dos próximos passos. Os exemplos em Node.js daqui em diante usam a variável `accessToken` criada acima. Quando ele expirar, peça outro: veja [Validade](/docs/guias/fundamentos/autenticacao#validade) e [Renove o token quando receber 401](/docs/guias/fundamentos/autenticacao#renovar-no-401). 4. **Confirme o token com ** `GET /me` Chame `GET /me` com o token no header `Authorization`: #### cURL ```bash curl "https://api.pagpolar.com/v1/me" \ -H "Authorization: Bearer " ``` #### Node.js ```js const response = await fetch('https://api.pagpolar.com/v1/me', { headers: { Authorization: `Bearer ${accessToken}` }, }); console.log(response.status, await response.json()); ``` Se o token estiver certo, a resposta é `200`: ```json { "data": { "credential_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "environment": "STAGING", "rate_limit_per_minute": 120 } } ``` `environment: STAGING` confirma que a chamada foi atendida pelo ambiente de testes. Se a resposta for `401`, veja [Autenticação](/docs/guias/fundamentos/autenticacao). 5. **Crie um produto** #### cURL ```bash curl -X POST "https://api.pagpolar.com/v1/products" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "name": "Curso de exemplo", "description": "Produto criado no início rápido" }' ``` #### Node.js ```js const response = await fetch('https://api.pagpolar.com/v1/products', { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ name: 'Curso de exemplo', description: 'Produto criado no início rápido', }), }); console.log(response.status, await response.json()); ``` Resposta `201` (resumida): ```json { "data": { "id": "c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f", "name": "Curso de exemplo", "type": "DIGITAL", "is_active": true } } ``` Guarde `data.id`. Ele é o `` do próximo passo. Contrato completo: [`POST /products`](/docs/referencia/produtos/create-product). 6. **Crie uma oferta** A oferta define o preço e os meios de pagamento. `price` vai em **centavos**, como número inteiro (`1000` = R$ 10,00), e volta em **reais** na resposta (`10`). Veja [Valores nas respostas](/docs/guias/fundamentos/valores-datas-e-identificadores#valores-nas-respostas). #### cURL ```bash curl -X POST "https://api.pagpolar.com/v1/offers" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "product_id": "", "title": "Oferta de lançamento", "price": 1000, "is_enabled_pix": true, "is_enabled_credit_card": false, "is_enabled_billet": false, "max_credit_card_installments": 1 }' ``` #### Node.js ```js const response = await fetch('https://api.pagpolar.com/v1/offers', { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ product_id: '', title: 'Oferta de lançamento', price: 1000, is_enabled_pix: true, is_enabled_credit_card: false, is_enabled_billet: false, max_credit_card_installments: 1, }), }); console.log(response.status, await response.json()); ``` Resposta `201` (resumida): ```json { "data": { "id": "d5e6f7a8-b9c0-4d1e-2f3a-4b5c6d7e8f9a", "identifier": "PPP1234567890", "title": "Oferta de lançamento", "price": 10, "payment_methods": { "pix": true, "credit_card": false, "billet": false }, "max_credit_card_installments": 1 } } ``` Guarde `data.identifier`. Ele é o `` do próximo passo. Contrato completo: [`POST /offers`](/docs/referencia/ofertas/create-offer). > **Por que enviar max_credit_card_installments** > > Sem esse campo, a oferta vale 12 parcelas, e R$ 10,00 em 12 parcelas fica abaixo da [parcela mínima](/docs/guias/jornadas/criar-produto-e-oferta#parcela-minima): a criação responde `400`. Com `1`, a oferta passa. 7. **Crie a venda PIX** Envie o código da oferta e os dados do cliente. No ambiente de testes, `customer.document` pode ser qualquer CPF válido. Três headers são obrigatórios: | Header | Valor | | ----------------- | ----------------------------------------------------------------------------------------------------------- | | `Authorization` | `Bearer ` seguido do token de acesso do passo 3. | | `Idempotency-Key` | Um valor único para esta cobrança, como um UUID. Veja [Idempotência](/docs/guias/fundamentos/idempotencia). | | `Content-Type` | `application/json` | #### cURL ```bash curl -X POST "https://api.pagpolar.com/v1/payments/pix" \ -H "Authorization: Bearer " \ -H "Idempotency-Key: 6b1f2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d" \ -H "Content-Type: application/json" \ -d '{ "offer_identifier": "", "external_reference": "PEDIDO-0001", "customer": { "name": "Maria Silva", "email": "cliente@exemplo.com", "document": "", "phone": "" } }' ``` #### Node.js ```js import { randomUUID } from 'node:crypto'; const response = await fetch('https://api.pagpolar.com/v1/payments/pix', { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'Idempotency-Key': randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ offer_identifier: '', external_reference: 'PEDIDO-0001', customer: { name: 'Maria Silva', email: 'cliente@exemplo.com', document: '', phone: '', }, }), }); console.log(response.status, await response.json()); ``` | Campo | Obrigatório | O que é | | -------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `offer_identifier` | Sim, ou `offer` | Código da oferta. | | `external_reference` | Não | Código do seu pedido, até 255 caracteres. Serve para achar a venda depois. Veja [Como a venda é encontrada](/docs/guias/fundamentos/valores-datas-e-identificadores#como-a-venda-e-encontrada). | Dados do cliente: | Campo | Obrigatório | O que é | | ------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customer.name` | Sim | Nome do cliente, até 255 caracteres. | | `customer.email` | Sim | E-mail válido do cliente. | | `customer.document` | Sim | CPF ou CNPJ do cliente, com ou sem pontuação. Veja o formato em [Documento e telefone](/docs/guias/fundamentos/valores-datas-e-identificadores#documento-e-telefone). | | `customer.phone` | Sim | Telefone do cliente com DDD, com ou sem pontuação. Veja o formato em [Documento e telefone](/docs/guias/fundamentos/valores-datas-e-identificadores#documento-e-telefone). | Resposta `201`: ```json { "data": { "offer_identifier": "PPP1234567890", "transactions": ["a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"], "subscriptions": [], "pix": { "qr_code": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-4a7b-8c9d" } } } ``` | Campo | O que fazer com ele | | ----------------- | -------------------------------------------------------------------------- | | `transactions[0]` | É o `id` da venda. Guarde junto do seu pedido. | | `pix.qr_code` | Mostre ao cliente como "copia e cola" ou gere a imagem do QR Code com ele. | Contrato completo: [`POST /payments/pix`](/docs/referencia/vendas/create-pix-payment). 8. **Confira o resultado** **1. Consulte a venda.** Use o `id` que veio em `transactions[0]`: #### cURL ```bash curl "https://api.pagpolar.com/v1/sales/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" \ -H "Authorization: Bearer " ``` #### Node.js ```js const response = await fetch( 'https://api.pagpolar.com/v1/sales/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d', { headers: { Authorization: `Bearer ${accessToken}` } }, ); console.log(response.status, await response.json()); ``` Resposta `200` (resumida): ```json { "data": { "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "identifier": "PPO9876543210", "external_reference": "PEDIDO-0001", "status": "PROCESSING", "payment_method": "PIX", "total_amount": 10, "paid_at": null } } ``` Você também pode consultar pelo código da venda (`identifier`) ou pela sua referência: `GET /sales/PEDIDO-0001`. Veja [Como a venda é encontrada](/docs/guias/fundamentos/valores-datas-e-identificadores#como-a-venda-e-encontrada). **2. Veja o webhook.** A sua URL recebe o evento [`TRANSACTION_CREATED`](/docs/webhooks/eventos/transaction-created). **3. Entenda o pagamento.** Quando um PIX é pago, chega [`TRANSACTION_PAID`](/docs/webhooks/eventos/transaction-paid). A venda passa a `status: PAID` e `paid_at` é preenchido. No ambiente de testes, isso acontece sozinho, como no aviso do início deste guia. ## Se algo deu errado Além dos [erros comuns a todas as rotas](/docs/guias/fundamentos/erros#erros-comuns), este guia pode responder: | Passo | Situação | Resposta | Como resolver | | ----- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | A conta já tem 5 credenciais ativas, somando Produção e Homologação. | `Limite de 5 credenciais ativas atingido. Revogue uma credencial antes de criar outra.` | Revogue uma credencial sem uso. | | 1 | A conta já tem uma chave de Homologação ativa. | A opção **Homologação** fica desabilitada no campo **Ambiente**. | Use a chave de Homologação que você já tem, ou revogue-a e crie outra. | | 1 | A etiqueta da chave mudou para **Falha ao preparar ambiente de testes**. | O motivo aparece ao passar o mouse sobre a etiqueta. | Revogue a chave e crie outra. | | 3 | A chave ainda não está pronta no ambiente de testes. | `401 unauthorized` | Espere a etiqueta **Ambiente de testes pronto** e repita. | | 6 | `product_id` errado ou de outra conta. | `404` com `Produto não encontrado` | Use o `data.id` do passo 5. | | 6 | Parcela abaixo do mínimo. | `400` com `O valor da parcela (...) fica abaixo do mínimo permitido (...)` | Envie `max_credit_card_installments: 1`. | | 7 | Código da oferta errado. | `404` com `Oferta não encontrada` | Use o `data.identifier` do passo 6. | | 7 | PIX desligado na oferta. | `409` com `Método de pagamento PIX não habilitado para esta oferta` | Crie a oferta com `is_enabled_pix: true` e `price` a partir do [valor mínimo do PIX](/docs/guias/jornadas/criar-produto-e-oferta#meios-de-pagamento). | | 3 a 8 | O ambiente de testes está fora do ar ou não respondeu em 30 segundos. | `502 sandbox_unavailable` | Espere alguns segundos e repita. Veja [Erros](/docs/guias/fundamentos/erros#sandbox-indisponivel). | ## Próximos passos - [Credenciais da API](/docs/guias/fundamentos/credenciais) — Restrinja por IP e revogue credenciais. - [Autenticar as requisições recebidas](/docs/webhooks/autenticar-requisicoes) — Confirme que o webhook veio da PagPolar. - [Idempotência](/docs/guias/fundamentos/idempotencia) — Repita uma cobrança sem cobrar duas vezes.