openapi: 3.1.0 info: title: zipmend API description: Documentation of the zipmend api version: 1.0.0 termsOfService: https://zipmend.com/agb/ contact: email: sales@zipmend.com url: https://redocly.com/docs/cli/ license: name: MIT url: https://opensource.org/license/mit/ servers: - url: https://app.zipmend.com/api/v3 description: Production server (uses live data) - url: https://sandbox.zipmend.com/api/v3 description: Sandbox server (uses test data) paths: /cities: get: summary: Get cities description: Get cities by country code and search term operationId: getCities tags: - Cities parameters: - $ref: '#/components/parameters/Country' - $ref: '#/components/parameters/Query' responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/GetCitiesResponse' examples: default_example: $ref: '#/components/examples/GetCitiesResponseExample' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' /price: post: summary: Generate a price description: Generate a price operationId: createPrice tags: - Price requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePriceRequest' examples: default_example: $ref: '#/components/examples/CreatePriceRequestExample' responses: '201': description: Created. content: application/json: schema: $ref: '#/components/schemas/CreatePriceResponse' examples: default_example: $ref: '#/components/examples/CreatePriceResponseExample' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' /booking/publish: post: summary: Publish a booking description: Endpoint for publish a booking operationId: publishBooking tags: - Booking requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PublishBookingRequest' examples: default_example: $ref: '#/components/examples/PublishBookingRequestExample' responses: '201': description: Created. content: application/json: schema: $ref: '#/components/schemas/SpecialEventResponse' examples: default_example: $ref: '#/components/examples/CreateSpecialEventResponseExample' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' components: schemas: Name: type: string example: Hamburg ZipCode: type: string example: 8051 CP Country: type: string example: NL Date: type: string format: date example: '2024-07-19T08:00:00+01:00' Email: description: Email address for ticket purchaser. type: string format: email example: museum-lover@example.com Phone: description: Phone number for the ticket purchaser (optional). type: string example: +1(234)-567-8910 BuyMuseumTicketsRequest: description: Request payload used for purchasing museum tickets. type: object properties: eventId: description: >- Unique identifier for a special event. Required if purchasing tickets for the museum's special events. $ref: '#/components/schemas/EventId' ticketDate: description: Date that the ticket is valid for. $ref: '#/components/schemas/Date' email: $ref: '#/components/schemas/Email' phone: $ref: '#/components/schemas/Phone' required: - ticketType - ticketDate - email TicketMessage: description: Confirmation message after a ticket purchase. type: string example: Museum general entry ticket purchased TicketId: description: Unique identifier for museum ticket. Generated when purchased. type: string format: uuid example: a54a57ca-36f8-421b-a6b4-2e8f26858a4c TicketConfirmation: description: Unique confirmation code used to verify ticket purchase. type: string example: ticket-event-a98c8f-7eb12 BuyMuseumTicketsResponse: description: Details for a museum ticket after a successful purchase. type: object properties: message: $ref: '#/components/schemas/TicketMessage' eventName: $ref: '#/components/schemas/EventName' ticketId: $ref: '#/components/schemas/TicketId' ticketDate: description: Date the ticket is valid for. $ref: '#/components/schemas/Date' confirmationCode: $ref: '#/components/schemas/TicketConfirmation' required: - message - ticketId - ticketType - ticketDate - confirmationCode GetTicketCodeResponse: description: Image of a ticket with a QR code used for museum or event entry. type: string format: binary GetMuseumHoursResponse: description: List of museum operating hours for consecutive days. type: array items: $ref: '#/components/schemas/MuseumDailyHours' GetCitiesResponse: description: Details for a museum ticket after a successful purchase. type: object properties: message: type: string example: Success! data: type: array items: $ref: '#/components/schemas/City' required: - message - data City: description: List of museum operating hours for consecutive days. type: object properties: name: $ref: '#/components/schemas/Name' zip_code: $ref: '#/components/schemas/ZipCode' country: $ref: '#/components/schemas/Country' Item: description: Goods description type: object properties: quantity: type: integer example: 3 length: type: integer example: 120 width: type: integer example: 100 height: type: integer example: 80 weight: type: integer example: 320 CreatePriceRequest: description: Values for generating price type: object properties: items: type: array items: $ref: '#/components/schemas/Item' loadings: type: array items: $ref: '#/components/schemas/City' unloadings: type: array items: $ref: '#/components/schemas/City' loading_date: type: string $ref: '#/components/schemas/Date' required: - loadings - unloadings - loading_date SpotTimes: type: object properties: start: type: string $ref: '#/components/schemas/Date' example: '2024-09-19T09:00:00+02:00' end: type: string $ref: '#/components/schemas/Date' example: '2024-09-19T09:00:00+02:00' ExtraService: type: object properties: label: type: string example: loadingThroughDriver cost: type: number example: 29.9 SpotAddresses: type: object properties: company_name: type: string example: zipmend GmbH first_name: type: string example: John last_name: type: string example: Smith address_line_1: type: string example: Große Reichenstraße 27 address_line_2: type: string example: Floor 3 country: type: string example: DE zip: type: string example: '28779' city: type: string example: Hamburg phone: type: string $ref: '#/components/schemas/Phone' example: '+491234567890' reference_number: type: string example: Ref12345 dates: type: array items: $ref: '#/components/schemas/SpotTimes' PriceObject: description: Price Object contains all values for a specific vehicle type: object properties: vehicle_type: type: integer example: 11 value: type: number example: 407.15 driving_time: type: integer example: 23575 estimated_loading_times: type: array items: $ref: '#/components/schemas/SpotTimes' estimated_unloading_times: type: array items: $ref: '#/components/schemas/SpotTimes' available_extra_services: type: array items: $ref: '#/components/schemas/ExtraService' CreatePriceResponse: description: Details for a museum ticket after a successful purchase. type: object properties: message: type: string example: Success! data: type: array items: $ref: '#/components/schemas/PriceObject' required: - message - data PublishBookingRequest: type: object properties: items: type: array items: $ref: '#/components/schemas/Item' vehicle_type: type: integer example: 11 additional_information: type: string example: Attention highly flammable goods loadings: type: array items: $ref: '#/components/schemas/SpotAddresses' unloadings: type: array items: $ref: '#/components/schemas/SpotAddresses' MuseumDailyHours: description: Daily operating hours for the museum. type: object properties: date: description: Date the operating hours apply to. $ref: '#/components/schemas/Date' example: '2024-12-31' timeOpen: type: string pattern: ^([01]\d|2[0-3]):?([0-5]\d)$ description: >- Time the museum opens on a specific date. Uses 24 hour time format (`HH:mm`). example: '09:00' timeClose: description: >- Time the museum closes on a specific date. Uses 24 hour time format (`HH:mm`). type: string pattern: ^([01]\d|2[0-3]):?([0-5]\d)$ example: '18:00' required: - date - timeOpen - timeClose EventId: description: Identifier for a special event. type: string format: uuid example: 3be6453c-03eb-4357-ae5a-984a0e574a54 EventName: type: string description: Name of the special event. example: Pirate Coding Workshop EventLocation: type: string description: Location where the special event is held. example: Computer Room EventDescription: type: string description: Description of the special event. example: >- Captain Blackbeard shares his love of the C...language. And possibly Arrrrr (R lang). EventDates: type: array items: $ref: '#/components/schemas/Date' description: List of planned dates for the special event. EventPrice: description: Price of a ticket for the special event. type: number format: float example: 25 CreateSpecialEventRequest: description: Request payload for creating new special events at the museum. type: object properties: name: $ref: '#/components/schemas/EventName' location: $ref: '#/components/schemas/EventLocation' eventDescription: $ref: '#/components/schemas/EventDescription' dates: $ref: '#/components/schemas/EventDates' price: $ref: '#/components/schemas/EventPrice' required: - name - location - eventDescription - dates - price UpdateSpecialEventRequest: description: >- Request payload for updating an existing special event. Only included fields are updated in the event. type: object properties: name: $ref: '#/components/schemas/EventName' location: $ref: '#/components/schemas/EventLocation' eventDescription: $ref: '#/components/schemas/EventDescription' dates: $ref: '#/components/schemas/EventDates' price: $ref: '#/components/schemas/EventPrice' ListSpecialEventsResponse: description: List of upcoming special events. type: array items: $ref: '#/components/schemas/SpecialEventResponse' SpecialEventResponse: description: Information about a special event. type: object properties: eventId: $ref: '#/components/schemas/EventId' name: $ref: '#/components/schemas/EventName' location: $ref: '#/components/schemas/EventLocation' eventDescription: $ref: '#/components/schemas/EventDescription' dates: $ref: '#/components/schemas/EventDates' price: $ref: '#/components/schemas/EventPrice' required: - eventId - name - location - eventDescription - dates - price Error: type: object properties: type: type: string example: object title: type: string example: Validation failed securitySchemes: MuseumPlaceholderAuth: type: http scheme: basic examples: BuyGeneralTicketsRequestExample: summary: General entry ticket value: ticketType: general ticketDate: '2023-09-07' email: todd@example.com BuyEventTicketsRequestExample: summary: Special event ticket value: ticketType: general eventId: dad4bce8-f5cb-4078-a211-995864315e39 ticketDate: '2023-09-05' email: todd@example.com BuyGeneralTicketsResponseExample: summary: General entry ticket value: message: Museum general entry ticket purchased ticketId: 382c0820-0530-4f4b-99af-13811ad0f17a ticketType: general ticketDate: '2023-09-07' confirmationCode: ticket-general-e5e5c6-dce78 BuyEventTicketsResponseExample: summary: Special event ticket value: message: Museum special event ticket purchased ticketId: b811f723-17b2-44f7-8952-24b03e43d8a9 eventName: Mermaid Treasure Identification and Analysis ticketType: event ticketDate: '2023-09-05' confirmationCode: ticket-event-9c55eg-8v82a CreatePriceRequestExample: description: Test 123 value: items: - quantity: 1 length: 230 width: 120 height: 80 weight: 320 loadings: - zip: '28779' city: Bremen country: DE unloadings: - zip: '28779' city: Bremen country: DE loading_date: '2024-07-19T08:00:00+01:00' CreatePriceResponseExample: summary: Example price response value: message: Success! data: - vehicle_type: 11 value: 407.15 driving_time: 23575 estimated_loading_times: - start: '2024-09-19T09:00:00+02:00' end: '2024-09-19T10:00:00+02:00' estimated_unloading_times: - start: '2024-09-19T14:00:00+02:00' end: '2024-09-19T15:00:00+02:00' available_extra_services: - label: loadingThroughDriver cost: 29.9 - label: unloadingThroughDriver cost: 29.9 - vehicle_type: 12 value: 450 driving_time: 24000 estimated_loading_times: - start: '2024-09-19T09:30:00+02:00' end: '2024-09-19T10:30:00+02:00' estimated_unloading_times: - start: '2024-09-19T14:30:00+02:00' end: '2024-09-19T15:30:00+02:00' available_extra_services: - label: loadingThroughDriver cost: 34.9 - label: unloadingThroughDriver cost: 34.9 PublishBookingRequestExample: summary: Example booking request value: items: - name: Tannenbaum quantity: 22 length: 120 width: 100 height: 80 weight: 320 vehicle_type: 13 additional_information: Attention highly flammable goods loadings: - company_name: Acme Corporation first_name: John last_name: Smith address_line_1: Karl-Marx-Strasse 1 address_line_2: Tor 2 country: DE zip: '28779' city: Bremen phone: '+49123456789' reference_number: '123456789' dates: - start: '2024-07-20T07:00:00+01:00' end: '2024-07-20T10:00:00+01:00' unloadings: - company_name: zipmend GmbH first_name: Max last_name: Mustermann address_line_1: Steintorweg 4 address_line_2: Tor 2 country: DE zip: '12247' city: Berlin phone: '+49123456789' reference_number: '123456789' dates: - start: '2024-07-20T13:50:00+01:00' end: '2024-07-20T16:50:00+01:00' CreateSpecialEventRequestExample: summary: Create special event value: name: Mermaid Treasure Identification and Analysis location: Under the seaaa 🦀 🎶 🌊. eventDescription: >- Join us as we review and classify a rare collection of 20 thingamabobs, gadgets, gizmos, whoosits, and whatsits, kindly donated by Ariel. dates: - '2023-09-05' - '2023-09-08' price: 0 CreateSpecialEventResponseExample: summary: Special event created value: eventId: dad4bce8-f5cb-4078-a211-995864315e39 name: Mermaid Treasure Identification and Analysis location: Under the seaaa 🦀 🎶 🌊. eventDescription: >- Join us as we review and classify a rare collection of 20 thingamabobs, gadgets, gizmos, whoosits, and whatsits, kindly donated by Ariel. dates: - '2023-09-05' - '2023-09-08' price: 30 GetSpecialEventResponseExample: summary: Get special event value: eventId: 6744a0da-4121-49cd-8479-f8cc20526495 name: Time Traveler Tea Party location: Temporal Tearoom eventDescription: Sip tea with important historical figures. dates: - '2023-11-18' - '2023-11-25' - '2023-12-02' price: 60 GetCitiesResponseExample: summary: List of cities value: message: Success! data: - name: Hattem zip_code: 8051 CP country: NL - name: Hattem zip_code: 8051 NL country: NL - name: Hattem zip_code: 8051 AK country: NL - name: Hattem zip_code: 8051 AW country: NL ListSpecialEventsResponseExample: summary: List of special events value: - eventId: f3e0e76e-e4a8-466e-ab9c-ae36c15b8e97 name: Sasquatch Ballet location: Seattle... probably eventDescription: >- They're big, they're hairy, but they're also graceful. Come learn how the biggest feet can have the lightest touch. dates: - '2023-12-15' - '2023-12-22' price: 40 - eventId: 2f14374a-9c65-4ee5-94b7-fba66d893483 name: Solar Telescope Demonstration location: Far from the sun. eventDescription: Look at the sun without going blind! dates: - '2023-09-07' - '2023-09-14' price: 50 - eventId: 6aaa61ba-b2aa-4868-b803-603dbbf7bfdb name: Cook like a Caveman location: Fire Pit on East side eventDescription: Learn to cook on an open flame. dates: - '2023-11-10' - '2023-11-17' - '2023-11-24' price: 5 - eventId: 602b75e1-5696-4ab8-8c7a-f9e13580f910 name: Underwater Basket Weaving location: Rec Center Pool next door. eventDescription: Learn to weave baskets underwater. dates: - '2023-09-12' - '2023-09-15' price: 15 - eventId: dad4bce8-f5cb-4078-a211-995864315e39 name: Mermaid Treasure Identification and Analysis location: Room Sea-12 eventDescription: >- Join us as we review and classify a rare collection of 20 thingamabobs, gadgets, gizmos, whoosits, and whatsits — kindly donated by Ariel. dates: - '2023-09-05' - '2023-09-08' price: 30 - eventId: 6744a0da-4121-49cd-8479-f8cc20526495 name: Time Traveler Tea Party location: Temporal Tearoom eventDescription: Sip tea with important historical figures. dates: - '2023-11-18' - '2023-11-25' - '2023-12-02' price: 60 - eventId: 3be6453c-03eb-4357-ae5a-984a0e574a54 name: Pirate Coding Workshop location: Computer Room eventDescription: >- Captain Blackbeard shares his love of the C...language. And possibly Arrrrr (R lang). dates: - '2023-10-29' - '2023-10-30' - '2023-10-31' price: 45 - eventId: 9d90d29a-2af5-4206-97d9-9ea9ceadcb78 name: Llama Street Art Through the Ages location: Auditorium eventDescription: Llama street art?! Alpaca my bags -- let's go! dates: - '2023-10-29' - '2023-10-30' - '2023-10-31' price: 45 - eventId: a3c7b2c4-b5fb-4ef7-9322-00a919864957 name: The Great Parrot Debate location: Outdoor Amphitheatre eventDescription: See leading parrot minds discuss important geopolitical issues. dates: - '2023-11-03' - '2023-11-10' price: 35 - eventId: b92d46b7-4c5d-422b-87a5-287767e26f29 name: Eat a Bunch of Corn location: Cafeteria eventDescription: We accidentally bought too much corn. Please come eat it. dates: - '2023-11-10' - '2023-11-17' - '2023-11-24' price: 5 UpdateSpecialEventRequestExample: summary: Update special event request value: location: On the beach. price: 15 UpdateSpecialEventResponseExample: summary: Update special event value: eventId: dad4bce8-f5cb-4078-a211-995864315e39 name: Mermaid Treasure Identification and Analysis location: On the beach. eventDescription: >- Join us as we review and classify a rare collection of 20 thingamabobs, gadgets, gizmos, whoosits, and whatsits, kindly donated by Ariel. dates: - '2023-09-05' - '2023-09-08' price: 15 GetMuseumHoursResponseExample: summary: Get hours response value: - date: '2023-09-11' timeOpen: '09:00' timeClose: '18:00' - date: '2023-09-12' timeOpen: '09:00' timeClose: '18:00' - date: '2023-09-13' timeOpen: '09:00' timeClose: '18:00' - date: '2023-09-14' timeOpen: '09:00' timeClose: '18:00' - date: '2023-09-15' timeOpen: '10:00' timeClose: '16:00' - date: '2023-09-18' timeOpen: '09:00' timeClose: '18:00' - date: '2023-09-19' timeOpen: '09:00' timeClose: '18:00' - date: '2023-09-20' timeOpen: '09:00' timeClose: '18:00' - date: '2023-09-21' timeOpen: '09:00' timeClose: '18:00' - date: '2023-09-22' timeOpen: '10:00' timeClose: '16:00' parameters: PaginationPage: name: page in: query description: Page number to retrieve. schema: type: integer default: 1 example: 2 PaginationLimit: name: limit in: query description: Number of days per page. schema: type: integer default: 10 maximum: 30 example: 15 EventId: name: eventId in: path description: Identifier for a special event. required: true schema: type: string format: uuid example: dad4bce8-f5cb-4078-a211-995864315e39 StartDate: name: startDate in: query description: >- Starting date to retrieve future operating hours from. Defaults to today's date. schema: type: string format: date example: '2023-02-23' EndDate: name: endDate in: query description: >- End of a date range to retrieve special events for. Defaults to 7 days after `startDate`. schema: type: string format: date example: '2023-04-18' TicketId: name: ticketId in: path description: >- Identifier for a ticket to a museum event. Used to generate ticket image. required: true schema: type: string format: uuid example: a54a57ca-36f8-421b-a6b4-2e8f26858a4c Country: name: country in: query required: true schema: type: string example: NL Query: name: query in: query schema: type: string example: 8051 CP Hattem responses: BadRequest: description: Bad request. content: application/problem+json: schema: $ref: '#/components/schemas/Error' NotFound: description: Not found. content: application/problem+json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Unauthorized. content: application/problem+json: schema: $ref: '#/components/schemas/Error' tags: - name: Cities description: Informations about cities and zipcodes - name: Price description: Get price calculated by the - name: Booking description: Museum tickets for general entrance or special events. security: - MuseumPlaceholderAuth: []