Endpoint, обязательные заголовки, формат данных и базовая диагностика.

Первый вызов API

Первый запрос выполняется только после получения Sandbox endpoint, security scheme, подписки и credentials. Используйте пример из конкретной OpenAPI-спецификации; шаблон ниже показывает общие платформенные требования.

Перед вызовом

Consumer application создано в Sandbox;
API subscription активна;
исходящий IP добавлен в whitelist, если это требуется;
TLS chain доверен клиенту;
credentials получены и сохранены безопасно;
известны base URL, API version и resource path.

Платформенные заголовки

Заголовок	Кто задаёт	Назначение
`Authorization` или API key header	Consumer	Аутентификация согласно security scheme API
`X-External-Request-ID`	Consumer; Gateway может дополнить в legacy-сценарии	Идентификатор конкретной попытки вызова
`traceparent`	Consumer или Gateway	W3C trace context для технической трассировки
`Idempotency-Key`	Consumer, когда требует контракт	Идентификатор одного бизнес-намерения
`Accept: application/json`	Consumer	Ожидаемый формат ответа
`Content-Type: application/json`	Consumer для JSON body	Формат тела запроса

Не формируйте доверенный Consumer ID самостоятельно

Канонический X-Consumer-ID определяется платформой из проверенной идентичности application. Произвольное значение, переданное извне, не считается доверенным.

Пример запроса

curl --request POST 'https://api.dev.esb.mtb.ua/<api>/<version>/<resource>' \
  --header 'Authorization: <scheme-and-credential>' \
  --header 'X-External-Request-ID: <unique-request-id>' \
  --header 'traceparent: 00-<trace-id>-<span-id>-01' \
  --header 'Idempotency-Key: <stable-business-request-key>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": "100.50",
    "currency": "EUR",
    "requestedAt": "2026-07-12T14:30:00+03:00"
  }'

Замените placeholders значениями из карточки подключения и OpenAPI. Не копируйте пример как контракт конкретного API.

Правила данных

поля JSON именуются в camelCase;
дата и время передаются в ISO 8601 с timezone;
денежные суммы передаются строкой, не float;
currency использует ISO 4217;
UUID v4 используется для ID, если контракт не говорит иное;
enum оформляются как UPPER_SNAKE_CASE;
null и отсутствующее поле имеют разный смысл;
parser должен терпимо относиться к новым неизвестным полям.

Идемпотентность

X-External-Request-ID идентифицирует отдельную попытку вызова. При повторе одной бизнес-операции он может измениться.

Idempotency-Key идентифицирует бизнес-намерение. При безопасном повторе той же операции Consumer использует прежний ключ. Минимальный scope проверки на платформе:

(consumer_id, idempotency_key)

Проверить ответ

Зафиксируйте:

HTTP status;
response body;
X-External-Request-ID;
traceparent;
время запроса и окружение.

Эти значения нужны для диагностики и Sandbox audit.

Быстрая диагностика

Результат	Что проверить первым
TLS error	Certificate chain, hostname и network path
`401`	Security scheme, credential, token expiry
`403`	Subscription, role, scope и resource binding
`404`	Environment, base path, API version и resource path
`409`	Idempotency или конфликт состояния согласно контракту
`429`	Назначенный rate limit и client-side backoff
`5xx`	Request ID, traceparent и статус целевого маршрута

Для обращения в поддержку

Передайте environment, API и version, UTC/EET-время ошибки, HTTP status, X-External-Request-ID и traceparent. Payload и credentials необходимо удалить или замаскировать.

Первый вызов API

On this page