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

CodeDescription
1001Missing idInvoice parameter
1002Invoice not found
1003Invoice already sent to KSEF (cannot modify)
1004Invalid dictionary value (currency, status, template, calculationType)
1005Invalid date format (must be YYYY-MM-DD)
1006Forbidden field (documentType, relatedDocumentId cannot be changed)
1007Database error

Related endpoints