MAGDA Sociale Zekerheid

Inleiding

Deze connector dekt een brede waaier aan sociale-zekerheidsgegevens (handicap, leefloon, werkloosheid, sociaal statuut) af.

Use cases

• Nagaan of een aanvrager een tegemoetkoming voor een handicap ontvangt, en het maandelijkse bedrag ervan, ter bepaling van een inkomensgerelateerd voordeel of premie.

• Het volledige dossier handicap van een aanvrager raadplegen (erkenningen, rechten) om de ondersteuningsbehoefte te kennen bij een sociale aanvraag.

• Nagaan of een aanvrager leefloon ontvangt, en voor welke periodes, relevant voor tegemoetkomingen die rekening houden met het bestaansminimum.

• Het bedrag van het leefloon opvragen voor een bepaald jaar, bijvoorbeeld ter berekening van een inkomensgerelateerde bijdrage.

• Nagaan of een aanvrager een vervangingsinkomen uit werkloosheid ontvangt, bijvoorbeeld voor een verminderd tarief, vrijstelling of prioriteit bij toewijzing.

• Het sociaal statuut van een aanvrager raadplegen (bv. verhoogde tegemoetkoming, OMNIO) ter bepaling van een sociaal tarief of een gereduceerde bijdrage.

Setup

Idem als bij alle MAGDA-connectoren. Zie MAGDA algemene setup.

Specifieke applicatie eigenschappen

Geen.

Services en functies

Overzicht

givefBetalingenHandicap

Vraag voor een persoon gegevens op omtrent uitbetalingen in kader van een handicap.

Workflow expressie 1

Variant waarbij je terugvalt op de default magda aansluitingsgegevens.

${magda.givefBetalingenHandicap(String insz, String startDate, String endDate, String dossierId)}

Workflow expressie 2

Variant waarbij de magda aansluitingsgegevens expliciet worden meegegeven.

${magda.givefBetalingenHandicap(String insz, String startDate, String endDate, String uri, String hoedanigheid, String dossierId)}

Java-code 1

GeefBetalingenHandicapResponse response = magda.givefBetalingenHandicap(insz, startDate, endDate, dossierId);

Variant waarbij je terugvalt op de default magda aansluitingsgegevens.

Java-code 2

GeefBetalingenHandicapResponse response = magda.givefBetalingenHandicap(insz, startDate, endDate, uri, hoedanigheid, dossierId);

Variant waarbij de magda aansluitingsgegevens expliciet worden meegegeven.

Input

Magda-documentatie

Technische documentatie GeefBetalingenHandicap-03.00.

Output

Je krijgt een getypeerd GeefBetalingenHandicapResponse-object terug met drie onderdelen: een algemene status, het opgevraagde ssin (met eventuele aanduiding of het INSZ geannuleerd of vervangen is), en results — vier afzonderlijke resultaatblokken (dgphResult, vsbResult, irisCareResult, niccinResult), elk met een eigen status en een lijst van payments (maandelijkse uitbetalingen, met jaar/maand, bedrag en een aanduiding of de betaling geschorst was).

Belangrijk: controleer de status van elk resultaatblok afzonderlijk — een globaal geslaagd antwoord (zonder Uitzondering) kan bij één of meerdere bronnen toch "geen gegevens gevonden" bevatten. vsbResult levert momenteel nog geen gegevens (voorzien voor toekomstig gebruik). Onze connector vraagt MDG niet op — een mdgResult-blok zal in de praktijk dus nooit gegevens bevatten via deze functie.

Is het opgegeven INSZ vervangen door een nieuw nummer, dan blokkeert de dienst en krijg je geen resultaten — het nieuwe INSZ staat in het replacedBy-attribuut van ssin, en je moet de vraag herhalen met dat nieuwe nummer. Is het INSZ enkel geannuleerd (niet vervangen), dan gaat de opvraging gewoon door.

Gepseudonimiseerd voorbeeld:

<ConsultPaymentsResponse>
    <status>
        <value>DATA_FOUND</value>
        <code>MSG00000</code>
    </status>
    <ssin>850102XXX45</ssin>
    <results>
        <dgphResult>
            <status>
                <value>DATA_FOUND</value>
                <code>MSG00000</code>
            </status>
            <payments>
                <payment>
                    <yearMonth>2025-01</yearMonth>
                    <amount>412.37</amount>
                    <cancelledPayment>0</cancelledPayment>
                </payment>
                <payment>
                    <yearMonth>2025-02</yearMonth>
                    <amount>412.37</amount>
                    <cancelledPayment>0</cancelledPayment>
                </payment>
            </payments>
        </dgphResult>
        <vsbResult>
            <status>
                <value>NO_DATA_FOUND</value>
                <code>MSG00100</code>
            </status>
            <!-- Momenteel altijd leeg: VSB levert nog geen betalingsgegevens -->
        </vsbResult>
        <irisCareResult>
            <status>
                <value>NO_DATA_FOUND</value>
                <code>MSG00021</code>
            </status>
        </irisCareResult>
        <niccinResult>
            <status>
                <value>NO_DATA_FOUND</value>
                <code>MSG00021</code>
            </status>
        </niccinResult>
    </results>
</ConsultPaymentsResponse>

Error-handling

Voor een compleet overzicht, kan je terecht op de MAGDA-foutcodepagina.

Klassieke MAGDA-uitzonderingen (Niveau 3, Type FOUT, Oorsprong MAGDA):

Categoriecodes (geven aan wat er van de bron zelf kwam):

Fouten kunnen hier op twee plaatsen voorkomen: als klassieke MAGDA-Uitzondering (bv. ongeldig INSZ), of als een statuscode binnen een specifiek resultaatblok (bv. MSG00021 bij irisCareResult) — deze laatste is geen uitzondering en vereist dus expliciete controle in je eigen code, ook als de aanroep zelf geslaagd is.

Bij sommige errors wil je het proces niet laten vastlopen. In dat geval vorm je de technische error (foutcode) om naar een BPMN-error en vang je deze op via een error boundary event.

// Voorbeeld: beide foutlagen controleren
GeefBetalingenHandicapResponse response = magda.givefBetalingenHandicap(insz, startDate, endDate, dossierId);

// Laag 1: klassieke MAGDA-uitzonderingen
List<UitzonderingType> uitzonderingen = response.getRepliek()
    .getAntwoorden().getAntwoord().getUitzonderingen().getUitzondering();

for (UitzonderingType uitzondering : uitzonderingen) {
    String code = uitzondering.getIdentificatie();
    if ("20002".equals(code)) {
        throw new BpmnError("MAGDA_ONGELDIG_INSZ", uitzondering.getDiagnose());
    }
    if ("20003".equals(code)) {
        throw new BpmnError("MAGDA_ONGELDIGE_PERIODE", uitzondering.getDiagnose());
    }
    if ("70002".equals(code) || "70003".equals(code)) {
        throw new BpmnError("MAGDA_BRON_FOUT", uitzondering.getDiagnose());
    }
}

// Laag 2: status per bron, binnen de inhoud van het antwoord (géén uitzondering!)
String dgphStatus = response.getResults().getDgphResult().getStatus().getCode();
if (!"MSG00000".equals(dgphStatus) && !"MSG00100".equals(dgphStatus) && !"MSG00021".equals(dgphStatus)) {
    // Onverwachte statuscode bij deze bron - nader onderzoeken, bv. loggen of BpmnError
    throw new BpmnError("MAGDA_DGPH_ONVERWACHTE_STATUS", "Statuscode: " + dgphStatus);
}

// SSIN-controle: is het opgegeven INSZ vervangen?
if (response.getSsin().getReplacedBy() != null) {
    throw new BpmnError("MAGDA_INSZ_VERVANGEN", "Nieuw INSZ: " + response.getSsin().getReplacedBy());
}

giveDossierHandicap

Zoek gegevens in het handicapdossier van een persoon.

Workflow expressie

${magda.giveDossierHandicap(String ssin, String date, String uri, String dossierId)}

Java-code 1

GeefDossierHandicapResponse response = magda.giveDossierHandicap(ssin, date, uri, dossierId);

Input

Magda-documentatie

Technische documentatie GeefDossierHandicap-03.00.

Output

Je krijgt een getypeerd GeefDossierHandicapResponse-object terug (ConsultFilesByDateResponse) met de erkenningen (handicapRecognitions) van het dossier handicap op de opgegeven referentiedatum, geraadpleegd bij zes bronnen: AVIQ, DGPH, DSL, IrisCare, NicCin en VSB (MDG wordt hier niet bevraagd).

Voor elke bevraagde bron krijg je een apart resultaatblok (dgphResult, aviqResult, dslResult, ...) met een eigen status. Het blok bevat, indien aanwezig, een handicapRecognition per geldige erkenning, met:

• recognitionStatus — de beslissingsdatum en de (open) geldigheidsperiode van de erkenning;

• legislation — de wetgeving waarbinnen de erkenning gebeurde;

• resultRecognitionChild — bij een erkenning voor een kind: score inzake zelfredzaamheid (oude wetgeving) of de pijlerscores (nieuwe wetgeving: pijler 1/2/3 en het totaal), relevant voor de bijkomende kinderbijslag of zorgtoeslag;

• resultRecognitionAdult — bij een erkenning voor een volwassene: scores op verminderde zelfredzaamheid (mobiliteit, voeding, hygiëne, huishouden, toezicht, sociale vaardigheden).

Let op: de detailstructuur van resultRecognitionChild/resultRecognitionAdult is enkel bevestigd voor dgphResult — de overige bronblokken kunnen een deel van deze velden missen (zie de matrix op de vraagpagina: niet elke bron levert elk detail).

Net als bij givefBetalingenHandicap kan het opgegeven ssin een @canceled- of @replacedBy-attribuut bevatten (zie Error-handling). Daarnaast bevat het antwoord een dataFilters-element met de XPath van elementen die weggefilterd werden omdat je organisatie daarvoor niet geautoriseerd is — dit geeft je expliciet zicht op wat er ontbrak, in plaats van dat je dit zelf moet afleiden.

Gepseudonimiseerd voorbeeld:

<ConsultFilesByDateResponse>
    <Status>
        <value>DATA_FOUND</value>
        <code>MSG00000</code>
    </Status>
    <ssin>850102XXX45</ssin>
    <dataFilters>
        <FilteredElement>results/dgphResult/file/resultRecognitionAdult</FilteredElement>
    </dataFilters>
    <results>
        <dgphResult>
            <status>
                <value>DATA_FOUND</value>
                <code>MSG00000</code>
            </status>
            <file>
                <handicapRecognitions>
                    <handicapRecognition>
                        <recognitionStatus>
                            <dateOfDecision>2022-03-14</dateOfDecision>
                            <startDateRecognition>2022-01-01</startDateRecognition>
                            <!-- endDateRecognition afwezig: erkenning van onbepaalde duur -->
                        </recognitionStatus>
                        <legislation>NIEUWE_WET</legislation>
                        <resultRecognitionChild>
                            <pillars>
                                <pillar1>3</pillar1>
                                <pillar2>4</pillar2>
                                <pillar3>2</pillar3>
                                <pillarsTotal>9</pillarsTotal>
                            </pillars>
                            <childPathology>0</childPathology>
                        </resultRecognitionChild>
                    </handicapRecognition>
                </handicapRecognitions>
            </file>
        </dgphResult>
    </results>
</ConsultFilesByDateResponse>

Error-handling

Voor een compleet overzicht, kan je terecht op de MAGDA-foutcodepagina.

Klassieke MAGDA-uitzonderingen (Niveau 3, Type FOUT, Oorsprong MAGDA):

Categoriecodes (geven aan wat er van de bron zelf kwam):

Fouten kunnen hier op twee plaatsen voorkomen: als klassieke MAGDA-Uitzondering (bv. ongeldig INSZ), of als een statuscode binnen een specifiek resultaatblok (bv. dgphResult/status) — deze laatste is geen uitzondering en vereist dus expliciete controle in je eigen code, ook als de aanroep zelf geslaagd is.

Bij sommige errors wil je het proces niet laten vastlopen. In dat geval vorm je de technische error (foutcode) om naar een BPMN-error en vang je deze op via een error boundary event.

// Voorbeeld: beide foutlagen controleren
GeefDossierHandicapResponse response = magda.giveDossierHandicap(ssin, date, uri, dossierId);

// Laag 1: klassieke MAGDA-uitzonderingen
List<UitzonderingType> uitzonderingen = response.getRepliek()
    .getAntwoorden().getAntwoord().getUitzonderingen().getUitzondering();

for (UitzonderingType uitzondering : uitzonderingen) {
    String code = uitzondering.getIdentificatie();
    if ("20002".equals(code)) {
        throw new BpmnError("MAGDA_ONGELDIG_INSZ", uitzondering.getDiagnose());
    }
    if ("40223".equals(code)) {
        // Geen blokkerende fout, wel relevant om te loggen: resultaten mogelijk onvolledig
        LOGGER.warn("MAGDA: lijst van elementen werd ingekort voor dossierId {}", dossierId);
    }
    if ("70002".equals(code) || "70003".equals(code)) {
        throw new BpmnError("MAGDA_BRON_FOUT", uitzondering.getDiagnose());
    }
}

// Laag 2: status per bron, binnen de inhoud van het antwoord (géén uitzondering!)
String dgphStatus = response.getResults().getDgphResult().getStatus().getCode();
if (!"MSG00000".equals(dgphStatus) && !"MSG00100".equals(dgphStatus) && !"MSG00021".equals(dgphStatus)) {
    throw new BpmnError("MAGDA_DGPH_ONVERWACHTE_STATUS", "Statuscode: " + dgphStatus);
}

// SSIN-controle: is het opgegeven INSZ vervangen?
if (response.getSsin().getReplacedBy() != null) {
    throw new BpmnError("MAGDA_INSZ_VERVANGEN", "Nieuw INSZ: " + response.getSsin().getReplacedBy());
}

giveDossierHandicapByPeriod

Zoek gegevens in het handicapdossier van een persoon (voor een specifieke periode).

Workflow expressie

${magda.giveDossierHandicapByPeriod(String ssin, String beginDate, String endDate, String uri, String hoedanigheid, String dossierId)}

Java-code 1

GeefDossierHandicapResponse response = magda.giveDossierHandicapByPeriod(ssin, beginDate, endDate, uri, hoedanigheid, dossierId);

Input

Magda-documentatie

Technische documentatie GeefDossierHandicap-03.00.

Output

Je krijgt een getypeerd GeefDossierHandicapResponse-object terug (ConsultFilesByPeriodResponse) met de rechten (rights) op een tegemoetkoming binnen de opgegeven periode, geraadpleegd bij DGPH (de andere bronnen worden door onze connector niet bevraagd voor deze functie).

Voor elk recht (rights) krijg je:

• period/beginDate en period/endDate — de geldigheidsperiode van het recht (endDate blijft leeg voor een lopend recht);

• legislation — de toegepaste wetgeving (bv. code 3 = IVT/IT, code 4 = THAB, code 6 = Parkeerkaart);

• totalMonthAmount — het geïndexeerde totale maandbedrag (som van IVT en IT);

• monthAmount — het deel daarvan dat integratietegemoetkoming (IT) is — het IVT-deel bereken je zelf als totalMonthAmount − monthAmount;

• categoryIVT (A/B/C, afhankelijk van de gezinstoestand) en categoryIT (1 tot 5, afhankelijk van de zelfredzaamheidsscore);

• partnerIncome — geeft aan of het inkomen van de partner (deels) vrijgesteld is bij de berekening;

• decisionStatus — de aard van de beslissing (bv. POSITIVE, of een van de NEGATIVE_*-redenen zoals NEGATIVE_TOO_MUCH_INCOME).

Let op: een persoon kan een erkende handicap hebben zonder dat dit een recht op een tegemoetkoming opent — rights kan dus leeg zijn, ook al bevat handicapRecognitions (bij een andere functie) wel gegevens.

Gepseudonimiseerd voorbeeld:

<ConsultFilesByPeriodResponse>
    <Status>
        <value>DATA_FOUND</value>
        <code>MSG00000</code>
    </Status>
    <ssin>850102XXX45</ssin>
    <results>
        <dgphResult>
            <status>
                <value>DATA_FOUND</value>
                <code>MSG00000</code>
            </status>
            <file>
                <rights>
                    <period>
                        <beginDate>2023-01-01</beginDate>
                        <!-- endDate afwezig: lopend recht -->
                    </period>
                    <legislation>3</legislation>
                    <totalMonthAmount>612.45</totalMonthAmount>
                    <monthAmount>241.18</monthAmount>
                    <categoryIVT>B</categoryIVT>
                    <categoryIT>3</categoryIT>
                    <partnerIncome>0</partnerIncome>
                    <decisionStatus>POSITIVE</decisionStatus>
                </rights>
            </file>
        </dgphResult>
    </results>
</ConsultFilesByPeriodResponse>

Error-handling

Voor een compleet overzicht, kan je terecht op de MAGDA-foutcodepagina.

Klassieke MAGDA-uitzonderingen (Niveau 3, Type FOUT, Oorsprong MAGDA):

Categoriecodes:

Fouten kunnen hier op twee plaatsen voorkomen: als klassieke MAGDA-Uitzondering (bv. ongeldige periode), of als een statuscode binnen het dgphResult-resultaatblok — deze laatste is geen uitzondering en vereist dus expliciete controle in je eigen code, ook als de aanroep zelf geslaagd is.

Bij sommige errors wil je het proces niet laten vastlopen. In dat geval vorm je de technische error (foutcode) om naar een BPMN-error en vang je deze op via een error boundary event.

// Voorbeeld: beide foutlagen controleren
GeefDossierHandicapResponse response = magda.giveDossierHandicapByPeriod(ssin, beginDate, endDate, uri, hoedanigheid, dossierId);

// Laag 1: klassieke MAGDA-uitzonderingen
List<UitzonderingType> uitzonderingen = response.getRepliek()
    .getAntwoorden().getAntwoord().getUitzonderingen().getUitzondering();

for (UitzonderingType uitzondering : uitzonderingen) {
    String code = uitzondering.getIdentificatie();
    if ("20002".equals(code)) {
        throw new BpmnError("MAGDA_ONGELDIG_INSZ", uitzondering.getDiagnose());
    }
    if ("20003".equals(code)) {
        throw new BpmnError("MAGDA_ONGELDIGE_PERIODE", uitzondering.getDiagnose());
    }
    if ("70002".equals(code) || "70003".equals(code)) {
        throw new BpmnError("MAGDA_BRON_FOUT", uitzondering.getDiagnose());
    }
}

// Laag 2: status binnen het dgphResult-blok (géén uitzondering!)
String dgphStatus = response.getResults().getDgphResult().getStatus().getCode();
if (!"MSG00000".equals(dgphStatus) && !"MSG00100".equals(dgphStatus) && !"MSG00021".equals(dgphStatus)) {
    throw new BpmnError("MAGDA_DGPH_ONVERWACHTE_STATUS", "Statuscode: " + dgphStatus);
}

// SSIN-controle: is het opgegeven INSZ vervangen?
if (response.getSsin().getReplacedBy() != null) {
    throw new BpmnError("MAGDA_INSZ_VERVANGEN", "Nieuw INSZ: " + response.getSsin().getReplacedBy());
}

giveDossierHandicapWithHc

Zoek gegevens in het handicapdossier van een persoon en filter op handicapcode of categorie.

Workflow expressie

${magda.giveDossierHandicapWithHc(String ssin, String date, String uri, String hc, String dossierId)}

Java-code 1

GeefDossierHandicapResponse response = magda.giveDossierHandicapWithHc(ssin, date, uri, hoedanigheid, dossierId);

Input

Magda-documentatie

Technische documentatie GeefDossierHandicap-03.00.

Output

Je krijgt een getypeerd GeefDossierHandicapResponse-object terug (ConsultFilesByDateResponse) met de sociale kaarten (socialCards) die geldig zijn op de opgegeven referentiedatum, geraadpleegd bij dezelfde zes bronnen als giveDossierHandicap (AVIQ, DGPH, DSL, IrisCare, NicCin, VSB — geen MDG).

Voor elke geldige kaart (socialCard) krijg je:

• deliveryDate — de datum waarop de kaart werd afgeleverd;

• endDate — de datum waarop het recht op de kaart eindigt (een indicatie voor wanneer een hernieuwing kan worden aangevraagd);

• cardNumber — het unieke kaartnummer;

• cardCategory — het type kaart: 0 = verminderingskaart, 1 = parkeerkaart.

Let op: in tegenstelling tot handicapRecognitions en rights geeft de officiële MAGDA-matrix van bron/onderdeel-combinaties niet expliciet aan welke van de zes bronnen effectief sociale kaarten kunnen leveren — vermoedelijk is dit vooral bij DGPH relevant (de historische uitreiker van deze kaarten), maar dat is niet met zekerheid bevestigd voor de andere bronnen.

Gepseudonimiseerd voorbeeld:

<ConsultFilesByDateResponse>
    <Status>
        <value>DATA_FOUND</value>
        <code>MSG00000</code>
    </Status>
    <ssin>850102XXX45</ssin>
    <results>
        <dgphResult>
            <status>
                <value>DATA_FOUND</value>
                <code>MSG00000</code>
            </status>
            <file>
                <socialCards>
                    <socialCard>
                        <deliveryDate>2022-06-01</deliveryDate>
                        <endDate>2027-06-01</endDate>
                        <cardNumber>4837291056</cardNumber>
                        <cardCategory>1</cardCategory>
                    </socialCard>
                </socialCards>
            </file>
        </dgphResult>
    </results>
</ConsultFilesByDateResponse>

Error-handling

Voor een compleet overzicht, kan je terecht op de MAGDA-foutcodepagina.

Twee foutlagen, zoals bij de andere twee giveDossierHandicap*-functies (klassieke uitzondering vs. statuscode binnen dgphResult).

Bij sommige errors wil je het proces niet laten vastlopen. In dat geval vorm je de technische error (foutcode) om naar een BPMN-error en vang je deze op via een error boundary event.

// Voorbeeld: beide foutlagen controleren
GeefDossierHandicapResponse response = magda.giveDossierHandicapWithHc(ssin, date, uri, hoedanigheid, dossierId);

List<UitzonderingType> uitzonderingen = response.getRepliek()
    .getAntwoorden().getAntwoord().getUitzonderingen().getUitzondering();

for (UitzonderingType uitzondering : uitzonderingen) {
    String code = uitzondering.getIdentificatie();
    if ("20002".equals(code)) {
        throw new BpmnError("MAGDA_ONGELDIG_INSZ", uitzondering.getDiagnose());
    }
    if ("70002".equals(code) || "70003".equals(code)) {
        throw new BpmnError("MAGDA_BRON_FOUT", uitzondering.getDiagnose());
    }
}

String dgphStatus = response.getResults().getDgphResult().getStatus().getCode();
if (!"MSG00000".equals(dgphStatus) && !"MSG00100".equals(dgphStatus) && !"MSG00021".equals(dgphStatus)) {
    throw new BpmnError("MAGDA_DGPH_ONVERWACHTE_STATUS", "Statuscode: " + dgphStatus);
}

if (response.getSsin().getReplacedBy() != null) {
    throw new BpmnError("MAGDA_INSZ_VERVANGEN", "Nieuw INSZ: " + response.getSsin().getReplacedBy());
}

giveHandicap

Vraag de handicapstatus op voor een bepaalde persoon.

Workflow expressie 1

Variant waarbij je terugvalt op de default magda aansluitingsgegevens.

${magda.giveHandicap(String insz, String date, String begin, String end, String dossierId)}

Workflow expressie 2

Variant waarbij de magda aansluitingsgegevens expliciet worden meegegeven.

${magda.giveHandicap(String insz, String date, String begin, String end, String uri, String hoedanigheid, String dossierId)}

Java-code 1

Variant waarbij je terugvalt op de default magda aansluitingsgegevens.

GeefHandicapResponse response = magda.giveHandicap(insz, date, begin, end, dossierId);

Java-code 2

Variant waarbij de magda aansluitingsgegevens expliciet worden meegegeven.

GeefHandicapResponse response = magda.giveHandicap(insz, date, begin, end, uri, hoedanigheid, dossierId);

Input

Output

Je krijgt een getypeerd GeefHandicapResponse-object terug. Onze connector vraagt hierbij steeds alle vier informatieblokken tegelijk op: medische erkenning, rechten, sociale kaarten én de status van de aanvraag — in tegenstelling tot de nieuwere functies, waar je per aanroep maar één specifiek onderdeel krijgt.

Error-handling

Foutafhandeling verloopt volgens het gebruikelijke MAGDA-patroon (Uitzonderingen op het antwoord, om te zetten naar een BPMN-error). Voor de exacte, dienst-specifieke foutcodes is momenteel geen documentatie beschikbaar; raadpleeg bij twijfel de MAGDA Service Desk.

giveLeefloonbedragen

Deze functie geeft de bedragen van het leefloon (jaarlijks en per maand), niet de periodes waarin het werd ontvangen — gebruik hiervoor giveLivingWagePeriods.

Workflow expressie 1

Variant waarbij je terugvalt op de default magda aansluitingsgegevens.

${magda.giveLeefloonbedragen(String insz, String year, String numberOfYearsBack, String dossierId)}

Workflow expressie 2

Variant waarbij de magda aansluitingsgegevens expliciet worden meegegeven.

${magda.giveLeefloonbedragen(String insz, String year, String numberOfYearsBack, String uri, String hoedanigheid, String dossierId)}

Java-code 1

Variant waarbij je terugvalt op de default magda aansluitingsgegevens.

GeefLeefloonbedragenResponse response = magda.giveLeefloonbedragen(insz, year, numberOfYearsBack, dossierId);

Java-code 2

Variant waarbij de magda aansluitingsgegevens expliciet worden meegegeven.

GeefLeefloonbedragenResponse response = magda.giveLeefloonbedragen(insz, year, numberOfYearsBack, uri, hoedanigheid, dossierId);

Input

Magda-documentatie

Technische documentatie GeefLeefLoonBedragen-02.00.

Output

Je krijgt een getypeerd GeefLeefloonbedragenResponse-object terug (Antwoorden/Antwoord, net als de andere SocZek-diensten) met een Tegemoetkoming-element, opgebouwd uit twee delen:

• Jaarlijks — de jaartotalen voor het opgevraagde jaar (en eventuele voorgaande jaren, via numberOfYearsBack): Leefloon, EquivalentLeefloon en Kinderbijslag, elk met een bedrag, een aanduiding of er een tweede gerechtigde was, het aantal maanden zonder toelage, en of het maximumbedrag werd toegekend.

• Maandelijks — per maand (Maand/@JaarMaand, formaat JJJJ-MM) een detailoverzicht via LeefloonPerPeriode, EquivalentLeefloonPerPeriode en KinderbijslagPerPeriode. Elk van die drie bevat een lijst van periodes met een bedrag, de begunstigde (INSZ), eventueel een partner (INSZ of een TweedeGerechtigde-vlag — nooit beide), en het OCMW dat de uitbetaling deed (ondernemingsnummer, bestandsnaam).

Let op: @LaatsteUitbetaling op periode-niveau geeft aan of dit de laatst uitbetaalde periode is — nuttig om te weten of er nog een lopende/toekomstige periode te verwachten is.

Gepseudonimiseerd voorbeeld:

<Antwoorden>
    <Antwoord>
        <Referte>550e8400-e29b-41d4-a716-446655440000</Referte>
        <Inhoud>
            <Tegemoetkoming>
                <Jaarlijks Jaar="2024">
                    <Leefloon>
                        <Bedrag>8760.24</Bedrag>
                        <TweedeGerechtigde>0</TweedeGerechtigde>
                        <AantalMaandenZonderToelage>0</AantalMaandenZonderToelage>
                        <MaximumLeefloonGekregen>1</MaximumLeefloonGekregen>
                    </Leefloon>
                    <Kinderbijslag>
                        <Bedrag>1240.00</Bedrag>
                        <TweedeGerechtigde>0</TweedeGerechtigde>
                    </Kinderbijslag>
                </Jaarlijks>
                <Maandelijks>
                    <Maand JaarMaand="2024-06">
                        <LeefloonPerPeriode LaatsteUitbetaling="1">
                            <LeefloonPeriode ID="1">
                                <Bedrag>730.02</Bedrag>
                                <Periode>
                                    <Begin>2024-06-01</Begin>
                                    <Einde>2024-06-30</Einde>
                                </Periode>
                                <Begunstigde>
                                    <INSZ>850102XXX45</INSZ>
                                </Begunstigde>
                                <OCMW>
                                    <Ondernemingsnummer>0207437468</Ondernemingsnummer>
                                    <Bestand>LWA_202406</Bestand>
                                </OCMW>
                                <MaximumLeefloonGekregen>1</MaximumLeefloonGekregen>
                            </LeefloonPeriode>
                        </LeefloonPerPeriode>
                    </Maand>
                </Maandelijks>
            </Tegemoetkoming>
        </Inhoud>
    </Antwoord>
</Antwoorden>

Error-handling

Voor een compleet overzicht, kan je terecht op de MAGDA-foutcodepagina.

Aan deze functie gerelateerde foutcodes:

Bij sommige errors wil je het proces niet laten vastlopen. In dat geval vorm je de technische error (foutcode) om naar een BPMN-error en vang je deze op via een error boundary event.

// Voorbeeld: uitzondering opvangen en gooien als BpmnError
GeefLeefloonbedragenResponse response = magda.giveLeefloonbedragen(insz, year, numberOfYearsBack, uri, hoedanigheid, dossierId);

List<UitzonderingType> uitzonderingen = response.getRepliek()
    .getAntwoorden().getAntwoord().getUitzonderingen().getUitzondering();

for (UitzonderingType uitzondering : uitzonderingen) {
    String code = uitzondering.getIdentificatie();
    if ("30001".equals(code) || "40003".equals(code) || "40177".equals(code)) {
        throw new BpmnError("MAGDA_LEEFLOON_NIET_GEVONDEN", uitzondering.getDiagnose());
    }
    if ("30004".equals(code)) {
        throw new BpmnError("MAGDA_PERSOONSNUMMER_GEWIJZIGD", uitzondering.getDiagnose());
    }
    if ("20002".equals(code)) {
        throw new BpmnError("MAGDA_ONGELDIG_INSZ", uitzondering.getDiagnose());
    }
}

giveLivingWagePeriods

Deze functie geeft de periodes (en het uitreikende OCMW) waarin leefloon werd ontvangen, zonder bedragen — gebruik hiervoor giveLeefloonbedragen.

Workflow expressie 1

${magda.giveLivingWagePeriods(String ssin, String startDate, String endDate, String dossierId)}

Variant waarbij je terugvalt op de default magda aansluitingsgegevens.

Workflow expressie 2

${magda.giveLivingWagePeriodsWithUri(String ssin, String startDate, String endDate, String uri, String hoedanigheid, String dossierId)}

Variant met expliciete aansluitingsgegevens.

Java-code 1

GeefLeefloonperiodesResponse response = magda.giveLivingWagePeriods(ssin, startDate, endDate, dossierId);

Variant waarbij je terugvalt op de default magda aansluitingsgegevens.

Java-code 2

GeefLeefloonperiodesResponse response = magda.giveLivingWagePeriodsWithUri(ssin, startDate, endDate, uri, hoedanigheid, dossierId);

Variant met expliciete aansluitingsgegevens.

Input

Magda-documentatie

Technische documentatie GeefLeefLoonPeriodes-02.00.

Output

Je krijgt een getypeerd GeefLeefloonperiodesResponse-object terug met een Leefloonperiodes-element (met @DatumBegin/@DatumEinde als bevestiging van de opgegeven periode) en daarbinnen een lijst van Leefloonperiode-elementen. Elke periode bevat het INSZ, optioneel het OCMW dat het leefloon heeft uitgereikt (ondernemingsnummer, met voorloopnul), de geldigheidsperiode (Periode/Begin–Periode/Einde) en de Categorie (LIVING_WAGE = gewoon leefloon, EQUIVALENT_LIVING_WAGE = equivalent leefloon).

Belangrijk: OCMW, Periode en Categorie zijn elk optioneel en komen enkel terug als jouw organisatie daarvoor gemachtigd is — niet elke afnemer mag bijvoorbeeld weten welk OCMW het leefloon heeft uitgereikt.

Het antwoord van KSZ bevat enkel periodes die minstens één dag overlappen met de opgegeven periode én met de periode waarin het INSZ bij KSZ/MAGDA geïntegreerd was. Let ook op: POD MI/SMALS houdt enkel attesten van de voorbije 5 jaar online beschikbaar.

Gepseudonimiseerd voorbeeld:

<Antwoord>
    <Referte>550e8400-e29b-41d4-a716-446655440000</Referte>
    <Inhoud>
        <Leefloonperiodes DatumBegin="2023-01-01" DatumEinde="2024-12-31">
            <Leefloonperiode>
                <INSZ>850102XXX45</INSZ>
                <OCMW>0765437865</OCMW>
                <Periode>
                    <Begin>2023-03-01</Begin>
                    <Einde>2023-09-30</Einde>
                </Periode>
                <Categorie>
                    <Code Beschrijving="Gewoon leefloon">LIVING_WAGE</Code>
                </Categorie>
            </Leefloonperiode>
        </Leefloonperiodes>
    </Inhoud>
</Antwoord>

Error-handling

Voor een compleet overzicht, kan je terecht op de MAGDA-foutcodepagina.

Aan deze functie gerelateerde foutcodes:

Bij sommige errors wil je het proces niet laten vastlopen. In dat geval vorm je de technische error (foutcode) om naar een BPMN-error en vang je deze op via een error boundary event.

// Voorbeeld: uitzondering opvangen en gooien als BpmnError
GeefLeefloonperiodesResponse response = magda.giveLivingWagePeriodsWithUri(ssin, startDate, endDate, uri, hoedanigheid, dossierId);

List<UitzonderingType> uitzonderingen = response.getRepliek()
    .getAntwoorden().getAntwoord().getUitzonderingen().getUitzondering();

for (UitzonderingType uitzondering : uitzonderingen) {
    String code = uitzondering.getIdentificatie();
    if ("30001".equals(code) || "40003".equals(code)) {
        throw new BpmnError("MAGDA_LEEFLOONPERIODES_NIET_GEVONDEN", uitzondering.getDiagnose());
    }
    if ("30002".equals(code) || "30003".equals(code) || "30004".equals(code)) {
        throw new BpmnError("MAGDA_INSZ_PROBLEEM", uitzondering.getDiagnose());
    }
    if ("20002".equals(code)) {
        throw new BpmnError("MAGDA_ONGELDIG_INSZ", uitzondering.getDiagnose());
    }
    if ("20003".equals(code) || "40004".equals(code)) {
        throw new BpmnError("MAGDA_ONGELDIGE_PERIODE", uitzondering.getDiagnose());
    }
}

giveReplacementIncome

Vraag gegevens vervangingsinkomen.

Workflow expressie

${magda.giveReplacementIncome(String insz, String uri, String begin, String end, String dossierId)}

Java-code

GeefVervangingsinkomenUitWerkloosheidResponse response = magda.giveReplacementIncome(insz, uri, begin, end, dossierId);

Input

Magda-documententatie

Technische documentatie GeefVervangingsInkomenUitWerkloosheid-02.01.

Output

Je krijgt een getypeerd GeefVervangingsinkomenUitWerkloosheidResponse-object terug. Onze connector vraagt hierbij steeds het blok UitbetaaldeSommen op (nooit Situatie of KwartaalActiveringsUitkering, al bestaan die als alternatieve opvraagmogelijkheden binnen de MAGDA-dienst), met alle uitkeringstypes (BeperkteUitkeringen staat vast op 0).

UitbetaaldeSommen bevat per maand (JaarMaand, formaat JJJJ-MM) een UitbetaaldeSom met:

• AantalUitkeringen — het aantal uitkeringen in die maand (kan een halve dag zijn, bv. 22.5);

• UitbetaaldBedrag — het brutobedrag dat de uitbetalingsinstelling heeft ingediend bij de RVA;

• GoedgekeurdBedrag — het door de RVA goedgekeurde bedrag (enkel aanwezig bij StatusDossier/Code 1 of 2);

• StatusDossier — 1 = definitief goedgekeurd, 2 = voorlopig goedgekeurd (procedure loopt nog), 3 = procedure nog niet gestart (geen bedrag beschikbaar).

Let op: bij StatusDossier = 3 is er dus nog geen bedrag gekend — dat is geen fout, gewoon een lopend dossier. Je periode kan maximaal 48 maanden bevatten, en de vroegste opvraagbare maand is 2008-01.

Gepseudonimiseerd voorbeeld:

<Antwoord>
    <Referte>550e8400-e29b-41d4-a716-446655440000</Referte>
    <Inhoud>
        <UitbetaaldeSommen>
            <UitbetaaldeSom>
                <JaarMaand>2024-06</JaarMaand>
                <AantalUitkeringen>22.5</AantalUitkeringen>
                <UitbetaaldBedrag>987.32</UitbetaaldBedrag>
                <GoedgekeurdBedrag>945.10</GoedgekeurdBedrag>
                <StatusDossier>
                    <Code>1</Code>
                    <Omschrijving>Definitief</Omschrijving>
                </StatusDossier>
            </UitbetaaldeSom>
            <UitbetaaldeSom>
                <JaarMaand>2024-07</JaarMaand>
                <AantalUitkeringen>20</AantalUitkeringen>
                <UitbetaaldBedrag>876.40</UitbetaaldBedrag>
                <StatusDossier>
                    <Code>3</Code>
                    <Omschrijving>Procedure nog niet aangevat</Omschrijving>
                </StatusDossier>
            </UitbetaaldeSom>
        </UitbetaaldeSommen>
    </Inhoud>
</Antwoord>

Error-handling

Voor een compleet overzicht, kan je terecht op de MAGDA-foutcodepagina.

Aan deze functie gerelateerde foutcodes:

Bij sommige errors wil je het proces niet laten vastlopen. In dat geval vorm je de technische error (foutcode) om naar een BPMN-error en vang je deze op via een error boundary event.

// Voorbeeld: uitzondering opvangen en gooien als BpmnError
GeefVervangingsinkomenUitWerkloosheidResponse response = magda.giveReplacementIncome(insz, uri, begin, end, dossierId);

List<UitzonderingType> uitzonderingen = response.getRepliek()
    .getAntwoorden().getAntwoord().getUitzonderingen().getUitzondering();

for (UitzonderingType uitzondering : uitzonderingen) {
    String code = uitzondering.getIdentificatie();
    if ("30001".equals(code) || "30003".equals(code) || "40067".equals(code)) {
        throw new BpmnError("MAGDA_VERVANGINGSINKOMEN_NIET_GEVONDEN", uitzondering.getDiagnose());
    }
    if ("30002".equals(code) || "40085".equals(code)) {
        throw new BpmnError("MAGDA_INSZ_PROBLEEM", uitzondering.getDiagnose());
    }
    if ("20001".equals(code)) {
        throw new BpmnError("MAGDA_ONGELDIG_INSZ", uitzondering.getDiagnose());
    }
}

giveSociaalStatuut

Check of een persoon voldoet aan bepaalde sociale statuten.

Workflow expressie 1

${magda.giveSociaalStatuut(String ssin, Map<String, String> socialeStatuten, String uri, String hoedanigheid, String dossierId)}

Controleer of een persoon voldoet aan één of meerdere sociale statuten (tot 8), elk op een specifieke datum.

Workflow expressie 2

${magda.giveSociaalStatuut(String ssin, Map<String, String> socialeStatuten, String locatie, String uri, String hoedanigheid, String dossierId)}

Zelfde als hierboven, maar met een bijkomende (afnemer-specifieke) locatiefilter.

Workflow expressie 3

${magda.giveSociaalStatuutWithPeriod(String ssin, String sociaalStatuut, String beginDatum, String eindDatum, String uri, String hoedanigheid, String dossierId)}

Controleer of een persoon voldeed aan één specifiek sociaal statuut over een volledige periode, in plaats van op één enkele datum.

Java-code 1

GeefSociaalStatuutResponse response = magda.giveSociaalStatuut(ssin, socialeStatuten, uri, hoedanigheid, dossierId);

Controleer of een persoon voldoet aan één of meerdere sociale statuten (tot 8), elk op een specifieke datum.

Java-code 2

GeefSociaalStatuutResponse response = magda.giveSociaalStatuut(ssin, socialeStatuten, locatie, uri, hoedanigheid, dossierId);

Zelfde als hierboven, maar met een bijkomende (afnemer-specifieke) locatiefilter.

Java-code 3

GeefSociaalStatuutResponse response = magda.giveSociaalStatuutWithPeriod(ssin, sociaalStatuut, beginDatum, eindDatum, uri, hoedanigheid, dossierId);

Controleer of een persoon voldeed aan één specifiek sociaal statuut over een volledige periode, in plaats van op één enkele datum.

Input

Magda-documentatie

Technische documentatie GeefSociaalStatuut-03.00.

Output

Je krijgt een getypeerd GeefSociaalStatuutResponse-object terug met Inhoud/Persoon: het opgevraagde INSZ en een lijst SocialeStatuten. Voor elk opgevraagd sociaal statuut (SociaalStatuut/Naam) krijg je:

• Resultaat — Code 0 (niet van toepassing) of 1 (van toepassing), met omschrijving;

• Periodes — de periode(s) waarin de persoon tot deze situatie behoorde (Begindatum/Einddatum);

• Details — bijkomende naam/waarde-parenmet extra informatie, indien van toepassing;

• Status — enkel gevuld bij een probleem met de gezinssamenstelling (code SSH00047).

Belangrijke kanttekening: de waarde van Naam (bv. "BIM_BVT_IN_FAMILY", "SMALL_PENSION") is geen vaste, universele lijst — deze acroniemen worden per afnemer bepaald door de KSZ tijdens het aansluitingsproces. Je kan dus niet zomaar elke gewenste naam invullen; welke statuten je mag/kan opvragen, ligt vast in jouw aansluitingsovereenkomst.

giveSociaalStatuut laat je tot 8 sociale statuten in één aanroep opvragen, elk met een eigen datum (of, via de zesparametervariant, een locatie-filter). giveSociaalStatuutWithPeriod vraagt telkens één sociaal statuut op, maar dan over een periode in plaats van een enkele datum.

Gepseudonimiseerd voorbeeld:

<Antwoord>
    <Referte>550e8400-e29b-41d4-a716-446655440000</Referte>
    <Inhoud>
        <Persoon>
            <INSZ>850102XXX45</INSZ>
            <SocialeStatuten>
                <SociaalStatuut>
                    <Naam>BIM_BVT_IN_FAMILY</Naam>
                    <Resultaat>
                        <Code>1</Code>
                        <Omschrijving>Van toepassing</Omschrijving>
                    </Resultaat>
                    <Periodes>
                        <Periode>
                            <Begindatum>2023-01-01</Begindatum>
                            <Einddatum>2024-12-31</Einddatum>
                        </Periode>
                    </Periodes>
                </SociaalStatuut>
            </SocialeStatuten>
        </Persoon>
    </Inhoud>
</Antwoord>

Error-handling

Voor een compleet overzicht, kan je terecht op de MAGDA-foutcodepagina.

Aan deze functie gerelateerde foutcodes:

Bij sommige errors wil je het proces niet laten vastlopen. In dat geval vorm je de technische error (foutcode) om naar een BPMN-error en vang je deze op via een error boundary event.

// Voorbeeld: uitzondering opvangen en gooien als BpmnError
GeefSociaalStatuutResponse response = magda.giveSociaalStatuut(ssin, socialeStatuten, uri, hoedanigheid, dossierId);

List<UitzonderingType> uitzonderingen = response.getRepliek()
    .getAntwoorden().getAntwoord().getUitzonderingen().getUitzondering();

for (UitzonderingType uitzondering : uitzonderingen) {
    String code = uitzondering.getIdentificatie();
    if ("30003".equals(code)) {
        throw new BpmnError("MAGDA_ONBESTAAND_INSZ", uitzondering.getDiagnose());
    }
    if ("30004".equals(code)) {
        // Annotaties bevatten "Oud INSZ" en "Nieuw INSZ"
        throw new BpmnError("MAGDA_INSZ_VERVANGEN", uitzondering.getDiagnose());
    }
    if ("40218".equals(code)) {
        // Annotatie bevat "Overlijdensdatum" - persoon niet meer bevragen
        throw new BpmnError("MAGDA_PERSOON_OVERLEDEN", uitzondering.getDiagnose());
    }
    if ("40214".equals(code) || "50000".equals(code)) {
        throw new BpmnError("MAGDA_ONGELDIGE_VRAAG", uitzondering.getDiagnose());
    }
    if ("20002".equals(code)) {
        throw new BpmnError("MAGDA_ONGELDIG_INSZ", uitzondering.getDiagnose());
    }
}