Offerte¶

POST Stuur een offerte in naar ZAGIS.

Voor gebruikers van PharmaPortal is het mogelijk om via een API vanuit een eigen systeem offertes in te sturen naar ZAGIS. Deze Offerte API is een REST-API met één endpoint en één mogelijke actie.

Toegang

Beschikbaar voor gebruikers van PharmaPortal.

Endpoint¶

TestProductie

POST https://demo.zagis.nl/api/zagis/offerte

POST https://www.zagis.nl/api/zagis/offerte

Authenticatie¶

Deze API maakt gebruik van:

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

Header	Toelichting
`x-zagis-offerte-key`	De aan uw organisatie uitgereikte API-key.
`x-zagis-offerte-hmac`	Hexadecimaal geëncodeerde SHA-512 HMAC van de request body.

Request¶

Requests zijn POST-requests met een JSON-payload.

curl -X POST https://demo.zagis.nl/api/zagis/offerte \
  -H "x-zagis-offerte-key: <uw-api-key>" \
  -H "x-zagis-offerte-hmac: <hmac>" \
  -H "Content-Type: application/json" \
  -d @offerte.json

Voorbeeld van een payload:

{
  "offerteCode": "04eba051",            # Unieke offertecode die in de offerte-aanvraag vermeld staat
  "readOnly": true,                     # Bij true controleert ZAGIS de offerte wel maar slaat deze niet op
  "bijlage": {                          # Optioneel wanneer er een PDF bijlage wordt meegestuurd. Max 5MB
    "filename": "Begeleidend Schrijven.pdf", # Optioneel, standaard 'bijlage.pdf'
    "contents": "JVBERi0xLjMKJcTl8uXrp/Og0MTGCj(...)==" # BASE64 Encoded PDF
  },
  "antwoorden": [                       // Indien in offerteaanvraag vragen zijn opgenomen
    { // Algemene vraag
        "vraagId": "29b7cb44-d116-4878-8ce7-a94a756cd1fd",
        "antwoord": "Ja"
    },{ // Algemene vraag
        "vraagId": "29b7cb44-d116-4878-8ce7-a94a756dd1fd",
        "antwoord": "2025-01-01" // Datum type, altijd YYYY-MM-DD
    },{ // Product specifieke vraag, product 1
        "vraagId": "29b7cb44-d116-4878-8ce7-a94a756cd1fe",
        "zindexNummer": 16070666,
        "antwoord": "Optie 1"
    },{ // Product specifieke vraag, product 2
        "vraagId": "29b7cb44-d116-4878-8ce7-a94a756cd1fe",
        "zindexNummer": 16070667,
        "antwoord": "Optie 2"
    }
  ],
  "artikelen": [
    {
      "zindexNummer": 16070666,
      "opmerking": "Betreft nieuwe verpakking",  # Max 255 karakters
      "referentie": "offerte-groep-2018-0004",   # Max 255 karakters
      "barcodeOpKae": false,                      # Barcode op kleinste afgifte eenheid, boolean
      "vastOfPercentage": "vast",                 # "vast" of "percentage"
      "volume": 1000,                             # Afwijkend beschikbaar jaarvolume in stuks (counting-units). Optioneel, alleen gebruiken bij een afwijkend jaarvolume
      "toeslag": 1.23,                            # Alleen indien in offerteaanvraag is aangegeven dat toeslag geoffreerd mag worden, default 0
      "prijzen": [
        {
          "looptijdMaanden": 12,   # De toegestane looptijden zijn aangegeven in de offerte-aanvraag
          "route": "groothandel",  # "groothandel" of "direct"
          "prijs": 4200,           # als vastOfPercentage = vast, verplicht > 0
          "percentage": 0          # als vastOfPercentage = percentage, verplicht > 0
        },
        {
          "looptijdMaanden": 24,
          "route": "groothandel",
          "prijs": 4100,
          "percentage": 0
        },
        {
          "looptijdMaanden": 36,
          "route": "groothandel",
          "prijs": 4000,
          "percentage": 0
        }
      ]
    },
    {
      "zindexNummer": 15825663,
      "opmerking": "Relatieve korting tov AIP",
      "referentie": "offerte-groep-2018-0008",
      "barcodeOpKae": true,
      "vastOfPercentage": "percentage",
      "prijzen": [
        {
          "looptijdMaanden": 12,
          "route": "groothandel",
          "prijs": 0,
          "percentage": 5
        },
        {
          "looptijdMaanden": 24,
          "route": "groothandel",
          "prijs": 0,
          "percentage": 10
        },
        {
          "looptijdMaanden": 36,
          "route": "groothandel",
          "prijs": 0,
          "percentage": 15
        }
      ]
    },
    {
      "zindexNummer": 17010102,
      "opmerking": "Staffel",
      "referentie": "offerte-groep-2018-0009",
      "barcodeOpKae": true,
      "isStaffel": true,                // Alleen indien staffel is toegestaan door inkopende apotheken in dit traject
      "staffelPer": "verpakking",       // ['verpakking', 'verpakkingOpStof', 'patienten', 'starters', 'eenheden']
      "gemetenPer": "kalenderjaar",     // ['kalenderjaar', 'jaar', 'contractperiode', 'kwartaal']
      "verrekeningPer": "kalenderjaar", // ['kalenderjaar', 'jaar', 'contractperiode', 'kwartaal']
      "vastOfPercentage": "percentage",
      "staffels": [
        {
          "van": 1,
          "tot": 10,
          "prijzen": [
            {
              "looptijdMaanden": 36,
              "route": "groothandel",
              "prijs": 0,
              "percentage": 15
            }
          ]
        },{
          "van": 11,
          "tot": 99999999,
          "prijzen": [
            {
              "looptijdMaanden": 36,
              "route": "groothandel",
              "prijs": 0,
              "percentage": 25
            }
          ]
        }
      ]
    }
  ]
}

Response¶

Code	Betekenis
`200`	Correct request.
`400`	Gebrek aan payload.
`401`	Foutieve authenticatie of HMAC.
`409`	Inhoudelijke fout in het request (bijvoorbeeld ongeldig ZI-nummer).

Voorbeeld van een response bij een succesvol & correct request zonder bijlage:

{
  "result":         "success",
  "readOnly":       true,   # Overgenomen van veld readOnly van request
  "totalRows":      6,      # Totaal aantal combinaties van artikel & prijzen
  "uniqueProducts": 2,      # Totaal aantal verwerkte unieke ZI-nummers
  "bijlage": {
    "available": false,
    "correct": false,
    "filename": "bijlage.pdf"
  }
}

Voorbeeld van een response bij een succesvol & correct request met bijlage:

{
  "result":         "success",
  "readOnly":       true,   # Overgenomen van veld readOnly van request
  "totalRows":      6,      # Totaal aantal combinaties van artikel & prijzen
  "uniqueProducts": 2,      # Totaal aantal verwerkte unieke ZI-nummers
  "bijlage": {
    "available": true,
    "correct": true,
    "filename": "Begeleidend schrijven.pdf"
  }
}

Voorbeeld van een response bij een inhoudelijk foutief request:

{
  "result":  "error",
  "message": "Artikel met index 0 heeft een ongeldig ZI#: 160706669"
}

Velden¶

Veld	Type	Omschrijving
`result`	string	`success` of `error`.
`readOnly`	boolean	Overgenomen uit het `readOnly`-veld van het request.
`totalRows`	integer	Totaal aantal combinaties van artikel & prijzen.
`uniqueProducts`	integer	Totaal aantal verwerkte unieke ZI-nummers.
`bijlage`	object	Status van de bijlage (`available`, `correct`, `filename`).
`message`	string	Foutmelding bij `result` = `error`.

Aandachtspunten

Na het succesvol aanleveren van een offerte met de vlag readOnly op false wordt de offertecode ongeldig gemaakt in ZAGIS; u kunt maar één keer per offertecode een offerte indienen. Wilt u testen of uw offerte correct is, gebruik dan readOnly = true.

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 API-key, API-secret & offertecodes.