{"openapi":"3.1.0","info":{"title":"Goldmary API","version":"1","description":"De routes die een persoonlijk token (gm_…) als REST-sleutel opent. Bedragen in centen."},"servers":[{"url":"https://goldmary.eu"}],"security":[{"token":[]}],"components":{"securitySchemes":{"token":{"type":"http","scheme":"bearer","description":"Persoonlijk token uit Instellingen, Koppelingen, AI-assistenten koppelen."}}},"paths":{"/api/v1/administraties/{administratieId}/invoices":{"get":{"operationId":"list_invoices","summary":"List the sales invoices (facturen), newest first.","parameters":[{"name":"administratieId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","schema":{"type":"string","description":"Only this status.","enum":["concept","definitief","betaald","geannuleerd"]}},{"name":"customer","in":"query","schema":{"type":"string","description":"Only invoices for this customer id."}}],"responses":{"200":{"description":"Gelukt.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"invoices":{"type":"array"}},"required":["ok","invoices"]}}}},"401":{"description":"Geen, een ongeldig, ingetrokken of verlopen token."},"403":{"description":"Een andere administratie, of schrijven met een token dat alleen mag lezen."},"429":{"description":"Meer dan 60 verzoeken per minuut per token of 300 per internetadres."}}},"post":{"operationId":"create_invoice","summary":"Make a concept sales invoice with one line for a customer. Goldmary does not send it and gives it no number; the user checks it and sends it in the app.","parameters":[{"name":"administratieId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customerId","lines"],"properties":{"customerId":{"type":"string","format":"uuid"},"lines":{"type":"array","items":{"type":"object","required":["description","quantity","unitPriceCents","vatRate"],"properties":{"description":{"type":"string"},"quantity":{"type":"string","description":"Hoeveelheid, hooguit drie decimalen, bijvoorbeeld 2,5 (een getal mag ook)"},"unitPriceCents":{"type":"integer"},"vatRate":{"type":"integer"}}}}}}}}},"responses":{"201":{"description":"Gelukt.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"invoice":{"type":"object"}},"required":["ok","invoice"]}}}},"401":{"description":"Geen, een ongeldig, ingetrokken of verlopen token."},"403":{"description":"Een andere administratie, of schrijven met een token dat alleen mag lezen."},"429":{"description":"Meer dan 60 verzoeken per minuut per token of 300 per internetadres."}}}},"/api/v1/administraties/{administratieId}/invoices/{id}":{"get":{"operationId":"get_invoice","summary":"One invoice with its lines, totals and status.","parameters":[{"name":"administratieId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Gelukt.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"invoice":{"type":"object"}},"required":["ok","invoice"]}}}},"401":{"description":"Geen, een ongeldig, ingetrokken of verlopen token."},"403":{"description":"Een andere administratie, of schrijven met een token dat alleen mag lezen."},"429":{"description":"Meer dan 60 verzoeken per minuut per token of 300 per internetadres."}}}},"/api/v1/administraties/{administratieId}/customers":{"get":{"operationId":"list_customers","summary":"List the customers (klanten).","parameters":[{"name":"administratieId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"q","in":"query","schema":{"type":"string","description":"Search in name, email and number."}}],"responses":{"200":{"description":"Gelukt.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"customers":{"type":"array"}},"required":["ok","customers"]}}}},"401":{"description":"Geen, een ongeldig, ingetrokken of verlopen token."},"403":{"description":"Een andere administratie, of schrijven met een token dat alleen mag lezen."},"429":{"description":"Meer dan 60 verzoeken per minuut per token of 300 per internetadres."}}},"post":{"operationId":"create_customer","summary":"Add a customer (klant). Returns the new customer with its id.","parameters":[{"name":"administratieId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"The customer's name."},"email":{"type":"string","description":"Invoice e-mail address."},"city":{"type":"string","description":"Place (plaats)."},"kvk":{"type":"string","description":"Dutch KvK number, 8 digits."}}}}}},"responses":{"201":{"description":"Gelukt.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"customer":{"type":"object"}},"required":["ok","customer"]}}}},"401":{"description":"Geen, een ongeldig, ingetrokken of verlopen token."},"403":{"description":"Een andere administratie, of schrijven met een token dat alleen mag lezen."},"429":{"description":"Meer dan 60 verzoeken per minuut per token of 300 per internetadres."}}}},"/api/v1/administraties/{administratieId}/postcode-opzoeken":{"get":{"operationId":"adres_opzoeken","summary":"Look up a Dutch address (PDOK, official BAG data). Give postcode and huisnummer (optional toevoeging) to get street and city, or q (3+ characters, e.g. 'Weena 66') for suggestions. PDOK only receives the address you give.","parameters":[{"name":"administratieId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"postcode","in":"query","schema":{"type":"string","description":"Dutch postcode, for example 3012CN."}},{"name":"huisnummer","in":"query","schema":{"type":"string","description":"House number, for example 660 or 66A."}},{"name":"toevoeging","in":"query","schema":{"type":"string","description":"Addition, for example bis."}},{"name":"q","in":"query","schema":{"type":"string","description":"Typed address for suggestions, at least 3 characters."}}],"responses":{"200":{"description":"Gelukt.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"gevonden":{"type":"boolean"},"straat":{"type":"string"},"plaats":{"type":"string"},"resultaten":{"type":"array"}},"required":["ok"]}}}},"401":{"description":"Geen, een ongeldig, ingetrokken of verlopen token."},"403":{"description":"Een andere administratie, of schrijven met een token dat alleen mag lezen."},"429":{"description":"Meer dan 60 verzoeken per minuut per token of 300 per internetadres."}}}},"/api/v1/administraties/{administratieId}/customers/{id}":{"get":{"operationId":"get_customer","summary":"One customer with its details.","parameters":[{"name":"administratieId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Gelukt.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"customer":{"type":"object"},"projects":{"type":"array"}},"required":["ok","customer","projects"]}}}},"401":{"description":"Geen, een ongeldig, ingetrokken of verlopen token."},"403":{"description":"Een andere administratie, of schrijven met een token dat alleen mag lezen."},"429":{"description":"Meer dan 60 verzoeken per minuut per token of 300 per internetadres."}}}},"/api/v1/administraties/{administratieId}/uren":{"get":{"operationId":"list_hours","summary":"The hours (uren) booked in one week, per project and day, in minutes.","parameters":[{"name":"administratieId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"week","in":"query","schema":{"type":"string","description":"Any day in the week, YYYY-MM-DD. Default: this week."}}],"responses":{"200":{"description":"Gelukt.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"week":{"type":"object"},"rijen":{"type":"array"},"dagTotaal":{"type":"object"},"weekTotaal":{"type":"object"}},"required":["ok","week","rijen","dagTotaal","weekTotaal"]}}}},"401":{"description":"Geen, een ongeldig, ingetrokken of verlopen token."},"403":{"description":"Een andere administratie, of schrijven met een token dat alleen mag lezen."},"429":{"description":"Meer dan 60 verzoeken per minuut per token of 300 per internetadres."}}}},"/api/v1/administraties/{administratieId}/bonnen":{"get":{"operationId":"list_expenses","summary":"List the receipts and purchase invoices (bonnen) with what was read from them.","parameters":[{"name":"administratieId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","description":"At most this many, newest first."}}],"responses":{"200":{"description":"Gelukt.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"receipts":{"type":"array"}},"required":["ok","receipts"]}}}},"401":{"description":"Geen, een ongeldig, ingetrokken of verlopen token."},"403":{"description":"Een andere administratie, of schrijven met een token dat alleen mag lezen."},"429":{"description":"Meer dan 60 verzoeken per minuut per token of 300 per internetadres."}}},"post":{"operationId":"create_expense","summary":"Add a receipt (bon) as a file of at most 5 MB. Goldmary keeps it unbooked; the user checks and books it in the app.","parameters":[{"name":"administratieId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["bestand"],"properties":{"bestand":{"type":"string","format":"binary","description":"Pdf, jpeg, png, webp of tekst, maximaal 5 MB."}}}}}},"responses":{"201":{"description":"Gelukt.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"receipt":{"type":"object"}},"required":["ok","receipt"]}}}},"401":{"description":"Geen, een ongeldig, ingetrokken of verlopen token."},"403":{"description":"Een andere administratie, of schrijven met een token dat alleen mag lezen."},"429":{"description":"Meer dan 60 verzoeken per minuut per token of 300 per internetadres."}}}},"/api/v1/administraties/{administratieId}/bonnen/{id}":{"get":{"operationId":"get_expense","summary":"One receipt (bon) with its amounts and booking.","parameters":[{"name":"administratieId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Gelukt.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"receipt":{"type":"object"}},"required":["ok","receipt"]}}}},"401":{"description":"Geen, een ongeldig, ingetrokken of verlopen token."},"403":{"description":"Een andere administratie, of schrijven met een token dat alleen mag lezen."},"429":{"description":"Meer dan 60 verzoeken per minuut per token of 300 per internetadres."}}}},"/api/v1/administraties/{administratieId}/boekingen":{"get":{"operationId":"list_bookings","summary":"List the bookings (boekingen) in a period, amounts in cents.","parameters":[{"name":"administratieId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"van","in":"query","schema":{"type":"string","description":"First day, YYYY-MM-DD. Default: 1 January of this year."}},{"name":"tot","in":"query","schema":{"type":"string","description":"Last day, YYYY-MM-DD. Default: today."}},{"name":"status","in":"query","schema":{"type":"string","description":"Only this status.","enum":["draft","confirmed","void"]}}],"responses":{"200":{"description":"Gelukt.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"boekingen":{"type":"array"},"totaal":{"type":"number"},"van":{"type":"string"},"tot":{"type":"string"}},"required":["ok","boekingen","totaal","van","tot"]}}}},"401":{"description":"Geen, een ongeldig, ingetrokken of verlopen token."},"403":{"description":"Een andere administratie, of schrijven met een token dat alleen mag lezen."},"429":{"description":"Meer dan 60 verzoeken per minuut per token of 300 per internetadres."}}}},"/api/v1/administraties/{administratieId}/boekingen/{id}":{"get":{"operationId":"get_booking","summary":"One booking with its lines.","parameters":[{"name":"administratieId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Gelukt.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"boeking":{"type":"object"}},"required":["ok","boeking"]}}}},"401":{"description":"Geen, een ongeldig, ingetrokken of verlopen token."},"403":{"description":"Een andere administratie, of schrijven met een token dat alleen mag lezen."},"429":{"description":"Meer dan 60 verzoeken per minuut per token of 300 per internetadres."}}}},"/api/v1/administraties/{administratieId}/btw-periode":{"get":{"operationId":"vat_period","summary":"The VAT (btw) figures for one quarter or month, per box of the Dutch VAT return, with what is still open.","parameters":[{"name":"administratieId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"jaar","in":"query","schema":{"type":"integer","description":"Year, e.g. 2026. Default: this year."}},{"name":"kwartaal","in":"query","schema":{"type":"integer","description":"Quarter 1-4. Default: the current quarter."}},{"name":"maand","in":"query","schema":{"type":"integer","description":"Month 1-12, for monthly VAT returns."}}],"responses":{"200":{"description":"Gelukt.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"tijdvak":{"type":"object"},"rubrieken":{"type":"array"}},"required":["ok","tijdvak","rubrieken"]}}}},"401":{"description":"Geen, een ongeldig, ingetrokken of verlopen token."},"403":{"description":"Een andere administratie, of schrijven met een token dat alleen mag lezen."},"429":{"description":"Meer dan 60 verzoeken per minuut per token of 300 per internetadres."}}}},"/api/v1/administraties/{administratieId}/winst-en-verliesrekening":{"get":{"operationId":"profit_and_loss","summary":"The profit and loss statement (winst-en-verliesrekening) for a period.","parameters":[{"name":"administratieId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"van","in":"query","schema":{"type":"string","description":"First day, YYYY-MM-DD. Default: 1 January of this year."}},{"name":"tot","in":"query","schema":{"type":"string","description":"Last day, YYYY-MM-DD. Default: today."}}],"responses":{"200":{"description":"Gelukt.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"van":{"type":"string"},"tot":{"type":"string"},"nettoOmzet":{"type":"number"},"resultaat":{"type":"number"},"regels":{"type":"array"}},"required":["ok","van","tot","nettoOmzet","resultaat","regels"]}}}},"401":{"description":"Geen, een ongeldig, ingetrokken of verlopen token."},"403":{"description":"Een andere administratie, of schrijven met een token dat alleen mag lezen."},"429":{"description":"Meer dan 60 verzoeken per minuut per token of 300 per internetadres."}}}},"/api/v1/administraties/{administratieId}/balans":{"get":{"operationId":"balance_sheet","summary":"The balance sheet (balans) on a date.","parameters":[{"name":"administratieId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"peildatum","in":"query","schema":{"type":"string","description":"The date, YYYY-MM-DD. Default: today."}}],"responses":{"200":{"description":"Gelukt.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"peildatum":{"type":"string"},"activa":{"type":"array"},"passiva":{"type":"array"},"eigenVermogen":{"type":"array"},"totaalActiva":{"type":"number"},"totaalPassiva":{"type":"number"}},"required":["ok","peildatum","activa","passiva","eigenVermogen","totaalActiva","totaalPassiva"]}}}},"401":{"description":"Geen, een ongeldig, ingetrokken of verlopen token."},"403":{"description":"Een andere administratie, of schrijven met een token dat alleen mag lezen."},"429":{"description":"Meer dan 60 verzoeken per minuut per token of 300 per internetadres."}}}},"/api/v1/administraties/{administratieId}/uren/cel":{"put":{"operationId":"set_hours","summary":"Set the minutes worked on one project on one day. Replaces what was booked in that cell; 0 clears it.","parameters":[{"name":"administratieId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["projectId","date","minutes"],"properties":{"projectId":{"type":"string","description":"The project id (uuid)."},"date":{"type":"string","description":"The day, YYYY-MM-DD."},"minutes":{"type":"integer","description":"Minutes worked, e.g. 90."}}}}}},"responses":{"200":{"description":"Gelukt.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"cel":{"type":"object"},"dagMinuten":{"type":"number"}},"required":["ok","cel","dagMinuten"]}}}},"401":{"description":"Geen, een ongeldig, ingetrokken of verlopen token."},"403":{"description":"Een andere administratie, of schrijven met een token dat alleen mag lezen."},"429":{"description":"Meer dan 60 verzoeken per minuut per token of 300 per internetadres."}}}}}}