Betalingskenmerk API: kenmerken ontcijferen vanuit je boekhouding

In het kort

Ontcijferen	`POST https://belastingskenmerk.nl/api/v1/ontcijfer`
Kenmerk berekenen	`POST https://belastingskenmerk.nl/api/v1/kenmerk`
Formaat	JSON in, JSON uit (`Content-Type: application/json`)
Per aanroep	Maximaal 100 kenmerken of aanslagnummers
Limiet	20 aanroepen per minuut en 5.000 per dag per IP-adres
Kosten	Gratis, geen API-sleutel nodig

Privacy: kenmerken bevatten een deel van een BSN of RSIN. De API verwerkt ze alleen om het antwoord te berekenen. Kenmerken, aanslagnummers en antwoorden worden niet gelogd of opgeslagen. We tellen alleen het aantal aanroepen. Stuur ze altijd via POST (zoals hieronder), niet in een URL.

Kenmerken ontcijferen

Stuur één kenmerk met "kenmerk" of meerdere met "kenmerken". Spaties en punten mogen.

POST /api/v1/ontcijfer
{ "kenmerken": ["0036 0000 1130 2270", "2036000016301110"] }

Antwoord:

{
  "resultaten": [
    {
      "invoer": "0036 0000 1130 2270",
      "kenmerk": "0036000011302270",
      "geldig": true,
      "controlecijferKlopt": true,
      "soort": "Aangifte omzetbelasting",
      "middel": "B",
      "omschrijving": "Aangifte omzetbelasting, 3e kwartaal 2023",
      "tijdvak": "3e kwartaal",
      "jaar": 2023,
      "idSoort": "BSN",
      "id": "036000012",
      "aanslagnummer": "036000012B0223270",
      "aanslagnummerOpgemaakt": "0360.00.012.B.0223270"
    },
    …
  ]
}

Is een kenmerk ongeldig, dan is geldig false en staat de reden in fout. De andere kenmerken in dezelfde aanroep worden gewoon verwerkt.

Aanslagnummer naar betalingskenmerk

POST /api/v1/kenmerk
{ "aanslagnummers": ["0360.00.012.L.0123110"] }

{
  "resultaten": [
    {
      "invoer": "0360.00.012.L.0123110",
      "geldig": true,
      "kenmerk": "2036000016301110",
      "soort": "Aangifte loonheffingen",
      "omschrijving": "Aangifte loonheffingen, november 2023",
      "aanslagnummerOpgemaakt": "0360.00.012.L.0123110"
    }
  ]
}

Werkt voor alle belastingen behalve vennootschapsbelasting (letter V): daar staat een herkenningscijfer in het kenmerk dat niet in het aanslagnummer zit.

Voorbeelden

curl

curl -X POST https://belastingskenmerk.nl/api/v1/ontcijfer \
  -H "Content-Type: application/json" \
  -d '{"kenmerk": "0036000011302270"}'

Excel (Power Query)

In Excel: Gegevens → Gegevens ophalen → Uit andere bronnen → Lege query, open de Geavanceerde editor en plak dit. Vervang de kenmerken door een kolom uit je eigen tabel als je dat wilt.

let
    Kenmerken = {"0036000011302270", "2036000016301110"},
    Body = Json.FromValue([kenmerken = Kenmerken]),
    Antwoord = Json.Document(Web.Contents(
        "https://belastingskenmerk.nl/api/v1/ontcijfer",
        [Headers = [#"Content-Type" = "application/json"], Content = Body])),
    Tabel = Table.FromRecords(Antwoord[resultaten], null, MissingField.UseNull)
in
    Tabel

Python

import requests

r = requests.post("https://belastingskenmerk.nl/api/v1/ontcijfer",
                  json={"kenmerken": ["0036000011302270", "2036000016301110"]})
for k in r.json()["resultaten"]:
    print(k["kenmerk"], k.get("soort"), k.get("tijdvak"), k.get("jaar"))

JavaScript

const r = await fetch("https://belastingskenmerk.nl/api/v1/ontcijfer", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ kenmerken: ["0036000011302270"] })
});
const { resultaten } = await r.json();

Foutcodes

`200`	Gelukt. Controleer per resultaat het veld `geldig`.
`400`	Ongeldige JSON, geen kenmerken meegestuurd, meer dan 100 per aanroep of een body groter dan 16 KB.
`405`	Gebruik POST.
`429`	Limiet bereikt: meer dan 20 aanroepen per minuut of 5.000 per dag. Bundel kenmerken (tot 100 per aanroep) om onder de limiet te blijven.

Goed om te weten

De berekening volgt de Specificatie betalingskenmerk bepaling 1.5 van de Belastingdienst, precies zoals de tool op deze site.
Het jaar staat met één cijfer in het kenmerk. De API kiest het meest recente jaar dat past (hooguit volgend jaar).
Belastingskenmerk.nl is geen dienst van de Belastingdienst. De API wordt aangeboden zoals hij is, zonder garantie op beschikbaarheid. Controleer belangrijke betalingen altijd in Mijn Belastingdienst.