UPN + ‘externe productcode’ waarbij het laatste met key/value

[alextreme]

Gebruikersverhaal

Als gemeentelijke ontwikkelaar
wil ik dat een ProductType een Uniforme Product Naam (UPN) en een of meerdere externe productcodes kan bevatten
zodat producten gestandaardiseerd en eenduidig kunnen worden gekoppeld aan de Uniforme Productnamen Lijst (UPL) van de VNG en aan externe systemen via specifieke codes.

---

Acceptatiecriteria

UPN-veld in ProductType

• Het datamodel van de ProductType-entiteit bevat een verplicht veld upn.
• De waarde van upn:
  • Moet overeenkomen met een productnaam uit de Uniforme Productnamen Lijst (UPL) van de VNG.
  • Wordt gevalideerd op basis van een beschikbare referentielijst met toegestane waarden.
• Bij foutieve invoer retourneert de API een duidelijke foutmelding in het Nederlands, zoals:
  • "De opgegeven UPN 'onbekend product' komt niet voor in de Uniforme Productnamen Lijst."

Externe productcodes

• Het datamodel van de ProductType-entiteit bevat een optioneel veld externe_productcodes, waarin een lijst van key/value paren kan worden opgeslagen.
• Elke externe productcode bevat:
  • key: De naam van het externe systeem of de context (bijv. "CBS", "ISO").
  • value: De bijbehorende code (bijv. "12345", "ISO-67890").
• Validatie:
  • Elke key moet uniek zijn binnen hetzelfde ProductType.
  • Zowel de key als de value mogen niet leeg zijn.
• Bij foutieve invoer retourneert de API foutmeldingen zoals:
  • "De sleutel 'CBS' is al in gebruik voor dit ProductType."
  • "De waarde van de externe productcode mag niet leeg zijn."

API-functionaliteit

• Bij het aanmaken of wijzigen van een ProductType kunnen de upn en externe_productcodes worden ingesteld, gewijzigd of verwijderd.
• Bij het opvragen van een ProductType retourneert de API:
  • De gekoppelde UPN.
  • De lijst van externe productcodes als key/value paren.
• Filtering op UPN en externe productcodes wordt ondersteund in de API (bijv. GET /producttypen?upn=Vergunning of GET /producttypen?externe_productcodes[CBS]=12345).

Documentatie

• De API-documentatie bevat voorbeelden van het instellen, bewerken en opvragen van de UPN en externe productcodes.
• Voorbeeld-API-aanvragen tonen hoe deze velden kunnen worden gebruikt in integraties en gemeentelijke toepassingen.

---

Definition of Done (DoD)

• Het veld upn en het optionele veld externe_productcodes zijn toegevoegd aan het ProductType-datamodel en geïmplementeerd in de API.
• Validatie en foutafhandeling voor UPN en externe productcodes zijn volledig geïmplementeerd.
• Filtering en querying op UPN en externe productcodes werken zoals beschreven en zijn getest.
• De API-documentatie is bijgewerkt met uitleg, voorbeelden, en validatieregels.