{
  "info": {
    "name": "Pearfy API v1",
    "description": "Coleção da API pública v1 da Pearfy (gateway de infoproduto). Autenticação por API key do produtor (pk_live_...) via Bearer ou header x-api-key. Valores monetários em CENTAVOS (BRL). Defina a variável de coleção `api_key` com a sua chave antes de usar.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{api_key}}",
        "type": "string"
      }
    ]
  },
  "variable": [
    {
      "key": "base_url",
      "value": "https://app.pearfy.com/api/v1",
      "type": "string"
    },
    {
      "key": "api_key",
      "value": "pk_live_SUA_CHAVE",
      "type": "string"
    },
    {
      "key": "product_id",
      "value": "",
      "type": "string"
    },
    {
      "key": "offer_id",
      "value": "",
      "type": "string"
    },
    {
      "key": "sale_id",
      "value": "",
      "type": "string"
    }
  ],
  "item": [
    {
      "name": "Autenticação",
      "item": [
        {
          "name": "Trocar API key por access_token",
          "request": {
            "auth": {
              "type": "noauth"
            },
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"grant_type\": \"client_credentials\",\n  \"client_id\": \"{{api_key}}\",\n  \"client_secret\": \"{{api_key}}\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/oauth/token",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "oauth",
                "token"
              ]
            },
            "description": "Fluxo OAuth2 client_credentials. Retorna a própria chave como access_token Bearer (expires_in 86400). Público, sem header de auth. Rate limit: 60 req/min por IP."
          }
        }
      ]
    },
    {
      "name": "Conta",
      "item": [
        {
          "name": "Detalhes da conta",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/account-details",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "account-details"
              ]
            },
            "description": "Dados da conta do produtor dono da chave + escopos concedidos. Não exige escopo, só uma chave válida."
          }
        }
      ]
    },
    {
      "name": "Produtos",
      "item": [
        {
          "name": "Listar produtos",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/products?page_size=50&page_number=1",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "products"
              ],
              "query": [
                {
                  "key": "page_size",
                  "value": "50",
                  "description": "Itens por página (1-100, default 50)."
                },
                {
                  "key": "page_number",
                  "value": "1",
                  "description": "Página 1-based."
                }
              ]
            },
            "description": "Escopo: products. Lista paginada dos produtos do produtor."
          }
        },
        {
          "name": "Criar produto",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"name\": \"Meu Curso\",\n  \"price\": 19700,\n  \"type\": \"curso\",\n  \"description\": \"Descrição opcional\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/products",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "products"
              ]
            },
            "description": "Escopo: products. Cria produto em rascunho + oferta padrão. price em CENTAVOS. type: curso|ebook|mentoria|software|assinatura. Para assinatura, envie payment_type='assinatura' e recurrence (monthly|quarterly|semiannual|annual). O produto nasce SEM forma de entrega: POST nao aceita delivery_types. Defina a entrega por PATCH antes de publicar."
          }
        },
        {
          "name": "Detalhe do produto",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/products/{{product_id}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "products",
                "{{product_id}}"
              ]
            },
            "description": "Escopo: products. Detalhe de um produto do produtor."
          }
        },
        {
          "name": "Editar produto",
          "request": {
            "method": "PATCH",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"delivery_types\": [\n    \"external\"\n  ],\n  \"delivery_url\": \"https://area.exemplo.com\",\n  \"status\": \"publicado\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/products/{{product_id}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "products",
                "{{product_id}}"
              ]
            },
            "description": "Escopo: products. Edita name/description/type/status/delivery_types/delivery_url/delivery_instructions. delivery_types substitui as formas de entrega (pearfy_members, external, email_access, payment_only); array vazio e recusado com 422 e payment_only e exclusivo. status=publicado aplica gates de completude + KYC (422 not_publishable / kyc_required). Mexer na entrega de um produto ja publicado SEM enviar status pode REBAIXAR pra rascunho: a resposta 200 traz unpublished { reason, missing }."
          }
        },
        {
          "name": "Excluir produto",
          "request": {
            "method": "DELETE",
            "header": [],
            "url": {
              "raw": "{{base_url}}/products/{{product_id}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "products",
                "{{product_id}}"
              ]
            },
            "description": "Escopo: products. Soft-delete (deleted_at + status='arquivado'). Retorna {id, deleted:true}."
          }
        }
      ]
    },
    {
      "name": "Ofertas",
      "item": [
        {
          "name": "Listar ofertas do produto",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/products/{{product_id}}/offers",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "products",
                "{{product_id}}",
                "offers"
              ]
            },
            "description": "Escopo: products. Todas as ofertas do produto (sem paginação), padrão primeiro."
          }
        },
        {
          "name": "Criar oferta",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"name\": \"Plano Anual\",\n  \"price\": 49700,\n  \"payment_methods\": [\"pix\", \"card\"],\n  \"installments_max\": 12,\n  \"recurrence_period\": \"annual\",\n  \"is_default\": false\n}"
            },
            "url": {
              "raw": "{{base_url}}/products/{{product_id}}/offers",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "products",
                "{{product_id}}",
                "offers"
              ]
            },
            "description": "Escopo: products. Máx 10 ofertas ativas (422 offer_limit). price em CENTAVOS. Na entrada cartão é 'card' (na saída vira 'credit_card')."
          }
        },
        {
          "name": "Editar oferta",
          "request": {
            "method": "PATCH",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"price\": 24700,\n  \"is_default\": true\n}"
            },
            "url": {
              "raw": "{{base_url}}/products/{{product_id}}/offers/{{offer_id}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "products",
                "{{product_id}}",
                "offers",
                "{{offer_id}}"
              ]
            },
            "description": "Escopo: products. Edita name/price/payment_methods/installments_max/recurrence_limit/is_default/active. recurrence_period NÃO é editável; is_default=false é ignorado."
          }
        },
        {
          "name": "Remover oferta",
          "request": {
            "method": "DELETE",
            "header": [],
            "url": {
              "raw": "{{base_url}}/products/{{product_id}}/offers/{{offer_id}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "products",
                "{{product_id}}",
                "offers",
                "{{offer_id}}"
              ]
            },
            "description": "Escopo: products. Delete físico. Bloqueia remover a última oferta ativa (422 last_offer). Retorna {id, deleted:true}."
          }
        }
      ]
    },
    {
      "name": "Vendas",
      "item": [
        {
          "name": "Listar vendas",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/sales?status=paid&payment_method=pix&page_size=50&page_number=1",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "sales"
              ],
              "query": [
                {
                  "key": "status",
                  "value": "paid",
                  "description": "paid|waiting_payment|refused|refunded|chargedback."
                },
                {
                  "key": "payment_method",
                  "value": "pix",
                  "description": "pix|credit_card|boleto."
                },
                {
                  "key": "product_id",
                  "value": "",
                  "description": "Filtra por produto.",
                  "disabled": true
                },
                {
                  "key": "start_date",
                  "value": "",
                  "description": "created_at >= (ISO 8601).",
                  "disabled": true
                },
                {
                  "key": "end_date",
                  "value": "",
                  "description": "created_at <= (ISO 8601).",
                  "disabled": true
                },
                {
                  "key": "page_size",
                  "value": "50"
                },
                {
                  "key": "page_number",
                  "value": "1"
                }
              ]
            },
            "description": "Escopo: sales. Lista paginada de vendas (formato drop-in). Filtro inválido é ignorado silenciosamente."
          }
        },
        {
          "name": "Detalhe da venda",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/sales/{{sale_id}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "sales",
                "{{sale_id}}"
              ]
            },
            "description": "Escopo: sales. Detalhe da venda com product.name resolvido."
          }
        },
        {
          "name": "Reembolsar venda",
          "request": {
            "method": "POST",
            "header": [],
            "url": {
              "raw": "{{base_url}}/sales/{{sale_id}}/refund",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "sales",
                "{{sale_id}}",
                "refund"
              ]
            },
            "description": "Escopo: sales_refund. Estorna no PSP e marca reembolsado. Síncrono e idempotente. Só vendas aprovadas (senão 422 not_refundable). Retorna {id, status:'refunded'}."
          }
        }
      ]
    },
    {
      "name": "Estatísticas",
      "item": [
        {
          "name": "Estatísticas por período",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/stats?start_date=2026-06-01T00:00:00Z&end_date=2026-06-30T23:59:59Z",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "stats"
              ],
              "query": [
                {
                  "key": "start_date",
                  "value": "2026-06-01T00:00:00Z",
                  "description": "Início (ISO 8601). Default: -30 dias."
                },
                {
                  "key": "end_date",
                  "value": "2026-06-30T23:59:59Z",
                  "description": "Fim (ISO 8601). Default: agora."
                }
              ]
            },
            "description": "Escopo: stats. Agregados do período (sem pedidos de teste). gross_amount e net_amount em CENTAVOS e só de vendas em BRL; by_currency traz os totais de cada moeda."
          }
        }
      ]
    }
  ]
}
