Documentation
Feedback
Guides
App Development

App Development
ServicesClients
Connecting to VTEX Core Commerce APIs

Learn how to enable seamless HTTP communication with VTEX Core Commerce APIs within your VTEX IO app.

VTEX IO apps are designed designed to seamlessly interface with VTEX Core Commerce APIs. These APIs provide a set of functionalities and data access points for managing and interacting with the VTEX e-commerce platform, enabling developers to perform various operations, such as managing orders, products, and customer data.

In this guide, you will learn how to create a custom client that can handle HTTP requests to these VTEX Core Commerce APIs, allowing your application to retrieve and manipulate data within the VTEX ecosystem.

Before you begin

Ensure a smooth development process by having the following prerequisites in place:

  • VTEX IO Development Workspace: Set up your VTEX IO environment by following the steps outlined in Creating a Development Workspace.
  • TypeScript Familiarity: Acquire a basic understanding of TypeScript, as we'll be using the node Builder for TypeScript development. For details, refer to Typescript's Official Documentation.
  • Understanding of Clients: Clients play a crucial role in facilitating interactions between your application and both external and internal services. Learn more about Clients.

Step by step

Step 1 - Setting up your VTEX IO app

  1. Start a new VTEX IO app using the node builder and open the project using your preferred code editor.

  2. Install the @vtex/api package by running the following command:


    _10
    yarn add @vtex/api

  3. Update the app's manifest.json to include the appropriate outbound-access policy for the requested URL. Here's a hypothetical example:

    manifest.json

    _22
    {
    _22
    "name": "your-app",
    _22
    "version": "1.0.0",
    _22
    "scripts": {
    _22
    // ...
    _22
    },
    _22
    "dependencies": {
    _22
    // ...
    _22
    },
    _22
    "builders": {
    _22
    // ...
    _22
    },
    _22
    "policies": [
    _22
    {
    _22
    "name": "outbound-access",
    _22
    "attrs": {
    _22
    "host": "{{account}}.vtexcommercestable.com.br",
    _22
    "path": "/api/checkout/pub/orderForm/*"
    _22
    }
    _22
    }
    _22
    ]
    _22
    }

Step 2 - Creating a Client for connecting to VTEX Core Commerce APIs

  1. Create a TypeScript file for your Client in the node/clients directory. Choose a name that easily identifies your Client (e.g., myClient.ts).

  2. Create a client that represents the module you want to access. It will be a class that extends JanusClient.

    ./node/clients/myClient.ts

    _10
    import type { InstanceOptions, IOContext } from ‘@’vtex/api’
    _10
    import { JanusClient } from ‘@vtex/api’
    _10
    _10
    export default class MyClient extends JanusClient {
    _10
    constructor(context: IOContext, options?: InstanceOptions) {
    _10
    super(context, { …options })
    _10
    }
    _10
    }

  3. In the constructor, set the VtexIdclientAutCookie header with the required token for authorization. Use ctx.authToken for the app's token, or ctx.vtex.storeUserAuthToken or ctx.vtex.adminUserAuthToken for requests from VTEX Admin or VTEX Storefront, respectively. Refer to App authentication using auth tokens for more information.

    ./node/clients/myClient.ts

    _16
    import type { InstanceOptions, IOContext } from ‘@’vtex/api’
    _16
    import { JanusClient } from ‘@vtex/api’
    _16
    _16
    export default class MyClient extends JanusClient {
    _16
    constructor(context: IOContext, options?: InstanceOptions) {
    _16
    super(ctx, {
    _16
    ...options,
    _16
    headers: {
    _16
    Accept: 'application/json',
    _16
    VtexIdclientAutCookie: ctx.storeUserAuthToken,
    _16
    'x-vtex-user-agent': ctx.userAgent,
    _16
    ...options?.headers,
    _16
    },
    _16
    })
    _16
    }
    _16
    }

    Ensure to export the Client from its module using either default or named export.

Step 3 - Implementing the Client methods

In your Client TypeScript file, implement the desired methods using the HttpClient for targeted HTTP calls.

./node/clients/myClient.ts

_34
import type { InstanceOptions, IOContext } from ‘@’vtex/api’
_34
import { JanusClient } from ‘@vtex/api’
_34
_34
export default class MyClient extends JanusClient {
_34
constructor(context: IOContext, options?: InstanceOptions) {
_34
super(ctx, {
_34
...options,
_34
headers: {
_34
Accept: 'application/json',
_34
VtexIdclientAutCookie: ctx.storeUserAuthToken,
_34
'x-vtex-user-agent': ctx.userAgent,
_34
...options?.headers,
_34
},
_34
})
_34
}
_34
_34
public newOrderForm = (orderFormId?: string) => {
_34
return this.http
_34
.postRaw<OrderForm>(this.routes.orderForm(orderFormId), undefined, {
_34
metric: 'checkout-newOrderForm',
_34
})
_34
.catch(statusToError) as Promise<IOResponse<OrderForm>>
_34
}
_34
_34
private get routes() {
_34
const base = '/api/checkout/pub'
_34
_34
return {
_34
orderForm: (orderFormId?: string) =>
_34
`$\{base\}/orderForm/$\{orderFormId ?? ''\}`
_34
}
_34
}
_34
_34
}

In the provided example, the newOrderForm method is implemented to make HTTP requests using this.http. It facilitates the creation of a new order form by sending a POST request (postRaw) to the specified endpoint. The method includes additional configurations such as defining the metric for tracking and handling potential errors in the response.

Step 4 - Exporting custom clients

Now that you've created your custom Client, organize and export it for use in your VTEX IO service. Follow these steps:

  1. Create an index.ts file in the node/clients folder.

  2. Inside the index.ts file, import the custom client you created in the previous step. For example:


    _10
    import MyClient from "./myClient.ts";

  3. Define a class called Clients that extends IOClients. This class is used to organize and configure your custom Clients. Within the Clients class, declare a get property for each of your custom Clients. This property allows you to access a specific Client by name. In our example, we've created a client named myClient that uses the MyClient class.


    _10
    import { IOClients } from "@vtex/api";
    _10
    import MyClient from "./myClient.ts";
    _10
    _10
    export class Clients extends IOClients {
    _10
    public get status() {
    _10
    return this.getOrSet("myClient", MyClient);
    _10
    }
    _10
    }

Now that you have developed and exported your custom Client to communicate with the desired service, your Clients can be accessed and used within your VTEX IO service to perform various tasks. Learn how to use clients effectively in the Using Node Clients guide.

Key considerations

  • GraphQL apps: Some Core Commerce modules already feature a GraphQL app that abstracts their endpoints. Check if the desired data is available via one of our GraphQL apps. Utilize the GraphQL IDE app on the Admin for exploration.
  • Authentication: IO apps do not require an appKey/appToken pair to make requests to VTEX Core Commerce APIs. Every app has its own rotating token that can be used on the app's code. In scenarios where using the app's token is not ideal (e.g., authorization depends on the calling user), opt to use the user's token instead, using ctx.vtex.storeUserAuthToken or ctx.vtex.adminUserAuthToken. Refer to Authentication for more information.

Example

Contributors
2
Photo of the contributor
Photo of the contributor
+ 2 contributors
Was this helpful?
Yes
No
Suggest edits (Github)
Contributors
2
Photo of the contributor
Photo of the contributor
+ 2 contributors
On this page