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

Related endpoints

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