Documentatie — API, widget en domeinen

Documentatie

Genoeg om te koppelen zonder ons te bellen — en genoeg context om te begrijpen waarom het zo is opgezet.

Basisprincipe

De website van de klant is alleen de ingang. Alle prijzen, regels, AI en gegevens blijven op onze servers. De browser identificeert zich met een publieke identifier en werkt daarna met een kortlevende sessie; server-to-server gebruikt een privaat credential.

Versionering

Alle endpoints staan onder /api/v1/. Een wijziging die bestaande integraties zou breken, krijgt een nieuwe versie.

Publieke API

Voor de browser. Een sessie is enkele minuten geldig en draagt uitsluitend smalle scopes: quote:create, quote:read:self, photo:upload en ai:request. Nooit tenant- of adminbeheerrechten.

Methode	Endpoint	Doel
POST	`/api/v1/public/session`	Opent een kortlevende sessie met een publieke identifier.
GET	`/api/v1/public/config`	Branding, publieke catalogus, features en juridische links.
POST	`/api/v1/public/quote`	Maakt of berekent een aanvraag binnen de sessie.
POST	`/api/v1/public/photo`	Uploadt een foto bij het project van de sessie.
POST	`/api/v1/public/ai-job`	Start een AI-taak: maatinschatting of visualisatie.

Sessie openen

curl -X POST "https://favium.be/api/v1/public/session" \
  -H "content-type: application/json" \
  -d '{ "public_key": "pub_live_xxxxx" }'

# antwoord
{ "session_token": "ses_…", "expires_in": 900,
  "scopes": ["quote:create", "photo:upload", "ai:request"] }

Tenant-API

Server-to-server, met een privaat credential in de authorization-header. Beschikbaar vanaf de plannen met API-toegang.

Methode	Endpoint	Doel
GET	`/api/v1/tenant/me`	Gegevens van de omgeving, plan en entitlements.
GET	`/api/v1/tenant/products`	De publiceerbare catalogus.
GET	`/api/v1/tenant/quotes`	Offertes met status en totalen.
GET	`/api/v1/tenant/leads`	Leads met score en pipelinestatus.

Webhooks

Ondertekende payloads met timestamp, idempotency-sleutel en herhaalpogingen.

quote.created — een aanvraag is aangemaakt
quote.completed — de berekening is rond
lead.created — er is een lead ontstaan
technical_review.required — er is technische controle nodig
subscription.updated — het abonnement is gewijzigd
integration.updated — een credential of domein is gewijzigd

Verifieer de handtekening met het endpoint-secret voordat u een payload verwerkt, en gebruik de idempotency-sleutel om dubbele verwerking te voorkomen.

Eigen domein

Zet één CNAME-record; de rest gebeurt automatisch.

DNS-record

# type  naam      waarde
CNAME   offerte   domains.favium.be

Status	Betekenis
DNS_PENDING	Het record is nog niet gevonden.
DNS_VERIFIED	Het record wijst correct naar het platform.
SSL_PENDING	Het certificaat wordt aangevraagd.
ACTIVE	Het domein is bereikbaar en beveiligd.
FAILED	De controle is mislukt; de melding staat bij het domein.

Fouten

Elke fout komt terug als JSON met een stabiele code.

Status	Code	Betekenis
400	`bad_request`	Ongeldige of ontbrekende invoer.
401	`unauthorized`	Geen geldige sessie of credential.
403	`forbidden`	Ontbrekende scope, rol of niet-toegestane origin.
404	`not_found`	Onbekend endpoint of object.
429	`rate_limited`	Te veel aanvragen; probeer het later opnieuw.
500	`server_error`	Interne fout; details staan in onze logs, niet in het antwoord.