Exempel på finansiella utbetalningar

Denna guide visar hur du arbetar med finansiella utbetalningar och utbetalningsspecifikationer i Amili API. Finansiell data är organiserad i en förälder-barn-relation:

Finance Payouts - Aggregerade utbetalningssammanfattningar till borgenärer
Finance Payout Specifications - Detaljerad transaktionsnivådata kopplad till individuella ärenden

Alla API-requests kräver en giltig autentiseringstoken i X-API-Key header. För detaljer om autentiseringsprocessen och tokenhantering, se Authentication documentation.

I denna guide kommer vi att använda AuthTokenProvider-klassen (dokumenterad i autentiseringsguiden) för att hantera tokenhantering.

Finanskategorier

Fältet finance_category avgör vilken typ av finansiell data som representeras:

Kategori	Beskrivning	Vanliga artiklar
`capital`	Kapitalbelopp som inkasseras	`capital`
`interest`	Ränta som debiterats på förfallna betalningar	`interest`
`creditor_commission`	Provision som borgenären tjänar från inkasso	`reminder`, `debt_collection`
`creditor_outlay`	Avgifter/kostnader som borgenären lagt till före ärenderegistrering	`reminder`, `invoice_fee`, `late_payment_fee`, `verdict_fee`, `enforcement`

Artikeltyper för creditor_outlay

reminder - Påminnelseavgifter som debiterats innan ärendet skickades till Amili
invoice_fee - Fakturaavgifter som inkluderats i kapital
late_payment_fee - Förseningsavgift (endast B2B, typiskt 450 SEK)
verdict_fee - Domslutskostnad (betalas kvartalsvis när den mottas)
enforcement - Utmätningsavgift (betalas när Kronofogden bekräftar betalning)

Välja rätt endpoint

Detaljnivån och användningsområdet avgör vilken endpoint som ska användas:

Användningsområde	Endpoint	Finanskategorier
Intäktsuppföljning	GET /finance--payouts	`interest`, `creditor_commission`
Ärende-/fakturauppföljning	GET /finance--payout-specifications	`capital`, `creditor_outlay`
Aggregerade utbetalningssummor	GET /finance--payouts	Alla kategorier
Fakturanivå-avstämning	GET /finance--payout-specifications	Alla kategorier

Scenario 1: Intäktsuppföljning - Ränta & Provisioner

Följ intäkter från inkasso genom att hämta utbetalningar för ränta på förfallna betalningar och intjänade provisioner. Detta är användbart för intäktsrapportering och mätning av inkassoprestanda.

TypeScriptPython

typescript

const token = await auth.getValidToken()

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

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

const payouts = response.data._items

python

import json

token = auth.get_valid_token()

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

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

Svar:

json

{
  "_items": [
    {
      "_id": "507f1f77bcf86cd799439098",
      "_created": "Fri, 13 Jun 2025 08:00:00 GMT",
      "_updated": "Fri, 13 Jun 2025 08:00:00 GMT",
      "_etag": "b2c3d4e5f67890123456789012345678",
      "creditor": "686e6ed854377058c2dd10bd",
      "currency": "SEK",
      "payout_reference": "65432",
      "ready_for_payout": true,
      "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",
      "finance_period_start_date": "Thu, 12 Jun 2025 00:00:00 GMT",
      "finance_period_end_date": "Thu, 12 Jun 2025 23:59:59 GMT",
      "finance_period_day": 163
    },
    {
      "_id": "507f1f77bcf86cd799439099",
      "_created": "Fri, 13 Jun 2025 08:00:00 GMT",
      "_updated": "Fri, 13 Jun 2025 08:00:00 GMT",
      "_etag": "a1b2c3d4e5f678901234567890123456",
      "creditor": "686e6ed854377058c2dd10bd",
      "currency": "SEK",
      "payout_reference": "65432",
      "ready_for_payout": true,
      "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",
      "finance_period_start_date": "Thu, 12 Jun 2025 00:00:00 GMT",
      "finance_period_end_date": "Thu, 12 Jun 2025 23:59:59 GMT",
      "finance_period_day": 163
    }
  ]
}

Svaret visar utbetalningar separerade efter finance_category. Fältet summary bryter ner belopp per artikeltyp inom den kategorin.

Scenario 2: Ärendeuppföljning - Kapital & Borgenärsutlägg

Följ kapitalbelopp och avgifter/kostnader som inkluderades i kapitalfordran vid ärenderegistrering. Detta möjliggör fakturanivå-avstämning och spårning av ursprunglig fordringsstruktur.

Kategorin capital representerar kapitalbeloppet, medan creditor_outlay representerar avgifter som borgenären redan debiterat innan ärendet skickades till Amili (såsom påminnelseavgifter eller fakturaavgifter). Dessa avgifter specificeras vid ärenderegistrering med fees_included_in_capital_to_claim och fees_already_claimed - se Case Flow Example för detaljer.

Datatillgänglighet

Utbetalningsspecifikationer skapas omedelbart när betalningar avräknas. All ärenderelaterad data (invoice_number, reference_number, references.case, belopp) är tillgänglig direkt efter avräkning.

Vissa fält läggs till senare i utbetalningslivscykeln:

payout - Sätts när specifikationen länkas till en utbetalning vid schemaläggning
payout_reference - Kaskaderas från den länkade utbetalningen
payout_date - Sätts när utbetalningen exporteras till banken

För ärendeuppföljning behöver du inte vänta på dessa fält.

TypeScriptPython

typescript

const token = await auth.getValidToken()

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

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

const specifications = response.data._items

python

import json

token = auth.get_valid_token()

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

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()
specifications = response.json()['_items']

Svar:

json

{
  "_items": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "_created": "Wed, 11 Jun 2025 12:00:00 GMT",
      "_updated": "Wed, 11 Jun 2025 12:00:00 GMT",
      "_etag": "c1d2e3f4567890123456789012345678",
      "creditor": "686e6ed854377058c2dd10bd",
      "currency": "SEK",
      "amount": 2050.0,
      "vat_amount": 0.0,
      "total_amount": 2050.0,
      "article": "capital",
      "state": "reminder",
      "booking_date": "Wed, 11 Jun 2025 00:00:00 GMT",
      "finance_category": "capital",
      "invoice_number": "INV-2025-020",
      "reference_number": "25020",
      "references": {
        "case": "507f1f77bcf86cd799439050"
      }
    },
    {
      "_id": "507f1f77bcf86cd799439012",
      "_created": "Wed, 11 Jun 2025 12:00:00 GMT",
      "_updated": "Wed, 11 Jun 2025 12:00:00 GMT",
      "_etag": "d2e3f45678901234567890123456789a",
      "creditor": "686e6ed854377058c2dd10bd",
      "currency": "SEK",
      "amount": 60.0,
      "vat_amount": 0.0,
      "total_amount": 60.0,
      "article": "reminder",
      "state": "reminder",
      "booking_date": "Wed, 11 Jun 2025 00:00:00 GMT",
      "finance_category": "creditor_outlay",
      "invoice_number": "INV-2025-020",
      "reference_number": "25020",
      "references": {
        "case": "507f1f77bcf86cd799439050"
      }
    },
    {
      "_id": "507f1f77bcf86cd799439013",
      "_created": "Tue, 10 Jun 2025 14:00:00 GMT",
      "_updated": "Tue, 10 Jun 2025 14:00:00 GMT",
      "_etag": "e3f456789012345678901234567890ab",
      "creditor": "686e6ed854377058c2dd10bd",
      "currency": "SEK",
      "amount": 1500.0,
      "vat_amount": 0.0,
      "total_amount": 1500.0,
      "article": "capital",
      "state": "reminder",
      "booking_date": "Tue, 10 Jun 2025 00:00:00 GMT",
      "finance_category": "capital",
      "invoice_number": "INV-2025-019",
      "reference_number": "25019",
      "references": {
        "case": "507f1f77bcf86cd799439051"
      }
    }
  ],
  "_meta": {
    "page": 1,
    "max_results": 100,
    "total": 3
  }
}

Varje specifikation inkluderar:

Fält	Beskrivning
`invoice_number`	Ursprungligt fakturanummer från ärenderegistrering
`reference_number`	Ärendets referensnummer för spårning
`references.case`	Länk till ärendedokumentet
`booking_date`	Kundbetalningsdatum - när slutkundens betalning registrerades/avräknades
`finance_category`	`capital` för kapitalbelopp, `creditor_outlay` för avgifter/kostnader
`article`	Specifik transaktionstyp (capital, reminder, invoice_fee, etc.)
`amount`	Belopp exklusive moms
`total_amount`	Belopp inklusive moms

Posterna med creditor_outlay motsvarar avgifter som specificerades vid ärenderegistrering i fees_already_claimed (t.ex. påminnelseavgifter som debiterats innan ärendet skickades till Amili).

Gruppering per kundbetalning

Använd banking_transaction._id för att identifiera alla specifikationsposter som härstammar från samma kundbetalning. Detta är användbart när du behöver avstämma betalningar i ditt system och vill gruppera poster (kapital, avgifter) som betalades tillsammans av kunden.

Observera: En enda banking_transaction kan omfatta flera ärenden om kunden betalade flera fakturor i en betalning (t.ex. samlade Kronofogden-betalningar).

Om payout_reference

Fältet payout_reference är den referens Amili använder vid utbetalning till borgenären - inte kundens betalningsreferens. Exempel inkluderar "Utbetalning kapital från Amili" eller "Utbetalning provision på inkassoavgifter". Detta fält sätts när specifikationen kopplas till en utbetalning.

Tips: Inkrementell datahämtning

När du bygger schemalagda jobb (t.ex. dagliga cron-jobb) för att hämta finansiell data, använd fältet _created för inkrementell hämtning:

TypeScriptPython

typescript

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

const query = 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=${query}&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 använda `_created` istället för andra datumfält?

Fält	Rekommenderat	Anledning
`_created`	✅ Ja	Oföränderligt, sätts när posten skapas, ändras aldrig
`booking_date`	⚠️ Möjligt	Sätts vid avräkning, men representerar affärsdatum inte skapandetid
`payout_date`	❌ Nej	Förblir `null` tills bankexport - poster skulle missas under schemaläggningsfasen
`_updated`	❌ Nej	Ändras vid varje uppdatering - kan orsaka att poster hämtas flera gånger

Idempotensmönster

Deduplicera alltid hämtade poster med _id för att hantera scenarier där:

Jobbet körs flera gånger under samma period
Jobbet misslyckades mitt i processen och behöver köras om
Nätverksproblem orsakade partiell bearbetning

Relaterad dokumentation

Finance Payout Endpoint
Finance Payout Specification Endpoint
Case Flow Example - Hur avgifter läggs till vid ärenderegistrering

Exempel på finansiella utbetalningar ​

Finanskategorier ​

Välja rätt endpoint ​

Scenario 1: Intäktsuppföljning - Ränta & Provisioner ​

Scenario 2: Ärendeuppföljning - Kapital & Borgenärsutlägg ​

Tips: Inkrementell datahämtning ​

Varför använda _created istället för andra datumfält? ​

Relaterad dokumentation ​

Exempel på finansiella utbetalningar

Finanskategorier

Välja rätt endpoint

Scenario 1: Intäktsuppföljning - Ränta & Provisioner

Scenario 2: Ärendeuppföljning - Kapital & Borgenärsutlägg

Tips: Inkrementell datahämtning

Varför använda `_created` istället för andra datumfält?

Relaterad dokumentation