Описание 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>