GIP upload¶

Concept

Deze API bestaat nog niet. Dit document is een concept-specificatie die wij ter afstemming aanleveren, zodat u uw dataformaat hierop 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 Upload een GIP-prijslijst (groothandel-inkoopprijzen) naar PharmaPortal.

Voor gebruikers van PharmaPortal is het mogelijk om via een API vanuit een eigen systeem een GIP-prijslijst te uploaden naar PharmaPortal. Dit is de API-variant van de "GIP toevoegen"-functie in PharmaPortal. Dit is een REST-API met één endpoint en één mogelijke actie.

Een GIP-prijs koppelt per artikel (Z-Index nummer) een prijs aan een groothandel voor een bepaalde maand. Eén upload betreft precies één groothandel en één maand, die u meegeeft via de headers x-portal-groothandel en x-portal-maand. De periode (ingangs- en einddatum) wordt door PharmaPortal uit die maand afgeleid; u zet dus geen datums in de regels. Een prijs geldt uitsluitend binnen de opgegeven maand: een maand zonder upload heeft geen GIP-prijs, er is geen automatische doorloop naar een volgende maand. Elke regel wordt uniek geïdentificeerd door de combinatie groothandel + maand + Z-Index binnen uw organisatie.

Toegang

Alleen beschikbaar voor licentiehouders van PharmaPortal.

Endpoint¶

TestProductie

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

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

Requests zijn POST-requests met de CSV-inhoud rechtstreeks als body (dus geen multipart-bestand of JSON). Het CSV-bestand bevat vier kolommen zonder kopregel. De groothandel en de maand geeft u éénmalig mee via de headers x-portal-groothandel en x-portal-maand; die staan dus niet in de regels. Zowel , als ; wordt als scheidingsteken herkend. De kolommen zijn, in volgorde:

#	Kolom	Omschrijving
1	`zindex_nummer`	Z-Index nummer (8 cijfers).
2	`soort`	`vast`, `percentage` of `afslag`.
3	`prijs`	Bij `vast`: de vaste prijs per verpakking (excl. btw). Bij `afslag`: het afslagbedrag t.o.v. AIP. Leeg bij `percentage`.
4	`percentage`	Bij `percentage`: kortingspercentage t.o.v. AIP (0–100). Leeg bij `vast`/`afslag`.

Bij afslag en percentage wordt de uiteindelijke prijs server-side berekend uit de AIP van het artikel (net als in de "GIP toevoegen"-functie).

Authenticatie¶

Deze API maakt gebruik van (identiek aan de overige PharmaPortal API's):

IP-whitelisting voor beveiliging
Een API-key voor authenticatie & rate-limiting
HMAC voor integriteitscontrole (verplicht bij POST)

De API-key bepaalt namens welke PharmaPortal-organisatie de GIP-lijst wordt weggeschreven (de portal_klant in de unieke sleutel). U hoeft dit niet mee te sturen.

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.
`x-portal-groothandel`	PI-code van de groothandel waarvoor deze upload geldt (verplicht). Eén upload betreft één groothandel. De waarde moet een bekende, actieve groothandel zijn.
`x-portal-maand`	De maand waarvoor de prijzen gelden, formaat `YYYYMM` (bijv. `202607` voor juli 2026) — verplicht. Hieruit worden de ingangs- en einddatum van alle regels afgeleid.
`x-portal-on-exist`	Bepaalt wat er gebeurt bij een reeds bestaande regel met dezelfde sleutel. Kan `error` (standaard), `overwrite` of `skip` bevatten. Zie Botsingen hieronder.
`content-type`	`text/csv`

Request¶

curl -X POST https://demo.pharma-portal.nl/api/gip/upload \
  -H "x-portal-key: <uw-api-key>" \
  -H "x-portal-hmac: <sha-512-hmac>" \
  -H "x-portal-groothandel: 671234" \
  -H "x-portal-maand: 202607" \
  -H "x-portal-on-exist: error" \
  -H "content-type: text/csv" \
  --data-binary @gip.csv

De voorbeelden hieronder gaan uit van de headers x-portal-groothandel: 671234 en x-portal-maand: 202607 (juli 2026). De prijzen gelden dus voor die groothandel en die maand.

1. Eenvoudige lijst met vaste prijzen — de meest voorkomende upload: per artikel één vaste prijs (excl. btw) voor de opgegeven maand.

12345678;vast;100.01;
34567890;vast;14.31;
56789012;vast;53.23;
78901234;vast;782.21;

2. Gemengde soorten — vaste prijs, kortingspercentage t.o.v. AIP en een afslagbedrag t.o.v. AIP door elkaar. Let op de lege kolommen (prijs leeg bij percentage, percentage leeg bij vast/afslag).

12345678;vast;100.01;
34567890;percentage;;12.5
56789012;afslag;5.00;

3. Komma als scheidingsteken — ook toegestaan (in plaats van ;).

12345678,vast,100.01,

Botsingen (x-portal-on-exist)¶

Een regel bestaat al wanneer er voor deze groothandel + maand + zindex_nummer (binnen uw organisatie) al een GIP-prijs in PharmaPortal aanwezig is. Het gedrag wordt bepaald door de header x-portal-on-exist:

Waarde	Gedrag
`error` (standaard)	De botsende regel wordt niet geïmporteerd en verschijnt in `errors`.
`overwrite`	De bestaande regel wordt bijgewerkt met de aangeleverde prijsgegevens.
`skip`	De bestaande regel blijft ongewijzigd; de aangeleverde regel wordt overgeslagen (telt als warning).

Regels die niet botsen worden altijd toegevoegd. Deze API verwijdert nooit regels die niet in de upload voorkomen — het is een upsert per regel, geen volledige vervanging van uw GIP-lijst.

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": 4,
    "numRowsImported": 2,
    "numRowsError": 1,
    "numRowsWarning": 1,
    "warnings": [
      { "line": 2, "message": "Regel overgeslagen: bestaat al (skip)." }
    ],
    "errors": [
      { "line": 4, "message": "Onbekend Z-Index nummer: 14321976" }
    ]
  }
}

Voorbeeld van een response bij een verwerkings-/verzoekfout:

{
  "result": "error",
  "errorMessage": "Ongeldige waarde voor x-portal-on-exist. Toegestaan: error, overwrite, skip"
}

Velden¶

Veld	Type	Omschrijving
`result`	string	`success` of `error`.
`data.numRowsTotal`	integer	Aantal aangeleverde regels.
`data.numRowsImported`	integer	Aantal succesvol verwerkte regels.
`data.numRowsError`	integer	Aantal regels met een fout (niet geïmporteerd).
`data.numRowsWarning`	integer	Aantal regels met een waarschuwing (bv. overgeslagen).
`data.warnings`	object[]	Waarschuwingen per regel (`line`, `message`).
`data.errors`	object[]	Fouten per regel (`line`, `message`).

Aandachtspunten

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

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 met ons op via info@zagis.nl. Wij zetten dan testdata voor u klaar en voorzien u van een API-key.