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", // (confirmed)
   "voorschot_percentage": 100, // (advance_percentage)
   "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}.", // ({contact_person_first_name}, {outing_number}, {invoice_amount}, {invoice_remaining_amount})
   "mail_signature": "Kind regards, {gebruiker_voornaam}", // ({user_first_name})
   "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, // (customer_id)
  "context": "invoice",
  "status": "concept", // (draft)
  "factuur_nummer": null, // (invoice_number)
  "verstuur_factuur_op": "2016-05-03", // (send_invoice_on)
  "datum": null, // (date)
  "pdf_locatie": null, // (pdf_location)
  "opmerking": null, // (remark)
  "aantal_personen": 1, // (number_of_persons)
  "betaaltermijn": 14, // (payment_term)
  "referentie_klant": null, // (customer_reference)
  "reference_external": "V0;0099-T099;Kassenbeleg-V1;",
  "herinnering1": null, // (reminder1)
  "herinnering2": null, // (reminder2)
  "calculated_totaalbedrag_inclusief_btw": 55, // (calculated_total_amount_including_vat)
  "mollie_transaction_id": null,
  "crediteert_factuur_id": null, // (credits_invoice_id)
  "bedrijf_id": 1, // (company_id)
  "btw_verlegd": false, // (vat_shifted)
  "boeking_id": 42 // (booking_id)
}

JSON Parameters:

boeking_id (int) – Required id of the booking (boeking_id means booking_id)
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. (voorschot_percentage means advance_percentage)
mail_to (int) – Optional, only available with status =``definitief`` (confirmed), 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`` (confirmed) 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 (createInvoice) permission

Filters

It is possible to filter by company by using bedrijf_id (company_id) as URL parameter:

GET /api2/facturen?bedrijf_id=1¶

Will only return invoices that belong to the company with ID 1

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 (draft)) can be made permanent with the markeeralsverzonden (mark_as_sent) 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

{
   "render_pdf:" false,
   "betalingen": [ // (payments)
      {
         "bedrag": 25.00, // (amount)
         "betaalmethode_id": 3, // (payment_method_id)
         "pos_id": 2,
         "location_id": 4
      }
   ]
}

Example response:

HTTP/1.1 200 OK Content-Length: 0

JSON Parameters:

render_pdf (string) – Optional true to render the pdf instantly, false to render the pdf using a background job
betalingen (payment[]) – Optional A list of payments (betalingen) to process on marking the invoice as permanent.
betalingen.bedrag (float) – Required The value of the payment (bedrag means amount)
betalingen.betaalmethode_id (int) – Optional A reference to a payment method (betaalmethode_id means payment_method_id).
betalingen.pos_id (int) – Optional A reference to a Recras point-of-sale
betalingen.locatie_id (int) – Optional A reference to a location (locatie_id). 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 (createInvoice) permission

Delete¶

Only draft invoices (status = concept (draft)) 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 (draft)

Read¶

GET /api2/facturen¶

Example request:

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

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": 1,
    "klant_id": 8, // (customer_id)
    "status": "verzonden", // (sent)
    "factuur_nummer": "1-4-8", // (invoice_number)
    "verstuur_factuur_op": "2016-05-03", // (send_invoice_on)
    "datum": "2016-05-03", // (date)
    "pdf_locatie": "factuur_1-4-8_2016-05-03.pdf", // (pdf_location)
    "opmerking": "", // (remark)
    "aantal_personen": 14, // (number_of_persons)
    "betaaltermijn": 14, // (payment_term)
    "referentie_klant": "", // (customer_reference)
    "reference_external": "V0;0099-T099;Kassenbeleg-V1;",
    "herinnering1": null, // (reminder1)
    "herinnering2": null, // (reminder2)
    "calculated_totaalbedrag_inclusief_btw": 19.75, // (calculated_total_amount_including_vat)
    "mollie_transaction_id": null,
    "crediteert_factuur_id": null, // (credits_invoice_id)
    "bedrijf_id": 1, // (company_id)
    "btw_verlegd": false, // (vat_shifted)
    "boeking_id": 3, // (booking_id)
    "pdf_href": "https://demo.recras.nl/api2/facturen/1.pdf"
  },
  {
    "id": 2,
    "klant_id": 5, // (customer_id)
    "status": "betaald", // (paid)
    "factuur_nummer": "1-5-5", // (invoice_number)
    "verstuur_factuur_op": "2016-05-03", // (send_invoice_on)
    "datum": "2016-05-03", // (date)
    "pdf_locatie": "factuur_1-5-5_2016-05-03.pdf", // (pdf_location)
    "opmerking": "", // (remark)
    "aantal_personen": 23, // (number_of_persons)
    "betaaltermijn": -3, // (payment_term)
    "referentie_klant": "", // (customer_reference)
    "reference_external": "",
    "herinnering1": null, // (reminder1)
    "herinnering2": null, // (reminder2)
    "calculated_totaalbedrag_inclusief_btw": 1824.75, // (calculated_total_amount_including_vat)
    "mollie_transaction_id": 0,
    "crediteert_factuur_id": null, // (credits_invoice_id)
    "bedrijf_id": 1, // (company_id)
    "btw_verlegd": false, // (vat_shifted)
    "boeking_id": 5, // (booking_id)
    "pdf_href": "https://demo.recras.nl/api2/facturen/2.pdf"
  },
]

Query Parameters:

boeking_id (int) – filter by booking id (boeking_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 (datum).
datumVoor (ISO8601-date) – Show only invoices dated on or before the given date (datumVoor means dateBefore).
datumNa (ISO8601-date) – Show only invoices dated on or after the given date (datumNa means dateAfter).
verstuur_factuur_op (ISO8601-date) – Show only invoices to be sent on the given date, relevant with ?status=concept (verstuur_factuur_op means send_invoice_on).
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 (credit invoice (Creditfactuur)) (invoice that credits this invoice)

GecrediteerdeFactuur (Credited Invoice (GecrediteerdeFactuur)) (invoice that the current resource credits)

_calculated.gestructureerde_mededeling (a prepared “Structured Communication” (Gestructureerde Mededeling) payment reference)

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

A specific invoice (factuur)

Example request:

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

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 4,
  "klant_id": 8, // (customer_id)
  "status": "verzonden", // (sent)
  "factuur_nummer": "1-4-8", // (invoice_number)
  "verstuur_factuur_op": "2016-05-03", // (send_invoice_on)
  "datum": "2016-05-03", // (date)
  "pdf_locatie": "factuur_1-4-8_2016-05-03.pdf", // (pdf_location)
  "opmerking": "", // (remark)
  "aantal_personen": 14, // (number_of_persons)
  "betaaltermijn": 14, // (payment_term)
  "referentie_klant": "", // (customer_reference)
  "reference_external": "",
  "herinnering1": null, // (reminder1)
  "herinnering2": null, // (reminder2)
  "calculated_totaalbedrag_inclusief_btw": 19.75, // (calculated_total_amount_including_vat)
  "mollie_transaction_id": null,
  "crediteert_factuur_id": null, // (credits_invoice_id)
  "bedrijf_id": 1, // (company_id)
  "btw_verlegd": false, // (vat_shifted)
  "boeking_id": 3, // (booking_id)
  "pdf_href": "https://demo.recras.nl/api2/facturen/4.pdf",
  "regels": [ // (lines)
    {
    "id": 226,
    "naam": "", // (name)
    "type": "groep", // (group)
    "kortingspercentage": 0, // (discount_percentage)
    "kortingomschrijving": "", // (discount_description)
    "voorschot_factuur_id": null, // (advance_invoice_id)
    "children_visible": false,
    "regels": [ // (lines)
      {
      "id": 227,
      "naam": "Passant - Klimbos", // (name: "Passerby - Climbing Forest")
      "type": "groep", // (group)
      "kortingspercentage": 0, // (discount_percentage)
      "kortingomschrijving": "", // (discount_description)
      "voorschot_factuur_id": null, // (advance_invoice_id)
      "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