Winstwaker Logo
Voor wie
E-commerce & SaaSZakelijke DienstenHoreca & LeisureModerne RetailBouw & Klusbedrijven
Hoe het werktTarievenGratis toolsDevelopersContact

Winstwaker API Referentie (v1)

Deze docs zijn afgestemd op de actuele runtime-contracten van de publieke /v1 endpoints.

Bouw je met AI? Gebruik https://winstwaker.nl/api/developers/llms als contextbron.

Authenticatie

  • GET /v1/health is publiek.
  • Alle andere endpoints vereisen Authorization: Bearer ....
  • ww_live_... voor live mode, ww_test_... voor test mode.
  • Create POST routes vereisen altijd Idempotency-Key.

Response Envelope

{
  "ok": true,
  "request_id": "uuid",
  "mode": "live",
  "status": "ACCEPTED | SUBMITTED | ...",
  "message": "Leesbare status",
  "data": {},
  "breakdown": {},
  "errors": null
}
{
  "ok": false,
  "request_id": "uuid",
  "mode": "live",
  "status": "ERROR",
  "message": "Readable message",
  "data": null,
  "breakdown": null,
  "errors": { "code": "AUTH_INVALID_KEY", "details": {} }
}

Rate Limits

  • X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
  • Bij 429 RATE_LIMIT_EXCEEDED wordt ook Retry-After meegestuurd.

Error Codes

  • AUTH_MISSING_BEARER, AUTH_INVALID_KEY, AUTH_IP_NOT_ALLOWED.
  • AUTH_SCOPE_MISSING, AUTH_KEY_MODE_MISMATCH.
  • RATE_LIMIT_EXCEEDED.
  • VALIDATION_MISSING_IDEMPOTENCY_KEY, VALIDATION_BLOCKED.
  • CONFLICT_IDEMPOTENCY, REQUEST_NOT_FOUND.
  • CREDITS_INSUFFICIENT, DIGIPOORT_SUBMIT_FAILED.

Webhook delivery voor deze developer-v1 flow is momenteel niet publiek gedocumenteerd; gebruik status-endpoints met refresh=true.

GET/v1/health

Health check (publiek)

Geeft operational of degraded terug.

  • 200: service is operationeel.
  • 503: service is degraded (bijv. datastore tijdelijk niet bereikbaar).
GET/v1/credits/balance

Haal creditsaldo op

Optionele query: mode=live|test. Zonder mode krijg je beide balansen.

  • 200: saldo(s) opgehaald.
  • Typische errors: AUTH_MISSING_BEARER, AUTH_INVALID_KEY, RATE_LIMIT_EXCEEDED.
GET/v1/credits/events

Haal credit-events op

  • mode=live|test (optioneel).
  • limit (default 25, max 100).
  • cursor voor paginatie.
  • 200: events met next_cursor.
  • Typische errors: VALIDATION_INVALID_MODE, auth errors, rate limit errors.
GET/v1/usage/summary

Usage overzicht

Query: period=day|month (default day).

  • 200: aggregatie van successful, failed, blocked, pending.
  • Typische errors: VALIDATION_INVALID_PERIOD, auth errors, rate limit errors.
POST/v1/omzetbelasting/returns

Dien omzetbelasting in

  • Verplicht: Idempotency-Key.
  • Gebruik ob_nummer of obNummer.
  • Gebruik periode in YYYY-Q[1-4] of year + quarter.
  • Input via vatData/vat_data of quickstart met omzet + btw_hoog.
  • 202 bij succesvolle submit, 200 bij idempotent replay.
  • Typische errors: VALIDATION_MISSING_IDEMPOTENCY_KEY, VALIDATION_BLOCKED, CONFLICT_IDEMPOTENCY, CREDITS_INSUFFICIENT, DIGIPOORT_SUBMIT_FAILED.
GET/v1/omzetbelasting/returns/{requestId}

BTW status opvragen

  • refresh=true|false (default true).
  • Response bevat endpoint-status, Digipoort metadata en eventuele errorcontext.
  • 200 bij gevonden request, 404 met REQUEST_NOT_FOUND als request onbekend is.
POST/v1/dividendbelasting/returns

Dien dividendbelasting in

  • Verplicht: Idempotency-Key.
  • Verplicht: distributionDate, grossDividend, dividendTax, netDividend.
  • Verplicht: withholdingEntityName, withholdingEntityRsin, beneficiaries[].
  • 202 bij succesvolle submit, 200 bij idempotent replay.
  • Typische errors: VALIDATION_BLOCKED, CONFLICT_IDEMPOTENCY, CREDITS_INSUFFICIENT, DIGIPOORT_SUBMIT_FAILED.
GET/v1/dividendbelasting/returns/{requestId}

Dividend status opvragen

  • refresh=true|false (default true).
  • Response bevat Digipoort metadata inclusief digipoort_kenmerk en statussen.
  • 200 bij gevonden request, 404 met REQUEST_NOT_FOUND als request onbekend is.