Required fields
InvoiceNumber: unique within the company for this invoice type, at most 20 characters. Send"Next"on create to generate it automatically from the ALFATNO number series."Next"cannot be sent on update.Date: the invoice date. If you send a time it is stored as the invoice time, otherwise the current time is used.CustomerCode: a customer the user can see.Lines: at least one line, each with its ownCurrencyCode.
DueDays (payment term in days) is stored with the invoice. ShipmentDefinitionCode (optional) comes from shipment definitions.
The invoice currency and EInvoiceType are not accepted in the request; the API determines them: CurrencyCode is sent per line, not on the header; the invoice’s currency is derived from the lines (when every line uses the same currency, that is the invoice currency, otherwise the company’s default currency) and returned as CurrencyCode/CurrencyId. AverageExchangeRate is filled from the lines and a value in the request is ignored (see currencies). EInvoiceType is returned in the response: 0 on purchase and sales return invoices and when the company does not use e-Invoice; on a sales or purchase return invoice of a company that uses e-Invoice, 1 (e-Invoice) when the customer is a registered e-Invoice user or ProfileId is IHRACAT, otherwise 2 (e-Archive).
Customer snapshot
The invoice’s address, title, tax number and tax office are not accepted in the request. They are copied from the customer at the moment the invoice is saved (the invoice address when the customer has one, otherwise the first address) and stay fixed afterward even if the customer changes later — this is why they only appear in responses (Address, CustomerTitle, TaxNumber, TaxOffice).
Lines
- The product is given with
ProductCode(the product’s code) orECommerceProductCode(its e-commerce integration code); one of them is required. If both are sent,ProductCodeis used.UnitCodeis required. The unit must be one of the product’s own units (its main unit, or its second/third unit). Quantitymust be greater than 0;UnitPricecannot be negative and must exclude VAT.VatIncludedis ignored (it is still accepted so that existing requests keep working).Discountsis the list of the line’s discount rates, applied one after another in list order.LineGroupNameis optional, from line groups.WarehouseNameis required when the product tracks stock (StockType2 to 7) and must be one of the company’s warehouses; such lines create a stock movement (see below). For a product that does not track stock (StockType1, or no stock type) the line never creates a stock movement;WarehouseNameis ignored even if sent.CurrencyCodeis required on every line.ExchangeRatemust be1when the line’s currency is the company’s default currency; otherwise it is required and must be greater than 0 (sent by the integrator, not calculated by the API).WithholdingCodeandWithholdingNumerator/WithholdingDenominatordescribe the line’s withholding (tevkifat) andWithheldVatAmountthe withheld VAT amount; they are stored as sent andWithheldVatAmountis checked like the other line amounts. The header’sApplyWithholding,WithholdingCode,WithholdingNumeratorandWithholdingDenominatorare filled from the lines: withholding is applied when any line has aWithholdingCode; the code, numerator and denominator are those of the withheld lines when they all share the same values, otherwise empty,1and1.AdditionalTaxesholds the line’s additional taxes (e.g. ÖTV): each hasCode(required),Rate,AmountandBase; at most 3 can be sent.Codemust be one of the additional tax codes and can be used only once on a line (3124,3125). Leave it empty when the line has none.
MainUnitQuantity in responses is Quantity converted to the product’s main unit, the same calculation as despatch lines: the quantity itself when UnitCode is the main unit, otherwise divided by the unit’s multiplier. It is positive when goods come in (purchase and sales-return invoices) and negative when they go out (sales and purchase-return invoices).
Stock movement, Lot and serial number tracking
A line whose product tracks stock also creates a stock movement when the invoice is saved (inbound for a purchase invoice). Depending on the product’s stock type the line carriesLots or SerialNumbers, following the same rules as despatches (a Lot-tracked product requires LotNo/Quantity/UnitCode, a FIFO/LIFO/FEFO product’s inbound entries create new lots, a serial-tracked product’s entries register new serial numbers).
The stock movement is also subject to the product’s critical stock controls that are set to stop the operation (4401, 4402, 4403).
Updating an invoice
Only the descriptive fields can be updated (Description, DocumentNumber, ShipmentDefinitionCode, SharingCode, PrintDescription, Consolidated, the return/order references, branch and investment incentive information, the energy period and the extra structured fields). The lines, customer, date and time, invoice number, payment term, amounts and taxes are fixed once the invoice is created: see Update purchase invoice. To correct them delete the invoice and create it again, or issue a return invoice. An invoice that has already been sent to GİB cannot be deleted (3027), but its descriptive fields can still be updated.
Linked orders and despatches
An invoice line created in the Noyax application by transferring an order or a despatch keeps its link to that order or despatch line; a line transferred from a despatch does not create its own stock movement, the despatch’s movement applies. The API does not create such transfers: invoices created through the API are not linked to orders or despatches, and every line with a warehouse creates its own stock movement.Customer ledger
Every purchase invoice always records a customer ledger entry (a credit, since a purchase invoice increases what the company owes the supplier) — unlike an order’s optionalCreateCustomerMovement, there is no toggle. If that ledger entry has already been closed by a collection/payment, the invoice’s customer, amount and currency can no longer be changed, and the invoice cannot be deleted (3015).
The entry’s amount is the invoice’s GrandTotal; on a sales invoice with InvoiceTypeCode IHRACKAYITLI the deferred taxes are deducted (see sales invoices).
Save-time checks
ProfileIdandInvoiceTypeCodeare used only on sales and purchase return invoices; on purchase and sales return invoices they are ignored. When the company uses e-Invoice, both are required on sales and purchase return invoices; otherwise both are optional.- On a purchase return invoice
InvoiceTypeCodemust beIADEorTEVKIFATIADE; on a sales invoice these two values are not allowed (3029). - When both
ProfileIdandInvoiceTypeCodeare sent,InvoiceTypeCodemust be one of the values GİB allows for thatProfileId(see the table below). - If a line’s
VatRateis0,VatExemptionCodemust be filled in when the invoice is an e-document (e-Invoice or e-Archive, seeEInvoiceTypeabove). - On a sales invoice, if any line has a
VatExemptionCode,InvoiceTypeCodemust beISTISNA,IHRACKAYITLIorSGK. - On a sales invoice with
InvoiceTypeCodeIHRACKAYITLI, a line with VAT and an emptyVatExemptionCodegets701. - When the company uses e-Invoice, the selected customer’s tax number, invoice title and tax office must be filled in, on a sales or purchase return invoice.
Extra structured fields
The invoice accepts a set of additional, entirely optional fields for less common scenarios (export, public sector, SGK, pharmaceutical/medical device, Hal). None of them are validated by the API or tied toProfileId/InvoiceTypeCode in any way: whatever you send is stored and returned as-is, and it is your responsibility to send the ones relevant to your own ProfileId.
Header: DeliveryInfo (export delivery address and terms), PaymentMeans (payment methods), ReferencedDespatches (despatches this invoice references), CustomerIdentitySchemes (additional customer identity numbers, e.g. MUSTERINO, TICARETSICILNO), PublicSectorSpendingUnit (the public-sector unit that will make the payment) and SgkInfo (social security invoice details).
Line: ExportInfo (export delivery/packaging details for the line), MedicineDeviceInfo (pharmaceutical/medical device tracking rows), HalInfo (wholesale produce market receipt information) and ProductInfo (model, brand, origin country and other identifiers).
Sharing
SharingCode limits who can see the invoice: empty means visible to everyone, otherwise it must be one of the user’s sharing codes. Invoices the user cannot see return 404.