Invoices
========
Current version: 1.4.0
Create
------
.. http:post:: /api2/facturen
Create a new invoice for a booking
**Example request**:
.. sourcecode:: http
POST /api2/facturen HTTP/1.1
Host: demo.recras.nl
Accept: application/json
{
"boeking_id": 42,
"context": "invoice",
"status": "definitief",
"voorschot_percentage": 100,
"mail_to": 5,
"mail_cc": [6, 7],
"mail_subject": "Invoice for your booking",
"mail_body": "Dear {contactpersoon_voornaam},
\nPlease find the invoice for booking {uitje_nummer} attached to this email. The total amount of the invoice is {factuur_bedrag}, the amount still due is {factuur_resterend_bedrag}.",
"mail_signature": "Kind regards, {gebruiker_voornaam}",
"reference_external": "V0;0099-T099;Kassenbeleg-V1;"
}
**Example response**:
.. sourcecode:: http
HTTP/1.1 201 Created
Content-Type: application/json
Location: /api2/facturen/5
{
"id": 5,
"klant_id": 13,
"context": "invoice",
"status": "concept",
"factuur_nummer": null,
"verstuur_factuur_op": "2016-05-03",
"datum": null,
"pdf_locatie": null,
"opmerking": null,
"aantal_personen": 1,
"betaaltermijn": 14,
"referentie_klant": null,
"reference_external": "V0;0099-T099;Kassenbeleg-V1;",
"herinnering1": null,
"herinnering2": null,
"calculated_totaalbedrag_inclusief_btw": 55,
"mollie_transaction_id": null,
"crediteert_factuur_id": null,
"bedrijf_id": 1,
"btw_verlegd": false,
"boeking_id": 42
}
:json int boeking_id: **Required** id of the booking
:json string context: **Optional**, *default* ``invoice``. The desired context of the invoice, possible values are ``invoice`` (for regular invoices), ``online_booking`` (for invoices created during online booking), or ``pos`` (for invoices created in the Recras POS)
:json string status: **Optional**, *default* ``concept``. The desired status of the invoice, possible values are ``concept`` (draft invoice), or ``definitief`` (permanent invoice).
:json float voorschot_percentage: **Optional**, default ``100``. The percentage of the booking that should be invoices with this invoice. This can be any number between 0 and 100.
:json int mail_to: **Optional**, only available with *status* =``definitief``, this number must reference a valid ``id`` of a contact person (with a valid email address) associated with this invoice. Adding this value will cause the invoice to be sent by email to the contact person.
:json int[] mail_cc: **Optional**, only available with *status* =``definitief`` **and** *mail_to* set. The values must reference an ``id`` of a contact person (with a valid email address) associated with the invoice.
:json string mail_subject: **Optional**, *default: subject set in company settings*, only available with *mail_to* set. You can use *booking*, *package*, *invoice*, *contact*, *contact person*, and *company* tags.
:json string mail_body: **Optional**, *default: body set in company settings*, only available with *mail_to* set. You can use *booking*, *package*, *invoice*, *contact*, *contact person*, and *company* tags.
:json string mail_signature: **Optional**, *default: staff signature, or company signature*, only available with *mail_to* set. You can use *booking*, *package*, *invoice*, *contact*, *contact person*, and *company* tags.
:json string reference_external: **Optional** An external reference, for example a reference to a government database (KassenSichV)
:resheader Location: The location of the newly created invoice resource
:statuscode 201: Invoice successfully created
:statuscode 406: Error in the input
:statuscode 403: Authenticated user lacks the ``createFactuur`` permission
**Errors**
``ERR_BOOKING_FULLY_INVOICED``
The net booking price is already completely invoiced. It's not allowed to create new invoices if the booking is fully invoiced.
Update
------
Draft invoices (*status* = ``concept``) can be made permanent with the ``markeeralsverzonden`` endpoint. Permanent invoices cannot be edited or deleted, but can change *status* with changes to their payments.
.. http:post:: /api2/facturen/(int:id)/markeeralsverzonden
**Example request**:
.. sourcecode:: http
POST /api2/facturen/4/markeeralsverzonden HTTP/1.1
Host: demo.recras.nl
Content-Type: application/json
{
"mail_to": 5,
"mail_cc": [6, 7],
"mail_subject": "Invoice for your booking",
"mail_body": "Dear {contactpersoon_voornaam},
\nPlease find the invoice for booking {uitje_nummer} attached to this email. The total amount of the invoice is {factuur_bedrag}, the amount still due is {factuur_resterend_bedrag}.",
"mail_signature": "Kind regards, {gebruiker_voornaam}"
"reference_external": "V0;0099-T099;Kassenbeleg-V1;",
"betalingen": [
{
"bedrag": 25.00,
"betaalmethode_id": 3,
"pos_id": 2,
"location_id": 4
}
]
}
**Example response**:
HTTP/1.1 200 OK
Content-Length: 0
:json int mail_to: **Optional**. Please see the explanation for this field in the section on creating invoices.
:json int[] mail_cc: **Optional**, only available with *mail_to* set. Please see the explanation for this field in the section on creating invoices.
:json string mail_subject: **Optional**, only available with *mail_to* set. Please see the explanation for this field in the section on creating invoices.
:json string mail_body: **Optional**, only available with *mail_to* set. Please see the explanation for this field in the section on creating invoices.
:json string mail_signature: **Optional**, only available with *mail_to* set. Please see the explanation for this field in the section on creating invoices.
:json string reference_external: **Optional** Please see the explanation for this field in the section on creating invoices.
:json payment[] betalingen: **Optional** A list of payments to process on marking the invoice as permanent.
:json float betalingen.bedrag: **Required** The value of the payment
:json int betalingen.betaalmethode_id: **Optional** A reference to a payment method.
:json int betalingen.pos_id: **Optional** A reference to a Recras point-of-sale
:json int betalingen.locatie_id: **Optional** A reference to a location. The referenced point-of-sale must be available at this location.
:resheader Location: The location of the newly created invoice resource
:statuscode 201: Invoice successfully created
:statuscode 406: Error in the input
:statuscode 403: Authenticated user lacks the ``createFactuur`` permission
Delete
------
Only draft invoices (*status* = ``concept``) can be deleted.
.. http:delete:: /api2/facturen/(int:id)
**Example request**:
.. sourcecode:: http
DELETE /api2/facturen/2 HTTP/1.1
Host: demo.recras.nl
**Example response**:
HTTP/1.1 200 OK
Content-Length: 0
:statuscode 200: Invoice deleted
:statuscode 403: Invoice does not have *status* ``concept``
Read
----
.. http:get:: /api2/facturen
**Voorbeeld request**:
.. sourcecode:: http
GET /api2/facturen HTTP/1.1
Host: demo.recras.nl
Accept: application/json
**Voorbeeld response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"id": 1,
"klant_id": 8,
"status": "verzonden",
"factuur_nummer": "1-4-8",
"verstuur_factuur_op": "2016-05-03",
"datum": "2016-05-03",
"pdf_locatie": "factuur_1-4-8_2016-05-03.pdf",
"opmerking": "",
"aantal_personen": 14,
"betaaltermijn": 14,
"referentie_klant": "",
"reference_external": "V0;0099-T099;Kassenbeleg-V1;",
"herinnering1": null,
"herinnering2": null,
"calculated_totaalbedrag_inclusief_btw": 19.75,
"mollie_transaction_id": null,
"crediteert_factuur_id": null,
"bedrijf_id": 1,
"btw_verlegd": false,
"boeking_id": 3,
"pdf_href": "https://demo.recras.nl/api2.php/facturen/1.pdf"
},
{
"id": 2,
"klant_id": 5,
"status": "betaald",
"factuur_nummer": "1-5-5",
"verstuur_factuur_op": "2016-05-03",
"datum": "2016-05-03",
"pdf_locatie": "factuur_1-5-5_2016-05-03.pdf",
"opmerking": "",
"aantal_personen": 23,
"betaaltermijn": -3,
"referentie_klant": "",
"reference_external": "",
"herinnering1": null,
"herinnering2": null,
"calculated_totaalbedrag_inclusief_btw": 1824.75,
"mollie_transaction_id": 0,
"crediteert_factuur_id": null,
"bedrijf_id": 1,
"btw_verlegd": false,
"boeking_id": 5,
"pdf_href": "https://demo.recras.nl/api2.php/facturen/2.pdf"
},
]
:query int boeking_id: filter by booking id, multiple values are possible with a comma-separated list
:query status: filter by invoice status, multiple values are allowed with a comma-separated list. Possible values are ``concept`` (drafts), ``betaald`` (fully paid invoices), ``deels_betaald`` (partially paid invoices), ``verzonden`` (invoices that are not paid)
:query context: filter by invoice context, multiple values are allowed with a comma-separated list. Possible values are ``invoice``, ``online_booking``, ``pos``. For more information on invoice contexts, please consult [the Recras end-user documentation on invoice contexts](/v2/docs/costs_and_invoices#invoice-contexts)
:query embed: Embed linked resources, you can request 0 or more, comma-separated, you can find a list of possible values below.
:query ISO8601-date datum: Show only invoices dated on the given date.
:query ISO8601-date datumVoor: Show only invoices dated on or before the given date.
:query ISO8601-date datumNa: Show only invoices dated on or after the given date.
:query ISO8601-date verstuur_factuur_op: Show only invoices to be sent on the given date, relevant with ``?status=concept``.
:query ISO8601-date verstuur_factuur_op<: Show only invoices to be sent on or before the given date, relevant with ``?status=concept``.
:query ISO8601-date verstuur_factuur_op>: Show only invoices to be sent on or after the given date, relevant with ``?status=concept``.
:query sort_order: The order in which to sort the results, possible values are ``asc`` (for ascending order), ``desc`` (for descending order). The results are sorted by: ``datum`` (invoice date), ``factuur_nummer`` (invoice reference), ``verstuur_factuur_op`` (date on which the invoice should be sent, relevant only for draft invoices), ``id``
:query int page_size: number of results to include; the default is to return all results at once. API consumers are advised not to rely on the API response containing all results and should fetch no more than 1000 results at a time and limit the request frequency sensibly.
:query int page: page number, counting from 1
:reqheader Authorization: mandatory Basic authentication
:statuscode 200: no error
**Possible values for embed-parameter**
* ``Klant`` (customer)
* ``Betalingen`` (payments)
* ``regels`` (invoice lines)
* ``Boeking`` (booking)
* ``Creditfactuur`` (invoice that credits this invoice)
* ``GecrediteerdeFactuur`` (invoice that the current resource credits)
* ``_calculated.gestructureerde_mededeling`` (a prepared "Gestructureerde Mededeling" payment reference)
.. http:get:: /api2/facturen/(int:id)
Een specifieke factuur
**Voorbeeld request**:
.. sourcecode:: http
GET /api2/facturen/4 HTTP/1.1
Host: demo.recras.nl
Accept: application/json
**Voorbeeld response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 4,
"klant_id": 8,
"status": "verzonden",
"factuur_nummer": "1-4-8",
"verstuur_factuur_op": "2016-05-03",
"datum": "2016-05-03",
"pdf_locatie": "factuur_1-4-8_2016-05-03.pdf",
"opmerking": "",
"aantal_personen": 14,
"betaaltermijn": 14,
"referentie_klant": "",
"reference_external": "",
"herinnering1": null,
"herinnering2": null,
"calculated_totaalbedrag_inclusief_btw": 19.75,
"mollie_transaction_id": null,
"crediteert_factuur_id": null,
"bedrijf_id": 1,
"btw_verlegd": false,
"boeking_id": 3,
"pdf_href": "https://demo.recras.nl/api2.php/facturen/4.pdf",
"regels": [
{
"id": 226,
"naam": "",
"type": "groep",
"kortingspercentage": 0,
"kortingomschrijving": "",
"voorschot_factuur_id": null,
"children_visible": false,
"regels": [
{
"id": 227,
"naam": "Passant - Klimbos",
"type": "groep",
"kortingspercentage": 0,
"kortingomschrijving": "",
"voorschot_factuur_id": null,
"children_visible": false,
}
]
}
],
}
:statuscode 200: OK
:statuscode 404: No invoice with this ``id``
Changelog
---------
1.1.0 - Added ``ERR_BOOKING_FULLY_INVOICED`` error definition
1.2.0 - Added ``?embed=_calculated.gestructureerde_mededeling`` parameter for GET requests
1.3.0 - Added ``reference_external`` field
1.4.0 - Added deleting of concept invoices