{"openapi":"3.1.0","info":{"title":"Gateway Pix API","version":"1.0.0","description":"API Pix para lojistas e plataformas. Valores em centavos."},"servers":[{"url":"https://soulpay.co"}],"components":{"securitySchemes":{"chave":{"type":"http","scheme":"bearer","description":"gw_live_... (produção) ou gw_sandbox_... (teste)"}},"schemas":{"Charge":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"livemode":{"type":"boolean"},"status":{"type":"string","enum":["pending","paid","expired","canceled","failed","chargeback","refunded"]},"amount_cents":{"type":"integer"},"currency":{"type":"string","example":"BRL"},"description":{"type":["string","null"]},"pix_qr_code":{"type":["string","null"],"description":"Imagem do QR Code (data URI SVG) enquanto a cobrança está pendente"},"pix_copy_paste":{"type":["string","null"]},"payment_url":{"type":"string","format":"uri","description":"Página de pagamento pronta para enviar ao comprador"},"expires_at":{"type":["string","null"],"format":"date-time"},"paid_at":{"type":["string","null"],"format":"date-time"},"fee_cents":{"type":["integer","null"]},"net_cents":{"type":["integer","null"]},"created_at":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}},"security":[{"chave":[]}],"paths":{"/v1/charges":{"post":{"summary":"Criar cobrança Pix","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":100}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount_cents"],"properties":{"amount_cents":{"type":"integer","minimum":100,"maximum":300000},"customer_name":{"type":"string","maxLength":200},"customer_document":{"type":"string","description":"CPF ou CNPJ"},"customer_phone":{"type":"string","description":"DDD + número"},"description":{"type":"string","maxLength":500},"metadata":{"type":"object"}}}}}},"responses":{"200":{"description":"Já existia (mesmo Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Charge"}}}},"201":{"description":"Criada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Charge"}}}},"400":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/charges/{id}":{"get":{"summary":"Consultar cobrança","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Charge"}}}},"404":{"description":"Não encontrada"}}}},"/v1/charges/{id}/simular":{"post":{"summary":"Simular pagamento (só modo de teste)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["paid","failed","canceled","expired"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Charge"}}}}}}},"/v1/webhook":{"get":{"summary":"Ver endereço de webhook","responses":{"200":{"description":"OK"}}},"put":{"summary":"Cadastrar/trocar endereço de webhook (devolve o segredo whsec_ uma única vez)","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"OK"}}},"delete":{"summary":"Desligar avisos","responses":{"200":{"description":"OK"}}}}}}