ZAGIS Verbruik API

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.

Deze prijs API is een REST api met 1 endpoint en 1 mogelijke actie

Test API endpoint:
https://demo.zagis.nl/api/zagis/verbruik/{jaar}

Productie API endpoint:
https://www.zagis.nl/api/zagis/verbruik/{jaar}

Authenticatie

Deze API maakt gebruik van:

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

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: 

[
  {
  	"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

Deze API retourneert de volgende HTTP status codes:

  • 200 Bij een correct request

Voorbeeld van een response bij een succesvol & 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
}
Aandachtspunten

Indien u uw integratie wilt testen neemt u tijdig contact met ons op via info@zagis.nl. Wij zetten dan testdata voor u klaar en voorzien u van een API-Key.