Svenska

English

Svenska

English

Appearance

Ekonomi & utbetalningshantering ​

Den här guiden täcker hur du spårar och stämmer av det kapital, ränta, avgifter och provisioner som Amili samlar in för din räkning. När gäldenärer gör betalningar avräknar Amili medlen och skapar ekonomiska poster som du kan fråga via API:et.

Ekonomidata är organiserad på två nivåer:

  • Utbetalningsspecifikationer (finance--payout-specifications) — Transaktionsposter kopplade till enskilda ärenden. Skapas omedelbart när betalningar avräknas.
  • Utbetalningar (finance--payouts) — Aggregerade sammanfattningar grupperade efter kategori och period. Skapas när specifikationer schemaläggs för banköverföring till borgenären.

Alla API-anrop kräver en giltig autentiseringstoken i X-API-Key-headern. För detaljer om autentiseringsprocessen och tokenhantering, se Autentiseringsdokumentationen.

I den här guiden använder vi klassen AuthTokenProvider (dokumenterad i autentiseringsguiden) för att hantera tokens.

Innehållsförteckning

Följ kapital- & avgiftsutbetalningar ​

Det vanligaste användningsfallet är att spåra hur mycket kapital och avgifter som har inkasserats per ärende. Använd endpointen finance--payout-specifications för att få transaktionsposter som kan matchas mot enskilda fakturor.

Ekonomikategorier

Varje specifikation har en finance_category som bestämmer vilken typ av pengar den representerar:

KategoriBeskrivning
capitalDet ursprungliga skuldbeloppet som inkasserats från gäldenären
creditor_outlayAvgifter som borgenären debiterat innan ärendet skickades till Amili (påminnelseavgifter, fakturaavgifter, etc.)
interestRänta debiterad på förfallna betalningar
creditor_commissionProvision intjänad från inkassoprocessen

För avstämning på ärendenivå är capital och creditor_outlay de mest relevanta kategorierna.

typescript
const token = await auth.getValidToken()

const where = encodeURIComponent(
  JSON.stringify({
    creditor: '686e6ed854377058c2dd10bd',
    finance_category: { $in: ['capital', 'creditor_outlay'] },
  })
)
const projection = encodeURIComponent(
  JSON.stringify({
    _id: 1,
    amount: 1,
    total_amount: 1,
    article: 1,
    finance_category: 1,
    invoice_number: 1,
    reference_number: 1,
    booking_date: 1,
    'references.case': 1,
  })
)

const response = await axios.get(
  `https://api-sandbox.amili.se/finance--payout-specifications?where=${where}&projection=${projection}&sort=-_created&max_results=100`,
  {
    headers: {
      'X-API-Key': token,
    },
  }
)
python
import json

token = auth.get_valid_token()

where = json.dumps({
    "creditor": "686e6ed854377058c2dd10bd",
    "finance_category": {"$in": ["capital", "creditor_outlay"]},
})
projection = json.dumps({
    "_id": 1,
    "amount": 1,
    "total_amount": 1,
    "article": 1,
    "finance_category": 1,
    "invoice_number": 1,
    "reference_number": 1,
    "booking_date": 1,
    "references.case": 1,
})

response = requests.get(
    'https://api-sandbox.amili.se/finance--payout-specifications',
    params={
        'where': where,
        'projection': projection,
        'sort': '-_created',
        'max_results': 100,
    },
    headers={'X-API-Key': token}
)
response.raise_for_status()
specifications = response.json()['_items']

Exempelsvar:

json
{
  "_items": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "amount": 2050.0,
      "total_amount": 2050.0,
      "article": "capital",
      "finance_category": "capital",
      "invoice_number": "INV-2025-020",
      "reference_number": "25020",
      "booking_date": "Wed, 11 Jun 2025 00:00:00 GMT",
      "references": { "case": "507f1f77bcf86cd799439050" }
    },
    {
      "_id": "507f1f77bcf86cd799439012",
      "amount": 60.0,
      "total_amount": 60.0,
      "article": "reminder",
      "finance_category": "creditor_outlay",
      "invoice_number": "INV-2025-020",
      "reference_number": "25020",
      "booking_date": "Wed, 11 Jun 2025 00:00:00 GMT",
      "references": { "case": "507f1f77bcf86cd799439050" }
    }
  ],
  "_meta": {
    "page": 1,
    "max_results": 100,
    "total": 2
  }
}

Nyckelfält ​

FältBeskrivning
invoice_numberUrsprungligt fakturanummer från ärenderegistreringen
reference_numberÄrendets referensnummer
references.caseÄrende-ID — använd detta för att korrelera med ärendedata
booking_dateNär kundens betalning avräknades
finance_categorycapital för kapitalbelopp, creditor_outlay för avgifter
articleSpecifik typ: capital, reminder, invoice_fee, late_payment_fee, etc.
amountBelopp exklusive moms
total_amountBelopp inklusive moms

Gruppering per kundbetalning

Använd banking_transaction._id för att identifiera alla specifikationsposter som härrör från samma kundbetalning. Detta är användbart vid avstämning — en enskild banktransaktion kan omfatta flera ärenden om kunden betalat flera fakturor på en gång (t.ex. samlade Kronofogden-betalningar).

Om utbetalningslivscykelfält

Vissa fält fylls i senare i utbetalningslivscykeln och är inte tillgängliga direkt efter avräkning:

  • payout — Sätts när specifikationen kopplas till en utbetalning vid schemaläggning
  • payout_reference — Referensen Amili använder på banköverföringen till borgenären
  • payout_date — Sätts när utbetalningen exporteras till banken

För ärendespårning och avstämning behöver du inte vänta på dessa fält.

Följ intäkter ​

För intäktsrapportering, använd endpointen finance--payouts för att få aggregerade sammanfattningar av ränta och provision intjänad från inkassoprocessen. Dessa utbetalningar grupperas per finance_category och period.

typescript
const token = await auth.getValidToken()

const where = encodeURIComponent(
  JSON.stringify({
    creditor: '686e6ed854377058c2dd10bd',
    finance_category: { $in: ['interest', 'creditor_commission'] },
  })
)

const response = await axios.get(
  `https://api-sandbox.amili.se/finance--payouts?where=${where}&sort=-payout_date&max_results=10`,
  {
    headers: {
      'X-API-Key': token,
    },
  }
)
python
import json

token = auth.get_valid_token()

where = json.dumps({
    "creditor": "686e6ed854377058c2dd10bd",
    "finance_category": {"$in": ["interest", "creditor_commission"]},
})

response = requests.get(
    'https://api-sandbox.amili.se/finance--payouts',
    params={
        'where': where,
        'sort': '-payout_date',
        'max_results': 10,
    },
    headers={'X-API-Key': token}
)
response.raise_for_status()
payouts = response.json()['_items']

Exempelsvar:

json
{
  "_items": [
    {
      "_id": "507f1f77bcf86cd799439098",
      "creditor": "686e6ed854377058c2dd10bd",
      "currency": "SEK",
      "payout_reference": "65432",
      "payout_date": "Fri, 13 Jun 2025 00:00:00 GMT",
      "amount": 3000.0,
      "vat_amount": 0.0,
      "total_amount": 3000.0,
      "summary": {
        "interest": {
          "count": 8,
          "amount": 3000.0,
          "vat_amount": 0.0,
          "total_amount": 3000.0
        }
      },
      "finance_category": "interest",
      "finance_interval": "daily"
    },
    {
      "_id": "507f1f77bcf86cd799439099",
      "creditor": "686e6ed854377058c2dd10bd",
      "currency": "SEK",
      "payout_reference": "65432",
      "payout_date": "Fri, 13 Jun 2025 00:00:00 GMT",
      "amount": 450.0,
      "vat_amount": 112.5,
      "total_amount": 562.5,
      "summary": {
        "reminder": {
          "count": 5,
          "amount": 450.0,
          "vat_amount": 112.5,
          "total_amount": 562.5
        }
      },
      "finance_category": "creditor_commission",
      "finance_interval": "daily"
    }
  ]
}

Fältet summary bryter ner den aggregerade utbetalningen per artikeltyp. Varje utbetalning representerar en enskild finance_category för en given period och borgenär.

Inkrementell hämtning ​

När du bygger ett schemalagt jobb för att periodiskt exportera ekonomidata (t.ex. en daglig cron), rekommenderar vi att filtrera på _created för att bara hämta nya poster sedan din senaste lyckade körning.

typescript
// Store the last successful fetch timestamp
let lastFetchTimestamp = loadLastTimestamp() // e.g., "Wed, 11 Jun 2025 00:00:00 GMT"

const where = encodeURIComponent(
  JSON.stringify({
    creditor: '686e6ed854377058c2dd10bd',
    finance_category: { $in: ['capital', 'creditor_outlay'] },
    _created: { $gte: lastFetchTimestamp },
  })
)

const response = await axios.get(
  `https://api-sandbox.amili.se/finance--payout-specifications?where=${where}&sort=_created&max_results=100`,
  { headers: { 'X-API-Key': token } }
)

// Process and deduplicate by _id (in case of job reruns)
const newRecords = deduplicateById(response.data._items)

// Update timestamp only after successful processing
saveLastTimestamp(new Date().toUTCString())
python
# Store the last successful fetch timestamp
last_fetch_timestamp = load_last_timestamp()  # e.g., "Wed, 11 Jun 2025 00:00:00 GMT"

query = json.dumps({
    "creditor": "686e6ed854377058c2dd10bd",
    "finance_category": {"$in": ["capital", "creditor_outlay"]},
    "_created": {"$gte": last_fetch_timestamp},
})

response = requests.get(
    'https://api-sandbox.amili.se/finance--payout-specifications',
    params={'where': query, 'sort': '_created', 'max_results': 100},
    headers={'X-API-Key': token}
)
response.raise_for_status()

# Process and deduplicate by _id (in case of job reruns)
new_records = deduplicate_by_id(response.json()['_items'])

# Update timestamp only after successful processing
save_last_timestamp(datetime.utcnow().strftime("%a, %d %b %Y %H:%M:%S GMT"))

Varför _created? ​

FältRekommenderatAnledning
_created✅ JaOföränderligt — sätts en gång när posten skapas, ändras aldrig
booking_date⚠️ MöjligtRepresenterar affärsdatumet, inte skapandetiden
payout_date❌ NejFörblir null tills bankexport — poster kan missas under schemaläggning
_updated❌ NejÄndras vid varje uppdatering — kan göra att poster hämtas flera gånger

Idempotens

Deduplicera alltid hämtade poster med _id för att hantera scenarier där jobbet körs flera gånger under samma period, misslyckas mitt i processen eller stöter på nätverksproblem.

Nästa steg ​