VTEX Service Integration API

openapi: 3.2.0
info:
  title: VTex Pick and Pack Last Mile Protocol Service Integration…
  description: The Pick and Pack Last Mile Protocol API enables seamless integration between the Pick and Pack app and delivery services.
  version: '1.0'
servers:
- url: https://auth.pickingnpacking.com/{environment}
  variables:
    environment:
      default: DefaultParameterValue
      description: Server to access the authentication necessary to make a request in the Pick and Pack Provider API.
- url: https://{store_endpoint}
  variables:
    your_endpoint:
      default: storeapi.com
      description: Server from the store.
- url: https://api.pickingnpacking.com/{environment}/v1/tracking/hook
  variables:
    environment:
      default: DefaultParameterValue
      description: Environment of the Pick and Pack Protocol App.
tags:
- name: Service Integration
  description: These endpoints must be developed to integrate with the Lastmile Pick and Pack Last Mile Protocol API.
paths:
  /create-service:
    post:
      tags:
      - Service Integration
      summary: VTex Create service
      description: 'Creates a service with the information that VTEX will send to the carrier. To understand how to integrate with a carrier, check the VTEX Pick and Pack Carriers Integration Protocol guide.


        This endpoint must be developed by the carriers or brokers to integrate into the protocol.


        ## Permissions


        This endpoint does not require permissions.'
      operationId: Createservice
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            example:
              orderId: SLR-29384924-01
              carrierId: servientrega-50461c9f3335
              seller: qaolimpica
              sender:
                name: Tabitha Sears
                phone: +57 2305781612
                email: tabitha_sears@fortean.brother
                city: Jenkinsville
                state: Northern Mariana Islands
                country: US
                address: 77 Sullivan Place, Jenkinsville, Northern Mariana Islands
                addressComplement: Flat 45
                number: '1029'
                reference: '3'
                location:
                  latitude: -75.269008
                  longitude: 137.499833
                pickupDate: '2024-04-25T18:06:41.202Z'
              receiver:
                name: Pansy Graves
                phone: +57 4240807147
                email: pansy_graves@zentime.moda
                city: Valle
                state: Marshall Islands
                country: Iceland
                neighborhood: Billings
                number: '9840'
                reference: 63 Billings Place, Valle, Marshall Islands
                addressComplement: Flat 45
                location:
                  latitude: -33.249891
                  longitude: -135.052901
                identification: '9541933267'
                deliveryDate: '2024-04-16T20:49:36.117Z'
                contactName: Savannah Porter
                deliveryWindow:
                  name: consectetur
                  initialDate: '2024-04-25T22:50:41.209Z'
                  finalDate: '2024-05-05T21:50:41.210Z'
              packages:
              - id: 6266df719ac55224b793ad36
                orderId: SLR-1221800709659-01
                envelope: Large
                description: Delicate package
                categories:
                - Cellphone
                - Technology
                dimensions:
                  width: '68'
                  height: '43'
                  length: '13'
                weight: '19'
                totalValue: 5616.01
                items:
                - id: 6266df71a19ebe35637e1f42
                  name: Tomatos
                  ean: '473390795673'
                  refId: '6266'
                  image: https://static9.depositphotos.com/1628352/1107/i/600/depositphotos_11071361-stock-photo-tomato.jpg
                  type: Food
                  price: 774230.01
                  weight: 4 kg
                  quantity: 4
                - id: 6266df71803601c3bc4e2d99
                  name: Tomatos
                  ean: '329949764612'
                  refId: '6266'
                  image: https://static9.depositphotos.com/1628352/1107/i/600/depositphotos_11071361-stock-photo-cellphone.jpg
                  type: Foods
                  price: 23162
                  weight: 14 kg
                  quantity: 9
              type: PICKUP_DELIVERY
              carrierServiceType: OTHERS
              comments: Delivery comments.
              paymentMethod: CASH_ON_DELIVERY
              orderValue: 8000
              settings:
              - label: Key secret
                value: keysecret-0122
                key: secrekey
              timezone:
                offset: 300
                value: America/Bogota
            schema:
              $ref: '#/components/schemas/CreateServiceBody'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseService'
        '400':
          description: Bad request
        '401':
          description: Required authentication
        '404':
          description: Resource not found
        '500':
          description: Internal error
      deprecated: false
      servers:
      - url: https://{store_endpoint}
        variables:
          your_endpoint:
            default: storeapi.com
            description: Server from the store.
components:
  schemas:
    Package:
      required:
      - id
      - orderId
      - envelope
      - dimensions
      - weight
      - totalValue
      - items
      - categories
      - description
      type: object
      description: Package information.
      properties:
        id:
          type: string
          description: Package ID.
        orderId:
          type: string
          description: Order ID.
        envelope:
          type: string
          description: Name of the envelope used.
        dimensions:
          $ref: '#/components/schemas/Dimensions'
          description: Package dimensions.
        weight:
          type: string
          description: Package weight in grams.
        totalValue:
          type: integer
          format: int32
          description: Total value of the order.
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
            description: Product general information.
          description: Array containing information about the order's products.
        categories:
          type: array
          items:
            type: string
            description: Category name.
          description: Array of categories.
        description:
          type: string
          description: Package description.
      example:
        id: a46e5bc1-8959-459f-a094-b6e699f7214c
        orderId: 46369545534253-01
        envelope: Foam or Plastic Containers
        dimensions:
          height: '5'
          length: '11'
          width: '7'
        weight: '48'
        totalValue: 5352
        items:
        - id: '184'
          name: Chicken
          ean: EAN354
          quantity: 8
          price: 669
          refId: '314'
          image: https://picsum.photos/seed/YtoZ9/128/480
          type: other
          weight: '6'
        categories:
        - Movies
        - Garden
        - Books
        description: Unde deserunt libero cupiditate illum.
    Label:
      required:
      - id
      - name
      - url
      - type
      type: object
      properties:
        id:
          type: string
          description: Label ID.
        name:
          type: string
          description: Name of the label.
        url:
          type: string
          description: Label URL.
        type:
          type: string
          description: Label's type of file.
      example:
        id: 78c83922-d658-48bf-89d5-0658a6a94e27
        name: Shipping label
        url: https://sandbox-download.postmen.com/label/2024-03-09/258a26a4-45ae-49eb-b64d-929d3b81f46d-1709947994279763.pdf
        type: PDF
    Timezone:
      required:
      - offset
      - value
      - label
      type: object
      description: Time zone information.
      properties:
        offset:
          type: integer
          format: int32
          description: Time zone offset.
        value:
          type: string
          description: Time zone.
        label:
          type:
          - string
          - 'null'
          description: Label.
      example:
        offset: 300
        value: America/Bogota
        label: null
    Dimensions:
      required:
      - height
      - length
      - width
      type: object
      properties:
        height:
          type: string
          description: Package height in centimeters.
        length:
          type: string
          description: Package length in centimeters.
        width:
          type: string
          description: Package width in centimeters.
      example:
        height: '5'
        length: '11'
        width: '7'
    CreateServiceBody:
      type: object
      properties:
        orderId:
          type: string
          description: Order ID.
        carrierId:
          type: string
          description: Carrier ID.
        seller:
          type: string
          description: Identifier representing the seller associated with the order.
        sender:
          description: Sender personal information.
          type: object
          properties:
            name:
              description: Sender name.
              type: string
            phone:
              description: Sender phone number.
              type: string
            email:
              description: Sender email.
              type: string
            city:
              description: Sender city of residence.
              type: string
            state:
              description: Sender state of residence.
              type: string
            country:
              description: Sender country of residence.
              type: string
            address:
              description: Sender address.
              type: string
            addressComplement:
              description: Sender address complement, as apartment number.
              type: string
            number:
              description: Sender residence number.
              type: string
            reference:
              description: Reference to the sender's address to facilitate localization.
              type: string
            location:
              description: Object containing specific latitude and longitude of the sender's address.
              type: object
              properties:
                latitude:
                  description: Sender address' latitude.
                  type: number
                longitude:
                  description: Sender address' longitude.
                  type: number
            pickupDate:
              description: Package pickup date in [UTC time format](https://learn.microsoft.com/en-us/rest/api/storageservices/formatting-datetime-values), as in `YYYY-MM-DDThh:mm:ssZ`.
              type: string
        receiver:
          description: Receiver personal information.
          type: object
          properties:
            name:
              description: Receiver name.
              type: string
            phone:
              description: Receiver phone number.
              type: string
            email:
              description: Receiver email.
              type: string
            city:
              description: Receiver city of residence.
              type: string
            state:
              description: Receiver state of residence.
              type: string
            country:
              description: Receiver country of residence.
              type: string
            address:
              description: Receiver address.
              type: string
            addressComplement:
              description: Receiver address complement, as apartment number.
              type: string
            number:
              description: Receiver residence number.
              type: string
            reference:
              description: Reference to the receiver's address to facilitate localization.
              type: string
            location:
              description: Object containing specific latitude and longitude of the receiver's address.
              type: object
              properties:
                latitude:
                  description: Receiver address' latitude.
                  type: number
                longitude:
                  description: Receiver address' longitude.
                  type: number
            identification:
              description: Receiver identification code.
              type: string
            deliveryDate:
              description: Delivery estimated date in [UTC time format](https://learn.microsoft.com/en-us/rest/api/storageservices/formatting-datetime-values), as in `YYYY-MM-DDThh:mm:ssZ`.
              type: string
            contactName:
              description: Receiver contact name.
              type: string
            deliveryWindow:
              description: Object containing information about package delivery window.
              type: object
              properties:
                name:
                  description: Carrier name.
                  type: string
                initialDate:
                  description: Delivery initial date in [UTC time format](https://learn.microsoft.com/en-us/rest/api/storageservices/formatting-datetime-values), as in `YYYY-MM-DDThh:mm:ssZ`.
                  type: string
                finalDate:
                  description: Delivery final date in [UTC time format](https://learn.microsoft.com/en-us/rest/api/storageservices/formatting-datetime-values), as in `YYYY-MM-DDThh:mm:ssZ`.
                  type: string
        packages:
          type: array
          items:
            $ref: '#/components/schemas/Package'
          description: Array containing information about all order's packages.
        carrierServiceType:
          type: string
          description: Carrier service type. The `carrierServiceType` value is not limited to these specific values. It will be defined by the carrier integrating with the Pick and Pack Last Mile Protocol API.
          enum:
          - BROKER
          - PICKUP_IN_STORE
          - NATIONAL
          - INTERNATIONAL
          - EXPRESS
          - SPECIALIZED
          - OTHERS
        type:
          type: string
          description: Order's type of delivery, `Delivery` or [`Pickup`](https://help.vtex.com/en/tutorial/pickup-points--2fljn6wLjn8M4lJHA6HP3R).
        paymentMethod:
          type: string
          description: Payment method.
        comments:
          type: string
          description: Comments.
        orderValue:
          type: integer
          description: Total value of the order.
        settings:
          description: Array of objects with additional custom fields defined by the carrier.
          type: array
          items:
            description: Object containing information about a custom field.
            type: object
            properties:
              label:
                description: Custom field description.
                type: string
              value:
                description: Custom field value.
                type: string
              key:
                description: Custom field key.
                type: string
        timezone:
          $ref: '#/components/schemas/Timezone'
    Item:
      title: Item
      required:
      - id
      - name
      - ean
      - quantity
      - price
      - refId
      - image
      - type
      - weight
      type: object
      properties:
        id:
          type: string
          description: Product ID.
        name:
          type: string
          description: Product name.
        ean:
          type: string
          description: Unique SKU identification code (barcode). Up to 13 numerical characters.
        quantity:
          type: integer
          format: int32
          description: Quantity of units of the product.
        price:
          type: integer
          format: int32
          description: Product price in cents.
        refId:
          type: string
          description: Product reference ID.
        image:
          type: string
          description: SKU image.
        type:
          type: string
          description: Item type.
        weight:
          type: string
          description: Product weight in grams.
      example:
        id: '184'
        name: Chicken
        ean: EAN354
        quantity: 8
        price: 669
        refId: '314'
        image: https://picsum.photos/seed/YtoZ9/128/480
        type: other
        weight: '6'
    ResponseService:
      type: object
      required:
      - status
      - serviceId
      - shippingPrice
      - metaData
      - shippingEstimatedDate
      - labels
      properties:
        status:
          type: string
          example: PENDING
          description: Status of the service.
          enum:
          - PENDING
          - ASSIGNED
          - PICKED
          - ON_ROUTE
          - INCIDENT
          - RETURNED
          - DELIVERED
          - CANCELED
          - ON_HOLD
        serviceId:
          type: string
          example: ASDF23324KDSF2
          description: Service ID.
        shippingPrice:
          type: number
          example: 20000.09
          description: Service shipping price.
        metaData:
          type: object
          properties:
            '{keyValue}':
              description: Carrier additional information.
              type: string
          example:
            anyKey: anyValue
        shippingEstimatedDate:
          type: string
          example: '2024-05-29T22:36:37.589Z'
          description: Shipping estimated date in [UTC time format](https://learn.microsoft.com/en-us/rest/api/storageservices/formatting-datetime-values), as in `YYYY-MM-DDThh:mm:ssZ`.
        labels:
          type: array
          items:
            $ref: '#/components/schemas/Label'
          description: Shipping labels, there may be more than one per order due to breakage in packages.
  parameters:
    Content-Type:
      name: Content-Type
      in: header
      description: Type of the content being sent.
      required: true
      style: simple
      schema:
        type: string
        example: application/json
    Accept:
      name: Accept
      in: header
      description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
      required: true
      style: simple
      schema:
        type: string
        example: application/json
    Authorization:
      name: Authorization
      in: header
      description: Authentication JWT. JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information as a JSON object between parties.
      required: true
      style: simple
      schema:
        type: string
        example: '{token}'