Convelio Shipping API

openapi: 3.2.0
info:
  title: Convelio Public Shipping API
  version: '2.0'
  contact:
    name: Convelio API Team
    email: api@convelio.com
    url: https://www.convelio.com
  termsOfService: https://www.convelio.com/fr/termes/
  license:
    name: MIT
    url: https://www.convelio.com/fr/termes/
  description: '**This document describes the current version (2.0) of the Shipping API.**


    The Convelio API is organized around REST. Our API has predictable resource-oriented urls, accept and return json-encoded requests and

    responses. It also use standard HTTP response codes, authentication, and verbs.


    You can use the Convelio API in sandbox mode, which does not affect your live data or interact with the live api.

    The API key you use to authenticate the request determine whether the request is live mode or sandbox mode.


    # API key

    Convelio authenticates your API requests using your account’s API key. If you do not include your key when making an API request,

    or use one that is incorrect, Convelio returns an error.


    Your API key has a *Secret* type, prefixed by *sk*, and should be kept confidential and only stored on your own servers.

    Your account’s secret API key can perform any API request to Convelio without restriction.


    There are also two **modes** for your API key: *live* and *test*.

    - *live* key can only be used on our production server.

    - *test* key can only be used on our sandbox server.


    <b>Example of key by modes</b>


    | **Type** \\ **Mode** | Test                              | Live                              |

    |---------------------|-----------------------------------|-----------------------------------|

    | Secret              | REDACTED_STRIPE_KEY | REDACTED_STRIPE_KEY |


    <b>Obtaining your API key</b>


    To get your API key, please send your request at api@convelio.com.'
  x-logo:
    url: public/assets/icons/convelio-black-spaced.svg
    altText: Convelio logo
servers:
- url: https://api.sandbox.convelio.com/v2
  description: Sandbox
- url: https://api.convelio.com/v2
  description: Production
security:
- secret_token: []
tags:
- name: shipping
  x-displayName: Shipping API
  description: Shipping API allow you to request a shipping estimate from our system
paths:
  /shipping/estimate/price:
    post:
      summary: Shipment estimation
      description: Use this endpoint to obtain a first estimation for a shipment.
      operationId: estimateShippingPrice
      tags:
      - shipping
      security:
      - secret_token: []
      parameters:
      - $ref: '#/components/parameters/currency-code'
      - $ref: '#/components/parameters/json-content-type'
      - $ref: '#/components/parameters/accept'
      requestBody:
        $ref: '#/components/requestBodies/estimate-price'
      responses:
        '200':
          description: Shipment rate estimation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/price'
        '401':
          $ref: '#/components/responses/unauthorized'
        '422':
          $ref: '#/components/responses/unprocessable-entity'
          description: No shipment estimation available for given request / ValidationFailed
        '500':
          $ref: '#/components/responses/internal-server-error'
  /shipping/quote:
    post:
      summary: Request a quote
      description: Get a quote from Convelio. An operations representative will get in contact with you if necessary.
      operationId: createShippingQuote
      tags:
      - shipping
      security:
      - secret_token: []
      parameters:
      - $ref: '#/components/parameters/currency-code'
      - $ref: '#/components/parameters/json-content-type'
      - $ref: '#/components/parameters/accept'
      requestBody:
        $ref: '#/components/requestBodies/quote'
      responses:
        '201':
          description: Quote created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/quote'
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '422':
          $ref: '#/components/responses/unprocessable-entity'
        '500':
          $ref: '#/components/responses/internal-server-error'
  /shipping/quote/{quoteId}:
    parameters:
    - $ref: '#/components/parameters/quote-id'
    - $ref: '#/components/parameters/json-content-type'
    - $ref: '#/components/parameters/accept'
    get:
      summary: Get quote
      description: Retrieve a quote by its ID.
      operationId: getShippingQuote
      tags:
      - shipping
      security:
      - secret_token: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/quote'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not-found'
        '422':
          $ref: '#/components/responses/unprocessable-entity'
        '500':
          $ref: '#/components/responses/internal-server-error'
  /shipping/order:
    post:
      summary: Create an Order
      description: Create an order for given Quote ID.
      operationId: createShippingOrder
      tags:
      - shipping
      security: []
      parameters:
      - $ref: '#/components/parameters/currency-code'
      - $ref: '#/components/parameters/json-content-type'
      - $ref: '#/components/parameters/accept'
      requestBody:
        $ref: '#/components/requestBodies/order'
      responses:
        '201':
          description: Order Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/order'
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '422':
          $ref: '#/components/responses/unprocessable-entity'
        '500':
          $ref: '#/components/responses/internal-server-error'
components:
  requestBodies:
    quote:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/quote-create'
        application/vnd.convelio-shipping.v2+json:
          schema:
            $ref: '#/components/schemas/quote-create'
    order:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/order-create'
        application/vnd.convelio-shipping.v2+json:
          schema:
            $ref: '#/components/schemas/order-create'
    estimate-price:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/shipment-estimation'
        application/vnd.convelio-shipping.v2+json:
          schema:
            $ref: '#/components/schemas/shipment-estimation'
  responses:
    internal-server-error:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/http-error'
          example:
            type: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
            title: Internal Server Error
            status: 500
            detail: There is an internal problem on our server.
    forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/http-error'
          example:
            type: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
            title: Forbidden
            status: 403
            detail: You are authenticated but not allowed to execute the action.
    unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/http-error'
          example:
            type: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
            title: Unauthorized
            status: 401
            detail: Token not found.
    bad-request:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/http-error'
          example:
            type: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
            title: Bad Request
            status: 400
            detail: Bad Request.
    not-found:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/http-error'
          example:
            type: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
            title: Not Found
            status: 404
            detail: Page not found.
    unprocessable-entity:
      description: Unprocessable Entity
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/http-unprocessable-entity-error'
          example:
            type: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
            title: Unprocessable Entity
            status: 422
            detail: The server was unable to process the request.
            validation_messages:
              '{field_name}':
                '{error_title}': 'Invalid delivery type. Valid values are: curbside, white_glove'
  parameters:
    quote-id:
      name: quoteId
      description: Quote ID
      in: path
      schema:
        type: string
      required: true
    json-content-type:
      name: Content-Type
      description: Content-Type header should be sent and should be `application/vnd.convelio-shipping.v2+json`
      in: header
      schema:
        type: string
        enum:
        - application/json
        - application/vnd.convelio-shipping.v2+json
        default: application/json
    currency-code:
      name: currency
      description: Currency to use for the response. Accepted currencies are EUR, USD and GBP.
      in: query
      schema:
        $ref: '#/components/schemas/currency-code'
    accept:
      description: Accept header should be sent and should be `application/json`
      name: Accept
      in: header
      schema:
        type: string
        enum:
        - '*/*'
        - application/json
        default: application/json
  schemas:
    quote-status:
      title: Quote Status
      x-tags:
      - Enums
      description: '- created: The API successfully returned an instant shipping price and the quote has been created in Convelio''s system.

        - processing: The API could not return an instant shipping price for some reason (geography, over-sized item, high commercial value) and Convelio''s Operational team is working on providing a Custom Quote within 24h.'
      readOnly: true
      type: string
      enum:
      - created
      - processing
    measurement-system:
      title: MeasurementSystem
      description: Unit system used for the pickup.
      type: string
      enum:
      - us
      - metric
    quote-create:
      title: RequestBodyCreateShippingQuote
      type: object
      properties:
        delivery:
          $ref: '#/components/schemas/delivery'
          required:
          - contact
        shipping_speed:
          $ref: '#/components/schemas/shipping-speed'
        direct_label_request:
          $ref: '#/components/schemas/direct-label-request'
        contract_insurance:
          $ref: '#/components/schemas/contract-insurance'
        pickups:
          type: array
          items:
            $ref: '#/components/schemas/pickup'
            required:
            - contacts
        customer_email:
          type: string
          maxLength: 255
          description: Add a customer email address to receive the quote by email.
          format: email
          example: person@example.com
        customer_reference_number:
          type: string
          maxLength: 255
        additional_info:
          type: string
          maxLength: 8000
      required:
      - delivery
      - shipping_speed
      - pickups
    direct-label-request:
      title: DirectLabelRequest
      x-tags:
      - Enums
      description: 'Direct label request.

        Possible values:

        - cheapest_option: API will return direct label prices if available and if direct label is the cheapest option.

        - direct_label_only: API will always consider the direct label option if available and return direct label prices accordingly.

        - direct_label_excluded: API will never consider the direct label option and therefore will never return direct label prices.'
      type: string
      enum:
      - cheapest_option
      - direct_label_only
      - direct_label_excluded
      default: cheapest_option
    billing-details:
      title: BillingDetails
      type: object
      properties:
        address:
          $ref: '#/components/schemas/address'
        name:
          type: string
          maxLength: 255
          example: Art center
        email:
          type: string
          maxLength: 255
          format: email
          example: art@center.org
        phone:
          $ref: '#/components/schemas/phone'
        vat_number:
          type: string
          maxLength: 255
          example: GB12345697
        customer_reference_number:
          type: string
          maxLength: 255
          example: REF123456
        eori_number:
          type: string
          maxLength: 255
          example: DE 1234567890 8
      required:
      - name
      - email
      - phone
      - address
    country-code:
      title: CountryCode
      x-tags:
      - Enums
      description: 'The country code according to

        [iso-3166-1-alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)

        '
      type: string
      example: FR
      enum:
      - AD
      - AE
      - AF
      - AG
      - AI
      - AL
      - AM
      - AO
      - AQ
      - AR
      - AS
      - AT
      - AU
      - AW
      - AX
      - AZ
      - BA
      - BB
      - BD
      - BE
      - BF
      - BG
      - BH
      - BI
      - BJ
      - BL
      - BM
      - BN
      - BO
      - BQ
      - BR
      - BS
      - BT
      - BV
      - BW
      - BY
      - BZ
      - CA
      - CC
      - CD
      - CF
      - CG
      - CH
      - CI
      - CK
      - CL
      - CM
      - CN
      - CO
      - CR
      - CU
      - CV
      - CW
      - CX
      - CY
      - CZ
      - DE
      - DJ
      - DK
      - DM
      - DO
      - DZ
      - EC
      - EE
      - EG
      - EH
      - ER
      - ES
      - ET
      - FI
      - FJ
      - FK
      - FM
      - FO
      - FR
      - GA
      - GB
      - GD
      - GE
      - GF
      - GG
      - GH
      - GI
      - GL
      - GM
      - GN
      - GP
      - GQ
      - GR
      - GS
      - GT
      - GU
      - GW
      - GY
      - HK
      - HM
      - HN
      - HR
      - HT
      - HU
      - ID
      - IE
      - IL
      - IM
      - IN
      - IO
      - IQ
      - IR
      - IS
      - IT
      - JE
      - JM
      - JO
      - JP
      - KE
      - KG
      - KH
      - KI
      - KM
      - KN
      - KP
      - KR
      - KW
      - KY
      - KZ
      - LA
      - LB
      - LC
      - LI
      - LK
      - LR
      - LS
      - LT
      - LU
      - LV
      - LY
      - MA
      - MC
      - MD
      - ME
      - MF
      - MG
      - MH
      - MK
      - ML
      - MM
      - MN
      - MO
      - MP
      - MQ
      - MR
      - MS
      - MT
      - MU
      - MV
      - MW
      - MX
      - MY
      - MZ
      - NA
      - NC
      - NE
      - NF
      - NG
      - NI
      - NL
      - 'NO'
      - NP
      - NR
      - NU
      - NZ
      - OM
      - PA
      - PE
      - PF
      - PG
      - PH
      - PK
      - PL
      - PM
      - PN
      - PR
      - PS
      - PT
      - PW
      - PY
      - QA
      - RE
      - RO
      - RS
      - RU
      - RW
      - SA
      - SB
      - SC
      - SD
      - SE
      - SG
      - SH
      - SI
      - SJ
      - SK
      - SL
      - SM
      - SN
      - SO
      - SR
      - SS
      - ST
      - SV
      - SX
      - SY
      - SZ
      - TC
      - TD
      - TF
      - TG
      - TH
      - TJ
      - TK
      - TL
      - TM
      - TN
      - TO
      - TR
      - TT
      - TV
      - TW
      - TZ
      - UA
      - UG
      - UM
      - US
      - UY
      - UZ
      - VA
      - VC
      - VE
      - VG
      - VI
      - VN
      - VU
      - WF
      - WS
      - YE
      - YT
      - ZA
      - ZM
      - ZW
    contract-insurance:
      title: ContractInsurance
      description: You can add an Ad Valorem insurance that will compensate your prejudice in the event of damage, theft or loss (up to the declared value of your items and shipping costs, in case of total loss).
      type: boolean
      default: false
    item.base:
      title: ItemBase
      type: object
      properties:
        name:
          type: string
          maxLength: 255
          example: Vase ming
        description:
          type: string
          maxLength: 255
          example: Vase ming XIV
        quantity:
          type: integer
          default: 1
          description: Item quantity.
          minimum: 1
          multipleOf: 1
        current_packing:
          $ref: '#/components/schemas/packing-type'
        desired_packing:
          $ref: '#/components/schemas/desired-packing'
        measurement_system:
          $ref: '#/components/schemas/measurement-system'
          default: metric
        type:
          $ref: '#/components/schemas/item-type'
        materials:
          $ref: '#/components/schemas/item-materials'
        value:
          $ref: '#/components/schemas/commercial-value'
      required:
      - value
      - current_packing
      - description
    price:
      title: Price
      x-tags:
      - Models
      readOnly: true
      properties:
        currency_code:
          type: string
          title: Money
          description: Shipping estimate price's currency code. Accepted currencies are EUR, USD and GBP.
          example: EUR
        vat_excluded_amount:
          type: integer
          description: 'Amount is a positive integer or zero. Estimated price of the shipping excluding taxes. A positive integer representing the

            price of the quote in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100,

            a zero-decimal currency). The minimum amount is $0.50 US or equivalent in charge currency. The amount

            value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).

            '
          example: 10000
        vat_included_amount:
          type: integer
          description: 'Amount is a positive integer or zero. Estimated price of the shipping including taxes. A positive integer representing the

            price of the quote in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100,

            a zero-decimal currency). The minimum amount is $0.50 US or equivalent in charge currency. The amount

            value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).

            '
          example: 12000
        vat_amount:
          type: integer
          description: 'Amount is a positive integer or zero. Estimated price of the taxes. A positive integer representing the

            price of the quote in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100,

            a zero-decimal currency). The minimum amount is $0.50 US or equivalent in charge currency. The amount

            value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).

            '
          example: 2000
        insurance_amount:
          type: integer
          description: 'Amount is a positive integer or zero. Estimated price of the insurance including taxes. A positive integer representing the

            price of the quote in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100,

            a zero-decimal currency). The minimum amount is $0.50 US or equivalent in charge currency. The amount

            value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).

            '
          example: 700
    currency-code:
      title: CurrencyCode
      type: string
      description: The currency code, according to [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)
      enum:
      - EUR
      - USD
      - GBP
      default: EUR
    quote:
      title: Quote
      x-tags:
      - Models
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: ID of the Quote.
          example: 123e4567-e89b-12d3-a456-426614174000
          readOnly: true
        quote_reference_number:
          type: string
          description: This QVO number is a direct reference to the quote and is used to communicate with Convelio's operational and support teams.
          example: QVO-001
          readOnly: true
        shipping_speed:
          $ref: '#/components/schemas/shipping-speed'
        direct_label_request:
          $ref: '#/components/schemas/direct-label-request'
        delivery:
          $ref: '#/components/schemas/delivery'
        pickups:
          type: array
          items:
            $ref: '#/components/schemas/pickup'
        share_link:
          type: string
          description: Instant quote sharelink.
          format: uri
          example: https://web.convelio.com/sharelinkencoded
        contract_insurance:
          $ref: '#/components/schemas/contract-insurance'
        customer_email:
          type: string
          maxLength: 255
          description: Add a customer email address to receive the quote by email.
          format: email
          example: person@example.com
        price:
          $ref: '#/components/schemas/price'
        status:
          $ref: '#/components/schemas/quote-status'
        customer_reference_number:
          type: string
          maxLength: 255
          example: CRN123456789
        additional_info:
          type: string
          maxLength: 8000
          example: Additional information for customs.
    packing-type:
      title: PackingType
      x-tags:
      - Enums
      description: '- not_packed: Your product is not protected by any kind of bubble warp or cardboard.

        - wood_crated: Your product is fully covered in bubble warp and fragile corners are covered with cardboard. Also, you placed adapted protections inside the wooden crate to prevent your product from moving too much and to protect it even further. Last but not least, the wood crate is put on pallet.'
      type: string
      enum:
      - not_packed
      - wood_crated
    http-error:
      title: HttpError
      x-tags:
      - Error responses
      description: 'The error model for the API follow the Content-Type **application/problem+json** defined by the [IETF RFC 7807](https://tools.ietf.org/html/rfc7807).


        Description of the errors:

        - Bad Request (400): The URL requested is not valid.

        - Unauthorized (401): Token not found.

        - Forbidden (403): You are authenticated but not allowed to execute the action.

        - Not Found (404): Page not found.

        - Unprocessable Entity (422): The server was unable to process the request.

        - Internal Server Error (500): There is an internal problem on our server.

        - Service Unavailable (503): The server is not ready to handle the request.

        '
      type: object
      properties:
        type:
          type: string
          example: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
          description: 'A URL to a page with more details regarding the problem.

            The primary identifier for the problem.

            It''s typically an absolute URL that leads to an HTML page containing human-readable documentation regarding the problem.'
        title:
          type: string
          description: Short human-readable summary of the problem.
          example: Forbidden
        status:
          type: integer
          description: 'The HTTP status code.

            It''s always the same as the status code in the HTTP header.

            It''s only included for the convenience of the consumer.'
          example: 403
          minimum: 100
        detail:
          type: string
          description: Human-readable description of this specific problem.
          example: Forbidden
      required:
      - type
      - title
      - status
      - detail
    contact:
      title: Contact
      x-tags:
      - Models
      type: object
      description: ''
      properties:
        first_name:
          type: string
          maxLength: 255
          example: John
          description: Contact's first name.
        last_name:
          type: string
          maxLength: 255
          example: Doe
          description: Contact's last name.
        email:
          type: string
          format: email
          maxLength: 255
          example: john.doe@exemple.com
          description: Contact's main email.
        phone:
          $ref: '#/components/schemas/phone'
        additional_emails:
          type: array
          description: Contact's additional email addresses.
          items:
            type: string
            format: email
        additional_phones:
          type: array
          description: Contact's additional phone numbers.
          items:
            $ref: '#/components/schemas/phone'
      required:
      - first_name
      - last_name
      - email
      - phone
    order:
      title: Order
      x-tags:
      - Models
      description: ''
      type: object
      properties:
        id:
          description: Order ID.
          type: string
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
        order_reference_number:
          type: string
          example: CVO-288
        contract_insurance:
          $ref: '#/components/schemas/contract-insurance'
        shipping_speed:
          $ref: '#/components/schemas/shipping-speed'
        pickups:
          type: array
          items:
            $ref: '#/components/schemas/pickup'
        delivery:
          $ref: '#/components/schemas/delivery'
        price:
          $ref: '#/components/schemas/price'
        billing_details:
          $ref: '#/components/schemas/billing-details'
        tracking_link:
          type: string
          format: uri
          description: Link to follow the progress of the shipping order.
          example: https://tracking.convelio.com/example
        dashboard_order_link:
          type: string
          format: uri
          description: Link to see the details of the shipping order.
          example: https://web.convelio.com/dashboard/order/288
        customer_reference_number:
          type: string
          description: Customer/partner provided reference number.
          maxLength: 255
          example: REF123456
    desired-packing:
      title: DesiredPacking
      x-tags:
      - Enums
      description: 'Leave empty by default.

        - masterpack: Convelio will soft-wrap the item and place it into a cardboard box.'
      type: string
      enum:
      - masterpack
      - cardboard_box_stdo_c1
      - cardboard_box_stdo_c2
      - cardboard_box_stdo_c3
      - cardboard_box_stdo_c4
      - cardboard_box_stdo_c5
      - cardboard_box_stdo_c6
      - cardboard_box_stdo_fp1
      - cardboard_box_stdo_fp2
      - cardboard_box_stdo_t1
      - cardboard_box_stdo_j1
      - cardboard_box_stdo_j2
      - cardboard_box_stdo_f1
      - cardboard_box_stdo_largetube
      - cardboard_box_stdo_2c1
      - cardboard_box_stdo_3c1
      - cardboard_box_stdo_2c2
      - cardboard_box_stdo_3c2
      - cardboard_box_stdo_2c3
      - cardboard_box_stdo_3c3
      - cardboard_box_stdo_2c4
      - cardboard_box_stdo_3c4
      - cardboard_box_stdo_2c5
      - cardboard_box_stdo_3c5
      - cardboard_box_stdo_2c6
      - cardboard_box_stdo_3c6
      - cardboard_box_stdo_2fp1
      - cardboard_box_stdo_3fp1
      - cardboard_box_stdo_2fp2
      - cardboard_box_stdo_3fp2
      - woodcrate_nsdp_pp
      - woodcrate_nsdp_g
      - woodcrate_nsdp_ppg
      - woodcrate_nsdp_cw
      - woodcrate_nsdp_tf
      - woodcrate_nsdp_tfw
      - woodcrate_nsdp_af
      - woodcrate_nsdo_scs
      - woodcrate_nsdo_scl
    pickup:
      title: Pickup
      type: object
      properties:
        company_name:
          type: string
          maxLength: 255
          example: Company Name LTD
          description: The company name.
        address:
          $ref: '#/components/schemas/address'
        contacts:
          type: array
          description: Pickup contact details.
          minItems: 1
          items:
            $ref: '#/components/schemas/contact'
        items:
          type: array
          description: Pickup items.
          minItems: 1
          items:
            oneOf:
            - $ref: '#/components/schemas/item'
            - $ref: '#/components/schemas/multi-part-item'
        additional_info:
          type: string
          example: Additional information regarding the pickup.
          description: Additional information regarding the pickup.
      required:
      - items
      - address
    http-unprocessable-entity-error:
      title: HttpUnprocessableEntityError
      x-tags:
      - Error responses
      type: object
      allOf:
      - $ref: '#/components/schemas/http-error'
      - properties:
          status:
            example: 422
          validation_messages:
            type: object
            description: Validation messages are only returned when your request have a body and the body is invalid.
            properties:
              '{field_name}':
                type: object
                description: 'The name of the field which is wrong in your request. Example: "delivery_type"'
                properties:
                  '{error_title}':
                    type: string
                    description: 'The title of the error. Example: "deliveryTypeInvalid"'
                    example: 'Invalid delivery type. Valid values are: curbside, white_glove'
            required:
            - '{field_name}'
    phone:
      title: Phone
      type: string
      maxLength: 255
      examples:
      - '+442033188673'
      - +44 2 033 188 673
      - +44 20 33 18 86 73
      - 44;2033188673;gb
      description: "Phone number with following formats:\n\n- **International E.164 formats**:<br>\n  Example: `+33123123123` or `+33 1 23 12 31 23`\n  - `+33`: Country code with a `+` prefix\n  - `123123123`: Local phone number\n\n  Spaces between digits are supported, but cleaned on our side.<br><br>\n\n- **Format with country code, local number, and country ISO2 code**:<br>\n   Example: `33;12312313;fr`\n     - `33`: Country code (international dialing code)\n     - `12312313`: Local phone number\n     - `fr`: Country `ISO 3166-1 alpha-2` code (France in this example)\n\n   The parts are separated by semicolons (`;`)."
    delivery-type:
      title: DeliveryType
      x-tags:
      - Enums
      description: 'Delivery options for the shipment. 2 possible values:

        - curbside: Our drivers will unload the items and deliver them in front of the building at the scheduled time.

        - white_glove: Our drivers will unload, unpack, check and install the product in the chosen room at the scheduled time. For a white-glove delivery, all the packages must fit in the staircase or in the elevator.

        - front_door_with_signature: delivery like `white_glove` with mandatory signature (only for jewelry or watch items)'
      type: string
      enum:
      - curbside
      - white_glove
      - front_door_with_signature
      default: curbside
    speed-shipment-estimation:
      title: ShippingSpeedShipmentEstimation
      x-tags:
      - Enums
      description: 'Freight speed.

        Possible values:

        - regular speed: Our standard air freight speed option.'
      type: string
      enum:
      - regular_speed
      default: regular_speed
    item-type:
      title: ItemType
      description: 'Available options:


        - fine_art.painting: Fine art painting

        - fine_art.picture: Fine art picture

        - fin

# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/convelio/refs/heads/main/openapi/convelio-shipping-api-openapi.yml