{"openapi":"3.0.3","info":{"title":"Patitas API","version":"1.0.0","description":"REST API for the Patitas shelter animal sponsorship platform. Connects Colombian animal shelters with monthly sponsors."},"servers":[{"url":"https://apipatitas.devbloom.dev","description":"Production"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Firebase ID Token","description":"Firebase Authentication ID token"}}},"tags":[{"name":"Health","description":"API status"},{"name":"Animals","description":"Animal catalog"},{"name":"Sponsorships","description":"Slot-based monthly sponsorships"},{"name":"Adoptions","description":"Adoption applications and workflow"},{"name":"Bookings","description":"Sponsor visit bookings"},{"name":"Shelters","description":"Shelter management"},{"name":"Webhooks","description":"Payment provider callbacks"}],"paths":{"/health":{"get":{"tags":["Health"],"summary":"Health check","responses":{"200":{"description":"API is running","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"}}}}}}}}},"/animals":{"get":{"tags":["Animals"],"summary":"Browse animal catalog","parameters":[{"name":"shelterId","in":"query","schema":{"type":"string"}},{"name":"species","in":"query","schema":{"type":"string","enum":["dog","cat","other"]}},{"name":"status","in":"query","schema":{"type":"string","enum":["available","sponsored","adopted"]}}],"responses":{"200":{"description":"List of animals"}}},"post":{"tags":["Animals"],"summary":"Create animal","security":[{"BearerAuth":[]}],"responses":{"201":{"description":"Animal created"},"401":{"description":"Unauthorized"}}}},"/animals/{id}":{"get":{"tags":["Animals"],"summary":"Get animal by ID","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Animal details"},"404":{"description":"Not found"}}},"put":{"tags":["Animals"],"summary":"Update animal","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated"},"401":{"description":"Unauthorized"}}}},"/animals/{id}/generate-description":{"post":{"tags":["Animals"],"summary":"Generate AI description from photos (Gemini)","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"AI-generated description"},"401":{"description":"Unauthorized"}}}},"/sponsorships/prepare":{"post":{"tags":["Sponsorships"],"summary":"Reserve slots and prepare Wompi payment","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["animalId","slots"],"properties":{"animalId":{"type":"string"},"slots":{"type":"integer","minimum":1,"maximum":4},"shelterId":{"type":"string"}}}}}},"responses":{"200":{"description":"Wompi widget parameters","content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string"},"signature":{"type":"string"},"amountInCents":{"type":"integer"},"currency":{"type":"string","example":"COP"},"slots":{"type":"integer"},"slotPriceCOP":{"type":"integer"},"shelterId":{"type":"string"}}}}}},"400":{"description":"Validation error (slots unavailable, already sponsored, etc.)"},"401":{"description":"Unauthorized"}}}},"/sponsorships/me":{"get":{"tags":["Sponsorships"],"summary":"Get authenticated user's sponsorships","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"List of sponsorships"},"401":{"description":"Unauthorized"}}}},"/sponsorships/{id}/update-slots":{"put":{"tags":["Sponsorships"],"summary":"Change slot count for an active sponsorship","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["newSlots"],"properties":{"newSlots":{"type":"integer","minimum":1,"maximum":4}}}}}},"responses":{"200":{"description":"Slots updated"},"400":{"description":"Validation error"},"403":{"description":"Forbidden"}}}},"/sponsorships/{id}/cancel":{"put":{"tags":["Sponsorships"],"summary":"Cancel a sponsorship and release slots","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cancelled"},"403":{"description":"Forbidden"}}}},"/sponsorships/{id}/approve":{"put":{"tags":["Sponsorships"],"summary":"Manually approve a pending sponsorship (shelter admin)","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Approved"},"403":{"description":"Forbidden"}}}},"/sponsorships/{id}/admin-cancel":{"put":{"tags":["Sponsorships"],"summary":"Cancel a sponsorship on behalf of sponsor (shelter admin)","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cancelled"},"403":{"description":"Forbidden"}}}},"/adoptions":{"post":{"tags":["Adoptions"],"summary":"Submit adoption application","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["animalId","shelterId"],"properties":{"animalId":{"type":"string"},"shelterId":{"type":"string"},"reason":{"type":"string"},"hasExperience":{"type":"boolean"},"livingConditions":{"type":"string"},"otherPets":{"type":"boolean"}}}}}},"responses":{"201":{"description":"Application submitted"},"401":{"description":"Unauthorized"}}},"get":{"tags":["Adoptions"],"summary":"List adoptions","security":[{"BearerAuth":[]}],"parameters":[{"name":"shelterId","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["applied","under_review","visit_scheduled","approved","rejected","completed","cancelled"]}}],"responses":{"200":{"description":"List of adoptions"},"401":{"description":"Unauthorized"}}}},"/adoptions/{id}":{"put":{"tags":["Adoptions"],"summary":"Advance adoption status","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["applied","under_review","visit_scheduled","approved","rejected","completed","cancelled"]},"reviewNotes":{"type":"string"}}}}}},"responses":{"200":{"description":"Status updated"},"403":{"description":"Forbidden"}}}},"/bookings":{"post":{"tags":["Bookings"],"summary":"Submit a visit booking request","security":[{"BearerAuth":[]}],"responses":{"201":{"description":"Booking requested"},"401":{"description":"Unauthorized"}}},"get":{"tags":["Bookings"],"summary":"List bookings","security":[{"BearerAuth":[]}],"parameters":[{"name":"shelterId","in":"query","schema":{"type":"string"}},{"name":"userId","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["requested","approved","active","completed","cancelled","rejected"]}}],"responses":{"200":{"description":"List of bookings"},"401":{"description":"Unauthorized"}}}},"/bookings/{id}":{"put":{"tags":["Bookings"],"summary":"Update booking status","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated"},"403":{"description":"Forbidden"}}}},"/shelters":{"get":{"tags":["Shelters"],"summary":"List shelters","responses":{"200":{"description":"List of shelters"}}},"post":{"tags":["Shelters"],"summary":"Create shelter","security":[{"BearerAuth":[]}],"responses":{"201":{"description":"Shelter created"},"401":{"description":"Unauthorized"}}}},"/shelters/{id}":{"get":{"tags":["Shelters"],"summary":"Get shelter by ID","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Shelter details"},"404":{"description":"Not found"}}},"put":{"tags":["Shelters"],"summary":"Update shelter","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated"},"403":{"description":"Forbidden"}}}},"/webhooks/wompi":{"post":{"tags":["Webhooks"],"summary":"Wompi payment event callback","description":"Verifies `x-event-checksum` HMAC-SHA256 signature. Handles APPROVED, DECLINED, ERROR, VOIDED transaction statuses.","parameters":[{"name":"x-event-checksum","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Event processed"},"400":{"description":"Invalid signature or payload"}}}}}}