Function createInvoiceHead

Description

Creates an invoice header (without line items). Line items should be added separately using createInvoiceItem endpoint.

Document Types (documentType)

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

Important notes

• Invoice is created with zero amounts (no line items yet)
• Invoice number is generated automatically from sequence 'Faktury'
• Payment due date is calculated from system parameter if not provided
• Exchange rate is fetched from NBP rates for non-PLN currencies
• A record in KSEF_FAKTURY is automatically created

Arguments

• params :

      array (
            // === REQUIRED FIELDS ===
            
            [ 'issuePlace' ] = string,      // Place of issue (e.g. 'Warszawa')
            [ 'issueDate' ] = 'yyyy-mm-dd', // Issue date
            [ 'saleDate' ] = 'yyyy-mm-dd',  // Sale date
            [ 'paymentMethod' ] = string,   // e.g. 'przelew', 'gotówka', 'karta'
            [ 'documentType' ] = string,    // 'FV', 'FK', 'PRO'
            [ 'status' ] = string,          // e.g. 'AKTYWNA'
            [ 'template' ] = string,        // 'VAT' or 'MARZA'
            [ 'currency' ] = string,        // 'PLN', 'EUR', 'USD', etc. (from dictionary)
            
            // Buyer (required)
            [ 'buyerName' ] = string,       // Full name
            [ 'buyerAddress' ] = string,    // Street and number
            [ 'buyerCity' ] = string,       // City
            [ 'buyerPostCode' ] = string,   // Postal code
            [ 'buyerNip' ] = string,        // Tax ID (NIP)
            
            // === CONDITIONAL FIELDS ===
            
            // Required for FK (correction invoice)
            [ 'relatedDocumentId' ] = string, // ID of corrected invoice
            
            // === OPTIONAL FIELDS ===
            
            [ 'sellerName' ] = string,          // Seller name (if not provided, taken from logged user's OSOBY.IMIE + NAZWISKO)
            [ 'paymentDueDate' ] = 'yyyy-mm-dd', // If not provided, calculated from system parameter
            [ 'calculationType' ] = string,      // 'netto' (default) or 'brutto'
            [ 'advanceType' ] = string,          // '', 'Zaliczka', 'Rozliczenie zaliczki'
            [ 'exchangeRate' ] = int,            // Rate * 10000 (if not provided, fetched from NBP)
            [ 'exchangeRateDate' ] = 'yyyy-mm-dd',
            
            // Buyer (optional)
            [ 'buyerCountry' ] = string,
            [ 'buyerReceivingPerson' ] = string,
            [ 'buyerCompanyId' ] = int,     // ID from FIRMY table
            [ 'buyerPersonId' ] = int,      // ID from OSOBY table
            
            // Recipient (if different from buyer)
            [ 'recipientName' ] = string,
            [ 'recipientAddress' ] = string,
            [ 'recipientCity' ] = string,
            [ 'recipientPostCode' ] = string,
            [ 'recipientNip' ] = string,
            [ 'recipientCountry' ] = string,
            [ 'recipientCompanyId' ] = int,
            [ 'recipientPersonId' ] = int,
            
            // Additional info
            [ 'notes' ] = string,           // Additional notes
            [ 'printNotes' ] = string,      // '0' or '1' - print notes on invoice
            [ 'headerText' ] = string,      // Header text
            [ 'footerText' ] = string,      // Footer text
            [ 'group' ] = string,           // Invoice group
            [ 'saleDateText' ] = string,    // Sale date in words
            [ 'paymentDueDateText' ] = string, // Payment due date in words
            [ 'templateLang' ] = string,    // '', 'PL', 'DE', 'EN'
            
            // Source linking
            [ 'source' ] = string,          // e.g. 'rezerwacja'
            [ 'sourceId' ] = string,        // ID of source entity
            [ 'source2' ] = string,
            [ 'sourceId2' ] = string,
            
            // KSEF
            [ 'toKsef' ] = int,             // 0 or 1 - send to KSEF
          )
      

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/' ;
  
  $params = array();
  $params['issuePlace'] = 'Warszawa';
  $params['issueDate'] = date('Y-m-d');
  $params['saleDate'] = date('Y-m-d');
  $params['paymentMethod'] = 'przelew';
  $params['documentType'] = 'FV';
  $params['status'] = 'AKTYWNA';
  $params['template'] = 'VAT';
  $params['currency'] = 'PLN';
  
  $params['buyerName'] = 'Firma ABC Sp. z o.o.';
  $params['buyerAddress'] = 'ul. Przykładowa 1';
  $params['buyerCity'] = 'Warszawa';
  $params['buyerPostCode'] = '00-001';
  $params['buyerNip'] = '1234567890';
  
  $ret = $udds->createInvoiceHead($params);
  
  // $ret['status'] == 'OK' on success
  // $ret['id'] = invoice ID (32 char GUID)
  // $ret['number'] = invoice number (e.g. '0001/02/2026')

Returns

Success response

{
  "status": "OK",
  "id": "00000004M1G221031126JF1B44ASNQ6D",
  "number": "0001/02/2026",
  "errors": []
}

Error response

{
  "status": "ERROR",
  "id": null,
  "number": null,
  "errors": [
    { "code": 1001, "message": "Pole Data wystawienia (issueDate) jest wymagane" },
    { "code": 1002, "message": "Nieprawidłowa waluta. Dozwolone: PLN, EUR, USD" }
  ]
}

Error codes

Code	Description
1001	Missing required field
1002	Invalid dictionary value (documentType, template, currency, calculationType)
1003	Invalid date format (must be YYYY-MM-DD)
1004	Bank account not found for company
1005	Invoice number sequence error
1006	Related document not found (for FK correction)
1007	Database error

Related endpoints

• createInvoiceItem - Add line items to invoice
• getInvoiceList - List invoices
• sendInvoiceToKsef - Send invoice to KSEF