1. Accounting
  2. Sales Receipt

Sales Receipt POST

URI

https://{DATACENTER}.brightpearlconnect.com/public-api/{ACCOUNT}
/accounting-service/invoice/sales-receipt/

Refer to our documentation on URI syntax for more information on how to construct URIs.

Description

Transforms the Receipt resource sent into the corresponding journal lines. This endpoint uses specific logic to validate the receipt representation, but then delegates to the journal entry logic to validate and create the lines in the database.
Using the adjustment field in a payment you can specify a certain amount to be taken from or redirected to a difference nominal code.

Sales Receipt POST Validation

Mandatory elements are the header, and at least one payment line

The fields that are mandatory in the header component are:

  • contactId
  • bankAccountNominalCode - unless the payments balance is 0
  • taxDate
  • exchangeRate (if currencyId is not the base currency)

The fields that are mandatory in each payment line are:

  • value

All currency values in the payload must be specified as strings, not as number types.

Other validations are:

  • The order id must be in the system
  • The order must be of type "sales order" or "sales credit"
  • The contact id must be in the system
  • The contact must be of type "customer"
  • The contact must be the primary contact for the order
  • The nominal code must be a bank account or an adjustment account
  • For each invoice reference given we check that the currency specified is compatible with the previous entries (if any):
    • If previous currency is not a base currency then the specified currency must be the same of the previous entries
    For further info see paragraph "Currency conversion" below.
  • If an adjustment is added to a payment it must have both value and nominal code
  • The sum of the payment and adjustment cannot be greater than the invoice amount

The journal-entry POST is then validating additional accounting rules, if applicable.

Default values are:

  • If currency id is not sent, it defaults to the base currency (unless exchange rate sent it not 1)
  • If no invoice reference is specified for a line then a temporary reference is created with this form accnt-JOURNAL_ID (where JOURNAL_ID is the number of the journal id being created)

Calculations and currency conversions:

  • If all journals for all invoices in the SR are in the same currency or there are no previous journal entries no conversion happens.
  • If SR is in foreign currency and previous journals are in base currency or multi currency feature toggle is off we convert the values to base currency using the specified exchange rate and create the SR in base currency.
  • If the payment that is being specified exceeds the amount of the invoice, an overpayment is created.
  • The overpayment can be produced also as a consequence of one of the base currency conversions described in the previous point. The invoice reference for the overpayment will be: prefix "ovr_" followed by the invoice that it is referring, i. e. ovr_SI-1029.
  • When an SR contains balancing positive and negative figures only lines for figures are created and no line for the bank account is created.

Invoice clearing:

  • If the posted SR (summed with eventual previous ones) has a value to clear an invoice all the journals that are relative to the same invoice reference will be marked as cleared.
  • When an invoice is cleared the calculation of the exchange rate variance is triggered: if the invoice is in a foreign currency and there was an exchange rate variance a special extra SR journal is created to compensate for the fluctuations in currency value.

Example

Creating a sales receipt for the sales invoice SI-876435 on order 500 (having received a payment) and sales credit SI-345 on order 3501 (having refunded a credit), both invoices belonging to customer 200. The second payment has an adjustment that will move 1 from the bank account to the specified 7804 nominal code. Returns the journal id if successful.

Request URI

/invoice/sales-receipt/

Request body

{
	"header": {
		"contactId": "200",
		"bankAccountNominalCode": "1200",
		"description": "Sales receipts Customer Company Ltd.",
		"taxDate": "2015-12-24",
		"currencyId": 2,
		"exchangeRate": 1.554307
	},
	"payments": [
		{
			"invoiceRef": "SI-876435",
			"orderId": "500",
			"value": "10.00"
		},
		{
			"invoiceRef": "SC-345",
			"orderId": "3501",
			"value": "-200.00",
			"adjustment": {
				"value": "-1.00",
				"nominalCode": "7804"
			}
		}
	]
}

Response

{
	"response": 30
}