This POST method allows you to create a new sales invoice and automatically mutate the invoiced products stock levels based on the invoice line quantities. This method will create an invoice within the ‘Facturatie’ (Invoicing) module of our software.
Notes:
- Maximum 75 invoice lines per invoice allowed.
- If CustomerNumber is used to identify the customer, the parameters CustomerName and CustomerEmail will be ignored.
- If CustomerName or CustomerEmail is used to identify the customer, and you have multiple customers that match, we will use the first found match.
- The parameters CustomerName and CustomerEmail can also be used combined. When both parameters are submitted, the system will search for relations where both name and e-mail match with the submitted parameters.
- You are required to add at least one invoice line. The invoice line must either contain the parameter ‘ProductNumber‘ or ‘ProductEAN‘. The value entered in either of those fields must refer to an existing product in your Silvasoft administration.
- A stock mutation for the selected product will be automatically created.
- Submitting an address is optional, if no address is submitted the default address for the relation will be used. When an address is submitted we will add the address to the relation file (CRM), if the address does not already exist. You can submit both a billing and shipping address using the ‘Address_Type’ field.
- When submitting attachments you can either submit it by URL (Silvasoft will download the file from the URL) or as a binary string in the field ‘FileContent’. In both cases the file will be mime checked and it cannot be greater than 10mb. When using ‘FileContent’ you must supply a name as well.
- Request
- Response
Parameters
CustomerNumber **
Integer
Details
The customer, identified by its customer number, to be associated with the invoice
CustomerName **
String
Details
The customer, identified by its name, to be associated with the invoice
CustomerEmail **
String
Details
The customer, identified by its e-mailaddress, to be associated with the invoice
AddAsDraft
Boolean (true|false)
Details
Defaults to false. If set to true, the invoice will we added as a draft ('concept' invoice)
InvoiceDate
Date String (dd-MM-yyyy)
Details
The invoice date in format dd-MM-yyyy. (http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html) Defaults to current date.
InvoiceNumber
Long
Details
An optional invoice number. Please note this number MUST be unique.
InvoiceNotes
String
Details
The invoice description
InvoiceDiscountPc
Float
Details
Discount % to be applied to the invoice. This will always be deducted from the total, even if you submit "SubTotalInclTax" for your invoice lines.
InvoiceReference
String
Details
Invoice reference number or text (max. 150 characters)
InvoiceDueDays
Integer
Details
In how much days must the invoice be payed? Leave empty or set to 0 to ignore.
InvoiceDueDate
Date String (dd-MM-yyyy)
Details
The due date for this invoice. Will be ignored and automatically calculated if InvoiceDueDays is set.
PackingSlipNotes
String
Details
Extra notes for the packing slip
InvoiceProject
String
Details
The project by either projectnumber or project name to be associated with the invoide
SelectProjectBy
String
Details
Allowed values: NAME or NUMBER. Determines wether the value in the parameter 'InvoiceProject' is the projectname or projectnumber.
OGM_Belgium
String
Details
A string containing the structured remittance information (OGM). This is only applicable for Belgian Silvasoft customers. Leave this empty if you want Silvasoft to generate the OGM (the generated OGM will be available in the response).
TemplateName_Invoice
String
Details
The template name to be used to generate the PDF invoice. If empty or not found the system will fall back to the default template or the template configured for the relation. To empty the template, use the quote "EMPTY".
TemplateName_Email
String
Details
The template name to be used to generate the e-mail contents. If empty or not found the system will fall back to the default template or the template configured for the relation. To empty the template, use the quote "EMPTY".
InvoiceForOrderNumber
Long
Details
If you want to associate this invoice to an order and also change the status of the order to "invoiced" then you can submit the ordernumber here. This setting will only work if a sales order is found belonging to the same relation als this invoice and with the number submitted here.
EmailToCustomer
Boolean (true|false)
Details
Whether you want to sent the generated invoice to the customer per e-mail. Defaults to false. E-mailing is done in background and there can be an delay of approx. 30 minutes before the mail is sent after the invoice is created.
HtmlAsPlainText
Boolean (true|false)
Details
Whether the response rich-text fields (notes and packing slip notes) will be returned as plain text or not. Defaults to false.
PeriodicInvoiceTemplate
Boolean (true|false)
Details
Defaults to false. Whether this invoice is a recurring/periodic invoice. If set to true please also submit at least the parameters "Periodic_StartingDate, Periodic_Frequency, Periodic_FrequencyUnit". Periodic / recurring invoices can be found in Silvasoft under the menu: Facturatie > Periodieke facturatie.
Periodic_StartingDate
Date String (dd-MM-yyyy)
Details
The start date for this recurring invoice template. If set to today, Silvasoft will directly create an invoice.
Periodic_EndDate
Date String (dd-MM-yyyy)
Details
The end date for this recurring invoice template.
Periodic_AutomaticMailing
Boolean (true|false)
Details
Do you want to e-mail created invoices automatically? If set to false Silvasoft will create the periodic invoice but not e-mail it to your customer.
Periodic_Frequency
Integer
Details
Every how many days,weeks,months,years do you want an invoice to be created?
Periodic_FrequencyUnit
String
Details
Choose from: Day,Week,Month,Year
Periodic_ChangeDateTokensValue
Integer
Details
The amount of months to change the date tokens with. For example: set to 1 to increase or decrease (depending on "Periodic_ChangeDateTokensBeforeAfter") the dates shown in the description of the final invoice with 1 month.
Periodic_ChangeDateTokensBeforeAfter
String
Details
Choose from: Before, After
Periodic_SkipWeekends
Boolean (true|false)
Details
Set to true if you don't want this template to generate invoices on weekend days.
Invoice_InvoiceLine *
Array
Details
A JSON array of invoice lines. At least one record must be present.
Invoice_InvoiceLine > ProductNumber **
String
Details
The productnumber of the product to be associated with the invoice line.
Invoice_InvoiceLine > ProductEAN **
String
Details
The product EAN code of the product to be associated with the invoice line.
Invoice_InvoiceLine > Quantity *
Float
Details
Quantity of units of the product for this invoice line
Invoice_InvoiceLine > UnitPriceExclTax
Float
Details
Price per ordered unit
Invoice_InvoiceLine > TaxPc
Float
Details
Numeric representation of the tax % to be applied for this invoice line. Please note that this percentage must be available within your Silvasoft administration. If no tax details are submitted Silvasoft will use the tax percentage as configured for the product.
Invoice_InvoiceLine > TaxCode
String
Details
The tax code to apply to this invoice line. For example if you have multiple tax codes with the same percentage, you can identify a specific tax code with this parameter. If no tax details are submitted Silvasoft will use the tax percentage as configured for the product.
Invoice_InvoiceLine > SubTotalInclTax
Float
Details
The invocie line subtotal, including taxes. When this parameter is set, the price per unit will be ignored and automatically calculated. If this parameter is not submitted then the subtotal will be the "Quantity" times "UnitPriceExclTax" times tax. Please note that this field behaves as a line total, including taxes, including line discount, excluding invoice discount. So this price will never change, except when an invoice discount is submitted ("InvoiceDiscountPc").
Invoice_InvoiceLine > Description
String
Details
Invoice line description
Invoice_InvoiceLine > CostCenter
String
Details
The Cost Center for the invoiceline (Dutch: Kostenplaats). If the Cost Center does not exist in your administration, a new one will be created.
Invoice_InvoiceLine > IsTextLine
Boolean (true|false)
Details
If this is a text line you can set this to true and omit price and tax fields
Invoice_InvoiceLine > TextLineCategory
String
Details
Optionally submit the name of the text category. If nothing is submitted the default text category will be used.
Invoice_InvoiceLine > LedgerAccountNumber
String
Details
The ledger accountnumber (Dutch: Grootboekrekeningnummer) to be associated with the invoiceline. The ledger account must be present in your administration.
Invoice_InvoiceLine > DiscountPc
String
Details
Invoiceline discount %. Please note that the behaviour of line discount depends on how your submit your line total. If you submit the "SubTotalInclTax" then the discount will be added, but not change the line total since the "SubTotalInclTax" behaves as a subtotal, AFTER discount. However, if you submit only a "Quantity" and a "UnitPriceExclTax" then the discount will be applied to the subtotal of "Quantity" times "UnitPriceExclTax" since this combination behaves as a total price BEFORE discount.
Invoice_InvoiceLine > DiscountAmountInclTax
String
Details
Invoiceline discount amount in EUR. Please note that the behaviour of line discount depends on how your submit your line total. If you submit the "SubTotalInclTax" then the discount will be added, but not change the line total since the "SubTotalInclTax" behaves as a subtotal, AFTER discount. However, if you submit only a "Quantity" and a "UnitPriceExclTax" then the discount will be applied to the subtotal of "Quantity" times "UnitPriceExclTax" since this combination behaves as a total price BEFORE discount.
Invoice_InvoiceLine > UseArticlePrice
Boolean (true|false)
Details
If set to true (default is false) you will not need to supply any price details for this line. Silvasoft will get the default product price and discount rules for the article or article category, as configured within your administration.
Invoice_Address
Array
Details
A JSON array of addresses. If no address is submitted the default address for the relation will be used.
Invoice_Address > Address_City
String
Details
The address (city) to be used for the invoice. If the address does not already exist it will be added as a new address to the customer (CRM).
Invoice_Address > Address_Street
String
Details
The address (street) to be used for the invoice. If the address does not already exist it will be added as a new address to the customer (CRM).
Invoice_Address > Address_PostalCode
String
Details
The address (postalcode) to be used for the invoice. If the address does not already exist it will be added as a new address to the customer (CRM).
Invoice_Address > Address_CountryCode
String
Details
The address (ISO 3166 (A2) countrycode) to be used for the invoice. If the address does not already exist it will be added as a new address to the customer (CRM).
Invoice_Address > Address_Unit
String
Details
The address (unit) to be used for the invoice. If the address does not already exist it will be added as a new address to the customer (CRM).
Invoice_Address > Address_UnitAppendix
String
Details
The address (unit appendix) to be used for the invoice. If the address does not already exist it will be added as a new address to the customer (CRM).
Invoice_Address > Address_Type
String
Details
Allowed values: ShippingAddress and BillingAddress. Shipping_Address will be used for the packing slip. If no ShippingAddress is submitted the billing address will be used for the packing slip.
Invoice_Attachment
Array
Details
An array of attachments to add to this invoice.
Invoice_Attachment > FileUrl
String
Details
Method 1: Add an attachment by using a URL pointing to the file to be attached to the invoice. The file will be downloaded and added as attachment. If the file is not downloadable, the order will still be created but without the attachment. The file URL must end with one of the following file extensions in order for it to be added to the order: .jpg, .png, .pdf, .doc, .docx, .xls, .xlsx
Invoice_Attachment > FileContent
String
Details
Method 2: Add an attachment as a binary string. When this field is submitted you MUST submit a FileName as well.
Invoice_Attachment > Internal
Boolean (true|false)
Details
Whether the attachment is 'Internal' (true) or 'Public' (false). Defaults to false.
Invoice_Attachment > FileName
String
Details
The name of the attachment WITH extension. Required when using 'FileContent'. Optional when using 'FileUrl'. If left empty a name will be auto-generated based on the current timestamp.
Invoice_SalesPerson
Array
Details
An array containing the salesperson. Only the first person will be used
Invoice_SalesPerson > FirstName
String
Details
Salesperson's first name
Invoice_SalesPerson > LastName
String
Details
Salesperson's last name
Invoice_SalesPerson > Prefix
String
Details
Salesperson's prefix
CURL Example
1 |
curl -X POST -H "Content-Type: application/json" -H "ApiKey: b7d343Bnhd436f3ec3bd3504582" -H "Username: john@doe.nl" "https://rest-api.silvasoft.nl/rest/addsalesinvoice/" |
Parameters
Response JSON Example
The response order can vary from the parameter order above
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 |
[ { "InvoiceReference":"system-X-1234", "InvoiceOutstandingAmount":789.69, "InvoiceNotes":"Invoices created from API", "ProjectName":"Pr-123", "ProjectNumber":"1", "InvoiceTotalInclTax":789.69, "InvoiceType":"INVOICING", "PackingSlipNotes":"Extra note to be added to the packing-slip", "CustomerNumber":1, "InvoiceTaxAmount":97.29, "InvoiceDueDate":"26-05-2017", "CustomerName":"Demo bedrijf", "InvoiceNumber":2, "InvoiceDate":"05-05-2017", "InvoiceTotalExclTax":692.4, "OGM_Belgium": "+++443/1414/00040+++", "Invoice_Contact":[ { "ContactType":"Invoice", "Email":null, "ContactNotes":null, "FamilyName":"Janssens", "FirstName":"Hendrik", "Phone":null, "Sex":"Man", "LastName":"Janssens", "DefaultContact":true }, { "ContactType":"PackingSlip", "Email":null, "ContactNotes":null, "FamilyName":"Janssens", "FirstName":"Hendrik", "Phone":null, "Sex":"Man", "LastName":"Janssens", "DefaultContact":true } ], "Invoice_Address":[ { "Address_CountryCode":"BE", "Address_Unit":"55", "Address_City":"Antwerpen", "Address_UnitAppendix":"", "AddressType":"BillingAddress", "Address_PostalCode":"2018", "Address_Street":"Voorbeeldstraat" } ] } ] |