Externe applicatie (Inkoop API)
Visma | ProActive biedt de mogelijkheid voor leveranciers of andere externe partijen of pakketten om inkooporders in de Spend Cloud in te schieten middels een API.
Door de order informatie op een bepaalde manier aan te bieden, kunnen inkooporders worden aangemaakt of bijgewerkt in de Spend Cloud, waarbij er eventueel een ontvangstregistratie vanuit externe bron aangestuurd kan worden. Deze API is gemaakt voor orders die vanuit externe bron zijn aangemaakt, goedgekeurd/geautoriseerd en reeds zijn geplaatst bij de leverancier of in elk geval bekend zijn. De toegevoegde waarde van deze API wordt gerealiseerd doordat externe orders gematcht kunnen worden met inkoopfacturen in de Spend Cloud, met als voordeel dat facturen op basis van deze externe orders automatisch goedgekeurd kunnen worden.
Hierbij zijn er een aantal punten van belang:
- De externe order zal reeds bekend moeten zijn bij de leverancier, omdat wij de order niet nog een keer verzenden/e-mailen/aanbieden.
- De externe order zal de goedkeuring in de Spend Cloud overslaan, omdat:
- De goedkeuring in het externe inkooppakket moet plaatsvinden;
- Met een leverancier is afgesproken dat alleen de daadwerkelijk geleverde goederen (o.a. pakbon) of diensten (daadwerkelijk gewerkt aantal uur inhuur derden) als orders worden aangeboden via de API.
In het menuonderdeel Applicatiebeheer / Algemeen / 'Externe applicatie' kan een beveiligde token worden gegenereerd om vervolgens te gebruiken om orders aan te bieden via de API. Hierbij kun je kiezen om de 'Externe applicatie' orders te laten (1) toevoegen, (2) bijwerken en/of (3) ontvangsten door te geven. Het toevoegen van externe orders is daarbij het meest voorkomende.
Als je de 'Externe applicatie' voor één leverancier wilt gaan inzetten dan kun je de token beperken door optioneel een specifieke leverancier te selecteren. Alleen voor deze leverancier kunnen er dan externe orders worden aangestuurd via deze token. Eventueel kun je meerdere tokens aanmaken voor verschillende externe applicaties of leveranciers. Het is dus ook mogelijk om een 'Externe applicatie' aan te maken, zonder deze te koppelen aan een leverancier. In dat geval kan de token worden gebruikt om verschillende orders in te schieten en wordt aan de hand van het meegestuurde leveranciersnummer (supplier_number) bepaald van welke leverancier een bepaalde order is.
De token is onbeperkt geldig en bij het tonen van de "Externe applicatie" wordt elke keer een nieuwe token gegenereerd. Het is dus niet mogelijk om te controleren of een ergens ingestelde token correct is; bij twijfel is het advies om altijd een nieuwe token te genereren en deze te gebruiken. De technische documentatie om via de API een order in te kunnen schieten vind je hier.
Let op: in de documentatie wordt uitgegaan van productie-omgevingen. Indien je via de API inkooporders aan wil maken in een testomgeving, is het begin van de url altijd: https://test.spend.cloud/
Let op: in de documentatie wordt uitgegaan van productie-omgevingen. Indien je via de API inkooporders aan wil maken in een testomgeving, is het begin van de url altijd: https://test.spend.cloud/
Voorbeeld van het JSON bericht dat wij verwachten wanneer er een inkooporder bij ons wordt aangeboden:
{
"orders": [
{
"ordernumber": "I9313375",
"external_ordernumber": "I9313995",
"supplier_number": "1",
"administration_number": "001",
"delivery_date": "5-12-2023",
"currency": "EUR",
"total_amount": "10.2100",
"vat_amount": "1.7700",
"total_amount_ex_vat": "8.4400",
"reference": "Reference",
"remark": "Order remark",
"lines": [
{
"linenumber": "1",
"brand": "Philips",
"articlename": "Airfryer",
"articlenumber": "10021AD",
"total_amount": "10.2100",
"total_amount_ex_vat": "8.4400",
"vat_amount": "1.7700",
"quantity": "1",
"unit": "Stuks",
"vat_percentage": "21",
"vat_code": "VAT21",
"unit_number": "1",
"ledger_number": "471210",
"ledger_code": "39101609",
"costcenter_number": "70",
"costunit_number": "60",
"dimension_a_number": "50",
"dimension_b_number": "40",
"dimension_c_number": "30",
"removed": "0"
}
]
}
]
}
"orders": [
{
"ordernumber": "I9313375",
"external_ordernumber": "I9313995",
"supplier_number": "1",
"administration_number": "001",
"delivery_date": "5-12-2023",
"currency": "EUR",
"total_amount": "10.2100",
"vat_amount": "1.7700",
"total_amount_ex_vat": "8.4400",
"reference": "Reference",
"remark": "Order remark",
"lines": [
{
"linenumber": "1",
"brand": "Philips",
"articlename": "Airfryer",
"articlenumber": "10021AD",
"total_amount": "10.2100",
"total_amount_ex_vat": "8.4400",
"vat_amount": "1.7700",
"quantity": "1",
"unit": "Stuks",
"vat_percentage": "21",
"vat_code": "VAT21",
"unit_number": "1",
"ledger_number": "471210",
"ledger_code": "39101609",
"costcenter_number": "70",
"costunit_number": "60",
"dimension_a_number": "50",
"dimension_b_number": "40",
"dimension_c_number": "30",
"removed": "0"
}
]
}
]
}
Aandachtspunten voor het aansturen van de velden:
- Niet alle velden hoeven verplicht ingevuld te worden, deze zijn hierboven dik gedrukt. Onderstaand een uitleg van de niet voor zich sprekende velden en de velden die voor de gebruiker van de Spend Cloud relevant zijn:
- ordernumber OF external_ordernumber = In de meeste situaties ontstaat de order in de externe applicatie en heb je te maken met een ander ordernummer dan het standaard ordernummerformaat uit de Spend Cloud. Wanneer een order wordt aangeboden met een external_ordernumber dan hoeft het veld ordernumber niet meegegeven te worden. Wanneer orders met een extern ordernummer worden aangeboden dan zal de Spend Cloud alsnog een eigen ordernummer genereren (zie voorbeeld hieronder van hoe dit eruit ziet).
- LET OP: wanneer de externe ordernummers alleen op een PDF worden meegegeven (dus niet in een XML factuur) dan zal de tekstherkenning op dit afwijkende formaat moeten worden uitgebreid. Neem hiervoor contact op met onze supportafdeling als dit de wens is. Hierbij is het van belang om te weten hoe het externe ordernummer formaat eruit ziet (bijv. uit hoeveel karakters lang en of het numeriek of alfanumeriek is).
- supplier_number = leveranciersnummer in de Spend Cloud (het veld 'Nummer' dat je kunt instellen door de leverancier te bewerken via Applicatiebeheer / Inkoop / Leveranciers onder 'Geavanceerde instellingen'.)
- administration_number = het nummer van de administratie in Spend Cloud. Deze is terug te vinden via Applicatiebeheer / Algemeen / Administraties / Nummer
- currency = valutacode op basis van de ISO 4217 standaard
- linenumber = per orderregel een uniek nummer meegeven waarbij wij adviseren te beginnen met '1' voor orderregel 1, '2' voor orderregel 2 etc.
- quantity = het aantal dat is besteld. Dit kunnen het aantal artikelen of bijvoorbeeld het aantal uren, of kilometers zijn. Dit geef je aan in "unit" en is vrij in te vullen
- vat_percentage = het btw percentage, zonder toevoeging als %. Notatie mag bijvoorbeeld zijn 21 of 21.0, maar dus geen 21%. Als er geen vat_code wordt meegestuurd, dient in Spend Cloud een btw-code als standaard voor Inkoop te zijn ingesteld. Controleer dit via Applicatiebeheer / Algemeen / Btw
- vat_code = in het geval er in een omgeving bijvoorbeeld 2 btw codes voor 0% bestaan (bijvoorbeeld 0% voor"geen btw" en 0% voor "btw verlegd") is het mogelijk om de juiste btw aan te sturen door de code in het request mee te sturen. Let op dat vat_percentage altijd verplicht is en de code aanvullend werkt
- Onderstaande velden zijn niet verplicht, maar zorgen ervoor dat de orders met completere financiële informatie naar Spend Cloud kunnen worden gestuurd. Dit draagt bij aan het proces van Touchless Factuurverwerking en versnelt dus de betaling van binnenkomende facturen, waar al een order voor bestaat.
- unit_number = het nummer van de organisatorische eenheid in de Spend Cloud zoals te vinden via Organisatie / Structuur. Indien de organisatiestructuur niet genummerd is kun je hier de standaard waarde "1" invullen. Dit is de bovenste organisatorische eenheid in de structuur. Wanneer je onderliggende organisatorische eenheden wilt aansturen dan zien wij vaak dat de laagste laag aan organisatorische eenheden hetzelfde nummer krijgen als de gekoppelde kostenplaats. Maar dit is alleen van toepassing als er per organisatorische eenheid maar één kostenplaats is gekoppeld.
- ledger_number OF ledger_code = Afhankelijk van de oorsprong van de order kan er een grootboekrekeningnummer (ledger_number) of een grootboek-vertaaltabel code (ledger_code) worden meegegeven naar de Spend Cloud. Wanneer een order wordt aangeboden met een ledger_number mag het veld ledger_code niet meegegeven worden en vice versa.
- ledger_number: de keuze voor een grootboekrekeningnummer zal worden gemaakt wanneer er externe orders uit een ander inkooppakket komen. Dit pakket is dan vaak in het bezit is van de grootboekrekeningnummers van de organisatie. Een andere reden dat voor ledger_number wordt gekozen is als er voor alle aangeboden externe orders een vaste grootboekrekening gehanteerd wordt.
- ledger_code: indien het een leverancier betreft die in staat is om een productcategoriecode mee te geven, is het afhankelijk van de leverancier wat voor ledger_codes worden meegegeven. Leveranciers kunnen eigen of algemene productcategoriestandaarden gebruiken, zoals UNSPSC- of NZI-codes.
- costcenter_number = kostenplaatsen worden daar nagenoeg alle Spend Cloud omgevingen gebruikt, dus het is een pre als deze nummers kunnen worden afgestemd en meegegeven. In het ideale geval is de Spend Cloud zo ingericht dat unit_number (nummer Organisatorische Eenheid) en costcenter_number (nummer Kostenplaats) aan elkaar gelijk zijn
- costunit_number = nummer kostendrager, af te stemmen met de Spend Cloud gebruiker
- dimension_a_number = nummer van vrij veld 1, af stemmen met de Spend Cloud gebruiker
- dimension_b_number = nummer van vrij veld 2, af stemmen met de Spend Cloud gebruiker
- dimension_c_number = nummer van vrij veld 3, af stemmen met de Spend Cloud gebruiker
Related Articles
Aanvraag nieuwe OCI koppeling
In jouw inkoopproces in de Spend Cloud kan je gebruik maken van OCI-koppelingen. Daarmee maak je vanuit de Spend Cloud een uitstap naar de webshop van een leverancier om jouw orderaanvraag samen te stellen. Deze orderaanvraag wordt vervolgens ...Inkoop configinstellingen
In het menu-onderdeel Configinstellingen / Inkoop, vind je instellingen die van toepassing zijn op de module Inkoop. Lees ook dit artikel voor meer informatie over configinstellingen. Zorg dat je weet wat een instelling doet voordat je deze gaat ...Wat kun je met de module Inkoop?
Met de module Inkoop kun je het hele inkoopproces van bestelling tot levering en betaling volgen. Het is mogelijk om per medewerker in te stellen of deze zelfstandig mag bestellen, bij welke leveranciers dat mag en tot welk bedrag. De inkoopaanvraag ...Het inkoop-archief
In het archief van inkoop staat een overzicht van alle orders die ooit aan jou zijn toegekend. Op basis van jouw rol zou het zo kunnen zijn dat je ook orders van andere medewerkers in het archief kan terugvinden. Je kunt hier de huidige status ...Budgetten binnen de module Inkoop
Binnen de module Inkoop is er de mogelijkheid te werken met waarschuwingen voor het overschrijden van een budget. Dit is een instelling die door een ProActive-consultant of door de afdeling Support kan worden ingeschakeld. Indien dit is ingeschakeld, ...