Чек-лист: что проверить перед интеграцией

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

Всё может пойти не так! Каждое поле из таблички может оказаться не тем, за кого себя выдает. А брокер может оказаться вообще в другом кластере 😵‍💫

В этом посте собрала список того, что по моему опыту может вызывать проблемы при интеграции и соответственно на что стоит обратить внимание заранее.

✔️ Формат даты времени

Примеры:

▶️Ваша система ожидает дату в ISO формате YYYY-MM-DD (год-месяц-день), а она приходит в формате DD/MM/YYYY (день/месяц/год)

▶️Также могут сыграть роль миллисекунды:
2025-03-05T14:30:00 или
2025-03-05T14:30:00.123Z


✔️ Строка vs список строк

Пример:

Мы ждём
currency: “RUB”

А приходит
currency: [“RUB”]

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


✔️ Уникальность полей

В некоторых ситуациях это может быть очень критичным. Например, если мы ориентируемся на это поле, чтобы отсечь дубликаты. А тут оказывается, что в другой системе прекрасно могут существовать разные записи с одинаковым значением этого поля.

💡Стоит уточнить даже про поле id, которое к вам приходит, уникально ли оно.

Например, один API принимал запросы на обработку, а в ответ для последующей проверки статуса отдавал не уникальные id. При попытке получить статус по такому id ругался на ошибку уникальности. Сам выдал, сам ругался 🤷‍♀️

✔️ Заполненность обязательных полей

Эта ситуация может быть опасна, если поле, которое мы считаем обязательным, в другой системе остается пустым только в редких случаях. Если оно всегда пустое — мы отловим и пофиксим это на этапе тестирования интеграции. А вот если оно чаще всего заполнено, но в редких случаях — нет, то мы рискуем не поймать этот редкий кейс при тестировании, а потом свалиться с ошибкой валидации уже на проде 😭

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


✔️ Версии API и библиотек

Вы можете интегрироваться со старым API. Использовать старую или наоборот слишком новую версию какой-то библиотеки, в которой изменен формат данных.

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


✔️ Адрес брокера

Если коллеги отправили данные, а вы их не видите у себя, стоит сверить адрес брокера и название очереди (топика Кафки).

В названии банально могла закрасться опечатка.

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


Некоторые из ошибок довольно легко обнаружить и поправить, а некоторые могут принести существенную головную боль.

Сталкивались ли вы с чем-то из списка или может у вас были другие ситуации ?