Response format

All responses from INFast API are in JSON and follow a standardized format. Here are the details 🧐

Success

In case of success, the API returns a JSON with a data field.

Exception!

This only applies to endpoints that return a response. Some endpoints (such as delete an item) do not return any data.

Single entity

When the request returns a single entity (for example Get an Item by ID), data contains the entity.

Example

{
  "data": {
    "id": "63e3c82675de4f6978054579",
    "portalId": "63e3c82675de4f6978054555",
    "name": "Robinet Mitigeur GH520",
    "type": "product",
    "price": 45.96,
    "vat": 20,
    "buyingPrice": 35.74,
    "reference": "P-000123",
    "lastUpdate": "2023-07-21T17:32:28Z"
  }
}

Multiple entities

When the request returns multiple entities (for example List Items), data is an array of entities.

Example

{
  "data": [
    {
      "id": "63e3c82675de4f6978054579",
      "portalId": "63e3c82675de4f6978054555",
      "name": "Item #1",
      ...
    },
    {
      "id": "666aa62f18a3a96aeb5d00b2",
      "portalId": "63e3c82675de4f6978054555",
      "name": "Item #2",
      ...
    },
    {
      "id": "666aa63fe883e6236f34ae07",
      "portalId": "63e3c82675de4f6978054555",
      "name": "Item #3",
      ...
    }
  ]
}

Error

In case of an error, the API returns a JSON detailing the error, in addition to the appropriate HTTP code.

Error object

{
  "error": "Error message",
  "code": 400,
  "details": ["Some details about the error"]
}

• error: the error message
• code: the HTTP code for this error (same as response headers).
• details: additional information to debug the error (optional).

Below are some examples of the most common error in the API.

Not found

You are trying to access an entity that does not exist, or no longer exists.

In the following example, details indicates that the document 648ac3762166300757144598 does not exist.

Example

{
  "error": "not found",
  "code": 404,
  "details": [
    {
      "path": "/api/v2/documents/648ac3762166300757144598",
      "message": "not found"
    }
  ]
}

Input data validation failure

The input data you provided does not validate against our OpenAPI schema.

In the following example, details indicates that the customerId field does not meet the required format.

Example

{
  "error": "request/body/customerId must NOT have fewer than 24 characters",
  "code": 400,
  "details": [
    {
      "path": "/body/customerId",
      "message": "must NOT have fewer than 24 characters",
      "errorCode": "minLength.openapi.validation"
    }
  ]
}

Request parameters issue

The request parameters you provided do not validate against our OpenAPI schema.

In the following example, details indicates that the status parameter does not exist on the specified endpoint.

Example

{
  "error": "Unknown query parameter 'status'",
  "code": 400,
  "details": [
    {
      "path": "/query/status",
      "message": "Unknown query parameter 'status'"
    }
  ]
}

Conflict error

Some actions cannot be performed depending on the state of the INFast application.

In the following example, the status of the document does not permit to delete it.

Example

{
  "error": "Can not delete a validated document",
  "code": 409
}