FOREST CRM - XML Invoice API

This API provides access to invoice data in the ForestCRM system.

This API provides the following services:

List invoices
Create new invoice
Update (modify) one invoice

List invoices

Request

The request format is:

https://app.forestcrm.hu/api/xml/<API KEY>/invoices

Request HTTP method: GET

Request parameters:

companyId (optional):: id of the company whose invoices are queried.
opportunityId (optional):: id of the opportunity whose invoices are queried.
invoiceNo (optional):: The 'invoice number' (external identifier) of the invoice(s) to be fetched.

If no parameters are supplied, all invoices for the tenant are returned. Any combination of parameters are allowed; they are 'AND'-ed.

Example

GET https://app.forestcrm.hu/api/xml/demo/invoices?companyId=5206

Response

Response conforms the attached XSD.

Notes:

'updated' is the last time the invoice's own data was updated. It does not reflect updates on company, opportunity, etc.

Example

  <invoices>
  <invoice id="30">
    <updated>2011-10-25T22:37:17+02:00</updated>
    <company id="5206">VIP Inc.</company>
    <opportunity id="121">Consulting</opportunity>
    <imported>false</imported>
    <invoice_no>IU-12345/2010</invoice_no>
    <description>Plans;</description>
    <amount>
      <value>15000</value>
      <currency>USD</currency>
    </amount>
    <delivery_date>2010-12-29</delivery_date>
    <invoice_date>2010-12-21</invoice_date>
    <due_date>2010-12-29</due_date>
    <paid_date>2011-01-03</paid_date>
    <paid_date_user_editable>true</paid_date_user_editable>
  </invoice>
  <invoice id="38">
    <updated>2011-11-01T20:17:03+02:00</updated>
    <company id="5206">VIP Inc.</company>
    <opportunity id="121">Project management</opportunity>
    <imported>true</imported>
    <invoice_no>IU-27462/2010</invoice_no>
    <description>1st Phase</description>
    <amount>
      <value>5000</value>
      <currency>USD</currency>
    </amount>
    <delivery_date>2010-12-31</delivery_date>
    <invoice_date>2010-12-31</invoice_date>
    <due_date>2011-01-31</due_date>
    <paid_date />
    <paid_date_user_editable>false</paid_date_user_editable>
  </invoice>
  </invoices>

Create a new invoice

Request

The request format is:

https://app.forestcrm.hu/api/xml/<API KEY>/invoices

Request HTTP method: POST

Request parameters:

invoice["opportunity_id"]:: The ID of the associated opportunity. Can be retrieved via the Opportunity API.
invoice["imported"]:: If true, modifications to this invoice via UI get disabled. Boolean; optional, defaults to false. Setting it to true helps keeping the source system and Forest in sync. See also paid_date_user_editable.
invoice["invoice_no"]:: External invoice number (text). Optional.
invoice["description"]:: Invoice description text. Optional.
invoice["amount"]:: Amount. Number (at most with sign and/or decimal digit); no thousand separators, no currency.
invoice["delivery_date"]:: Date of delivery (yyyy-mm-dd).
invoice["invoice_date"]:: Invoice date (yyyy-mm-dd). Must be present if invoice_no is not empty, otherwise optional.
invoice["due_date"]:: Due date (yyyy-mm-dd). Must not be present without invoice_date and must be present with it.
invoice["paid_date"]:: The date on which the invoice was paid (yyyy-mm-dd). Must not be present without invoice_date. No partial payments.
invoice["paid_date_user_editable"]:: If set to true users can modify paid_date of this invoice via the UI, regardless of the setting of imported. Boolean; optional, defaults to true. Intended for systems that can export invoices but cannot set matching payment date later.
invoice["external_ref"]:: External reference to the entity. Optional.

Example

POST https://app.forestcrm.hu/api/xml/demo/invoices

Header:

Content-Type: application/json

Body:

{
  "invoice": {
    "invoice_no": "A23445/2011",
    "imported": true,
    "amount": 10000,
    "description": "1st Phase",
    "opportunity_id": "566",
    "delivery_date": "2011-03-26",
    "invoice_date": "2011-03-26"
    "due_date": "2011-04-26"
  }
}

Response

If the company could be created the response is of status code 200 and the body contains the the ID of the invoice created in XML format:

  <invoice>
    <id type="integer">14914</id>
  </invoice>

Errors are reported with a status code (422) and the response body contains the errors in XML format.

Update (modify) an existing invoice

Request

The request format is:

https://app.forestcrm.hu/api/xml/<API KEY>/invoices/<invoice ID>

https://app.forestcrm.hu/api/xml/<API KEY>/invoices/<invoice ID>?external_ref

external_ref: If present (with any value or without value), `id` is interpreted as an external reference ("external id").

Request HTTP method: PUT

Request parameters:

invoice["opportunity_id"]:: The ID of the associated opportunity. Can be retrieved via the Opportunity API. Optional.
invoice["imported"]:: If true, modifications to this invoice via UI get disabled (boolean). Boolean; optional. Setting it to true helps keeping the source system and Forest in sync. See also paid_date_user_editable.
invoice["invoice_no"]:: External invoice number (text). Optional.
invoice["description"]:: Invoice description text. Optional.
invoice["amount"]:: Amount. Number (at most with sign and/or decimal digit); no thousand separators, no currency. Optional.
invoice["delivery_date"]:: Date of delivery (yyyy-mm-dd). Optional.
invoice["invoice_date"]:: Invoice date (yyyy-mm-dd). Date; Must be present if invoice_no is not empty, otherwise optional.
invoice["due_date"]:: Due date (yyyy-mm-dd). Must not be present without invoice_date and must be present with it.
invoice["paid_date"]:: The date on which the invoice was paid (yyyy-mm-dd). Must not be present without invoice_date. No partial payments.
invoice["paid_date_user_editable"]:: If set to true users can modify paid_date of this invoice via the UI, regardless of the setting of imported. Boolean; optional. Intended for systems that can export invoices but cannot set matching payment date later.
invoice["external_ref"]:: External reference to the entity. Optional.

Note that the requested attributes get updated (overwritten), missing attributes don't change.

Example

PUT https://app.forestcrm.hu/api/xml/demo/invoices/14914

Header:

Content-Type: application/json

Body:

{
  "invoice": {
    "paid_date": "2011-05-02"
  }
}

Response

If the invoice could be updated the response is of status code 200.

Errors are reported with a status code (422) and the response body contains the errors in XML format.

Back to index