Описание XML-RPC протокола Вся работа с сервером ведется

Описание XML-RPC протокола
Вся работа с сервером ведется посредством отправки и получения данных в xml формате.
URL интерфейса http://captchabot.com/rpc/xml.php
Синтаксис протокола
Отправка запроса
<methodCall>
<methodName>ocr_server::func_name</methodName>
<params>
<param><param_type>data</param_type></param>
<param><param_type>data</param_type></param>
</params>
</methodCall>
Параметр methodName содержит в себе название вызываемой на сервере функции. Начинается
всегда с ocr_server после чего следует разделитель “::” и вызываемая функция (func_name). Список функций
рассмотрен ниже.
Во вкладе params передаются данные для вызываемой функции.
Блок <param><param_type>data</param_type></param> состоит из трех элементов:

Сами теги <param></param> - внутри, которых передаются тип панных и сами данные

<param_type> </param_type> - тип передаваемых данных - string, base64, int, double и т.д.

data - сами данные, соотвествующие указанному типу
Примеры:
<param><int>0</int></param>
<param><string>test</string></param>
<param><base64>dGVzdA==</base64></param>
Ответ сервера (пример)
<xml version="1.0" encoding="utf-8"?><methodResponse>
<params>
<param>
<value>
<struct>
<member>
<name>Параметр 1</name>
<value>
<string>Текст 1</string>
</value>
</member>
<member>
<name>Параметр 2</name>
<value>
<int>123456</int>
</value>
</member>
</struct>
</value>
</param>
</params>
</methodResponse>
Функции
Analyze
Функция распознавания изображения.
Вызов:
<methodCall>
<methodName>ocr_server::analyze</methodName>
<params>
<param><base64>IMAGE BODY</base64></param>
<param><string>system_key</string></param>
<param><string>SYSTEM_KEY</string></param>
<param><int>LANGUAGE</int></param>
</params>
</methodCall>
Через <base64>IMAGE BODY</base64> - передается тело изображения.
<string>system_key</string> - передается либо логин для аутентификации по паре логин / пароль, либо
system_key для аутентификации по системному ключу.
<string>SYSTEM_KEY</string> - содержит пароль или значение system_key. Зависит от выбранного
способа аутентификации.
<int>LANGUAGE</int> - языковые параметры распознавания изображения. Подробнее рассмотрены в
пункте «Языковые параметры».
Ответ:
Ответ приходит также в XML формате.
<xml version="1.0" encoding="utf-8"?>
<methodResponse>
<params>
<param>
<value>
<struct>
<member>
<name>text</name>
<value>
<string>TEXT OF IMAGE</string>
</value>
</member>
<member>
<name>id</name>
<value>
<int>IMAGE IDENTIFICATOR</int>
</value>
</member>
</struct>
</value>
</param>
</params>
</methodResponse>
В <string>TEXT OF IMAGE</string> содержится распознанный текст с изображения.
В <int>IMAGE IDENTIFICATOR</int> содержится уникальный идентификатор изображения на сервере.
Ver
Функция репортинга о неправильно распознанном изображении. Принимает 2 аргумента: Значение
репортинга имеющее 2 варианта yes (распознано верно) или no(распознано не верно) и Идентификатор
изображения. Подтверждать правильно распознанное изображение не обязательно, так как по умолчанию
оно считается правильным.
Вызов:
<methodCall>
<methodName>ocr_server::ver</methodName>
<params>
<param><string>yes|no</string></param>
<param><int> IMAGE IDENTIFICATOR </int></param>
</params>
</methodCall>
Ответа нет
Balance
Функция возвращает текущий баланс клиента Принимает 1 аргумент: Системный ключ.
Вызов:
<methodCall>
<methodName>ocr_server::balance</methodName>
<params>
<param><string>system_key</string></param>
<param><string>SYSTEM_KEY</string></param>
</params>
</methodCall>
Ответ:
<xml version="1.0" encoding="utf-8"?>
<methodResponse>
<params>
<param>
<value>
<struct>
<member>
<name>balance</name>
<value>
<double>BALANCE</double>
</value>
</member>
</struct>
</value>
</param>
</params>
</methodResponse>
Limit
Функция возвращает текущий дневной лимит и израсходованный лимит клиента. Принимает 1 аргумент:
Системный ключ.
Вызов:
<methodCall>
<methodName>ocr_server::limit</methodName>
<params>
<param><string>system_key</string></param>
<param><string>SYSTEM_KEY</string></param>
</params>
</methodCall>
Ответ:
<xml version="1.0" encoding="utf-8"?>
<methodResponse>
<params>
<param>
<value>
<struct>
<member>
<name>day_limit</name>
<value>
<string>DAY_LIMIT</string>
</value>
</member>
<member>
<name>spent_limit</name>
<value>
<string>SPENT_LIMIT</string>
</value>
</member>
</struct>
</value>
</param>
</params>
</methodResponse>
Примечание к функциям balance и limit
Параметры <float>BALANCE</float>, <float>DAY_LIMIT</float> и <float>SPENT_LIMIT</float>
содержат данные в строковом типе, но при нормальном обработчике xml-rpc протокола конвертируются во
float. В этот момент может произойти ошибка конертации данных, в зависимости от языковых настроек
Вашей системы.
Сервер возвращает разделитель целой и дробной части на основе своих настроек, в большинстве случаев
это точка “.” Этот момент Вам надо будет “лично” проконтролировать, т.к. разделитель целой и дробной
части в Вашей системе может быть запятая “,” На всякий случай рекомендуется преобразовывать строку,
полученную от сервера (с типом данных float) в строку, пригодную для конвертации в дробное число, с
учетом Ваших языковых настроек.
Обработка ошибок
В случае возникновения какой-либо ошибки в процессе выполнения функции сервер возвращает номер
ошибки в виде числа.
Коды и описания ошибок смотрите в оотвествющем документе.
Пример ошибки: 401 (negative balance. Недостаточно средств на счету для выполнения операции). В
документе будет только номер 401
Ответ:
"<?xml version=\"1.0\" encoding=\"utf-8\"?>
<methodResponse>
<params>
<param>
<value>
<int>401</int>
</value>
</param>
</params>
</methodResponse>"
Языковые параметры
Языковые параметры используются для указания системе, по каким критериям предварительно
проверять распознанный текст перед отправкой обратно клиенту. Например, с их помощью Вы можете
указать, что на изображении только цифры или наоборт только буквы. В данный момент поддерживается 2
версии параметров.
1 вариант (устаревший)
Передается в теле запроса сразу после пароля
<param><int>LANGUAGE</int></param>
Может принимать следующие значения
Английский, не чувствителен к регистру (по умолчанию): 0
Английский регистрозависимый: 5
Английский все буквы большие: 6
Английский все буквы маленькие: 7
Изображения Recaptcha type: 8
Изображения с мат. выражениями: 9
Новый вариант:
Также передается в теле запроса. В этом случае параметр LANGUAGE должен быть равен нулю. В
противном случае новые параметры не будут приняты во внимание.
Параметры должны передаваться в строгом порядке, иначе они будут восприняты системой некорректно.
Пример:
<param><int>LANGUAGE</int></param>
<param><int>SYMB</int></param>
<param><int>CASE</int></param>
<param><int>CALC</int></param>
<param><int>MIN</int></param>
<param><int>MAX</int></param>
<param><int>PHRASE</int></param>
Значения:
LANGUAGE = всегда равен 0.
SYMB = тип символов. 0 цифры и буквы. 1 только буквы. 2 только цифры
CASE = Регистр символов. 0 регистронезависим (смешанный). 1 верхний регистр. 2 Нижний регистр,3
регистрозависим.
CALC = по умолчанию 0. 1 если цифры на изображении необходимо посчитать
MIN = минимальная длина текста. По умолчанию 3
MAX = максимальная длина текста. По умолчанию 20
PHRASE = 1 текст состоит из 2 или более слов. 0 по умолчанию не проводить проверки кол-ва слов.
Примеры
Ниже приведены примеры, основываясь на которых можно ориентироваться в параметрах
1.
Математическая капча. Ответ состоит только из цифр. Длина ответа от 1 до 3 символов.
<methodCall><methodName>ocr_server::analyze</methodName><params>
<param><base64>IMAGE BODY</base64></param>
<param><string>system_key</string></param>
<param><string>SYSTEM_KEY</string></param>
<param><int>0</int></param>
<param><int>2</int></param>
<param><int>0</int></param>
<param><int>1</int></param>
<param><int>1</int></param>
<param><int>3</int></param>
<param><int>0</int></param>
</params></methodCall>
2.
ReCaptcha. Регистрозависимая капча, состоит из 2 слов. Смешанные символы.
<methodCall><methodName>ocr_server::analyze</methodName><params>
<param><base64>IMAGE BODY</base64></param>
<param><string>system_key</string></param>
<param><string>SYSTEM_KEY</string></param>
<param><int>0</int></param>
<param><int>0</int></param>
<param><int>3</int></param>
<param><int>0</int></param>
<param><int>3</int></param>
<param><int>20</int></param>
<param><int>1</int></param>
</params></methodCall>
3.
Капча состоящая ТОЛЬКО из букв в нижнем регистре.
<methodCall><methodName>ocr_server::analyze</methodName><params>
<param><base64>IMAGE BODY</base64></param>
<param><string>system_key</string></param>
<param><string>SYSTEM_KEY</string></param>
<param><int>0</int></param>
<param><int>1</int></param>
<param><int>2</int></param>
<param><int>0</int></param>
<param><int>3</int></param>
<param><int>20</int></param>
<param><int>0</int></param>
</params></methodCall>
4.
Капча состоящая ТОЛЬКО из цифр.
<methodCall><methodName>ocr_server::analyze</methodName><params>
<param><base64>IMAGE BODY</base64></param>
<param><string>system_key</string></param>
<param><string>SYSTEM_KEY</string></param>
<param><int>0</int></param>
<param><int>2</int></param>
<param><int>0</int></param>
<param><int>0</int></param>
<param><int>3</int></param>
<param><int>20</int></param>
<param><int>0</int></param>
</params></methodCall>
5.
Капча состоящая из цифр и букв в верхнем регистре.
<methodCall><methodName>ocr_server::analyze</methodName><params>
<param><base64>IMAGE BODY</base64></param>
<param><string>system_key</string></param>
<param><string>SYSTEM_KEY</string></param>
<param><int>0</int></param>
<param><int>0</int></param>
<param><int>1</int></param>
<param><int>0</int></param>
<param><int>3</int></param>
<param><int>20</int></param>
<param><int>0</int></param>
</params></methodCall>
6.
Капча состоящая из букв и цифр. Регисрозависимая.
<methodCall><methodName>ocr_server::analyze</methodName><params>
<param><base64>IMAGE BODY</base64></param>
<param><string>system_key</string></param>
<param><string>SYSTEM_KEY</string></param>
<param><int>0</int></param>
<param><int>0</int></param>
<param><int>3</int></param>
<param><int>0</int></param>
<param><int>3</int></param>
<param><int>20</int></param>
<param><int>0</int></param>
</params></methodCall>
7.
Капча состоящая из букв и цифр. Регисронезависимая.
<methodCall><methodName>ocr_server::analyze</methodName><params>
<param><base64>IMAGE BODY</base64></param>
<param><string>system_key</string></param>
<param><string>SYSTEM_KEY</string></param>
<param><int>0</int></param>
<param><int>0</int></param>
<param><int>0</int></param>
<param><int>0</int></param>
<param><int>3</int></param>
<param><int>20</int></param>
<param><int>0</int></param>
</params></methodCall>