Verbruik

POST Upload verbruikgegevens naar ZAGIS.

Voor gebruikers van ZAGIS is het mogelijk om via een API vanuit een eigen systeem verbruikgegevens te uploaden. Dit kan periodiek (dagelijks, maandelijks, jaarlijks) of op ad-hoc basis. In ZAGIS worden verbruikgegevens gegroepeerd per jaar; een upload kan incrementeel of vervangend zijn. Dit is een REST-API met één endpoint en één mogelijke actie.

Toegang

Alleen beschikbaar voor gebruikers van ZAGIS.

Endpoint

TestProductie

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

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

Parameter	In	Type	Verplicht	Omschrijving
jaar	pad	integer	ja	Het jaar waarop het verbruik betrekking heeft.

Authenticatie

Deze API maakt gebruik van:

• IP-whitelisting voor beveiliging
• Een API-key voor authenticatie en rate-limiting
• HMAC voor integriteitscontrole

Stuur de volgende headers mee:

Header	Toelichting
x-zagis-key	De aan uw organisatie uitgereikte API-key.
x-zagis-hmac	Hexadecimaal geëncodeerde SHA-512 HMAC van het request body.
x-zagis-on-exists	Kan warn, add of replace bevatten. Geeft aan welke actie ZAGIS moet nemen als er al gegevens in ZAGIS opgenomen zijn in het betreffende jaar. Bij warn stopt ZAGIS het import proces. Bij add wordt het verbruik op ZI# bij het bestaande verbruik op ZI# opgeteld. Bij replace wordt het bestaande verbruik op ZI# vervangen. ZI# die in het bestaande verbruik staan en niet in de upload zitten worden niet gewist.
x-zagis-on-aantal	Of de aantallen in stuk of verpakking worden aangeleverd. Bij verpakking zal ZAGIS zelf omrekenen naar stuks.

Request

Requests zijn POST-requests met een JSON-array als payload. Voorbeeld:

curl -X POST https://demo.zagis.nl/api/zagis/verbruik/2025 \
  -H "x-zagis-key: <uw-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	Betekenis
200	Correct request.

Voorbeeld van een response bij een succesvol en correct request:

{
  "result": "success",      // 'success' of 'error'
  "errorMessage": "",       // Error message bij fout
  "errorCode": 0,           // Error code bij fout
  "numRowsTotal": 5,        // Aantal rijen ontvangen
  "numRowsError": 1,        // Aantal rijen met een fout, worden niet geimporteerd
  "numRowsWarning": 1,      // Aantal rijen met een waarschuwing, worden wel geimporteerd
  "warnings": [             // Array met opgetreden waarschuwingen
    {
      "line": 12,
      "0": [
        "Artikel is vervallen."
      ]
    }
  ],
  "errors": [               // Array met opgetreden errors
    {
      "line": 44,
      "0": [
        "Onbekend Z-Index nummer: 14321976"
      ]
    }
  ]
}

Voorbeeld van een response bij een inhoudelijk foutief request:

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

Velden

Veld	Type	Omschrijving
result	string	success of error.
errorMessage	string	Error message bij fout.
errorCode	integer	Error code bij fout.
numRowsTotal	integer	Aantal ontvangen rijen.
numRowsError	integer	Aantal rijen met een fout; worden niet geïmporteerd.
numRowsWarning	integer	Aantal rijen met een waarschuwing; worden wel geïmporteerd.
warnings	object[]	Array met opgetreden waarschuwingen.
errors	object[]	Array met opgetreden errors.

Aandachtspunten

Wilt u uw integratie testen? Neem tijdig contact met ons op via info@zagis.nl. Wij zetten dan testdata voor u klaar en voorzien u van een API-key.