Összefoglaló

A SOAP szabvány szerint működő IIS-n futó ASP.NET web service célja összekötni a CobraConto.Net rendszert weben publikált külső rendszerekkel, mint például:

• webáruházak
• partnerportálok
• szakértői rendszerek
• webes CRM-ek
• vám- és jövedéki nyilvántartások, pl: VamSoft KompaktZoll

Szinkronizálható adatok:

• partnerek
• termékek
• vevői megrendelések
• szállítói megrendelések
• raktári mozgások
• számlázás (távnyomtatással, NAV feladással, könyveléssel)
• bármi, amire az Ön cégének szüksége van

Technikai dokumentáció

Adatkommunikáció módja a Cobra Computer által biztosított web szolgáltatások segítségével történik a jelen dokumentációban ismertetett metódusok és adatstruktúrák használatával.

Teszt hozzáférés és WSDL információk az alábbi linkről érhetők el: http://support.cobraconto.net/WAPI/services.html

Hívások általános paraméterei és a hívások sikerességének ellenőrzése:

Az ismertetett web szolgáltatásokkal elérhető  web metódusok közös jellemzője, hogy a működésükhöz szükséges paramétereken felül várnak további két, azonosításra szolgáló paramétert. Ezeket értelmezését az ismétlések elkerülése végett  a  dokumentumban kiemeltük:

• AAuth: egy jogosultság ellenőrzéshez szükséges Auth típusú objektum, ami név-jelszó párost tartalmaz. Ezt az értékét a program összeveti a web.configban megadott név-jelszó párossal.
• AtransactionId: egy szöveges adat, amivel a hívó fél egyedileg azonosíthatja a kért műveletet, mert a bizonylatok feladására használt eljárások ATransactionId paramétere alapján a rendszer naplót vezet, amiből lekérdezhető egy adott eljárás hívás eredménye az erre a célra vezetett eseménynaplóból. GetTransactionLog(Auth AAuth, string ATransactionId)
  A GetTransactionLog meghívásával tudható meg az is, hogy az újonnan rögzített adat a rendszerben milyen belső azonosítót kapott (Az adatrögzítésben érintet szülőtábla elsődleges kulcsának az értéke).
• Adatrögzítéskor RowState lehetséges értékek:
  • 0 = nincs a rekordban változás, nem dolgozza fel a program
  • 1 = új rekordként rögzíti a program
  • 2 = meglévő rekord módosításaként próbálja rögzíteni a program
  • -1 = törli a rekordot a program

Törzsadatok kezelése

Terméktörzs lekérdezése

(ProductService.asmx, WSDL: http://support.cobraconto.net/WAPI/ProductService.asmx?WSDL)

• Termékek lekérdezése:
  GetProductList (Auth AAuth, string AtransactionId, DateTime AFromDate)
  AFromDate: A CCN-ben ezen időpont után újként felvett vagy módosított termékek listáját
• Egy meghatározott termék adatai CCN-es belső azonosító alapján: 
  GetProduct(Auth AAuth, , string AtransactionId, int AId)
  AId:  A termék elsődleges kulcsa (dbo.Product.Id)
• Egy meghatározott termék adatai külső azonosító alapján:
  GetProductByPartNo(Auth AAuth, string AtransactionId, string APartNo)
  APartNo: A terméket reprezentáló külső azonosító, mint cikkszám vagy vonalkód
• Terméklista lekérdezése, mely termékek a megadott időponttól változtak, opcionális kategória szűréssel. LAPOZVA, az SQL Server pagination funkciójával megvalósítva:
  GetPagedProductList(Auth AAuth, string ATransactionId, DateTime AFromDate, int ACategoryId, int APageNum, int APageSize)
  • paraméter: “AAuth”: Authentikációs (login) objektum
  • paraméter: “ATransactionId”: Kliens oldali tranzakció azonosító, ami alapján a hívás naplózódik a szerver oldalon
  • paraméter: “AFromDate”: Dátum amikortól a termékben bekövetkező változásokat figyelembe veszi a program a lista összeállításánál
  • paraméter: “ACategoryId”: Kategória belső azonosító, mint szűrőfeltétel, vagy 0, ha minden kategóriára szükség van
  • paraméter: “APageNum”: Kért oldal száma
  • paraméter: “APageSize”: Kért oldal méreteAzaz, hogy hány rekordot adjon vissza

A lekérdezések eredménye ProductList struktúrájú.

Partner lekérdezése

(PartnerService.asmx, WSDL: http://support.cobraconto.net/WAPI/PartnerService.asmx?WSDL)

• Partnerek lekérdezése:
  GetPartnerList (Auth AAuth, string AtransactionId, DateTime AFromDate)
  AFromDate: A CCN-ben ezen időpont után újként felvett vagy módosított partnerek listáját

• Egy meghatározott partner adatai CCN-es belső azonosító alapján:
  GetPartner(Auth AAuth, string AtransactionId, int AId)
  AId:  A partner elsődleges kulcsa (dbo.Partner.Id)
• Egy meghatározott partner adatai külső azonosító alapján:
  GetPartnerByClientNo(Auth AAuth, string AtransactionId, string AClientNo)
  APartNo: A partnert reprezentáló külső azonosító, mint ügyfélkód vagy adószám
• Egy meghatározott partner adatai meghatározott külső azonosító alapján:
  GetPartnerByClientNoEx(Auth AAuth, string AtransactionId, string AClientNo, int AClientNoId)

A lekérdezések eredménye PartnerList struktúrájú.

Partner rögzítése

(PartnerService.asmx, WSDL: http://support.cobraconto.net/WAPI/PartnerService.asmx?WSDL)

• Egy új partner adatainak rögzítése, meglévő partner adatainakmódosítása:
  SetPartner(Auth AAuth, string AtransactionId, Partner clsPartner)
  clsPartner:  A rögzítendő partner adatait tartalmazó objektum

Egyéb törzsadatok kezelése

(BaseDataService.asmx, WSDL: http://support.cobraconto.net/WAPI/BaseDataService.asmx?WSDL)

• Id alapján főkönyvi szám (dbo.Account) lekérdezése: GetAccount
• Kontírszám és adóév alapján főkönyvi szám (dbo.Account) lekérdezése: GetAccountByCode
• Adóév (dbo.TaxYear) és réteg (1 v. 2) alapján számlatökür lekérdezése: GetAccountList
• GetBankAccountList
• GetBankList
• A gyártókhoz (GetManufacturerList) tartozó márkák listája: GetBrandList
• GetCategoryList
• GetChannelList
• GetClientNoList
• GetCollector
• GetCollectorList
• GetCountryList
• GetCurrencyList
• GetEmployeeList
• GetFirmList
• GetGatherNoList
• GetLanguageList
• GetManufacturerList
• Termék azonosítók (cikkszám, szállítói cikkszám, termékkód, stb): GetPartNoList
• GetPaymentList
• GetPriceTypeList
• Jellemzők lekérdezése: GetPropertyList. Resultban:
  • <TypeId>1</TypeId> : termékjellemző
  • <TypeId>2</TypeId> : bizonylatjellemző
• ÁFA kulcsok lekérdezése: GetTaxList
• ÁFA típusok lekérdezése adóév (TaxYear.Id) alapján: GetTaxTypeList
• Adóév (dbo.TaxYear) lekérdezése Id alapján: GetTaxYear
• Adóév (dbo.TaxYear) lekérdezése évszám alapján: GetTaxYearByYearNum
• Teljes adóév lista lekérdezése: GetTaxYearList
• Gyűjtő felvétele: SetCollector

Számlakészítés

(InvoiceService.asmx, WSDL: http://support.cobraconto.net/WAPI/InvoiceService.asmx?WSDL)

• • CreateDepositCreditingInvoice: Előleg számlát beszámító végszámla kiállító végpont
    • • a külső rendszer Cobraban szerepelő előleg számla Id-re hivatkozik
      • a külső rendszer a CreateInvoice-ban már megvalósított módon megadja a végszámla partnerét, keltét, számviteli teljesítési, ÁFA teljesítési és fizetési határidő dátumát, a fizetési módot, stb
      • a külső rendszer CSAK a végszámla pozitív tételeit küldi be, az előleg számla tételeit mínusz mennyiséggel a Cobra WAPI emeli be
      • a NAV feladáshoz szükséges hivatkozást a Cobra rendszer biztosítja

• • CreateInvoice: alapszámla, előleg számla és gyüjtőszámla kiállítására alkalmas végpont

• • CreateInvoiceFromTemplate: megadott számlasablon alapján alapszámla kiállítására alkalmas végpont

• • CreateInvoiceModifierDocument: Számla módosító okirat készítő végpont
    • • a külső rendszer Cobraban szerepelő számla Id-re hivatkozik
      • a külső rendszer a CreateInvoice-ban már megvalósított módon megadja a módosító okirat partnerét, keltét, számviteli teljesítési, ÁFA teljesítési és fizetési határidő dátumát, a fizetési módot, stb
      • a külső rendszer CSAK az eredeti számlát módosító pozitív tételeket küldi be, a végpont a megadott számlaszám ÖSSZES tételét automatikusan mínusz tételként felrakja az előkészített módosító okiratra
      • a NAV feladáshoz szükséges hivatkozást a Cobra rendszer biztosítja
  • CreateStornoInvoice: Számla sztornó / érvénytelenítő készítő végpont
    • • a külső rendszer Cobraban szerepelő számla Id-re hivatkozik
      • a NAV feladáshoz szükséges hivatkozást a Cobra rendszer biztosítja

• • GetInvoiceFileList: adott adóévból listázza az összes számlatömb összes adatát
  • GetInvoiceResponse: megadott számla id alapján visszaadja annak legfontosabb adatait, ha kell, tételeit

Raktárkészlet

(StockHandlerService.asmx, WSDL: http://support.cobraconto.net/WAPI/StockHandlerService.asmx?WSDL)

Lekérdezése

• Készlet információ:
  GetStockPile(Auth AAuth, DateTime ADate, int AStockId)
  ADate: Ebben az időpontban (nap) aktuális készlet listája
  AStockId: A CCN adatstruktúrában a raktárt reprezentáló tábla elsődleges kulcsa (dbo.Stock.Id)

A lekérdezés eredménye StockPile struktúrájú.

• GetStockPileOverView: a Készletkezelés / Készlet áttekintés lekérdezést valósítja meg. Minta: https://help.cobra.hu/wp-content/uploads/WAPI_examples/ProductService_StockHandlerService.xlsx

Készletmozgások feladása

• Leltár felvételi ív kitöltése:
  PostInventorySheet(Auth AAuth, string TransactionId, InventorySheet AInventorySheet) AInventorySheet: A fellelt készletet tartalmazza.
• Közvetlen készletmozgás generálása. Raktárközi mozgások és nem leltári korrekciók (pl. selejtezés) alapján történt raktári mozgások feladására használható. A vevői és beszerzési rendelések teljesítésekor történő raktári mozgásokat (ki-, és betárolás) az adott feladás elvégzi, nem szabad feladni külön a készletmozgást:
  PostStockMove(Auth AAuth, VoucherList AVoucherList)
  AVoucherList: Készletmozgást leíró bizonylatok listája

Vevői rendelések

(SalesOrderService.asmx, WSDL: http://support.cobraconto.net/WAPI/SalesOrderService.asmx?WSDL)

Rögzítése

• Belső Id (dbo.Order.Id) alapján megrendelés érvénytelenítése: CancelOrder
• Új vevői megrendelés rögzítése: SetOrder

Szállítói rendelések

(PurchaseOrderService.asmx, http://support.cobraconto.net/WAPI/PurchaseOrderService.asmx?WSDL)

Lekérdezése

• GetPurchaseOrder
• GetPurchaseOrderFileList
• GetPurchaseOrderList

Rögzítése

• SetPurchaseOrder

Ki-, és betárolásra váró bizonylatok

Lekérdezése

(PickingService.asmx)

• Nyitott vagy meghiúsult szállítói rendelések a majdani betároláshoz:
  GetPurchaseOrderPickingLists(Auth AAuth, string AtransactionId, DateTime AFromDate)
  AFromDate:  A CCN-ben ezen időpont után újként felvett, módosított vagy törölt kimenő rendelések listája.A lekérdezés eredménye VoucherList struktúrájú. Adattartalma a megadott dátum után keletkezett/módosított/érvénytelenített szállítói rendelések.
• Egy kimenő rendelés adatai:
  GetPurchaseOrderPickingList(Auth AAuth, string AtransactionId, int AId)
  Aid:  A szállítói rendelés elsődleges kulcsa (dbo.PurchaseOrder.Id)A lekérdezés eredménye VoucherList struktúrájú. Adattartalma a megadott azonosítójú szállítói rendelés.
• Kitárolásra váró vevői rendeléseket reprezentáló teljesítés objektumok:
  GetSalesOrderPickingLists (Auth AAuth, string AtransactionId)A lekérdezés eredménye VoucherList struktúrájú. Adattartalma a komissiózás alatt lévő vevői rendelésekhez tartozó teljesítés objektumok listája, amely minden esetben az összest tartalmazza.
• Egy kitárolásra váró vevői rendelést reprezentáló teljesítés objektum:
  GetSalesOrderPickingList (Auth AAuth, string AtransactionId, int Aid)
  Aid:  A vevői rendeléshez tartozó teljesítés objektum elsődleges kulcsa (dbo.Completion.Id)A lekérdezés eredménye VoucherList struktúrájú. Adattartalma a komissiózás alatt lévő / komissiózott teljesítés objektum.

Ki-, és betárolt bizonylatok feladása

• Betárolt szállítói rendelés feladása :
  PostPurchaseCompletionPiclingLists(Auth Aauth, VoucherList AVoucherList) A VoucherList–ben hivatkozott bizonylatszámú szállítói rendelés(ek) betárolása a megadott mennyiségekkel.
• Kitárolt vevői rendelések feladása:
  PostSalesCompletionPickingLists(Auth AAuth, VoucherList AVoucherList) A VoucherList–ben hivatkozott bizonylatszámú teljesítés objektum(ok)  (komissiózás alatt álló vevői rendelés(ek))  kitárolása a megadott mennyiségekkel.

Bejövő (szállító) számlák

(FinancePayableService.asmx, WSDL: http://support.cobraconto.net/WAPI/FinancePayableService.asmx?WSDL)

Lekérdezése

• GetFinancePayable
• GetFinancePayableAcquittance
• GetFinancePayableAcquittanceList
• GetFinancePayableFileList
• GetFinancePayableList

Rögzítése

• SetFinancePayable

Kimenő (vevő) számlák

(FinanceReceivableService.asmx, WSDL: http://support.cobraconto.net/WAPI/FinanceReceivableService.asmx?WSDL)

Lekérdezése

• GetFinanceReceivable
• GetFinanceReceivableAcquittance
• GetFinanceReceivableAcquittanceList
• GetFinanceReceivableFileList
• GetFinanceReceivableList

Rögzítése

• SetFinanceReceivable

Tranzakciós napló (log)

Lekérdezése

• GetTransactionLog(ATransactionId): a műveletben elküldött azonosító alapján a hívás eredményét adja vissza az erre a célra vezetett eseménynaplóból.

Cobra WAPI telepítés

Előfeltételek

• A helyi Windows Servert, SQL Servert és hálózati kapcsolatokat ismerő rendszergazda. Ha Ön nincs ezen ismereteknek birtokában, _ne_ kezdjen neki a műveleteknek. A helytelenül elvégzett műveletekből eredő károkért és/vagy veszteségért való felelősséget a Cobra Computer Kft. kifejezetten kizárja.
• Minimum Windows Server 2012
• Kiszolgálói szerepkörök:
  • Webkiszolgáló (IIS) (Web Server IIS)
    • Webkiszolgáló (Web Server)
      • Állapot és diagnosztika (Health and Diagnostic)
        • HTTP-naplózás (http Logging)
      • Általános http-szolgáltatások (Common HTTP Features)
        • Alapértelmezett dokumentum (Default Document)
        • HTTP-hibák (HTTP Errors)
        • Könyvtár tallózás (Directory Browsing)
        • Statikus tartalom (Static Content)
      • Biztonság (Security)
        • Kérelmek szűrése (Request Filtering)
      • Alkalmazásfejlesztés (Application Development)
        • .NET kiterjeszthetőség 4.5/4.6/4.7/4.8 (.NET Extensibility 4.5/4.6/4.7/4.8)
        • NET 4.5/4.6/4.7/4.8
        • ISAPI-bővítmények (ISAPI Extensions)
        • ISAPI-szűrők (ISAPI Filters)
      • Kiszolgáló eszközök (Management Tools)
        • IIS-kezelő konzol (IIS Management Console)

Könyvtár létrehozás

A wapi_bin.zip fájlt tömörítsük ki abba a könyvtárba, ahonnan a webservice-t működtetni szeretnénk (pl. c:\inetpub\wwwroot\ vagy c:\WAPI).

A könyvtáron belül:

• a bin könyvtárba kerüljenek a .dll kiterjesztésű fájlok

  

• a gyökerébe pedig az összes .asmx és a config fájl

  

• Amennyiben a szöveges log-ot is ebben a könyvtárban fogja tárolni, érdemes egy külön LOG mappát létrehozni erre a célra

Logolás

A WAPI alkalmazás 2 szintű logolást végez:

1. szöveges fájlba, melynek elérési útját a Web.config fájlban kell megadni az ErrorLogFile beállításnál:

   

2. Adatbázisba, melyet ugyanazon SQL Server instance-on kell létrehozni az alábbi script alapján. Természetesen a létrehozáshoz sysadmin jog és a helyi SQL Server könyvtárstruktúrájának ismerete elengedhetetlen. CreateWAPILOGdb.zip

Licencekód kérése és rögzítése

A conto@cobra.hu címre küldje el CASE SENSITIVE módon leírva:

• az SQL Server neve, melyen a kezelendő adatbázis található
• az SQL adatbázis neve

Ez alapján fognak a kollégáink küldeni Önnek licence kódot, melyet a Web.config fájlba kell rögzíteni, a LicenceVS kulcs értékeként. Például:

Figyelem! Az adatbázis paraméterekben is ugyanolyan CASE SENSITIVE módon kell a Server és a catalog értékét megadni, ahogyan azt a licence kéréskor küldte el!

Web.config

Az ASP.Net alkalmazások, így a Cobra WAPI központi konfigurációja is ebben a fájlban található.

IIS új webhely hozzáadása

Figyelem! A leírás ez esetben nem pótolja az IIS adminisztrációjának és a helyi hálózati működés ismerteit! Ha Ön nincs ezen ismereteknek birtokában, _ne_ kezdjen neki a műveleteknek. A helytelenül elvégzett műveletekből eredő károkért és/vagy veszteségért való felelősséget a Cobra Computer Kft. kifejezetten kizárja.

1. Right Click the Site and Click “Add Website…”

   

2. On the Add Website window type the Site Name and Select the Website Files and Select the IP Address
   1. Type the domain name in “Site name”
   2. It is better to create a dedicated Application pool for a website, but You can use an existing application pool. Select an application pool or keep is the default to create new application pool same name as sitename. Requirements:
      1. .NET CLR version: v4.0
      2. Menaged pipeline mode: Integrated
   3. Select your site’s files path by clicking “Physical path”
   4. Binding / Type: Select protocol to configure (eg: http or https)
   5. Binding / IP address: Select ip address from drop list to set dedicated ip for site or keep is the default to use shared ip.
   6. Binding / Port: Enter port on which site will be accessible for users.
   7. Binding / Host name: Enter you actual domain name you want to use, or leave it empty for accessing the website only with ip:port.
      Example:

      

3. Verify the configuration: To verify configuration you can simply access the site in a web browser. Eg.: http://localhost:8082/ProductService.asmx?wsdl

   

Kérés, válasz minták