Welcome to api.rob-net.nl
This page is your starting point for connecting to the ROB-Net REST API for suppliers. On this page you can find information about the ins and outs of using the REST API. For specific topics please view the sidebar navigation. For the used ROB-Net terminology, recent changes and/or OpenAPI specifications: please see the navigation bar at the top right of this page.
Postman Collection
A postman collection is available through the ROB-Net helpdesk. It contains example calls for all of the REST API methods.
API Overview
The ROB-Net REST API provides a myriad of methods in order to allow the supplier to communicate planned work on an object. Since this version the API supports rental vehicle requests (historically also known as relief vehicle requests). The current specifications and schema can be found on the API details page here.
Authentication
Authentication is done through an HTTP header named Authentication which contains a JWT bearer token. The actual token can be retrieved through ROB-Net by going to the page "Pakketkoppeling" which can be found as an option in the "Instellingen" menu dropdown. The token needs to be prefixed with the text Bearer like so:
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9
Encoding
The REST API exclusively uses UTF-8 for HTTP requests.
Identifiers
The REST API relies on the use of Global Unique Identifier (GUID), also known as Universally Unique Identifier (UUID), for IDs. In order to ensure uniqueness, the create service request method generates a GUID server side as ID for service requests. For components the user is free to supply the GUIDs with the constraint that within a service request all GUIDs must be unique.
Date and DateTime
No (REST) API documentation is complete without a short paragraph about the datetime usage. All dates are expected to be in the format yyyy-MM-dd (e.g. 2022-11-28), commonly known as an ISO 8601 format and described as a full-date by RFC3339 on internet Date/Time formats. The fields using dates as value will be documented in the API details as having the format date.
The datetime values are expected to be in the format yyyy-MM-ddThh:mm:ssZ (e.g. 2022-11-28T07:30:00Z), also known as an ISO 8601 format and described as a date-time by RFC3339 on internet Date/Time formats. The fields using datetime as value will be documented in the API details as having the format date-time. In addition it is allowed to replace the trailing Z with a time zone offset, e.g. +02:00 for the GMT+2 time zone which is the daylight saving time for the Netherlands.
Note that all API responses which include datetime values will always use the UTC time zone, e.g. "checkoutDate": "2022-02-04T12:23:38.977Z", regardless of the time zone the datetime was originally supplied with.
Workflow
From the perspective of the API user there are 6 distinct phases of a request, with the first five currently fully supported by the REST API:
- Discovery phase
- Draft phase
- Lessor phase
- Response phase
- Invoicing phase
- Archived phase
Discovery Phase
Before a new request is made this optional phase may take place. During this phase the available lessors can be fetched, tire specifications may be retrieved or searched through, contracts may be requested, existing requests can be viewed and more.
Draft Phase
During draft a request is created by the supplier (API user). The only requirement at this stage is that the request is tied to an object in ROB-Net. Whilst in the draft phase most of the request is still mutable. Once ready for review by the lessor it can advance to the lessor phase by patching the appropriate status or by supplying this status in the overwrite service request method.
The draft phase can be skipped by creating a service request with the appropriate status to request approval immediately upon successful creation.
Lessor Phase
When a request resides in the lessor phase it means the lessor is reviewing the request. In the case of a service request it means that each line is given a response status, for example approved or denied. Once done reviewing the lessor will return the request to the supplier. If the request is approved, the invoicing phase may be entered. If the request is partially or completely denied the response phase is entered.
Response Phase
During the response phase the supplier can alter the request to make the desired changes. Once done, the supplier may send it again to the lessor for review. The only next possible phase is the lessor phase. This phase transition is achieved by patching the appropriate status for service requests.
Invoicing Phase
The invoicing phase is a special type of the response phase in which the request has been approved by the lessor and can either be invoiced by the supplier or optionally changed. If the request is invoiced the archived phase will automatically follow, but if any changes are made to the request itself the phase changes directly to the response phase. It is not possible to alter a request once invoiced.
Note that if the approved request has no associated costs the archived phase will automatically be entered. This may be the case if all lines are either under warranty or their cancellation has been approved.
Archived Phase
Around midnight, in the Amsterdam time zone, all invoiced requests are archived in ROB-Net. This means that the requests disappear from methods such as get all requests and are put in a separate place. The REST API currently offers no methods that can retrieve archived requests.
Methods
In this section the different available methods of the ROB-Net REST API endpoints are described. Specifics and more detailed information is available on the API Details page. The subsections below are sorted alphabetically by title.
GET /v2/lessors/notifications is used to retrieve a list of all active notifications relevant for the current supplier. The optional query parameter showInactiveNotifications (true / false) can be provided to also return notifications that have expired. The optional query parameter lessorId can be provided to filter notifications on the publisher.
PUT /v2/servicerequests/{id}/attachment is used to upload a file to attach to a service request. The service request is identified by the GUID in the {id} parameter
DELETE v2/servicerequests/{id}/attachments/{attachmentId} is used to delete an attachment from a service request. The service request is identified by the GUID in the {id} parameter and the attachment by the {attachmentId} parameter
GET /v2/servicerequests/{id}/attachments/{attachmentId} is used to retrieve a service request attachment. The service request is identified by the GUID in the {id} parameter and the attachment by the {attachmentId} parameter
GET /v2/servicerequests/{id}/attachments is used to retrieve all service request attachments. The service request is identified by the GUID in the {id} parameter
GET /v2/components is used to retrieve the complete list of all components supported by ROB-Net. This is not meant to determine the allowed components for use in a service request, use the contract endpoint components method or lessor endpoint components method for that.
GET /v2/contracts/{licensePlate}/components is used to retrieve the retrieve allowed components for the active object identified by the {licensePlate} parameter. If a service request already exists for the specified object, the lessor contract components method is strongly recommended to be used instead. Details on the optional URL query parameters can be found here.
GET /v2/lessors/{lessorId}/contracts/{licensePlate}/components is used to retrieve the allowed components for the specified lessor owned object. This method will always yield a list of allowed components if the object exists, regardless of its active/inactive state. The lessor is identified by the {lessorId} parameter which can be found in the service request, whereas the object contract is identified by the {licensePlate}. Details on the optional URL query parameters can be found here.
GET /v2/contracts/{licensePlate} is used to retrieve the contract for the active object identified by the {licensePlate} parameter. For inactive objects use the lessor contract method.
GET /v2/lessors/{lessorId}/contracts/{licensePlate} is used to retrieve the contract for the specified lessor. This method will always yield a contract if the object exists, regardless of its active/inactive state. The lessor is identified by the {lessorId} parameter which can be found in the service request, whereas the contract is identified by the {licensePlate}.
GET /v2/objecttypes is used to retrieve a list of all known object type codes and their associated object type categories as used by the service level methods to further specify configured rates.
GET /v2/damagecomponents is used to retrieve the complete list of all damage components supported by ROB-Net. This is not meant to determine the allowed damage components for use in a damage service request, use the contract endpoint damage components method or lessor endpoint damage components method for that.
GET /v2/contracts/{licensePlate}/damagecomponents is used to retrieve the allowed damage components for the active object identified by the {licensePlate} parameter. If a damage service request already exists for the specified object, it is strongly recommended to use the lessor contract damage components method instead.
GET /v2/lessors/{lessorId}/contracts/{licensePlate}/damagecomponents is used to retrieve the allowed damage components for the specified lessor owned object. This method will always yield a list of allowed damage components if the object exists, regardless of its active/inactive state. The lessor is identified by the {lessorId} parameter which can be found in the damage service request, whereas the object is identified by the {licensePlate}. Details on the optional URL query parameters can be found here.
GET /v2/damageservicerequests is used to retrieve an overview of open damage service requests.
GET /v2/damageservicerequests/{id} is used to retrieve the complete damage service request identified by its GUID as the {id} parameter.
POST /v2/damageservicerequests is used to create new damage service requests. There is no constraint on the number of damage service requests for a given object at a time per supplier. This method is only valid during the draft phase. The response will contain the assigned GUID of the damage service request used to refer to it in other methods.
PATCH /v2/damageservicerequests/{id} is used to modify the damage service request identified by the GUID as the {id} parameter. This is the default method to use when modifying an existing damage service request in either the draft phase or the response phase. In its most minimalistic form it can be used to only change the status of the damage service request, i.e. to advance it to the lessor phase. However, it can also change the supplier remarks, add or change lines that are part of the damage service request, supply the appointment details and partial vin of the object.
DELETE /v2/damageservicerequests/{id} is used to delete the damage service request identified by the GUID as the {id} parameter. This method is only valid during the draft phase.
PUT /v2/damageservicerequests/{requestId}/components/{componentId} is used to create or overwrite damage service request lines. The damage service request to modify is identified by its GUID in the {requestId} parameter, whilst the line to create or overwrite is specified by the {componentId} parameter. This method is only valid during the draft phase or the response phase.
DELETE /v2/damageservicerequests/{requestId}/components/{componentId} is used to delete existing damage service request lines. The damage service request to modify is identified by its GUID in the {requestId} parameter, whilst the delete is identified by the {componentId} parameter. It is only valid for newly created lines that have not been sent yet to the lessor during the draft phase or response phase. If the line has been sent to the lessor already it can be cancelled instead.
POST /v2/damageservicerequests/{requestId}/components/{componentId}/cancel is used to cancel existing damage service request lines. The damage service request to modify is identified by its GUID in the {requestId} parameter, whilst the line to cancel is identified by the {componentId} parameter. It is only valid for lines that have been sent to the lessor, which narrows it to the response phase. For newly created lines use the delete line method.
PUT /v2/damageservicerequests/{id}/attachments is used to upload a file to attach to a damage service request. The service request is identified by the GUID in the {id} parameter
DELETE /v2/damageservicerequests/{id}/attachments/{attachmentId} is used to delete an attachment from a damage service request. The service request is identified by the GUID in the {id} parameter and the attachment by the {attachmentId} parameter
GET /v2/damageservicerequests/{id}/attachments/{attachmentId} is used to retrieve a damage service request attachment. The service request is identified by the GUID in the {id} parameter and the attachment by the {attachmentId} parameter
GET /v2/damageservicerequests/{id}/attachments is used to retrieve all damage service request attachments. The service request is identified by the GUID in the {id} parameter
GET /v2/damageservicerequests/{id}/invoicetemplates This method is used to retrieve templates to base the next invoice on. Depending on the amount already invoiced, this method will return a debit invoice template, a credit invoice template or both. The templates include the required information to correctly address the invoice to the (sub)lessor associated with the damage service request along with the amount to debit invoice and the amount to credit invoice. The damage service request is identified by the GUID in the {id} parameter. This method is valid in both the invoicing phase and archived phase.
POST /v2/damageservicerequests/{id}/invoices is used to create a new invoice for a damage service request. Depending on the lessor setting, a discount invoice may be required. The damage service request is identified by the GUID in the {id} parameter. Consider using the templates method to more easily create a correct invoice. During the invoicing phase only debit invoices (and optionally discount invoices) are allowed. In the archived phase, both debit and credit invoices are allowed.
GET /v2/damageservicerequests/{id}/invoices is used to retrieve all invoices for a damage service request. The request is identified by the GUID in the {id} parameter. This method is valid in both the invoicing phase and the archived phase.
GET /v2/damageservicerequests/{id}/invoices/{invoiceId} is used to retrieve a single invoice for a damage service request. The request is identified by the GUID in the {id} parameter, and the specific invoice by the integer {invoiceId} parameter. This method is valid in both the invoicing phase and the archived phase.
POST /v2/damageservicerequests/{id}/invoices/status is used to set the invoice status for a damage service request. The request is identified by the GUID in the {id} parameter. This method is valid in the invoicing phase.
PUT /v2/damageservicerequests/{id}/invoices/{invoiceId}/pdf is used to upload a PDF file to attach to a specific invoice of a damage service request. The damage service request is identified by the GUID in the {id} parameter, the specific invoice by the integer {invoiceId} parameter. This method is valid in both the invoicing phase and archived phase.
GET /v2/damageservicerequests/{id}/invoices/{invoiceId}/pdf is used to retrieve the previously uploaded PDF file attached to a specific invoice of a damage service request. The damage service request is identified by the GUID in the {id} parameter, the specific invoice by the integer {invoiceId} parameter. This method is valid in both the invoicing phase and archived phase.
GET /v2/dealerships is used to retrieve all dealership codes and their names known to ROB-Net. This information may provide helpful context when dealing with service level agreements.
GET /v2/servicerequests/{id}/invoices is used to retrieve all the invoices of a service request. The request is identified by the GUID in the {id} parameter. This method is valid in both the invoicing phase and archived phase.
GET /v2/servicerequests/{id}/invoices/{invoiceId} is used to retrieve a single invoice of a service request. The request is identified by the GUID in the {id} parameter, the specific invoice by the integer {invoiceId} parameter. This method is valid in both the invoicing phase and archived phase.
GET /v2/servicerequests/{id}/invoicetemplate Deprecated
Please use the method /v2/servicerequests/{id}/invoicetemplates instead.
This method is used to retrieve a template to base a new invoice on. This template includes the required information to correctly address the
invoice to the (sub)lessor associated with the request along with the amount
to debit invoice and the amount to credit invoice. The request is identified
by the GUID in the {id} parameter. This method is valid in both the
invoicing phase and archived phase.
GET /v2/servicerequests/{id}/invoicetemplates This method is used to retrieve templates to base the next invoice on. Depending on the amount already invoiced, this method will return a debit invoice template, a credit invoice template or both. The templates include the required information to correctly address the invoice to the (sub)lessor associated with the request along with the amount to debit invoice and the amount to credit invoice. The request is identified by the GUID in the {id} parameter. This method is valid in both the invoicing phase and archived phase.
POST /v2/servicerequests/{id}/invoices is used to create a new invoice for a request. The request is identified by the GUID in the {id} parameter. Consider using the template method in order to more easily create a correct invoice. During the invoicing phase only debit invoices are allowed and in the archived phase both debit and credit invoices are allowed.
PUT /v2/servicerequests/{id}/invoices is used to set the invoice status of a request. The request affected is identified by GUID in the {id} parameter. This method is only valid during the invoicing phase. This method should only be used if invoicing is either done outside of ROB-Net or if the request will not be invoiced at all.
PUT /v2/servicerequests/{id}/invoices/{invoiceId}/pdf is used to upload a PDF file to attach to a specific invoice of a service request. The request is identified by the GUID in the {id} parameter, the specific invoice by the integer {invoiceId} parameter. This method is valid in both the invoicing phase and archived phase.
GET /v2/servicerequests/{id}/invoices/{invoiceId}/pdf is used to retrieve the previously uploaded PDF file attached to a specific invoice of a service request. The request is identified by the GUID in the {id} parameter, the specific invoice by the integer {invoiceId} parameter. This method is valid in both the invoicing phase and archived phase.
GET /v2/lessors is used to retrieve a list of all active lessors participating in ROB-Net.
GET /v2/lessor/{lessorId} is used to retrieve a specific active lessor participating in ROB-Net.
GET /v2/rentalclasses is used to retrieve all rental classes and their descriptions known to ROB-Net. This information may provide helpful context when dealing with rental vehicle service requests.
GET /v2/rentalvehicles/{licensePlate} is used to retrieve information about the rental class properties of a vehicle identified by the given license plate. The returned information is intended to be helpful in determining the appropriate SLA rates to use.
Request Methods
Deprecated
These methods are deprecated, please refer to the service request equivalent.
GET /v2/requests is used to retrieve information about open requests. The latter are currently not retrievable or mutable by other methods than this method. Details on the optional URL query parameters can be found here.
In ROB-Net service level agreements are on a per category basis. This means that the values configured for repair and maintenance, tires and rental vehicle may come from different service level agreements respectively.
This separation of service level agreements per category also means that if an agreement is not configured with values for a specific category the system will try to fallback to a more generic agreement. The precedence from highest to lowest is:
- An agreement with a match in the object lessor and vehicle make (dealership)
- An agreement with a match in the object lessor
- The default service level
In addition, there are two sets of values per service level agreements: the current values are those which are applicable on the date of the HTTP request made and the future values are those applicable on a date in the future and onwards.
To see what agreements are applicable to for specific object please refer to the contract methods.
GET /v2/servicelevel is used to retrieve all service level information for the user. This combines the output of the following methods:
- The default service level GET /v2/servicelevel/default
- All applicable service level agreements GET /v2/servicelevel/agreements
- The cluster the user belongs to or administers GET /v2/servicelevel/cluster
GET /v2/servicelevel/default is used to retrieve the default service level configuration. Note that this method yields an HTTP status code 403 for cluster administrators.
GET /v2/servicelevel/agreements/{id} is used to retrieve a specific service level agreement. Note that each agreement must has a unique set of associated lessors (required) and dealerships (optional). Refer to the default service level methods for values not associated with any particular lessors.
GET /v2/servicerequests is used to retrieve an overview of open service requests. Details on the optional URL query parameters can be found here.
GET /v2/servicerequests/{id} is used to retrieve the complete service request identified by its GUID as the {id} parameter.
POST /v2/servicerequests is used to create new service requests. Only two service requests may exist for a given object at a time per supplier. One may contain rental vehicle lines and the other may contain repair and maintenance and/or tires lines. This method is only valid during the draft phase. The response will contain the assigned GUID of the service request used to refer to it in other methods.
PUT /v2/servicerequests/{id} is used to overwrite the service request identified by the GUID as the {id} parameter. This is a convenient way to (almost) completely rewrite a service request that is still in its draft phase. Once a service request has been sent to the lessor this method is no longer valid to use. In most cases the PATCH method is more appropriate to use.
PATCH /v2/servicerequests/{id} is used to modify the service request identified by the GUID as the {id} parameter. This is the default method to use when modifying an existing service request in either the draft phase or the response phase. In its most minimalistic form it can be used to only change the status of the service request, i.e. to advance it to the lessor phase. However, it can also change the supplier remarks, add or change lines that are part of the service request, supply the appointment details and partial vin of the object.
DELETE /v2/servicerequests/{id} is used to delete the service request identified by the GUID as the {id} parameter. This method is only valid during the draft phase.
PUT /v2/servicerequests/{requestId}/components/{componentId} is used to create or overwrite service request lines. The service request to modify is identified by its GUID in the {requestId} parameter, whilst the line to create or overwrite is specified by the {componentId} parameter. This method is only valid during the draft phase or the response phase.
DELETE /v2/servicerequests/{requestId}/components/{componentId} is used to delete existing service request lines. The service request to modify is identified by its GUID in the {requestId} parameter, whilst the line to create or overwrite is identified by the {componentId} parameter. It is only valid for newly created lines that have not been sent yet to the lessor during the draft phase or response phase. If the line has been sent to the lessor already it can be cancelled instead.
POST /v2/servicerequests/{requestId}/components/{componentId}/cancel is used to cancel existing service request lines. The service request to modify is identified by its GUID in the {requestId} parameter, whilst the line to cancel is identified by the {componentId} parameter. It is only valid for lines that have been sent to the lessor, which narrows it to the response phase. For newly created lines use the delete line method.
GET /v2/tire is used to retrieve specifications of a tire by either BAC code or tire ID. Service requests may contain tire specifications when dealing with tire components. In these cases the tire ID is always used. Details on the URL query parameters can be found here.
GET /v2/tires is used to search for tire specifications by general terms, by partial specifications, by EAN code and more. The results will include tire IDs for use with tire components. Details on the URL query parameters can be found here.
GET /v2/tires/makes is used to retrieve a list of all known tire makes in ROB-Net.
Frequently Asked Questions
Why is the service request being rejected by the API despite using the allowed components to create it?
The allowed components are determined by the contract. This resource is mutable by the lessor at any time. Do not cache the allowed components or the contract, retrieve a fresh copy whenever changing a request by using the component methods.
How to supply the mileage or hours of the vehicle?
In the allowed components either a mileage component or an hours component is included, depending on the type of object. A mileage component is identifiable by the combination of ROB-code 5401 with the operation code 19 (no type code). A hours component is identifiable by the combination of ROB code 5449 with the operation code 19 (no type code).
What fields are required for a draft service request?
For all service requests the following is required to create one for the draft phase:
- The license plate of the object
What fields are required for requesting approval?
For repair and maintenance and/or tires service requests the following is required:
- The license plate of the object
- The partial VIN of the object
- The following appointment details: work order number, estimated duration of the repair, the workshop date and the contact person
- The mileage or hours reading, for pointers see this FAQ entry
- At least one line, excluding the mileage or hours read
For rental vehicle service requests the following is required:
- The license plate of the object
- The following appointment details: work order number, the (expected) checkout date of the to-be-rented vehicle
- A single rental vehicle line