MAGDA Werk

Inleiding

Diensten die arbeidsgegevens, zoals informatie over loopbanen en werkrelaties, bevatten.

Use cases

• Loon- en arbeidstijdgegevens van een werknemer opvragen ter voorbereiding van een inkomenstoets bij een sociale aanvraag.

• Nagaan of een zelfstandige een actieve of afgesloten loopbaan heeft (bv. bij een aanvraag die rekening houdt met het zelfstandigenstatuut).

• De arbeidsrelaties van een aanvrager raadplegen (via DIMONA-aangiftes), bijvoorbeeld om een tewerkstellingsvoorwaarde te controleren.

• Nagaan of een aanvrager via interimcontracten tewerkgesteld is (of was), relevant voor premies die rekening houden met de aard van de tewerkstelling.

Setup

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

Specifieke applicatie eigenschappen

Geen.

Services en functies

Overzicht

giveDmfa

Gegevens opvragen met betrekking tot loon- en arbeidstijdgegevens voor een bepaalde persoon. giveDmfa gebruikt de standaard aansluitingsconfiguratie; geefDmfaVoorWerknemer laat je de hoedanigheid expliciet meegeven — beide spreken exact dezelfde onderliggende dienst aan en retourneren hetzelfde objecttype.

Workflow expressie 1

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

Valt terug op de standaard aansluitingsconfiguratie voor MAGDA.

Workflow expressie 2

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

Hoedanigheid expliciet meegeven.

Java-code 1

GeefDmfaVoorWerknemerResponse response = magda.giveDmfa(insz, uri, begin, end, dossierId);

Valt terug op de standaard aansluitingsconfiguratie voor MAGDA.

Java-code 2

GeefDmfaVoorWerknemerResponse response = magda.geefDmfaVoorWerknemer(insz, uri, hc, begin, end, dossierId);

Hoedanigheid expliciet meegeven.

Input

Magda-documentatie

Technische info GeefDmfaVoorWerknemer-03.00.

Output

Je krijgt een getypeerd GeefDmfaVoorWerknemerResponse-object terug met een lijst Attesten — elk Attest is een DMFA-kwartaalaangifte met betrekking tot de werknemer. Een attest bevat:

• Identificatie — nummer/versie van het attest, en de status (0 nieuw, 1 wijziging, 3 annulatie, 4 heractivatie);

• AangifteWerkgever — het kwartaal (Kwartaal), het RSZ-nummer en KBO-nummer van de werkgever, en de gegevens van de werknemer zelf (Werknemer/INSZ, naam), met daarbinnen de Werknemerslijn: Categorie (werkgeverscategorie), Kerngetal (type werknemer), de Periode van het kwartaal, en — het belangrijkste onderdeel — Tewerkstellingen, met de effectieve loon- en arbeidstijdgegevens per tewerkstelling.

• Anomalieën — eventuele fouten die de RSZ zelf al gesignaleerd heeft bij de aangifte (enkel bij de meest recente situatie van een attest).

Let op — paginering: als niet alle attesten in één antwoord passen, krijg je een VolgendAttest-nummer mee (en/of de informatiecode 40217, "het antwoord is partieel, een extra opvraging is noodzakelijk"). Je moet dan een vervolgvraag doen met dat volgnummer om de rest op te halen.

Belangrijke beperking: een aantal gedetailleerde blokken (verminderingen, bijdragen, sommige naamswijzigingen, aanvullende vergoedingen) zijn via deze Geef-dienst niet beschikbaar — die worden enkel ontsloten via de aparte PubliceerDmfaVoorWerknemer-dienst, na een aanvraag in batch.

Gepseudonimiseerd voorbeeld:

<Antwoord>
    <Referte>550e8400-e29b-41d4-a716-446655440000</Referte>
    <Inhoud>
        <Attesten>
            <Attest>
                <Identificatie>
                    <Nummer>1</Nummer>
                    <Versie>1</Versie>
                    <Status>
                        <Code>0</Code>
                        <Omschrijving>Nieuw</Omschrijving>
                    </Status>
                    <DatumCreatie>2024-04-15</DatumCreatie>
                </Identificatie>
                <AangifteWerkgever>
                    <Kwartaal>2024-1</Kwartaal>
                    <RSZNummer>1234567</RSZNummer>
                    <Ondernemingsnummer>0123456789</Ondernemingsnummer>
                    <Werknemer>
                        <INSZ>850102XXX45</INSZ>
                        <Werknemerslijn>
                            <Categorie>015</Categorie>
                            <Kerngetal>495</Kerngetal>
                            <Periode>
                                <Begin>2024-01-01</Begin>
                                <Einde>2024-03-31</Einde>
                            </Periode>
                            <!-- Tewerkstellingen bevat de eigenlijke loon-/arbeidstijdgegevens, zie apart Type DMFA Attest - Tewerkstelling -->
                        </Werknemerslijn>
                    </Werknemer>
                </AangifteWerkgever>
            </Attest>
        </Attesten>
    </Inhoud>
</Antwoord>

Error-handling

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

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
GeefDmfaVoorWerknemerResponse response = magda.giveDmfa(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) || "40003".equals(code)) {
        throw new BpmnError("MAGDA_DMFA_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 ("40080".equals(code)) {
        throw new BpmnError("MAGDA_ONGELDIG_KWARTAAL", uitzondering.getDiagnose());
    }
    if ("40217".equals(code)) {
        // Geen blokkerende fout: paginering, vervolgvraag nodig met VolgendAttest-nummer
        String volgnummer = response.getRepliek().getAntwoorden().getAntwoord().getInhoud().getVolgendAttest();
        // herhaal de aanvraag met dit volgnummer
    }
}

geefLoopbaanARZA

Vraag loopbaangegevens op voor een zelfstandige.

Workflow expressie

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

Java-code

GeefLoopbaanARZAResponse response = magda.geefLoopbaanARZA(ssin, uri, startDate, endDate, hoedanigheid);

Input

Magda-documentatie

Technische documentatie GeefLoopbaanARZA-02.01.

Output

Je krijgt een getypeerd GeefLoopbaanARZAResponse-object terug met Inhoud/Zelfstandige — enkel aanwezig als er effectief informatie gevonden werd voor de opgegeven zelfstandige. Dit bevat:

• INSZ — het rijksregisternummer van de zelfstandige;

• Ondernemingsnummer — het laatst gekende ondernemingsnummer (optioneel, kan ontbreken bij oudere dossiers). Belangrijke nuance: als dit veld ontbreekt terwijl er wel een actieve periode als zelfstandige teruggegeven wordt, gaat het om een vennootschap met rechtspersoonlijkheid, niet om een eenmanszaak;

• Aansluitingen — een lijst van aansluitingen, elk met:

  • SociaalVerzekeringsfonds (Code + Omschrijving + Ondernemingsnummer van het fonds);

  • Loopbanen — een lijst van Loopbaan-segmenten, elk met Bijdragereeks (type tewerkstelling, bv. "Hoofdberoep"), Periode (Begin/Einde), optioneel PeriodeGelijkgesteld (bv. bij ziekte), Beroep, Hoedanigheid (bv. "Activiteit in eigen naam" of "Meewerkende echtgenote") en DatumOndertekening.

Let op bij Code/Omschrijving-paren: enkel bij SociaalVerzekeringsfonds bepaalt MAGDA zelf de juiste omschrijving bij de code. Bij alle andere paren (Bijdragereeks, PeriodeGelijkgesteld, Beroep, Hoedanigheid) wordt de omschrijving rechtstreeks van de KSZ overgenomen, in de taal van je vraag indien beschikbaar — anders krijg je de eerst beschikbare taal, samen met foutcode 25002 als signaal dat de gevraagde taal niet gevonden werd.

Gepseudonimiseerd voorbeeld:

<Antwoord>
    <Referte>550e8400-e29b-41d4-a716-446655440000</Referte>
    <Inhoud>
        <Zelfstandige>
            <INSZ>850102XXX45</INSZ>
            <Ondernemingsnummer>0765432198</Ondernemingsnummer>
            <Aansluitingen>
                <Aansluiting>
                    <SociaalVerzekeringsfonds>
                        <Code>003</Code>
                        <Omschrijving Oorsprong="MAGDA" TaalCode="nl">S.V.M.B.</Omschrijving>
                        <Ondernemingsnummer>0409088689</Ondernemingsnummer>
                    </SociaalVerzekeringsfonds>
                    <Loopbanen>
                        <Loopbaan>
                            <Bijdragereeks>
                                <Code>100</Code>
                                <Omschrijving Oorsprong="KSZ">Hoofdberoep</Omschrijving>
                            </Bijdragereeks>
                            <Periode>
                                <Begin>2015-01-01</Begin>
                                <Einde>2023-12-31</Einde>
                            </Periode>
                            <Beroep>
                                <Code>307107</Code>
                                <Omschrijving Oorsprong="KSZ">Bakker</Omschrijving>
                            </Beroep>
                            <Hoedanigheid>
                                <Code>100</Code>
                                <Omschrijving Oorsprong="KSZ">Activiteit in eigen naam</Omschrijving>
                            </Hoedanigheid>
                            <DatumOndertekening>2015-01-05</DatumOndertekening>
                        </Loopbaan>
                    </Loopbanen>
                </Aansluiting>
            </Aansluitingen>
        </Zelfstandige>
    </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
GeefLoopbaanARZAResponse response = magda.geefLoopbaanARZA(ssin, uri, startDate, endDate, hoedanigheid);

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_LOOPBAAN_NIET_GEVONDEN", uitzondering.getDiagnose());
    }
    if ("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());
    }
    // 25002 is informatief (vertaalprobleem bij de bron) - niet blokkerend, wel te loggen
}

geefWerkrelaties

Zoek arbeidsrelaties op voor een persoon (DIMONA-aangifte).

Workflow expressie 1

${magda.geefWerkrelaties(String uri, String hoedanigheid, String insz, String startDate, String endDate, UUID referte)}

Enkel gewone contracten.

Workflow expressie 2

${magda.geefWerkrelatiesWithInterim(String uri, String hoedanigheid, String insz, String startDate, String endDate, UUID referte)}

Gewone contracten én interimcontracten.

Java-code 1

GeefWerkrelatiesResponse response = magda.geefWerkrelaties(uri, hoedanigheid, insz, startDate, endDate, referte);

Enkel gewone contracten.

Java-code 2

GeefWerkrelatiesResponse response = magda.geefWerkrelatiesWithInterim(uri, hoedanigheid, insz, startDate, endDate, referte);

Gewone contracten én interimcontracten.

Input

Magda-documentatie

Technische documentatie GeefWerkrelaties-02.00.

Output

Je krijgt een getypeerd GeefWerkrelatiesResponse-object terug met een lijst Contracten (max. 2000 per antwoord). Elk Contract bestaat uit vijf blokken:

• Relatie — identificatie van werkgever (RSZ- of KBO-nummer) en werknemer (INSZ, naam, voornaam, en IdentificatiePersoonGevalideerd: geeft aan of de identificatie via het INSZ correct verliep);

• Bron — of de gegevens uit de RSZ- of de DIBISS-gegevensbank komen;

• Aangifte — het DimonaNummer (unieke identificatie van het contract), de PeriodeTijdstip (Begin/Einde), het ParitairComite, optioneel AardWerknemer (bv. "STU" voor student), of het contract Geannuleerd is, en de DimonaActie (I = indienst, O = uitdienst, U = wijziging, C = annulatie, B = verwijdering);

• InterimOnderneming (optioneel) — bij een contract via een interimkantoor, de identificatie van de eigenlijke opdrachtgever;

• PlaatsTewerkstelling (optioneel) — enkel relevant voor studenten: het effectieve adres van tewerkstelling.

Belangrijk om te weten: als het aantal gevonden contracten te groot is, krijg je geen antwoord maar een foutmelding (30005, "te veel gegevens gevonden, verfijn de zoekcriteria") — er is geen automatische paginering zoals bij sommige andere diensten.

Gepseudonimiseerd voorbeeld:

<Antwoord>
    <Referte>550e8400-e29b-41d4-a716-446655440000</Referte>
    <Inhoud>
        <Contracten>
            <Contract>
                <Relatie>
                    <Werkgever>
                        <RSZNummer>0123456789</RSZNummer>
                    </Werkgever>
                    <Werknemer>
                        <INSZ>850102XXX45</INSZ>
                        <IdentificatiePersoonGevalideerd Beschrijving="Identificatie persoon OK">1</IdentificatiePersoonGevalideerd>
                        <Naam>Peeters</Naam>
                        <Voornaam>Anna</Voornaam>
                    </Werknemer>
                </Relatie>
                <Bron Beschrijving="Rijksdienst voor sociale zekerheid">RSZ</Bron>
                <Aangifte>
                    <DimonaNummer>7765432178</DimonaNummer>
                    <PeriodeTijdstip>
                        <Begin>
                            <Datum>2022-01-08</Datum>
                        </Begin>
                        <Einde>
                            <Datum>2024-02-28</Datum>
                        </Einde>
                    </PeriodeTijdstip>
                    <ParitairComite>124</ParitairComite>
                    <Geannuleerd>0</Geannuleerd>
                    <DimonaActie Beschrijving="Uitdienst">O</DimonaActie>
                </Aangifte>
            </Contract>
        </Contracten>
    </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
GeefWerkrelatiesResponse response = magda.geefWerkrelaties(uri, hoedanigheid, insz, startDate, endDate, referte);

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

for (UitzonderingType uitzondering : uitzonderingen) {
    String code = uitzondering.getIdentificatie();
    if ("30001".equals(code)) {
        throw new BpmnError("MAGDA_WERKRELATIES_NIET_GEVONDEN", uitzondering.getDiagnose());
    }
    if ("30005".equals(code)) {
        throw new BpmnError("MAGDA_TE_VEEL_RESULTATEN", uitzondering.getDiagnose());
    }
    if ("30002".equals(code) || "30003".equals(code) || "30004".equals(code)) {
        throw new BpmnError("MAGDA_INSZ_PROBLEEM", uitzondering.getDiagnose());
    }
    if ("20002".equals(code) || "20007".equals(code)) {
        throw new BpmnError("MAGDA_ONGELDIGE_IDENTIFICATIE", uitzondering.getDiagnose());
    }
    if ("40035".equals(code)) {
        throw new BpmnError("MAGDA_ONGELDIGE_CRITERIA", uitzondering.getDiagnose());
    }
}