Invoices¶

Current version: 1.4.0

Create¶

POST /api2/facturen¶

Create a new invoice for a booking

Example request:

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},<br><br>\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:

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 Parameters:

boeking_id (int) – Required id of the booking
context (string) – 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)
status (string) – Optional, default concept. The desired status of the invoice, possible values are concept (draft invoice), or definitief (permanent invoice).
voorschot_percentage (float) – Optional, default 100. The percentage of the booking that should be invoices with this invoice. This can be any number between 0 and 100.
mail_to (int) – 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.
mail_cc (int[]) – 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.
mail_subject (string) – 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.
mail_body (string) – 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.
mail_signature (string) – 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.
reference_external (string) – Optional An external reference, for example a reference to a government database (KassenSichV)

Response Headers:

Location – The location of the newly created invoice resource

Status Codes:

201 Created – Invoice successfully created
406 Not Acceptable – Error in the input
403 Forbidden – 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.

POST /api2/facturen/(int: id)/markeeralsverzonden¶

Example request:

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},<br><br>\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 Parameters:

mail_to (int) – Optional. Please see the explanation for this field in the section on creating invoices.
mail_cc (int[]) – Optional, only available with mail_to set. Please see the explanation for this field in the section on creating invoices.
mail_subject (string) – Optional, only available with mail_to set. Please see the explanation for this field in the section on creating invoices.
mail_body (string) – Optional, only available with mail_to set. Please see the explanation for this field in the section on creating invoices.
mail_signature (string) – Optional, only available with mail_to set. Please see the explanation for this field in the section on creating invoices.
reference_external (string) – Optional Please see the explanation for this field in the section on creating invoices.
betalingen (payment[]) – Optional A list of payments to process on marking the invoice as permanent.
betalingen.bedrag (float) – Required The value of the payment
betalingen.betaalmethode_id (int) – Optional A reference to a payment method.
betalingen.pos_id (int) – Optional A reference to a Recras point-of-sale
betalingen.locatie_id (int) – Optional A reference to a location. The referenced point-of-sale must be available at this location.

Response Headers:

Location – The location of the newly created invoice resource

Status Codes:

201 Created – Invoice successfully created
406 Not Acceptable – Error in the input
403 Forbidden – Authenticated user lacks the createFactuur permission

Delete¶

Only draft invoices (status = concept) can be deleted.

DELETE /api2/facturen/(int: id)¶

Example request:

DELETE /api2/facturen/2 HTTP/1.1
Host: demo.recras.nl

Example response:

HTTP/1.1 200 OK Content-Length: 0

Status Codes:

200 OK – Invoice deleted
403 Forbidden – Invoice does not have status concept

Read¶

GET /api2/facturen¶

Voorbeeld request:

GET /api2/facturen HTTP/1.1
Host: demo.recras.nl
Accept: application/json

Voorbeeld response:

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/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/facturen/2.pdf"
  },
]

Query Parameters:

boeking_id (int) – filter by booking id, multiple values are possible with a comma-separated list
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)
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)
embed – Embed linked resources, you can request 0 or more, comma-separated, you can find a list of possible values below.
datum (ISO8601-date) – Show only invoices dated on the given date.
datumVoor (ISO8601-date) – Show only invoices dated on or before the given date.
datumNa (ISO8601-date) – Show only invoices dated on or after the given date.
verstuur_factuur_op (ISO8601-date) – Show only invoices to be sent on the given date, relevant with ?status=concept.
verstuur_factuur_op< (ISO8601-date) – Show only invoices to be sent on or before the given date, relevant with ?status=concept.
verstuur_factuur_op> (ISO8601-date) – Show only invoices to be sent on or after the given date, relevant with ?status=concept.
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
page_size (int) – 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.
page (int) – page number, counting from 1

Request Headers:

Authorization – mandatory Basic authentication

Status Codes:

200 OK – 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)

GET /api2/facturen/(int: id)¶

Een specifieke factuur

Voorbeeld request:

GET /api2/facturen/4 HTTP/1.1
Host: demo.recras.nl
Accept: application/json

Voorbeeld response:

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/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,
      }
    ]
    }
  ],
}

Status Codes:

200 OK – OK
404 Not Found – 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

Invoices¶

Create¶

Update¶

Delete¶

Read¶

Changelog¶

Recras API

Navigation

Related Topics