{"openapi":"3.0.3","info":{"title":"QueRegalar.me Agent API","version":"0.2.0","description":"Commerce/gifting connector: create a birthday/wedding/baby-shower wishlist, find something to buy under a budget, reserve a gift without duplicates, or pledge a group contribution. Public giver operations need no token. Owner CRUD requires QREGALARME_TOKEN (password-equivalent). Spanish and English."},"servers":[{"url":"https://queregalar.me"}],"tags":[{"name":"public","description":"Giver tools on a public list (no token)"},{"name":"owner","description":"Owner tools; Bearer QREGALARME_TOKEN"}],"security":[],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"QREGALARME_TOKEN"},"qregalarmeToken":{"type":"apiKey","in":"header","name":"X-QRegalarme-Token"}},"schemas":{"GiftInput":{"type":"object","required":["title"],"properties":{"title":{"type":"string","maxLength":140,"examples":["Cafetera moka"]},"description":{"type":"string","examples":["De acero, tamaño 6 tazas"]},"url":{"type":"string","examples":["https://example.com/producto"]},"image_url":{"type":"string"},"price":{"type":"string","examples":["450"]},"currency":{"type":"string","examples":["MXN"]},"priority":{"type":"string","enum":["alto","normal","bajo"],"default":"normal"},"status":{"type":"string","enum":["available","reserved","received","hidden"],"default":"available"}}},"Gift":{"allOf":[{"$ref":"#/components/schemas/GiftInput"},{"type":"object","properties":{"id":{"type":"integer"},"reserved_by":{"type":"string"},"reserved_note":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}}}]}}},"paths":{"/api/public/lists/{username}":{"get":{"tags":["public"],"operationId":"getWishlist","summary":"Public wishlist (get_wishlist)","description":"Use when the user wants to see a lista de regalos / birthday gift list. Hidden gifts omitted. Do not invent prices.","parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string","example":"ana"}}],"responses":{"200":{"description":"Public list"},"404":{"description":"not_found"}}}},"/api/public/lists/{username}/available":{"get":{"tags":["public"],"operationId":"getAvailableGifts","summary":"Available gifts under budget (qué regalo comprar)","parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string"}},{"name":"max_budget","in":"query","schema":{"type":"number","example":800}},{"name":"currency","in":"query","schema":{"type":"string","example":"MXN"}},{"name":"priority","in":"query","schema":{"type":"string","enum":["alto","normal","bajo"]}}],"responses":{"200":{"description":"Available gifts + contribution buckets"}}}},"/api/public/lists/{username}/contribution-options":{"get":{"tags":["public"],"operationId":"getContributionOptions","summary":"Group gifts that accept pledges","parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string"}},{"name":"max_budget","in":"query","schema":{"type":"number"}},{"name":"currency","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Contribution options"}}}},"/gifts/{id}/reserve":{"post":{"tags":["public"],"operationId":"reserveGift","summary":"Apartar un regalo (no duplicates)","description":"Confirm with the user first. 409 if already reserved. Not a payment.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reserved_by"],"properties":{"reserved_by":{"type":"string"},"reserved_note":{"type":"string"}}}}}},"responses":{"200":{"description":"Reserved"},"409":{"description":"already_reserved"}}}},"/api/public/users/{username}/gifts/{giftId}/contributions":{"post":{"tags":["public"],"operationId":"pledgeContribution","summary":"Pledge toward a group gift (not a payment)","parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string"}},{"name":"giftId","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["contributor_name","amount"],"properties":{"contributor_name":{"type":"string"},"amount":{},"currency":{"type":"string"}}}}}},"responses":{"201":{"description":"Pledged"},"409":{"description":"amount_exceeds_remaining or already_fully_pledged"}}}},"/api/public/draft-group-message":{"post":{"tags":["public"],"operationId":"draftGroupMessage","summary":"Draft WhatsApp share text","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["username","gift_ids"],"properties":{"username":{"type":"string"},"gift_ids":{"type":"array","items":{"type":"integer"}},"buyer_names":{"type":"array","items":{"type":"string"}},"budget":{"type":"string"},"note":{"type":"string"}}}}}},"responses":{"200":{"description":"Template"}}}},"/api/public/draft-contribution-message":{"post":{"tags":["public"],"operationId":"draftContributionMessage","summary":"Draft WhatsApp text for a group pledge","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["username","gift_id"],"properties":{"username":{"type":"string"},"gift_id":{"type":"integer"},"contributor_name":{"type":"string"},"amount":{}}}}}},"responses":{"200":{"description":"Template"}}}},"/api/agent/me":{"get":{"tags":["owner"],"operationId":"getCurrentUser","security":[{"bearerAuth":[]}],"summary":"Ver dueño del token","responses":{"200":{"description":"Usuario autenticado"},"401":{"description":"Token inválido"}}}},"/api/agent/gifts":{"get":{"tags":["owner"],"operationId":"listGifts","security":[{"bearerAuth":[]}],"summary":"Listar regalos del owner","responses":{"200":{"description":"Lista de regalos"}}},"post":{"tags":["owner"],"operationId":"createGift","security":[{"bearerAuth":[]}],"summary":"Crear regalo / create a wishlist item","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftInput"}}}},"responses":{"201":{"description":"Regalo creado"},"400":{"description":"title_required"}}}},"/api/agent/gifts/{id}":{"patch":{"tags":["owner"],"operationId":"updateGift","security":[{"bearerAuth":[]}],"summary":"Actualizar regalo o status","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftInput"}}}},"responses":{"200":{"description":"Regalo actualizado"},"404":{"description":"No encontrado"}}},"delete":{"tags":["owner"],"operationId":"deleteGift","security":[{"bearerAuth":[]}],"summary":"Borrar regalo","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Borrado o no existente"}}}}}}