WA Lookup
Записи проверки регистрации проходят через состояния «завершено», «не определено» и «обновление»
На протяжении всего жизненного цикла результата разделяйте завершённые наблюдения и неразрешённые попытки.

Статус регистрации — это наблюдение, а не постоянная метка

Завершённая проверка регистрации в WhatsApp отвечает на вопрос, был ли один номер в формате E.164 зарегистрирован на зафиксированный момент проверки.

Результат может быть полезен сразу, но его не следует хранить как вечное свойство вроде phone.is_valid. Номера телефонов и регистрации на платформе могут меняться, а последующий технический сбой не отменяет ранее завершённый результат. Поэтому надёжная модель фиксирует и само решение, и контекст, в котором оно было получено.

WA Lookup возвращает информацию о регистрации синхронно. Это позволяет легко сохранить наблюдение ровно в тот момент, когда приложение его получает. При этом модель всё равно должна отличать завершённую проверку от запроса, который так и не дал решения о регистрации.

Минимальная полезная запись результата

Поле Пример Почему это важно
source_phone Исходный переданный текст Позволяет исправлять и проверять данные, не меняя источник
e164_phone +17253100591 Указывает нормализованное значение, которое фактически проверялось
service_type ws Указывает контракт результата
outcome completed Классификация вашего приложения: завершённый результат или неудачный запрос
registered true или false Хранит завершённый результат регистрации
received_at Метка времени приложения Фиксирует, когда пришёл синхронный ответ
api_code 0 Отделяет внешний результат API от наблюдения о регистрации

Задавайте registered только для завершённого решения. Если приложению нужна история ошибок, журналируйте HTTP-статус и код API отдельно; не превращайте такие ответы в ещё одно значение регистрации.

Точно сохраняйте три формы ответа

Документированный контракт предусматривает две формы завершённого результата и одну отдельную форму ошибки:

  1. Завершённый результат «зарегистрирован» — code=0 и data.registered=true.
  2. Завершённый результат «не зарегистрирован» — code=0 и data.registered=false.
  3. Нет решения — ненулевой код API без значения registered, которое можно сохранить.

Некорректный ввод, недостаточный баланс, ограничения параллелизма, тайм-ауты, техническое обслуживание и внутренние сбои используют ненулевые коды API. Это ошибки запроса, а не значения результата регистрации в WhatsApp.

Сохраняйте историю при новой проверке

Если приложению нужен более свежий статус, добавьте новое наблюдение или создайте новую версию существующей записи. Не перезаписывайте старое checked_at, сохраняя прежний результат, и не заменяйте последнее завершённое значение на false только потому, что обновление не удалось.

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

Ситуация Последний завершённый результат Отдельный журнал запросов
Первая проверка завершилась с true true, получено в T1 Успех в T1
Последующий запрос к API вернул ошибку true, получено в T1 Ошибка HTTP/API в T2
Последующая проверка завершилась с false false, получено в T3 Успех в T3

Выбирайте время обновления исходя из бизнес-решения

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

Определите правило явно:

  • какой максимальный возраст результата допускает процесс;
  • какие ответы API с ненулевым кодом должны инициировать повторный вызов позже;
  • после каких ошибок API вызывающая сторона решает отправить запрос повторно;
  • как соблюдаются ограничения параллелизма и тайм-ауты;
  • как метки времени отображаются операторам.

Главное — не выдавать старое значение из базы данных за результат в реальном времени. WA Lookup предоставляет синхронное текущее наблюдение при вызове; интегрирующее приложение само решает, когда нужно вызвать сервис снова.

Принцип надёжного хранения

Храните сведения о регистрации как наблюдения с метками времени, а операционные попытки — как отдельные состояния.

Так registered=false сохраняет смысл, повторные попытки становятся безопаснее, а каждый интерфейс может точно сказать, когда был проверен отображаемый статус. Это также соответствует границам продукта: WA Lookup предоставляет результаты проверки регистрации, а система клиента отвечает за хранение, политику обновления и последующие решения.

Источники