Invoices

class Invoices extends DolibarrApi (View source)

API class for invoices

Properties

protected DoliDB $db from  DolibarrApi
Restler $r from  DolibarrApi
static string[] $FIELDS

Methods

__construct()

Constructor

string|array<string, mixed>
_checkValForAPI(string $field, string|string[] $value, object $object)

Check and convert a string depending on its type/name.

from  DolibarrApi
object
_filterObjectProperties(object $object, string $properties)

Filter properties that will be returned on object

from  DolibarrApi
object
_cleanObjectDatas(object $object)

Clean sensible object datas

static bool
_checkAccessToResource(string $resource, int $resource_id = 0, string $dbtablename = '', string $feature2 = '', string $dbt_keyfield = 'fk_soc', string $dbt_select = 'rowid')

Check access by user to a given resource

from  DolibarrApi
bool|string
_checkFilters(string $sqlfilters, string $error = '')

Return if a $sqlfilters parameter is valid Function no more used. Kept for backward compatibility with old APIs of modules

from  DolibarrApi
static string
_forge_criteria_callback(string[] $matches)

Function to forge a SQL criteria from a Generic filter string.

from  DolibarrApi
object
get(int $id, int $contact_list = 1, string $properties = '', bool $withLines = true)

Get properties of a invoice object

object
getByRef(string $ref, int $contact_list = 1)

Get properties of an invoice object by ref

object
getByRefExt(string $ref_ext, int $contact_list = 1)

Get properties of an invoice object by ref_ext

array
index(string $sortfield = "t.rowid", string $sortorder = 'ASC', int $limit = 100, int $page = 0, string $thirdparty_ids = '', string $status = '', string $sqlfilters = '', string $properties = '', bool $pagination_data = false, int $loadlinkedobjects = 0, bool $withLines = true)

List invoices

int
post(array $request_data = null)

Create invoice object

object
createInvoiceFromOrder(int $orderid)

Create an invoice using an existing order.

object
createInvoiceFromContract(int $contractid)

Create an invoice using a contract.

array
getLines(int $id)

Get lines of an invoice

object
putLine(int $id, int $lineid, array $request_data = null)

Update a line to a given invoice

array
postContact(int $id, int $contactid, string $type, string $source = 'external', int $notrigger = 0)

Add a contact type of given invoice

array<int, mixed>
getContacts(int $id, string $type = '')

Get contacts of given invoice

object
deleteContact(int $id, int $contactid, string $type)

Delete a contact type of given invoice

object
deleteLine(int $id, int $lineid)

Deletes a line of a given invoice

object|false
put(int $id, array $request_data = null)

Update invoice

array
delete(int $id)

Delete invoice

int
postLine(int $id, array $request_data = null)

Add a line to a given invoice

object
addContact(int $id, int $fk_socpeople, string $type_contact, string $source, int $notrigger = 0)

Adds a contact to an invoice

object
settodraft(int $id, int $idwarehouse = -1)

Sets an invoice as draft

object|false
validate(int $id, string $force_number = '', int $idwarehouse = 0, int $notrigger = 0)

Validate an invoice

object
settopaid(int $id, string $close_code = '', string $close_note = '')

Sets an invoice as paid

object
settounpaid(int $id)

Sets an invoice as unpaid

object
getDiscount(int $id)

Get discount from invoice

object
markAsCreditAvailable(int $id)

Create a discount (credit available) for a credit note or a deposit.

int
useDiscount(int $id, int $discountid)

Add a discount line into an invoice (as an invoice line) using an existing absolute discount

int
useCreditNote(int $id, int $discountid)

Add an available credit note discount to payments of an existing invoice.

array
getPayments(int $id)

Get list of payments of a given invoice

int
addPayment(int $id, string $datepaye, int $paymentid, string $closepaidinvoices, int $accountid, string $num_payment = '', string $comment = '', string $chqemetteur = '', string $chqbank = '')

Add payment line to a specific invoice with the remain to pay as amount.

int
addPaymentDistributed(array $arrayofamounts, string $datepaye, int $paymentid, string $closepaidinvoices, int $accountid, string $num_payment = '', string $comment = '', string $chqemetteur = '', string $chqbank = '', string $ref_ext = '', bool $accepthigherpayment = false)

Add a payment to pay partially or completely one or several invoices.

array
putPayment(int $id, string $num_payment = '')

Update a payment

object
getTemplateInvoice(int $id, int $contact_list = 1)

Get properties of a template invoice object

array
indexTemplateInvoices(string $sortfield = "t.rowid", string $sortorder = 'ASC', int $limit = 100, int $page = 0, string $thirdparty_ids = '', string $status = '', string $sqlfilters = '', string $properties = '', bool $pagination_data = false, int $loadlinkedobjects = 0, bool $withLines = true)

List template invoices

object
_cleanTemplateObjectDatas(object $object)

Clean sensible object datas

Details

at line 58
__construct()

Constructor

in DolibarrApi at line 98
protected string|array<string, mixed> _checkValForAPI(string $field, string|string[] $value, object $object)

Check and convert a string depending on its type/name.

Parameters

string $field

Field name
string|string[] $value

Value to check/clean
object $object Object

Return Value

string|array<string, mixed>

Value cleaned

in DolibarrApi at line 156
protected object _filterObjectProperties(object $object, string $properties)

Filter properties that will be returned on object

Parameters

object $object

Object to clean
string $properties

Comma separated list of properties names

Return Value

object

Object with cleaned properties

at line 1985
protected object _cleanObjectDatas(object $object)

Clean sensible object datas

Parameters

object $object

Object to clean

Return Value

object

Object with cleaned properties

in DolibarrApi at line 393
static protected bool _checkAccessToResource(string $resource, int $resource_id = 0, string $dbtablename = '', string $feature2 = '', string $dbt_keyfield = 'fk_soc', string $dbt_select = 'rowid')

Check access by user to a given resource

Parameters

string $resource

element to check
int $resource_id

Object ID if we want to check a particular record (optional) is linked to a owned thirdparty (optional).
string $dbtablename

'TableName&SharedElement' with Tablename is table where object is stored. SharedElement is an optional key to define where to check entity. Not used if objectid is null (optional)
string $feature2

Feature to check, second level of permission (optional). Can be or check with 'level1|level2'.
string $dbt_keyfield

Field name for socid foreign key if not fk_soc. Not used if objectid is null (optional)
string $dbt_select

Field name for select if not rowid. Not used if objectid is null (optional)

Return Value

bool

in DolibarrApi at line 421
protected bool|string _checkFilters(string $sqlfilters, string $error = '')

Return if a $sqlfilters parameter is valid Function no more used. Kept for backward compatibility with old APIs of modules

Parameters

string $sqlfilters

sqlfilter string
string $error

Error message

Return Value

bool|string

True if valid, False if not valid

in DolibarrApi at line 439
static protected string _forge_criteria_callback(string[] $matches)

Function to forge a SQL criteria from a Generic filter string.

Function no more used. Kept for backward compatibility with old APIs of modules

Parameters

string[] $matches

Array of found string by regex search. Each entry is 1 and only 1 criteria. Example: "t.ref:like:'SO-%'", "t.date_creation:<:'20160101'", "t.date_creation:<:'2016-01-01 12:30:00'", "t.nature:is:NULL", "t.field2:isnot:NULL"

Return Value

string

Forged criteria. Example: "t.field like 'abc%'"

at line 79
object get(int $id, int $contact_list = 1, string $properties = '', bool $withLines = true)

Get properties of a invoice object

Return an array with invoice information

Parameters

int $id

ID of invoice
int $contact_list

0:Return array contains all properties, 1:Return array contains just id, -1: Do not return contacts/adddesses
string $properties

Restrict the data returned to these properties. Ignored if empty. Comma separated list of properties names
bool $withLines

true or false to display or hide lines

Return Value

object

Object with cleaned properties

Exceptions

RestException

at line 103
object getByRef(string $ref, int $contact_list = 1)

Get properties of an invoice object by ref

Return an array with invoice information

Parameters

string $ref

Ref of object
int $contact_list

0: Returned array of contacts/addresses contains all properties, 1: Return array contains just id, -1: Do not return contacts/adddesses

Return Value

object

Object with cleaned properties

Exceptions

RestException

at line 121
object getByRefExt(string $ref_ext, int $contact_list = 1)

Get properties of an invoice object by ref_ext

Return an array with invoice information

Parameters

string $ref_ext

External reference of object
int $contact_list

0: Returned array of contacts/addresses contains all properties, 1: Return array contains just id, -1: Do not return contacts/adddesses

Return Value

object

Object with cleaned properties

Exceptions

RestException

at line 209
array index(string $sortfield = "t.rowid", string $sortorder = 'ASC', int $limit = 100, int $page = 0, string $thirdparty_ids = '', string $status = '', string $sqlfilters = '', string $properties = '', bool $pagination_data = false, int $loadlinkedobjects = 0, bool $withLines = true)

List invoices

Get a list of invoices

Parameters

string $sortfield

Sort field
string $sortorder

Sort order
int $limit

Limit for list
int $page

Page number
string $thirdparty_ids

Thirdparty ids to filter orders of (example '1' or '1,2,3') {@pattern /^[0-9,]*$/i}
string $status

Filter by invoice status : draft | unpaid | paid | cancelled
string $sqlfilters

Other criteria to filter answers separated by a comma. Syntax example "(t.ref:like:'SO-%') and (t.date_creation:<:'20160101')"
string $properties

Restrict the data returned to these properties. Ignored if empty. Comma separated list of properties names
bool $pagination_data

If this parameter is set to true the response will include pagination data. Default value is false. Page starts from 0
int $loadlinkedobjects

Load also linked object
bool $withLines

true or false to display or hide lines

Return Value

array

Array of invoice objects

Exceptions

RestException
RestException

at line 350
int post(array $request_data = null)

Create invoice object

Parameters

array $request_data

Request data

Return Value

int

ID of invoice

at line 411
object createInvoiceFromOrder(int $orderid)

Create an invoice using an existing order.

Parameters

int $orderid

Id of the order

Return Value

object

Object with cleaned properties

Exceptions

RestException
RestException
RestException
RestException
RestException

at line 455
object createInvoiceFromContract(int $contractid)

Create an invoice using a contract.

Parameters

int $contractid

Id of the contract

Return Value

object

Object with cleaned properties

Exceptions

RestException
RestException
RestException
RestException

at line 493
array getLines(int $id)

Get lines of an invoice

Parameters

int $id

Id of invoice

Return Value

array

Array of lines

at line 531
object putLine(int $id, int $lineid, array $request_data = null)

Update a line to a given invoice

Parameters

int $id

Id of invoice to update
int $lineid

Id of line to update
array $request_data

InvoiceLine data

Return Value

object

Object with cleaned properties

Exceptions

RestException
RestException
RestException

at line 606
array postContact(int $id, int $contactid, string $type, string $source = 'external', int $notrigger = 0)

Add a contact type of given invoice

Parameters

int $id

Id of invoice to update
int $contactid

Id of contact to add
string $type

Type (code in dictionary) of the contact (BILLING, SHIPPING, CUSTOMER + possibly your own)
string $source

internal=Contact intern (llx_user), external=Contact extern (llx_socpeople)
int $notrigger

0=Enable all triggers (default), 1=Disable all triggers

Return Value

array

Exceptions

RestException
RestException

at line 727
array<int, mixed> getContacts(int $id, string $type = '')

Get contacts of given invoice

Return an array with contact information

Parameters

int $id

ID of invoice
string $type

Type of the contact (BILLING, SHIPPING, CUSTOMER)

Return Value

array<int, mixed>

Array with contact and user associated

Exceptions

RestException

at line 764
object deleteContact(int $id, int $contactid, string $type)

Delete a contact type of given invoice

Parameters

int $id

Id of invoice to update
int $contactid

Row key of the contact in the array contact_ids.
string $type

Type of the contact (BILLING, SHIPPING, CUSTOMER).

Return Value

object

Object with cleaned properties

Exceptions

RestException
RestException
RestException

at line 809
object deleteLine(int $id, int $lineid)

Deletes a line of a given invoice

Parameters

int $id

Id of invoice
int $lineid

Id of the line to delete

Return Value

object

Object with cleaned properties

Exceptions

RestException
RestException
RestException
RestException

at line 847
object|false put(int $id, array $request_data = null)

Update invoice

Parameters

int $id

Id of invoice to update
array $request_data Datas

Return Value

object|false

Object with cleaned properties

at line 910
array delete(int $id)

Delete invoice

Parameters

int $id

Invoice ID

Return Value

array

at line 967
int postLine(int $id, array $request_data = null)

Add a line to a given invoice

Example of POST query : { "desc": "Desc", "subprice": "1.00000000", "qty": "1", "tva_tx": "20.000", "localtax1_tx": "0.000", "localtax2_tx": "0.000", "fk_product": "1", "remise_percent": "0", "date_start": "", "date_end": "", "fk_code_ventilation": 0, "info_bits": "0", "fk_remise_except": null, "product_type": "1", "rang": "-1", "special_code": "0", "fk_parent_line": null, "fk_fournprice": null, "pa_ht": "0.00000000", "label": "", "array_options": [], "situation_percent": "100", "fk_prev_id": null, "fk_unit": null }

Parameters

int $id

Id of invoice
array $request_data

InvoiceLine data

Return Value

int

Exceptions

RestException
RestException
RestException
RestException

at line 1054
object addContact(int $id, int $fk_socpeople, string $type_contact, string $source, int $notrigger = 0)

Adds a contact to an invoice

Parameters

int $id

Order ID
int $fk_socpeople

Id of thirdparty contact (if source = 'external') or id of user (if source = 'internal') to link
string $type_contact

Type of contact (code). Must a code found into table llx_c_type_contact. For example: BILLING
string $source

external=Contact extern (llx_socpeople), internal=Contact intern (llx_user)
int $notrigger

Disable all triggers

Return Value

object

Exceptions

RestException
RestException
RestException
RestException

at line 1102
object settodraft(int $id, int $idwarehouse = -1)

Sets an invoice as draft

Parameters

int $id

Order ID
int $idwarehouse

Warehouse ID

Return Value

object

Object with cleaned properties

Exceptions

RestException
RestException
RestException
RestException

at line 1150
object|false validate(int $id, string $force_number = '', int $idwarehouse = 0, int $notrigger = 0)

Validate an invoice

If you get a bad value for param notrigger check that ou provide this in body { "idwarehouse": 0, "notrigger": 0 }

Parameters

int $id

Invoice ID
string $force_number

force ref invoice
int $idwarehouse

Warehouse ID
int $notrigger

1=Does not execute triggers, 0= execute triggers

Return Value

object|false

Object with cleaned properties

at line 1204
object settopaid(int $id, string $close_code = '', string $close_note = '')

Sets an invoice as paid

Parameters

int $id

Order ID
string $close_code

Code filled if we classify to 'Paid completely' when payment is not complete (for escompte for example)
string $close_note

Comment defined if we classify to 'Paid' when payment is not complete (for escompte for example)

Return Value

object

Object with cleaned properties

Exceptions

RestException
RestException
RestException
RestException

at line 1254
object settounpaid(int $id)

Sets an invoice as unpaid

Parameters

int $id

Order ID

Return Value

object

Object with cleaned properties

Exceptions

RestException
RestException
RestException
RestException

at line 1298
object getDiscount(int $id)

Get discount from invoice

Parameters

int $id

Id of invoice

Return Value

object

Object with cleaned properties

at line 1341
object markAsCreditAvailable(int $id)

Create a discount (credit available) for a credit note or a deposit.

Parameters

int $id

Invoice ID

Return Value

object

Object with cleaned properties

Exceptions

RestException
RestException
RestException
RestException

at line 1537
int useDiscount(int $id, int $discountid)

Add a discount line into an invoice (as an invoice line) using an existing absolute discount

Note that this consume the discount.

Parameters

int $id

Id of invoice
int $discountid

Id of discount

Return Value

int

Exceptions

RestException
RestException
RestException
RestException

at line 1582
int useCreditNote(int $id, int $discountid)

Add an available credit note discount to payments of an existing invoice.

Note that this consume the credit note.

Parameters

int $id

Id of invoice
int $discountid

Id of a discount coming from a credit note

Return Value

int

Exceptions

RestException
RestException
RestException
RestException

at line 1628
array getPayments(int $id)

Get list of payments of a given invoice

Parameters

int $id

Id of invoice

Return Value

array

Exceptions

RestException
RestException
RestException
RestException

at line 1676
int addPayment(int $id, string $datepaye, int $paymentid, string $closepaidinvoices, int $accountid, string $num_payment = '', string $comment = '', string $chqemetteur = '', string $chqbank = '')

Add payment line to a specific invoice with the remain to pay as amount.

Parameters

int $id

Id of invoice
string $datepaye

{@from body} Payment date
int $paymentid

{@from body} Payment mode Id {@min 1}
string $closepaidinvoices

{@from body} Close paid invoices {@choice yes,no}
int $accountid

{@from body} Account Id {@min 1}
string $num_payment

{@from body} Payment number (optional)
string $comment

{@from body} Note private (optional)
string $chqemetteur

{@from body} Payment issuer (mandatory if paymentcode = 'CHQ')
string $chqbank

{@from body} Issuer bank name (optional)

Return Value

int

Payment ID

Exceptions

RestException
RestException
RestException

at line 1802
int addPaymentDistributed(array $arrayofamounts, string $datepaye, int $paymentid, string $closepaidinvoices, int $accountid, string $num_payment = '', string $comment = '', string $chqemetteur = '', string $chqbank = '', string $ref_ext = '', bool $accepthigherpayment = false)

Add a payment to pay partially or completely one or several invoices.

Warning: Take care that all invoices are owned by the same customer. Example of value for parameter arrayofamounts: {"1": {"amount": "99.99", "multicurrency_amount": ""}, "2": {"amount": "", "multicurrency_amount": "10"}}

Parameters

array $arrayofamounts

{@from body} Array with id of invoices with amount to pay for each invoice
string $datepaye

{@from body} Payment date
int $paymentid

{@from body} Payment mode Id {@min 1}
string $closepaidinvoices

{@from body} Close paid invoices {@choice yes,no}
int $accountid

{@from body} Account Id {@min 1}
string $num_payment

{@from body} Payment number (optional)
string $comment

{@from body} Note private (optional)
string $chqemetteur

{@from body} Payment issuer (mandatory if paiementcode = 'CHQ')
string $chqbank

{@from body} Issuer bank name (optional)
string $ref_ext

{@from body} External reference (optional)
bool $accepthigherpayment

{@from body} Accept higher payments that it remains to be paid (optional)

Return Value

int

Payment ID

Exceptions

RestException
RestException
RestException
RestException

at line 1942
array putPayment(int $id, string $num_payment = '')

Update a payment

Parameters

int $id

Id of payment
string $num_payment

Payment number

Return Value

array

Exceptions

RestException
RestException
RestException

at line 2038
object getTemplateInvoice(int $id, int $contact_list = 1)

Get properties of a template invoice object

Return an array with invoice information

Parameters

int $id

ID of template invoice
int $contact_list

0:Return array contains all properties, 1:Return array contains just id, -1: Do not return contacts/adddesses

Return Value

object

Object with cleaned properties

Exceptions

RestException

at line 2069
array indexTemplateInvoices(string $sortfield = "t.rowid", string $sortorder = 'ASC', int $limit = 100, int $page = 0, string $thirdparty_ids = '', string $status = '', string $sqlfilters = '', string $properties = '', bool $pagination_data = false, int $loadlinkedobjects = 0, bool $withLines = true)

List template invoices

Get a list of template invoices

Parameters

string $sortfield

Sort field
string $sortorder

Sort order
int $limit

Limit for list
int $page

Page number
string $thirdparty_ids

Thirdparty ids to filter orders of (example '1' or '1,2,3') {@pattern /^[0-9,]*$/i}
string $status

Filter by template status: draft | active | suspended
string $sqlfilters

Other criteria to filter answers separated by a comma. Syntax example "(t.ref:like:'SO-%') and (t.date_creation:<:'20160101')"
string $properties

Restrict the data returned to these properties. Ignored if empty. Comma separated list of properties names
bool $pagination_data

If this parameter is set to true the response will include pagination data. Default value is false. Page starts from 0
int $loadlinkedobjects

Load also linked object
bool $withLines

true or false to display or hide lines

Return Value

array

Array of recurring invoice objects

Exceptions

RestException
RestException

at line 2231
protected object _cleanTemplateObjectDatas(object $object)

Clean sensible object datas

Parameters

object $object

Object to clean

Return Value

object

Object with cleaned properties