Naar de inhoud
Documentatie
Handleiding API Demo
Nederlands
De applicatie openen

De licentie raadplegen

Use case stap voor stap om de licentie van een kantoor via de API te lezen, de plafonds en de maandelijkse raming te kennen en een activeringssleutel te activeren.

Bijgewerkt op 05-10-2026 Deze pagina bewerken

De licentie van een kantoor bepaalt zijn formule, zijn plafonds voor dossiers en gebruikers en zijn facturatieraming. Uw integratie kan ze lezen om na te gaan of er nog een dossier kan worden aangemaakt, of om het verbruik in een dashboard te tonen.

Vereisten: een token met de bevoegdheid read, in het bezit van een lid van het kantoor, en de public_token van het kantoor. Voor het activeren van een sleutel zijn bovendien write en de rol van beheerder of manager nodig.

Stap 1: de licentie lezen

curl "https://api.novafisko.com/v1/firms/Fd7hQ2mN8sXa/licence?lang=fr" \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN"

{
  "status": "active",
  "subscription": {
    "id": 31,
    "status": "active",
    "billing_interval": "monthly",
    "current_period_start": "2026-10-01",
    "current_period_end": "2026-10-31",
    "trial_ends_at": null,
    "source": "licence_key",
    "billed": true,
    "pilot": {"active": false, "until": null}
  },
  "plan": {
    "code": "firm",
    "name": "Cabinet",
    "kind": "firm",
    "features": ["peppol", "document_import", "bank"],
    "base_price_monthly": 49.0,
    "tiers": [{"from": 1, "to": 10, "unit_price": 9.0}, {"from": 11, "to": null, "unit_price": 7.0}],
    "max_companies": null,
    "peppol_fair_use_per_company": 200,
    "annual_discount_pct": 10.0
  },
  "usage": {
    "month": "2026-10",
    "companies": 12,
    "users": 4,
    "bank_accounts": 15,
    "rows": [
      {"company_id": 318, "token": "k3Jd9fPq2LmX", "name": "Le Comptoir Montois SRL", "code": "COMPTOIR", "bank_accounts": 2, "status": "active", "activated_at": "2026-01-06T09:00:00+00:00", "deactivated_at": null}
    ],
    "max_companies": 25,
    "over_limit": false,
    "suggestion": null
  },
  "estimate": {
    "month": "2026-10",
    "base": 49.0,
    "companies_breakdown": [
      {"from": 1, "to": 10, "quantity": 10, "unit_price": 9.0, "total": 90.0},
      {"from": 11, "to": null, "quantity": 2, "unit_price": 7.0, "total": 14.0}
    ],
    "options": [],
    "discount": 0.0,
    "subtotal": 153.0,
    "vat_rate": 21.0,
    "vat_amount": 32.13,
    "total_incl_vat": 185.13,
    "billed": true
  },
  "next_month_preview": {"companies": 12, "total": 153.0},
  "over_limit": false,
  "limits": {"max_users": 10, "max_companies": 25, "users_count": 4, "companies_count": 12},
  "expires_at": "2027-09-30",
  "warning": null,
  "activation": {
    "key_masked": "NF-••••-••••-••••-7K2Q",
    "activated_at": "2026-01-06T08:55:12+00:00",
    "valid_until": "2027-09-30",
    "services": ["peppol", "document_import"]
  },
  "statements": [
    {"id": 904, "reference": "NF-2026-09-0031", "kind": "monthly", "period": "2026-09", "subtotal": 146.0, "vat_amount": 30.66, "total": 176.66, "status": "paid", "issued_at": "2026-10-01", "paid_at": "2026-10-03"}
  ],
  "options_available": [
    {"code": "extra_bank_account", "name": "Compte bancaire supplémentaire", "price_monthly": 2.0, "unit": "par compte"}
  ],
  "can_manage": true
}

Het antwoord is ingekort: het bevat ook entitlements, companies_detail, comparison en enkele historische velden die voor de oude versies van de applicaties worden behouden. De bovenstaande cijfers zijn voorbeelden: de echte tarieftabel wordt gepubliceerd door GET /v1/pricing.

Nuttige velden voor een integratie

Veld Gebruik
status none als het kantoor geen bruikbaar abonnement heeft, anders de status van het abonnement
limits.max_companies, limits.companies_count Weten of er nog plaats is voor een nieuw dossier. null betekent zonder plafond
limits.max_users, limits.users_count Zelfde logica voor de medewerkers
over_limit Het kantoor overschrijdt het plafond van zijn formule
expires_at Einde van de geldigheid van de activeringssleutel, null zonder sleutel
warning Te tonen waarschuwing (nabije vervaldag, overschrijding), anders null
estimate Raming van de lopende maand, exclusief btw en inclusief btw
can_manage De gebruiker kan een sleutel activeren of vrijgeven
Opmerking

De bedragen van de licentie zijn JSON-getallen en geen strings. Het gaat om commerciële bedragen en niet om boekingen. Zie Conventies.

Een gebruiker die geen lid is van het kantoor krijgt 404.

Stap 2: controleren voordat u een dossier aanmaakt

def can_add_company(licence):
    limits = licence["limits"]
    if limits["max_companies"] is None:
        return True  # no ceiling on this plan
    return limits["companies_count"] < limits["max_companies"]

Als u toch een dossier aanmaakt terwijl het plafond is bereikt, antwoordt POST /v1/companies 422 met de code company_limit_reached. Op dezelfde manier antwoordt het toevoegen van een medewerker boven het plafond 422 met user_limit_reached.

Stap 3: een sleutel activeren

Een activeringssleutel heeft de vorm NF-XXXX-XXXX-XXXX-XXXX. Hij kent een formule, opties en plafonds toe voor een bepaalde duur.

curl -X POST https://api.novafisko.com/v1/firms/Fd7hQ2mN8sXa/licence/activate \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "NF-8H2K-P4QM-7TZD-7K2Q"}'

Bij succes is het antwoord 200 de bijgewerkte licentie, in dezelfde vorm als in stap 1. Bij een weigering is het antwoord 422:

{
  "message": "Cette clé d'activation a expiré.",
  "code": "expired_key",
  "errors": {"key": ["Cette clé d'activation a expiré."]}
}
code Betekenis
invalid_key Onbekende of verkeerd ingevoerde sleutel
expired_key Vervallen sleutel
exhausted_key Toegestaan aantal activeringen al bereikt
key_reserved Sleutel voorbehouden aan een ander kantoor
already_active Sleutel al actief op dit kantoor

De route is beperkt tot 10 pogingen per minuut.

Een sleutel vrijgeven

curl -X DELETE https://api.novafisko.com/v1/firms/Fd7hQ2mN8sXa/licence/activation \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN"

De sleutel wordt opnieuw beschikbaar en het abonnement dat ervan afhangt, wordt opgezegd. Het antwoord is de bijgewerkte licentie.

Let op

Het activeren en het vrijgeven van een sleutel zijn geblokkeerd in het demokantoor (403, code demo_mode).

Publieke tarieftabel

Twee publieke routes, zonder authenticatie, voeden een simulator:

curl https://api.novafisko.com/v1/pricing
curl "https://api.novafisko.com/v1/pricing/simulate?companies=12"

Hun gedetailleerde schema staat in de referentie.

Zie ook