Invoices

Get invoices list

GET /invoices/invoices[/status/#{status}][/start_date/#{start_date}][/end_date/#{end_date}][/clients/#{clients}][/tags/#{tags}][/number/#{number}][/amount_paid_operator/#{amount_paid_operator}][/amount_paid/#{amount_paid}][/amount_total_operator/#{amount_total_operator}][/amount_total/#{amount_total}][/amount_due_operator/#{amount_due_operator}][/amount_due/#{amount_due}][/currency/#{currency}][/user/#{user_id}]

URI arguments

                                                                                                                                                           

Argument	Type	Required	Valeur/Description
status	string		One or more statuses to filter. You can pass several statuses at the same time by using “:” as a separator. For example: /status/draft:sent:unpaid See the possible values ​​of status.
start_date	date		If the argument is not specified, the default is the first day of the current month.
end_date	date		If the argument is not specified, the default is the last day of the current month.
clients	string		One or more clients to filter. You can pass several clients at the same time by using “:” as a separator. For example: /clients/Client%20Name:Another%20Client%20Name
tags	string		One or more tags to filter.  You can pass several tags at the same time by using “:” as a separator. For example: /tags/Tag 1:Tag 2
number	string		All or part of an invoice number to filter (equivalent to the MySQL function “LIKE ‘#{number}%’”.
amount_paid_operator	string		See the possible values ​​of operator.
amount_paid	double		An amount paid.
amount_total_operator	string		See the possible values ​​of operator.
amount_total	double		A total amount.
amount_due_operator	string		See the possible values ​​of operator.
amount_due	double		An amount due.
currency	string		See the possible values ​​of currency.
user	integer		The #{user_id} of the user to filter the results by.

cURL request example

curl -u #:#{password}'\
-H 'User-Agent: #{user_agent}'\
-X GET https://#{subdomain}.iscriba.com/api/invoices/invoices/status/draft:sent/currency/EUR

XML response example

HTTP Status: 200 OK

<?xml version="1.0" encoding="utf-8"?>
<xml>
	<invoices>
		<invoice>
			<invoice_id>1</invoice_id>
			<company_name>Company Name</company_name>
			<client_id>3</client_id>
			<invoice_number>F10100001</invoice_number>
			<date_invoice>2010-11-04</date_invoice>
			<due_date>2010-11-31</due_date>
			<total>1120</total><!-- Total VAT Excluded -->
			<grand_total>1212.62</grand_total><!-- Total VAT Included -->
			<currency>EUR</currency>
			<status>draft</status>
			<amount_paid>0</amount_paid>
			<amount_due>1212.62</amount_due>
		</invoice>
		<invoice>
		...
		</invoice>
	</invoices>
</xml>

Top

---

Get an invoice

GET /invoices/invoice/id/#{invoice_id}

URI arguments

Argument	Type	Required	Value
id	integer	yes	Le #{invoice_id} de la facture que vous souhaitez obtenir.

cURL request example

curl -u #:#{password}'\
-H 'User-Agent: #{user_agent}'\
-X GET https://#{subdomain}.iscriba.com/api/invoices/invoice/id/29

XML response example

HTTP Status: 200 OK

<?xml version="1.0" encoding="utf-8"?>
<xml>
	<invoice>
		<invoice_id>29</invoice_id>
		<user_id>1</user_id>
		<company_id>1</company_id>
		<company_name>Company Name</company_name>
		<summary></summary>
		<client_id>2</client_id>
		<client_name>Client Name</client_name>
		<client_language>french</client_language>
		<client_tax_id>FR12123123123</client_tax_id>
		<invoice_number>F10100002</invoice_number>
		<related_invoice_number></related_invoice_number>
		<related_invoice_id>0</related_invoice_id>
		<purchaseorder_number></purchaseorder_number>
		<related_purchaseorder_id>0</related_purchaseorder_id>
		<date_creation>2010-11-04 13:08:57</date_creation>
		<date_invoice>2010-11-04</date_invoice>
		<total>1120</total><!-- Total VAT Excluded -->
		<global_discount_total>0</global_discount_total>
		<global_discount_percentage>0</global_discount_percentage>
		<sub_total>1120</sub_total><!-- Subtotal VAT Excluded -->
		<tax_total>49.5</tax_total>
		<alt_tax_total>43.12</alt_tax_total>
		<tax_name>TVA</tax_name>
		<tax_percentage>5.5</tax_percentage>
		<alt_tax_name>TVA</alt_tax_name>
		<alt_tax_percentage>19.6</alt_tax_percentage>
		<use_tax_inclusive>0</use_tax_inclusive>
		<taxation_mode>simple</taxation_mode>
		<grand_total>1212.62</grand_total><!-- Total VAT Included -->
		<currency>EUR</currency>
		<terms>0</terms>
		<custom_terms></custom_terms>
		<due_date>2010-11-04</due_date>
		<payment>VIR</payment>
		<payment_specified></payment_specified>
		<late_fee>0</late_fee>
		<late_fee_specified>0</late_fee_specified>
		<billing_address>
			<name>Client Name</name>
			<address1></address1>
			<address2></address2>
			<address3></address3>
			<address4></address4>
			<city></city>
			<state></state>
			<postalcode></postalcode>
			<country></country>
		</billing_address>
		<notes></notes>
		<status>draft</status>
		<type>standard</type>
		<refunds_total>0</refunds_total>
		<payments_total>0</payments_total>
		<lines>
			<line>
				<item_id>0</item_id>
				<line_id>44</line_id>
				<line_number>1</line_number>
				<kind>1</kind>
				<qty>1</qty>
				<description>Lorem ipsum dolor sit amet</description>
				<tax_percentage>5.5</tax_percentage>
				<alt_tax_percentage>0</alt_tax_percentage>
				<unit_price>900</unit_price>
				<reduction_percentage>0</reduction_percentage>
			</line>
			<line>
			...
			</line>
		</lines>		
	</invoice>
</xml>

Top

---

Get an invoice in PDF

GET /invoices/invoice/id/#{invoice_id}/format/pdf

URI arguments

Argument	Type	Required	Value
id	integer	yes	The #{invoice_id} of the invoice you wish to get.

cURL request example

curl -u #:#{password}'\
-H 'User-Agent: #{user_agent}'\
-X GET https://#{subdomain}.iscriba.com/api/invoices/invoice/id/29/format/pdf

XML response example

HTTP Status: 200 OK

Content-Type: application/pdf

%PDF-1.4

...

%%EOF

Top

---

Create an invoice

POST /invoices/invoice

Request fields

Field	Type	Required	Description
date	date	yes	Date of the invoice. Can’t be prior to the date of the last invoice created.
client_id	integer	yes	The #{client_id} of the company for which you are creating the invoice.
summary	string		A summary of the invoice (for internal usage).
currency	string		Currency of the invoice. The default is the one from your account settings. See the possible values ​​of currency.
address	array		This field is used to customize the billing address. If you do not pass it, the default address of the client is used.
address[address1]	string		Address Line 1.
address[address2]	string		Address Line 2.
address[address3]	string		Address Line 3.
address[address4]	string		Address Line 4.
address[city]	string		City.
address[state]	string		Region/State.
address[postalcode]	string		Postal code.
purchaseorder_number	string		A purchase order number related to the invoice.
tax_name	string		Name of the tax. The default value is the one from your account settings.
tax_percentage	double		Tax percentage. The default value is the one from your account settings.
alt_tax_name	string		Alternative tax name. The default value is the one from your account settings.
alt_tax_percentage	double		Alternative tax percentage. The default value is the one from your account settings.
use_tax_inclusive	boolean		Define if the unit price of the items include tax. The default value is the one from your account settings.
taxation_mode	string		The default value is the one from your account settings. Must be “compound” to use compound tax calculation.
global_discount_percentage	double		Global discount percentage. Default value is 0.
terms	string		Terms of payment settlement. The default value is the one from your account settings. See the possible values ​​of terms.
payment	string		Payment method. The default value is the one from your account settings. See the possible values ​​of payment.
late_fee	double		Late fee percentage. The default value is the one from your account settings. See the possible values ​​of late_fee.
lines	array	yes (at least one line)	Invoice lines.
lines[#{key}][item_id]	integer		The #{item_id} of the inventory item associated with the line. If provided, description and unit_price fields are not required.
lines[#{key}][kind]	integer		Line kind. Default value is “1” for “Service”. See the possible values ​​of kind.
lines[#{key}][qty]	double		Item quantity. Equals 1 by default.
lines[#{key}][description]	string	yes	Item description.
lines[#{key}][tax]	boolean		Apply tax. Equals FALSE if not provided.
lines[#{key}][alt_tax]	boolean		Apply alternative tax. Equals FALSE if not provided.
lines[#{key}][unit_price]	double	yes	Item price.
lines[#{key}][reduction_percentage]	double		Reduction percentage for the line.
notes	string		Notes that you may want to add to the invoice. This field does not appear on the document if you leave it blank.

cURL request example

curl -u #:#{password}'\
-H 'User-Agent: #{user_agent}'\
-d "date=2010-11-08&client_id=14&currency=EUR&address[address1]=Ligne d'adresse 1&address[address2]=Ligne d'addresse 2&address[city]=Ville&address[postalcode]=01234&purchaseorder_number=C20101001-001&tax_name=TVA&tax_percentage=19.6&alt_tax_name=TVA&alt_tax_percentage=5.5&taxation_mode=simple&global_discount_percentage=0&terms=30END&payment=VIR&late_fee=0&lines[0][description]=Ligne de facture 1&lines[0][unit_price]=10&lines[0][qty]=1&lines[1][description]=Ligne de facture 2&lines[1][unit_price]=20&lines[1][qty]=2&notes=Notes de la facture"\
https://#{subdomain}.iscriba.com/api/invoices/invoice

XML response example

HTTP Status: 201 Created

<?xml version="1.0" encoding="utf-8"?>
<xml>
	<invoice_id>1</invoice_id>
</xml>	

Top

---

Modify an invoice

PUT /invoices/invoice/id/#{invoice_id}

URI arguments

Argument	Type	Required	Value
id	integer	yes	The #{invoice_id} of the invoice you wish to modify.

Request fields

Same as create an invoice except no field is required. All fields not included in the request remain unchanged. Date and client_id field are not taken into account.

Warning: for fields of type array, you must provide the full array if you want to add, edit or delete an array element.

cURL request example

curl -u #:#{password}'\
-H 'User-Agent: #{user_agent}'\
-X PUT\
-d "address[address1]=Ligne d'adresse 1&address[address2]=Ligne d'addresse 2&address[city]=Ville&address[postalcode]=01234"\
https://#{subdomain}.iscriba.com/api/invoices/invoice/id/1

XML response example

HTTP Response: 200 OK

<?xml version="1.0" encoding="utf-8"?>
<xml>
	<invoice_id>1</invoice_id>
</xml>	

Top

---

Modify the status of an invoice

PUT /invoices/invoice_status/id/#{invoice_id}

URI arguments

Argument	Type	Required	Value
id	integer	yes	The #{invoice_id} of the invoice for which you wish to modify the status.

Request fields

Field	Type	Required	Description
status	string	yes	See the possible values ​​of status.

cURL request example

curl -u #:#{password}'\
-H 'User-Agent: #{user_agent}'\
-X PUT\
-d "status=sent"\
https://#{subdomain}.iscriba.com/api/invoices/invoice_status/id/1

XML response example

HTTP Response: 200 OK

<?xml version="1.0" encoding="utf-8"?>
<xml>
	<invoice>
		<id>1</id>
		<status>sent</status>
	</invoice>
</xml>	

Top

---

Delete an invoice

DELETE /invoices/invoice/id/#{invoice_id}

URI arguments

Argument	Type	Required	Value
id	integer	yes	The #{invoice_id} of the invoice you wish to delete.

cURL request example

curl -u #:#{password}'\
-H 'User-Agent: #{user_agent}'\
-X DELETE https://#{subdomain}.iscriba.com/api/invoices/invoice/id/1

XML response example

HTTP Response: 200 OK

<?xml version="1.0" encoding="utf-8"?>
<xml>
	<invoice_id>1</invoice_id>
</xml>	

Top

---

Get comments related to an invoice

GET /invoices/invoice_related_comments/id/#{invoice_id}

URI arguments

Argument	Type	Required	Value
id	integer	yes	The #{invoice_id} of the invoice for which you wish to get the related comments.

cURL request example

curl -u #:#{password}'\
-H 'User-Agent: #{user_agent}'\
-X GET https://#{subdomain}.iscriba.com/api/invoices/invoice_related_comments/id/19

XML response example

HTTP Status: 200 OK

<?xml version="1.0" encoding="utf-8"?>
<xml>
	<invoice_related_comments>
		<invoice_related_comment>
			<comment_id>11</comment_id>
			<invoice_id>33</invoice_id>
			<user_id>1</user_id>
			<firstname>John</firstname>
			<lastname>Doe</lastname>
			<title></title>
			<subtitle></subtitle>
			<content>Lorem ipsum dolor sit amet.</content>
			<date>2010-12-23</date>
			<type>post</type>
			<is_public>0</is_public>
		</invoice_related_comment>
		<invoice_related_comment>
		...
		</invoice_related_comment>
	</invoice_related_comments>
</xml>

Top

---

Create a comment related to an invoice

POST /invoices/invoice_related_comment

Request fields

Champ	Type	Required	Description
invoice_id	integer	yes	The #{invoice_id} of the invoice to which the comment will be related.
content	string	yes	The content of the comment (only raw text allowed).
is_public	boolean		Define if the comment is visible to the client. The default value is TRUE (comment is public).

cURL request example

curl -u #:#{password}'\
-H 'User-Agent: #{user_agent}'\
-d "invoice_id=10&content=Lorem ipsum dolor sit amet.&is_public=0"\
https://#{subdomain}.iscriba.com/api/invoices/invoice_related_comment

XML response example

HTTP Status: 201 Created

<?xml version="1.0" encoding="utf-8"?>
<xml>
	<comment_id>1</comment_id>
</xml>	

Top

---

Delete a comment related to an invoice

DELETE /invoices/invoice_related_comment/id/#{comment_id}

URI arguments

Argument	Type	Required	Value
id	integer	yes	The #{comment_id} of the comment you wish to delete.

cURL request example

curl -u #:#{password}'\
-H 'User-Agent: #{user_agent}'\
-X DELETE https://#{subdomain}.iscriba.com/api/invoices/invoice_related_comment/id/1

XML response example

HTTP Response: 200 OK

<?xml version="1.0" encoding="utf-8"?>
<xml>
	<comment_id>1</comment_id>
</xml>	

Top

---

Get documents related to an invoice

GET /invoices/invoice_related_documents/id/#{invoice_id}

URI arguments

Argument	Type	Required	Value
id	integer	yes	The #{invoice_id} of the invoice for which you wish to get related documents.

cURL request example

curl -u #:#{password}'\
-H 'User-Agent: #{user_agent}'\
-X GET https://#{subdomain}.iscriba.com/api/invoices/invoice_related_documents/id/19

XML response example

HTTP Status: 200 OK

<?xml version="1.0" encoding="utf-8"?>
<xml>
	<invoice_related_documents>
		<invoice_related_document>
			<id>27</id>
			<number>F10110014</number>
			<date_creation>2010-11-23 00:46:19</date_creation>
			<date>2010-11-22</date>
			<total>100</total><!-- Total VAT Included -->
			<currency>EUR</currency>
			<type>refund</type><!-- is filled only in the case of invoices to distinguish refund invoices ("refund") form standard invoices ("standard") -->
			<kind>invoice</kind>
			<status>draft</status>
		</invoice_related_document>
		<invoice_related_document>
		...
		</invoice_related_document>
	</invoice_related_documents>
</xml>

Top

---

Get tags related to an invoice

GET /invoices/invoice_related_tags/id/#{invoice_id}

URI arguments

Argument	Type	Required	Value
id	integer	yes	The #{invoice_id} of the invoice for which you wish to get the related tags.

cURL request example

curl -u #:#{password}'\
-H 'User-Agent: #{user_agent}'\
-X GET https://#{subdomain}.iscriba.com/api/invoices/invoice_related_tags/id/19

XML response example

HTTP Status: 200 OK

<?xml version="1.0" encoding="utf-8"?>
<xml>
	<invoice_related_tags>
		<invoice_related_tag>
			<tag_id>5</tag_id>
			<tag_name>lorem</tag_name>
		</invoice_related_tag>
		<invoice_related_tag>
		...
		</invoice_related_tag>
	</invoice_related_tags>
</xml>

Top

---

Create a tag related to an invoice

POST /invoices/invoice_related_tag

Request fields

Field	Type	Required	Description
invoice_id	integer	yes	The #{invoice_id} of the invoice the tag will be related to.
tag	string	yes	Tag name.

cURL request example

curl -u #:#{password}'\
-H 'User-Agent: #{user_agent}'\
-d "invoice_id=10&tag=Votre-tag"\
https://#{subdomain}.iscriba.com/api/invoices/invoice_related_tag

XML response example

HTTP Status: 201 Created

<?xml version="1.0" encoding="utf-8"?>
<xml>
	<tag_id>1</tag_id>
</xml>	

Top

---

Delete a tag related to an invoice

DELETE /invoices/invoice_related_tag/invoice_id/#{invoice_id}/tag_id/#{tag_id}

URI arguments

Argument	Type	Required	Value
invoice_id	integer	yes	The #{invoice_id} of the invoice the tag is related to.
tag_id	integer	yes	The #{tag_id} of the tag related to the invoice.

cURL request example

curl -u #:#{password}'\
-H 'User-Agent: #{user_agent}'\
-X DELETE https://#{subdomain}.iscriba.com/api/invoices/invoice_related_tag/invoice_id/1/tag_id/1

XML response example

HTTP Response: 200 OK

<?xml version="1.0" encoding="utf-8"?>
<xml>
	<tag_id>1</tag_id>
</xml>	

Top

---

Create a refund invoice

POST /invoices/refund

Request fields

Field	Type	Required	Description
invoice_id	integer	yes	The #{invoice_id} of the invoice on which you want to do a refund.
refund_lines	array	yes (at least one line)	Original invoice lines on which you are doing a refund.
refund_lines[#{key}][line_id]	integer	yes	The #{line_id} of the original invoice line on which your a doing a refund.
refund_lines[#{key}][unit_price]	double		The #{unit_price} of the amount on which you want to perform a refund against the original invoice line. If it is not provided, the total amount of the original line is used.

cURL request example

curl -u #:#{password}'\
-H 'User-Agent: #{user_agent}'\
-d "invoice_id=1&refund_lines[0][line_id]=2&refund_lines[1][line_id]=4"\
https://#{subdomain}.iscriba.com/api/invoices/refund

XML response example

HTTP Status: 201 Created

<?xml version="1.0" encoding="utf-8"?>
<xml>
	<invoice_id>1</invoice_id>
</xml>	

Top

---

Delete a payment related to an invoice

DELETE /invoices/invoice_related_payment/invoice_id/#{invoice_id}/payment_id/#{payment_id}

URI arguments

Argument	Type	Required	Description
invoice_id	integer	yes	The #{invoice_id} of the invoice for which the payment is related.
payment_id	integer	yes	The #{payment_id} of the payment related to the invoice.

cURL request example

curl -u #:#{password}'\
-H 'User-Agent: #{user_agent}'\
-X DELETE\ 
https://#{subdomain}.iscriba.com/api/invoices/invoice_payment/invoice_id/10/payment_id/15

XML response example

HTTP Response: 200 OK

<?xml version="1.0" encoding="utf-8"?>
<xml>
	<payment_id>15</payment_id>
</xml>	

Top

---