Direct naar de inhoud
Sursa Developers

Tijd en formaten

JSON en tekst

  • Request- en response-bodies zijn JSON in UTF-8, met Content-Type: application/json. Voor het uploaden van bestanden wordt multipart/form-data gebruikt.
  • Veldnamen en enumwaarden zijn snake_case: next_retry_at, index_failed.
  • Foutmeldingen en de teksten van de API zijn in het Engels. Teksten die je zelf schrijft, zoals titels van kaarten, worden teruggegeven zoals je ze hebt geschreven, in welke taal dan ook.

Tijdstippen

Elk tijdstip is een RFC 3339-tijdstempel in UTC:

{"created_at": "2026-10-24T10:00:00Z"}
  • Nieuwere velden gebruiken de korte vorm met Z, zoals hierboven.
  • Sommige velden die al eerder bestonden, gebruiken de vorm 2026-10-24T10:00:00.123456+00:00, met maximaal zes cijfers voor fracties van een seconde. Dat is hetzelfde moment in UTC. Parseer beide vormen met een standaardparser voor RFC 3339; vergelijk tijdstempels niet als strings.
  • Elk veld waarvan de naam op _at eindigt, is een tijdstempel.

Tijdstippen die je stuurt, moeten een tijdzoneverschuiving bevatten: Z of een numerieke verschuiving zoals +02:00. Een tijdstip zonder verschuiving is dubbelzinnig en geeft 422 met de code validation.failed. Sursa zet elk tijdstip dat het ontvangt om naar UTC.

const since = new Date(Date.now() - 24 * 3600 * 1000).toISOString(); // "2026-10-23T10:00:00.000Z"

In een querystring moet een + worden geschreven als %2B, anders wordt hij gelezen als een spatie. Codeer tijdwaarden voor de URL (URL-encoding), of gebruik Z.

Datums, duur en aantallen

SoortVormVoorbeeld
Datum zonder tijdYYYY-MM-DD, in een veld dat op _date eindigt"due_date": "2026-11-01"
DuurEen geheel getal, met de eenheid in de veldnaam"interval_days": 90, "timeout_seconds": 30
AantalEen geheel getal, in een veld dat op _count eindigt"part_count": 12
Waar of onwaarEen boolean, genoemd naar een bijvoeglijk naamwoord zonder is_"active": true, "sensitive": false

Geldbedragen

Bedragen in financiële responses zijn decimale strings, zoals "1250.00", nooit drijvendekommagetallen, zodat er geen precisie verloren gaat. De valuta is een apart veld met een ISO 4217-code, zoals "EUR". Parseer bedragen met een decimaal type in je programmeertaal.

ID’s

ID’s zijn strings of gehele getallen, afhankelijk van het object. Zie ID’s van objecten.

Enumeraties

Velden met een vaste set waarden, zoals een status, zijn strings. Elke enumeratie in een response kan in een latere versie nieuwe waarden krijgen: behandel een waarde die je niet kent als “overig”. Zie Versies en compatibiliteit.

Null en ontbrekende velden

  • null betekent “geen waarde”: een kaart zonder eigenaar heeft "owner_id": null.
  • Een veld kan in een response ontbreken als het niet van toepassing is op dit object of dit request. In de API-referentie staat welke velden altijd aanwezig zijn.
  • In een PATCH houdt een veld dat je weglaat zijn waarde. Stuur null om een veld leeg te maken waar de referentie zegt dat null is toegestaan.