VTEX Shipping Network API

openapi: 3.0.0
info:
  title: VTEX Shipping Network API
  contact: {}
  description: "**[VTEX Shipping Network](https://developers.vtex.com/docs/guides/vtex-shipping-network)** connects carriers and store owners to deliver better freight costs, and a simpler and smarter logistics operation. VTEX Shipping Network uses the following steps during a package's tracking process: \r\n\r\n- **Notification:** OMS notifies the carrier that a package is being dispatched. \r\n\r\n- **Tracking:** tracking of the package begins, and is repeated in cycles, until its final delivery. \r\n\r\nFor carriers to integrate with VTEX Shipping Network's Hub, our main system, it is necessary to develop apps in VTEX IO, and associate API routes with them. The carrier's apps integrate with the hub, that in turn are connected to other VTEX systems, fulfilling the steps cited above. \r\n\r\nCheckout our [Integration Guide](https://developers.vtex.com/docs/guides/vtex-shipping-network) to learn more."
  version: '1.0'
servers:
  - url: https://app.io.vtex.com
    description: VTEX server URL.
    variables: {}
paths:
  /{app_name}/v{app_version}/{account}/{workspace}/notify:
    post:
      tags:
        - Notification
      summary: VTex Notify carrier with app
      description: "This endpoint notifies the carrier about a dispatch order by calling the `vtex.carrier-notifier app`. When the call is made, the following data is sent: \n\n- Dispatched packages information. \n\n- Fiscal information about the carrier notified. \n\n- Carrier's contact email. \n\nThe call's response includes all tracking data and each package's ID generated by the notification made to the carrier. \r\n\r\n## Permissions\r\n\r\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:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Logistics | Logistics access | **Transportation read only** |\r\n\r\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).\r\n\r\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: NotifyCarrierwithApp
      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:
              $ref: '#/components/schemas/NotifyCarrierwithAppRequest'
            example:
              account:
                name: Ltda
                accountName: '{{account}}'
                isOperating: true
                defaultUrl:
                district:
                country: Brasil
                complement:
                companyName: LTDA
                cnpj: '00000000000000'
                city:
                address:
                number:
                postalCode:
                state:
                telephone:
                tradingName: tradingName
              email: email
              dispatchOrder:
                id: 653560c2-7965-4614-a730-8e45c89bf284
                packageIds:
                  - 6529cd28-6fd1-4b95-8397-5fad0a79d41c
                sender:
                  cnpj: '00000000000000'
                  fantasyName:
                  stateRegistration:
                  id:
                  name: LTDA
                  address:
                    postalCode: '03475015'
                    country:
                      code: BRA
                      name: Brasil
                    subregion1:
                      code: SP
                      name: São Paulo
                    subregion2:
                      code: São Paulo
                      name: São Paulo
                    subregion3:
                      code: Vila Antonieta
                      name: Vila Antonieta
                    street: Rua Exemplo
                    number: '01'
                    complement: ''
                    location:
                  email:
                  phone: '999999999'
                carrier:
                  cnpj: '00000000000000'
                  fantasyName: carrier
                  stateRegistration: 096/3624636
                  id: vtexlog_exemplo
                  name: Carrier LTDA.
                  address:
                    postalCode: '90200001'
                    country:
                      code: BRA
                      name: Brasil
                    subregion1:
                      code: RS
                      name: Rio Grande do Sul
                    subregion2:
                      code: Porto_Alegre
                      name: Porto Alegre
                    subregion3:
                      code: Anchieta
                      name: Anchieta
                    street: Rua Exemplo
                    number: '01'
                    complement: Pavilhão 6
                    location:
                  email: email
                  phone: '+5511111111111'
        required: true
      responses:
        '200':
          description: OK
          headers: {}
      deprecated: false
  /{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`. \r\n\r\n## Permissions\r\n\r\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:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Logistics | Logistics access | **Transportation read only** |\r\n\r\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).\r\n\r\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: []
components:
  securitySchemes:
    appKey:
      type: apiKey
      in: header
      name: X-VTEX-API-AppKey
      description: Unique identifier of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).
    appToken:
      type: apiKey
      in: header
      name: X-VTEX-API-AppToken
      description: Secret token of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).
    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.'
  schemas:
    Account:
      title: Account
      required:
        - name
        - accountName
        - isOperating
        - defaultUrl
        - district
        - country
        - complement
        - companyName
        - cnpj
        - city
        - address
        - number
        - postalCode
        - state
        - telephone
        - tradingName
      type: object
      properties:
        name:
          type: string
          description: Inserted name.
          example: Ltda
        accountName:
          type: string
          description: Name of the VTEX Account dispatching the package.
          example: mystore
        isOperating:
          type: boolean
          description: Whether the store is operating or not.
          example: true
        defaultUrl:
          type: string
          nullable: true
          description: Retrieved from VTEX's License Manager.
          example: https://url.example.com
        district:
          type: string
          nullable: true
          description: District where the VTEX store dispatching the package is located.
          example: District name
        country:
          type: string
          description: Country where the VTEX store, dispatching the package, is located.
          example: Brasil
        complement:
          type: string
          nullable: true
          description: Complement for the VTEX store's address.
          example: Second floor
        companyName:
          type: string
          description: Name of the VTEX store responsible for the package.
          example: VTEX Store 1
        cnpj:
          type: string
          description: CNPJ code of the VTEX store responsible for the package.
          example: '00000000000000'
        city:
          type: string
          nullable: true
          description: City where the VTEX store responsible for the package is located.
          example: Rio de Janeiro
        address:
          type: string
          nullable: true
          description: Address where the VTEX store responsible for the package is located.
          example: VTEX Street
        number:
          type: string
          nullable: true
          description: Number of the address related to the `address` field.
          example: '26'
        postalCode:
          type: string
          nullable: true
          description: ZIP code of the VTEX store responsible for the package.
          example: 12345-678
        state:
          type: string
          nullable: true
          description: State of the address belonging to the VTEX store responsible for the package.
          example: RJ
        telephone:
          type: string
          nullable: true
          description: Telephone number of the VTEX store responsible for the package.
          example: '99999999'
        tradingName:
          type: string
          description: Trading name of the VTEX store responsible for the package.
          example: Trading name
      description: Account information.
      example:
        name: Ltda
        accountName: '{{account}}'
        isOperating: true
        defaultUrl:
        district:
        country: Brasil
        complement:
        companyName: LTDA
        cnpj: '00000000000000'
        city:
        address:
        number:
        postalCode:
        state:
        telephone:
        tradingName: tradingName
    Address:
      title: Address
      description: Address of the VTEX account responsible for sending the package.
      required:
        - postalCode
        - country
        - subregion1
        - subregion2
        - subregion3
        - street
        - number
        - complement
        - location
      type: object
      properties:
        postalCode:
          type: string
          nullable: true
          description: ZIP code of the package's recipient.
          example: 12345-678
        country:
          $ref: '#/components/schemas/Country'
        subregion1:
          $ref: '#/components/schemas/Subregion1'
        subregion2:
          $ref: '#/components/schemas/Subregion2'
        subregion3:
          $ref: '#/components/schemas/Subregion3'
        street:
          type: string
          description: Recipient's address.
          example: Street example
        number:
          type: string
          description: Number of the recipient's address.
          example: '1'
        complement:
          type: string
          nullable: true
          description: Complement for the recipient's address.
          example: A
        location:
          $ref: '#/components/schemas/Location'
      example:
        postalCode: 00000-000
        country:
          code: BRA
          name: BRA
        subregion1:
          code: SP
          name: SP
        subregion2:
          code: São Paulo
          name: São Paulo
        subregion3:
          code: Burgo Paulista
          name: Burgo Paulista
        street: Rua Exempo
        number: '01'
        complement:
        location:
          lat: -46.48582077026367
          lng: -23.521709442138672
    Country:
      title: Country
      description: Recipient's country.
      required:
        - code
        - name
      type: object
      properties:
        code:
          type: string
          description: Country's three-digit identifying code, from the recipient's address.
          example: BRA
        name:
          type: string
          description: Country's name, from the recipient's address.
          example: Brasil
      example:
        code: BRA
        name: BRA
    Subregion1:
      title: State
      description: Recipient's address state's information.
      required:
        - code
        - name
      type: object
      properties:
        code:
          type: string
          description: State's code, from the recipient's address.
          example: SP
        name:
          type: string
          description: State's name, from the recipient's address.
          example: Sao Paulo
      example:
        code: SP
        name: SP
    Subregion2:
      title: City
      description: Recipient's address city's information.
      required:
        - code
        - name
      type: object
      properties:
        code:
          type: string
          description: City's code, from the recipient's address.
          example: SP
        name:
          type: string
          description: City's name, from the recipient's address.
          example: Sao Paulo
      example:
        code: SP
        name: São Paulo
    Subregion3:
      title: Neighborhood
      description: Recipient's address neighborhood's information.
      required:
        - code
        - name
      type: object
      properties:
        code:
          type: string
          description: Neighborhood's code, from the recipient's address.
          example: Neighborhood example
        name:
          type: string
          description: Neighborhood's name, from the recipient's address.
          example: Neighborhood example
      example:
        code: Vila Antonieta
        name: Vila Antonieta
    Location:
      title: Location
      description: Recipient's address geocoordinates.
      required:
        - lat
        - lng
      type: object
      nullable: true
      properties:
        lat:
          type: number
          description: Latitude number of the address' geolocation coordinates.
          example: -46.48582077026367
        lng:
          type: number
          description: Longitude number of the address' geolocation coordinates.
          example: -23.521709442138672
      example:
        lat: -46.48582077026367
        lng: -23.521709442138672
    NotifyCarrierwithAppRequest:
      title: NotifyCarrierwithAppRequest
      description: Object containing email, account, and dispatched order information.
      required:
        - email
        - dispatchOrder
        - account
      type: object
      properties:
        account:
          $ref: '#/components/schemas/Account'
        email:
          type: string
          description: Fill in this field if you wish to send the generated file for an email besides the ones already involved in the operation, like the carrier and VTEX account's email.
          example: email
        dispatchOrder:
          $ref: '#/components/schemas/DispatchOrder'
    DispatchOrder:
      title: DispatchOrder
      description: Information about the dispatched order.
      required:
        - id
        - packageIds
        - sender
        - carrier
      type: object
      properties:
        id:
          type: string
          description: ID of the dispatched order.
          example: 653560c2-7965-4614-a730-8e45c89bf284
        packageIds:
          type: array
          description: Array with package IDs.
          items:
            type: string
            description: Identification codes of the packages.
            example: 6529cd28-6fd1-4b95-8397-5fad0a79d41c
        sender:
          $ref: '#/components/schemas/Sender'
        carrier:
          $ref: '#/components/schemas/Carrier'
    Sender:
      title: Sender
      description: User's logged account in the VTEX store.
      required:
        - cnpj
        - fantasyName
        - stateRegistration
        - id
        - name
        - address
        - email
        - phone
      type: object
      properties:
        cnpj:
          type: string
          description: CNPJ code of the VTEX account responsible for sending the package.
          example: 81.316.120/0001-02
        fantasyName:
          type: string
          description: Fantasy name of the VTEX account responsible for sending the package.
          example: Carrier 123
          nullable: true
        stateRegistration:
          type: string
          description: State Registration code of the VTEX account responsible for sending the package.
          example: '9843759348'
          nullable: true
        id:
          type: string
          description: VTEX account's ID.
          example: accountId
          nullable: true
        name:
          type: string
          description: Name of the VTEX account responsible for sending the package.
          example: Store LTDA
        address:
          $ref: '#/components/schemas/Address'
        email:
          type: string
          description: Email of the VTEX account responsible for sending the package.
          example: [email protected]
          nullable: true
        phone:
          type: string
          description: Sender's contact number.
          example: '+5511111111111'
          nullable: true
      example:
        cnpj: '00000000000000'
        fantasyName:
        stateRegistration:
        id:
        name: LTDA
        address:
          postalCode: '03475015'
          country:
            code: Brasil
            name: Brasil
          subregion1:
            code: SP
            name: SP
          subregion2:
            code: São Paulo
            name: São Paulo
          subregion3:
            code: Vila Antonieta
            name: Vila Antonieta
          street: Rua Exemplo
          number: '01'
          complement: ''
          location:
        email:
        phone: '+5511111111111'
    Carrier:
      title: Carrier
      description: Carrier responsible for delivering the dispatched order.
      required:
        - cnpj
        - fantasyName
        - stateRegistration
        - id
        - name
        - address
        - email
        - phone
      type: object
      properties:
        cnpj:
          type: string
          description: Carrier's CNPJ.
          example: '00000000000000'
        fantasyName:
          type: string
          description: Carrier's fantasy name.
          example: Carrier A
        stateRegistration:
          type: string
          description: Carrier's state registration number.
          example: '843904894875'
        id:
          type: string
          description: Carrier's ID.
          example: vtexShippinNetwork_example
        name:
          type: string
          description: Carrier's company name.
          example: Carrier LTDA
        address:
          $ref: '#/components/schemas/Address'
        email:
          type: string
          description: Carrier's email address.
          example: [email protected]
        phone:
          type: string
          description: Carrier's contact number.
          example: '+5511111111111'
          nullable: true
      example:
        cnpj: '00000000000000'
        fantasyName: carrier
        stateRegistration: 096/3624636
        id: vtexlog_exemplo
        name: Carrier LTDA.
        address:
          postalCode: '90200001'
          country:
            code: BRA
            name: Brasil
          subregion1:
            code: RS
            name: Rio Grande do Sul
          subregion2:
            code: Porto_Alegre
            name: Porto Alegre
          subregion3:
            code: Anchieta
            name: Anchieta
          street: Rua Exemplo
          number: '01'
          complement: Pavilhão 6
          location:
        email: email
        phone: '+5511111111111'
    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
tags:
  - name: Notification
  - name: Tracking