{
  "openapi": "3.0.3",
  "info": {
    "title": "Учет3Д: приём заявок с сайта",
    "version": "1.0.0",
    "description": "Первый этап обмена: внешний сайт создаёт заявку в общем списке Учет3Д. Мастер проверяет состав, цены и доставку и сам подтверждает заказ. Приём не создаёт заказ, клиента, оплату или списание склада. Базовый обмен входит в обычную подписку без доплаты. Ключи чтения не дают права создавать заявки. Начальное описание 03.11.2026."
  },
  "servers": [
    {
      "url": "https://xn--3-htbb6cdy.xn--p1ai",
      "description": "учет3д.рф"
    }
  ],
  "externalDocs": {
    "description": "Настройка подключения, Tilda и примеры",
    "url": "https://xn--3-htbb6cdy.xn--p1ai/help/integrations/incoming-orders"
  },
  "tags": [
    {
      "name": "Заявки",
      "description": "До 60 обращений в минуту на ключ и мастерскую. Тем же ключом обращайтесь последовательно. До 100 новых заявок за 24 часа вместе с витриной. До 20 действующих подключений. Ключи создаёт владелец в настройках; показ один раз, замена и отзыв доступны отдельно."
    }
  ],
  "paths": {
    "/api/public/v1/order-requests": {
      "post": {
        "tags": [
          "Заявки"
        ],
        "security": [
          {
            "IncomingBearer": []
          }
        ],
        "operationId": "createOrderRequest",
        "summary": "Передать заявку с сайта",
        "description": "Тело до 256 КБ. Сохраните externalId и Idempotency-Key до отправки. Повторяйте неизменённое тело с теми же значениями после потери ответа, 429 или 503. Повтор принятой покупки возвращает исходное подтверждение и не создаёт вторую заявку, даже после замены ключа либо удаления заявки. Для новой покупки используйте новые значения. История отдельна для каждого подключения. На одну заявку сохраняется до 20 различных ключей повтора. Новый 21-й ключ отклоняется с 409 INCOMING_REPEAT_KEYS_LIMIT; известные ключи продолжают работать. Используйте исходный ключ для повторов.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 160,
              "minLength": 1
            },
            "description": "Постоянный ключ повторной отправки одной покупки. Не генерировать заново при повторе. На одну заявку допускается не более 20 различных значений. Неизменный ключ можно повторять и после достижения этого предела."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateRequest"
              },
              "example": {
                "externalId": "site-order-1042",
                "customer": {
                  "name": "Покупатель",
                  "email": "buyer@example.com"
                },
                "items": [
                  {
                    "sku": "BOX-01",
                    "quantity": 2,
                    "offeredUnitPriceMinor": 45000
                  }
                ],
                "currency": "RUB",
                "delivery": {
                  "method": "Курьер",
                  "address": "Адрес покупателя",
                  "recipient": "Покупатель",
                  "offeredAmountMinor": 20000
                },
                "comment": "Связаться перед доставкой"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Новая заявка сохранена.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Received"
                },
                "example": {
                  "requestId": "11111111-1111-4111-8111-111111111111",
                  "receiptId": "22222222-2222-4222-8222-222222222222",
                  "externalId": "site-order-1042",
                  "status": "received",
                  "issues": []
                }
              }
            }
          },
          "200": {
            "description": "Повтор: исходное подтверждение приёма.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Received"
                },
                "example": {
                  "requestId": "11111111-1111-4111-8111-111111111111",
                  "receiptId": "22222222-2222-4222-8222-222222222222",
                  "externalId": "site-order-1042",
                  "status": "received",
                  "issues": []
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "413": {
            "$ref": "#/components/responses/Error413"
          },
          "415": {
            "$ref": "#/components/responses/Error415"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          }
        }
      }
    },
    "/api/public/v1/order-requests/status": {
      "get": {
        "tags": [
          "Заявки"
        ],
        "security": [
          {
            "IncomingBearer": []
          }
        ],
        "operationId": "getOrderRequestStatusByExternalId",
        "summary": "Проверить отправку по внешнему номеру",
        "description": "Только результат своего подключения, без контактов, состава и номера заказа. В ответе status отражает состояние заявки, orderCreated сообщает факт создания заказа.",
        "parameters": [
          {
            "name": "externalId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 160,
              "minLength": 1
            },
            "description": "Тот же внешний номер, что при создании. Закодируйте его как значение параметра URL."
          }
        ],
        "responses": {
          "200": {
            "description": "Состояние заявки.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReceiptStatus"
                },
                "example": {
                  "requestId": "11111111-1111-4111-8111-111111111111",
                  "receiptId": "22222222-2222-4222-8222-222222222222",
                  "externalId": "site-order-1042",
                  "status": "new",
                  "orderCreated": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          }
        }
      }
    },
    "/api/public/v1/order-requests/{receiptId}": {
      "get": {
        "tags": [
          "Заявки"
        ],
        "security": [
          {
            "IncomingBearer": []
          }
        ],
        "operationId": "getOrderRequestStatusByReceipt",
        "summary": "Проверить отправку по подтверждению приёма",
        "parameters": [
          {
            "name": "receiptId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "receiptId из ответа приёма."
          }
        ],
        "responses": {
          "200": {
            "description": "Состояние заявки; removed означает удалённую заявку, подтверждение сохранено.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReceiptStatus"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          }
        }
      }
    },
    "/api/public/v1/order-requests/tilda": {
      "post": {
        "tags": [
          "Заявки"
        ],
        "security": [
          {
            "TildaKey": []
          },
          {
            "IncomingBearer": []
          }
        ],
        "operationId": "createTildaOrderRequest",
        "summary": "Принять форму Tilda",
        "description": "Ключ в X-Uchet3D-Key. Внешний номер tilda:{formid}:{tranid}. Товары передаются массивом или JSON-строкой массива; внешний код товара совпадает с артикулом Учет3Д. Нет состава или не найден артикул: заявка сохраняется в общем списке с issues для ручной проверки. Только test=test отвечает без сохранения. Повтор формы возвращает исходное подтверждение, изменённое содержимое того же номера даёт 409. Не передавайте cookies покупателей.",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/TildaForm"
              },
              "example": {
                "tranid": "467251:8442970",
                "formid": "form48844953",
                "Name": "Покупатель",
                "Email": "buyer@example.com",
                "products": "[{\"externalid\":\"BOX-01\",\"name\":\"Коробка\",\"quantity\":2,\"price\":450}]"
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TildaForm"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Форма сохранена, повтор приёма либо тест подключения.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Received"
                    },
                    {
                      "$ref": "#/components/schemas/TildaTest"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "413": {
            "$ref": "#/components/responses/Error413"
          },
          "415": {
            "$ref": "#/components/responses/Error415"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "IncomingBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Ключ входящих заявок Учет3Д",
        "description": "Отдельный отзываемый ключ с правом create_order_requests. Только на сервере. Не передавать в URL. Ключ чтения не подходит."
      },
      "TildaKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Uchet3D-Key",
        "description": "Тот же отдельный ключ для приёмщика Tilda. Выберите передачу в заголовке."
      }
    },
    "schemas": {
      "Customer": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 80,
            "minLength": 1
          },
          "phone": {
            "type": "string",
            "maxLength": 50,
            "description": "Не менее пяти цифр, до 50 символов. Разрешены начальный +, пробелы, скобки, точка и дефис."
          },
          "email": {
            "type": "string",
            "maxLength": 200
          },
          "contact": {
            "type": "string",
            "maxLength": 200
          }
        },
        "required": [
          "name"
        ],
        "anyOf": [
          {
            "required": [
              "phone"
            ],
            "properties": {
              "phone": {
                "type": "string",
                "minLength": 1
              }
            }
          },
          {
            "required": [
              "email"
            ],
            "properties": {
              "email": {
                "type": "string",
                "minLength": 1
              }
            }
          },
          {
            "required": [
              "contact"
            ],
            "properties": {
              "contact": {
                "type": "string",
                "minLength": 1
              }
            }
          }
        ],
        "description": "Имя и хотя бы один контакт. Строки обрезаются по краям; строки со служебными символами не принимаются."
      },
      "Delivery": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "method": {
            "type": "string",
            "maxLength": 120
          },
          "address": {
            "type": "string",
            "maxLength": 500
          },
          "recipient": {
            "type": "string",
            "maxLength": 160
          },
          "pickupPoint": {
            "type": "string",
            "maxLength": 200
          },
          "offeredAmountMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000000000,
            "description": "Предложенная сумма в сотых долях денежной единицы. Для RUB 45000 означает 450 рублей. Не создаёт оплату."
          }
        }
      },
      "RequestItem": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "sku": {
            "type": "string",
            "maxLength": 120,
            "minLength": 1,
            "description": "Артикул действующего товара этой мастерской. Повторяющиеся артикулы объедините в одну позицию."
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "maximum": 999
          },
          "offeredUnitPriceMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000000000,
            "description": "Предложенная сумма в сотых долях денежной единицы. Для RUB 45000 означает 450 рублей. Не создаёт оплату."
          }
        },
        "required": [
          "sku",
          "quantity"
        ]
      },
      "CreateRequest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "externalId": {
            "type": "string",
            "maxLength": 160,
            "minLength": 1,
            "description": "Постоянный уникальный номер покупки в пределах подключения."
          },
          "customer": {
            "$ref": "#/components/schemas/Customer"
          },
          "items": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/RequestItem"
            }
          },
          "currency": {
            "type": "string",
            "maxLength": 3,
            "minLength": 3,
            "pattern": "^[A-Za-z]{3}$",
            "description": "Трёхбуквенный код. Приводится к верхнему регистру и должен совпадать с валютой мастерской."
          },
          "delivery": {
            "$ref": "#/components/schemas/Delivery"
          },
          "comment": {
            "type": "string",
            "maxLength": 1000
          }
        },
        "required": [
          "externalId",
          "customer",
          "items",
          "currency"
        ]
      },
      "Issue": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "field": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "field",
          "code",
          "message"
        ]
      },
      "Received": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "receiptId": {
            "type": "string",
            "format": "uuid"
          },
          "externalId": {
            "type": "string",
            "maxLength": 160
          },
          "status": {
            "type": "string",
            "enum": [
              "received"
            ]
          },
          "issues": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Issue"
            }
          }
        },
        "required": [
          "requestId",
          "receiptId",
          "externalId",
          "status",
          "issues"
        ]
      },
      "ReceiptStatus": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "receiptId": {
            "type": "string",
            "format": "uuid"
          },
          "externalId": {
            "type": "string",
            "maxLength": 160
          },
          "status": {
            "type": "string",
            "enum": [
              "new",
              "accepted",
              "declined",
              "removed"
            ]
          },
          "orderCreated": {
            "type": "boolean"
          }
        },
        "required": [
          "requestId",
          "receiptId",
          "externalId",
          "status",
          "orderCreated"
        ]
      },
      "Error": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "error": {
            "type": "string",
            "description": "Сообщение для человека."
          },
          "code": {
            "type": "string",
            "description": "Постоянный код причины."
          },
          "field": {
            "type": "string",
            "description": "Путь к неверному полю, если применимо."
          },
          "requestId": {
            "type": "string",
            "format": "uuid",
            "description": "Номер обращения для разбора отказа; это не номер созданной заявки."
          }
        },
        "required": [
          "error",
          "code",
          "requestId"
        ]
      },
      "TildaProduct": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "externalid": {
            "type": "string",
            "maxLength": 120,
            "description": "Внешний код Tilda должен совпадать с артикулом Учет3Д."
          },
          "externalId": {
            "type": "string",
            "maxLength": 120
          },
          "sku": {
            "type": "string",
            "maxLength": 120
          },
          "name": {
            "type": "string",
            "maxLength": 200
          },
          "title": {
            "type": "string",
            "maxLength": 200
          },
          "quantity": {
            "oneOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ]
          },
          "qty": {
            "oneOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ]
          },
          "price": {
            "oneOf": [
              {
                "type": "number",
                "minimum": 0,
                "maximum": 100000000
              },
              {
                "type": "string"
              }
            ],
            "description": "Цена за штуку в основных денежных единицах, например 450.00 рублей."
          }
        }
      },
      "TildaForm": {
        "type": "object",
        "additionalProperties": true,
        "description": "Форма Tilda. Неизвестные служебные поля игнорируются. test=test проверяет подключение без заявки. Для обычной заявки нужны tranid, formid и хотя бы один контакт. Неполный состав сохраняется с замечаниями. Отметки платежа не проводят оплату.",
        "properties": {
          "test": {
            "type": "string",
            "enum": [
              "test"
            ]
          },
          "tranid": {
            "type": "string",
            "maxLength": 120
          },
          "formid": {
            "type": "string",
            "maxLength": 32
          },
          "Name": {
            "type": "string",
            "maxLength": 80
          },
          "Phone": {
            "type": "string",
            "maxLength": 50
          },
          "Email": {
            "type": "string",
            "maxLength": 200
          },
          "Contact": {
            "type": "string",
            "maxLength": 200
          },
          "Comments": {
            "type": "string",
            "maxLength": 1000
          },
          "currency": {
            "type": "string",
            "maxLength": 3
          },
          "products": {
            "oneOf": [
              {
                "type": "array",
                "maxItems": 100,
                "items": {
                  "$ref": "#/components/schemas/TildaProduct"
                }
              },
              {
                "type": "string",
                "description": "JSON-строка массива товаров."
              }
            ]
          },
          "payment": {
            "oneOf": [
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "string"
              }
            ],
            "description": "Совместимый контейнер products/delivery/currency из формы. Не проводит оплату."
          },
          "delivery": {
            "oneOf": [
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "string"
              }
            ]
          },
          "Delivery": {
            "type": "string",
            "maxLength": 120
          },
          "Address": {
            "type": "string",
            "maxLength": 500
          }
        },
        "anyOf": [
          {
            "required": [
              "test"
            ]
          },
          {
            "required": [
              "tranid",
              "formid"
            ],
            "anyOf": [
              {
                "required": [
                  "Phone"
                ]
              },
              {
                "required": [
                  "Email"
                ]
              },
              {
                "required": [
                  "Contact"
                ]
              },
              {
                "required": [
                  "phone"
                ]
              },
              {
                "required": [
                  "email"
                ]
              }
            ]
          }
        ]
      },
      "TildaTest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "test": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        },
        "required": [
          "success",
          "test"
        ]
      }
    },
    "responses": {
      "Error401": {
        "description": "Ключ не передан, неверен, заменён или отозван.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "Ключ не передан, неверен, заменён или отозван.",
              "code": "INCOMING_KEY_INVALID",
              "requestId": "33333333-3333-4333-8333-333333333333"
            }
          }
        }
      },
      "Error403": {
        "description": "Закончился действующий доступ мастерской.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "Закончился действующий доступ мастерской.",
              "code": "INCOMING_ACCESS_EXPIRED",
              "requestId": "33333333-3333-4333-8333-333333333333"
            }
          }
        }
      },
      "Error404": {
        "description": "Результат этой отправки не найден в подключении.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "Результат этой отправки не найден в подключении.",
              "code": "INCOMING_RECEIPT_NOT_FOUND",
              "requestId": "33333333-3333-4333-8333-333333333333"
            }
          }
        }
      },
      "Error409": {
        "description": "Внешний номер или ключ повтора использован с другим содержимым (INCOMING_REPEAT_CONFLICT), либо для одной заявки уже привязано 20 различных ключей и передан ещё один новый (INCOMING_REPEAT_KEYS_LIMIT). Ранее привязанные ключи продолжают работать.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "examples": {
              "conflict": {
                "summary": "Содержимое отличается от ранее принятого",
                "value": {
                  "error": "Внешний номер или ключ повтора уже использован с другим содержимым.",
                  "code": "INCOMING_REPEAT_CONFLICT",
                  "requestId": "33333333-3333-4333-8333-333333333333"
                }
              },
              "repeatKeysLimit": {
                "summary": "Слишком много различных ключей у одной заявки",
                "value": {
                  "error": "Для повтора используйте прежний ключ Idempotency-Key. У одной заявки уже слишком много разных ключей.",
                  "code": "INCOMING_REPEAT_KEYS_LIMIT",
                  "field": "Idempotency-Key",
                  "requestId": "33333333-3333-4333-8333-333333333333"
                }
              }
            }
          }
        }
      },
      "Error413": {
        "description": "Тело больше 256 КБ либо в форме больше 1000 полей.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "Тело больше 256 КБ либо в форме больше 1000 полей.",
              "code": "INCOMING_BODY_TOO_LARGE",
              "requestId": "33333333-3333-4333-8333-333333333333"
            }
          }
        }
      },
      "Error415": {
        "description": "Неподдерживаемый Content-Type.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "Неподдерживаемый Content-Type.",
              "code": "INCOMING_CONTENT_TYPE",
              "requestId": "33333333-3333-4333-8333-333333333333"
            }
          }
        }
      },
      "Error422": {
        "description": "Неверные поля, JSON, артикул либо валюта. Заявка не создана. Код INCOMING_TOTAL_TOO_LARGE: сумма по ценам каталога превышает 999999999999.99 в валюте мастерской.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "Неверные поля, JSON, артикул либо валюта. Заявка не создана.",
              "code": "INCOMING_INVALID_FIELD",
              "requestId": "33333333-3333-4333-8333-333333333333"
            }
          }
        }
      },
      "Error429": {
        "description": "Предел обращений, параллельный запрос тем же ключом либо общий суточный предел заявок.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "Предел обращений, параллельный запрос тем же ключом либо общий суточный предел заявок.",
              "code": "INCOMING_RATE_LIMIT",
              "requestId": "33333333-3333-4333-8333-333333333333"
            }
          }
        },
        "headers": {
          "Retry-After": {
            "description": "Через сколько секунд повторить тот же запрос.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        }
      },
      "Error503": {
        "description": "Временная недоступность. Повторите неизменённый запрос с теми же номерами.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "Временная недоступность. Повторите неизменённый запрос с теми же номерами.",
              "code": "INCOMING_UNAVAILABLE",
              "requestId": "33333333-3333-4333-8333-333333333333"
            }
          }
        },
        "headers": {
          "Retry-After": {
            "description": "Через сколько секунд повторить тот же запрос.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        }
      }
    }
  }
}
