De AFAS-connectoren die je in de praktijk nodig hebt

Een naslagpagina voor wie een koppeling met AFAS Profit bouwt of beheert: welke connectoren u werkelijk aanraakt bij order-, factuur- en urenstromen, welke velden erin moeten, wat de beheerder klaarzet en waar elke connector u in de steek laat. Alles is op 28 augustus 2026 nagelezen op help.afas.nl, met de bron bij de bewering. Wat wij uit ervaring toevoegen staat onder "in de praktijk"; wat niet in de AFAS-documentatie staat, heet hier niet gedocumenteerd.

Eerst de bouwstenen

Een GetConnector haalt gegevens op en is gebaseerd op een gegevensverzameling die u zelf in Profit inricht; een UpdateConnector voegt toe, wijzigt of verwijdert en heeft een vaste, door AFAS bepaalde structuur (Connector - externe software koppelen). Van de speciale connectoren komt alleen de SubjectConnector (bijlagen bij dossieritems) hieronder terug.

Twee data voor de agenda: bestaande classic tokens krijgen in september 2026 een einddatum van 15 februari 2027, en app connectoren op classic tokens moeten uiterlijk 31 augustus 2027 op OAuth staan (Overstappen van classic tokens op OAuth). Wie nu bouwt, begint met OAuth.

Wat de beheerder klaarzet

De inrichting in Profit, zoals AFAS die zelf beschrijft in Eigen app connector inrichten in vogelvlucht en Beveiliging van connectoren:

Stap 6 is niet cosmetisch: een GetConnector geeft records "voor zover dit is toegestaan op basis van de filterautorisatie" (App connector), en KnSubject wijzigt of verwijdert alleen dossieritems waar de connector-gebruiker via filterautorisatie rechten op heeft (KnSubject). Een koppeling die in test alles ziet en in productie de helft, heeft hier het verschil zitten.

GetConnectoren: wat voor alle drie de stromen geldt

Een GetConnector heeft geen vaste velden. De beheerder maakt hem aan via Algemeen / Uitvoer / Beheer / GetConnector op een gegevensverzameling en kiest de velden; de namen in de kolom Veld worden de namen in het resultaat, en de gegevensverzameling is na aanmaken niet meer te wisselen (GetConnector toevoegen). Welk veld u ook mist: de klant zet het er zelf in, en de metainfo-aanroep is de enige betrouwbare manier om te zien wat erin zit.

Een gepagineerde aanroep ziet er dan zo uit (fictieve deelnemer, fictieve connectornaam):

`` GET https://12345.resttest.afas.online/profitrestservices/connectors/Wr_Verkooporders ?skip=0&take=500 &orderbyfieldids=Ordernummer &filterfieldids=Orderdatum%2CStatus &filtervalues=2026-08-01T00%3A00%2C1 &operatortypes=2%2C1 Authorization: AfasToken PHRva2VuPjx2ZXJzaW9uPjE8L3ZlcnNpb24+PGRhdGE+...PC9kYXRhPjwvdG9rZW4+ ``

Doorlopen tot er een lege set terugkomt, zoals AFAS het zelf beschrijft.

Gewijzigd en verwijderd ophalen

Voor "alleen wat er sinds gisteren veranderde" zet de beheerder de logvelden Toevoegdatum en Wijzigingsdatum uit de sectie Logging in de gegevensverzameling. AFAS: "In de audit-velden zie je alleen de laatste wijziging, niet de voorgaande wijzigingen"; >=[Vandaag] filtert op 00:00 uur van vandaag; betaal- en afletterstatus van facturen vallen erbuiten (Gewijzigde gegevens opvragen).

Verwijderingen ziet u er niet in. Daarvoor is een GetConnector op het logboek nodig, met Type log = D en Log datum als filter, en "Logs worden ingesteld per omgeving": wat in test aanstaat, staat in productie niet vanzelf aan (Verwijderde gegevens opvragen).

UpdateConnectoren: wat voor alle drie de stromen geldt

De REST-kant is eenvormig (UpdateConnector (REST/JSON)): POST <endpoint>/connectors/<Connector> voegt toe, PUT wijzigt, DELETE <endpoint>/connectors/<Connector>/<Element>/@<Sleutelveld>/<waarde> verwijdert. De body is altijd { "<Connector>": { "Element": { "Fields": {…}, "Objects": {…} } } }. Speciale tekens moeten in UTF-8; anders komen er vraagtekens in Profit.

Verplichte velden staan niet als lijst op de helppagina's maar in de XML-voorbeeldbestanden en in AFAS Connect en API Docs. Hieronder staan alleen de velden die de helppagina met naam noemt.

Orders

Uit de FbSales-pagina (FbSales): "Een insert van een verkooporder zonder regels en zonder SoQu zal afgekeurd worden." Met SoQu neemt Profit de hele offerte met alle regels over. Regels wijzigt u op artikelcode of op GUID; verwijderen kan per order of per regel. Het afleveradres is een Adres ID uit de debiteurweergave, anders krijgt u "De ingevulde waarde bij 'Afleveradres' bestaat niet." Voor FbPurch geldt hetzelfde met Dlad, en de afwijkende leverdatum is alleen te wijzigen "als de regelstatus niet op Afgehandeld staat" (FbPurch).

In de praktijk: wijzig regels op GUID, niet op artikelcode. Of een PUT de niet-meegestuurde regels laat staan is niet beschreven; dat is de eerste test in de testomgeving, voordat er een productieorder wordt aangeraakt.

Facturen

Vier regels uit de FiEntries-documentatie (FiEntries): "Je kunt met deze UpdateConnector alleen complete boekingen aanleveren (met alle benodigde debet- en creditregels)"; "Crediteurenfacturen mogen alleen worden geboekt in een inkoopboek"; "Je kunt maximaal 1.000 regels per journaalpost aanbieden"; en "Er wordt geen controle gedaan op de geldigheid van btw-codes." Een verkeerde btw-code gaat er dus in en komt er pas bij de aangifte weer uit.

In de praktijk is FiEntries of FiElectronicInvoicePurchase de keuze tussen zelf coderen en laten herkennen. FiEntries verlangt dat de koppeling grootboek, btw en kostenplaats al kent; de e-factuurconnector laat Profit dat doen, in de fiatteerstroom die de klant al heeft. Wie beide door elkaar gebruikt krijgt dubbele facturen.

Uren

Uit de PtRealization-documentatie (PtRealization): over Ch, doorbelasten: "Als dit veld niet wordt aangeleverd, wordt de waarde 'True' toegepast", met als uitzondering projecten met termijnen. "Het veld Aantal wordt niet berekend op basis van de begin- en eindtijd, maar overgenomen zoals je dit aanlevert." En: "De nacalculatieregel kan na accordering aangepast worden. De nacalculatieregel kan na accordering verwijderd worden." Dat geldt ook voor regels die uit verlofaanvragen en verzuimmeldingen zijn ontstaan.

Bij PtRealizationWeek staat een eigenaardigheid die u nergens anders leest (PtRealizationWeek): bij eindtijd 00:00 gaat Profit de eindtijd alsnog berekenen, "en dit levert soms niet de goede uitkomst op. Als workaround kun je 23:59 uur gebruiken."

Dossieritems

Dossieritems zitten in alle drie de stromen: de PDF bij de inkooporder, de getekende urenstaat, de scan van de inkoopfactuur.

Een correct gevormd verzoek zoals AFAS het documenteert, voor een inkoopfactuur-PDF als dossieritem bij een inkooprelatie. Alle nummers zijn fictief.

``` POST https://12345.resttest.afas.online/profitrestservices/connectors/KnSubject Authorization: AfasToken <base64> Content-Type: application/json;charset=utf-8

{ "KnSubject": { "Element": { "Fields": { "StId": -5, "Ds": "Inkoopfactuur 2026-0418 Leverancier B.V.", "Da": "2026-08-28" }, "Objects": [ { "KnSubjectLink": { "Element": { "Fields": { "DoCRM": true, "SfTp": 11, "SfId": "300042", "BcId": "300042" } } } }, { "KnSubjectAttachment": { "Element": { "Fields": { "FileName": "inkoopfactuur-2026-0418.pdf", "FileStream": "JVBERi0xLjcKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2c..." } } } } ] } } } ```

Bij succes komt er een 201 terug met het aangemaakte dossieritem; wijzigen gaat via PUT met "@SbId": <nummer> in het element, verwijderen via DELETE …/connectors/KnSubject/KnSubject/@SbId/<nummer> (KnSubject, UpdateConnector REST).

Valkuilen die u pas kent als u het gedaan hebt

Het gedrag staat telkens in de documentatie; niemand leest het voordat het misgaat.

De stille 100. Een GetConnector zonder skip en take geeft geen fout; hij geeft de eerste honderd regels en zwijgt (REST API). Een koppeling die in test met 60 orders werkt en in productie bij order 101 ophoudt, heeft dit. Wie dan -1/-1 invult, loopt bij een grote tabel tegen de 15 minuten of de 150.000 aan. Pagineren, met sortering op een sleutelveld.

FiEntries kent geen verschil, alleen een boeking. Een inkoopfactuur die al in Profit staat is met FiEntries niet te corrigeren: alleen toevoegen en verwijderen, en wat u toevoegt moet als geheel in evenwicht zijn (FiEntries). Een koppeling die "de gewijzigde regel opnieuw stuurt" maakt een tweede boeking. Herstel is verwijderen op factuurnummer en opnieuw aanleveren, of de paar velden van FiInvoice.

Doorbelasten staat standaard aan. Uren via PtRealization zonder Ch zijn factureerbare uren, ook de interne (PtRealization). En Qu wordt niet uit begin- en eindtijd berekend: 09:00 tot 17:00 met aantal 0 is acht uur in de tijden en nul op de factuur. Reken het aantal zelf en stuur Ch altijd mee.

Het token is er vier. Een token geldt voor de combinatie omgeving, app connector, gebruiker en device (Tokens); test, acceptatie en productie hebben elk een eigen basis-URL (URL's). Een productietoken op de test-URL geeft een 401 die niet zegt welke van de vier niet klopt. Zet de omgevingsletter (O, T, A) naast het token in de configuratie.

De komma in de klantnaam. Filterwaarden gaan de URL in met %2C en %3B als scheidingsteken; "Janssen, Henk" wordt twee filters (GetConnector REST). AFAS verwijst dan naar een complex filter. Filter op codes, niet op namen.

Wat u hier niet mee kunt, en waar maatwerk begint

De connectoren doen wat in de tabellen staat en niets meer. Daarbuiten valt:

• Een GetConnector geeft alleen de velden die de beheerder heeft toegevoegd, en de gegevensverzameling ligt na aanmaken vast. Een veld dat de verzameling niet kent is inrichting aan de Profit-kant, geen koppelingswerk.
• Verwijderingen komen alleen uit het logboek, en dat moet per omgeving aanstaan.
• Tijdzonegedrag van datumfilters is niet gedocumenteerd; wie rond middernacht op "gisteren" filtert, test dat eerst in de eigen omgeving.
• Financiële mutaties zijn niet te wijzigen; verwijderen en opnieuw boeken is de enige weg.
• Verplichte velden van FbDirectInvoice en FbPurch staan niet op de helppagina, alleen in het XML-voorbeeld en in AFAS Connect.
• Of een PUT op FbSales de niet-meegestuurde regels laat staan, is nergens beschreven.

Maatwerk begint waar de koppeling moet beslissen: welke regel bij welke order hoort, welk grootboek bij welke leverancier, wat er gebeurt met een order die in Profit al is vrijgegeven terwijl het bronsysteem hem nog wijzigt. Dat is geen connector-vraag maar een vertaalvraag, en die hoort in de laag tussen de systemen. Hoe wij die laag inrichten staat op /koppelingen/afas/ en op /koppelingen/; de technische uitgangspunten op /techniek/.

Dit is de stand van de AFAS-documentatie op 28 augustus 2026. AFAS verwijst voor de volledige specificaties naar AFAS Connect en API Docs; wijkt een veld daar af van deze pagina, dan heeft AFAS gelijk.