VTEX Tracking API

openapi: 3.2.0
info:
  title: Vtex Tracking API
  version: '1.0'
  contact: {}
  description: 'Operations tagged Tracking across 2 of this provider''s published API definitions: vtex-orders-openapi-original.yml, vtex-shipping-network-openapi-original.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{accountName}.{environment}.com.br
  description: VTEX server URL.
  variables:
    accountName:
      description: Name of the VTEX account. Used as part of the URL.
      default: apiexamples
    environment:
      description: Environment to use. Used as part of the URL.
      enum:
      - vtexcommercestable
      default: vtexcommercestable
- url: https://app.io.vtex.com
  description: VTEX server URL.
  variables: {}
tags:
- name: Tracking
paths:
  /api/oms/pvt/orders/{orderId}/invoice/{invoiceNumber}/tracking:
    put:
      tags:
      - Tracking
      summary: VTex Update order tracking status
      description: 'This endpoint sends a tracking event to an order that already has a tracking number registered to its invoice.


        This request is not meant to send a tracking number and URL to the invoice. If you wish to send a tracking number and URL to an order, use the [Update order''s partial invoice](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/oms/pvt/orders/-orderId-/invoice/-invoiceNumber-) endpoint. For more information, see [Partial invoice](https://help.vtex.com/en/tracks/partial-invoices--2xkTisx4SXOWXQel8Jg8sa/q9GPspTb9cHlMeAZfdEUe) scenarios.


        This endpoint applies to orders with any shipping type, whether delivery or [pickup](https://help.vtex.com/en/tutorial/pickup-points--2fljn6wLjn8M4lJHA6HP3R).


        > The `Notify invoice` License Manager resource is needed to use this API request. This is included in `OMS - Full access` and `IntegrationProfile - Fulfillment Oms`, among other default roles available in the Admin. Learn more about [License Manager Roles](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc).'
      operationId: UpdateTrackingStatus
      parameters:
      - name: Content-Type
        in: header
        description: Type of the content being sent.
        required: true
        style: simple
        schema:
          type: string
          default: application/json
      - 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
          default: application/json
      - name: orderId
        in: path
        description: Order ID is a unique code that identifies an order.
        example: 1172452900788-01
        required: true
        style: simple
        schema:
          type: string
          example: 1172452900788-01
      - name: invoiceNumber
        in: path
        description: Number that identifies the invoice.
        example: '000030711'
        required: true
        style: simple
        schema:
          type: string
          example: '000030711'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTrackingStatusRequest'
            example:
              isDelivered: false
              deliveredDate: 2022-10-01 21:15
              events:
              - city: Rio de Janeiro
                state: RJ
                description: Coletado pela transportadora
                date: '2015-06-23'
              - city: Sao Paulo
                state: SP
                description: A caminho de Curitiba
                date: '2015-06-24'
        required: true
      responses:
        '200':
          description: OK
          headers:
            Cache-Control:
              content:
                text/plain:
                  schema:
                    type: string
                  example: no-cache
            Connection:
              content:
                text/plain:
                  schema:
                    type: string
                  example: keep-alive
            Content-Length:
              content:
                text/plain:
                  schema:
                    type: string
                  example: '116'
            Date:
              content:
                text/plain:
                  schema:
                    type: string
                  example: Wed, 29 Mar 2017 18:05:00 GMT
            Expires:
              content:
                text/plain:
                  schema:
                    type: string
                  example: '-1'
            Pragma:
              content:
                text/plain:
                  schema:
                    type: string
                  example: no-cache
            Server:
              content:
                text/plain:
                  schema:
                    type: string
                  example: nginx
            X-CDNIgnore:
              content:
                text/plain:
                  schema:
                    type: string
                  example: '1'
            X-Powered-by-VTEX-Janus-Edge:
              content:
                text/plain:
                  schema:
                    type: string
                  example: v1.35.3
            X-Track:
              content:
                text/plain:
                  schema:
                    type: string
                  example: stable
            X-VTEX-Janus-Router-Backend-App:
              content:
                text/plain:
                  schema:
                    type: string
                  example: omsapi-v1.5.143
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/UpdateTrackingStatus'
              example:
                date: '2017-03-29T18:04:31.0521233+00:00'
                orderId: v501245lspt-01
                receipt: f67d33a8029c42ce9a8f07fc17f54449
      deprecated: false
      security:
      - appKey:
        - '{{appKey}}'
        appToken:
        - '{{appToken}}'
    servers:
    - url: https://{accountName}.{environment}.com.br
      description: VTEX server URL.
      variables:
        accountName:
          description: Name of the VTEX account. Used as part of the URL.
          default: apiexamples
        environment:
          description: Environment to use. Used as part of the URL.
          enum:
          - vtexcommercestable
          default: vtexcommercestable
  /{app_name}/v{app_version}/{account}/{workspace}/tracking:
    post:
      tags:
      - Tracking
      summary: VTex Tracking events with app
      description: "This endpoint is called by the hub to  obtain the tracking events of a series of tracking numbers. This call's request updates the events of a list of tracking codes, for packages that are still pending delivery. The expected response is an object contaning the tracking information and the package's notification ID for every `packageID`. \n\n## Permissions\n\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\n\n| **Product** | **Category** | **Resource** |\n| --------------- | ----------------- | ----------------- |\n| Logistics | Logistics access | **Transportation read only** |\n\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\n\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
      operationId: TrackingEvents
      parameters:
      - name: app_name
        in: path
        description: Name of the app developed by the carrier's integration.
        required: true
        style: simple
        schema:
          type: string
          default: '{{app name}}'
      - name: app_version
        in: path
        description: Version of the app developed by the carrier's integration.
        required: true
        style: simple
        schema:
          type: string
          default: '{{version}}'
      - name: account
        in: path
        description: VTEX account dispatching the package.
        required: true
        style: simple
        schema:
          type: string
          default: VTEX Store example
      - name: workspace
        in: path
        description: 'Workspace used in VTEX IO. '
        required: true
        style: simple
        schema:
          type: string
          default: master
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/TrackingEventsRequest'
              description: Array containing tracking information.
              example:
              - trackingNumber: BR000000000
            example:
            - trackingNumber: BR000000000
        required: true
      responses:
        '200':
          description: OK
          headers: {}
      deprecated: false
      security:
      - appKey: []
        appToken: []
      - VtexIdclientAutCookie: []
    servers:
    - url: https://app.io.vtex.com
      description: VTEX server URL.
      variables: {}
components:
  schemas:
    Event:
      title: Event
      required:
      - city
      - state
      - description
      - date
      type: object
      properties:
        city:
          type: string
        state:
          type: string
        description:
          type: string
        date:
          type: string
      example:
        city: Rio de Janeiro
        state: RJ
        description: Coletado pela transportadora
        date: '2015-06-23'
    UpdateTrackingStatusRequest:
      title: UpdateTrackingStatusRequest
      required:
      - isDelivered
      - deliveredDate
      - events
      type: object
      properties:
        isDelivered:
          type: boolean
          description: When set as `true`, it means the order got to its final shipping address, whether by delivery or pickup shipping type. When set as `false`, the order is still in transit to its shipping address.
          example: false
        deliveredDate:
          type:
          - string
          - 'null'
          description: Date and time of when the package was delivered. Note that it is different from the tracking date parameter. The `deliveredDate` format is `yyyy-mm-dd hh:mm`.
          example: 2022-10-01 21:15
        events:
          type: array
          items:
            $ref: '#/components/schemas/Event'
          description: Array containing events information.
      example:
        isDelivered: false
        deliveredDate: null
        events:
        - city: Rio de Janeiro
          state: RJ
          description: Coletado pela transportadora
          date: '2015-06-23'
        - city: Sao Paulo
          state: SP
          description: A caminho de Curitiba
          date: '2015-06-24'
    UpdateTrackingStatus:
      title: UpdateTrackingStatus
      required:
      - date
      - orderId
      - receipt
      type: object
      properties:
        date:
          type: string
        orderId:
          type: string
        receipt:
          type: string
      example:
        date: '2017-03-29T18:04:31.0521233+00:00'
        orderId: v501245lspt-01
        receipt: f67d33a8029c42ce9a8f07fc17f54449
    TrackingEventsRequest:
      title: TrackingEventsRequest
      description: Shipping's tracking information.
      required:
      - trackingNumber
      type: object
      properties:
        trackingNumber:
          type: string
          description: Shipping's tracking identification code.
          example: BR000000000
      example:
        trackingNumber: BR000000000
  securitySchemes:
    appKey:
      type: apiKey
      in: header
      name: X-VTEX-API-AppKey
    appToken:
      type: apiKey
      in: header
      name: X-VTEX-API-AppToken
    VtexIdclientAutCookie:
      type: apiKey
      in: header
      name: VtexIdclientAutCookie
      description: '[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours.'
x-refined-from:
- vtex-orders-openapi-original.yml
- vtex-shipping-network-openapi-original.yml