{"openapi":"3.1.0","info":{"title":"ProFactuur API","version":"1.0.0","description":"REST API voor ProFactuur (Team-plan). Authenticatie met Authorization: Bearer <sleutel>. Maximaal 60 verzoeken per minuut per sleutel."},"servers":[{"url":"https://profactuur.be/api/v1"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}},"responses":{"Error":{"description":"Fout","content":{"application/json":{"example":{"error":{"status":422,"message":"Validatie mislukt","errors":{"klant_id":"Klant niet gevonden"}}}}}}}},"paths":{"/klanten":{"get":{"tags":["Klanten"],"summary":"Klanten oplijsten","description":"Geeft alle klanten terug, alfabetisch op naam.","parameters":[{"name":"limit","in":"query","required":false,"description":"1 tot 100, standaard 50","schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"description":"Aantal over te slaan, standaard 0","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"description":"Zoek op naam","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":[{"id":"6f1c...","naam":"Bakkerij Peeters"}],"total":1}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["Klanten"],"summary":"Klant aanmaken","description":"Maakt een nieuwe klant aan.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["naam"],"properties":{"naam":{"type":"string","description":"Naam van de klant"},"type":{"type":"string","description":"bedrijf of particulier, standaard bedrijf"},"email":{"type":"string","description":"Adres voor facturen per e-mail"},"adres":{"type":"string","description":"Volledig adres"},"land":{"type":"string","description":"ISO-landcode, standaard BE"},"kbo_btw_nummer":{"type":"string","description":"Ondernemings- of btw-nummer"},"peppol_id":{"type":"string","description":"Peppol-adres, bv. 0208:0123456789"}}},"example":{"naam":"Bakkerij Peeters","email":"boekhouding@peeters.be"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"example":{"data":{"id":"6f1c...","naam":"Bakkerij Peeters"}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/klanten/{id}":{"get":{"tags":["Klanten"],"summary":"Klant ophalen","description":"Geeft één klant met alle gegevens terug.","parameters":[{"name":"id","in":"path","required":true,"description":"ID van de klant","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"id":"6f1c...","naam":"Bakkerij Peeters","type":"bedrijf","email":"boekhouding@peeters.be","land":"BE","kbo_btw_nummer":"BE0123456789"}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"patch":{"tags":["Klanten"],"summary":"Klant bijwerken","description":"Wijzigt enkel de velden die je meestuurt. Zelfde velden als bij aanmaken.","parameters":[{"name":"id","in":"path","required":true,"description":"ID van de klant","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"email":"nieuw@peeters.be"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"id":"6f1c...","email":"nieuw@peeters.be"}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/producten":{"get":{"tags":["Producten"],"summary":"Producten oplijsten","description":"Geeft de producten en diensten uit je prijslijst terug.","parameters":[{"name":"limit","in":"query","required":false,"description":"1 tot 100, standaard 50","schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"description":"Aantal over te slaan, standaard 0","schema":{"type":"integer"}},{"name":"actief","in":"query","required":false,"description":"true of false","schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":[{"id":"1d3e...","naam":"Onderhoud","eenheidsprijs":49}],"total":1}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/producten/{id}":{"get":{"tags":["Producten"],"summary":"Product ophalen","description":"Geeft één product terug.","parameters":[{"name":"id","in":"path","required":true,"description":"ID van het product","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"id":"1d3e...","naam":"Onderhoud","eenheid":"maand","eenheidsprijs":49,"btw_percentage":21,"actief":true}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/offertes":{"get":{"tags":["Offertes"],"summary":"Offertes oplijsten","description":"Geeft offertes terug, nieuwste eerst.","parameters":[{"name":"limit","in":"query","required":false,"description":"1 tot 100, standaard 50","schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"description":"Aantal over te slaan, standaard 0","schema":{"type":"integer"}},{"name":"status","in":"query","required":false,"description":"concept, verzonden, geaccepteerd, geweigerd of verlopen","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":[{"id":"7e8f...","status":"concept","totaal_incl":726}],"total":1}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["Offertes"],"summary":"Conceptofferte aanmaken","description":"Maakt een offerte in concept. Totalen en btw rekent ProFactuur zelf.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["klant_id","regels"],"properties":{"klant_id":{"type":"string","format":"uuid","description":"Klant van het document"},"regels":{"type":"array","items":{"type":"object"},"description":"Minstens één regel: omschrijving, aantal, eenheidsprijs, btw_percentage, of een product_id"},"datum":{"type":"string","format":"date","description":"Standaard vandaag"},"notities":{"type":"string","description":"Vrije tekst onderaan het document"},"geldig_tot":{"type":"string","format":"date","description":"Standaard 30 dagen na de datum"}}},"example":{"klant_id":"6f1c...","regels":[{"omschrijving":"Webdesign","aantal":8,"eenheidsprijs":75,"btw_percentage":21}]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"example":{"data":{"id":"7e8f...","status":"concept","totaal_incl":726}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/offertes/{id}":{"get":{"tags":["Offertes"],"summary":"Offerte ophalen","description":"Geeft één offerte met regels terug.","parameters":[{"name":"id","in":"path","required":true,"description":"ID van de offerte","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"id":"7e8f...","nummer":"OF-2026-0003","status":"verzonden","regels":[{"omschrijving":"Webdesign","aantal":8,"eenheidsprijs":75,"btw_percentage":21,"totaal":600}]}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/facturen":{"get":{"tags":["Facturen"],"summary":"Facturen oplijsten","description":"Geeft facturen en creditnota's terug, nieuwste eerst.","parameters":[{"name":"limit","in":"query","required":false,"description":"1 tot 100, standaard 50","schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"description":"Aantal over te slaan, standaard 0","schema":{"type":"integer"}},{"name":"status","in":"query","required":false,"description":"concept, verzonden of betaald","schema":{"type":"string"}},{"name":"van","in":"query","required":false,"description":"Vanaf datum (YYYY-MM-DD)","schema":{"type":"string","format":"date"}},{"name":"tot","in":"query","required":false,"description":"Tot en met datum","schema":{"type":"string","format":"date"}},{"name":"type","in":"query","required":false,"description":"factuur of creditnota","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":[{"id":"9a2b...","type":"factuur","nummer":"2026-0042","status":"verzonden","datum":"2026-10-10","totaal_incl":726}],"total":1}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["Facturen"],"summary":"Conceptfactuur aanmaken","description":"Maakt een factuur in concept. De vervaldatum volgt je standaard betaaltermijn.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["klant_id","regels"],"properties":{"klant_id":{"type":"string","format":"uuid","description":"Klant van het document"},"regels":{"type":"array","items":{"type":"object"},"description":"Minstens één regel: omschrijving, aantal, eenheidsprijs, btw_percentage, of een product_id"},"datum":{"type":"string","format":"date","description":"Standaard vandaag"},"notities":{"type":"string","description":"Vrije tekst onderaan het document"}}},"example":{"klant_id":"6f1c...","regels":[{"omschrijving":"Webdesign","aantal":8,"eenheidsprijs":75,"btw_percentage":21}]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"example":{"data":{"id":"9a2b...","nummer":null,"status":"concept","totaal_incl":726}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/facturen/{id}":{"get":{"tags":["Facturen"],"summary":"Factuur ophalen","description":"Geeft één factuur met regels terug.","parameters":[{"name":"id","in":"path","required":true,"description":"ID van de factuur","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"id":"9a2b...","type":"factuur","nummer":"2026-0042","status":"verzonden","datum":"2026-10-10","totaal_incl":726,"vervaldatum":"2026-11-09","customer_id":"6f1c...","ogm":"+++123/4567/89012+++","totaal_excl":600,"totaal_btw":126,"regels":[{"omschrijving":"Webdesign","aantal":8,"eenheidsprijs":75,"btw_percentage":21,"totaal":600}]}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/facturen/{id}/definitief":{"post":{"tags":["Facturen"],"summary":"Factuur definitief maken","description":"Kent het volgende factuurnummer en de gestructureerde mededeling toe. Daarna kan de factuur niet meer wijzigen.","parameters":[{"name":"id","in":"path","required":true,"description":"ID van de factuur","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"id":"9a2b...","nummer":"2026-0042","status":"verzonden","ogm":"+++123/4567/89012+++"}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/facturen/{id}/versturen":{"post":{"tags":["Facturen"],"summary":"Factuur versturen","description":"Verstuurt een definitieve factuur via Peppol of per e-mail met de PDF als bijlage.","parameters":[{"name":"id","in":"path","required":true,"description":"ID van de factuur","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kanaal"],"properties":{"kanaal":{"type":"string","description":"peppol of email"},"email":{"type":"string","description":"Ander adres dan dat van de klant (enkel bij email)"},"simuleer":{"type":"string","description":"Enkel met een testsleutel: afgeleverd (standaard), geweigerd of fout"}}},"example":{"kanaal":"peppol"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"kanaal":"peppol","peppol_status":"verzonden"}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/facturen/{id}/pdf":{"get":{"tags":["Facturen"],"summary":"PDF downloaden","description":"Geeft de factuur als PDF-bestand terug.","parameters":[{"name":"id","in":"path","required":true,"description":"ID van de factuur","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/facturen/{id}/ubl":{"get":{"tags":["Facturen"],"summary":"UBL downloaden","description":"Geeft de factuur als Peppol BIS Billing 3.0 XML terug.","parameters":[{"name":"id","in":"path","required":true,"description":"ID van de factuur","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/xml":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/facturen/{id}/creditnota":{"post":{"tags":["Creditnota's"],"summary":"Creditnota aanmaken","description":"Maakt een conceptcreditnota met dezelfde regels als de definitieve factuur.","parameters":[{"name":"id","in":"path","required":true,"description":"ID van de originele factuur","schema":{"type":"string","format":"uuid"}}],"responses":{"201":{"description":"OK","content":{"application/json":{"example":{"data":{"id":"b3c4...","type":"creditnota","status":"concept","gekoppelde_factuur_id":"9a2b..."}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/creditnotas":{"get":{"tags":["Creditnota's"],"summary":"Creditnota's oplijsten","description":"Geeft creditnota's terug, nieuwste eerst.","parameters":[{"name":"limit","in":"query","required":false,"description":"1 tot 100, standaard 50","schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"description":"Aantal over te slaan, standaard 0","schema":{"type":"integer"}},{"name":"status","in":"query","required":false,"description":"concept, verzonden of betaald","schema":{"type":"string"}},{"name":"van","in":"query","required":false,"description":"Vanaf datum (YYYY-MM-DD)","schema":{"type":"string","format":"date"}},{"name":"tot","in":"query","required":false,"description":"Tot en met datum","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":[{"id":"b3c4...","type":"creditnota","nummer":"2026-0043","status":"verzonden","datum":"2026-10-10","totaal_incl":726}],"total":1}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/creditnotas/{id}/versturen":{"post":{"tags":["Creditnota's"],"summary":"Creditnota versturen","description":"Verstuurt een definitieve creditnota via Peppol of per e-mail.","parameters":[{"name":"id","in":"path","required":true,"description":"ID van de creditnota","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kanaal"],"properties":{"kanaal":{"type":"string","description":"peppol of email"},"email":{"type":"string","description":"Ander adres dan dat van de klant (enkel bij email)"},"simuleer":{"type":"string","description":"Enkel met een testsleutel: afgeleverd (standaard), geweigerd of fout"}}},"example":{"kanaal":"email"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"kanaal":"email","naar":"boekhouding@peeters.be"}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/inbox":{"get":{"tags":["Inbox"],"summary":"Ontvangen documenten oplijsten","description":"Geeft facturen en creditnota's terug die je via Peppol ontving.","parameters":[{"name":"limit","in":"query","required":false,"description":"1 tot 100, standaard 50","schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"description":"Aantal over te slaan, standaard 0","schema":{"type":"integer"}},{"name":"status","in":"query","required":false,"description":"Bv. nieuw of betaald","schema":{"type":"string"}},{"name":"van","in":"query","required":false,"description":"Vanaf datum (YYYY-MM-DD)","schema":{"type":"string","format":"date"}},{"name":"tot","in":"query","required":false,"description":"Tot en met datum","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":[{"id":"c4d5...","leverancier":"Leverancier BV","factuurnummer":"INV-881","datum":"2026-10-05","bedrag":242,"status":"nieuw"}],"total":1}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/inbox/{id}":{"get":{"tags":["Inbox"],"summary":"Ontvangen document ophalen","description":"Geeft één ontvangen document met alle gegevens terug.","parameters":[{"name":"id","in":"path","required":true,"description":"ID van het document","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"id":"c4d5...","leverancier":"Leverancier BV","factuurnummer":"INV-881","datum":"2026-10-05","bedrag":242,"status":"nieuw","heeft_pdf":true,"heeft_ubl":true}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/inbox/{id}/pdf":{"get":{"tags":["Inbox"],"summary":"PDF van ontvangen document","description":"Geeft de PDF terug die de leverancier meestuurde.","parameters":[{"name":"id","in":"path","required":true,"description":"ID van het document","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/inbox/{id}/ubl":{"get":{"tags":["Inbox"],"summary":"UBL van ontvangen document","description":"Geeft het originele Peppol-XML terug.","parameters":[{"name":"id","in":"path","required":true,"description":"ID van het document","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/xml":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/test/inbox":{"post":{"tags":["Inbox"],"summary":"Testdocument ontvangen","description":"Maakt een fictief ontvangen document aan. Werkt enkel met een testsleutel.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"leverancier":{"type":"string","description":"Standaard Testleverancier BV"},"factuurnummer":{"type":"string","description":"Standaard een willekeurig TEST-nummer"},"bedrag":{"type":"string","description":"Standaard 121"},"datum":{"type":"string","format":"date","description":"Standaard vandaag"}}},"example":{"leverancier":"Drukkerij Janssens","bedrag":242}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"example":{"data":{"id":"5f6a...","leverancier":"Drukkerij Janssens","factuurnummer":"TEST-48213","bedrag":242,"status":"nieuw"}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}}}}