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: []