Offers

API version 1.6.0

Offers are price quotes for services or products. Clients can create offers to inform potential customers of their services in order to pursuade them to purchase their services instead of those offered by competitors. This article describe how offers are implemented as part of the Profifact service. Because offers are often highly customized, the implementation does not provide methods for creating and updating offers.

Index

Introduction
Retrieving multiple offers
1. Request
2. Response
Retrieving an offer
1. Request
2. Response

Introduction

The offer model and its relations to other models

Offers form an important part of the sales operations of many enterprises. They inform about the services and products that can be delivered and provide insight into the associated costs. Despite their differences in purpose offers are very similar to invoices. Both are sent to (potential) customers and both consist of a set of lines with amounts, descriptions and prices. Unlike invoices however, offers are usually targeted at a particular customer which makes it more difficult to automate to process of creating an offer. Futhermore the (Dutch) regulations for offers are not as strict as those for invoices allowing clients a more liberal approach to creating offers. The primary judge of the quality of an offer is the customer, not the Belastingdienst.
The life cycle of an offer is somewhat different from that of an invoice. Like invoices, offers start as concepts from which they migrate to a definitive status. Depending upon the reaction of the customer an offer can then either be accepted or declined. Finally, accepted offers can be invoiced. The following is a list of all offer statuses with their meanings:

CONCEPT: Indicates that an offer is a concept that has not been made definitive yet. Offers with status CONCEPT do not have an offer number and can be modified or deleted by the client. Once a concept offer is marked definitive, it is assigned an offer number and its status is set to SENT.
SENT: Indicates that an offer is definitive and ready to be judged by its customer. Offers with status SENT cannot be changed or deleted. Depending on the response from the customer the next status of the offer is either ACCEPTED or DECLINED.
ACCEPTED: Indicates that an offer has been accepted by the customer. The client is in the process of delivering the services and products represented by the offer. Once delivery is (partially) complete, one or more invoices may be created based on the offer. The status of the offer then changes to INVOICED.
DECLINED: Indicates that an offer has been declined by the customer. This is a final status even though the offer may still be accepted or invoiced in which case its status changes to ACCEPTED or INVOICED.
INVOICED: Indicates that an offer has been accepted and that at least one invoice created for it has reached invoice status UNSETTLED. Offer status INVOICED is assigned automatically by Profifact once at least one of the invoices created for the offer is made definitive by having its status changed to UNSETTLED (see invoice statuses).

Once an offer reaches status SENT it cannot be modified or deleted. Not even if the address of the client or the customer changes or if the offer template associated with the offer changes. Profifact implements this behavior by associating an offer with a customer through a customer address. If the address of a customer changes only offers with status CONCEPT are updated to reference the new customer address. Offers with other statuses keep a reference to the original address. The same applies for the references to the client's address and the offer template. Because templates do not have addresses old versions are marked archived to indicate that they are not the latest version. An archived version of a template is created automatically when a template is changed (see templates).

Starting with API version 1.5.0, text-only offer lines are supported and each line has a type attribute that indicates the type of the line. Text only lines allow users to add text blocks to offers which can be used to provide product details, comments or other information that is useful or important to the customer.

REGULAR: A regular offer line that represents a good or service with an amount, a price and a VAT rate.
TEXT: A text-only offer line that is rendered without amount, price an VAT rate. For consistency with regular offer lines, the line amount and price are always zero and the line VAT rate is always null.

The Profifact service currently only implements operations for retrieving offers. Depending on the demand, automated operations for creating, updating and deleting offers may be added in the future.

Retrieving multiple offers

Clients can retrieve multiple offers by sending an HTTP GET request to /offers. Offers can be retrieved as a set of offer objects or as a set of summarized offer records. The former is useful when the client wants offer objects exactly as returned when retrieving a single offer. The latter is more useful if the results are to be displayed in a table.
Authentication is required and only offers owned by the client are returned. If no limit is specified, the maximum number of items returned is 100. If a client has more than 100 offers, multiple requests are needed to retrieve all items.

Request

HTTP GET requests to /offers may include any of the following GET parameters:

order: A comma separated set of field names specifying the sort order of the matching items. A minus sign preceeding a field name indicates descending sort order.
offset: The offset of the first item to return from the collection of matching items.
limit: The maximum number of items to return.
summary: Specifies whether to return summaries or objects. Valid values are 0 to indicate offer objects must be returned (i.e. no summarized information) and 1 to indicate that the server should return summarized offer information. 0 is the default value and yields the same results as not specifying the summary parameter at all.
customerId: A unique ID of the customer whose offers to return. If specified, only offers of a particular customer are returned. All three ID forms defined in the support section on retrieving a customer are supported.
status: A commma separated array of offer statuses, as defined in the introduction, indicating the statuses of the offers to include in the results. If specified the results are filtered by offer status such that only offers are included whose statuses are in the array of offer statuses indicated by the value this parameter. The empty string is not a valid value for this parameter, because it would always cause an empty result set.

Examples


            // Retrieve the first 100 offer objects ordered by ID (both are equivalent):

            GET /offers?summary=0&limit=100&order=id HTTP/1.1

            GET /offers HTTP/1.1

            

            // Retrieve offer objects 20 through 29 (if available) ordered by number:

            GET /offers?order=number&offset=20&limit=10 HTTP/1.1

            

            // Retrieve offer objects sorted by price type, status and id (descending):

            GET /offers?order=priceType,status,-id HTTP/1.1

            

            // Retrieve summaries of the first 100 offers ordered by offer ID:

            GET /offers?summary=1&order=id HTTP/1.1

            

            // Retrieve the first 100 offer objects for a customer by ID (both are equivalent):

            GET /offers?customerId=989732 HTTP/1.1

            GET /offers?customerId=id:989732 HTTP/1.1

            

            // Retrieve the first 100 offer objects for a customer by address ID:

            GET /offers?customerId=addressId:5941 HTTP/1.1

            

            // Retrieve the first 100 offer objects for a customer by external ID:

            GET /offers?customerId=externalId:JQ88P003 HTTP/1.1

            

            // Retrieve the first 100 concept offer objects:

            GET /offers?status=CONCEPT HTTP/1.1

            

            // Retrieve summaries of the first 100 unsettled and uncollectible offers:

            GET /offers?summary=1&status=UNSETTLED,UNCOLLECTIBLE HTTP/1.1

Response

The Profifact server may send any of the status codes defined in response status codes in response to an incoming request. For a valid request HTTP status 200 OK is returned and the response body contains a data structure with the members defined in the tables below. See the section on data types for an explanation of property data types.

If the summary parameter is not specified or has value 0 the following fields are returned:

Name	Type	Description
count	int	Specifies the number of items returned.
total	int	Specifies the total number of matching items.
offset	int	Specifies the offset of the first returned item in the collection of all matching items.
items	array	The possibly empty array of the offer objects selected for being returned based on the request. For each object the server returns exactly the properties defined by the Retrieving an offer response.

Otherwise, if the summary parameter is specified and has value 1 the following fields are returned:

Name	Type	Description
count	int	Specifies the number of items returned.
total	int	Specifies the total number of matching items.
offset	int	Specifies the offset of the first returned item in the collection of all matching items.
items	array	The possibly empty array of the offer summary records selected for being returned based on the request.
id	int	The unique ID of the offer assigned by Profifact.
customerAddressId	int	The unique ID of the version of the address of the customer associated with the offer. Customer addresses may change over time, but an offer always keeps a reference to the version of the address that was assigned to it when it was created. The only time the customer address ID of an offer changes is when the client modifies the address of the customer while the offer has status CONCEPT. The reference held by the offer is then updated to the new version of the customer address.
number	int?	The number assigned to the offer or null if the offer has status CONCEPT. Offer numbers start with the year in which they were created. The year in the offer number is always the same as the year in the date of the offer. The last four digits of the offer number are the index of the offer in that year.
date	date	The date of the offer.
status	string	The status of the offer as defined in the introduction.
validPeriod	int	The length of the period in days after an offer is created during which it may be accepted by the customer. Valid values are in the range from 0 to 999.
customerName	string	The name of the customer of the offer.
totalInclusive	decimal	The total amount represented by the offer inclusing VAT.

Retrieving an offer

Clients can retrieve a single offer by sending an HTTP GET request to /offer/RESOURCE_ID where RESOURCE_ID is the unique identifier of the requested offer.

Request

Offers can be retrieved invoices in two formats, JSON and PDF. Which of the two is returned for a particular request depends on the value of the Accept request header. If the first acceptable media type specified in the Accept header is application/json, the server returns a JSON representation of the offer. If the first acceptable media type is application/pdf, the server returns a rendered PDF representation of the offer.
Currently, no additional GET parameters are supported for requests to /offers/RESOURCE_ID.

Examples


            // Retrieve the JSON reprsentation of an offer by its unique ID:

            GET /invoices/397999 HTTP/1.1

            Accept: application/json

            

            // Retrieve a PDF representation of the same offer:

            GET /invoices/397999 HTTP/1.1

            Accept: application/pdf

Response

The Profifact server may send any of the status codes defined in response status codes in response to an incoming request. For a valid request HTTP status 200 OK is returned and the response body contains the data requested by the client. Requesting a PDF representation causes the service to return binary PDF data that can be stored as a PDF file. Requesting a JSON representation causes the service to return an offer object whose members are shown in the table below. See the section on data types for an explanation of property data types.

Name	Type	Description
id	int	The unique ID of the offer assigned by Profifact.
clientAddressId	int	The unique ID of the version of the client's address associated with the offer. Client addresses may change over time, but an offer always keeps a reference to the version of the address that was assigned to it when it was created. The only time the client address ID of an offer changes is when the client modifies its own address while the offer has status CONCEPT. The reference held by the offer is then updated to the new version of the client's address.
customerAddressId	int	The unique ID of the version of the address of the customer associated with the offer. Customer addresses may change over time, but an offer always keeps a reference to the version of the address that was assigned to it when it was created. The only time the customer address ID of an offer changes is when the client modifies the address of the customer while the offer has status CONCEPT. The reference held by the offer is then updated to the new version of the customer address.
templateId	int	The unique ID of the version of the template associated with the offer. Offer templates may change over time, but an offer always keeps a reference to the version of the template that was assigned to it when the offer was created. The only time the template ID of an offer changes is when the client modifies the template while the offer has status CONCEPT. The reference held by the offer is then updated to the new version of the template.
number	int?	The number assigned to the offer or null if the offer has status CONCEPT. Offer numbers start with the year in which they were created. The year in the offer number is always the same as the year in the date of the offer. The last four digits of the offer number are the index of the offer in that year.
date	date	The date of the offer.
status	string	The status of the offer as defined in the introduction.
priceType	string	Indicates whether the prices in the lines of the offer include VAT. Valid values are INCLUSIVE and EXCLUSIVE.
validPeriod	int	The length of the period in days after an offer is created during which it may be accepted by the customer. Valid values are in the range from 0 to 999.
reference	string	The reference of the offer as specified by the client.
comments	string	The comments of the offer as specified by the client.
lines	array	The array offer lines that are part of the offer. An offer has at least one offer line. Offer lines do not have IDs, because they do not exist as seperate entities outside the scope of offers. Offer lines are returned in the order in which they appear on the offer.
type	string	The type of the offer line as defined in the introduction.
amount	decimal	The amount of the product or service represented by the offer line.
price	decimal	The price of the product or service represented by the offer line.
description	string	A description of the product or service represented by the offer line.
vatRateId	int	The unique ID of the VAT rate that applies to the product or service represented by the offer line.
invoices	array	The array of invoices that were created based on the offer. Offers with status CONCEPT cannot have associated invoices. See the response for retrieving an invoice for a more in depth discussion of the properties returned for each invoice.
id	int	The unique ID of the invoice assigned by Profifact.
parentId	int?	The unique ID of the invoice of which the invoice is a reversal. If the invoice is not a reversal the value is null.
clientAddressId	int	The unique ID of the version of the client's address associated with the invoice.
customerAddressId	int	The unique ID of the version of the address of the customer associated with the invoice.
templateId	int	The unique ID of the version of the template associated with the invoice.
number	int?	The number assigned to the invoice or null if the invoice has status CONCEPT.
date	date	The date of the invoice.
status	string	The status of the invoice.
priceType	string	Indicates whether the prices in the lines of the invoice include VAT.
paymentPeriod	int	The payment period of the invoice in days.
reference	string	The reference of the invoice as specified by the client.
comments	string	The comments of the invoice as specified by the client.