FTP/FTPS-протокол¶

Интеграция с использованием шаблона¶

Описание¶

Интеграционный сервис предоставляет возможность просто и быстро создавать SMS-рассылки путем формирования и копирования файлов в формате .csv. Интеграция осуществляется путем выкладывания клиентом файла в определенную папку на FTP-сервер платформы. Пароль на папку сообщается клиенту безопасным способом.

Сервис платформы 1 раз в 10 секунд проверяет папку на наличие архивного файла. При обнаружении файла происходит его обработка, после чего он удаляется с FTP-сервера. Если в папке присутствует много архивов, сервис начинает обработку самого раннего файла. Файлы обрабатываются по очереди.

Внимание

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

Точка доступа¶

FTP-сервер платформы доступен по адресу: ftp1.integrationapi.net

Формат приема сообщений по FTP¶

Важно

Формат названия архива: [логин_Клиента]_[YYYYMMDDhhmmss].zip Пример: guest_20120207231932.zip

Файлы для отправки должны быть упакованы в архив .zip без пароля и находиться в папке [sms]. Папка [sms] должна содержать два файла формата .csv (данные разделяются символом ; ).

Кодировка всех файлов по умолчанию - UTF-8. Если вам необходимо выкладывать файлы в другой кодировке, обратитесь в техподдержку.

Структура архива:

sms/
  contacts.csv
  template.csv

Первый файл должен называться contacts.csv

Наименование столбца	Описание
phone обязательный	Номера получателя сообщения в международном формате: код страны + код сети + номер телефона. Пример: `79031234567`
senddate	Дата и время отправки сообщения в формате `YYYYMMDDThh:mm:ss` (локальное время клиента). Если сообщение нужно отправить сразу после получения файла, поле должно содержать пустое значение. Значение этого поля является более приоритетным по сравнению со значением из файла `template.csv`. Если поле не заполнено, то при отправке должно браться значение из файла `template.csv`. Может учитывать часовой пояс абонента, если заполнено поле localtime в файле `template.csv`. Пример: `2010-06-01T19:14:00`.
attr1	Текстовое поле для подстановки в шаблон.
attrN	N-е текстовое поле для подстановки в шаблон.

Второй файл должен называться template.csv. В файле должна быть только одна строка с данными.

Наименование столбца	Описание
message обязательный	Шаблон сообщения с полями для подстановки. Название поля подстановки должно быть заключено в символ `#`. Данные подставляются из соответствующего столбца в файле `contacts.csv`. Пример: `Уважаемый #attr1# #attr2# #attr3#! Если соответствующее значение в файле contacts.csv не найдено, то поле подстановки заменяется на пустое значение.`
sourceaddress обязательный	Адрес отправителя сообщения. До 11 латинских символов или до 15 цифровых. Предварительно должен быть запрошен через личный кабинет и подтвержден технической поддержкой. Пример: `TESTSMS` (регистр имеет значение).
validity	Время жизни сообщения, устанавливается в минутах. Пример: `180` (по умолчанию подставляется `1440` = 24 часа)
senddate	Дата и время отправки сообщения в формате `YYYYMMDDThh:mm:ss` (локальное время клиента). Если сообщение нужно отправить сразу после получения файла, поле должно содержать пустое значение. Поле может переопределяться значением для конкретного абонента из файла `contacts.csv`. Пример: `2010-06-01T19:14:00`
localtime	Учет часового пояс абонента. Применяется только если указана дата отправки в файле `template.csv`, либо непосредственно у контакта в файле `contacts.csv`. Часовой пояс определяется автоматически по номеру абонента. Возможные значения: `1` - учитывать часовой пояс `0` – не учитывать

Внимание

Незаполненных столбцов ни в одном из файлов быть не должно. Если нет необходимости заполнять данными какие-то столбцы, то и сами столбцы добавлять в файл не нужно.

Спецификация запросов¶

Взаимодействовать с FTP-сервером платформы можно двумя способами:

Работа через FTP-клиент (например, Windows Explorer)
Работа через командную строку Windows или через Telnet

Работа через FTP-клиент¶

FTP-клиентом, встроенным в ОС Windows, является Windows Explorer. В нем работа с FTP-архивами практически не отличается от работы с файлами на компьютере.

Сначала необходимо открыть окно Windows Explorer и установить соединение с FTP-сервером. Для этого в строке адреса нужно ввести ftp.integrationapi.net.
После установки соединения Windows Explorer запросит пароль, соответствующий выданному логину.

Работа через командную строку Windows или через Telnet¶

Для работы с FTP необходимо ввести в командной строке: C:\ ftp ftp.integrationapi.net

После подключения к данному серверу необходимо пройти следующие обязательные этапы:

Идентификация (ввод имени-идентификатора и пароля).
Выбор каталога.
Определение режима обмена (поблочный, поточный, ASCII или двоичный).
Выполнение команд обмена (get, mget, dir, mdel, mput или put).
Завершение процедуры (quit или close).

На первом этапе необходимо ввести свои учетные данные. Управление доступом осуществляется с помощью команд:

USER - имя пользователя
PASS - пароль
CWD - имя новой рабочей директории
CDUP - перейти на один уровень директории вверх
QUIT – выход

Также необходимо определиться с параметрами передачи данных: PORT ip1,ip2,ip3,ip4,p1,p2 - IP-адрес клиента (ip1,ip2,ip3,ip4,) и порт (p1,p2) (расчет порта p1*256+p2=номер порта).

Пример:

Entering Passive Mode (194,87,5,52,9,79)
194.87.5.52 - IP адрес
2383 - номер порта, расчет порта 9*256+79=2383
PASV - сервер должен определить нестандартный порт данных, начать его слушать и вернуть IP-адрес и номер порта в формате PORT.
TYPE { { A | E } [ N | T | C ] } | I | L {размер-байта} (по умолчанию - A N) - специфицирует тип информации.

Для копирования файла из удаленного сервера используется команда GET, для копирования группы файлов - MGET. Аналогом команды GET в какой-то степени является команда DIR (ls), только она переносит содержимое каталога, что для некоторых операционных систем эквивалентно. При использовании модификации MGET проявляйте осторожность - вы можете заблокировать телекоммуникационный канал длительным копированием.

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

Интеграция без шаблона¶

Описание¶

Интеграционный сервис предоставляет возможность просто и быстро создавать SMS-рассылки путем формирования и копирования файлов в формате .csv. Интеграция осуществляется путем выкладывания клиентом файла в определенную папку на FTP-сервер платформы. Пароль на папку должен сообщаться клиенту безопасным способом.

Сервис платформы 1 раз в 10 секунд проверяет папку на наличие архивного файла. При обнаружении файла происходит его обработка, после чего он удаляется с FTP-сервера. Если в папке присутствует много архивов, то сервис начинает обработку самого раннего файла. Файлы обрабатываются по очереди.

Точка доступа¶

FTP – сервер платформы располагается по адресу: ftp1.integrationapi.net

Формат приема сообщений по FTP¶

Важно

Формат названия архива: [логин_Клиента]_[YYYYMMDDhhmmss].zip Пример: guest_20120207231932.zip

Файлы для отправки должны быть упакованы в архив .zip без пароля и находиться в папке [sms]. Папка [sms] должна содержать два файла формата .csv (данные разделяются символом ; ).

Кодировка всех файлов по умолчанию - UTF-8.

Структура архива:

sms/
  name.csv (либо name.txt)

В .txt (или .csv) – файле строки, начиная со второй, содержатся данные для отправки сообщений (одна строка – одно сообщение).

Параметры полей в файле с данными для отправки сообщений:

Наименование столбца Описание

TELNR_LONG
обязательный

Номера получателя сообщения в международном формате: код страны + код сети + номер телефона.

Пример: 79031234567

TEXT
обязательный Текст сообщения

Адрес отправителя задается по умолчанию, необходимо заранее сообщить его в техническую поддержку.
Время жизни сообщения, по умолчанию, составляет 24 часа. Для изменения времени жизни сообщения необходимо также обратиться в техподдержку.
Отправка по часовым поясам и отложенная отправка в данном виде интеграции не предусмотрена.
Статистику по рассылкам клиент может посмотреть в своем личном кабинете.