Dagverbruik

POST Upload verbruikgegevens op dagniveau 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. Deze koppeling biedt de mogelijkheid om het verbruik op dagniveau vast te stellen. 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-details

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

Authenticatie

Deze API maakt gebruik van:

• IP-whitelisting voor beveiliging
• Een API-key voor authenticatie & 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.
x-zagis-extrapolatie	Detailverbruik doorzetten naar jaarverbruik. Mogelijkheden extrapoleer, totaliseer of niets.

Request

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

curl -X POST https://demo.zagis.nl/api/zagis/verbruik-details \
  -H "x-zagis-key: <uw-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
  }
]'

Velden

Veld	Type	Omschrijving
ontvangst_datum	string	Datum van ontvangst (JJJJ-MM-DD).
zindex_nummer	integer	Z-Index nummer van het artikel.
waarde	number	Verbruikwaarde.
aantal	integer	Aantal, in stuk of verpakking (zie x-zagis-on-aantal).

Response

Deze API retourneert de volgende HTTP-statuscodes:

Code	Betekenis
200	Correct request.

Voorbeeld van een response bij een succesvol & correct request:

{
  "result": "success",       // 'success' of 'error'
  "errorMessage": "",        // Foutmelding bij fout
  "errorCode": 0,            // Foutcode bij fout
  "numRowsTotal": 5,         // Aantal rijen ontvangen
  "numRowsError": 1,         // Aantal rijen met een fout, worden niet geïmporteerd
  "numRowsWarning": 1,       // Aantal rijen met een waarschuwing, worden wel geïmporteerd
  "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	Foutmelding bij een fout.
errorCode	integer	Foutcode bij een 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.