# Delete fiscal_group Source: https://docs.x-mart.io/api-reference/fiscal/delete-admin-fiscal-groups-id api-reference/openapi.json DELETE /admin/fiscal-groups/{id} # Delete category by productId Source: https://docs.x-mart.io/api-reference/fiscal/delete-admin-product-fiscal-categories-productid api-reference/openapi.json DELETE /admin/product-fiscal-categories/{productId} # List fiscal_groups Source: https://docs.x-mart.io/api-reference/fiscal/get-admin-fiscal-groups api-reference/openapi.json GET /admin/fiscal-groups # Get fiscal_group by UUID Source: https://docs.x-mart.io/api-reference/fiscal/get-admin-fiscal-groups-id api-reference/openapi.json GET /admin/fiscal-groups/{id} # List persisted orders (paginated) Source: https://docs.x-mart.io/api-reference/fiscal/get-admin-orders api-reference/openapi.json GET /admin/orders Orden por `created_at` descendente. Filtros opcionales por tienda, origen, estado, texto en `order_id`, rango de fechas de creación e intentos de webhook. # List product_fiscal_category Source: https://docs.x-mart.io/api-reference/fiscal/get-admin-product-fiscal-categories api-reference/openapi.json GET /admin/product-fiscal-categories # Get by productId (text) Source: https://docs.x-mart.io/api-reference/fiscal/get-admin-product-fiscal-categories-productid api-reference/openapi.json GET /admin/product-fiscal-categories/{productId} # Create fiscal_group Source: https://docs.x-mart.io/api-reference/fiscal/post-admin-fiscal-groups api-reference/openapi.json POST /admin/fiscal-groups # Create product fiscal category Source: https://docs.x-mart.io/api-reference/fiscal/post-admin-product-fiscal-categories api-reference/openapi.json POST /admin/product-fiscal-categories # Enrich order with taxes Source: https://docs.x-mart.io/api-reference/fiscal/post-enrich-order api-reference/openapi.json POST /enrich-order Calcula impuestos sobre líneas principales (`order.products[].price.totalPrice`) y modificadores según reglas fiscales y guarda la orden en base de datos (upsert por `orderId`). El cuerpo puede ser `OrderPayload` en la raíz o envuelto en un objeto con propiedad `payload`. Requisitos: body no vacío; `orderId` presente en el payload para respuesta 200. # Enrich, persist, and notify via webhook Source: https://docs.x-mart.io/api-reference/fiscal/post-enrich-order-forward api-reference/openapi.json POST /enrich-order-forward Mismo cuerpo que `POST /enrich-order`. Tras enriquecer y persistir, envía un POST JSON al webhook (`ORDER_WEBHOOK_URL`) con **únicamente el payload enriquecido** (misma forma que el campo `payload` de la respuesta 200 de `/enrich-order`). La respuesta HTTP de **esta** API solo indica si el flujo y el webhook respondieron bien; no devuelve la orden. # Update fiscal_group (partial) Source: https://docs.x-mart.io/api-reference/fiscal/put-admin-fiscal-groups-id api-reference/openapi.json PUT /admin/fiscal-groups/{id} # Update category (productId cannot be sent in body) Source: https://docs.x-mart.io/api-reference/fiscal/put-admin-product-fiscal-categories-productid api-reference/openapi.json PUT /admin/product-fiscal-categories/{productId} # Orders - Payment Information Source: https://docs.x-mart.io/api-reference/fulfillment/getpay GET /api/order/infoPayments Oauth authentication with client credentials # Pickup Orders - Dispatched Source: https://docs.x-mart.io/api-reference/fulfillment/postdispatched POST /api/order/dispatched Oauth authentication with client credentials # Orders - Status Change Source: https://docs.x-mart.io/api-reference/fulfillment/poststatus POST /api/order/status Oauth authentication with client credentials # Registers tracking information for a specific order Source: https://docs.x-mart.io/api-reference/fulfillment/posttrack POST /api/order/tracking Record tracking information for a specific order # Orders - Transfer Source: https://docs.x-mart.io/api-reference/fulfillment/puttransfer PUT /api/order/transfer Autenticación oauth con client credentials # Get Order Source: https://docs.x-mart.io/api-reference/injection/get GET /order/{orderId} Gets detailed information of a specific order by its ID, including products, pricing, client details, store info, shipping, payments, marketing and additional info. # New Order Webhook Source: https://docs.x-mart.io/api-reference/injection/postorder POST /domain-cliente/webhook/new-order This service will need to be implemented on the client side so that Trade can consume it. This will serve to notify the client every time a new order entered event occurs. # Create Stores and Sales Channels Source: https://docs.x-mart.io/api-reference/v3/channels-stores/post POST /v3/channels-stores This endpoint allows registering stores and sales channels in the system. Important!: Each request sent is processed as a new configuration, so if a store, sales channel, warehouse, etc. is not sent, its entire configuration will be deleted # Get Synchronization Report Source: https://docs.x-mart.io/api-reference/v3/lists/get GET /v3/lists/sync-summary/lists Allows obtaining a detailed report of: synchronization status, categories, products, modifiers, modifier options, errors and warnings of the last synchronization of a store # This endpoint allows registering or editing a list in the system Source: https://docs.x-mart.io/api-reference/v3/lists/put PUT /v3/lists/{listId} This endpoint allows you to register or edit a list in the system. Important: Each submitted request is processed as a new configuration, so if a product, category, modifier, etc. is not sent all your configuration will be deleted # This endpoint allows adding a list to the system Source: https://docs.x-mart.io/api-reference/v3/products/post POST /api/v3/products This endpoint allows you to add a list in the system. Important: Each submitted request is processed as a new configuration, so if a product, category, modifier, etc. is not sent all your configuration will be deleted. # This endpoint allows updating product information Source: https://docs.x-mart.io/api-reference/v3/products/put PUT /api/v3/products/{vendorId} This endpoint allows you to update product information # This endpoint allows registering or editing a list in the system Source: https://docs.x-mart.io/api-reference/v3/products/putpro PUT /api/v3/products/{update} This endpoint updates information for an existing product # Get stores by brand Source: https://docs.x-mart.io/api-reference/v3/stores/get GET /v3/stores This endpoint allows listing the stores of a brand registered in the system # Get store by id Source: https://docs.x-mart.io/api-reference/v3/stores/getId GET /v3/stores/{storeId} This endpoint allows obtaining information about a store registered in the system # Change store status Source: https://docs.x-mart.io/api-reference/v3/stores/put PUT /v3/stores/{storeId} This endpoint changes the status of a store in the system # Channels Source: https://docs.x-mart.io/ingles/Concepts/Channels Discover what channels are to achieve a successful synchronization Refers to the sales channel of the store, such as delivery, pickup, or any other means through which products are sold to customers. # Stores Source: https://docs.x-mart.io/ingles/Concepts/Stores Discover what stores are to achieve a successful synchronization Refers to the configuration of the commercial establishment or store, including details such as operating hours, names, address, and any other relevant information for its identification and operation. # List Source: https://docs.x-mart.io/ingles/Concepts/list Discover what lists are to achieve a successful synchronization The payload of the menu, meaning the configuration of products with their prices, images, taxes, and other necessary details for correct display and management. # Our API Source: https://docs.x-mart.io/ingles/Our API Learn about external client integration, store and list overview, and discover v3 injection and status changes ## 1. External client integration How to obtain an OAuth client? NOTE: Before requesting an OAuth client, it is necessary to have established a commercial agreement with Trade. Once this step is completed and the required information detailed below is gathered, you can start the account configuration process using the designated channels provided by X-Mart. Information needed to create an OAuth client: | Data | Required Information | Description | Utility | | ----------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | | **Country (required)** | Name | Name of the country where the application or website will operate. | Necessary for creating delivery addresses, billing information, etc. | | **Allow invoices as final consumer (required)** | YES, NO | Show forms for entering billing information | Request billing information before making a purchase. | | **City(ies) (required)** | Name - Latitude - Longitude | List of cities. | In Pickup allows obtaining the city's stores, locates the delivery address. | | **Sector(s) (required)** | Name - Latitude - Longitude - City | List of sectors. | Along with the city, allows locating the delivery address, necessary for creating delivery addresses. | | **Brand(s) (required)** | Brand name (Vendor) - Brief brand description - Unique brand identifier | List of brands. | Necessary for creating stores, sales channels, and lists. | | **Brand logo(s) (optional)** | Compressed file with brand logos (jpg/png), each image file must have the brand name. | Compressed file of brand images. | In future versions, the brand logo may be displayed. | | **Zones (required)** | kml, kmz, csv files | Files reflecting the polygons of the coverage areas. | Necessary to get the nearest store. | | **List of zones and stores (required)** | Name, identifier or store code - Coverage zone - City | List reflecting the relationship between coverage zone and store. | List used by Trade for configuring zones by store. | ## 2. Overview of Stores and Lists X-Mart provides a series of API endpoints that facilitate the management and synchronization of stores, sales channels, and lists within the platform. Below is a summary of the main endpoints available: ### Stores and Sales Channels This endpoint allows you to retrieve a list of stores associated with a specific brand. It is useful for getting an overview of all operational locations under a brand. This endpoint is used to add new stores and sales channels to the system. It facilitates the efficient expansion and updating of the store network. Allows you to retrieve specific details of a store based on its unique identifier. It is essential for the management and updating of precise information for each individual store. With this endpoint, you can modify the operational status of a store (e.g., active or inactive). It is crucial for keeping the store's availability up-to-date in real-time. ### Lists This endpoint provides a detailed report of the data synchronization, allowing you to monitor and verify the status of the synchronizations performed. This endpoint is used to add new stores and sales channels to the system. It facilitates the efficient expansion and updating of the store network. This set of endpoints ensures comprehensive and efficient management of store, sales, and list operations within X-Mart, offering robust tools for real-time control and monitoring. ## 3. Explanation of v3 injection X-Mart's Service Catalog includes a series of methods that facilitate the management and synchronization of data on the platform. Below is a summary of the main endpoints available: Token Retrieval This endpoint allows obtaining an authentication token necessary to access other services on the platform. It is essential to ensure that all interactions with the API are secure and authorized. New Order Webhook This endpoint is used to receive notifications of new orders. It allows external systems to integrate with X-Mart to process and manage orders in real-time. Order Retrieval This endpoint allows retrieving specific details of an order based on its unique identifier. It is crucial for the management and tracking of orders, ensuring that each transaction is recorded and can be consulted at any time. ## 4. Fulfillment (status changes) X-Mart provides a series of API endpoints that facilitate the management and processing of orders, ensuring an efficient flow from order placement to fulfillment. Below is a summary of the main endpoints available: This endpoint allows obtaining an authentication token using a registered client. It is essential to ensure that all interactions with the API are secure and authorized. This endpoint is used to redeem a local coupon using a UID (Unique Identifier) and a promotion code. It facilitates the application of discounts and promotions on customer orders. This endpoint is crucial for keeping customers informed about the status and location of their orders in real-time. It is vital for managing and updating the status of orders as they progress through the fulfillment process. This endpoint is essential for managing logistics and ensuring that orders are delivered efficiently. It helps coordinate the collection of orders by customers and ensures the pickup process runs smoothly. This endpoint is important for verifying and managing the payments made by customers, ensuring that all transactions are accurate and correctly recorded. # Get Token Source: https://docs.x-mart.io/ingles/api-reference/authentication/login/post POST /authentication/login This endpoint allows obtaining the access token for OAuth2 clients # Order integration Guide Source: https://docs.x-mart.io/ingles/essentials/Order integration Guide ## Overview Use the Orders API to ingest and manage incoming orders from X-Mart. The API includes a webhook for real-time notifications of new orders. Once you have correctly configured your webhook URL and menu, you can retrieve and accept orders using the endpoints provided in the Orders API. ### Understanding the Order Flow To successfully integrate orders, it is essential to follow the X-Mart order integration flow shown in the diagram below. Study the diagram carefully and ensure you understand each step before proceeding. This will ensure proper implementation and functionality of your integration. Diagram Placeholder ### Order Notifications The Orders API sends notifications to the webhook configured in your account whenever an order is placed. These notifications provide real-time updates for order ingestion. Key points to remember: • Your service (a single webhook URL) can receive webhooks for orders across multiple stores. • Ensure your webhook is capable of processing these notifications efficiently to avoid delays or errors. Check the full guide on web services injection Are you ready? Let's create your account at X-Mart 🚀 # Authentication Source: https://docs.x-mart.io/ingles/essentials/auth ```bash POST theme={null} https://api.artisn.desarrollo-redbrand.com/api/authentication/login ``` ## Requirements Access to this API may require prior approval and configuration. It is recommended to review the getting started guides before integration. ## Request Parameters Requests must be sent in application/json format and should include the following parameters: | **Key** | **Type** | **Description** | | --------------- | -------- | -------------------------------------------------------------- | | `client_id` | `string` | Unique identifier for the client application. | | `client_secret` | `string` | Secret key for the client application used for authentication. | | `grant_type` | `string` | Grant type used for authentication. | ## Example Request ```bash Example request theme={null} curl --request POST \ --url https://api.artisn.desarrollo-redbrand.com/api/authentication/login \ --header 'Content-Type: application/json' \ --data '{ "client_id": "", "client_secret": "", "grant_type": "" }' ``` ## Example Response ```bash Example response theme={null} { "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" } ``` ## Response Fields | **Key** | **Type** | **Description** | | ------------- | -------- | ------------------------------------------------------------------------- | | `accessToken` | `string` | Generated access token, used to authenticate against protected endpoints. | ## Using the Token The obtained accessToken must be sent in the request header when calling protected endpoints. # Next Steps See the [Store Integration Guide](/essentials/stores%20integration%20Guide) for steps to construct your menu. # Menu integration Guide Source: https://docs.x-mart.io/ingles/essentials/menu integration Guide # Overview Create and update menus using the endpoints of the **V3 Lists API**. Each store can have its own individually configurable menu. **Product** Displayed as any item a user can select from a store's menu, including desserts, drinks, and condiments. **Category** Groups one or more products, such as Add-ons, Main Dishes, and Drinks. **Modifier Groups** Groups modifiers that can be selected as customizations under a main item. For example, the modifier group "Drink Flavor" contains eligible items like strawberry, lemon, and orange as options. **Catalogue (Channel)** Groups one or more categories from a store. It allows referencing two types of fulfillment: Pickup and Delivery. ![Menu API Diagram](https://s3.us-east-1.amazonaws.com/admin.kfc.production/menuintegration.jpeg) # Components * **Get Synchronization Report (GET)** This endpoint provides a detailed report of the data synchronization, allowing you to monitor and verify the status of the synchronizations performed. * **Register or Edit a List (PUT)** This endpoint is used to add new stores and sales channels to the system. It facilitates the efficient expansion and updating of the store network. # FAQ **¿What specifications must menu item images meet for successful processing?** Images must be sized 744px x 744px. **¿Can I set specific availability schedules for categories, items, or modifiers?** Yes, it is possible to set availability schedules for both **categories** and **items**. You must use the attribute *“schedules”:\[ ]* for both cases. In the case of **modifiers**, it is not possible to assign a schedule. ```bash Example for category theme={null} { "categories": [ { "name": "DINNER", "images": [ { "fileUrl": "https://samercadito.blob.core.windows.net/imagenesv3/C761AD4F-FDA8-EF11-9C36-E18191D08780_744x744.png", "imageCategoryId": "category" } ], "position": 480, "schedules": [ { "day": "FRIDAY", "endTime": "16:00", "startTime": "12:00" }, { "day": "MONDAY", "endTime": "16:00", "startTime": "12:00" } ], "displayInList": true, "productListing": [ { "position": 0, "productId": 63897 } ], "productCategoryId": "C761AD4F-FDA8-EF11-9C36-E18191D08780" } ] } ``` ```bash Example for item theme={null} { "name": "ORANGE JUICE", "type": "PRODUCT", "active": true, "images": [ { "fileUrl": "https://samercadito.blob.core.windows.net/imagenesv3/domicilio_533_744x745_1721068779.png", "imageCategoryId": "product" } ], "priceInfo": { "price": 4.65, "pointPrice": 200 }, "productId": 533, "schedules": [ { "day": "FRIDAY", "endTime": "23:59", "startTime": "05:00" }, { "day": "MONDAY", "endTime": "23:59", "startTime": "05:00" } ], "upselling": [ "62840", "62865" ], "description": "Orange juice", "productModifiers": [ { "position": 1, "modifierId": "43152BBA-EE67-EB11-80F4-000D3A019254" } ] } ``` # Next Steps See the [Order Integration Guide](/essentials/Order%20integration%20Guide) for steps to construct your menu. # Store Integration Guide Source: https://docs.x-mart.io/ingles/essentials/stores integration Guide # Overview Manage your ecommerce stores using the **API V3 endpoints** for lists. You can create, delete, and update stores, as well as configure independent schedules for each one. # Components * **Get stores by brand (GET)** This endpoint allows you to retrieve a list of stores associated with a specific brand. It is useful for getting an overview of all operational locations under a brand. * **Create Stores and Sales Channels (POST)** This endpoint is used to add new stores and sales channels to the system. It facilitates the efficient expansion and updating of the store network. * **Get store by ID (GET)** Allows you to retrieve specific details of a store based on its unique identifier. It is essential for the management and updating of precise information for each individual store. * **Change store status (PUT** With this endpoint, you can modify the operational status of a store (e.g., active or inactive). It is crucial for keeping the store's availability up-to-date in real-time. # Next Steps Please refer to the [Menu Integration guide](/essentials/menu%20integration%20Guide) to see the steps for building your menu. # FAQ **If I send a synchronization and have new changes, is it necessary to perform a full store synchronization or just a menu synchronization?** To reflect the new changes, it is sufficient to send a menu synchronization if the adjustments only affect the menu items. However, if the changes also include modifications to the stores (such as hours, locations, etc.), then a full store synchronization will be required. # Introduction Source: https://docs.x-mart.io/ingles/introduction The X-Mart APIs enable customers to programmatically manage **stores**, **lists**, **and** **orders** on the X-Mart platform, providing a seamless and efficient way to integrate your ERP or POS with our headless commerce solution. Hero Light Hero Dark # Integration Process Overview X-Mart is a **headless commerce platform** with a robust integrations API that simplifies the synchronization and management process from an external ERP or POS system. By leveraging our APIs, you can automate and centralize your operations, ensuring an **updated and continuous flow of information** across your systems. Hero Light Hero Dark **Note:** This integration workflow facilitates centralized and efficient process management, ensuring a seamless exchange of information. Are you ready? Let's create your account at X-Mart 🚀 # Key Integration Steps Here’s a brief overview of the APIs involved in the integration process: ### 1. Auth API * Manage authentication and secure access to the X-Mart APIs. * Generate and refresh tokens for authorized API requests. ### 2. Stores API * Create, update, and manage stores and sales channels in the X-Mart platform. * Retrieve detailed information about stores and modify their status programmatically. ### 3. Lists API * Synchronize and manage product lists, including categories, products, modifiers, and options. * Access detailed reports on synchronization status, errors, and warnings to ensure data accuracy. ### 4. Orders API * Ingest and manage incoming orders with real-time webhook notifications. * Update order statuses to reflect operational progress. # Next Steps To get started with the X-Mart APIs: 1. Familiarize yourself with the authentication process in the **Auth API** section. 2. Begin configuring your stores using the **Stores API**. 3. Synchronize your product data using the **Lists API**. 4. Set up and test your order integration with the **Orders API**. Explore the rest of the documentation for detailed guides, examples, and best practices for each API. Find a guide to integrate X-Mart with your e-commerce platforms # Quickstart Source: https://docs.x-mart.io/ingles/quickstart How to configure the Xmart account ### Set up your account If you haven't already, register to get an X-Mart account and get started. You can create an account [in our dashboard](https://app.x-mart.io/auth/signin). ### How to set up You can send your menu synchronizations taking into account [the necessary configuration](https://docs.x-mart.io/api-reference/authentication/login/post) provided by X-Mart. Make sure to follow all the steps and specific settings to ensure proper integration. It is possible to process your orders through our injection web service. We have included a notification webhook to inform you in real-time about new orders.