Contracten upload¶

Concept

Deze specificatie is nog niet definitief. Deze API bestaat nog niet; dit document is een concept-specificatie die wij ter afstemming aanleveren zodat u uw dataformaat kunt voorbereiden. Endpoints, kolommen, headers en responses kunnen tijdens de implementatie nog wijzigen. Bouw geen productie-integratie op basis van dit document zonder afstemming met Pharma-Intelligence.

POST Lees (upload) contracten vanuit een eigen systeem in PharmaPortal.

Voor gebruikers van PharmaPortal is het mogelijk om via een API vanuit een eigen systeem contracten in te lezen (te uploaden) in PharmaPortal. Dit is de API-variant van de "Contract toevoegen"-uploadfunctie in PharmaPortal. Elk contract koppelt per artikel (Z-Index nummer) een prijsafspraak aan een klant (PI-code), geldig over een periode. Contracten worden weggeschreven onder uw organisatie. Dit is een REST-API met één endpoint en één mogelijke actie.

Toegang

Alleen beschikbaar voor licentiehouders van PharmaPortal.

Endpoint¶

TestProductie

POST https://demo.pharma-portal.nl/api/contracten/upload

POST https://www.pharma-portal.nl/api/contracten/upload

Zie ook Contracten op peildatum voor het uitlezen van actieve contracten.

Request body¶

Requests zijn POST-requests met de CSV-inhoud rechtstreeks als body (dus geen multipart-bestand of JSON). Het CSV-bestand bevat dertien kolommen zonder kopregel. Zowel , als ; wordt als scheidingsteken herkend. De kolommen zijn, in volgorde:

#	Kolom	Omschrijving
1	`pi_code`	PI-code van de klant waarvoor het contract geldt.
2	`zindex_nummer`	Z-Index nummer (8 cijfers).
3	`ingangs_datum`	Ingangsdatum, formaat `YYYY-MM-DD`.
4	`eind_datum`	Einddatum, formaat `YYYY-MM-DD`.
5	`soort`	`vast` of `percentage`.
6	`vaste_prijs`	Bij `vast`: de vaste prijs per verpakking (excl. btw). Leeg bij `percentage`.
7	`percentage`	Bij `percentage`: kortingspercentage t.o.v. AIP (0–100). Leeg bij `vast`.
8	`distributie`	`groothandel` of `direct`.
9	`herkomst`	Vrije tekst, herkomst van het contract.
10	`opmerking`	Vrije tekst (optioneel).
11	`volume_stuks`	Afgegeven jaarvolume in stuks (optioneel, standaard leeg/onbekend).
12	`toeslag`	Toeslagbedrag (optioneel).
13	`toeslag_omschrijving`	Omschrijving van de toeslag (optioneel).

Bij soort=percentage wordt de uiteindelijke prijs server-side berekend uit de AIP van het artikel (net als in de "Contract toevoegen"-uploadfunctie). Het type afslag wordt bij het inlezen van contracten niet ondersteund.

Voorbeelden¶

1. Minimale regels — alleen de verplichte velden ingevuld; optionele kolommen (opmerking, volume_stuks, toeslag, toeslag_omschrijving) blijven leeg maar de scheidingstekens blijven staan.

671234;12345678;2026-01-01;2026-12-31;vast;100.01;;direct;Inkooptraject 2026;;;;
671234;34567890;2026-01-01;2026-12-31;vast;14.31;;direct;Inkooptraject 2026;;;;

2. Vaste prijs én kortingspercentage door elkaar — bij percentage laat u vaste_prijs leeg en vult u percentage; de prijs wordt uit de AIP berekend.

671234;12345678;2026-01-01;2026-12-31;vast;100.01;;groothandel;Inkooptraject 2026;;1000;;
671234;34567890;2026-01-01;2026-12-31;percentage;;12.5;direct;Inkooptraject 2026;kortingsafspraak;500;;

3. Meerdere klanten in één upload — elke regel bepaalt via pi_code voor welke klant het contract geldt.

671234;12345678;2026-01-01;2026-12-31;vast;100.01;;groothandel;Inkooptraject 2026;;1000;;
671299;12345678;2026-01-01;2026-12-31;vast;98.75;;groothandel;Inkooptraject 2026;;750;;
680055;12345678;2026-01-01;2026-12-31;percentage;;10;direct;Inkooptraject 2026;;250;;

4. Met toeslag — een toeslagbedrag met omschrijving en een opgegeven jaarvolume.

671234;56789012;2026-01-01;2026-12-31;vast;53.23;;groothandel;Inkooptraject 2026;incl. koeltransport;2000;3.50;Koelvergoeding

Komma (,) is ook toegestaan als scheidingsteken in plaats van ;.

Authenticatie¶

Deze API maakt gebruik van (identiek aan de overige PharmaPortal API's): IP-whitelisting voor beveiliging, een API-key voor authenticatie & rate-limiting, en HMAC voor integriteitscontrole (verplicht bij POST). De API-key bepaalt namens welke PharmaPortal-organisatie de contracten worden weggeschreven. De klant per regel geeft u op via de kolom pi_code.

Header	Toelichting
`x-portal-key`	De aan uw organisatie uitgereikte API-key.
`x-portal-hmac`	Hexadecimaal geëncodeerde SHA-512 HMAC van het request body (de ruwe CSV), berekend met uw API-secret.
`content-type`	`text/csv`

Request¶

curl -X POST https://demo.pharma-portal.nl/api/contracten/upload \
  -H "x-portal-key: <uw-api-key>" \
  -H "x-portal-hmac: <sha-512-hmac>" \
  -H "content-type: text/csv" \
  --data-binary @contracten.csv

Response¶

Code	Betekenis
`200`	Bij een verwerkt request (ook wanneer individuele regels fouten bevatten).
`401`	Bij foutieve authenticatie, HMAC of IP.

Voorbeeld van een response bij een succesvol & correct request:

{
  "result": "success",
  "data": {
    "numRowsTotal": 2,
    "numRowsImported": 2,
    "numRowsError": 0,
    "errors": []
  }
}

Voorbeeld van een response met regelfouten:

{
  "result": "success",
  "data": {
    "numRowsTotal": 2,
    "numRowsImported": 1,
    "numRowsError": 1,
    "errors": [
      { "line": 2, "message": "Percentage moet tussen 0 en 100 liggen" }
    ]
  }
}

Voorbeeld van een response bij een verzoekfout:

{
  "result": "error",
  "errorMessage": "Niet genoeg velden op rij (3)"
}

Velden¶

Veld	Type	Omschrijving
`result`	string	`success` of `error`.
`data.numRowsTotal`	integer	Aantal aangeleverde regels.
`data.numRowsImported`	integer	Aantal succesvol aangemaakte contracten.
`data.numRowsError`	integer	Aantal regels met een fout (niet aangemaakt).
`data.errors`	object[]	Regelfouten, met `line` en `message`.
`errorMessage`	string	Alleen bij `result: error`: omschrijving van de verzoekfout.

Aandachtspunten

De HMAC dient over de exacte CSV-bytes van het request body berekend te worden.

Elk contract wordt weggeschreven met uw organisatie als eigenaar; leverancier_nummer blijft leeg (dit wordt alleen gevuld vanuit een afgeronde inkoopronde). Elke regel wordt als een afzonderlijk contract toegevoegd. Het opgegeven volume_stuks wordt als jaarvolume bij het contract vastgelegd.

Per upload geldt een maximale bestandsgrootte van 10 MB. Zeer grote lijsten kunt u opsplitsen in meerdere requests (richtlijn: maximaal ca. 50.000 regels per request).

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