Function createInvoiceItem

Description

Adds a line item to an existing invoice. Automatically calculates values and updates invoice totals.

Calculation method

• Algorithm: Method 2 (WARTOSC_NETTO × vatRate = KWOTA_VAT, then BRUTTO = NETTO + VAT)
• VAT summary: Sum of partial VAT amounts from items
• Rounding: Polish method (standard mathematical rounding)

Important notes

• quantity is stored as value × 100 (e.g., 0.5 pieces = 50)
• All prices and values are in grosze (cents) - multiply by 100
• Invoice totals (RAPORT_*, DO_ZAPLATY_*, SLOWNIE) are updated automatically
• Cannot add items to invoices already sent to KSEF
• The required price field depends on invoice's WYLICZANIE_FAKTURY:
  • netto → requires priceNetto
  • brutto → requires priceBrutto

Arguments

• params :

      array (
            // === REQUIRED FIELDS ===
            
            [ 'idInvoice' ] = string,       // Invoice ID (32 char GUID)
            [ 'name' ] = string,            // Product/service name
            [ 'quantity' ] = int,           // Quantity × 100 (e.g., 1 pc = 100, 0.5 kg = 50)
            [ 'unit' ] = string,            // Unit of measure (from dictionary: 'szt.', 'kg', 'mb', etc.)
            [ 'vatRate' ] = string,         // VAT rate (from dictionary: '23', '8', '5', '0', 'zw', 'np')
            
            // === PRICE (one required depending on invoice calculation type) ===
            
            [ 'priceNetto' ] = int,         // Net unit price in grosze (required when invoice calculationType = 'netto')
            [ 'priceBrutto' ] = int,        // Gross unit price in grosze (required when invoice calculationType = 'brutto')
            
            // === MANUAL MODE (optional) ===
            
            [ 'manualMode' ] = bool,        // If true, all values below are required and used as-is
            [ 'valueNetto' ] = int,         // Total net value in grosze (only with manualMode)
            [ 'valueBrutto' ] = int,        // Total gross value in grosze (only with manualMode)
            [ 'valueVat' ] = int,           // VAT amount in grosze (only with manualMode)
            
            // === OPTIONAL FIELDS ===
            
            [ 'sww' ] = string,             // SWW code
            [ 'gtu' ] = string,             // GTU code
            [ 'accountNumber' ] = string,   // Accounting account number
          )
      

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/' ;
  
  // Add item to existing invoice
  $params = array();
  $params['idInvoice'] = '00000004M1G221031126JF1B44ASNQ6D';
  $params['name'] = 'Usługa konsultingowa';
  $params['quantity'] = 100;       // 1 piece (×100)
  $params['unit'] = 'szt.';
  $params['vatRate'] = '23';
  $params['priceNetto'] = 50000;   // 500.00 PLN (in grosze)
  
  $ret = $udds->createInvoiceItem($params);
  
  // $ret['status'] == 'OK' on success
  // $ret['id'] = item ID
  // $ret['idInvoice'] = invoice ID
  // $ret['calculatedValues'] = calculated prices and values

Example with fractional quantity

  // 0.5 kg of product at 32 PLN/kg net
  $params = array();
  $params['idInvoice'] = '...';
  $params['name'] = 'Produkt na wagę';
  $params['quantity'] = 50;        // 0.5 kg (×100)
  $params['unit'] = 'kg';
  $params['vatRate'] = '23';
  $params['priceNetto'] = 3200;    // 32.00 PLN/kg (in grosze)
  
  // Result:
  // valueNetto = 3200 × 50 / 100 = 1600 (16.00 PLN)
  // valueVat = round(1600 × 23 / 100) = 368 (3.68 PLN)
  // valueBrutto = 1600 + 368 = 1968 (19.68 PLN)

Returns

Success response

{
  "status": "OK",
  "id": "ABCD1234EFGH5678IJKL9012MNOP3456",
  "idInvoice": "00000004M1G221031126JF1B44ASNQ6D",
  "calculatedValues": {
    "priceNetto": 50000,
    "priceBrutto": 61500,
    "valueNetto": 50000,
    "valueBrutto": 61500,
    "valueVat": 11500
  },
  "errors": []
}

Error response

{
  "status": "ERROR",
  "id": null,
  "errors": [
    { "code": 1001, "message": "Pole Nazwa towaru/usługi (name) jest wymagane" }
  ]
}

Error codes

Code	Description
1001	Missing required field
1002	Invalid dictionary value (unit, vatRate)
1003	Invoice not found
1004	Invoice already sent to KSEF (cannot modify)
1005	Manual mode requires all value fields
1006	Database error

Related endpoints

• createInvoiceHead - Create invoice header first
• getInvoiceList - List invoices
• sendInvoiceToKsef - Send invoice to KSEF