1. Параметри протоколу
2. Аутентифікація та ідентифікація
3. Формати параметрів
4. Команди
5. Коди відповіді на запит
6. Результати виконання команд
7. Статуси операції

1. Параметри протоколу

1.1 Вступ

Контрактор і сервер обмінюються повідомленнями через HTTP методом POST у форматі text/xml. Кодування повідомлень — UTF-8.
HTTP-заголовок Content-Type вказує на формат повідомлення:

Content-Type: text/xml; charset=utf-8

1.2 URL сервісу

Усі запити надсилаються на адресу:

https://core.c-b-g.company/ContractorApi.php

1.3 Відповідь сервера

• Успіх: HTTP 200 OK та <ReturnCode>0</ReturnCode><ReturnMessage>OK</ReturnMessage>
• Помилки: інші ReturnCode, пояснення в ReturnMessage.

Відсутність відповіді або HTTP-код який відрізняється від 200 не означає відмову. Повторіть запит після вирішення проблем.

2. Аутентифікація та ідентифікація

2.1 Ідентифікація Контрактора

HTTP-заголовок:

X-GC-Auth-Point: <номер точки>

2.2 Аутентифікація запиту за ЕЦП

HTTP-заголовок:

X-GC-Auth-Sign: <підпис у Base64>

• Алгоритм: RSA/SHA1
• Підпис формується за тілом запиту

2.3 ЕЦП відповіді сервера

Сервер додає підпис в заголовок відповіді:

X-GC-Auth-Sign: <підпис у Base64>

3. Формати параметрів

3.1 Ідентифікатор операції (OperationId)

Унікальний рядок (до 64 символів), напр.:

• "1112"
• "1113_1228"
• "1114_12282359"

3.2 Ідентифікатор сервісу (ServiceId)

Унікальний ідентифікатор типу сервісу. Доступні сервіси — в Каталозі.

3.3 Обсяг угоди (Volume)

Типи:

• A — кількість (у.о., штуки)
• V — вартість (в UAH)

Наприклад: "12345.012V"

3.4 Позначення

• INT - рядок цифр, що містить ціле невід'ємне число, не більше 2^16, наприклад, "12345";
• LONG - рядок цифр, що містить ціле невід'ємне число не більше 2^32, наприклад, "12345";
• VARCHAR(n) - рядок довільних символів, довжиною трохи більше n, наприклад, "qwerty";
• MONEY - рядок, що містить невід'ємне число фіксованої точності від 0 до 4 знаків у дробовій частині з роздільником крапка, та з непустою цілою частиною, наприклад, "1.0000" "0.01";
• VOLUME - рядок, що містить значення типу MONEY, об'єднаний з типом обсягу операції (A або V) шляхом об'єднання рядків, наприклад, "12345.012V";
• DATETIME - рядок, що містить дату та час у форматі YYYY-MM-DDTHH:MM:SS. Приклад: "2025-01-01T15: 52:50";
• PARAMS – рядок, який містить значення реквізитів конкатенованих символом “;”.

4. Команди

4.1 Типи команд

• Operation — провести операцію
• Check — перевірити стан операції

4.2 Параметри відповіді на команди

• ResultCode
• ResultMessage
• ResultData

4.3 Команда Operation

Параметри запиту:

* — хоча б один із параметрів обов’язковий: Volume або Price

Приклад запиту:

<OperationRequest>
  <Commands>
    <OperationRequestCommand>
      <ServiceId>1</ServiceId>
      <OperationId>125206188472552900</OperationId>
      <Volume>1</Volume>
      <Params>380913016166</Params>
      <Timeout>30</Timeout>
    </OperationRequestCommand>
  </Commands>
</OperationRequest>

Приклад відповіді:

<Response>
  <ReturnCode>0</ReturnCode>
  <ReturnMessage>OK</ReturnMessage>
  <Commands>
    <OperationResponseCommand>
      <ResultCode>412</ResultCode>
      <ResultMessage>Очікується підтвердження або скасування операції</ResultMessage>
      <OperationId>125206188472552900</OperationId>
      <Id>14507921</Id>
    </OperationResponseCommand>
  </Commands>
</Response>

4.4 Команда Check

Параметри запиту:

Приклад запиту:

<CheckRequest>
  <Commands>
    <CheckRequestCommand>
      <OperationId>125206188472552900</OperationId>
    </CheckRequestCommand>
  </Commands>
</CheckRequest>

Приклад відповіді:

<Response>
  <ReturnCode>0</ReturnCode>
  <ReturnMessage>OK</ReturnMessage>
  <Commands>
    <CheckResponseCommand>
      <ResultCode>412</ResultCode>
      <ResultMessage>Очікується підтвердження або скасування операції</ResultMessage>
      <OperationId>125206188472552900</OperationId>
    </CheckResponseCommand>
  </Commands>
</Response>

5. Коди відповіді на запит (ReturnCode)

6. Результати виконання команд (ResultCode)

7. Статуси операції (ResultCode)