AFAS connectoren: GetConnector, UpdateConnector en app connector

Drie soorten connectoren

Alles wat een externe koppeling met AFAS Profit doet, loopt via connectoren op de REST API onder https://<omgevingsnummer>.rest.afas.online/ProfitRestServices. Er zijn drie soorten, en ze hebben elk een andere eigenaar:

Een GetConnector of UpdateConnector die niet in de app connector staat, bestaat voor de koppeling niet. De aanroep krijgt dan de melding "GetConnector niet ondersteund voor deze app of de gebruiker is niet geautoriseerd", ook met een geldig token. Welke GetConnectoren en UpdateConnectoren een omgeving heeft, en welke daarvan geblokkeerd zijn, geeft de aanroep GET /metainfo.

Daarmee ligt de eerste stap van elke AFAS koppeling bij de beheerder, niet bij de bouwer. In de praktijk is dat de stap waar het op wacht. Wij leveren daarom vooraf de volledige lijst: welke GetConnectoren en UpdateConnectoren, welke velden per GetConnector, welke gebruikersgroep.

Classic token of OAuth

Een koppeling meldt zich op twee manieren aan. Met een classic token, een vaste sleutel die bij elke aanroep meegaat als Authorization: AfasToken <Base64>. Of met OAuth, waarbij de koppeling eerst een kortlevend access token ophaalt. AFAS faseert het classic token uit. De tijdlijn uit de documentatie over authenticatie, bijgewerkt op 30 september 2026:

Het helpcentrum van AFAS noemt voor het verlopen van bestaande tokens 15 februari 2027 in plaats van 1 mei 2027. Reken met de vroegste datum. Het helpcentrum meldt ook dat app connectoren die 6 maanden of langer niet zijn gebruikt, worden geblokkeerd.

Voor een koppeling tussen twee systemen is de client credentials flow de route: geen gebruiker die inlogt, de koppeling werkt onder de gebruiker van de app connector.

POST /ProfitRestServices/oauth/token HTTP/1.1
Host: 12345.rest.afas.online
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>

Het antwoord bevat een access_token met expires_in: 3600, zonder refresh token. Na een uur vraagt de koppeling een nieuw token; tussendoor hergebruikt hij het, in plaats van per aanroep een nieuw te halen. Vanaf Profit 9 heeft een client secret een geldigheidsduur, standaard 180 dagen. Een verlopen secret stopt de koppeling, dus het vernieuwen hoort in de planning, of de koppeling gebruikt private key JWT.

Twee regels gelden voor beide methoden. Een token of secret is na het aanmaken niet meer in Profit te raadplegen; is het kwijt, dan maakt de beheerder een nieuw. En een IP-restrictie op de app connector wordt in CIDR-notatie ingesteld, zonder IPv6. De koppeling komt dan van een vast IPv4-adres; een ander adres krijgt een 403.

GetConnector: lezen met skip, take en filters

Een GetConnector zonder skip en take geeft altijd de eerste 100 regels. Er komt geen foutmelding bij: de koppeling ziet 100 artikelen en denkt dat dat alles is. De grenzen per aanroep:

• velden maal regels onder 150.000 (een advies; AFAS kondigt een harde limiet aan)
• maximaal 75 MB per aanroep
• time-out na 900 seconden
• een URL met filter van maximaal 2.048 tekens

Een rekenvoorbeeld met 42.000 artikelen:

Bij bladeren hoort een sortering op een uniek veld (orderbyfieldids=ItemCode), anders verschuift de volgorde tussen twee aanroepen en valt er een regel tussen de pagina's. AFAS schrijft ook dat het ophalen trager wordt naarmate skip oploopt. Bij grote sets werkt een filter op het gesorteerde veld beter: de volgende aanroep vraagt alles vanaf de laatste artikelcode van de vorige.

Filters gaan als drie parallelle lijsten in de URL: filterfieldids, filtervalues en operatortypes. Een komma tussen de waarden is EN, een puntkomma is OF. De operators die een koppeling het meest gebruikt:

Een ongeldige combinatie, zoals skip=2&take=-1, geeft geen nette 400 maar een 500 met "Er is een onverwachte fout opgetreden". Hoe je zo'n ronde over de hele dag doorrekent, staat in doorvoer berekenen.

UpdateConnector: schrijven en foutmeldingen lezen

Schrijven gaat met POST voor nieuw, PUT voor wijzigen en DELETE voor verwijderen, naar /connectors/FbSales, /connectors/KnSalesRelationOrg enzovoort. Twee instellingen in het verzoek bepalen of de inhoud goed aankomt. Speciale tekens moeten in UTF-8; anders staat er in Profit een vraagteken in plaats van é of ü. En de header Accept-Language bepaalt in welke taal codetabelwaarden worden gelezen: voor het geslacht Man is dat M bij nl-nl en H bij fr-fr.

Weigert Profit een record, dan komt er een 500 met drie velden in de body:

{
  "externalMessage": "De ingevulde waarde bij 'Betaalvoorwaarde' bestaat niet.",
  "errorNumber": -2147220469,
  "profitLogReference": "5D0E7C21A94B4F6E8B1F3A60C2D9E447"
}

externalMessage is de korte melding die een gebruiker in Profit ook zou zien. profitLogReference verwijst naar het omgevingslogboek, waar de beheerder de volledige fout vindt. errorNumber is meestal een algemene code en zegt weinig. AFAS logt alleen fouten, en nooit de inhoud van het verzoek. Wat er precies is verstuurd, moet dus in de log van de koppeling staan.

Of een nieuwe poging zin heeft, hangt af van de code:

Een time-out aan de kant van de koppeling betekent niet dat Profit gestopt is. AFAS raadt aan de volle 900 seconden af te wachten voordat dezelfde aanroep opnieuw gaat. Wie eerder opnieuw stuurt, laat Profit hetzelfde werk twee keer doen, en een order kan dan twee keer binnenkomen. Hoe dubbele relaties en orders ontstaan staat in dubbele klanten en debiteuren.

Wat betekent dit voor je koppeling?

Het werk aan AFAS zit voor een deel bij de beheerder: de app connector, de GetConnectoren en de overstap naar OAuth voor 31 augustus 2027. Wij leveren de lijst die daarvoor nodig is en bouwen de koppeling op OAuth, met eigen GetConnectoren, sortering en filters per ronde, en een foutafhandeling die per code kiest tussen opnieuw proberen en de controlelijst. In het dashboard staat bij elke geweigerde order de melding en de profitLogReference, zodat je beheerder hem in het logboek terugvindt.

Welke stromen we tussen AFAS en je webshop koppelen, en waar de veldcodes op vastlopen, staat op de pagina over de AFAS webshop koppeling. Voor WooCommerce is er de WooCommerce AFAS koppeling. Vertel welke Profit-versie en welke authenticatie je nu gebruikt, dan zie je welke connectoren en welke stappen nodig zijn.