Daily consumption

POST Upload consumption data at day level to ZAGIS.

Users of ZAGIS can upload consumption data from their own system via an API. This can be done periodically (daily, monthly, yearly) or on an ad-hoc basis. This connection makes it possible to record consumption at day level. An upload can be incremental or replacing. This is a REST API with a single endpoint and one possible action.

Access

Available to ZAGIS users only.

Endpoint

TestProduction

POST https://demo.zagis.nl/api/zagis/verbruik-details

POST https://www.zagis.nl/api/zagis/verbruik-details

Authentication

This API uses:

• IP whitelisting for security
• An API key for authentication & rate limiting
• HMAC for integrity checking

Send the following headers:

Header	Description
x-zagis-key	The API key issued to your organisation.
x-zagis-hmac	Hexadecimally encoded SHA-512 HMAC of the request body.
x-zagis-on-exists	Can contain warn, add or replace. Indicates which action ZAGIS should take if data has already been recorded in ZAGIS for the year in question. With warn ZAGIS stops the import process. With add the consumption for a ZI# is added to the existing consumption for that ZI#. With replace the existing consumption for a ZI# is replaced. ZI# present in the existing consumption but not in the upload are not deleted.
x-zagis-on-aantal	Whether quantities are supplied in stuk (units) or verpakking (packages). With verpakking ZAGIS converts to units itself.
x-zagis-extrapolatie	Carry detailed consumption through to yearly consumption. Options extrapoleer, totaliseer or niets.

Request

Requests are POST requests with a JSON array as payload.

curl -X POST https://demo.zagis.nl/api/zagis/verbruik-details \
  -H "x-zagis-key: <your-api-key>" \
  -H "x-zagis-hmac: <hmac>" \
  -H "Content-Type: application/json" \
  -d '[
  {
    "ontvangst_datum": "2022-01-01",
    "zindex_nummer": 12345678,
    "waarde": 100.01,
    "aantal": 12
  },
  {
    "ontvangst_datum": "2022-01-02",
    "zindex_nummer": 34567890,
    "waarde": 14.31,
    "aantal": 80
  },
  {
    "ontvangst_datum": "2022-01-03",
    "zindex_nummer": 56789012,
    "waarde": 53.23,
    "aantal": 400
  },
  {
    "ontvangst_datum": "2022-01-04",
    "zindex_nummer": 78901234,
    "waarde": 782.21,
    "aantal": 1201
  }
]'

Fields

Field	Type	Description
ontvangst_datum	string	Receipt date (YYYY-MM-DD).
zindex_nummer	integer	Z-Index number of the article.
waarde	number	Consumption value.
aantal	integer	Quantity, in stuk (units) or verpakking (packages) (see x-zagis-on-aantal).

Response

This API returns the following HTTP status codes:

Code	Meaning
200	Correct request.

Example of a response for a successful & correct request:

{
  "result": "success",       // 'success' or 'error'
  "errorMessage": "",        // Error message on failure
  "errorCode": 0,            // Error code on failure
  "numRowsTotal": 5,         // Number of rows received
  "numRowsError": 1,         // Number of rows with an error, not imported
  "numRowsWarning": 1,       // Number of rows with a warning, still imported
  "warnings": [              // Array of warnings that occurred
    {
      "line": 12,
      "0": [
        "Artikel is vervallen."
      ]
    }
  ],
  "errors": [                // Array of errors that occurred
    {
      "line": 44,
      "0": [
        "Onbekend Z-Index nummer: 14321976"
      ]
    }
  ]
}

Example of a response for a request with a content error:

{
  "result": "error",
  "errorMessage": "Invalid value for onExist. Allowed [warn, add, replace]",
  "errorCode": 1
}

Fields

Field	Type	Description
result	string	success or error.
errorMessage	string	Error message on failure.
errorCode	integer	Error code on failure.
numRowsTotal	integer	Number of rows received.
numRowsError	integer	Number of rows with an error; not imported.
numRowsWarning	integer	Number of rows with a warning; still imported.
warnings	object[]	Array of warnings that occurred.
errors	object[]	Array of errors that occurred.

Notes

Want to test your integration? Contact us in good time at info@zagis.nl. We will then prepare test data for you and provide you with an API key.