Pikaopas

Aloita Fenerum API:n käyttö muutamassa minuutissa. Tämä opas käy läpi todennuksen perusteet ja ensimmäisten resurssien luomisen.

Peruskäsitteet

Ennen kuin sukellat API:in, ymmärrä nämä keskeiset objektit:

Tili

Tili edustaa asiakastasi—tahoa, jolle laskutat palvelusi. Jokaisella tilillä voi olla useita tilauksia, laskuja ja maksutapoja.

Keskeiset attribuutit:

• code - Oma yksilöllinen tunniste asiakkaalle (esim. CUST001)
• name - Asiakkaan tai yrityksen nimi
• email - Laskutuksen yhteyssähköposti
• type - Joko company tai person

Esimerkki:

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "code": "CUST001",
  "name": "Acme Corporation",
  "email": "billing@acme.com",
  "type": "company"
}

Plan

Plan on tarjoamasi tuote tai palvelu. Ajattele sitä myytävän kokonaisuuden templaattina.

Esimerkkejä:

• "Professional Plan"
• "Enterprise License"
• "Cloud Storage"

Planilla ei itsessään ole hinnastoa—hinnoittelu määritellään PlanTerms-kohdassa.

PlanTerms

PlanTerms määrittelee Planin konkreettiset hinnoittelu- ja laskutusehdot. Yhdellä Planilla voi olla useita ehtoja (esim. kuukausi- vs. vuosihinnoittelu).

Keskeiset attribuutit:

• price - Veloitettava summa
• currency - Valuuttakoodi (USD, EUR, DKK, jne.)
• interval_type - Laskutusjakso: day, month tai year
• interval_count - Jaksojen lukumäärä (esim. 1 kuukausittain, 12 vuosittain)
• backwards_charging - Kun false, veloitus jakson alussa (yleisin). Kun true, veloitus jakson lopussa.

Esimerkki:

{
  "uuid": "plan-terms-uuid",
  "price": "99.00",
  "currency": "USD",
  "interval_type": "month",
  "interval_count": 1,
  "backwards_charging": false,
  "active": true
}

Tilaus

Tilaus edustaa Tilin aktiivista Planin käyttöä. Tässä asiakas ja Plan yhdistyvät.

Keskeiset attribuutit:

• account - Mikä asiakas on tilannut
• terms - Mitä PlanTerms-ehtoja käytetään
• quantity - Yksikköjen määrä (käyttäjäkohtaisessa hinnoittelussa, per seat)
• collection_method - Miten maksu kerätään: invoice, card tai direct_debit
• status - Nykytila: active, cancelled, paused, jne.

Esimerkki:

{
  "uuid": "sub-uuid",
  "account": "CUST001",
  "terms": "plan-terms-uuid",
  "quantity": 5,
  "collection_method": "card",
  "status": "active",
  "current_period_start": "2025-01-01",
  "current_period_end": "2025-02-01"
}

Määritys

Hanki API-tokenisi

1. Siirry kohtaan Settings → Integrations
2. Napsauta Fenerum-osion Create API user
3. Kopioi tokenisi ja säilytä se turvallisesti

Pidä tokenisi salassa! Älä koskaan lisää sitä versionhallintaan tai paljasta sitä selainpuolen koodissa.

Nopea esimerkki

Näin luot asiakkaan ja aloitat laskutuksen:

1. Luo tili

curl -X POST https://app.fenerum.com/api/v1/accounts/ \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "X-Client-System: MyApp" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "CUST001",
    "name": "Acme Corporation",
    "email": "billing@acme.com",
    "type": "company",
    "legal_address": "123 Main Street",
    "legal_zipcode": "12345",
    "legal_city": "Copenhagen",
    "legal_country": "DK"
  }'

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "code": "CUST001",
  "name": "Acme Corporation",
  "email": "billing@acme.com",
  "type": "company"
}

2. Luo tilaus

curl -X POST https://app.fenerum.com/api/v1/subscriptions/ \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "X-Client-System: MyApp" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "CUST001",
    "terms": "YOUR_PLAN_TERMS_UUID",
    "quantity": 5,
    "collection_method": "invoice",
    "start_date": "2025-01-01"
  }'

{
  "uuid": "sub-uuid",
  "account": "CUST001",
  "terms": "YOUR_PLAN_TERMS_UUID",
  "quantity": 5,
  "collection_method": "invoice",
  "status": "active",
  "current_period_start": "2025-01-01",
  "current_period_end": "2025-02-01"
}

Seuraavat vaiheet

Nyt kun perusasiat ovat hallussa, tutustu näihin oppaisiin:

• Integration Workflows - Valitse liiketoimintaasi sopiva integraatiotapa
• Authentication - Opi vaadittavista otsakkeista ja tietoturvan parhaista käytännöistä
• Accepting Payments - Integroi Stripe tai QuickPay maksujen keräämistä varten
• API Reference - Täydellinen päätepisteiden dokumentaatio

Usein kysytyt kysymykset

Miten löydän Planin UUID:n?

Käytä Plans-päätepistettä:

curl https://app.fenerum.com/api/v1/plans/ \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "X-Client-System: MyApp"

Vastaus sisältää kaikki Planit ja niihin liittyvät PlanTerms-objektit UUID-arvoineen.

Mitä eroa on code- ja uuid-kentillä?

• code - Oma, valitsemasi tunniste resurssille
• uuid - Fenerumin järjestelmän generoima yksilöllinen tunniste

Voit käyttää kumpaa tahansa API-pyynnöissä, mutta code on usein kätevämpi, koska hallitset sitä itse.

Tarvitsetko apua?

Ota yhteyttä tukeemme tai tutustu koko API-dokumentaatioon.