Function updateInvoiceHead

Description

Updates an existing invoice header. Only provided fields are updated - missing fields retain their current values.

Important notes

• All fields are optional (except idInvoice) - only provided fields are updated
• Forbidden fields: documentType and relatedDocumentId cannot be changed (create a new invoice instead)
• Cannot update invoices already sent to KSEF (have KSEF_NUMBER)
• If you change currency, the exchange rate is automatically fetched
• Modification timestamps are always updated (DATA_MODYFIKACJI, ID_MODYFIKUJACEGO)

Arguments

• params :

      array (
            // === REQUIRED ===
            
            [ 'idInvoice' ] = string,          // Invoice ID (32 char GUID)
            
            // === OPTIONAL - Basic info ===
            
            [ 'issuePlace' ] = string,         // Place of issue
            [ 'issueDate' ] = string,          // Issue date (YYYY-MM-DD)
            [ 'saleDate' ] = string,           // Sale date (YYYY-MM-DD)
            [ 'paymentDueDate' ] = string,     // Payment due date (YYYY-MM-DD)
            [ 'paymentMethod' ] = string,      // Payment method
            [ 'status' ] = string,             // Status: 'AKTYWNA' | 'TYMCZASOWA'
            [ 'template' ] = string,           // Template: 'VAT' | 'MARZA'
            [ 'currency' ] = string,           // Currency code (PLN, EUR, USD...)
            [ 'calculationType' ] = string,    // 'netto' | 'brutto'
            [ 'advanceType' ] = string,        // '' | 'Zaliczka' | 'Rozliczenie zaliczki'
            [ 'templateLang' ] = string,       // Template language: '' | 'PL' | 'EN' | 'DE'
            
            // === OPTIONAL - Buyer (nabywca) ===
            
            [ 'buyerName' ] = string,          // Buyer company/person name
            [ 'buyerAddress' ] = string,       // Street address
            [ 'buyerCity' ] = string,          // City
            [ 'buyerPostCode' ] = string,      // Postal code
            [ 'buyerNip' ] = string,           // Tax ID (NIP)
            [ 'buyerCountry' ] = string,       // Country
            [ 'buyerReceivingPerson' ] = string, // Person receiving document
            [ 'buyerCompanyId' ] = string,     // Link to FIRMY.ID_FIRMY
            [ 'buyerPersonId' ] = string,      // Link to OSOBY.ID_OSOBY
            
            // === OPTIONAL - Recipient (odbiorca, if different from buyer) ===
            
            [ 'recipientName' ] = string,
            [ 'recipientAddress' ] = string,
            [ 'recipientCity' ] = string,
            [ 'recipientPostCode' ] = string,
            [ 'recipientNip' ] = string,
            [ 'recipientCountry' ] = string,
            [ 'recipientCompanyId' ] = string,
            [ 'recipientPersonId' ] = string,
            
            // === OPTIONAL - Seller ===
            
            [ 'sellerName' ] = string,         // Seller/salesperson name
            
            // === OPTIONAL - Additional info ===
            
            [ 'notes' ] = string,              // Notes to print on invoice
            [ 'printNotes' ] = string,         // '0' | '1' - whether to print notes
            [ 'headerText' ] = string,         // Custom header text
            [ 'footerText' ] = string,         // Custom footer text
            [ 'group' ] = string,              // Invoice group
            [ 'saleDateText' ] = string,       // Sale date in words
            [ 'paymentDueDateText' ] = string, // Payment due date in words
            
            // === OPTIONAL - Source linking ===
            
            [ 'source' ] = string,             // Source entity type (e.g., 'rezerwacja')
            [ 'sourceId' ] = string,           // Source entity ID
            [ 'source2' ] = string,            // Secondary source type
            [ 'sourceId2' ] = string,          // Secondary source ID
            
            // === OPTIONAL - KSEF ===
            
            [ 'toKsef' ] = int,                // 0 | 1 - flag for KSEF sending
          )
      

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/' ;
  
  // Update buyer info and status
  $params = array();
  $params['idInvoice'] = '00000004M1G221031126JF1B44ASNQ6D';
  $params['buyerName'] = 'Nowa Firma Sp. z o.o.';
  $params['buyerAddress'] = 'ul. Nowa 123';
  $params['buyerCity'] = 'Kraków';
  $params['status'] = 'AKTYWNA';
  
  $ret = $udds->updateInvoiceHead($params);
  
  // $ret['status'] == 'OK' on success
  // $ret['idInvoice'] = invoice ID
  // $ret['number'] = invoice number (unchanged)
  // $ret['updatedFields'] = list of fields that were updated

Example: change payment terms only

  $params = array();
  $params['idInvoice'] = '...';
  $params['paymentMethod'] = 'gotówka';
  $params['paymentDueDate'] = '2026-03-15';
  $params['paymentDueDateText'] = 'płatne przy odbiorze';
  
  $ret = $udds->updateInvoiceHead($params);
  // Only payment fields are updated

Example: change currency

  $params = array();
  $params['idInvoice'] = '...';
  $params['currency'] = 'EUR';
  
  $ret = $udds->updateInvoiceHead($params);
  // Exchange rate is automatically fetched and updated
  // NOTE: Existing items are NOT recalculated! 
  // Change currency only on invoices without items.

Returns

Success response

{
  "status": "OK",
  "idInvoice": "00000004M1G221031126JF1B44ASNQ6D",
  "number": "FV/0001/02/2026",
  "updatedFields": {
    "buyerName": "Nowa Firma Sp. z o.o.",
    "buyerAddress": "ul. Nowa 123",
    "buyerCity": "Kraków",
    "status": "AKTYWNA"
  },
  "errors": []
}

Error response

{
  "status": "ERROR",
  "errors": [
    { "code": 1003, "message": "Nie można modyfikować faktury wysłanej do KSEF (numer: 123456)" }
  ]
}

Error codes

Related endpoints

• createInvoiceHead - Create new invoice
• getInvoice - Get invoice details
• updateInvoiceItem - Update invoice item
• setInvoiceStatus - Quick status change
• getInvoiceList - List invoices