Prestaties upload¶

POST Upload een CSV-bestand met prestaties (declaratieregels van add-on geneesmiddelen) naar Pharma-Insights.

Voor instellingen die Pharma-Insights gebruiken is het mogelijk om vanuit het eigen systeem (ZIS, EPD, datawarehouse) de prestatiegegevens rechtstreeks aan te leveren. Dit is de API-variant van de handmatige prestatie-upload in Insights. Dit is een REST-API met één endpoint en één mogelijke actie.

Het bestand wordt na ontvangst gevalideerd en asynchroon verwerkt. De response bevat het resultaat van de validatie per regel; de verdere verwerking (omrekenen, start-stop, dashboards) volgt op de achtergrond en is zichtbaar in het overzicht van geüploade bestanden in Insights.

Toegang

Alleen beschikbaar voor instellingen met een Pharma-Insights-licentie. Vraag een API-key aan via vragen@pharma-insights.nl. Een testomgeving wordt niet standaard aangeboden; neem contact op als u die voor uw implementatie nodig heeft.

Endpoint¶

POST https://www.pharma-insights.nl/api/prestaties

Requests zijn POST-requests met de CSV-inhoud rechtstreeks als body (dus geen multipart-bestand of JSON). Andere HTTP-methoden worden geweigerd met 405.

Bestandsformaat¶

Geen kopregel. Een kopregel wordt als ongeldige regel gerapporteerd en overgeslagen.
Scheidingsteken: ; (aanbevolen), , of tab. Het teken dat in de eerste regel het vaakst voorkomt wordt gebruikt voor het hele bestand.
Tekstcodering UTF-8; een UTF-8 BOM is toegestaan.
Lege regels worden overgeslagen.
Gebruik in het hele bestand één datumnotatie. YYYY-MM-DD wordt aanbevolen.
Aantallen zijn standaard stuks (eenheden). Levert u verpakkingen of de HiX-inkoophoeveelheid aan, geef dat dan aan met de header x-aantallen-in (zie hieronder).

De kolommen zijn, in volgorde:

#	Kolom	Verplicht	Toelichting
1	`prestatie_id`	ja	Uniek nummer van de prestatie/declaratieregel. Alleen cijfers, maximaal 18 cijfers.
2	`patient_id`	ja	Gepseudonimiseerd patiëntnummer (tekst). Nooit een BSN of naam.
3	`indicatie_id`	ja	G-Standaard indicatie-id (bestand indicaties bij supplementaire producten).
4	`agb_code`	ja	AGB-code van het specialisme, bijv. `313` (Inwendige geneeskunde) of `324` (Reumatologie). Moet voorkomen in de NZa-zorgtypering.
5	`zindex_nummer`	ja	Z-Index nummer (8 cijfers) van een add-on artikel met declaratietitel.
6	`aantal_eenheden`	ja	Aantal in de eenheid van `x-aantallen-in` (standaard stuks), ongelijk aan 0. Decimaalteken `,` of `.`.
7	`uzovi_code`	ja	UZOVI-code van de zorgverzekeraar.
8	`uitvoerings_datum`	ja	Datum van toediening/verstrekking, `YYYY-MM-DD`. Mag niet in de toekomst liggen.
9	`zorgtypering_code`	ja	Zorgtyperingscomponent (NZa) die geldig is bij de opgegeven `agb_code`.
10	`opmerkingen`	nee	Vrije tekst.
11	`arts_code`	nee	Vrije tekst, bijv. AGB-code van de voorschrijver.
12	`postcode`	nee	Vier cijfers van de postcode van de patiënt, of leeg.
13	`muraliteit`	nee	`intramuraal` (standaard) of `extramuraal`.

Verplichte kolommen moeten altijd aanwezig zijn; optionele kolommen mogen weggelaten worden (dan bevat de regel 9 kolommen) of leeg blijven.

Authenticatie¶

De instelling wordt herkend aan de combinatie van twee headers. Er is geen HMAC en geen IP-whitelisting; bewaar de API-key daarom als geheim.

Header	Toelichting
`x-picode`	De PI-Code van uw instelling.
`x-apikey`	De aan uw instelling uitgereikte API-key.
`x-aantallen-in`	Optioneel. Eenheid van `aantal_eenheden`: `stuk` (standaard), `verpakking` of `inkoophoeveelheid`. Zie Eenheid van aantallen.
`content-type`	`text/csv`

Eenheid van aantallen (x-aantallen-in)¶

Insights rekent alle aantallen om naar verpakkingen. Met de header x-aantallen-in geeft u aan in welke eenheid uw bestand staat; de header geldt voor het hele bestand.

Waarde	Betekenis
`stuk` (standaard)	Aantal stuks (counting units), bijv. tabletten, flacons of spuiten. Wordt gedeeld door de verpakkingsinhoud uit de G-Standaard.
`verpakking`	Aantal verpakkingen. Geen omrekening.
`inkoophoeveelheid`	Inkoophoeveelheid zoals in een HiX-extract, waarbij de verpakkingsinhoud van sommige artikelen (bijv. drankjes in ml) anders is gedefinieerd. Wordt gedeeld door de inkoophoeveelheid uit de G-Standaard.

Een onbekende waarde levert een 400 op. De laatst gebruikte eenheid wordt onthouden en staat voorgeselecteerd bij de handmatige upload in Insights.

Request¶

curl -X POST https://www.pharma-insights.nl/api/prestaties \
  -H "x-picode: 871001" \
  -H "x-apikey: <uw-api-key>" \
  -H "x-aantallen-in: stuk" \
  -H "content-type: text/csv" \
  --data-binary @prestaties.csv

Voorbeeld van prestaties.csv met alleen de verplichte kolommen:

900000001;P-8f3a2c;1234;313;12118249;2;3311;2026-06-15;0
900000002;P-8f3a2c;1234;313;12118249;2;3311;2026-07-13;0
900000003;P-51be09;1234;324;15239876;1;7029;2026-07-14;0

Met optionele kolommen:

900000004;P-51be09;1234;324;15239876;1;7029;2026-08-11;0;;01012345;3511;intramuraal

Response¶

Code	Betekenis
`200`	Bestand ontvangen en in verwerking. `validation` bevat de afgekeurde regels (kan leeg zijn).
`400`	Lege body, ongeldige `x-aantallen-in`, of geen enkele geldige regel in het bestand.
`401`	`x-picode` of `x-apikey` ontbreekt, of hoort niet bij een actieve instelling.
`405`	Andere HTTP-methode dan POST.
`503`	De API is tijdelijk uitgeschakeld. Probeer het later opnieuw.

Alle foutresponses zijn JSON.

Voorbeeld van een response bij een verwerkt request waarin één regel is afgekeurd:

{
  "result": "success",
  "message": "Bestand succesvol ontvangen en in verwerking.",
  "validation": [
    {
      "columnIndex": 4,
      "columnNumber": 5,
      "value": 14321976,
      "message": "Nummer is geen geldig Z-Index nummer voor een add-on product. Het artikel dient een declaratietitel te hebben (gehad).",
      "rowNumber": 3,
      "rowIndex": 2
    }
  ]
}

Voorbeeld van een response wanneer geen enkele regel geldig is:

{
  "result": "error",
  "message": "Bestand bevat geen geldige rijen.",
  "validation": [
    {
      "columnIndex": 0,
      "columnNumber": 1,
      "value": "",
      "message": "Niet genoeg kolommen in de rij. Verwacht minimaal 9 kolommen. Gevonden: 3 kolommen.",
      "rowNumber": 1,
      "rowIndex": 0
    }
  ]
}

Voorbeeld van een response bij een authenticatiefout:

{
  "result": "error",
  "error": "Ongeldige of ontbrekende x-picode/x-apikey"
}

Velden¶

Veld	Type	Omschrijving
`result`	string	`success` of `error`.
`message`	string	Toelichting op het resultaat.
`error`	string	Foutmelding; alleen aanwezig bij fouten zonder regelvalidatie (lege body, authenticatie, 405, 503).
`validation`	object[]	Afgekeurde regels. Leeg wanneer alle regels geldig zijn.
`validation[].rowNumber`	integer	Regelnummer in het bestand (1-gebaseerd).
`validation[].rowIndex`	integer	Regelindex (0-gebaseerd).
`validation[].columnNumber`	integer	Kolomnummer (1-gebaseerd).
`validation[].columnIndex`	integer	Kolomindex (0-gebaseerd).
`validation[].value`	mixed	De aangeleverde waarde na normalisatie.
`validation[].message`	string	Reden van afkeuring.

Aandachtspunten

Controleer validation ook bij een 200. Afgekeurde regels worden niet verwerkt; de overige regels wel. Corrigeer de afgekeurde regels en lever ze opnieuw aan.

Controleer de eenheid van uw aantallen. Zonder x-aantallen-in worden de aantallen als stuks gelezen; een bestand in verpakkingen levert dan veel te lage aantallen op.

De verwerking gebeurt op de achtergrond. De status en het aantal verwerkte regels vindt u in Insights in het overzicht van geüploade bestanden.

Vragen over aansluiting, de API-key of het bestandsformaat: vragen@pharma-insights.nl.