REST API

De Corlega REST API laat je programmatisch contacten beheren, offertes en facturen ophalen of aanmaken, en de status van je organisatie raadplegen.

Base URL

https://api.corlega.com/v1

Alle endpoints vereisen HTTPS.

Authenticatie

Corlega gebruikt bearer tokens in de Authorization header. Elke API-key is per organisatie en heeft één of meer scopes die bepalen welke endpoints aangeroepen mogen worden.

Een API-key aanmaken

1. Dashboard → Organisatie → Instellingen → API-keys → Nieuwe key
2. Geef de key een naam (bv. "Productie", "n8n-koppeling")
3. Kies de scopes (zie hieronder)
4. Optioneel: vervaldatum
5. Kopieer de key direct. wordt maar één keer getoond
6. Bewaar veilig (1Password, Vault, etc.)

Token-format

corlega_<32 url-safe chars>

We slaan je key nooit raw op. alleen een scrypt-hash. Als je de key kwijt bent, moet je een nieuwe genereren.

Voorbeeld-request

curl https://api.corlega.com/v1/contacts \
  -H "Authorization: Bearer corlega_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Scopes

Elke key heeft minimaal één scope. Wildcards worden ondersteund.

Key-rotatie

Roteer je keys minstens jaarlijks of bij verdenking van compromise. In het dashboard kun je:

• Nieuwe key aanmaken. beide keys werken parallel tot je de oude revoket
• Bestaande key revoken. direct ongeldig, geen grace-period

Endpoints

Contacts

Alle paden zijn relatief aan de base URL https://api.corlega.com/v1.

Quotes

Invoices

Paginatie

Lijst-endpoints zijn paginated. Default 25 items per pagina, max 100.

curl "https://api.corlega.com/v1/contacts?page=2&pageSize=50" \
  -H "Authorization: Bearer corlega_..."

Response:

{
  "data": [...],
  "meta": {
    "page": 2,
    "pageSize": 50,
    "total": 247,
    "hasMore": true
  }
}

Errors

Alle errors hebben dezelfde shape:

{
  "error": {
    "code": "insufficient_scope",
    "message": "Missing required scope: invoices.write."
  }
}

Status codes

Rate limits

120 requests per minuut per API-key (sliding window). Bij overschrijding krijg je 429 Too Many Requests met een Retry-After-header in seconden.

Implementeer in je client een exponential backoff:

async function withRetry(fn, maxAttempts = 5) {
  for (let i = 0; i < maxAttempts; i++) {
    try {
      return await fn();
    } catch (err) {
      if (err.status !== 429 || i === maxAttempts - 1) throw err;
      const retryAfter = parseInt(err.headers["retry-after"] ?? "1");
      await new Promise(r => setTimeout(r, retryAfter * 1000));
    }
  }
}

Versioning

Alle endpoints draaien onder https://api.corlega.com/v1/. Bij breaking changes komt een https://api.corlega.com/v2/-versie, en v1 blijft minstens 12 maanden actief met Deprecation-header in de responses.

Legacy: corlega.com/api/v1/*

Tot je migratie naar api.corlega.com blijven de oude endpoints onder https://corlega.com/api/v1/* werken. exact dezelfde routes en gedrag. Voor nieuwe integraties: gebruik api.corlega.com.

SDK's

Officiële SDK's: nog niet. Op de roadmap voor Q4 2026.

Voor nu raden we aan: gebruik je platform's HTTP-client (Node fetch, Python httpx, etc.). De API is bewust simpel gehouden zodat handcoded wrappers triviaal zijn.

Voorbeeld: contact aanmaken

const res = await fetch("https://api.corlega.com/v1/contacts", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.CORLEGA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Bouwbedrijf De Vries B.V.",
    email: "info@devries-bouw.nl",
    phone: "06 12345678",
    kvkNumber: "12345678",
    type: "business",
  }),
});

if (!res.ok) {
  const body = await res.json();
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const { data: contact } = await res.json();
console.log("Aangemaakt:", contact.id);

Voorbeeld: alle offertes ophalen

async function* allQuotes(apiKey) {
  let page = 1;
  while (true) {
    const res = await fetch(
      `https://api.corlega.com/v1/quotes?page=${page}&pageSize=100`,
      { headers: { Authorization: `Bearer ${apiKey}` } },
    );
    const { data, meta } = await res.json();
    for (const quote of data) yield quote;
    if (!meta.hasMore) break;
    page++;
  }
}

for await (const quote of allQuotes(process.env.CORLEGA_API_KEY)) {
  console.log(quote.number, quote.status, quote.total);
}

Volgende stap

• Webhooks. krijg push-notificaties wanneer events plaatsvinden
• Troubleshooting. als iets niet werkt