{"openapi":"3.0.0","info":{"title":"PagPolar — API de Integração","version":"1.0.0","description":"API REST para integração de sistemas externos com a PagPolar.\n\n> 🤖 É um agente de IA? O índice da documentação em texto está em\n> [/docs/llms.txt](/docs/llms.txt), com o endereço e o resumo de cada guia. Os eventos de\n> webhook estão em [/docs/webhooks.json](/docs/webhooks.json).\n\n## Como usar esta especificação\nEste arquivo é o contrato de cada operação: parâmetros, corpos, respostas e erros. As regras\nque valem para todas as chamadas e o passo a passo de cada fluxo estão nos guias do portal:\n\n1. [Início rápido](/docs/guias/inicio-rapido): credencial, token de acesso e primeira venda.\n2. [Autenticação](/docs/guias/fundamentos/autenticacao): troque a `X-API-Key` pelo token em\n `POST /auth/token` e envie `Authorization: Bearer ` nas demais rotas.\n3. [Erros](/docs/guias/fundamentos/erros), [Idempotência](/docs/guias/fundamentos/idempotencia)\n e [Paginação e filtros](/docs/guias/fundamentos/paginacao-e-filtros).\n\nOs endpoints de venda (`POST /payments/pix`, `/payments/boleto`,\n`/payments/credit-card`) e o de troca de plano cobram de verdade e/ou têm efeito\ncolateral. Teste com a chave de Homologação, que leva as chamadas ao ambiente de testes.\n\nCada schema de resposta documenta os campos que podem vir `null` e os valores possíveis\nde campos com opções fixas (ex.: `status`, `payment_method`) — vale conferir antes de\nescrever o código que lê a resposta.\n\n## Autenticação e credencial\n\n### Criando uma credencial\nA criação é feita pelo painel, em **Configurações → API**\n(`/dashboard/configuracoes/api`):\n\n1. Clique em **\"Nova chave\"**.\n2. Preencha o nome da integração, escolha o ambiente (**Produção** ou **Homologação**) e\n informe a URL do webhook (e, opcionalmente, os eventos e os IPs autorizados).\n3. Clique em **\"Salvar\"**.\n\nA tela **\"Chave criada com sucesso\"** exibe a `api_key` e o `webhook_authorization`\n— **ambos aparecem uma única vez**, com botão de copiar para cada um. Guarde-os com\nsegurança; se perdê-los, revogue a credencial e crie outra.\n\nUm webhook dedicado é criado automaticamente e vinculado à credencial. Ele **não pode\nser removido nem desativado** enquanto a credencial estiver ativa; revogue a credencial\nprimeiro.\n\nLimite de 5 credenciais ativas por conta.\n\nToda credencial ativa acessa todos os endpoints desta API — não há permissões por\ncredencial.\n\n### Ambiente da credencial\nCada credencial pertence a um ambiente, escolhido na criação e que não pode ser alterado\ndepois. O ambiente aparece no prefixo da chave, para a integração não confundir as chaves:\n\n| Ambiente | Prefixo da chave |\n|---|---|\n| Produção (`PRODUCTION`, padrão) | `pgp_live_` |\n| Homologação (`STAGING`) | `pgp_test_` |\n\nO ambiente **identifica** a chave, mas não muda o processamento: uma chave de homologação\nopera sobre os mesmos dados e cobra de verdade, como a de produção.\n\nChaves emitidas antes da criação do ambiente não têm o segmento (`pgp__`),\npertencem a Produção e continuam válidas.\n\n### Primeiro passo: trocar a chave por um token\nA chave só é usada em uma rota: `POST /auth/token`. Ela devolve um **token de acesso**\nque vale 24 horas, e é esse token que vai em todas as outras chamadas.\n\n```bash\ncurl -X POST https://pagpolar-api.creativecode.dev.br/v1/auth/token \\\n -H \"X-API-Key: pgp_live_a1b2c3d4_\"\n```\n\n```json\n{\n \"data\": {\n \"access_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 86400\n }\n}\n```\n\nNas demais rotas, envie o token no header `Authorization`:\n\n```bash\ncurl https://pagpolar-api.creativecode.dev.br/v1/me \\\n -H \"Authorization: Bearer \"\n```\n\nGuarde o token em memória e reaproveite enquanto valer — não peça um token por requisição.\nQuando expirar, a API responde `401 unauthorized` com `Token expirado`: chame\n`POST /auth/token` de novo com a mesma chave. Não existe rota de renovação.\n\n`GET /me` é o jeito mais rápido de confirmar que o token está correto — retorna o\nambiente e o limite de requisições da credencial, sem depender de nenhum outro dado.\n\nRevogar a credencial derruba os tokens dela em até 1 minuto: cada requisição confere a\ncredencial por trás do token. Chave errada, ausente, expirada ou revogada responde\n`401 unauthorized`.\n\n## Quickstart — fazendo sua primeira venda\nToda venda aponta a oferta de **uma** destas formas — enviando uma, a outra não é necessária\n(as duas juntas, ou nenhuma, retornam `400`):\n\n| Campo | Uso |\n|---|---|\n| `offer_identifier` | Código de uma oferta existente (**GET /offers**) |\n| `offer` | Oferta informada na hora, sem cadastro prévio |\n\n```json\n{ \"offer_identifier\": \"1234567890\", \"customer\": { \"...\": \"...\" } }\n```\n\n```json\n{\n \"offer\": {\n \"product_id\": \"c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f\",\n \"name\": \"Consultoria avulsa\",\n \"value\": 4990,\n \"createOffer\": false\n },\n \"customer\": { \"...\": \"...\" }\n}\n```\n\nRegras de `offer`:\n- `value` em centavos, mínimo 500 (R$ 5,00).\n- Mesmo produto, nome, valor e visibilidade → reaproveita; senão cria.\n- `createOffer: false` → oferta **oculta**: fora das listagens, não abre por código, usável só aqui.\n- Parcelas: até 12x, respeitando parcela mínima de R$ 5,00; assinatura 1x.\n\nA resposta traz `offer_identifier` da oferta usada. Os exemplos abaixo usam\n`offer_identifier`, mas todos aceitam `offer`.\n\n### Venda de afiliado\nPara creditar a venda a um afiliado, envie `affiliate_identifier` com o código dele — o\nmesmo que aparece no link de divulgação (`PAO` seguido de 10 dígitos). Vale nos pagamentos\ne em `POST /plans/offer/{id}/subscribe`.\n\n- Formato inválido → `400`.\n- Código inexistente, de outro produto, de afiliação encerrada ou sem a oferta liberada para o\n afiliado → **ignorado**: a venda é processada normalmente, sem afiliado.\n- Não existe cookie nem regra de primeiro ou último clique pela API: vale o código enviado, e\n a escolha de qual afiliado creditar é do seu sistema.\n- Oferta criada na hora com `offer` só gera comissão se o afiliado tiver todas as ofertas\n do produto liberadas.\n- Comissão, repasse e recorrência seguem exatamente as regras da venda pelo checkout.\n\nTodas as chamadas abaixo exigem o header `Idempotency-Key` (qualquer string única por\ntentativa, ex.: um UUID) — reenviar a mesma chave nunca gera uma segunda cobrança.\n\n### PIX\n`POST /payments/pix`:\n\n```json\n{\n \"offer_identifier\": \"1234567890\",\n \"customer\": {\n \"name\": \"Fulano de Tal\",\n \"email\": \"fulano@exemplo.com\",\n \"document\": \"12345678909\",\n \"phone\": \"11999999999\"\n }\n}\n```\n\nResposta (`201`):\n\n```json\n{\n \"data\": {\n \"transactions\": [\"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d\"],\n \"subscriptions\": [],\n \"pix\": { \"qr_code\": \"00020126...\" }\n }\n}\n```\n\nUse `pix.qr_code` para gerar o QR Code ou o \"copia e cola\" na sua tela de checkout.\n\n### Boleto\n`POST /payments/boleto` — mesmo corpo do PIX (sem `installments` nem `credit_card`):\n\n```json\n{\n \"offer_identifier\": \"1234567890\",\n \"customer\": {\n \"name\": \"Fulano de Tal\",\n \"email\": \"fulano@exemplo.com\",\n \"document\": \"12345678909\",\n \"phone\": \"11999999999\"\n }\n}\n```\n\nResposta (`201`):\n\n```json\n{\n \"data\": {\n \"transactions\": [\"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d\"],\n \"subscriptions\": [],\n \"boleto\": {\n \"barcode\": \"34191.79001 01043.510047 91020.150008 1 96610000015000\",\n \"pdf_link\": \"https://boletos.pagpolar.com/a1b2c3d4.pdf\"\n }\n }\n}\n```\n\n### Cartão de crédito\n`POST /payments/credit-card` exige `installments` e o objeto `credit_card`:\n\n```json\n{\n \"offer_identifier\": \"1234567890\",\n \"installments\": 3,\n \"customer\": {\n \"name\": \"Fulano de Tal\",\n \"email\": \"fulano@exemplo.com\",\n \"document\": \"12345678909\",\n \"phone\": \"11999999999\"\n },\n \"credit_card\": {\n \"holder_name\": \"FULANO DE TAL\",\n \"holder_document\": \"12345678909\",\n \"number\": \"4111111111111111\",\n \"expiration_month\": 12,\n \"expiration_year\": 2030,\n \"cvv\": \"123\"\n }\n}\n```\n\nResposta (`201`):\n\n```json\n{\n \"data\": {\n \"transactions\": [\"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d\"],\n \"subscriptions\": []\n }\n}\n```\n\nO número de parcelas pode ser limitado pela oferta (confira\n`max_credit_card_installments` em `GET /offers/{identifier}`); acima do limite, a API\nresponde `400`.\n\n### Produto físico — endereço e frete\nOferta de produto físico (`requires_shipping: true` em `GET /offers/{identifier}`) exige\ndois campos a mais na cobrança: `address`, com o endereço de entrega, e\n`shipping_option_id`, com a opção de frete escolhida. Sem um deles a API responde `400`.\n\nO fluxo é:\n\n1. `GET /offers/{identifier}/shipping?postal_code=01311000` devolve as opções de entrega\n para aquele CEP, cada uma com `id`, valor e prazo;\n2. a cobrança (`POST /payments/pix`, `/boleto` ou `/credit-card`) vai com o `id`\n escolhido em `shipping_option_id` e com o mesmo CEP em `address.postal_code`;\n3. o frete entra no total cobrado e aparece em `shipping` na consulta da venda.\n\nAntes disso, o vendedor precisa ter feito no painel da PagPolar, uma vez por produto: a\nintegração de logística cadastrada, o peso e as dimensões do produto preenchidos e pelo\nmenos uma configuração de frete ativa. Sem isso a consulta de frete responde `400`.\n\nDepois do pagamento confirmado, a PagPolar gera o pedido de separação e o vendedor registra\no envio e o código de rastreio no painel.\n\n### E se a venda for de uma assinatura?\nNenhuma das rotas acima cria assinatura — mesmo apontando para uma oferta recorrente, o\nresultado é sempre uma cobrança avulsa (`subscriptions` sempre vem vazio). Para assinar um\ncliente de verdade, use `POST /plans/offer/{id}/subscribe` — veja a seção **Assinaturas —\nciclo de vida** logo abaixo.\n\n## Assinaturas — ciclo de vida\nUma assinatura (`Subscription`) é criada por `POST /plans/offer/{id}/subscribe` e evolui\npor um conjunto fixo de status (`GET /subscriptions/{id}` sempre reflete o atual). Esta\nseção descreve o fluxo real, ponta a ponta, para quem só usa a rota de criação — troca de\nplano e cancelamento têm suas próprias rotas na tag **Assinaturas**, descritas nelas mesmas.\n\n### 1. Criação — nasce em `DRAFT`\n`POST /plans/offer/{id}/subscribe` só aceita cartão de crédito. A cobrança do ciclo 1 é\nfeita no gateway **depois** da resposta HTTP — a assinatura sempre nasce com\n`status: DRAFT`, mesmo quando a chamada tem sucesso.\n\n### 2. Confirmação — assíncrona, via webhook ou polling\nSegundos depois, o gateway confirma (ou recusa) a cobrança. Não existe um jeito síncrono de\nsaber o resultado na mesma requisição de criação:\n- **Aceita pelo gateway**: webhook `SUBSCRIPTION_CONFIRMED`. O `status` continua `DRAFT`\n e vira `ACTIVE` quando a primeira fatura é paga.\n- **Recusa**: `status` vira `FAILED` (webhook `SUBSCRIPTION_FAILED`).\n\nAssine os dois eventos para saber o resultado assim que ele sai do gateway. Se preferir não\nusar webhook, faça polling em `GET /subscriptions/{id}` alguns segundos após a criação.\n\n### 3. Ativa e cobrando — renovações automáticas\nUma vez confirmada, a assinatura cobra automaticamente a cada ciclo (mensal, anual etc.,\nconforme o `cycle` da oferta), sem nova ação da sua integração. Cada cobrança gera uma\n`Transaction` própria — consultável em `GET /sales`/`GET /sales/{identifier}` e notificada\npelos eventos de transação (`TRANSACTION_PAID`, `TRANSACTION_CANCELED` etc.). O webhook\n`SUBSCRIPTION_RENEWED` é disparado especificamente quando um ciclo além do primeiro é pago\ncom sucesso — é sobre a assinatura em si (não substitui `TRANSACTION_PAID`, que é sobre a\ncobrança daquele ciclo).\n\n### 4. Trocar de plano — não altera o ciclo de vida acima\n`POST /subscriptions/{id}/plan-change` troca a oferta/valor de uma assinatura já ativa.\nUpgrade cobra a diferença de imediato; downgrade é agendado para o próximo ciclo. Nenhum dos\ndois interrompe o fluxo de renovação descrito no passo 3 — a assinatura segue cobrando\nnormalmente, só que pela nova oferta a partir do momento efetivo da troca. Veja\n`GET /subscriptions/{id}/plan-options` e `POST /subscriptions/{id}/plan-change/preview`\nantes de executar.\n\n### 5. Cancelamento — imediato ou assíncrono, dependendo do método\n`DELETE /subscriptions/{id}` solicita o cancelamento. Como a assinatura criada por esta API\né sempre cartão, o cancelamento **não é imediato**: o `status` vira `CANCELING` na hora e só\nmuda para `CANCELED` quando o gateway confirmar (assíncrono, mesmo mecanismo do passo 2).\nAssine o webhook `SUBSCRIPTION_CANCELED` para saber quando o cancelamento é efetivado.\n\n### Resumo visual (caminho de cartão)\n```\nDRAFT ──(gateway confirma)──> ACTIVE ──(cada ciclo pago)──> ACTIVE (renovação)\nDRAFT ──(gateway recusa)────> FAILED\nACTIVE ──(DELETE /subscriptions/{id})──> CANCELING ──(gateway confirma)──> CANCELED\n```\n\n## Paginação\nEndpoints de listagem aceitam `page` e `per_page` (máximo 100) e respondem com\n`{ data, meta }`.\n\n## Idempotência\n`POST /payments/pix`, `POST /payments/boleto`, `POST /payments/credit-card`,\n`POST /plans/offer/{id}/subscribe` e `POST /subscriptions/{id}/plan-change` exigem o\nheader `Idempotency-Key`. Repetir a\nmesma chave devolve a resposta original com o header `Idempotency-Replayed: true`, sem\ncriar uma nova cobrança/assinatura. Use um UUID por tentativa e reenvie o mesmo valor em\ncaso de timeout.\n\n## Limites de requisição\nO limite é definido pela plataforma e não é configurável na criação da credencial: vale o\n`rate_limit_per_minute` da credencial, 120 por minuto no padrão, exibido em `GET /me`.\n\nÉ **um limite só**: toda chamada, em qualquer rota, conta na mesma contagem da credencial.\nNão há limite separado por rota. Para mais requisições por minuto, fale com o suporte.\n\nToda resposta traz `X-RateLimit-Limit`, `X-RateLimit-Remaining` e `X-RateLimit-Reset`.\nAs rotas que movimentam dinheiro (cobranças, assinatura, reembolso, troca de plano e troca\nde cartão) respondem `503` quando o controle de limite está fora do ar; as demais seguem.\n\n## Erros\nTodos os erros seguem o formato `{ \"error\": { \"code\", \"message\", \"request_id\" } }`.\nInforme o `request_id` ao acionar o suporte.\n\n## Webhooks\nCada credencial possui um webhook dedicado, criado automaticamente na criação da\ncredencial, que recebe uma notificação **HTTP POST** para cada evento de venda ou\nassinatura. É assim que sua integração sabe que um PIX foi pago, sem precisar ficar\nconsultando `GET /sales/{identifier}` em loop.\n\nEsta seção traz o payload de exemplo de cada um dos 15 eventos, resumido ao essencial\npara você reconhecer o formato rapidamente.\n\n### Eventos disponíveis\n| Evento | Quando é enviado |\n|---|---|\n| `TRANSACTION_CREATED` | Transação criada no checkout ou pela API |\n| `TRANSACTION_PENDING` | Cobrança de renovação de assinatura (PIX/boleto) gerada e aguardando pagamento |\n| `TRANSACTION_PAID` | Pagamento confirmado pelo gateway |\n| `TRANSACTION_CANCELED` | Transação cancelada antes do pagamento, ou estorno de transação não paga. A recusa do cartão **não** gera este evento: a venda fica `FAILED`, sem evento |\n| `TRANSACTION_EXPIRED` | Transação expirada (renovação não paga a tempo) |\n| `TRANSACTION_REFUNDED` | Reembolso efetuado com sucesso |\n| `TRANSACTION_ASK_REFUNDING` | Solicitação de reembolso (garantia) recebida |\n| `TRANSACTION_CHARGEBACK_APPROVED` | Chargeback aprovado pelo emissor do cartão |\n| `SUBSCRIPTION_CREATED` | Nova assinatura criada |\n| `SUBSCRIPTION_CONFIRMED` | Assinatura em cartão aceita pelo gateway (o status continua `DRAFT` até a primeira fatura ser paga) |\n| `SUBSCRIPTION_FAILED` | Assinatura em cartão recusada/falhou ao confirmar no gateway |\n| `SUBSCRIPTION_RENEWED` | Um ciclo de cobrança (que não o primeiro) foi pago com sucesso |\n| `SUBSCRIPTION_CANCELED` | Assinatura cancelada |\n| `SUBSCRIPTION_DELAYED` | Assinatura com pagamento atrasado (dentro do prazo de carência) |\n| `SUBSCRIPTION_EXPIRED` | Assinatura expirada (renovação não efetuada dentro do prazo de carência) |\n\n### Formato\nTodo evento chega no formato:\n\n```json\n{\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"event\": \"TRANSACTION_PAID\",\n \"creation_date\": \"2026-01-29T14:35:00.000Z\",\n \"version\": \"1.0.0\",\n \"data\": { }\n}\n```\n\nO conteúdo de `data` muda conforme o evento — veja o exemplo de cada um abaixo.\n\n### Payload de cada evento\nTodos os eventos de transação trazem `transaction`, `items`, `buyer` e (quando\naplicável) `subscription` dentro de `data`. Quando a transação é do tipo **DIRECT** e\ntem order bumps/upsells associados, o payload ganha o campo `order_bumps` (array de\ntransações relacionadas); quando a transação é **ORDERBUMP** ou **UPSELL**, ganha o campo\n`reference_transaction` com os dados da transação principal (pai). Isso não está\nrepetido em cada exemplo abaixo para não poluir — vale para todo evento de transação.\n\n### De onde veio a venda (`source`)\nTodo evento traz `source` dentro de `data`, dizendo por qual canal a venda nasceu:\n\n| `source.channel` | Significado |\n|---|---|\n| `CHECKOUT` | Compra feita pelo checkout da PagPolar |\n| `API` | Pedido criado por uma integração via esta API |\n| `MANUAL` | Venda cortesia gerada manualmente pelo vendedor (por exemplo, um ingresso emitido para alguém) |\n| `AWARD` | Venda gerada como prêmio para afiliado |\n\n`source.api_credential_id` traz o id da credencial que criou o pedido quando o canal é\n`API`, e vem `null` nos demais canais. Order bumps, upsells e renovações herdam o canal da\nvenda original; eventos de assinatura usam o canal da primeira cobrança da assinatura. Use\nesse campo para ignorar eventos de vendas que sua integração não criou.\n\n#### TRANSACTION_CREATED\nTransação criada no checkout, ainda em processamento (`paid_at` nulo).\n\n```json\n{\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"event\": \"TRANSACTION_CREATED\",\n \"creation_date\": \"2026-01-29T14:00:00.000Z\",\n \"version\": \"1.0.0\",\n \"data\": {\n \"transaction\": {\n \"id\": \"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d\",\n \"identifier\": \"0087103960\",\n \"status\": \"PROCESSING\",\n \"payment_method\": \"CREDIT_CARD\",\n \"total_amount\": 197,\n \"installments\": 3,\n \"cycle\": 1,\n \"paid_at\": null,\n \"created_at\": \"2026-01-29T14:00:00.000Z\"\n },\n \"items\": [\n {\n \"quantity\": 1,\n \"amount\": 197,\n \"product\": {\n \"id\": \"c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f\",\n \"name\": \"Curso Completo de Marketing Digital\",\n \"type\": \"DIGITAL\"\n },\n \"price\": {\n \"id\": \"d5e6f7a8-b9c0-4d1e-2f3a-4b5c6d7e8f9a\",\n \"title\": \"Plano Anual\",\n \"identifier\": \"1234567890\"\n }\n }\n ],\n \"buyer\": {\n \"name\": \"João Silva\",\n \"email\": \"joao.silva@email.com\",\n \"document\": \"12345678900\",\n \"phone\": \"11999999999\"\n },\n \"subscription\": null,\n \"source\": {\n \"channel\": \"API\",\n \"api_credential_id\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"\n }\n }\n}\n```\n\n#### TRANSACTION_PENDING\nCobrança de renovação de assinatura em PIX ou boleto gerada e aguardando pagamento. Traz\n`subscription` preenchida, já que só ocorre em renovação. Se a cobrança do ciclo anterior\nnão foi paga, ela chega antes como `TRANSACTION_EXPIRED`.\n\n```json\n{\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"event\": \"TRANSACTION_PENDING\",\n \"creation_date\": \"2026-03-01T10:00:00.000Z\",\n \"version\": \"1.0.0\",\n \"data\": {\n \"transaction\": {\n \"id\": \"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d\",\n \"identifier\": \"0087103960\",\n \"status\": \"DRAFT\",\n \"payment_method\": \"BOLETO\",\n \"total_amount\": 197,\n \"installments\": 1,\n \"cycle\": 2,\n \"paid_at\": null,\n \"created_at\": \"2026-01-29T14:00:00.000Z\"\n },\n \"items\": [\n {\n \"quantity\": 1,\n \"amount\": 197,\n \"product\": {\n \"id\": \"c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f\",\n \"name\": \"Curso Completo de Marketing Digital\",\n \"type\": \"DIGITAL\"\n },\n \"price\": {\n \"id\": \"d5e6f7a8-b9c0-4d1e-2f3a-4b5c6d7e8f9a\",\n \"title\": \"Plano Anual\",\n \"identifier\": \"1234567890\"\n }\n }\n ],\n \"buyer\": {\n \"name\": \"João Silva\",\n \"email\": \"joao.silva@email.com\",\n \"document\": \"12345678900\",\n \"phone\": \"11999999999\"\n },\n \"subscription\": {\n \"id\": \"f7a8b9c0-d1e2-4f3a-4b5c-6d7e8f9a0b1c\",\n \"status\": \"ACTIVE\",\n \"start_at\": \"2026-01-01T00:00:00.000Z\",\n \"next_billing_at\": \"2026-02-01T00:00:00.000Z\"\n },\n \"source\": {\n \"channel\": \"API\",\n \"api_credential_id\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"\n }\n }\n}\n```\n\n#### TRANSACTION_PAID\nPagamento confirmado pelo gateway — a transação muda para `PAID`.\n\n```json\n{\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"event\": \"TRANSACTION_PAID\",\n \"creation_date\": \"2026-01-29T14:35:00.000Z\",\n \"version\": \"1.0.0\",\n \"data\": {\n \"transaction\": {\n \"id\": \"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d\",\n \"identifier\": \"0087103960\",\n \"status\": \"PAID\",\n \"payment_method\": \"CREDIT_CARD\",\n \"total_amount\": 197,\n \"installments\": 3,\n \"cycle\": 1,\n \"paid_at\": \"2026-01-29T14:35:00.000Z\",\n \"created_at\": \"2026-01-29T14:00:00.000Z\"\n },\n \"items\": [\n {\n \"quantity\": 1,\n \"amount\": 197,\n \"product\": {\n \"id\": \"c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f\",\n \"name\": \"Curso Completo de Marketing Digital\",\n \"type\": \"DIGITAL\"\n },\n \"price\": {\n \"id\": \"d5e6f7a8-b9c0-4d1e-2f3a-4b5c6d7e8f9a\",\n \"title\": \"Plano Anual\",\n \"identifier\": \"1234567890\"\n }\n }\n ],\n \"buyer\": {\n \"name\": \"João Silva\",\n \"email\": \"joao.silva@email.com\",\n \"document\": \"12345678900\",\n \"phone\": \"11999999999\"\n },\n \"subscription\": null,\n \"source\": {\n \"channel\": \"API\",\n \"api_credential_id\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"\n }\n }\n}\n```\n\n#### TRANSACTION_CANCELED\nTransação cancelada antes da confirmação do pagamento. A recusa do cartão **não** gera este\nevento: a venda fica `FAILED` e nenhum evento é enviado.\n\n```json\n{\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"event\": \"TRANSACTION_CANCELED\",\n \"creation_date\": \"2026-01-30T09:00:00.000Z\",\n \"version\": \"1.0.0\",\n \"data\": {\n \"transaction\": {\n \"id\": \"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d\",\n \"identifier\": \"0087103960\",\n \"status\": \"CANCELED\",\n \"payment_method\": \"CREDIT_CARD\",\n \"total_amount\": 197,\n \"installments\": 3,\n \"cycle\": 1,\n \"paid_at\": null,\n \"created_at\": \"2026-01-29T14:00:00.000Z\"\n },\n \"items\": [\n {\n \"quantity\": 1,\n \"amount\": 197,\n \"product\": {\n \"id\": \"c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f\",\n \"name\": \"Curso Completo de Marketing Digital\",\n \"type\": \"DIGITAL\"\n },\n \"price\": {\n \"id\": \"d5e6f7a8-b9c0-4d1e-2f3a-4b5c6d7e8f9a\",\n \"title\": \"Plano Anual\",\n \"identifier\": \"1234567890\"\n }\n }\n ],\n \"buyer\": {\n \"name\": \"João Silva\",\n \"email\": \"joao.silva@email.com\",\n \"document\": \"12345678900\",\n \"phone\": \"11999999999\"\n },\n \"subscription\": null,\n \"source\": {\n \"channel\": \"API\",\n \"api_credential_id\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"\n }\n }\n}\n```\n\n#### TRANSACTION_EXPIRED\nTransação de renovação de assinatura expirada sem pagamento (PIX/boleto não pago dentro\ndo prazo). Traz `subscription` preenchida, já que só ocorre em renovação.\n\n```json\n{\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"event\": \"TRANSACTION_EXPIRED\",\n \"creation_date\": \"2026-03-01T10:00:00.000Z\",\n \"version\": \"1.0.0\",\n \"data\": {\n \"transaction\": {\n \"id\": \"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d\",\n \"identifier\": \"0087103960\",\n \"status\": \"EXPIRED\",\n \"payment_method\": \"BOLETO\",\n \"total_amount\": 197,\n \"installments\": 3,\n \"cycle\": 1,\n \"paid_at\": null,\n \"created_at\": \"2026-01-29T14:00:00.000Z\"\n },\n \"items\": [\n {\n \"quantity\": 1,\n \"amount\": 197,\n \"product\": {\n \"id\": \"c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f\",\n \"name\": \"Curso Completo de Marketing Digital\",\n \"type\": \"DIGITAL\"\n },\n \"price\": {\n \"id\": \"d5e6f7a8-b9c0-4d1e-2f3a-4b5c6d7e8f9a\",\n \"title\": \"Plano Anual\",\n \"identifier\": \"1234567890\"\n }\n }\n ],\n \"buyer\": {\n \"name\": \"João Silva\",\n \"email\": \"joao.silva@email.com\",\n \"document\": \"12345678900\",\n \"phone\": \"11999999999\"\n },\n \"subscription\": {\n \"id\": \"f7a8b9c0-d1e2-4f3a-4b5c-6d7e8f9a0b1c\",\n \"status\": \"ACTIVE\",\n \"start_at\": \"2026-01-01T00:00:00.000Z\",\n \"next_billing_at\": \"2026-02-01T00:00:00.000Z\"\n },\n \"source\": {\n \"channel\": \"API\",\n \"api_credential_id\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"\n }\n }\n}\n```\n\n#### TRANSACTION_REFUNDED\nReembolso efetuado com sucesso. O objeto `transaction` ganha `refund_reason` e\n`refund_at` preenchido com a data do reembolso.\n\n```json\n{\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"event\": \"TRANSACTION_REFUNDED\",\n \"creation_date\": \"2026-02-05T16:00:00.000Z\",\n \"version\": \"1.0.0\",\n \"data\": {\n \"transaction\": {\n \"id\": \"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d\",\n \"identifier\": \"0087103960\",\n \"status\": \"REFUNDED\",\n \"payment_method\": \"CREDIT_CARD\",\n \"total_amount\": 197,\n \"installments\": 3,\n \"cycle\": 1,\n \"paid_at\": \"2026-01-29T14:35:00.000Z\",\n \"created_at\": \"2026-01-29T14:00:00.000Z\",\n \"refund_reason\": \"Produto não atendeu às expectativas do cliente\",\n \"refund_at\": \"2026-02-05T16:00:00.000Z\"\n },\n \"items\": [\n {\n \"quantity\": 1,\n \"amount\": 197,\n \"product\": {\n \"id\": \"c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f\",\n \"name\": \"Curso Completo de Marketing Digital\",\n \"type\": \"DIGITAL\"\n },\n \"price\": {\n \"id\": \"d5e6f7a8-b9c0-4d1e-2f3a-4b5c6d7e8f9a\",\n \"title\": \"Plano Anual\",\n \"identifier\": \"1234567890\"\n }\n }\n ],\n \"buyer\": {\n \"name\": \"João Silva\",\n \"email\": \"joao.silva@email.com\",\n \"document\": \"12345678900\",\n \"phone\": \"11999999999\"\n },\n \"subscription\": null,\n \"source\": {\n \"channel\": \"API\",\n \"api_credential_id\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"\n }\n }\n}\n```\n\n#### TRANSACTION_ASK_REFUNDING\nCliente solicitou reembolso (garantia) — a transação **ainda não** foi reembolsada, só a\nsolicitação foi registrada. `refund_at` vem `null` até o reembolso ser efetuado (aí\nsim dispara `TRANSACTION_REFUNDED`).\n\n```json\n{\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"event\": \"TRANSACTION_ASK_REFUNDING\",\n \"creation_date\": \"2026-02-03T11:30:00.000Z\",\n \"version\": \"1.0.0\",\n \"data\": {\n \"transaction\": {\n \"id\": \"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d\",\n \"identifier\": \"0087103960\",\n \"status\": \"ASK_REFUND\",\n \"payment_method\": \"CREDIT_CARD\",\n \"total_amount\": 197,\n \"installments\": 3,\n \"cycle\": 1,\n \"paid_at\": \"2026-01-29T14:35:00.000Z\",\n \"created_at\": \"2026-01-29T14:00:00.000Z\",\n \"refund_reason\": \"Produto não atendeu às expectativas do cliente\",\n \"refund_at\": null\n },\n \"items\": [\n {\n \"quantity\": 1,\n \"amount\": 197,\n \"product\": {\n \"id\": \"c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f\",\n \"name\": \"Curso Completo de Marketing Digital\",\n \"type\": \"DIGITAL\"\n },\n \"price\": {\n \"id\": \"d5e6f7a8-b9c0-4d1e-2f3a-4b5c6d7e8f9a\",\n \"title\": \"Plano Anual\",\n \"identifier\": \"1234567890\"\n }\n }\n ],\n \"buyer\": {\n \"name\": \"João Silva\",\n \"email\": \"joao.silva@email.com\",\n \"document\": \"12345678900\",\n \"phone\": \"11999999999\"\n },\n \"subscription\": null,\n \"source\": {\n \"channel\": \"API\",\n \"api_credential_id\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"\n }\n }\n}\n```\n\n#### TRANSACTION_CHARGEBACK_APPROVED\nO emissor do cartão aprovou uma contestação (chargeback). O valor é revertido e o objeto\n`transaction` ganha `chargeback_approved_at`. Diferente de `TRANSACTION_REFUNDED`, não traz\n`refund_reason` nem `refund_at`.\n\n```json\n{\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"event\": \"TRANSACTION_CHARGEBACK_APPROVED\",\n \"creation_date\": \"2026-02-10T09:15:00.000Z\",\n \"version\": \"1.0.0\",\n \"data\": {\n \"transaction\": {\n \"id\": \"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d\",\n \"identifier\": \"0087103960\",\n \"status\": \"CHARGEBACK_APPROVED\",\n \"payment_method\": \"CREDIT_CARD\",\n \"total_amount\": 197,\n \"installments\": 3,\n \"cycle\": 1,\n \"paid_at\": \"2026-01-29T14:35:00.000Z\",\n \"created_at\": \"2026-01-29T14:00:00.000Z\",\n \"chargeback_approved_at\": \"2026-02-10T09:15:00.000Z\"\n },\n \"items\": [\n {\n \"quantity\": 1,\n \"amount\": 197,\n \"product\": {\n \"id\": \"c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f\",\n \"name\": \"Curso Completo de Marketing Digital\",\n \"type\": \"DIGITAL\"\n },\n \"price\": {\n \"id\": \"d5e6f7a8-b9c0-4d1e-2f3a-4b5c6d7e8f9a\",\n \"title\": \"Plano Anual\",\n \"identifier\": \"1234567890\"\n }\n }\n ],\n \"buyer\": {\n \"name\": \"João Silva\",\n \"email\": \"joao.silva@email.com\",\n \"document\": \"12345678900\",\n \"phone\": \"11999999999\"\n },\n \"subscription\": null,\n \"source\": {\n \"channel\": \"API\",\n \"api_credential_id\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"\n }\n }\n}\n```\n\n#### SUBSCRIPTION_CREATED\nNova assinatura criada — traz `subscription`, `product` e `buyer`, sem `transaction`\n(o pagamento do primeiro ciclo é notificado separadamente via `TRANSACTION_PAID`).\n\n```json\n{\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"event\": \"SUBSCRIPTION_CREATED\",\n \"creation_date\": \"2026-01-28T10:00:00.000Z\",\n \"version\": \"1.0.0\",\n \"data\": {\n \"subscription\": {\n \"id\": \"f7a8b9c0-d1e2-4f3a-4b5c-6d7e8f9a0b1c\",\n \"external_id\": \"sub_pagarme_abc123\",\n \"status\": \"ACTIVE\",\n \"start_at\": \"2026-01-28T10:00:00.000Z\",\n \"end_at\": null,\n \"next_billing_at\": \"2026-02-28T10:00:00.000Z\",\n \"payment_method\": \"CREDIT_CARD\",\n \"total_amount\": 49.9,\n \"created_at\": \"2026-01-28T10:00:00.000Z\"\n },\n \"product\": {\n \"id\": \"c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f\",\n \"name\": \"Assinatura Premium Mensal\",\n \"type\": \"DIGITAL\"\n },\n \"buyer\": {\n \"name\": \"João Silva\",\n \"email\": \"joao.silva@email.com\",\n \"document\": \"12345678900\",\n \"phone\": \"11999999999\"\n },\n \"source\": {\n \"channel\": \"API\",\n \"api_credential_id\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"\n }\n }\n}\n```\n\n#### SUBSCRIPTION_CONFIRMED\nAssinatura em **cartão de crédito** confirmada de fato no gateway — dispara depois de\n`SUBSCRIPTION_CREATED` (que já chega com `status: DRAFT`), quando a cobrança é criada com\nsucesso no gateway e `external_id` é preenchido. O `status` **continua `DRAFT`** — a\nassinatura só vira `ACTIVE` quando a primeira fatura é paga. Não existe para PIX/boleto,\nque já nascem confirmados sincronamente.\n\n```json\n{\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"event\": \"SUBSCRIPTION_CONFIRMED\",\n \"creation_date\": \"2026-02-10T10:05:00.000Z\",\n \"version\": \"1.0.0\",\n \"data\": {\n \"subscription\": {\n \"id\": \"f7a8b9c0-d1e2-4f3a-4b5c-6d7e8f9a0b1c\",\n \"external_id\": \"sub_pagarme_abc123\",\n \"status\": \"DRAFT\",\n \"start_at\": \"2026-01-28T10:00:00.000Z\",\n \"end_at\": null,\n \"next_billing_at\": \"2026-02-28T10:00:00.000Z\",\n \"payment_method\": \"CREDIT_CARD\",\n \"total_amount\": 49.9,\n \"created_at\": \"2026-01-28T10:00:00.000Z\"\n },\n \"product\": {\n \"id\": \"c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f\",\n \"name\": \"Assinatura Premium Mensal\",\n \"type\": \"DIGITAL\"\n },\n \"buyer\": {\n \"name\": \"João Silva\",\n \"email\": \"joao.silva@email.com\",\n \"document\": \"12345678900\",\n \"phone\": \"11999999999\"\n },\n \"source\": {\n \"channel\": \"API\",\n \"api_credential_id\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"\n }\n }\n}\n```\n\n#### SUBSCRIPTION_FAILED\nAssinatura em **cartão de crédito** recusada ou com erro ao confirmar no gateway —\n`status` vira `FAILED`. Dispara no lugar de `SUBSCRIPTION_CONFIRMED` quando a criação no\ngateway falha (cartão recusado, erro do provedor).\n\n```json\n{\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"event\": \"SUBSCRIPTION_FAILED\",\n \"creation_date\": \"2026-02-10T10:05:00.000Z\",\n \"version\": \"1.0.0\",\n \"data\": {\n \"subscription\": {\n \"id\": \"f7a8b9c0-d1e2-4f3a-4b5c-6d7e8f9a0b1c\",\n \"external_id\": null,\n \"status\": \"FAILED\",\n \"start_at\": \"2026-01-28T10:00:00.000Z\",\n \"end_at\": null,\n \"next_billing_at\": \"2026-02-28T10:00:00.000Z\",\n \"payment_method\": \"CREDIT_CARD\",\n \"total_amount\": 49.9,\n \"created_at\": \"2026-01-28T10:00:00.000Z\"\n },\n \"product\": {\n \"id\": \"c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f\",\n \"name\": \"Assinatura Premium Mensal\",\n \"type\": \"DIGITAL\"\n },\n \"buyer\": {\n \"name\": \"João Silva\",\n \"email\": \"joao.silva@email.com\",\n \"document\": \"12345678900\",\n \"phone\": \"11999999999\"\n },\n \"source\": {\n \"channel\": \"API\",\n \"api_credential_id\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"\n }\n }\n}\n```\n\n#### SUBSCRIPTION_RENEWED\nUm ciclo de cobrança que **não** é o primeiro foi pago com sucesso (renovação). O\npagamento em si (a transação do ciclo) é notificado separadamente via `TRANSACTION_PAID`\n— este evento é sobre a assinatura como um todo, com `next_billing_at` já atualizado\npara o próximo ciclo.\n\n```json\n{\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"event\": \"SUBSCRIPTION_RENEWED\",\n \"creation_date\": \"2026-03-01T10:05:00.000Z\",\n \"version\": \"1.0.0\",\n \"data\": {\n \"subscription\": {\n \"id\": \"f7a8b9c0-d1e2-4f3a-4b5c-6d7e8f9a0b1c\",\n \"external_id\": \"sub_pagarme_abc123\",\n \"status\": \"ACTIVE\",\n \"start_at\": \"2026-01-28T10:00:00.000Z\",\n \"end_at\": null,\n \"next_billing_at\": \"2026-04-01T00:00:00.000Z\",\n \"payment_method\": \"CREDIT_CARD\",\n \"total_amount\": 49.9,\n \"created_at\": \"2026-01-28T10:00:00.000Z\"\n },\n \"product\": {\n \"id\": \"c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f\",\n \"name\": \"Assinatura Premium Mensal\",\n \"type\": \"DIGITAL\"\n },\n \"buyer\": {\n \"name\": \"João Silva\",\n \"email\": \"joao.silva@email.com\",\n \"document\": \"12345678900\",\n \"phone\": \"11999999999\"\n },\n \"source\": {\n \"channel\": \"API\",\n \"api_credential_id\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"\n }\n }\n}\n```\n\n#### SUBSCRIPTION_CANCELED\nAssinatura cancelada — `end_at` é preenchido com a data do cancelamento.\n\n```json\n{\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"event\": \"SUBSCRIPTION_CANCELED\",\n \"creation_date\": \"2026-03-15T08:00:00.000Z\",\n \"version\": \"1.0.0\",\n \"data\": {\n \"subscription\": {\n \"id\": \"f7a8b9c0-d1e2-4f3a-4b5c-6d7e8f9a0b1c\",\n \"external_id\": \"sub_pagarme_abc123\",\n \"status\": \"CANCELED\",\n \"start_at\": \"2026-01-28T10:00:00.000Z\",\n \"end_at\": \"2026-03-15T08:00:00.000Z\",\n \"next_billing_at\": \"2026-02-28T10:00:00.000Z\",\n \"payment_method\": \"CREDIT_CARD\",\n \"total_amount\": 49.9,\n \"created_at\": \"2026-01-28T10:00:00.000Z\"\n },\n \"product\": {\n \"id\": \"c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f\",\n \"name\": \"Assinatura Premium Mensal\",\n \"type\": \"DIGITAL\"\n },\n \"buyer\": {\n \"name\": \"João Silva\",\n \"email\": \"joao.silva@email.com\",\n \"document\": \"12345678900\",\n \"phone\": \"11999999999\"\n },\n \"source\": {\n \"channel\": \"API\",\n \"api_credential_id\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"\n }\n }\n}\n```\n\n#### SUBSCRIPTION_DELAYED\nPagamento da renovação atrasado, mas ainda dentro do prazo de carência —\n`status` permanece `PENDING_RENEWAL` até expirar (aí dispara `SUBSCRIPTION_EXPIRED`).\n\n```json\n{\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"event\": \"SUBSCRIPTION_DELAYED\",\n \"creation_date\": \"2026-02-19T08:00:00.000Z\",\n \"version\": \"1.0.0\",\n \"data\": {\n \"subscription\": {\n \"id\": \"f7a8b9c0-d1e2-4f3a-4b5c-6d7e8f9a0b1c\",\n \"external_id\": null,\n \"status\": \"PENDING_RENEWAL\",\n \"start_at\": \"2026-01-28T10:00:00.000Z\",\n \"end_at\": null,\n \"next_billing_at\": \"2026-02-28T10:00:00.000Z\",\n \"payment_method\": \"BOLETO\",\n \"total_amount\": 49.9,\n \"created_at\": \"2026-01-28T10:00:00.000Z\"\n },\n \"product\": {\n \"id\": \"c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f\",\n \"name\": \"Assinatura Premium Mensal\",\n \"type\": \"DIGITAL\"\n },\n \"buyer\": {\n \"name\": \"João Silva\",\n \"email\": \"joao.silva@email.com\",\n \"document\": \"12345678900\",\n \"phone\": \"11999999999\"\n },\n \"source\": {\n \"channel\": \"API\",\n \"api_credential_id\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"\n }\n }\n}\n```\n\n#### SUBSCRIPTION_EXPIRED\nAssinatura expirada por falta de renovação dentro do prazo de carência.\n\n```json\n{\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"event\": \"SUBSCRIPTION_EXPIRED\",\n \"creation_date\": \"2026-02-18T09:00:00.000Z\",\n \"version\": \"1.0.0\",\n \"data\": {\n \"subscription\": {\n \"id\": \"f7a8b9c0-d1e2-4f3a-4b5c-6d7e8f9a0b1c\",\n \"external_id\": null,\n \"status\": \"EXPIRED\",\n \"start_at\": \"2026-01-28T10:00:00.000Z\",\n \"end_at\": null,\n \"next_billing_at\": \"2026-02-28T10:00:00.000Z\",\n \"payment_method\": \"BOLETO\",\n \"total_amount\": 49.9,\n \"created_at\": \"2026-01-28T10:00:00.000Z\"\n },\n \"product\": {\n \"id\": \"c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f\",\n \"name\": \"Assinatura Premium Mensal\",\n \"type\": \"DIGITAL\"\n },\n \"buyer\": {\n \"name\": \"João Silva\",\n \"email\": \"joao.silva@email.com\",\n \"document\": \"12345678900\",\n \"phone\": \"11999999999\"\n },\n \"source\": {\n \"channel\": \"API\",\n \"api_credential_id\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"\n }\n }\n}\n```\n\n### Autenticando o webhook recebido\nToda requisição chega com o header `Authorization: Bearer `,\nonde `webhook_authorization` é o token exibido uma única vez na criação da credencial\n(veja \"Autenticação e credencial\" acima). **Isso é um token fixo comparado por igualdade —\nnão há assinatura HMAC do corpo da requisição por evento.** Valide o header antes de\nprocessar o evento; não assuma que o payload não pode ter sido adulterado em trânsito por\nalguém que descobriu o token.\n\n### Reentrega\nEm caso de falha (timeout de 10s, erro de rede, ou qualquer resposta tratada como erro), o\nevento é reenviado a cada 30 segundos (intervalo fixo) até o limite de tentativas\nconfigurado no webhook (padrão: 5). Exceção: um retorno **404** não gera reenvio, mesmo\nque ainda restem tentativas — verifique se sua URL está no ar antes de configurar o\nwebhook. Depois de esgotar as tentativas, não há nenhuma notificação automática; consulte\no histórico de entregas no painel.\n\nResponda **200** assim que tiver recebido o evento — processe de forma assíncrona se a\nlógica de negócio demorar, para não gerar reentregas desnecessárias por timeout."},"servers":[{"url":"https://pagpolar-api.creativecode.dev.br/v1"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token de acesso devolvido por POST /auth/token. Envie como \"Authorization: Bearer \". Vale 24 horas."},"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Chave da credencial. Usada apenas em POST /auth/token, para obter o token de acesso."}},"schemas":{"AccessToken":{"type":"object","required":["access_token","token_type","expires_in"],"properties":{"access_token":{"type":"string","description":"Token de acesso (JWT). Envie em `Authorization: Bearer `.","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJlNmY3YThiOS1jMGQxLTRlMmYtM2E0Yi01YzZkN2U4ZjlhMGIifQ.assinatura-do-token"},"token_type":{"type":"string","enum":["Bearer"],"description":"Sempre `Bearer`.","example":"Bearer"},"expires_in":{"type":"integer","description":"Segundos até o token expirar, contados a partir da emissão. `86400` são 24 horas.","example":86400}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_request","unauthorized","forbidden","not_found","conflict","unprocessable_entity","rate_limit_exceeded","service_unavailable","internal_error","error"],"description":"`code` reflete a categoria HTTP do erro, não o caso de negócio específico — dois erros\ndiferentes na mesma categoria (por exemplo, oferta inativa e oferta expirada, ambos `409`)\ncompartilham o mesmo `code` (`conflict`). Para diferenciar casos dentro da mesma categoria,\nuse o texto de `message`.\n\n| `code` | HTTP | Quando ocorre |\n|---|---|---|\n| `invalid_request` | 400 | Corpo ou parâmetros inválidos (schema), header obrigatório ausente, ou regra de negócio violada (ex.: parcelas acima do limite da oferta) |\n| `unauthorized` | 401 | Token ausente, inválido ou expirado, ou credencial inválida, expirada ou revogada |\n| `forbidden` | 403 | Bloqueio de acesso (IP não autorizado, produto não permite a operação) |\n| `not_found` | 404 | Recurso não encontrado (produto, oferta, venda, assinatura, cliente) |\n| `conflict` | 409 | Estado do recurso impede a operação (oferta inativa/expirada, método de pagamento não habilitado, requisição idêntica em processamento) |\n| `unprocessable_entity` | 422 | Reservado — não emitido atualmente por nenhum endpoint |\n| `rate_limit_exceeded` | 429 | Limite de requisições excedido |\n| `service_unavailable` | 503 | Serviço de limite indisponível — repita com a mesma `Idempotency-Key` |\n| `internal_error` | 5xx | Erro inesperado — `message` vem genérica; informe o `request_id` ao suporte |"},"message":{"type":"string"},"request_id":{"type":"string","nullable":true}}}}},"Credential":{"type":"object","required":["credential_id","environment","rate_limit_per_minute"],"properties":{"credential_id":{"type":"string","format":"uuid","description":"Identificador da credencial dona do token.","example":"e6f7a8b9-c0d1-4e2f-3a4b-5c6d7e8f9a0b"},"environment":{"type":"string","enum":["PRODUCTION","STAGING"],"description":"Ambiente da credencial, definido na criação e imutável. As duas cobram de verdade.","example":"PRODUCTION"},"rate_limit_per_minute":{"type":"integer","description":"Limite de requisições por minuto desta credencial.","example":120}}},"Product":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f"},"name":{"type":"string","example":"Curso de Marketing Digital"},"description":{"type":"string","nullable":true,"example":"Aprenda a vender online do zero"},"author":{"type":"string","nullable":true,"example":"João Silva"},"promotional_text":{"type":"string","nullable":true,"example":"Oferta por tempo limitado"},"is_active":{"type":"boolean","example":true},"image":{"type":"string","nullable":true,"description":"null quando o produto não tem imagem cadastrada.","example":"https://api.pagpolar.com/files/abc123.png"},"type":{"type":"string","enum":["PHYSICAL","DIGITAL","SUBSCRIPTION","PACKAGE"],"description":"Tipo do produto. `PHYSICAL` pode aparecer em produtos criados no painel, mas produtos físicos ainda não são processados pela API: não há envio, frete nem rastreio.","example":"DIGITAL"},"content_type":{"type":"string","enum":["DEFAULT","EVENT_ONLINE","EVENT_IN_PERSON","EBOOK","COURSE"],"example":"COURSE"},"warranty_time":{"type":"integer","description":"Prazo de garantia em dias.","example":7},"category":{"type":"object","nullable":true,"description":"null quando o produto não tem categoria.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"Cursos"}}},"created_at":{"type":"string","format":"date-time","example":"2026-01-15T12:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-02-01T09:30:00.000Z"}}},"Offer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"d5e6f7a8-b9c0-4d1e-2f3a-4b5c6d7e8f9a"},"identifier":{"type":"string","description":"Código da oferta: prefixo `PPP` seguido de 10 dígitos.","example":"PPP1234567890"},"title":{"type":"string","nullable":true,"example":"Plano Mensal"},"price":{"type":"number","example":197.9},"is_active":{"type":"boolean","example":true},"requires_shipping":{"type":"boolean","description":"true quando o produto é físico: a cobrança exige `address` e `shipping_option_id`. Consulte as opções em `GET /offers/{identifier}/shipping`.","example":false},"is_default":{"type":"boolean","example":false},"product_id":{"type":"string","format":"uuid","example":"c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f"},"payment_methods":{"type":"object","description":"Meios de pagamento ligados. Cada meio só fica ligado se o preço atinge o mínimo dele: PIX R$ 5,00, cartão R$ 5,00 e boleto R$ 10,00.","properties":{"pix":{"type":"boolean","example":true},"credit_card":{"type":"boolean","example":true},"billet":{"type":"boolean","example":false}}},"max_credit_card_installments":{"type":"integer","example":12},"cycle":{"type":"string","nullable":true,"description":"null para oferta avulsa (não recorrente). Preenchido só quando a oferta é de assinatura.","enum":["DAILY","WEEKLY","MONTHLY","YEARLY"],"example":"MONTHLY"},"cycle_interval":{"type":"integer","nullable":true,"example":1},"cycle_interval_limit":{"type":"integer","nullable":true,"description":"null quando a assinatura não tem limite de ciclos.","example":12},"allow_purchase_quantity":{"type":"boolean","example":false},"purchase_quantity_limit":{"type":"integer","nullable":true,"example":10},"purchase_quantity_min":{"type":"integer","example":1},"expires_at":{"type":"string","format":"date-time","nullable":true,"example":null},"created_at":{"type":"string","format":"date-time","example":"2026-01-10T10:00:00.000Z"}}},"Customer":{"type":"object","description":"Documento e telefone são sempre retornados mascarados por política de privacidade.","properties":{"id":{"type":"string","format":"uuid","example":"e6f7a8b9-c0d1-4e2f-3a4b-5c6d7e8f9a0b"},"name":{"type":"string","example":"Maria Souza"},"email":{"type":"string","format":"email","example":"maria@exemplo.com"},"document":{"type":"string","nullable":true,"description":"Mascarado: CPF vira ***.XXX.***-**, CNPJ vira **.XXX.***/****-**. null se o cliente não tem documento cadastrado.","example":"***.456.***-**"},"phone":{"type":"string","nullable":true,"description":"Mascarado: mantém só os últimos 4 dígitos (****XXXX). null se o cliente não tem telefone cadastrado.","example":"****4321"},"is_active":{"type":"boolean","example":true},"created_at":{"type":"string","format":"date-time","example":"2026-01-05T08:00:00.000Z"}}},"Sale":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Id da venda. É o mesmo valor que volta em `transactions` na criação do pagamento e pode ser usado em `GET /sales/{identifier}`.","example":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"},"identifier":{"type":"string","description":"Código da venda: prefixo `PPO` seguido de 10 dígitos. É o mesmo código do painel e do webhook.","example":"PPO9876543210"},"external_reference":{"type":"string","nullable":true,"description":"Referência do pedido enviada por você na criação do pagamento ou da assinatura. `null` quando não foi enviada.","example":"PED-2026-0001"},"status":{"type":"string","enum":["DRAFT","OPEN","PROCESSING","PAID","CANCELED","ASK_REFUND","REFUNDED","REFUNDING","ABANDONED","EXPIRED","FAILED","CHARGEBACK_REQUESTED","CHARGEBACK_APPROVED"],"example":"PAID"},"type":{"type":"string","enum":["BILLING","TRANSFER","FEE"],"example":"BILLING"},"payment_method":{"type":"string","enum":["CREDIT_CARD","PIX","BOLETO","APPLE_PAY","GOOGLE_PAY"],"example":"PIX"},"installments":{"type":"integer","example":1},"total_amount":{"type":"number","example":197},"cycle":{"type":"integer","description":"Posição do ciclo de cobrança para vendas recorrentes (não é a periodicidade — para isso veja Offer.cycle). 1 para venda avulsa.","example":1},"paid_at":{"type":"string","format":"date-time","nullable":true,"description":"null enquanto a venda não é paga.","example":"2026-01-20T14:32:10.000Z"},"refund_at":{"type":"string","format":"date-time","nullable":true,"example":null},"created_at":{"type":"string","format":"date-time","example":"2026-01-20T14:30:00.000Z"},"customer":{"$ref":"#/components/schemas/Customer"},"items":{"type":"array","items":{"type":"object","properties":{"quantity":{"type":"integer","example":1},"amount":{"type":"number","example":197},"original_amount":{"type":"number","example":197},"discount_value":{"type":"number","example":0},"offer":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"identifier":{"type":"string","description":"Código da oferta: prefixo `PPP` seguido de 10 dígitos.","example":"PPP1234567890"},"title":{"type":"string","example":"Plano Mensal"}}},"product":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"Curso de Marketing Digital"},"type":{"type":"string","example":"DIGITAL"}}}}}},"shipping":{"type":"object","nullable":true,"description":"Frete cobrado e endereço de entrega. `null` quando a venda não tem entrega.","properties":{"amount":{"type":"number","description":"Valor do frete em reais, já somado ao total da venda.","example":32.9},"option_name":{"type":"string","nullable":true,"description":"Nome da opção de frete escolhida na cobrança.","example":"SEDEX"},"address":{"type":"object","nullable":true,"properties":{"street":{"type":"string","example":"Rua das Flores"},"number":{"type":"string","example":"123"},"complement":{"type":"string","nullable":true,"example":"Apto 4B"},"neighborhood":{"type":"string","example":"Centro"},"city":{"type":"string","example":"São Paulo"},"state":{"type":"string","example":"SP"},"postal_code":{"type":"string","example":"01311000"}}}}},"payment_details":{"type":"object","nullable":true,"description":"null antes da venda ser processada (ex.: aguardando confirmação do gateway).","properties":{"qr_code":{"type":"string","nullable":true,"example":"00020126..."},"qr_code_expires_at":{"type":"string","format":"date-time","nullable":true},"billet_barcode":{"type":"string","nullable":true,"example":"34191.79001 01043.510047 91020.150008 1 96610000015000"},"billet_link":{"type":"string","nullable":true,"example":"https://boletos.pagpolar.com/a1b2c3d4.pdf"},"last_credit_card_digits":{"type":"string","nullable":true,"example":"4242"}}}}},"ShippingOption":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"Identificador da opção de frete. Envie este valor em `shipping_option_id` na criação do pagamento. Vale enquanto a configuração de frete do produto não mudar.","example":"wil_a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"},"name":{"type":"string","description":"Nome da opção, como o comprador vê.","example":"SEDEX"},"type":{"type":"string","enum":["FREE","PAID","DYNAMIC"],"description":"`FREE` frete grátis, `PAID` valor fixo definido pelo vendedor, `DYNAMIC` calculado na hora pela transportadora.","example":"DYNAMIC"},"cost":{"type":"number","nullable":true,"description":"Valor do frete em reais.","example":32.9},"min_days":{"type":"integer","description":"Prazo mínimo de entrega, já somado o preparo do vendedor. No frete calculado (`DYNAMIC`) vem igual ao máximo.","example":5},"max_days":{"type":"integer","description":"Prazo máximo de entrega, já somado o preparo do vendedor.","example":5},"days_type":{"type":"string","enum":["BUSINESS_DAYS","CALENDAR_DAYS"],"description":"Se o prazo é contado em dias úteis ou em dias corridos.","example":"BUSINESS_DAYS"}}},"Subscription":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"f7a8b9c0-d1e2-4f3a-4b5c-6d7e8f9a0b1c"},"status":{"type":"string","enum":["DRAFT","PENDING_PAYMENT","ACTIVE","PENDING_RENEWAL","PROCESSING","CANCELING","CANCELED","ASK_REFUND","REFUNDED","ABANDONED","EXPIRED","FAILED"],"example":"ACTIVE"},"payment_method":{"type":"string","nullable":true,"enum":["CREDIT_CARD","PIX","BOLETO","APPLE_PAY","GOOGLE_PAY"],"example":"CREDIT_CARD"},"start_at":{"type":"string","format":"date-time","nullable":true,"example":"2026-01-01T00:00:00.000Z"},"end_at":{"type":"string","format":"date-time","nullable":true,"description":"Data de término, quando a assinatura tem prazo definido.","example":null},"next_billing_at":{"type":"string","format":"date-time","nullable":true,"example":"2026-09-01T00:00:00.000Z"},"next_billing_amount":{"type":"number","nullable":true,"example":97},"total_amount":{"type":"number","nullable":true,"example":1164},"canceled_at":{"type":"string","format":"date-time","nullable":true,"description":"null enquanto a assinatura não é cancelada.","example":null},"cycle_limit":{"type":"integer","nullable":true,"description":"Quantidade máxima de ciclos cobrados. `null` quando não há limite.","example":null},"paid_at":{"type":"string","format":"date-time","nullable":true,"example":"2026-01-01T00:05:00.000Z"},"created_at":{"type":"string","format":"date-time","example":"2026-01-01T00:00:00.000Z"},"customer":{"$ref":"#/components/schemas/Customer"},"offer":{"$ref":"#/components/schemas/Offer"},"product":{"$ref":"#/components/schemas/Product"}}},"PlanChangeOptions":{"type":"object","properties":{"allow_client_plan_change":{"type":"boolean","example":true},"current_product_price_id":{"type":"string","format":"uuid","example":"d5e6f7a8-b9c0-4d1e-2f3a-4b5c6d7e8f9a"},"options":{"type":"array","description":"Ofertas do mesmo produto disponíveis para troca. Inclui a oferta atual da assinatura mesmo se ela não estiver mais selecionável para novas trocas.","items":{"$ref":"#/components/schemas/Offer"}}}},"PlanChangePreview":{"type":"object","properties":{"type":{"type":"string","enum":["UPGRADE","DOWNGRADE"]},"current_product_price_id":{"type":"string","format":"uuid"},"current_price":{"type":"number"},"new_product_price_id":{"type":"string","format":"uuid"},"new_price":{"type":"number"},"total_days":{"type":"integer"},"remaining_days":{"type":"integer"},"prorated_credit":{"type":"number"},"charge_amount":{"type":"number"},"effective_at":{"type":"string","format":"date-time"},"current_payment_method":{"type":"string"}}},"PlanChange":{"type":"object","properties":{"type":{"type":"string","enum":["UPGRADE","DOWNGRADE"]},"upgrade":{"type":"object","nullable":true,"description":"Presente apenas quando type=UPGRADE","properties":{"transaction_id":{"type":"string","format":"uuid"},"charge_amount":{"type":"number"},"status":{"type":"string","enum":["paid","pending","failed"]},"pix":{"type":"object","nullable":true,"properties":{"qr_code":{"type":"string"}}},"boleto":{"type":"object","nullable":true,"properties":{"barcode":{"type":"string"},"pdf_link":{"type":"string"}}}}}}},"Refund":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["PENDING","ACCEPTED","ACCEPTED_BY_ADMIN","REFUSED","REFUSED_BY_ADMIN","WAITING_SEND","WAITING_TRACK_CODE","SENT","REFUNDING","REFUNDED","CANCELED","FAILED"],"description":"PENDING aguarda o vendedor · ACCEPTED/ACCEPTED_BY_ADMIN aceito pelo vendedor, pelo admin ou automaticamente · REFUSED/REFUSED_BY_ADMIN recusado · WAITING_SEND, WAITING_TRACK_CODE e SENT são etapas da devolução do produto físico · REFUNDING estorno pedido ao gateway · REFUNDED estorno concluído · CANCELED pedido desfeito · FAILED o gateway recusou o estorno.","example":"REFUNDED"},"requested_by":{"type":"string","enum":["CLIENT","SELLER"],"description":"Quem pediu o reembolso. `CLIENT` é o pedido do comprador — aberto por ele no painel ou informado por você em `POST /refunds`. `SELLER` é a decisão do vendedor, no painel ou pela API.","example":"CLIENT"},"is_partial":{"type":"boolean","description":"`true` quando o reembolso é só de alguns itens.","example":false},"refund_amount":{"type":"number","nullable":true,"description":"Valor do reembolso parcial, em reais. `null` no reembolso total — vale o total da venda.","example":null},"reason":{"type":"string","nullable":true,"description":"Motivo informado no pedido.","example":"Não atendeu às expectativas"},"customer_observation":{"type":"string","nullable":true,"example":null},"refused_reason":{"type":"string","nullable":true,"description":"Motivo da recusa, quando recusado.","example":null},"canceled_reason":{"type":"string","nullable":true,"description":"Motivo do cancelamento, quando cancelado.","example":null},"return_tracking":{"type":"object","nullable":true,"description":"Rastreio da devolução do produto físico. `null` quando não há devolução.","properties":{"code":{"type":"string","example":"BR123456789BR"},"provider":{"type":"string","nullable":true},"sent_at":{"type":"string","format":"date-time","nullable":true},"received_at":{"type":"string","format":"date-time","nullable":true}}},"sale":{"type":"object","properties":{"identifier":{"type":"string","example":"PPO9876543210"},"status":{"type":"string","example":"REFUNDED"},"payment_method":{"type":"string","example":"PIX"},"total_amount":{"type":"number","example":197}}},"customer":{"$ref":"#/components/schemas/Customer"},"created_at":{"type":"string","format":"date-time","example":"2026-01-25T09:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-27T16:20:00.000Z"}}},"PaymentResult":{"type":"object","required":["offer_identifier","transactions","subscriptions"],"properties":{"offer_identifier":{"type":"string","description":"Código da oferta usada na venda — a informada, a reaproveitada ou a criada a partir de `offer`.","example":"PPP1234567890"},"transactions":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Ids das vendas criadas. O primeiro é a venda principal; use em `GET /sales/{identifier}`.","example":["a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"]},"subscriptions":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Ids das assinaturas criadas. Vazio em venda avulsa.","example":[]},"pix":{"type":"object","description":"Só vem na cobrança PIX.","properties":{"qr_code":{"type":"string","description":"Código \"copia e cola\" para o cliente pagar."}}},"boleto":{"type":"object","description":"Só vem na cobrança por boleto.","properties":{"barcode":{"type":"string","description":"Linha digitável."},"pdf_link":{"type":"string","description":"Link do PDF do boleto."}}}}},"OperationResult":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Sempre `true` quando a operação foi aceita.","example":true}}},"RefundCreateRequest":{"type":"object","required":["sale_identifier"],"properties":{"sale_identifier":{"type":"string","maxLength":255,"description":"Código público da venda a reembolsar — o `identifier` que vem em `GET /sales`, na resposta da cobrança e no payload dos webhooks. São só dígitos; o prefixo e a URL do checkout que contenha o código também são aceitos. **Não** é o `id` (uuid) da venda: com o uuid a resposta é `404`. A venda precisa ser da própria conta da credencial.","example":"PPO9876543210"},"requested_by":{"type":"string","enum":["SELLER","CLIENT"],"default":"SELLER","description":"Quem pediu o reembolso, para o registro ficar fiel: `SELLER` quando a decisão foi sua e `CLIENT` quando o comprador pediu por fora (e-mail, telefone, atendimento). O campo só muda o registro, que volta em `requested_by` na consulta — o estorno é imediato nos dois casos, porque quem chama a rota é o vendedor.","example":"SELLER"},"reason":{"type":"string","maxLength":255,"description":"Motivo do reembolso, em texto livre. Fica gravado no pedido e aparece em `GET /refunds`.","example":"Cliente desistiu da compra"},"customer_observation":{"type":"string","maxLength":255,"description":"Observação do comprador, quando houver.","example":"Pediu o cancelamento por e-mail"}}},"PixDedicatedPaymentRequest":{"title":"PIX","type":"object","required":["customer"],"properties":{"offer_identifier":{"type":"string","example":"PPP1234567890","description":"Código de uma oferta existente. Envie este campo **ou** `offer` — nunca os dois."},"offer":{"type":"object","required":["product_id","name","value","createOffer"],"description":"Oferta informada na hora. Envie este objeto **ou** `offer_identifier` — nunca os dois. Reaproveita a oferta com mesmo produto, nome, valor e visibilidade; senão cria.","properties":{"product_id":{"type":"string","format":"uuid","description":"Produto da sua conta."},"name":{"type":"string","maxLength":255,"example":"Consultoria avulsa","description":"Nome da oferta."},"value":{"type":"integer","minimum":500,"example":4990,"description":"Valor em centavos. Mínimo 500 (R$ 5,00)."},"createOffer":{"type":"boolean","example":false,"description":"`true`: oferta visível. `false`: oferta oculta, fora das listagens e usável só por esta API."}}},"quantity":{"type":"integer","minimum":1,"default":1},"affiliate_identifier":{"type":"string","pattern":"^PAO[0-9]{10}$","example":"PAO1234567890","description":"Código do afiliado que trouxe a venda, no formato `PAO` seguido de 10 dígitos. Formato inválido retorna `400`. Código de afiliado inexistente, de outro produto, inativo ou sem a oferta liberada é **ignorado**: a venda é processada normalmente, sem afiliado. Não há cookie nem regra de primeiro ou último clique — vale o código enviado."},"external_reference":{"type":"string","maxLength":255,"description":"Referência do pedido no seu sistema (por exemplo, o número do pedido). Opcional. Depois você consulta a venda por ela em `GET /sales/{identifier}` e filtra em `GET /sales?external_reference=`. Pode se repetir entre pedidos: a consulta devolve a venda mais recente com essa referência.","example":"PED-2026-0001"},"customer":{"type":"object","required":["name","email","document","phone"],"properties":{"name":{"type":"string","example":"Fulano de Tal"},"email":{"type":"string","format":"email","example":"fulano@exemplo.com"},"document":{"type":"string","description":"CPF (11 dígitos) ou CNPJ (14 dígitos), com ou sem pontuação: `12345678909` ou `123.456.789-09`. A API grava só os dígitos. Fora disso, 400.","example":"12345678909"},"phone":{"type":"string","description":"DDD e número, com 10 ou 11 dígitos (12 ou 13 com o código do país 55). Pontuação, espaços, parênteses e `+` são aceitos: `11999998888`, `(11) 99999-8888` ou `+55 11 99999-8888`. A API grava só os dígitos. Fora disso, 400.","example":"11999999999"}}},"address":{"type":"object","description":"Obrigatório quando a oferta é de produto físico (`requires_shipping: true`); nos demais casos é opcional e não é usado no processamento da venda.","required":["street","number","neighborhood","city","state","postal_code"],"properties":{"street":{"type":"string","example":"Rua das Flores"},"number":{"type":"string","example":"123"},"complement":{"type":"string","nullable":true,"example":"Apto 4B"},"neighborhood":{"type":"string","example":"Centro"},"city":{"type":"string","example":"São Paulo"},"state":{"type":"string","example":"SP"},"postal_code":{"type":"string","example":"01000-000"}}},"shipping_option_id":{"type":"string","description":"Opção de frete escolhida, obrigatória quando a oferta é de produto físico (`requires_shipping: true`). Use o `id` devolvido por `GET /offers/{identifier}/shipping` para o mesmo CEP enviado em `address.postal_code`. Enviar este campo numa oferta que não exige frete retorna `400`.","example":"wil_a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"},"buyer_ip":{"type":"string","description":"IP do comprador final. Melhora a análise antifraude.","example":"203.0.113.10"},"buyer_user_agent":{"type":"string","description":"User agent do comprador final."}}},"BoletoDedicatedPaymentRequest":{"title":"Boleto","type":"object","required":["customer"],"properties":{"offer_identifier":{"type":"string","example":"PPP1234567890","description":"Código de uma oferta existente. Envie este campo **ou** `offer` — nunca os dois."},"offer":{"type":"object","required":["product_id","name","value","createOffer"],"description":"Oferta informada na hora. Envie este objeto **ou** `offer_identifier` — nunca os dois. Reaproveita a oferta com mesmo produto, nome, valor e visibilidade; senão cria.","properties":{"product_id":{"type":"string","format":"uuid","description":"Produto da sua conta."},"name":{"type":"string","maxLength":255,"example":"Consultoria avulsa","description":"Nome da oferta."},"value":{"type":"integer","minimum":500,"example":4990,"description":"Valor em centavos. Mínimo 500 (R$ 5,00)."},"createOffer":{"type":"boolean","example":false,"description":"`true`: oferta visível. `false`: oferta oculta, fora das listagens e usável só por esta API."}}},"quantity":{"type":"integer","minimum":1,"default":1},"affiliate_identifier":{"type":"string","pattern":"^PAO[0-9]{10}$","example":"PAO1234567890","description":"Código do afiliado que trouxe a venda, no formato `PAO` seguido de 10 dígitos. Formato inválido retorna `400`. Código de afiliado inexistente, de outro produto, inativo ou sem a oferta liberada é **ignorado**: a venda é processada normalmente, sem afiliado. Não há cookie nem regra de primeiro ou último clique — vale o código enviado."},"external_reference":{"type":"string","maxLength":255,"description":"Referência do pedido no seu sistema (por exemplo, o número do pedido). Opcional. Depois você consulta a venda por ela em `GET /sales/{identifier}` e filtra em `GET /sales?external_reference=`. Pode se repetir entre pedidos: a consulta devolve a venda mais recente com essa referência.","example":"PED-2026-0001"},"customer":{"type":"object","required":["name","email","document","phone"],"properties":{"name":{"type":"string","example":"Fulano de Tal"},"email":{"type":"string","format":"email","example":"fulano@exemplo.com"},"document":{"type":"string","description":"CPF (11 dígitos) ou CNPJ (14 dígitos), com ou sem pontuação: `12345678909` ou `123.456.789-09`. A API grava só os dígitos. Fora disso, 400.","example":"12345678909"},"phone":{"type":"string","description":"DDD e número, com 10 ou 11 dígitos (12 ou 13 com o código do país 55). Pontuação, espaços, parênteses e `+` são aceitos: `11999998888`, `(11) 99999-8888` ou `+55 11 99999-8888`. A API grava só os dígitos. Fora disso, 400.","example":"11999999999"}}},"address":{"type":"object","description":"Obrigatório quando a oferta é de produto físico (`requires_shipping: true`); nos demais casos é opcional e não é usado no processamento da venda.","required":["street","number","neighborhood","city","state","postal_code"],"properties":{"street":{"type":"string","example":"Rua das Flores"},"number":{"type":"string","example":"123"},"complement":{"type":"string","nullable":true,"example":"Apto 4B"},"neighborhood":{"type":"string","example":"Centro"},"city":{"type":"string","example":"São Paulo"},"state":{"type":"string","example":"SP"},"postal_code":{"type":"string","example":"01000-000"}}},"shipping_option_id":{"type":"string","description":"Opção de frete escolhida, obrigatória quando a oferta é de produto físico (`requires_shipping: true`). Use o `id` devolvido por `GET /offers/{identifier}/shipping` para o mesmo CEP enviado em `address.postal_code`. Enviar este campo numa oferta que não exige frete retorna `400`.","example":"wil_a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"},"buyer_ip":{"type":"string","description":"IP do comprador final. Melhora a análise antifraude.","example":"203.0.113.10"},"buyer_user_agent":{"type":"string","description":"User agent do comprador final."}}},"CreditCardDedicatedPaymentRequest":{"title":"Cartão de crédito","type":"object","required":["installments","customer","credit_card"],"properties":{"offer_identifier":{"type":"string","example":"PPP1234567890","description":"Código de uma oferta existente. Envie este campo **ou** `offer` — nunca os dois."},"offer":{"type":"object","required":["product_id","name","value","createOffer"],"description":"Oferta informada na hora. Envie este objeto **ou** `offer_identifier` — nunca os dois. Reaproveita a oferta com mesmo produto, nome, valor e visibilidade; senão cria.","properties":{"product_id":{"type":"string","format":"uuid","description":"Produto da sua conta."},"name":{"type":"string","maxLength":255,"example":"Consultoria avulsa","description":"Nome da oferta."},"value":{"type":"integer","minimum":500,"example":4990,"description":"Valor em centavos. Mínimo 500 (R$ 5,00)."},"createOffer":{"type":"boolean","example":false,"description":"`true`: oferta visível. `false`: oferta oculta, fora das listagens e usável só por esta API."}}},"quantity":{"type":"integer","minimum":1,"default":1},"affiliate_identifier":{"type":"string","pattern":"^PAO[0-9]{10}$","example":"PAO1234567890","description":"Código do afiliado que trouxe a venda, no formato `PAO` seguido de 10 dígitos. Formato inválido retorna `400`. Código de afiliado inexistente, de outro produto, inativo ou sem a oferta liberada é **ignorado**: a venda é processada normalmente, sem afiliado. Não há cookie nem regra de primeiro ou último clique — vale o código enviado."},"external_reference":{"type":"string","maxLength":255,"description":"Referência do pedido no seu sistema (por exemplo, o número do pedido). Opcional. Depois você consulta a venda por ela em `GET /sales/{identifier}` e filtra em `GET /sales?external_reference=`. Pode se repetir entre pedidos: a consulta devolve a venda mais recente com essa referência.","example":"PED-2026-0001"},"customer":{"type":"object","required":["name","email","document","phone"],"properties":{"name":{"type":"string","example":"Fulano de Tal"},"email":{"type":"string","format":"email","example":"fulano@exemplo.com"},"document":{"type":"string","description":"CPF (11 dígitos) ou CNPJ (14 dígitos), com ou sem pontuação: `12345678909` ou `123.456.789-09`. A API grava só os dígitos. Fora disso, 400.","example":"12345678909"},"phone":{"type":"string","description":"DDD e número, com 10 ou 11 dígitos (12 ou 13 com o código do país 55). Pontuação, espaços, parênteses e `+` são aceitos: `11999998888`, `(11) 99999-8888` ou `+55 11 99999-8888`. A API grava só os dígitos. Fora disso, 400.","example":"11999999999"}}},"address":{"type":"object","description":"Obrigatório quando a oferta é de produto físico (`requires_shipping: true`); nos demais casos é opcional e não é usado no processamento da venda.","required":["street","number","neighborhood","city","state","postal_code"],"properties":{"street":{"type":"string","example":"Rua das Flores"},"number":{"type":"string","example":"123"},"complement":{"type":"string","nullable":true,"example":"Apto 4B"},"neighborhood":{"type":"string","example":"Centro"},"city":{"type":"string","example":"São Paulo"},"state":{"type":"string","example":"SP"},"postal_code":{"type":"string","example":"01000-000"}}},"shipping_option_id":{"type":"string","description":"Opção de frete escolhida, obrigatória quando a oferta é de produto físico (`requires_shipping: true`). Use o `id` devolvido por `GET /offers/{identifier}/shipping` para o mesmo CEP enviado em `address.postal_code`. Enviar este campo numa oferta que não exige frete retorna `400`.","example":"wil_a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"},"buyer_ip":{"type":"string","description":"IP do comprador final. Melhora a análise antifraude.","example":"203.0.113.10"},"buyer_user_agent":{"type":"string","description":"User agent do comprador final."},"installments":{"type":"integer","minimum":1,"maximum":12,"description":"O máximo real pode ser menor que 12: é limitado pela configuração da oferta (consulte max_credit_card_installments em GET /offers/{identifier}). Acima do limite da oferta, retorna 400.","example":3},"credit_card":{"type":"object","required":["holder_name","holder_document","number","expiration_month","expiration_year","cvv"],"description":"Dados do cartão de crédito usado na cobrança.","properties":{"holder_name":{"type":"string","example":"FULANO DE TAL"},"holder_document":{"type":"string","description":"CPF (11 dígitos) ou CNPJ (14 dígitos) do titular do cartão, com ou sem pontuação. A API grava só os dígitos. Fora disso, 400.","example":"12345678909"},"number":{"type":"string","example":"4111111111111111"},"expiration_month":{"type":"integer","minimum":1,"maximum":12,"example":12},"expiration_year":{"type":"integer","minimum":2000,"maximum":2100,"example":2030},"cvv":{"type":"string","example":"123"}}}}}},"responses":{"Unauthorized":{"description":"Token ausente, inválido ou expirado, ou credencial revogada ou expirada. Chame POST /auth/token para obter um token novo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ApiKeyUnauthorized":{"description":"Header X-API-Key ausente, chave inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"IpNotAllowed":{"description":"IP não autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"CredentialIpNotAllowed":{"description":"IP não autorizado para esta credencial","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimited":{"description":"Limite de requisições excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServiceUnavailable":{"description":"Serviço de limite indisponível — repita a requisição com a mesma Idempotency-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InvalidData":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InvalidDataOrEmptyBody":{"description":"Dados inválidos ou corpo vazio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InvalidFilter":{"description":"Filtro inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ProductNotFound":{"description":"Produto não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"OfferNotFound":{"description":"Oferta não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"OfferUpdateNotFound":{"description":"Oferta de produto não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"OfferShippingNotConfigured":{"description":"CEP inválido, ou produto físico sem configuração de frete ativa","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"PlanNotFound":{"description":"Plano não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"PlanOfferNotFound":{"description":"Oferta de plano não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"CustomerNotFound":{"description":"Cliente não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"SaleNotFound":{"description":"Venda não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"PaymentNotFound":{"description":"Pagamento não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"SubscriptionNotFound":{"description":"Assinatura não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"SubscriptionOrPlanNotFound":{"description":"Assinatura ou plano não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"PaymentBadRequest":{"description":"Dados inválidos, Idempotency-Key ausente, número de parcelas acima do limite da oferta, ou documento/telefone fora do formato (CPF 11 dígitos, CNPJ 14, telefone 10 a 13 dígitos)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"PaymentOfferNotFound":{"description":"Oferta não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"PaymentConflict":{"description":"Oferta inativa/expirada, método não habilitado ou requisição idêntica em processamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RefundBadRequest":{"description":"Dados inválidos, Idempotency-Key ausente, ou já existe um pedido de reembolso em andamento para a venda","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RefundConflict":{"description":"A venda não está paga, não é possível reembolsar","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"SubscriptionCardBadRequest":{"description":"Dados de cartão inválidos, assinatura sem cobrança no cartão ou troca recusada pelo gateway","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"SubscriptionCardRateLimited":{"description":"Limite de requisições por minuto da credencial excedido na troca de cartão","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"PlanChangePreviewBadRequest":{"description":"Plano não pertence ao mesmo produto ou não é selecionável","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"PlanChangeBadRequest":{"description":"Dados inválidos ou Idempotency-Key ausente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"PlanChangeForbidden":{"description":"Produto não permite troca de plano pelo cliente, plano não selecionável ou IP não autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"PlanChangeConflict":{"description":"Requisição idêntica em processamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"security":[{"BearerAuth":[]}],"tags":[{"name":"Autenticação"},{"name":"Produtos"},{"name":"Ofertas"},{"name":"Planos"},{"name":"Vendas"},{"name":"Reembolsos"},{"name":"Assinaturas"},{"name":"Clientes"}],"paths":{"/auth/token":{"post":{"operationId":"createAccessToken","tags":["Autenticação"],"summary":"Obter o token de acesso","description":"Troca a chave da credencial por um **token de acesso**. É a primeira chamada de qualquer\nintegração: todas as outras rotas exigem esse token.\n\nEnvie a chave no header `X-API-Key`. A resposta traz o token, que vale **24 horas**.\nNas demais rotas, envie `Authorization: Bearer `.\n\nNão existe rota de renovação: quando o token expirar, chame esta rota de novo com a mesma chave.\nGuarde o token em memória e reaproveite enquanto valer — não peça um token por requisição.\n\nA chave continua sendo o segredo da integração: ela só trafega nesta rota.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Token de acesso emitido","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AccessToken"}}},"example":{"data":{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJlNmY3YThiOS1jMGQxLTRlMmYtM2E0Yi01YzZkN2U4ZjlhMGIifQ.assinatura-do-token","token_type":"Bearer","expires_in":86400}}}}},"401":{"$ref":"#/components/responses/ApiKeyUnauthorized"},"403":{"$ref":"#/components/responses/CredentialIpNotAllowed"}}}},"/me":{"get":{"operationId":"getCurrentCredential","tags":["Autenticação"],"summary":"Dados da credencial autenticada","description":"Retorna o ambiente da credencial (PRODUCTION ou STAGING) e o limite de requisições por minuto. Útil para validar a integração.","responses":{"200":{"description":"Dados da credencial","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Credential"}}},"example":{"data":{"credential_id":"e6f7a8b9-c0d1-4e2f-3a4b-5c6d7e8f9a0b","environment":"PRODUCTION","rate_limit_per_minute":120}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/products":{"get":{"operationId":"listProducts","tags":["Produtos"],"summary":"Listar produtos","parameters":[{"name":"page","in":"query","description":"Número da página, começando em 1.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","description":"Itens por página, de 1 a 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"is_active","in":"query","description":"`true` lista só os ativos; `false`, só os inativos. Sem o filtro, lista os dois.","schema":{"type":"boolean"}},{"name":"name","in":"query","description":"Nome do produto. Busca por parte do texto, sem diferenciar maiúsculas de minúsculas.","schema":{"type":"string","minLength":1,"maxLength":255}},{"name":"type","in":"query","description":"Tipo do produto. Planos (`SUBSCRIPTION`) não aparecem aqui: use `GET /plans`.","schema":{"type":"string","enum":["DIGITAL","PHYSICAL","PACKAGE"]}}],"responses":{"200":{"description":"Lista de produtos","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"type":"object","properties":{"page":{"type":"integer","example":1},"per_page":{"type":"integer","example":25},"total":{"type":"integer","example":143},"total_pages":{"type":"integer","example":6}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"createProduct","tags":["Produtos"],"summary":"Criar produto","description":"Cria um produto **digital** (`type` sempre `DIGITAL` — outros tipos não são criáveis\npela API pública nesta versão).\n\n**Produtos físicos ainda não são processados pela API.** Não há envio, frete nem código de\nrastreio por aqui: use a API só para produtos digitais e assinaturas.\n\nO produto é criado sem imagem e sem categoria — ambos podem ser preenchidos depois pelo\npainel. `warranty_time` (garantia, em dias) também não é aceito no corpo: é resolvido\nautomaticamente a partir da configuração mínima de garantia da sua conta.\n\nEste endpoint só cria o produto. Para vender, crie também uma oferta (preço) para ele —\nconsulte a documentação da rota de ofertas.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":255,"example":"Curso de Marketing Digital"},"description":{"type":"string","nullable":true,"example":"Aprenda a vender online do zero"}}},"examples":{"default":{"summary":"Produto digital","value":{"name":"Curso de Marketing Digital","description":"Aprenda a vender online do zero"}}}}}},"responses":{"201":{"description":"Produto criado","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}}},"examples":{"default":{"value":{"data":{"id":"c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f","name":"Curso de Marketing Digital","description":"Aprenda a vender online do zero","author":null,"promotional_text":null,"is_active":true,"image":null,"type":"DIGITAL","content_type":"DEFAULT","warranty_time":7,"category":null,"created_at":"2026-01-15T12:00:00.000Z","updated_at":"2026-01-15T12:00:00.000Z"}}}}}}},"400":{"$ref":"#/components/responses/InvalidData"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/products/{id}":{"get":{"operationId":"getProduct","tags":["Produtos"],"summary":"Consultar produto","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Produto","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"404":{"$ref":"#/components/responses/ProductNotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"updateProduct","tags":["Produtos"],"summary":"Editar produto","description":"Edita campos básicos de um produto já criado. Só `name`, `description` e `is_active`\npodem ser alterados por aqui — envie apenas os campos que deseja atualizar (edição parcial).\n\nNão é possível trocar `image`, `category`, `warranty_time` ou `type` por esta rota;\nesses campos continuam editáveis apenas pelo painel.\n\nO corpo não pode vir vazio: pelo menos um dos três campos precisa ser enviado.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"name":{"type":"string","maxLength":255,"example":"Curso de Marketing Digital"},"description":{"type":"string","nullable":true,"example":"Aprenda a vender online do zero"},"is_active":{"type":"boolean","example":true}}},"examples":{"default":{"summary":"Editar nome e descrição","value":{"name":"Curso de Marketing Digital","description":"Aprenda a vender online do zero"}},"deactivate":{"summary":"Desativar produto","value":{"is_active":false}}}}}},"responses":{"200":{"description":"Produto atualizado","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}}},"examples":{"default":{"value":{"data":{"id":"c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f","name":"Curso de Marketing Digital","description":"Aprenda a vender online do zero","author":null,"promotional_text":null,"is_active":true,"image":null,"type":"DIGITAL","content_type":"DEFAULT","warranty_time":7,"category":null,"created_at":"2026-01-15T12:00:00.000Z","updated_at":"2026-01-15T12:00:00.000Z"}}}}}}},"400":{"$ref":"#/components/responses/InvalidDataOrEmptyBody"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"404":{"$ref":"#/components/responses/ProductNotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/offers":{"post":{"operationId":"createOffer","tags":["Ofertas"],"summary":"Criar oferta","description":"Cria uma oferta (preço) avulsa para um produto já existente do seu catálogo. `product_id`\nprecisa pertencer à sua conta — produtos de outro whitelabel retornam 404.\n\nEsta rota **não cria assinatura**: `cycle`/`cycle_interval` não são aceitos aqui. Toda\noferta criada pela API pública é de cobrança avulsa. Limites de quantidade de compra,\ntexto promocional, cobrança de taxas do comprador e ajuste de taxa de parcelamento também\nnão são aceitos nesta versão — configure-os pelo painel, se necessário.\n\n`is_default` não pode ser definido pelo corpo: a primeira oferta criada para um produto é\nmarcada automaticamente como padrão pela plataforma.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["product_id","price"],"properties":{"product_id":{"type":"string","format":"uuid","example":"c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f"},"price":{"type":"integer","minimum":0,"description":"Preço da oferta em centavos, número inteiro — a mesma unidade de offer.value. 4990 = R$ 49,90. Valor com casas decimais retorna 400.","example":19790},"title":{"type":"string","nullable":true,"example":"Plano Mensal"},"is_active":{"type":"boolean","default":true,"example":true},"is_enabled_pix":{"type":"boolean","default":true,"description":"PIX. Mínimo de R$ 5,00. Os três meios começam ligados, mas cada um só fica ligado se o preço atinge o mínimo dele: PIX R$ 5,00, cartão R$ 5,00 e boleto R$ 10,00. Abaixo do mínimo, o meio é desligado ao salvar, mesmo enviando `true`. Envie `false` para desligar um meio acima do mínimo. Na edição sem `price`, só os meios enviados são recalculados; com `price`, os três são recalculados.","example":true},"is_enabled_credit_card":{"type":"boolean","default":true,"description":"Cartão de crédito. Mínimo de R$ 5,00. Os três meios começam ligados, mas cada um só fica ligado se o preço atinge o mínimo dele: PIX R$ 5,00, cartão R$ 5,00 e boleto R$ 10,00. Abaixo do mínimo, o meio é desligado ao salvar, mesmo enviando `true`. Envie `false` para desligar um meio acima do mínimo. Na edição sem `price`, só os meios enviados são recalculados; com `price`, os três são recalculados.","example":true},"is_enabled_billet":{"type":"boolean","default":true,"description":"Boleto. Mínimo de R$ 10,00. Os três meios começam ligados, mas cada um só fica ligado se o preço atinge o mínimo dele: PIX R$ 5,00, cartão R$ 5,00 e boleto R$ 10,00. Abaixo do mínimo, o meio é desligado ao salvar, mesmo enviando `true`. Envie `false` para desligar um meio acima do mínimo. Na edição sem `price`, só os meios enviados são recalculados; com `price`, os três são recalculados.","example":true},"max_credit_card_installments":{"type":"integer","example":12,"description":"Máximo de parcelas no cartão de crédito. O valor de cada parcela (price / max_credit_card_installments) não pode ficar abaixo de R$ 5,00 — abaixo disso, a criação/edição retorna 400."}}},"examples":{"default":{"summary":"Oferta avulsa","value":{"product_id":"c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f","price":19790,"title":"Plano Mensal","is_enabled_pix":true,"is_enabled_credit_card":true,"is_enabled_billet":false,"max_credit_card_installments":12}}}}}},"responses":{"201":{"description":"Oferta criada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Offer"}}},"examples":{"default":{"value":{"data":{"id":"d5e6f7a8-b9c0-4d1e-2f3a-4b5c6d7e8f9a","identifier":"PPP1234567890","title":"Plano Mensal","price":197.9,"is_active":true,"is_default":true,"product_id":"c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f","payment_methods":{"pix":true,"credit_card":true,"billet":false},"max_credit_card_installments":12,"cycle":null,"cycle_interval":null,"cycle_interval_limit":null,"allow_purchase_quantity":false,"purchase_quantity_limit":null,"purchase_quantity_min":1,"expires_at":null,"created_at":"2026-01-15T12:00:00.000Z"}}}}}}},"400":{"$ref":"#/components/responses/InvalidData"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"404":{"$ref":"#/components/responses/ProductNotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/offers/{identifier}/shipping":{"get":{"operationId":"listOfferShipping","tags":["Ofertas"],"summary":"Consultar o frete de uma oferta","description":"Devolve as opções de entrega de uma oferta de produto físico para um CEP. Use o `id` da opção escolhida em `shipping_option_id` na criação do pagamento.\n\nPré-requisito, feito pelo vendedor no painel: a integração de logística cadastrada, as dimensões e o peso do produto preenchidos e pelo menos uma configuração de frete ativa. Sem configuração de frete, a consulta responde `400`.\n\nOferta que não é de produto físico responde `200` com a lista vazia. Se a transportadora não responder, as opções de frete calculado ficam de fora e as opções grátis e de valor fixo continuam na lista.","parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string"},"example":"PPP1234567890"},{"name":"postal_code","in":"query","required":true,"description":"CEP de destino, com ou sem pontuação.","schema":{"type":"string"},"example":"01311000"},{"name":"quantity","in":"query","required":false,"description":"Quantidade de unidades, para o cálculo do peso. O padrão é 1.","schema":{"type":"integer","minimum":1},"example":1}],"responses":{"200":{"description":"Opções de frete","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ShippingOption"}}}}}}},"400":{"$ref":"#/components/responses/OfferShippingNotConfigured"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"404":{"$ref":"#/components/responses/OfferNotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/offers/{identifier}":{"get":{"operationId":"getOffer","tags":["Ofertas"],"summary":"Consultar oferta pelo código","parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string"},"example":"PPP1234567890"}],"responses":{"200":{"description":"Oferta","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Offer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"404":{"$ref":"#/components/responses/OfferNotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/offers/by-product/{id}":{"get":{"operationId":"listProductOffers","tags":["Ofertas"],"summary":"Listar ofertas de um produto","description":"`id` precisa ser o id (uuid) de um produto da sua conta — produtos de outro whitelabel retornam 404.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f"},{"name":"page","in":"query","description":"Número da página, começando em 1.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","description":"Itens por página, de 1 a 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"is_active","in":"query","description":"`true` lista só os ativos; `false`, só os inativos. Sem o filtro, lista os dois.","schema":{"type":"boolean"}},{"name":"title","in":"query","description":"Título da oferta. Busca por parte do texto, sem diferenciar maiúsculas de minúsculas.","schema":{"type":"string","minLength":1,"maxLength":255}}],"responses":{"200":{"description":"Lista de ofertas do produto","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Offer"}},"meta":{"type":"object","properties":{"page":{"type":"integer","example":1},"per_page":{"type":"integer","example":25},"total":{"type":"integer","example":143},"total_pages":{"type":"integer","example":6}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"404":{"$ref":"#/components/responses/ProductNotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/offers/{id}":{"patch":{"operationId":"updateOffer","tags":["Ofertas"],"summary":"Editar oferta","description":"Edita campos comerciais de uma oferta já criada. Envie apenas os campos que deseja\natualizar (edição parcial) — o corpo não pode vir vazio.\n\nDiferente da consulta (`GET /offers/{identifier}`, que usa o código da oferta, `PPP` seguido de 10 dígitos), esta\nrota identifica a oferta pelo `id` (uuid).\n\nNão é possível alterar `product_id`, `cycle`/`cycle_interval` (assinatura) ou\n`is_default` por aqui — a troca de oferta padrão continua sendo feita apenas pelo painel.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","example":"d5e6f7a8-b9c0-4d1e-2f3a-4b5c6d7e8f9a"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"price":{"type":"integer","minimum":0,"description":"Preço da oferta em centavos, número inteiro — a mesma unidade de offer.value. 4990 = R$ 49,90. Valor com casas decimais retorna 400.","example":24790},"title":{"type":"string","nullable":true,"example":"Plano Mensal Promocional"},"is_active":{"type":"boolean","example":true},"is_enabled_pix":{"type":"boolean","default":true,"description":"PIX. Mínimo de R$ 5,00. Os três meios começam ligados, mas cada um só fica ligado se o preço atinge o mínimo dele: PIX R$ 5,00, cartão R$ 5,00 e boleto R$ 10,00. Abaixo do mínimo, o meio é desligado ao salvar, mesmo enviando `true`. Envie `false` para desligar um meio acima do mínimo. Na edição sem `price`, só os meios enviados são recalculados; com `price`, os três são recalculados.","example":true},"is_enabled_credit_card":{"type":"boolean","default":true,"description":"Cartão de crédito. Mínimo de R$ 5,00. Os três meios começam ligados, mas cada um só fica ligado se o preço atinge o mínimo dele: PIX R$ 5,00, cartão R$ 5,00 e boleto R$ 10,00. Abaixo do mínimo, o meio é desligado ao salvar, mesmo enviando `true`. Envie `false` para desligar um meio acima do mínimo. Na edição sem `price`, só os meios enviados são recalculados; com `price`, os três são recalculados.","example":true},"is_enabled_billet":{"type":"boolean","default":true,"description":"Boleto. Mínimo de R$ 10,00. Os três meios começam ligados, mas cada um só fica ligado se o preço atinge o mínimo dele: PIX R$ 5,00, cartão R$ 5,00 e boleto R$ 10,00. Abaixo do mínimo, o meio é desligado ao salvar, mesmo enviando `true`. Envie `false` para desligar um meio acima do mínimo. Na edição sem `price`, só os meios enviados são recalculados; com `price`, os três são recalculados.","example":true},"max_credit_card_installments":{"type":"integer","example":6,"description":"Máximo de parcelas no cartão de crédito. O valor de cada parcela (price / max_credit_card_installments) não pode ficar abaixo de R$ 5,00 — abaixo disso, a criação/edição retorna 400."}}},"examples":{"default":{"summary":"Editar preço e título","value":{"price":24790,"title":"Plano Mensal Promocional"}},"deactivate":{"summary":"Desativar oferta","value":{"is_active":false}}}}}},"responses":{"200":{"description":"Oferta atualizada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Offer"}}},"examples":{"default":{"value":{"data":{"id":"d5e6f7a8-b9c0-4d1e-2f3a-4b5c6d7e8f9a","identifier":"PPP1234567890","title":"Plano Mensal Promocional","price":247.9,"is_active":true,"is_default":false,"product_id":"c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f","payment_methods":{"pix":true,"credit_card":true,"billet":false},"max_credit_card_installments":6,"cycle":null,"cycle_interval":null,"cycle_interval_limit":null,"allow_purchase_quantity":false,"purchase_quantity_limit":null,"purchase_quantity_min":1,"expires_at":null,"created_at":"2026-01-15T12:00:00.000Z"}}}}}}},"400":{"$ref":"#/components/responses/InvalidDataOrEmptyBody"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"404":{"$ref":"#/components/responses/OfferUpdateNotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/plans":{"get":{"operationId":"listPlans","tags":["Planos"],"summary":"Listar planos","description":"Um plano é um produto do tipo `SUBSCRIPTION` — aparece aqui, não em `GET /products`.","parameters":[{"name":"page","in":"query","description":"Número da página, começando em 1.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","description":"Itens por página, de 1 a 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"is_active","in":"query","description":"`true` lista só os ativos; `false`, só os inativos. Sem o filtro, lista os dois.","schema":{"type":"boolean"}},{"name":"name","in":"query","description":"Nome do plano. Busca por parte do texto, sem diferenciar maiúsculas de minúsculas.","schema":{"type":"string","minLength":1,"maxLength":255}}],"responses":{"200":{"description":"Lista de planos","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"type":"object","properties":{"page":{"type":"integer","example":1},"per_page":{"type":"integer","example":25},"total":{"type":"integer","example":143},"total_pages":{"type":"integer","example":6}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"createPlan","tags":["Planos"],"summary":"Criar plano","description":"Cria um plano de assinatura — internamente é um produto com `type=SUBSCRIPTION`, por\nisso a resposta usa o mesmo formato de `Product`.\n\nO plano é criado sem imagem e sem categoria — ambos podem ser preenchidos depois pelo\npainel. `warranty_time` também não é aceito no corpo: é resolvido automaticamente a\npartir da configuração mínima de garantia da sua conta.\n\nEste endpoint só cria o plano. Para vender, crie também uma oferta recorrente para ele —\nconsulte `POST /plans/{id}/offers`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":255,"example":"Assinatura Premium"},"description":{"type":"string","nullable":true,"example":"Acesso completo à plataforma, renovação mensal"}}},"examples":{"default":{"summary":"Plano de assinatura","value":{"name":"Assinatura Premium","description":"Acesso completo à plataforma, renovação mensal"}}}}}},"responses":{"201":{"description":"Plano criado","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}}},"examples":{"default":{"value":{"data":{"id":"a8b9c0d1-e2f3-4a4b-5c6d-7e8f9a0b1c2d","name":"Assinatura Premium","description":"Acesso completo à plataforma, renovação mensal","author":null,"promotional_text":null,"is_active":true,"image":null,"type":"SUBSCRIPTION","content_type":"DEFAULT","warranty_time":7,"category":null,"created_at":"2026-01-15T12:00:00.000Z","updated_at":"2026-01-15T12:00:00.000Z"}}}}}}},"400":{"$ref":"#/components/responses/InvalidData"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/plans/{id}":{"get":{"operationId":"getPlan","tags":["Planos"],"summary":"Consultar plano","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"a8b9c0d1-e2f3-4a4b-5c6d-7e8f9a0b1c2d"}],"responses":{"200":{"description":"Plano","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"404":{"$ref":"#/components/responses/PlanNotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"updatePlan","tags":["Planos"],"summary":"Editar plano","description":"Edita campos básicos de um plano já criado. Só `name`, `description` e `is_active`\npodem ser alterados por aqui — envie apenas os campos que deseja atualizar (edição parcial).\n\nO corpo não pode vir vazio: pelo menos um dos três campos precisa ser enviado.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"a8b9c0d1-e2f3-4a4b-5c6d-7e8f9a0b1c2d"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"name":{"type":"string","maxLength":255,"example":"Assinatura Premium"},"description":{"type":"string","nullable":true,"example":"Acesso completo à plataforma, renovação mensal"},"is_active":{"type":"boolean","example":true}}},"examples":{"default":{"summary":"Editar nome e descrição","value":{"name":"Assinatura Premium","description":"Acesso completo à plataforma, renovação mensal"}},"deactivate":{"summary":"Desativar plano","value":{"is_active":false}}}}}},"responses":{"200":{"description":"Plano atualizado","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}}},"examples":{"default":{"value":{"data":{"id":"a8b9c0d1-e2f3-4a4b-5c6d-7e8f9a0b1c2d","name":"Assinatura Premium","description":"Acesso completo à plataforma, renovação mensal","author":null,"promotional_text":null,"is_active":true,"image":null,"type":"SUBSCRIPTION","content_type":"DEFAULT","warranty_time":7,"category":null,"created_at":"2026-01-15T12:00:00.000Z","updated_at":"2026-01-15T12:00:00.000Z"}}}}}}},"400":{"$ref":"#/components/responses/InvalidDataOrEmptyBody"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"404":{"$ref":"#/components/responses/PlanNotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/plans/{id}/offers":{"get":{"operationId":"listPlanOffers","tags":["Planos"],"summary":"Listar ofertas de um plano","description":"`id` precisa ser o id (uuid) de um plano da sua conta — planos de outro whitelabel retornam 404.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"a8b9c0d1-e2f3-4a4b-5c6d-7e8f9a0b1c2d"},{"name":"page","in":"query","description":"Número da página, começando em 1.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","description":"Itens por página, de 1 a 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"is_active","in":"query","description":"`true` lista só os ativos; `false`, só os inativos. Sem o filtro, lista os dois.","schema":{"type":"boolean"}},{"name":"title","in":"query","description":"Título da oferta. Busca por parte do texto, sem diferenciar maiúsculas de minúsculas.","schema":{"type":"string","minLength":1,"maxLength":255}}],"responses":{"200":{"description":"Lista de ofertas do plano","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Offer"}},"meta":{"type":"object","properties":{"page":{"type":"integer","example":1},"per_page":{"type":"integer","example":25},"total":{"type":"integer","example":143},"total_pages":{"type":"integer","example":6}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"404":{"$ref":"#/components/responses/PlanNotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"createPlanOffer","tags":["Planos"],"summary":"Criar oferta de plano","description":"Cria uma oferta **recorrente** para um plano já existente do seu catálogo. `cycle` é\nobrigatório — `WEEKLY`, `MONTHLY` ou `YEARLY` (`DAILY` não é aceito pela API pública).\n\n**Isso cria só a oferta (o preço recorrente) do plano — não cria uma assinatura de\nverdade para um cliente.** Para assinar um cliente de fato nesta oferta, use\n`POST /plans/offer/{id}/subscribe`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"a8b9c0d1-e2f3-4a4b-5c6d-7e8f9a0b1c2d"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["price","cycle"],"properties":{"price":{"type":"integer","minimum":0,"description":"Preço da oferta em centavos, número inteiro — a mesma unidade de offer.value. 4990 = R$ 49,90. Valor com casas decimais retorna 400.","example":9790},"cycle":{"type":"string","enum":["WEEKLY","MONTHLY","YEARLY"],"example":"MONTHLY"},"cycle_interval":{"type":"integer","minimum":1,"description":"A cada quantos ciclos a cobrança se repete (ex.: cycle=MONTHLY + cycle_interval=3 = trimestral).","example":1},"title":{"type":"string","nullable":true,"example":"Plano Mensal"},"is_active":{"type":"boolean","default":true,"example":true},"is_enabled_pix":{"type":"boolean","default":true,"description":"PIX. Mínimo de R$ 5,00. Os três meios começam ligados, mas cada um só fica ligado se o preço atinge o mínimo dele: PIX R$ 5,00, cartão R$ 5,00 e boleto R$ 10,00. Abaixo do mínimo, o meio é desligado ao salvar, mesmo enviando `true`. Envie `false` para desligar um meio acima do mínimo. Na edição sem `price`, só os meios enviados são recalculados; com `price`, os três são recalculados.","example":true},"is_enabled_credit_card":{"type":"boolean","default":true,"description":"Cartão de crédito. Mínimo de R$ 5,00. Os três meios começam ligados, mas cada um só fica ligado se o preço atinge o mínimo dele: PIX R$ 5,00, cartão R$ 5,00 e boleto R$ 10,00. Abaixo do mínimo, o meio é desligado ao salvar, mesmo enviando `true`. Envie `false` para desligar um meio acima do mínimo. Na edição sem `price`, só os meios enviados são recalculados; com `price`, os três são recalculados.","example":true},"is_enabled_billet":{"type":"boolean","default":true,"description":"Boleto. Mínimo de R$ 10,00. Os três meios começam ligados, mas cada um só fica ligado se o preço atinge o mínimo dele: PIX R$ 5,00, cartão R$ 5,00 e boleto R$ 10,00. Abaixo do mínimo, o meio é desligado ao salvar, mesmo enviando `true`. Envie `false` para desligar um meio acima do mínimo. Na edição sem `price`, só os meios enviados são recalculados; com `price`, os três são recalculados.","example":true},"max_credit_card_installments":{"type":"integer","example":1,"description":"Ofertas de plano não podem ser parceladas no cartão de crédito — envie 1 ou omita o campo (default). Valores acima de 1 retornam 400."}}},"examples":{"default":{"summary":"Oferta mensal","value":{"price":9790,"cycle":"MONTHLY","title":"Plano Mensal","is_enabled_pix":true,"is_enabled_credit_card":true,"is_enabled_billet":false}}}}}},"responses":{"201":{"description":"Oferta de plano criada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Offer"}}},"examples":{"default":{"value":{"data":{"id":"b9c0d1e2-f3a4-4b5c-6d7e-8f9a0b1c2d3e","identifier":"PPP1234567890","title":"Plano Mensal","price":97.9,"is_active":true,"is_default":true,"product_id":"a8b9c0d1-e2f3-4a4b-5c6d-7e8f9a0b1c2d","payment_methods":{"pix":true,"credit_card":true,"billet":false},"max_credit_card_installments":1,"cycle":"MONTHLY","cycle_interval":1,"cycle_interval_limit":null,"allow_purchase_quantity":false,"purchase_quantity_limit":null,"purchase_quantity_min":1,"expires_at":null,"created_at":"2026-01-15T12:00:00.000Z"}}}}}}},"400":{"$ref":"#/components/responses/InvalidData"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"404":{"$ref":"#/components/responses/PlanNotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/plan-offers/{id}":{"patch":{"operationId":"updatePlanOffer","tags":["Planos"],"summary":"Editar oferta de plano","description":"Edita campos comerciais de uma oferta de plano já criada. Envie apenas os campos que\ndeseja atualizar (edição parcial) — o corpo não pode vir vazio.\n\nNão é possível alterar `product_id` ou `is_default` por aqui — a troca de oferta\npadrão continua sendo feita apenas pelo painel.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","example":"b9c0d1e2-f3a4-4b5c-6d7e-8f9a0b1c2d3e"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"price":{"type":"integer","minimum":0,"description":"Preço da oferta em centavos, número inteiro — a mesma unidade de offer.value. 4990 = R$ 49,90. Valor com casas decimais retorna 400.","example":11790},"cycle":{"type":"string","enum":["WEEKLY","MONTHLY","YEARLY"],"example":"MONTHLY"},"cycle_interval":{"type":"integer","minimum":1,"example":1},"title":{"type":"string","nullable":true,"example":"Plano Mensal"},"is_active":{"type":"boolean","example":true},"is_enabled_pix":{"type":"boolean","default":true,"description":"PIX. Mínimo de R$ 5,00. Os três meios começam ligados, mas cada um só fica ligado se o preço atinge o mínimo dele: PIX R$ 5,00, cartão R$ 5,00 e boleto R$ 10,00. Abaixo do mínimo, o meio é desligado ao salvar, mesmo enviando `true`. Envie `false` para desligar um meio acima do mínimo. Na edição sem `price`, só os meios enviados são recalculados; com `price`, os três são recalculados.","example":true},"is_enabled_credit_card":{"type":"boolean","default":true,"description":"Cartão de crédito. Mínimo de R$ 5,00. Os três meios começam ligados, mas cada um só fica ligado se o preço atinge o mínimo dele: PIX R$ 5,00, cartão R$ 5,00 e boleto R$ 10,00. Abaixo do mínimo, o meio é desligado ao salvar, mesmo enviando `true`. Envie `false` para desligar um meio acima do mínimo. Na edição sem `price`, só os meios enviados são recalculados; com `price`, os três são recalculados.","example":true},"is_enabled_billet":{"type":"boolean","default":true,"description":"Boleto. Mínimo de R$ 10,00. Os três meios começam ligados, mas cada um só fica ligado se o preço atinge o mínimo dele: PIX R$ 5,00, cartão R$ 5,00 e boleto R$ 10,00. Abaixo do mínimo, o meio é desligado ao salvar, mesmo enviando `true`. Envie `false` para desligar um meio acima do mínimo. Na edição sem `price`, só os meios enviados são recalculados; com `price`, os três são recalculados.","example":true},"max_credit_card_installments":{"type":"integer","example":1,"description":"Ofertas de plano não podem ser parceladas no cartão de crédito — envie 1 ou omita o campo (default). Valores acima de 1 retornam 400."}}},"examples":{"default":{"summary":"Editar preço","value":{"price":11790}},"deactivate":{"summary":"Desativar oferta de plano","value":{"is_active":false}}}}}},"responses":{"200":{"description":"Oferta de plano atualizada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Offer"}}},"examples":{"default":{"value":{"data":{"id":"b9c0d1e2-f3a4-4b5c-6d7e-8f9a0b1c2d3e","identifier":"PPP1234567890","title":"Plano Mensal","price":117.9,"is_active":true,"is_default":true,"product_id":"a8b9c0d1-e2f3-4a4b-5c6d-7e8f9a0b1c2d","payment_methods":{"pix":true,"credit_card":true,"billet":false},"max_credit_card_installments":1,"cycle":"MONTHLY","cycle_interval":1,"cycle_interval_limit":null,"allow_purchase_quantity":false,"purchase_quantity_limit":null,"purchase_quantity_min":1,"expires_at":null,"created_at":"2026-01-15T12:00:00.000Z"}}}}}}},"400":{"$ref":"#/components/responses/InvalidDataOrEmptyBody"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"404":{"$ref":"#/components/responses/PlanOfferNotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/plans/offer/{id}/subscribe":{"post":{"operationId":"createSubscription","tags":["Assinaturas"],"summary":"Assinar um plano (criar assinatura)","description":"Cria uma assinatura de verdade para um cliente em uma oferta de plano existente. `id`\npode ser o id (uuid) **ou** o identifier da oferta de plano — mesma resolução usada em\n`GET /offers/{identifier}`.\n\nSó aceita **cartão de crédito**.\n\nA cobrança do cartão é feita no gateway **depois** da resposta desta requisição: a\nassinatura retorna com `status: DRAFT`. O webhook `SUBSCRIPTION_CONFIRMED` avisa que o\ngateway aceitou a assinatura — o status continua `DRAFT` — e ela vira `ACTIVE` quando a\nprimeira fatura é paga. Se o gateway recusar, o webhook é `SUBSCRIPTION_FAILED` e o status\nvira `FAILED`. Como alternativa aos webhooks, faça polling em `GET /subscriptions/{id}`.\n\nO header `Idempotency-Key` é **obrigatório**. Em caso de timeout, reenvie a requisição\ncom a mesma chave: a resposta original será devolvida sem criar uma segunda assinatura.\n\n**Uma assinatura não é cobrada diretamente — cada ciclo cobrado (o primeiro e todas as\nrenovações seguintes) gera uma `Transaction` própria**, a mesma entidade retornada por\n`GET /sales`/`GET /sales/{identifier}`. Ou seja, para acompanhar os pagamentos de uma\nassinatura ao longo do tempo, use os eventos de transação (`TRANSACTION_PAID`,\n`TRANSACTION_CANCELED`, etc.) e `GET /sales` filtrando pelo cliente/período — os eventos\nde assinatura (`SUBSCRIPTION_*`) informam mudanças de status da assinatura em si, não de\ncada cobrança individual.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"b9c0d1e2-f3a4-4b5c-6d7e-8f9a0b1c2d3e"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"example":"2f1c4d2e-8f4a-4c1e-9f7b-6a2d1e3c5b90"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["installments","customer","credit_card"],"properties":{"installments":{"type":"integer","minimum":1,"maximum":12,"description":"O máximo real pode ser menor que 12: é limitado pela configuração da oferta (consulte max_credit_card_installments em GET /offers/{identifier}). Acima do limite da oferta, retorna 400.","example":3},"customer":{"type":"object","required":["name","email","document","phone"],"properties":{"name":{"type":"string","example":"Fulano de Tal"},"email":{"type":"string","format":"email","example":"fulano@exemplo.com"},"document":{"type":"string","description":"CPF (11 dígitos) ou CNPJ (14 dígitos), com ou sem pontuação: `12345678909` ou `123.456.789-09`. A API grava só os dígitos. Fora disso, 400.","example":"12345678909"},"phone":{"type":"string","description":"DDD e número, com 10 ou 11 dígitos (12 ou 13 com o código do país 55). Pontuação, espaços, parênteses e `+` são aceitos: `11999998888`, `(11) 99999-8888` ou `+55 11 99999-8888`. A API grava só os dígitos. Fora disso, 400.","example":"11999999999"}}},"address":{"type":"object","description":"Obrigatório quando a oferta é de produto físico (`requires_shipping: true`); nos demais casos é opcional e não é usado no processamento da venda.","required":["street","number","neighborhood","city","state","postal_code"],"properties":{"street":{"type":"string","example":"Rua das Flores"},"number":{"type":"string","example":"123"},"complement":{"type":"string","nullable":true,"example":"Apto 4B"},"neighborhood":{"type":"string","example":"Centro"},"city":{"type":"string","example":"São Paulo"},"state":{"type":"string","example":"SP"},"postal_code":{"type":"string","example":"01000-000"}}},"credit_card":{"type":"object","required":["holder_name","holder_document","number","expiration_month","expiration_year","cvv"],"description":"Dados do cartão de crédito usado na cobrança.","properties":{"holder_name":{"type":"string","example":"FULANO DE TAL"},"holder_document":{"type":"string","description":"CPF (11 dígitos) ou CNPJ (14 dígitos) do titular do cartão, com ou sem pontuação. A API grava só os dígitos. Fora disso, 400.","example":"12345678909"},"number":{"type":"string","example":"4111111111111111"},"expiration_month":{"type":"integer","minimum":1,"maximum":12,"example":12},"expiration_year":{"type":"integer","minimum":2000,"maximum":2100,"example":2030},"cvv":{"type":"string","example":"123"}}},"buyer_ip":{"type":"string","description":"IP do comprador final. Melhora a análise antifraude.","example":"203.0.113.10"},"buyer_user_agent":{"type":"string"},"affiliate_identifier":{"type":"string","pattern":"^PAO[0-9]{10}$","example":"PAO1234567890","description":"Código do afiliado que trouxe a venda, no formato `PAO` seguido de 10 dígitos. Formato inválido retorna `400`. Código de afiliado inexistente, de outro produto, inativo ou sem a oferta liberada é **ignorado**: a venda é processada normalmente, sem afiliado. Não há cookie nem regra de primeiro ou último clique — vale o código enviado."},"external_reference":{"type":"string","maxLength":255,"description":"Referência do pedido no seu sistema (por exemplo, o número do pedido). Opcional. Depois você consulta a venda por ela em `GET /sales/{identifier}` e filtra em `GET /sales?external_reference=`. Pode se repetir entre pedidos: a consulta devolve a venda mais recente com essa referência.","example":"PED-2026-0001"}}},"examples":{"default":{"summary":"Assinar plano mensal","value":{"installments":1,"customer":{"name":"Fulano de Tal","email":"fulano@exemplo.com","document":"12345678909","phone":"11999999999"},"credit_card":{"holder_name":"FULANO DE TAL","holder_document":"12345678909","number":"4111111111111111","expiration_month":12,"expiration_year":2030,"cvv":"123"},"buyer_ip":"203.0.113.10"}}}}}},"responses":{"201":{"description":"Assinatura criada (status inicial DRAFT, aguardando confirmação do gateway)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Subscription"}}},"examples":{"default":{"value":{"data":{"id":"f7a8b9c0-d1e2-4f3a-4b5c-6d7e8f9a0b1c","status":"DRAFT","payment_method":"CREDIT_CARD","start_at":null,"next_billing_at":null,"next_billing_amount":null,"total_amount":null,"canceled_at":null,"created_at":"2026-01-15T12:00:00.000Z"}}}}}}},"400":{"$ref":"#/components/responses/PaymentBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"404":{"$ref":"#/components/responses/PlanOfferNotFound"},"409":{"$ref":"#/components/responses/PaymentConflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/sales":{"get":{"operationId":"listSales","tags":["Vendas"],"summary":"Listar vendas","parameters":[{"name":"page","in":"query","description":"Número da página, começando em 1.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","description":"Itens por página, de 1 a 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"status","in":"query","description":"Situação da venda.","schema":{"type":"string","enum":["DRAFT","OPEN","PROCESSING","PAID","CANCELED","ASK_REFUND","ASK_PARTIAL_REFUND","REFUNDED","PARTIALLY_REFUNDED","REFUNDING","ABANDONED","EXPIRED","FAILED","CHARGEBACK_REQUESTED","CHARGEBACK_APPROVED"]}},{"name":"payment_method","in":"query","description":"Meio de pagamento da venda.","schema":{"type":"string","enum":["CREDIT_CARD","PIX","BOLETO","APPLE_PAY","GOOGLE_PAY"]}},{"name":"created_from","in":"query","description":"Vendas criadas a partir desta data e hora, incluindo ela. ISO 8601 com fuso.","schema":{"type":"string","format":"date-time"}},{"name":"created_to","in":"query","description":"Vendas criadas até esta data e hora, incluindo ela. ISO 8601 com fuso.","schema":{"type":"string","format":"date-time"}},{"name":"external_reference","in":"query","description":"Lista só as vendas com esta referência do pedido (a mesma enviada na criação do pagamento ou da assinatura).","schema":{"type":"string","maxLength":255}},{"name":"product_id","in":"query","description":"Vendas que têm este produto em algum item. A venda volta com todos os itens.","schema":{"type":"string","format":"uuid"}},{"name":"customer_email","in":"query","description":"E-mail do cliente da venda. E-mail completo, sem diferenciar maiúsculas de minúsculas.","schema":{"type":"string","format":"email"}},{"name":"customer_document","in":"query","description":"Documento do cliente da venda. CPF com 11 dígitos ou CNPJ com 14, com ou sem pontuação.","schema":{"type":"string","example":"123.456.789-09"}}],"responses":{"200":{"description":"Lista de vendas","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Sale"}},"meta":{"type":"object","properties":{"page":{"type":"integer","example":1},"per_page":{"type":"integer","example":25},"total":{"type":"integer","example":143},"total_pages":{"type":"integer","example":6}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sales/{identifier}":{"get":{"operationId":"getSale","tags":["Vendas"],"summary":"Consultar venda","description":"Aceita três formas de referência, testadas nesta ordem: o `id` da venda (uuid, o mesmo que volta em `transactions` na criação do pagamento), o código da venda e a `external_reference` que você enviou no pedido. O valor só é tratado como código quando tem o formato do código: 10 dígitos, com ou sem o prefixo (ex.: `PPO0087103960`), ou um link terminado nele. Se a mesma `external_reference` foi usada em mais de um pedido, volta a venda mais recente.","parameters":[{"name":"identifier","in":"path","required":true,"description":"Id (uuid), código ou referência externa da venda.","schema":{"type":"string"}}],"responses":{"200":{"description":"Venda","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Sale"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"404":{"$ref":"#/components/responses/SaleNotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/refunds":{"get":{"operationId":"listRefunds","tags":["Reembolsos"],"summary":"Listar reembolsos","description":"Lista os pedidos de reembolso das suas vendas, do mais recente para o mais antigo — abertos\npelo comprador ou por você. Cada pedido traz a situação, o motivo, o valor (quando parcial) e\na venda a que pertence.\n\nPara ser avisado em tempo real, assine os webhooks `TRANSACTION_ASK_REFUNDING` (pedido\nrecebido) e `TRANSACTION_REFUNDED` (estorno concluído).","parameters":[{"name":"page","in":"query","description":"Número da página, começando em 1.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","description":"Itens por página, de 1 a 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"status","in":"query","description":"Situação do pedido (veja `Refund.status`).","schema":{"type":"string"}},{"name":"sale_identifier","in":"query","description":"Código da venda — traz só os pedidos dessa venda.","schema":{"type":"string"}},{"name":"created_from","in":"query","description":"Solicitações de reembolso criadas a partir desta data e hora, incluindo ela. ISO 8601 com fuso.","schema":{"type":"string","format":"date-time"}},{"name":"created_to","in":"query","description":"Solicitações de reembolso criadas até esta data e hora, incluindo ela. ISO 8601 com fuso.","schema":{"type":"string","format":"date-time"}},{"name":"customer_email","in":"query","description":"E-mail do cliente da venda. E-mail completo, sem diferenciar maiúsculas de minúsculas.","schema":{"type":"string","format":"email"}},{"name":"customer_document","in":"query","description":"Documento do cliente da venda. CPF com 11 dígitos ou CNPJ com 14, com ou sem pontuação.","schema":{"type":"string","example":"123.456.789-09"}}],"responses":{"200":{"description":"Lista de reembolsos","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}},"meta":{"type":"object","properties":{"page":{"type":"integer","example":1},"per_page":{"type":"integer","example":25},"total":{"type":"integer","example":143},"total_pages":{"type":"integer","example":6}}}}}}}},"400":{"$ref":"#/components/responses/InvalidFilter"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"createRefund","tags":["Reembolsos"],"summary":"Reembolsar uma venda","description":"Reembolsa uma venda sua. Como quem pede é o próprio vendedor, o pedido **já nasce aceito**:\no estorno é enviado ao gateway na hora, a assinatura da venda é cancelada e os acessos do\ncomprador são revogados. **Não há como desfazer.**\n\nO reembolso é sempre **total**. Reembolso de alguns itens continua só no painel.\n\nA venda precisa estar paga ou já com um pedido de reembolso aberto; em qualquer outra\nsituação a resposta é `409`. Só existe um pedido em andamento por venda.\n\nA resposta traz a situação do pedido: `REFUNDING` enquanto o gateway não confirma e\n`FAILED` quando ele recusa o estorno (por exemplo, por falta de saldo de um co-produtor).\nA confirmação vem depois pelo webhook `TRANSACTION_REFUNDED`.\n\nO header `Idempotency-Key` é **obrigatório**: reenviar a mesma chave devolve a resposta\noriginal, sem pedir um segundo estorno.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"example":"2f1c4d2e-8f4a-4c1e-9f7b-6a2d1e3c5b90"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundCreateRequest"},"examples":{"default":{"summary":"Reembolso total","value":{"sale_identifier":"PPO9876543210","reason":"Cliente desistiu da compra"}}}}}},"responses":{"201":{"description":"Reembolso solicitado","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Refund"}}}}}},"400":{"$ref":"#/components/responses/RefundBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"404":{"$ref":"#/components/responses/SaleNotFound"},"409":{"$ref":"#/components/responses/RefundConflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/subscriptions":{"get":{"operationId":"listSubscriptions","tags":["Assinaturas"],"summary":"Listar assinaturas","parameters":[{"name":"page","in":"query","description":"Número da página, começando em 1.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","description":"Itens por página, de 1 a 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"status","in":"query","description":"Situação da assinatura.","schema":{"type":"string","enum":["DRAFT","PENDING_PAYMENT","ACTIVE","PENDING_RENEWAL","PROCESSING","CANCELING","CANCELED","ASK_REFUND","REFUNDED","ABANDONED","EXPIRED","FAILED"]}},{"name":"plan_id","in":"query","description":"Assinaturas deste plano.","schema":{"type":"string","format":"uuid"}},{"name":"customer_email","in":"query","description":"E-mail do cliente da assinatura. E-mail completo, sem diferenciar maiúsculas de minúsculas.","schema":{"type":"string","format":"email"}},{"name":"customer_document","in":"query","description":"Documento do cliente da assinatura. CPF com 11 dígitos ou CNPJ com 14, com ou sem pontuação.","schema":{"type":"string","example":"123.456.789-09"}},{"name":"created_from","in":"query","description":"Assinaturas criadas a partir desta data e hora, incluindo ela. ISO 8601 com fuso.","schema":{"type":"string","format":"date-time"}},{"name":"created_to","in":"query","description":"Assinaturas criadas até esta data e hora, incluindo ela. ISO 8601 com fuso.","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Lista de assinaturas","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Subscription"}},"meta":{"type":"object","properties":{"page":{"type":"integer","example":1},"per_page":{"type":"integer","example":25},"total":{"type":"integer","example":143},"total_pages":{"type":"integer","example":6}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/subscriptions/{id}":{"get":{"operationId":"getSubscription","tags":["Assinaturas"],"summary":"Consultar assinatura","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Assinatura","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Subscription"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"404":{"$ref":"#/components/responses/SubscriptionNotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"operationId":"cancelSubscription","tags":["Assinaturas"],"summary":"Cancelar assinatura","description":"Solicita o cancelamento da assinatura.\n\n- **Boleto ou PIX**: cancelamento é imediato — a assinatura muda para `canceled`,\n o acesso é revogado de imediato nas integrações (MemberKit/Circle) e não há mais cobranças.\n- **Cartão de crédito**: o cancelamento é solicitado ao gateway de pagamento e a assinatura\n fica com status `canceling` até a confirmação (assíncrona).\n\nCancelar uma assinatura que já está cancelada ou em outro status que não permite\ncancelamento não tem efeito (operação idempotente).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Cancelamento solicitado","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperationResult"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"404":{"$ref":"#/components/responses/SubscriptionNotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/subscriptions/{id}/card":{"patch":{"operationId":"updateSubscriptionCard","tags":["Assinaturas"],"summary":"Trocar cartão da assinatura","description":"Substitui o cartão de crédito usado nas cobranças de uma assinatura paga com cartão. O novo\ncartão é salvo no gateway e passa a ser cobrado a partir do próximo ciclo; o plano, o valor e\nas datas de cobrança não mudam.\n\nA troca é aceita em qualquer situação da assinatura — use-a, por exemplo, para regularizar uma\nassinatura cuja renovação foi recusada. Se o gateway não aceitar a troca naquele estado, a\nrequisição retorna `400` com a mensagem do gateway.\n\nA troca não gera cobrança, por isso não exige `Idempotency-Key`. Conta no limite por minuto\nda credencial, como qualquer rota.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["credit_card"],"properties":{"credit_card":{"type":"object","required":["holder_name","holder_document","number","expiration_month","expiration_year","cvv"],"description":"Dados do cartão de crédito usado na cobrança.","properties":{"holder_name":{"type":"string","example":"FULANO DE TAL"},"holder_document":{"type":"string","description":"CPF (11 dígitos) ou CNPJ (14 dígitos) do titular do cartão, com ou sem pontuação. A API grava só os dígitos. Fora disso, 400.","example":"12345678909"},"number":{"type":"string","example":"4111111111111111"},"expiration_month":{"type":"integer","minimum":1,"maximum":12,"example":12},"expiration_year":{"type":"integer","minimum":2000,"maximum":2100,"example":2030},"cvv":{"type":"string","example":"123"}}}}},"examples":{"default":{"summary":"Novo cartão","value":{"credit_card":{"holder_name":"FULANO DE TAL","holder_document":"12345678909","number":"4111111111111111","expiration_month":12,"expiration_year":2030,"cvv":"123"}}}}}}},"responses":{"200":{"description":"Cartão da assinatura atualizado","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperationResult"}}}}}},"400":{"$ref":"#/components/responses/SubscriptionCardBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"404":{"$ref":"#/components/responses/SubscriptionNotFound"},"429":{"$ref":"#/components/responses/SubscriptionCardRateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/subscriptions/{id}/plan-options":{"get":{"operationId":"listSubscriptionPlanOptions","tags":["Assinaturas"],"summary":"Listar opções de troca de plano","description":"Lista os planos do mesmo produto disponíveis para troca (upgrade ou downgrade) nesta assinatura, e se o produto permite troca de plano pelo cliente.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Opções de troca de plano","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PlanChangeOptions"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"404":{"$ref":"#/components/responses/SubscriptionNotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/subscriptions/{id}/plan-change/preview":{"post":{"operationId":"previewSubscriptionPlanChange","tags":["Assinaturas"],"summary":"Calcular preview de troca de plano","description":"Calcula o crédito ou cobrança proporcional de uma troca de plano sem efetivá-la. Não tem efeito colateral.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["new_product_price_id"],"properties":{"new_product_price_id":{"type":"string","format":"uuid"}}},"examples":{"default":{"summary":"Preview de troca","value":{"new_product_price_id":"b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"}}}}}},"responses":{"200":{"description":"Preview calculado","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PlanChangePreview"}}}}}},"400":{"$ref":"#/components/responses/PlanChangePreviewBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"404":{"$ref":"#/components/responses/SubscriptionOrPlanNotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/subscriptions/{id}/plan-change":{"post":{"operationId":"changeSubscriptionPlan","tags":["Assinaturas"],"summary":"Executar upgrade ou downgrade de plano","description":"Executa a troca de plano de uma assinatura. A direção (upgrade ou downgrade) é\ndeterminada automaticamente pela comparação de preço entre o plano atual e o novo plano.\n\n- **Upgrade**: cobra a diferença proporcional imediatamente, no cartão salvo da assinatura\n (`payment_choice=current`) ou em um novo cartão informado no corpo da requisição\n (`payment_choice=new_card`).\n- **Upgrade no cartão aprovado, mas sem a troca concluída na hora** (por exemplo, falha no\n gateway ao atualizar o plano): a resposta é `200` com `upgrade.status` `pending`, e a venda\n da diferença continua em `PROCESSING`. A troca é confirmada quando o gateway avisa o pagamento; nesse\n momento a venda passa a `PAID` e o webhook `TRANSACTION_PAID` é enviado. Não cobre de novo.\n- **Downgrade**: não gera cobrança imediata; é agendado para entrar em vigor na próxima\n renovação da assinatura.\n\nO header `Idempotency-Key` é **obrigatório**. Em caso de timeout, reenvie a requisição\ncom a mesma chave: a resposta original será devolvida sem processar a troca duas vezes.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"example":"3a2b1c4d-9e8f-4a7b-8c6d-5e4f3a2b1c0d"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["new_product_price_id"],"properties":{"new_product_price_id":{"type":"string","format":"uuid"},"payment_choice":{"type":"string","enum":["current","new_card"],"default":"current","description":"Só é relevante para upgrade. Ignorado em downgrade."},"card":{"type":"object","description":"Obrigatório somente quando payment_choice=new_card","properties":{"number":{"type":"string"},"holder_name":{"type":"string"},"holder_document":{"type":"string","description":"CPF (11 dígitos) ou CNPJ (14 dígitos) do titular, com ou sem pontuação. Fora disso, 400."},"exp_month":{"type":"integer"},"exp_year":{"type":"integer"},"cvv":{"type":"string"}}}}},"examples":{"upgrade_current_card":{"summary":"Upgrade cobrando no cartão salvo","value":{"new_product_price_id":"b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e","payment_choice":"current"}},"upgrade_new_card":{"summary":"Upgrade com novo cartão","value":{"new_product_price_id":"b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e","payment_choice":"new_card","card":{"number":"4111111111111111","holder_name":"FULANO DE TAL","holder_document":"12345678909","exp_month":12,"exp_year":2030,"cvv":"123"}}},"downgrade":{"summary":"Downgrade (agendado para a próxima renovação)","value":{"new_product_price_id":"c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f"}}}}}},"responses":{"200":{"description":"Troca de plano processada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PlanChange"}}},"examples":{"upgrade":{"summary":"Upgrade cobrado via PIX","value":{"data":{"type":"UPGRADE","upgrade":{"transaction_id":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","charge_amount":49.9,"status":"pending","pix":{"qr_code":"00020126..."}}}}},"downgrade":{"summary":"Downgrade agendado","value":{"data":{"type":"DOWNGRADE"}}}}}}},"400":{"$ref":"#/components/responses/PlanChangeBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/PlanChangeForbidden"},"404":{"$ref":"#/components/responses/SubscriptionOrPlanNotFound"},"409":{"$ref":"#/components/responses/PlanChangeConflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/customers":{"get":{"operationId":"listCustomers","tags":["Clientes"],"summary":"Listar clientes","description":"Documento e telefone são sempre mascarados nesta API.","parameters":[{"name":"page","in":"query","description":"Número da página, começando em 1.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","description":"Itens por página, de 1 a 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"email","in":"query","description":"E-mail do cliente. E-mail completo, sem diferenciar maiúsculas de minúsculas.","schema":{"type":"string","format":"email"}},{"name":"name","in":"query","description":"Nome do cliente. Busca por parte do texto, sem diferenciar maiúsculas de minúsculas.","schema":{"type":"string","minLength":1,"maxLength":255}},{"name":"document","in":"query","description":"Documento do cliente. CPF com 11 dígitos ou CNPJ com 14, com ou sem pontuação.","schema":{"type":"string","example":"123.456.789-09"}}],"responses":{"200":{"description":"Lista de clientes","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"meta":{"type":"object","properties":{"page":{"type":"integer","example":1},"per_page":{"type":"integer","example":25},"total":{"type":"integer","example":143},"total_pages":{"type":"integer","example":6}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/customers/{id}":{"get":{"operationId":"getCustomer","tags":["Clientes"],"summary":"Consultar cliente","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Cliente","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Customer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"404":{"$ref":"#/components/responses/CustomerNotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/payments/pix":{"post":{"operationId":"createPixPayment","tags":["Vendas"],"summary":"Fazer uma venda no PIX","description":"Cria uma cobrança PIX em cima de uma oferta existente. O método de pagamento é definido\npela própria rota, então não é preciso enviar `payment_method` no corpo.\n\nO header `Idempotency-Key` é **obrigatório**. Em caso de timeout, reenvie a requisição\ncom a mesma chave: a resposta original será devolvida sem gerar uma segunda cobrança.\n\nA resposta desta rota traz o PIX **gerado** (`pix.qr_code`), não o **pago**. A confirmação\ndo pagamento acontece de forma assíncrona — assine o webhook `TRANSACTION_PAID` para ser\nnotificado assim que o PIX for pago, ou consulte `GET /sales/{identifier}` usando o\n`transactions[0]` da resposta para checar o `status` a qualquer momento.\n\nEsta rota **não cria assinaturas**: mesmo apontando para uma oferta recorrente, o\nresultado é sempre uma cobrança avulsa (`subscriptions` sempre vem vazio na resposta).","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"example":"2f1c4d2e-8f4a-4c1e-9f7b-6a2d1e3c5b90"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PixDedicatedPaymentRequest"},"examples":{"default":{"summary":"PIX com offer_identifier (sem offer)","value":{"offer_identifier":"PPP1234567890","customer":{"name":"Fulano de Tal","email":"fulano@exemplo.com","document":"12345678909","phone":"11999999999"},"buyer_ip":"203.0.113.10"}},"hiddenOffer":{"summary":"PIX com offer (sem offer_identifier)","value":{"offer":{"product_id":"c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f","name":"Consultoria avulsa","value":4990,"createOffer":false},"customer":{"name":"Fulano de Tal","email":"fulano@exemplo.com","document":"12345678909","phone":"11999999999"},"buyer_ip":"203.0.113.10"}}}}}},"responses":{"201":{"description":"Pagamento PIX criado","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PaymentResult"}}},"examples":{"default":{"summary":"PIX","value":{"data":{"offer_identifier":"PPP1234567890","transactions":["a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"],"subscriptions":[],"pix":{"qr_code":"00020126..."}}}}}}}},"400":{"$ref":"#/components/responses/PaymentBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"404":{"$ref":"#/components/responses/PaymentOfferNotFound"},"409":{"$ref":"#/components/responses/PaymentConflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/payments/boleto":{"post":{"operationId":"createBoletoPayment","tags":["Vendas"],"summary":"Fazer uma venda no boleto","description":"Cria uma cobrança em boleto em cima de uma oferta existente. O método de pagamento é\ndefinido pela própria rota, então não é preciso enviar `payment_method` no corpo.\n\nO header `Idempotency-Key` é **obrigatório**. Em caso de timeout, reenvie a requisição\ncom a mesma chave: a resposta original será devolvida sem gerar uma segunda cobrança.\n\nEsta rota **não cria assinaturas**: mesmo apontando para uma oferta recorrente, o\nresultado é sempre uma cobrança avulsa (`subscriptions` sempre vem vazio na resposta).","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"example":"2f1c4d2e-8f4a-4c1e-9f7b-6a2d1e3c5b90"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoletoDedicatedPaymentRequest"},"examples":{"default":{"summary":"Boleto com offer_identifier (sem offer)","value":{"offer_identifier":"PPP1234567890","customer":{"name":"Fulano de Tal","email":"fulano@exemplo.com","document":"12345678909","phone":"11999999999"},"buyer_ip":"203.0.113.10"}},"hiddenOffer":{"summary":"Boleto com offer (sem offer_identifier)","value":{"offer":{"product_id":"c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f","name":"Consultoria avulsa","value":4990,"createOffer":false},"customer":{"name":"Fulano de Tal","email":"fulano@exemplo.com","document":"12345678909","phone":"11999999999"},"buyer_ip":"203.0.113.10"}}}}}},"responses":{"201":{"description":"Pagamento em boleto criado","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PaymentResult"}}},"examples":{"default":{"summary":"Boleto","value":{"data":{"offer_identifier":"PPP1234567890","transactions":["a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"],"subscriptions":[],"boleto":{"barcode":"34191.79001 01043.510047 91020.150008 1 96610000015000","pdf_link":"https://boletos.pagpolar.com/a1b2c3d4.pdf"}}}}}}}},"400":{"$ref":"#/components/responses/PaymentBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"404":{"$ref":"#/components/responses/PaymentOfferNotFound"},"409":{"$ref":"#/components/responses/PaymentConflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/payments/credit-card":{"post":{"operationId":"createCreditCardPayment","tags":["Vendas"],"summary":"Fazer uma venda no cartão de crédito","description":"Cria uma cobrança em cartão de crédito em cima de uma oferta existente. O método de\npagamento é definido pela própria rota, então não é preciso enviar `payment_method` no\ncorpo.\n\nO header `Idempotency-Key` é **obrigatório**. Em caso de timeout, reenvie a requisição\ncom a mesma chave: a resposta original será devolvida sem gerar uma segunda cobrança.\n\nA cobrança no cartão pode ser confirmada ou recusada pelo gateway na hora ou depois da\nresposta desta requisição. Aprovada, chega o webhook `TRANSACTION_PAID`. **Recusada, a venda\nfica `FAILED` e nenhum evento é enviado** — nem `TRANSACTION_CANCELED`. Confira o `status`\nconsultando `GET /sales/{identifier}` com o `transactions[0]` da resposta.\n\nEsta rota **não cria assinaturas**: mesmo apontando para uma oferta recorrente, o\nresultado é sempre uma cobrança avulsa (`subscriptions` sempre vem vazio na resposta).","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"example":"2f1c4d2e-8f4a-4c1e-9f7b-6a2d1e3c5b90"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditCardDedicatedPaymentRequest"},"examples":{"default":{"summary":"Cartão com offer_identifier (sem offer)","value":{"offer_identifier":"PPP1234567890","installments":3,"customer":{"name":"Fulano de Tal","email":"fulano@exemplo.com","document":"12345678909","phone":"11999999999"},"credit_card":{"holder_name":"FULANO DE TAL","holder_document":"12345678909","number":"4111111111111111","expiration_month":12,"expiration_year":2030,"cvv":"123"},"buyer_ip":"203.0.113.10"}},"hiddenOffer":{"summary":"Cartão com offer (sem offer_identifier)","value":{"offer":{"product_id":"c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f","name":"Consultoria avulsa","value":4990,"createOffer":false},"installments":3,"customer":{"name":"Fulano de Tal","email":"fulano@exemplo.com","document":"12345678909","phone":"11999999999"},"credit_card":{"holder_name":"FULANO DE TAL","holder_document":"12345678909","number":"4111111111111111","expiration_month":12,"expiration_year":2030,"cvv":"123"},"buyer_ip":"203.0.113.10"}}}}}},"responses":{"201":{"description":"Pagamento em cartão de crédito criado","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PaymentResult"}}},"examples":{"default":{"summary":"Cartão de crédito","value":{"data":{"offer_identifier":"PPP1234567890","transactions":["a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"],"subscriptions":[]}}}}}}},"400":{"$ref":"#/components/responses/PaymentBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"404":{"$ref":"#/components/responses/PaymentOfferNotFound"},"409":{"$ref":"#/components/responses/PaymentConflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/payments/{identifier}":{"get":{"operationId":"getPayment","tags":["Vendas"],"summary":"Consultar pagamento","description":"Mesma consulta de `GET /sales/{identifier}`: aceita o `id` da venda (uuid), o código da venda (10 dígitos, com ou sem o prefixo, ou link terminado nele) ou a `external_reference` enviada no pedido, testados nesta ordem.","parameters":[{"name":"identifier","in":"path","required":true,"description":"Id (uuid), código ou referência externa da venda.","schema":{"type":"string"}}],"responses":{"200":{"description":"Venda correspondente ao pagamento","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Sale"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/IpNotAllowed"},"404":{"$ref":"#/components/responses/PaymentNotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}}