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

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

Related endpoints