Function getInvoiceList

Description

Returns a paginated list of invoices with filtering options.

Document Types (TYP_DOKUMENTU)

• FV - Faktura VAT (VAT Invoice)
• FK - Faktura Korygująca (Correction Invoice)
• PRO - Pro-forma

Important notes

• All monetary values are returned in cents/grosze (integer). To get the value in PLN/EUR, divide by 100.
  Example: toPayPLN = 15000 means 150.00 PLN
• Exchange rates are stored as int * 10000. To get actual rate, divide by 10000.
  Example: exchangeRate = 45230 means 4.5230
• By default, only invoices with STATUS = 'AKTYWNA' are returned.
• KSEF data is included from KSEF_FAKTURY table (LEFT JOIN). If invoice has no KSEF record, ksef.toKsef returns 0, other fields return null.

Arguments

• params :

      array (          
            // Multiple values filters (arrays)
            [ 'invoiceSearch' ][ 'documentType' ] = array ( 'FV', 'FK', 'PRO' ),
            [ 'invoiceSearch' ][ 'status' ] = array ( 'AKTYWNA', ... ),
            [ 'invoiceSearch' ][ 'invoiceNumber' ] = array ( 'FV/001/2026', ... ),
            [ 'invoiceSearch' ][ 'idInvoice' ] = array ( 'abc123', ... ),
            [ 'invoiceSearch' ][ 'group' ] = array ( 'SPRZEDAZ', ... ),
  
            // Date range filters
            [ 'invoiceSearch' ][ 'issueDateFrom' ] = 'yyyy-mm-dd',
            [ 'invoiceSearch' ][ 'issueDateTo' ] = 'yyyy-mm-dd',
            [ 'invoiceSearch' ][ 'saleDateFrom' ] = 'yyyy-mm-dd',
            [ 'invoiceSearch' ][ 'saleDateTo' ] = 'yyyy-mm-dd',
  
            // Client (buyer) filters
            [ 'invoiceSearch' ][ 'idClientCompany' ] = int,
            [ 'invoiceSearch' ][ 'idClientPerson' ] = int,
  
            // Other filters
            [ 'invoiceSearch' ][ 'idBranch' ] = string (ID_FIRMY - branch/office),
            [ 'invoiceSearch' ][ 'template' ] = string (CFG_SZABLON),
            [ 'invoiceSearch' ][ 'currency' ] = string (CFG_WALUTA: 'PLN', 'EUR', ...),
            [ 'invoiceSearch' ][ 'advanceType' ] = string ('Zaliczka' | 'Rozliczenie zaliczki'),
            [ 'invoiceSearch' ][ 'source' ] = string (ZRODLO),
            [ 'invoiceSearch' ][ 'sourceId' ] = string (ID_ZRODLA),
            [ 'invoiceSearch' ][ 'idCreatedBy' ] = int (ID_WPROWADZAJACEGO),
  
            // KSEF filters
            [ 'invoiceSearch' ][ 'toKsef' ] = int (0 | 1), // 0 = not for KSEF, 1 = send to KSEF
                                                           // Note: toKsef=0 also matches invoices without KSEF record
            [ 'invoiceSearch' ][ 'ksefNumber' ] = array ( '1234567890-...' ), // KSEF invoice numbers (multiple)
            [ 'invoiceSearch' ][ 'processingCode' ] = array ( 200, 400, ... ), // KSEF processing codes (multiple)
            [ 'invoiceSearch' ][ 'hasKsefNumber' ] = bool, // true = has KSEF number, false = no KSEF number
  
            // Sorting
            [ 'invoiceSearch' ][ 'orderBy' ] = 'issueDate' | 'number' | 'saleDate' | 'paymentDueDate'
            [ 'invoiceSearch' ][ 'orderDirection' ] = 'a' | 'd'
  
            // Pagination
            [ 'invoiceSearch' ][ 'perPage' ] = int default = 10
            [ 'invoiceSearch' ][ 'pageNo' ] = int default = 0 (0-based)
          )
      

Example

  require_once ( 'classUddsOx.php' ) ;

  $udds = new classUddsOx ;
  $udds->customerCode = [your_customerCode] ;
  $udds->login = [your_login] ;
  $udds->password = [your_password] ;
  $udds->serverUrl = 'http://api.dlaoperatora.pl/udds/' ;
  
  $yourParams = array();
  $yourParams [ 'invoiceSearch' ][ 'documentType' ] = array( 'FV', 'FK' );
  $yourParams [ 'invoiceSearch' ][ 'issueDateFrom' ] = '2026-01-01' ;
  $yourParams [ 'invoiceSearch' ][ 'issueDateTo' ] = date ( 'Y-m-d' ) ;
  $yourParams [ 'invoiceSearch' ][ 'orderBy' ] = 'issueDate' ;
  $yourParams [ 'invoiceSearch' ][ 'orderDirection' ] = 'd' ;
  $yourParams [ 'invoiceSearch' ][ 'perPage' ] = 20 ;
  $yourParams [ 'invoiceSearch' ][ 'pageNo' ] = 0 ;
  
  $ret = $udds->getInvoiceList ( $yourParams ) ;

Returns

Array with:

• itemsCount - total number of matching invoices
• items[] - array of invoice objects

Invoice object structure

{
  "id": "abc123",
  "head": {
    "number": "FV/001/2026",
    "documentType": "FV",           // FV, FK, PRO
    "issueDate": "2026-01-10",
    "issuePlace": "Warszawa",
    "saleDate": "2026-01-10",
    "saleDateText": "",
    "paymentDueDate": "2026-01-24",
    "paymentDueDateText": "",
    "paymentMethod": "Przelew",
    "status": "AKTYWNA",
    "group": "SPRZEDAZ",
    "advanceType": ""               // Zaliczka, Rozliczenie zaliczki
  },
  "seller": {
    "name": "Firma XYZ",
    "idBranch": "123",
    "bank": "PKO BP",
    "accountNumber": "12345678901234567890123456",
    "iban": "PL12345678901234567890123456",
    "swift": "PKOPPLPW",
    "idBankAccount": 1
  },
  "buyer": {
    "name": "Klient ABC",
    "address": "ul. Testowa 1",
    "city": "Kraków",
    "postCode": "30-001",
    "nip": "1234567890",
    "country": "Polska",
    "receivingPerson": "Jan Kowalski",
    "idCompany": 456,
    "idPerson": 789
  },
  "recipient": {
    "name": "",                     // if different from buyer
    "address": "",
    "city": "",
    "postCode": "",
    "nip": "",
    "country": "",
    "idCompany": 0,
    "idPerson": 0
  },
  "amounts": {                      // ALL VALUES IN GROSZE (cents)!
    "toPayPLN": 12300,              // = 123.00 PLN
    "toPayCurrency": 12300,         // in document currency (CFG_WALUTA)
    "nettoPLN": 10000,              // = 100.00 PLN
    "nettoCurrency": 10000,
    "bruttoPLN": 12300,
    "bruttoCurrency": 12300,
    "vatPLN": 2300,
    "paid": 0
  },
  "currency": {
    "code": "PLN",
    "exchangeRate": 10000,          // * 10000, so 10000 = 1.0000
    "exchangeRateDate": "2026-01-10",
    "template": "POLSKI",
    "templateLang": "PL",
    "calculationType": "netto"      // netto or brutto
  },
  "correction": {
    "relatedDocumentNumber": "",    // for FK only
    "relatedDocumentId": ""
  },
  "source": {
    "type": "",                     // e.g. "REZERWACJE"
    "id": "",
    "type2": "",
    "id2": ""
  },
  "info": {
    "notes": "",
    "printNotes": "0",
    "headerText": "",
    "footerText": "",
    "amountInWords": ""
  },
  "system": {
    "insertDate": "2026-01-10",
    "insertTime": "10:30:00",
    "insertUserId": 1,
    "updateDate": "2026-01-10",
    "updateTime": "10:30:00",
    "updateUserId": 1,
    "exportStatus": ""
  },
  "ksef": {                           // from KSEF_FAKTURY table (may be null if no record)
    "toKsef": 0,                      // 0 = not for KSEF, 1 = send to KSEF (default 0 if no record)
    "ksefNumber": null,               // KSEF invoice number (null if not sent)
    "processingCode": null,           // KSEF processing code (int)
    "statusDescription": null,        // KSEF status description
    "invoicingDatetime": null,        // datetime in KSEF system
    "upoLink": null,                  // UPO download link
    "verificationUrl": null,          // verification URL
    "upoHash": null,                  // UPO hash
    "invoiceHash": null               // invoice hash
  }
}