Pikaopas kehittäjille

Tämä opas näyttää miten pääset alkuun Kirjapro API:n kanssa.

Yleiskatsaus

Kirjapro API perustuu Supabase Edge Functionsiin. Tarvitset:

1. Access Token - JWT-token autentikointiin
2. API Key - Supabase anon key

Autentikointi

Token-rakenne

Kaikki API-pyynnöt vaativat kaksi headeria:

Authorization: Bearer <access_token>
apikey: <supabase_anon_key>

Tokenin hankinta

Access token saadaan Supabase Auth -kirjautumisen yhteydessä:

import { createClient } from '@supabase/supabase-js';

const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY);

// Kirjautuminen
const { data: { session } } = await supabase.auth.signInWithPassword({
  email: 'user@example.com',
  password: 'password'
});

// Token käyttöön
const accessToken = session?.access_token;

Ensimmäinen API-kutsu

cURL

curl -X POST \
  "https://<project>.supabase.co/functions/v1/send-einvoice" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "apikey: $SUPABASE_ANON_KEY" \
  -H "Content-Type: application/json" \
  -d '{"invoiceId": "uuid-here"}'

JavaScript

const response = await fetch(
  `${SUPABASE_URL}/functions/v1/send-einvoice`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'apikey': SUPABASE_ANON_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ invoiceId: 'uuid-here' }),
  }
);

const result = await response.json();

Vastausten käsittely

Onnistunut vastaus

{
  "success": true,
  "data": {
    "id": "invoice-uuid",
    "status": "SENT"
  }
}

Virheellinen vastaus

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Virheellinen laskun ID"
  }
}

Vinkki

Tarkista aina success-kenttä ennen datan käsittelyä.

Webhookin rekisteröinti

Webhookit mahdollistavat reaaliaikaiset ilmoitukset tapahtumista.

1. Määritä HTTPS-endpoint palvelimellesi
2. Rekisteröi webhook Kirjapron asetuksissa
3. Tallenna webhook-salaisuus allekirjoitusten varmistamiseen
4. Käsittele tapahtumat endpointissasi

// Webhook-käsittelijä (Express)
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-kirjapro-signature'];

  // Varmista allekirjoitus
  const expected = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (signature !== expected) {
    return res.status(401).send('Invalid signature');
  }

  // Käsittele tapahtuma
  const { event, data } = req.body;
  console.log(`Received ${event}:`, data);

  res.status(200).send('OK');
});

Rate Limiting

API:lla on pyyntörajoitukset:

Endpoint	Raja
send-einvoice	10 / min
generate-*-pdf	20 / min
checkout/portal	5 / min

Rajoituksen ylittyessä saat 429 Too Many Requests -vastauksen.

Seuraavat askeleet

• Autentikointi - Syvempi katsaus JWT-tokeneihin
• Webhookit - Kaikki tapahtumatyypit
• API-referenssi - Täydellinen endpoint-listaus
• Finvoice - Verkkolaskustandardi
• SEPA - Pankkistandardit

Tuki

Ongelmia? Ota yhteyttä: tuki@kirjapro.fi