Внимание! Преди да почнете да четете тази докуметация, е добре да се запознаете със следните понятия, SOAP, XML, също така е добре да сте запознати с езика за програмирате PHP, защото ще бъде позван в примерите.
Документация на SOAP API-то на Fakturirane.bg v 1.0 beta Внимание! Преди да почнете да четете тази докуметация, е добре да се запознаете със следните понятия, SOAP, XML, също така е добре да сте запознати с езика за програмирате PHP, защото ще бъде позван в примерите. 1. Какво позволява Api-то на Fakturirane.bg 2. Използвани библиотеки 3. Аутентикиране 4. Създаване на документ Какво позволява Api-то на Fakturirane.bg В моемнта API-to на Fakturirane.bg е в начален стадии, и има ограничени възможности. То ви позволява да създадете проформа фактура и фактура и тяхното изпращане до клиента, през трета страна. Каква може да е тази трета страна? Тази трета страна може да е вашият онлайн магазин или сайт, през който Вие вършите всекиденвни операции, като обработка на поръчнки и др. С тази своя възможност, ние Ви спестяваме едно влизане в Fakturirane.bg и едно преналиване на информацията, която трябва да се съдържа във Вашият документ, с което Вие спестявате време и извършване на една операция по няколко пъти. Api-to ви позволява да работите с Вашите потребители, като ползвате email-ът и паролата им за open in browser PRO version Are you a developer? Try out the HTML to PDF API pdfcrowd.com удостоверяване към api-то, като по този начин, може да вържете няколко човека, които да издават документи през техните акаунти. Използвани библиотеки С цел максималнто Ви улесняване в разработката, Ви препоръчваме да използвате следните библиотеки. Библиотека Описание URL NuSoap Целта на тази бибиотека е да улесни връзването и аутентикирането към SOAP сървъра, както и улесняването на аутентикирането и изпращането на заявки към него. http://sourceforge.net/projects/nusoap/ Array2XML Целта на тази бибиотека е да улесни създаването на XML-ът, съдържащ информация за документа с всичките му атрубути, от хора не дотолкова запознати с генериране на валидни XML документи. http://www.lalit.org/lab/convert-phparray-to-xml-with-attributes/ Аутентикиране За аутентикиране се използват същите email и парола, както и в системата на Fakturirane.bg 1. require_once 'soap/nusoap.php'; // Зареждаме основната библиотека 2. $client = new nusoap_client('http://fakturirane_bg/api'); // Връзваме се апито 3. $param = new SoapVar(array('username' => 'marto@www-you.com', 'password' => '**** ***'), SOAP_ENC_OBJECT); // Изпращаме нашата логин информация 4. $header = new SoapHeader('http://fakturirane_bg/api', 'AuthenticationInfo', $para m, false); // Запазва го в хедъра, който ще бъде изпратен за обработка 5. $client->setHeaders(array($header)); open in browser PRO version Are you a developer? Try out the HTML to PDF API pdfcrowd.com 6. // Проверява за грешки при вход 7. $err = $client->getError(); 8. if ($err) { 9. // Ако имаме нека ги видим 10. throw new Exception($err); 11. die(); 12. // Нека спрем до тук щом няма успешна връзка 13. } 14. Възможни грешки Код Върната грешка Причина 403 Authentication failed! Грешно изпратени емайл и парола. 401 User is disabled! Този акаун не е активен Създаване на документи В момента системата поддъжа само създаване на фактури и проформа фактури. След, като се аутентикирате успешно, трябва да извикате функцията, която създава документи, като изпратите XML файл, които описва атрибутите на факурата. За цел на примера, инфомрацията е показана като масив. 1. array( open in browser PRO version Are you a developer? Try out the HTML to PDF API pdfcrowd.com 2. 'company' => array( 3. 'name' => 'Име на контрагента', // Името на контрагнта 4. 'bulstat' => '11111111111', // ЕИК на контрагента 5. 'vat_bulstat' => '', // ЕИК по ДДС 6. 'adress' => 'ж.к. Хаджи Димитър бл. 79 вх. Г ап. 71', // Адрес на фимата 7. 'mol' => 'Милена Миткова', // МОЛ 8. 'phone' => '0898 506133', // Телефон 9. 'email' => 'dia2001@abv.bg', // Email 10. ), 11. 'goods' => array( // Описание на редовете 12. 'good' => array( 13. 'title' => 'Абонамент за семинари 01.06.2014 - 31.08.2014', // Име на стоката 14. 'type' => 0, // Тип на стоката 15. 'price' => '72.2000', // Цена до 4 знака 16. 'quantity' => 1, // Количество 17. ) 18. ), 19. 'total_no_vat' => '72', // Цена без ддс 20. 'invoice_tax_amount' => '72', // Данъчна основа 21. 'total' => '72', // Тотал 22. 'vat_rate' => 20, // % ДДС - по подразбиране е 20% 23. 'attend_date' => '20.05.2013', 24. 'return_value' => 'id' // Какво да върне след създаване. Може да е id, number и both. При both ще се върне във формат id::number 25. 'payment_type' => 1, // Тип на плащане 26. 'paid_date' => '20.05.2013', // Падеж на плащането 27. 'mail' => array( // Използва се, ако искате фактурата да бъде изпратена по ем open in browser PRO version Are you a developer? Try out the HTML to PDF API pdfcrowd.com айл 28. 'from' => '', // От кой емайл се изпраща. Ако е оставено празно ще се ипо злва емайлт на фирмата от която се изпраща, а ако то е празно на логнатия потреби тел 29. 'to' => 'fbyalkov@bulmar.com', 30. 'subject' => 'Фактура за закупен видео семинар', 31. // Съобшението на емайлът. Виж таближата надолу за допълнителна информаци я за възможните променливи 32. 'message' => 'Здравейте, 33. 34. Издадена е фактура с № {{invoice_number}} за закупени видео семинари. 35. 36. За въпроси може да пишете на имейл support@fakturirane.bg. 37. 38. Благодарим Ви за интереса към нашите семинари! 39. Accounting Seminars', 40. 'attach_document' => true, 41. 'header' => false, 42. ) 43. ); 44. Внимание! Датата на фактурата, на този етап се задава автоматичо от апито (текущата дата.) От следващата версия типът на информацията за създаденият документ ще се премести, като open in browser PRO version Are you a developer? Try out the HTML to PDF API pdfcrowd.com параметър на функцията за създаване. В момента се праща като параметър на XML-ът - return_value Променлива Описание {{invoice_number}} Ще бъде заместен с номер на документа {{invoice_id}} Ще бъде заместен с служебният номер на документа {{invoice_id}} Ще бъде заместен с служебният номер на документа {{invoice_date}} Ще бъде заместен с датата на документа {{customer_name}} Ще бъде заместен с името на клиента, на който се издава документа {{customer_eik}} Ще бъде заместен с ЕИК номера, на който се издава документа {{total}} Ще бъде заместен с тотала на документа {{total_no_vat}} Ще бъде заместен с тотала без ддс {{payment_type}} Ще бъде заместен с метода на плащане Извикване на функцията за създаване на документ 1. $xmlResult = Array2XML::createXML('document', $xml); // Създава xml от горният ма сив 2. $responce = $client->call('api.create_document', array('xml' => $xmlResult->saveX ML(), 'type' => 'invoice', 'eik' => '12321312312')); // Объръща се към апито open in browser PRO version Are you a developer? Try out the HTML to PDF API pdfcrowd.com 3. Функцията приема 3 параметъра. 1. xml : XML файлът в който е описана фактурата 2. type : типът на създаваният документ. В момента се поддържа invoice и proforma 3. eik : ЕИК номерът на фирмата от която се издава фактурата Възможни грешки Грешка Описание ERROR : Cannot create company! Не може да създаде клиента. Възможна причина - не са изпратени всички полета ERROR : Cannot create customer office Не може да създаде офиса на клиента. Възможна причина - не са изпратени всички полета ERROR : Cannot find bank! Не може да открие банката. Номера на банковата сметка е грешен ERROR : Cannot create document rows! Не може да запази атрибутите на документа. Не са изпратени всички полета ERROR : Cannot create document! Не може да запази документа. Не са избратени всички полета open in browser PRO version Are you a developer? Try out the HTML to PDF API pdfcrowd.com Номенклатури с типове Тип на стоката Тип Описание 0 Стока 1 Услуга 2 Друго Тип на плащането Тип Описание 1 В брой 2 Банков превод 3 Бартер / Насрещно прихващане