New Status in the API: How Not to Accidentally Close an Order

Служба доставки добавила статус «ожидает уточнения адреса». Магазин знает только «создан», «в пути» и «доставлен». Старый обработчик не находит совпадения и ставит значение по умолчанию — «доставлен». Запрос успешно разобран, исключений нет, покупателю уже уходит поздравление. Формально программа отработала; смысл события она придумала сама.

Это учебный сценарий, а не описание конкретной службы. Его полезный вывод: неизвестное значение должно оставаться различимой неопределённостью. Получатель может сохранить событие для разбора, но не должен выдавать отсутствие правила сопоставления за подтверждённый бизнес-результат.

Дополнительное поле с комментарием иногда можно игнорировать без изменения решения. Новое значение поля статуса может определять само решение: отгружать ли товар, закрывать ли заказ, уведомлять ли покупателя. Правило «терпимо относимся к новым данным» не отвечает на вопрос, что делать с неизвестным управляющим значением.

Рекомендации Google AIP-180 отдельно предупреждают о новых значениях перечислений в ответах: старый клиент может обработать их неправильно. Это руководство по проектированию API, а не обещание совместимости любого внешнего сервиса. Для конкретной интеграции возможность расширения списка и поведение клиента нужно выяснять по её контракту.

Если проверка JSON Schema ограничивает поле через enum, значение вне списка не проходит такую проверку. Это ожидаемая работа закрытого набора. Снятие ограничения позволит прочитать строку, но не создаст корректного соответствия внутреннему статусу. Успешная валидация формы и понимание состояния — разные этапы.

Предположим, внешний сервис прислал учебный код address_check. Получатель сохраняет именно этот код, идентификатор внешней отправки, время и идентификатор события, если он предусмотрен источником. Отдельно фиксирует результат сопоставления: правило пока отсутствует. Внутренний подтверждённый статус заказа и внешний необработанный сигнал не следует сливать в одно поле.

Что останавливать, зависит от последствий. Для нашего сценария разумно не завершать доставку и не отправлять уведомление об успешном вручении до выяснения смысла. При этом нет необходимости автоматически блокировать весь магазин: другие заказы и независимые операции могут продолжаться, если архитектура допускает такую изоляцию.

Молчаливое сохранение прежнего статуса тоже недостаточно. Оператор должен видеть, что получены новые данные, которые пока не применены. Иначе «в пути» будет выглядеть как свежая подтверждённая информация, хотя система уже встретила исключение. Нужны заметный сигнал, срок разбора и ответственный, а не вечное спокойствие зелёной карточки.

Получатель уведомления должен соблюдать правила повторов конкретного API. Если событие надёжно сохранено для дальнейшего разбора, протокол может позволять подтвердить получение, оставив бизнес-обработку незавершённой. Если же событие не сохранено, положительный ответ может лишить систему возможности получить его снова. Универсального HTTP-кода для любой службы здесь нет.

Отказ с последующими повторами тоже не исправит неизвестный словарь сам по себе. Один и тот же новый статус может приходить часами, занимая очередь. Поэтому заранее разделяют временную недоступность обработчика и отсутствие правила сопоставления. Во втором случае важны сохранённый исходник, видимость проблемы и контролируемое возвращение к обработке после исправления.

В журнал диагностики не нужно копировать адрес и телефон покупателя ради названия статуса. Для первичного разбора обычно достаточно технических идентификаторов и кода состояния. Полный исходный документ, если его хранение необходимо, требует предусмотренного доступа и срока хранения. Диагностическая запись не должна становиться второй бесконтрольной базой заказов.

Сначала выясняют значение нового состояния по документации поставщика. «Адрес уточняется» не равно «доставка отменена» и не равно «доставлено». Иногда прямого внутреннего аналога нет: тогда понадобится отдельное состояние интеграции или дополнительный признак, а не ближайшее слово из выпадающего списка.

После согласования проверяют новую ветку на сохранённых обезличенных примерах в тестовой среде. Повторное применение должно учитывать уже достигнутое состояние и порядок событий: старое уведомление об уточнении адреса не должно отменять более позднее подтверждение вручения. Правило версий или порядка выбирают по возможностям источника, не по порядку строк в журнале.

В набор приёмки стоит включить известный код, новый непустой код, пустое значение и отсутствие поля. Затем — повтор одного события и его получение после более нового. Это разные случаи; общий результат «не упало» не доказывает правильность. Для каждого случая заранее задают, что сохраняется, какое действие разрешено и что увидит оператор.

В интеграции магазина с 1С или доставкой полезно требовать отдельный ответ на вопрос: «Что произойдёт завтра, когда словарь источника расширится?» Хороший ответ оставляет проверяемый исходный сигнал и ограничивает последствия неопределённости. Он не обещает угадать новый статус по названию.

The delivery service added the status "awaiting address clarification." The store knows only "created," "in transit," and "delivered." The old handler finds no match and assigns the default value—"delivered." The request parses successfully with no exceptions, and a congratulatory message is already sent to the buyer. Formally, the program executed; however, it invented the meaning of the event itself.

This is a training scenario, not a description of a specific service. Its useful takeaway: an unknown value must remain a distinguishable uncertainty. The recipient may save the event for later analysis, but must not treat the absence of a matching rule as a confirmed business outcome.

An additional comment field can sometimes be ignored without changing the decision. The new status field value may itself determine the decision: whether to ship the product, close the order, or notify the buyer. The rule 'be tolerant of new data' does not answer what to do with an unknown control value.

Google AIP-180 recommendations specifically warn about new enumeration values in responses: an older client may process them incorrectly. This is an API design guide, not a guarantee of compatibility for any external service. For a specific integration, the ability to extend the list and the client behavior must be determined by its contract.

If JSON Schema validation restricts the field via enum, any value outside the list fails that validation. This is expected behavior for a closed set. Removing the restriction allows reading the string, but does not create a valid mapping to the internal status. Successful form validation and understanding the state are different stages.

Suppose an external service sends a test code address_check. The recipient saves exactly this code, the external shipment identifier, the timestamp, and the event identifier if the source provides one. Separately, it records the matching result: the rule is currently missing. Do not merge an internal confirmed order status with an external unprocessed signal into a single field.

What to stop depends on the consequences. For our scenario, it is reasonable to halt delivery and refrain from sending a successful delivery notification until the meaning is clarified. There is no need to automatically block the entire store: other orders and independent operations can continue if the architecture allows such isolation.

Silently retaining the previous status is also insufficient. The operator must see that new data has been received but not yet applied. Otherwise, 'in transit' will appear as fresh confirmed information, even though the system has already encountered an exception. A visible signal, a review deadline, and a responsible person are needed, not perpetual calm on a green card.

The notification recipient must adhere to the retry rules for the specific API. If the event is reliably persisted for later processing, the protocol may allow acknowledging receipt while leaving business processing incomplete. However, if the event is not persisted, a positive response could deprive the system of the ability to retrieve it again. There is no universal HTTP status code for every service in this scenario.

A failure followed by retries will not fix an unknown dictionary on its own. The same new status can arrive for hours, clogging the queue. Therefore, temporary unavailability of the handler and the absence of a mapping rule must be distinguished in advance. In the latter case, preserving the original source, visibility of the issue, and controlled resumption of processing after the fix are critical.

There is no need to copy the buyer's address and phone number into the diagnostic log just for the status name. For initial analysis, technical identifiers and status codes are usually sufficient. The full original document, if storage is required, demands defined access controls and a retention period. A diagnostic record must not become a second uncontrolled order database.

First, determine the meaning of the new status from the provider's documentation. 'Address being clarified' is not equal to 'delivery cancelled' and is not equal to 'delivered'. Sometimes there is no direct internal equivalent: in that case, a separate integration status or an additional flag is needed, not the closest word from the dropdown list.

After agreement, test the new branch on saved anonymized examples in the staging environment. Reapplying must account for the already reached state and the order of events: an old notification about clarifying the address must not cancel a later confirmation of delivery. Choose a version rule or order based on the source's capabilities, not the order of lines in the log.

The acceptance test suite should include a known code, a new non-empty code, an empty value, and the absence of the field. Then, repeat one event and receive it after a newer one. These are different cases; a common result of 'it did not crash' does not prove correctness. For each case, define in advance what is saved, what action is allowed, and what the operator will see.

In integrating a store with 1C or a delivery service, it is useful to require a separate answer to the question: 'What will happen tomorrow when the source dictionary expands?' A good answer preserves a verifiable original signal and limits the consequences of uncertainty. It does not promise to guess a new status by name.