Consumption

POST Upload consumption data 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. In ZAGIS consumption data is grouped by year; an upload can be incremental or replacing. This is a REST API with a single endpoint and a single possible action.

Access

Available to ZAGIS users only.

Endpoint

TestProduction

POST https://demo.zagis.nl/api/zagis/verbruik/{jaar}

POST https://www.zagis.nl/api/zagis/verbruik/{jaar}

Parameter	In	Type	Required	Description
jaar	path	integer	yes	The year the consumption relates to.

Authentication

This API uses:

• IP whitelisting for security
• An API key for authentication and 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	Hex-encoded SHA-512 HMAC of the request body.
x-zagis-on-exists	Can be warn, add or replace. Indicates which action ZAGIS should take if data already exists in ZAGIS for the given year. 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# that are in the existing consumption but not in the upload are not deleted.
x-zagis-on-aantal	Whether the quantities are supplied in stuk (units) or verpakking (packages). With verpakking ZAGIS converts to units itself.

Request

Requests are POST requests with a JSON array as payload. Example:

curl -X POST https://demo.zagis.nl/api/zagis/verbruik/2025 \
  -H "x-zagis-key: <your-api-key>" \
  -H "x-zagis-hmac: <hmac>" \
  -H "x-zagis-on-exists: warn" \
  -H "x-zagis-on-aantal: stuk" \
  -H "Content-Type: application/json" \
  -d '[
    { "zindex_nummer": 12345678, "omzet": 100.01, "aantal": 12 },
    { "zindex_nummer": 34567890, "omzet": 14.31, "aantal": 80 },
    { "zindex_nummer": 56789012, "omzet": 53.23, "aantal": 400 },
    { "zindex_nummer": 78901234, "omzet": 782.21, "aantal": 1201 }
  ]'

Response

Code	Meaning
200	Correct request.

Example of a response for a successful and 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 invalid content:

{
  "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 an API key.