{"openapi":"3.1.0","info":{"title":"Nelvra public catalog and checkout handoff","version":"1.1.0","description":"Read public product facts and obtain a checkout link. Preparing a link does not create a payment session, charge the buyer, accept terms, or unlock the private PDF. Complete payment in the buyer-authorized browser using Stripe. Never send card numbers, credentials, login codes or private order data to this API."},"servers":[{"url":"https://nelvra.crevox.io"}],"security":[],"externalDocs":{"description":"Public product facts and purchase instructions","url":"https://nelvra.crevox.io/dla-agentow"},"tags":[{"name":"Catalog","description":"Public product and price discovery"},{"name":"Checkout","description":"Stateless browser handoff; never a charge"}],"paths":{"/api/catalog":{"get":{"operationId":"readCatalog","tags":["Catalog"],"summary":"Read current public offer and sales availability","description":"Amounts are PLN minor units (groszy): 499 means 4.99 PLN. Read billing.type and renewalAmountMinor before asking the buyer to authorize a plan. Responses may be cached for 300 seconds; the checkout server validates the actual catalog again.","responses":{"200":{"description":"Public product catalog. Re-read before purchase.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}}}}},"/api/agent/checkout":{"post":{"operationId":"prepareCheckoutHandoff","tags":["Checkout"],"summary":"Get a browser checkout link without charging the buyer","description":"Present plan, first amount, renewal and terms to the buyer. Open checkoutUrl in the buyer-authorized browser. Enter payment data only in Stripe. Preserve that browser for the order and PDF download. This operation does not authorize payment or provide a download token.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["plan"],"properties":{"plan":{"type":"string","enum":["monthly","once"]},"referralCode":{"type":"string","pattern":"^[a-f0-9]{16}$","description":"Optional valid public partner code."}}},"examples":{"oneTime":{"value":{"plan":"once"}},"monthly":{"value":{"plan":"monthly"}}}}}},"responses":{"200":{"description":"Checkout link, no payment collected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutHandoff"}}}},"400":{"description":"Invalid request. Only documented fields are accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Sales unavailable. Do not promise a purchase.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Catalog":{"type":"object","required":["schema","language","currency","amountsIn","version","canonicalUrl","salesEnabled","freshness","product","offers","seller","links","agentPurchase"],"properties":{"schema":{"const":"nelvra.catalog.v1"},"language":{"const":"pl-PL"},"currency":{"const":"PLN"},"amountsIn":{"const":"minor_units"},"version":{"type":"string","format":"date"},"canonicalUrl":{"type":"string","format":"uri"},"salesEnabled":{"type":"boolean"},"freshness":{"type":"object","required":["contentUpdated","offerCacheSeconds","recheckBeforePurchase"],"properties":{"contentUpdated":{"type":"string","format":"date"},"offerCacheSeconds":{"const":300},"recheckBeforePurchase":{"const":true}}},"product":{"$ref":"#/components/schemas/Product"},"offers":{"type":"array","minItems":2,"maxItems":2,"items":{"oneOf":[{"$ref":"#/components/schemas/MonthlyOffer"},{"$ref":"#/components/schemas/OneTimeOffer"}]}},"seller":{"type":"object","properties":{"name":{"type":["string","null"]},"address":{"type":["string","null"]},"email":{"type":["string","null"]}}},"links":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"agentPurchase":{"type":"object","required":["mode","requiresBuyerAuthorization","acceptsRawCardData"],"properties":{"mode":{"const":"browser_checkout"},"requiresBuyerAuthorization":{"const":true},"requiresPaymentConfirmation":{"const":true},"acceptsRawCardData":{"const":false}}}}},"Product":{"type":"object","required":["id","name","description","informationUrl","language","format","pages","compatibility","independent","notIncluded","delivery"],"properties":{"id":{"const":"nelvra-guide"},"name":{"type":"string"},"description":{"type":"string"},"informationUrl":{"type":"string","format":"uri"},"language":{"const":"pl-PL"},"format":{"const":"application/pdf"},"pages":{"const":5},"independent":{"const":true},"compatibility":{"type":"array","items":{"type":"string"}},"notIncluded":{"type":"array","items":{"type":"string"}},"delivery":{"type":"object","properties":{"method":{"const":"browser_bound_download"},"timing":{"const":"after_verified_payment_webhook"},"emailDelivery":{"const":false},"keepDownloadedCopy":{"const":true}}}}},"MonthlyOffer":{"type":"object","required":["id","name","amountMinor","previousLowest30DaysMinor","discountPercent","discountAppliesTo","billing","checkoutUrl"],"properties":{"name":{"type":"string"},"amountMinor":{"const":499},"previousLowest30DaysMinor":{"const":998},"discountPercent":{"const":50},"checkoutUrl":{"type":"string","format":"uri"},"includes":{"type":"array","items":{"type":"string"}},"id":{"const":"monthly"},"discountAppliesTo":{"const":"first_payment"},"updateFrequencyGuaranteed":{"const":false},"billing":{"type":"object","required":["type","interval","intervalCount","renewalAmountMinor","untilCancelled"],"properties":{"type":{"const":"subscription"},"interval":{"const":"month"},"intervalCount":{"const":1},"renewalAmountMinor":{"const":499},"untilCancelled":{"const":true}}}}},"OneTimeOffer":{"type":"object","required":["id","name","amountMinor","previousLowest30DaysMinor","discountPercent","discountAppliesTo","billing","checkoutUrl"],"properties":{"name":{"type":"string"},"amountMinor":{"const":2499},"previousLowest30DaysMinor":{"const":4998},"discountPercent":{"const":50},"checkoutUrl":{"type":"string","format":"uri"},"includes":{"type":"array","items":{"type":"string"}},"id":{"const":"once"},"discountAppliesTo":{"const":"one_time_purchase"},"futureUpdatesIncluded":{"const":false},"billing":{"type":"object","required":["type"],"properties":{"type":{"const":"one_time"}}}}},"CheckoutHandoff":{"type":"object","required":["status","checkoutUrl","plan","currency","amountMinor","renewalMinor","requiresUserAuthorization","paymentCollected","fulfillment"],"properties":{"status":{"const":"requires_payment"},"checkoutUrl":{"type":"string","format":"uri"},"plan":{"enum":["monthly","once"]},"currency":{"const":"pln"},"amountMinor":{"type":"integer","minimum":0},"renewalMinor":{"type":["integer","null"]},"requiresUserAuthorization":{"const":true},"paymentCollected":{"const":false},"fulfillment":{"const":"browser_bound_download"},"instructions":{"type":"string"}},"oneOf":[{"properties":{"plan":{"const":"monthly"},"amountMinor":{"const":499},"renewalMinor":{"const":499}}},{"properties":{"plan":{"const":"once"},"amountMinor":{"const":2499},"renewalMinor":{"type":"null"}}}]},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}