REST · JSON · Bearer · OpenAPI 3.0
REST API для enterprise клиентов
REST API, позволяющий вам подключить коммерческие предложения, заказы, статус производства, поставки и счета к вашему собственному операционному стеку — ERP, клиентский портал, сервис-деск. Документировано в OpenAPI 3.0 с примерами на curl, Python и Node.js. Доступ предоставляется клиентам с действующей программой и подписанным соглашением об использовании.
Основы: аутентификация, базовый URL, формат
API аутентитируется с bearer-токеном, который мы выдаём вам вместе с программой. Токен ротируется каждые девяносто дней или по вашему запросу. Базовый URL производственной среды — https://api.corp-merch.com.mx/v1. Базовый URL песочницы — https://sandbox.api.corp-merch.com.mx/v1. Песочница содержит фиктивные данные и обнуляется каждый понедельник в ноль часов GMT-6.
Формат обмена — JSON с UTF-8. Даты и время обрабатываются в ISO 8601 с таймзоной — мы предпочитаем YYYY-MM-DDTHH:MM:SS-06:00 для времени Мехико. Суммы в центах MXN — чтобы представить пятьдесят песо пятьдесят сентаво, вы отправляете 5050. Коды стран — ISO 3166-1 alpha-2 — MX для Мексики, US для США, CA для Канады.
Основные эндпоинты
API выставляет шесть блоков эндпоинтов. Блок предложений: POST /quotes для создания предложения, GET /quotes/{id} для деталей, POST /quotes/{id}/approve для одобрения, POST /quotes/{id}/reject для отклонения с обоснованием. Блок заказов: POST /orders для создания заказа из одобренного предложения, GET /orders/{id} для деталей, PATCH /orders/{id} для обновления разрешённых полей до производства, POST /orders/{id}/cancel для отмены до производства.
Блок статусов: GET /orders/{id}/status для полного статуса, GET /orders/{id}/status/history для истории с временными метками, GET /orders/{id}/documents для связанных документов. Блок отгрузок: GET /orders/{id}/shipments для списка отгрузок, GET /shipments/{id} для деталей, POST /shipments/{id}/confirm для подтверждения получения, когда клиент подписывает акт. Блок счетов: GET /orders/{id}/invoices для списка, GET /invoices/{id} для деталей с XML CFDI 4.0 и PDF. Блок каталога: GET /catalog/products для списка продуктов, GET /catalog/products/{id} для деталей с ценами и наличием.
Пример: создание коммерческого предложения
Для создания предложения отправляется POST запрос на /v1/quotes с bearer-токеном в заголовке Authorization и JSON-телом с продуктами, количествами, методом нанесения и сроками. Эндпоинт возвращает идентификатор предложения и деталь с ценами в центах MXN до НДС, разбитым НДС, итогом и сроком по линейке.
Минимальное тело предложения включает массив линеек с product_id, quantity, decoration с методомом — screen, dtf, embroidery, laser — и delivery_address с полным адресом. Для линеек с переменной персонализацией — номер сотрудника, индивидуальный размер — включается массив variables на линейку. Предложение выдаётся в течение минуты, когда каталог распознаёт продукт и адрес попадает в зону покрытия.
Пример: проверка статуса заказа
Для проверки статуса отправляется GET на /v1/orders/{id}/status с bearer-токеном. Эндпоинт возвращает текущий статус — created, approved, in_production, quality_check, packed, shipped, delivered, invoiced, closed, canceled — и процент продвижения по стадии. Ответ включает расчётную дату поставки на основе календаря клиента и мастерской.
Для тиражей с несколькими стадиями — раскрой, пошив, нанесение, упаковка, отгрузка, доставка — клиент получает разбивку по стадиям с процентом продвижения. Когда стадия задерживается, статус возвращает причину — нехватка сырья, несоответствие, ожидание подтверждения клиента — и обновлённую расчётную дату. Интеграция остаётся согласованной с webhooks, которые срабатывают при изменении статуса.
Обработка ошибок и повторы
Ошибки возвращаются со стандартными HTTP-кодами — 400 для неверного запроса, 401 для отсутствующего или неверного токена, 403 для запрещённого ресурса, 404 для ненайденного resource, 409 для конфликта состояния, 422 для ошибки валидации, 429 для превышения лимита, 500 для внутренней ошибки. Тело ошибки включает code с машиночитаемым кодом, message с человекочитаемым описанием и details с массивом полей в ошибке, где применимо.
Лимит частоты — шестьдесят запросов в минуту на токен и тысяча запросов в час на токен. Когда лимит превышен, эндпоинт возвращает 429 с заголовком Retry-After, указывающим секунды ожидания. Мы реализуем экспоненциальный бэкофф на клиенте с джиттером, чтобы избежать эффекта стада. Для клиентов с большим объёмом договариваемся о повышенном лимите в начале программы.
Лучшие практики интеграции
Мы рекомендуем три практики. Во-первых, используйте песочницу для разработки и тестирования перед выходом в продакшн. Песочница содержит фиктивные данные и обнуляется каждый понедельник. Во-вторых, подпишитесь на webhooks вместо опроса статуса — webhooks срабатывают при изменении статуса, без необходимости клиенту опрашивать. В-третьих, валидируйте подписи HMAC SHA-256 webhook'ов перед обработкой тела, чтобы подтвердить, что webhook приходит из API.
Для клиентов на serverless-стеках webhook'и подписывают тело и доставляются с заголовками временной метки и идентификатора события. Клиент должен валидировать подпись, временную метку — с допуском пять минут — и идентификатор, чтобы избежать дубликатов при повторе. Полная документация включает справочный раздел с доступными событиями и форматом тела.
Поддержка и наблюдаемость
Для клиентов с продуктовой интеграцией мы назначаем технического руководителя мастерской, который отвечает на вопросы интеграции в течение четырёх рабочих часов и участвует в сессиях парного программирования, когда требуется. Технический руководитель также обрабатывает инциденты — пропущенный webhook, расхождение между порталом и API, неожиданные ответы.
API публикует операционные метрики — доступность, латентность p95, частоту ошибок — на дашборде статуса, на который клиенты могут подписаться. Для клиентов со строгим SLA — банки, финтех, государство — мы предоставляем выделенный дашборд с метриками реального времени и прямым каналом коммуникации для критических инцидентов. Страница статуса доступна без аутентификации.
Запросите доступ к SDK
Если вашей технической команде нужен доступ к SDK для интеграции коммерческих предложений, заказов, статусов, поставок или счетов с вашим операционным стеком, давайте поговорим. Мы предоставим bearer-токен, доступ к песочнице и полную документацию в вашем формате.
REST API и SDK предоставляются клиентам с действующей программой и подписанным соглашением об использовании. Документация может обновляться без предварительного уведомления; о мажорных версиях сообщается за тридцать дней. Corp-Merch.MX — мексиканская мастерская корпоративного мерча; мы работаем независимо.