Skip to main content
A purchase invoice has a header and one or more lines. The invoice type is never a field in the request: it is fixed by the endpoint you call. There are four invoice endpoint groups — Purchase, Sales, Purchase Return and Sales Return — sharing the same fields, numbering mechanism and result codes, with the differences noted on each page.
The API does not calculate line amounts, but it checks that they add up. Line amounts, discount amounts, VAT, additional taxes and withholding are stored as you send them (the same fields as despatch lines); a line whose amounts do not follow Noyax’s rules is rejected (3126). The invoice totals, AverageExchangeRate and the header’s withholding fields are filled from the lines; values sent for them are ignored. The API also calculates the invoice’s currency (derived from the lines) and a line’s main unit quantity. A line’s AdditionalTaxes follow the same rules as the product’s additional taxes: at most 3, each Code required and one of the listed codes, and a code can be used only once on a line.

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 own CurrencyCode.
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) or ECommerceProductCode (its e-commerce integration code); one of them is required. If both are sent, ProductCode is used. UnitCode is required. The unit must be one of the product’s own units (its main unit, or its second/third unit).
  • Quantity must be greater than 0; UnitPrice cannot be negative and must exclude VAT. VatIncluded is ignored (it is still accepted so that existing requests keep working).
  • Discounts is the list of the line’s discount rates, applied one after another in list order.
  • LineGroupName is optional, from line groups.
  • WarehouseName is required when the product tracks stock (StockType 2 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 (StockType 1, or no stock type) the line never creates a stock movement; WarehouseName is ignored even if sent.
  • CurrencyCode is required on every line. ExchangeRate must be 1 when 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).
  • WithholdingCode and WithholdingNumerator/WithholdingDenominator describe the line’s withholding (tevkifat) and WithheldVatAmount the withheld VAT amount; they are stored as sent and WithheldVatAmount is checked like the other line amounts. The header’s ApplyWithholding, WithholdingCode, WithholdingNumerator and WithholdingDenominator are filled from the lines: withholding is applied when any line has a WithholdingCode; the code, numerator and denominator are those of the withheld lines when they all share the same values, otherwise empty, 1 and 1.
  • AdditionalTaxes holds the line’s additional taxes (e.g. ÖTV): each has Code (required), Rate, Amount and Base; at most 3 can be sent. Code must 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 carries Lots 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 optional CreateCustomerMovement, 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

  • ProfileId and InvoiceTypeCode are 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 InvoiceTypeCode must be IADE or TEVKIFATIADE; on a sales invoice these two values are not allowed (3029).
  • When both ProfileId and InvoiceTypeCode are sent, InvoiceTypeCode must be one of the values GİB allows for that ProfileId (see the table below).
  • If a line’s VatRate is 0, VatExemptionCode must be filled in when the invoice is an e-document (e-Invoice or e-Archive, see EInvoiceType above).
  • On a sales invoice, if any line has a VatExemptionCode, InvoiceTypeCode must be ISTISNA, IHRACKAYITLI or SGK.
  • On a sales invoice with InvoiceTypeCode IHRACKAYITLI, a line with VAT and an empty VatExemptionCode gets 701.
  • 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 to ProfileId/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.