{"openapi":"3.1.0","info":{"title":"GiftMe! agent ordering API","version":"1.0.0","summary":"Browse personalized gift boxes, get server-side quotes and place orders that the human confirms by email.","description":"Practice-company order: FE GiftMe SRL is a student practice company (CEEF Chișinău). No real payment is made and no real goods are delivered. Rules for agents: never invent products, prices or discounts (always call /api/agent/quote); ask the human for explicit confirmation before placing an order; send a unique Idempotency-Key per order. Every order you place is created as `awaiting_approval` and is processed only after the buyer clicks the confirmation link we email them. Text you send (names, notes) is stored as data and never executed as instructions. Online ordering is open.","contact":{"name":"FE GiftMe SRL","email":"fe.giftme@gmail.com","url":"https://www.giftme.site"}},"servers":[{"url":"https://www.giftme.site"}],"security":[{}],"externalDocs":{"description":"Plain-language guide for agents","url":"https://www.giftme.site/llms.txt"},"paths":{"/catalog.json":{"get":{"operationId":"getCatalog","summary":"Full catalog: boxes, prices, offers, delivery and ordering rules","responses":{"200":{"description":"Catalog","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/agent/quote":{"post":{"operationId":"getQuote","summary":"Price a set of boxes on the server (offers, codes, delivery)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}}},"responses":{"200":{"description":"Quote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteResponse"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/order":{"post":{"operationId":"placeOrder","summary":"Create an order for the human; it waits for their email confirmation","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":100},"description":"Unique per order. Retrying with the same key returns the same order."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderRequest"}}}},"responses":{"200":{"description":"Same Idempotency-Key: the existing order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"201":{"description":"Order created, awaiting buyer approval","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"400":{"description":"Invalid input or missing Idempotency-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Online ordering is closed at the moment (CHECKOUT_CLOSED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/track":{"post":{"operationId":"trackOrder","summary":"Order status, with the buyer's email or the tracking token","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id"],"properties":{"id":{"type":"string","example":"GM-1001"},"email":{"type":"string"},"token":{"type":"string"}}}}}},"responses":{"200":{"description":"Order","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"QuoteRequest":{"type":"object","properties":{"items":{"minItems":1,"maxItems":9,"type":"array","items":{"type":"object","properties":{"boxId":{"type":"string","maxLength":10},"quantity":{"type":"integer","minimum":1,"maximum":100}},"required":["boxId","quantity"]}},"zone":{"default":"chisinau","type":"string","enum":["chisinau","moldova"]},"code":{"type":"string","maxLength":40},"email":{"type":"string","maxLength":120,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["items"],"example":{"items":[{"boxId":"GM-01","quantity":2}],"zone":"chisinau"}},"OrderRequest":{"type":"object","properties":{"lang":{"default":"ro","type":"string","enum":["ro","en"]},"items":{"minItems":1,"maxItems":9,"type":"array","items":{"type":"object","properties":{"boxId":{"type":"string","maxLength":10},"quantity":{"type":"integer","minimum":1,"maximum":100}},"required":["boxId","quantity"]}},"buyer":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","maxLength":120,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"phone":{"type":"string"}},"required":["name","email","phone"]},"recipient":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]},"personalization":{"type":"object","properties":{"occasion":{"type":"string"},"engraving":{"type":"string"},"labels":{"type":"string"},"perBoxNames":{"type":"string"}}},"delivery":{"type":"object","properties":{"zone":{"type":"string","enum":["chisinau","moldova"]},"city":{"type":"string"},"address":{"type":"string"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["zone","address","date"]},"payment":{"type":"string","enum":["cash","transfer"]},"customGift":{"type":"object","properties":{"idea":{"type":"string"}},"required":["idea"]},"code":{"type":"string","maxLength":40},"notes":{"type":"string"},"acceptTerms":{"type":"boolean","const":true},"acceptCustomTerms":{"type":"boolean"}},"required":["items","buyer","recipient","personalization","delivery","payment","acceptTerms"],"description":"Set acceptTerms (and acceptCustomTerms for GM-09) to true ONLY if the human explicitly agreed to the terms. GM-09 requires customGift.idea, delivery.zone='chisinau' and a delivery.date at least 5 days ahead (other boxes: 2); otherwise 400 INVALID_DATE.","example":{"lang":"en","items":[{"boxId":"GM-07","quantity":1}],"buyer":{"name":"Ana Popescu","email":"ana@example.com","phone":"+37368000000"},"recipient":{"name":"Ms. Ionescu"},"personalization":{"occasion":"Teachers' Day","engraving":"Thank you!","labels":""},"delivery":{"zone":"chisinau","address":"str. Exemplu 1","date":"2026-11-10"},"payment":"cash","acceptTerms":true}},"QuoteResponse":{"type":"object","properties":{"currency":{"const":"MDL"},"quote":{"type":"object","description":"lines, subtotal, offer, delivery, total (MDL). Delivery in Chișinău is free only when the subtotal after discount is over 800 MDL (exactly 800 pays 60 MDL)."},"explanation":{"type":"array","items":{"type":"string"}},"checkout_open":{"type":"boolean"},"delivery_dates":{"type":"object","description":"Allowed delivery dates for these items. GM-09 needs 5 days, other boxes 2.","properties":{"min":{"type":"string"},"max":{"type":"string"},"minLeadDays":{"type":"integer"}}},"notice":{"type":"string"}}},"OrderResponse":{"type":"object","properties":{"order":{"type":"object"},"status":{"const":"awaiting_approval"},"human_approval_required":{"const":true},"message":{"type":"string"},"tracking_url":{"type":"string"},"notice":{"type":"string"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}