Spring til indhold
Forta Pay
English Log ind Book en samtale

Reference

Import

Forta Pay API v1

3 operationer

Batch-import (fakturaer/debitorer/mandater) som JSON-array, OIOUBL eller CSV. Kører som PRØVE (`dry_run=true`) og viser hver difference før den anvendes

POST /imports

Prøven skriver INTET i domænet (ingen debitorer, fakturaer, FI-id'er eller hændelser) — kun importen selv og dens rækker. Hver række får et planlagt udfald: create, exists_identical (nøglen findes med samme indhold → 0 skrivninger), exists_different (nøglen findes med andet indhold → overskrives ALDRIG, blokerer ikke de andre), conflict_owner (fakturaen ejes af det tidligere system eller er lukket ved kilden) eller invalid (med reason_codes). Naturlig nøgle = external_ref. Fakturarækker peger på debitoren med debtor_external_ref (kildens kundenummer) eller debtor_id.

Importerede fakturaer oprettes HOLDT (import_hold): ingen opkrævning, rykker eller udsendelse før skiftets aktivering, og debtor.created/invoice.created udskydes dertil. Apply udsender import.completed.

Bygget: kind ∈ {debtors, invoices} med format ∈ {json, csv}, og kind=mandates med format=bs0603 (total-0603); profile=generic. Resten svarer 422 not_supported_yet med det stykke der bygger det (planned_in). CSV: første linje er feltnavne (total.amount = indlejret felt), skilletegn ; eller ,, tom celle = udeladt.

0603 (BS-mandater ved dataleverandørskift): naturlig nøgle = mandatnummeret (kanonisk, uden foranstillede nuller). Debitoren findes på kundenummeret mod debitorens external_ref (foranstillede nuller ignoreres). Grunde ved invalid: other_pbs (posten tilhører et andet PBS-nr. end kreditorens), no_debtor, ambiguous_debtor (kundenummeret rammer flere debitorer — blokeres, vælges aldrig), mandatnr_invalid. Et mandat med samme nummer der er afsluttet i Forta Pay, genoplives ikke (exists_different, ended_locally). Oprettede mandater er active, uden bankkonto, uden 0605 og HOLDT til skiftet (opkrævning og afmelding svarer 409 mandate_import_hold); mandate.created udskydes. Kreditoren skal have et PBS-nr. (409 bs_not_configured).

dry_run=false validerer OG anvender i samme transaktion. En nyere prøve for samme kreditor og kind gør ældre uanvendte prøver stale.

Parametre

Idempotency-Key

header · string (uuid) · påkrævet

Obligatorisk på alle POST/PATCH/DELETE. Lever 24 timer.

Krop · ImportCreate

creditor_id

string · påkrævet

B8: en import hører til ÉN kreditor

kind

string · påkrævet

invoices · debtors · mandates

format

string · påkrævet

json · oioubl · csv · bs0603

profile

string · valgfri

farpay (SKIFT-4): rækkerne har FarPay-portalens egne kolonnenavne. kind=invoices («InvoiceModels»: InvoiceNumber, CustomerNumber, PaymentStatus, PaymentMethod, PaymentDate = FORFALD, TypeCode, UnpaidAmount, CreatedDate; valgfrit Id, Amount, PaidAmount, Currency, PaymentInfo = FarPays FI-nr., ReminderHistory = som InvoiceCreate.reminder_history) sorteres i klasse B/C (overtages: faktura holdt + ejerskab forta_pay), D (inkasso, FarPay-opkrævning undervejs, saldo afviger fra e-conomic, åben uden rest: kun ejerskab previous_system), F (betalt/markeret betalt/rykker lukket: kun ejerskab closed); kreditnotaer (PCM) → skipped. Beløb er KRONER. kind=debtors («CustomerModels»: CustomerNumber, Name; valgfrit EmailPortal, SmsPhoneNumber, Street, HouseNumber, Address, PostCode, City, Country, Cvr, Gln, Id, PaymentType) — pladsholdere i kontaktfelterne udelades med en grund. kind=mandates → 422 not_supported_yet

generic · farpay

dry_run

boolean · valgfri

content

liste af | string · valgfri

Inline-indhold (≤ 5 MB, ≤ 5.000 rækker): JSON-array af rækker (format=json), CSV-teksten (format=csv) eller en TOTAL-0603 som tekst (format=bs0603, kun med kind=mandates; kun sektion 0210/transkode 0230 — en ændringsfil giver 422 not_a_total_extract). Importerede BS-mandater er aktive hos Betalingsservice, oprettes uden bankkonto og uden 0605, og er holdt til skiftet aktiveres

upload_url_requested

boolean · valgfri

Ikke bygget — 422 not_supported_yet

Svar

201

Prøven er gemt (`validated`) — eller anvendt (`applied`) ved `dry_run=false` · Import

409

`bs_not_configured` — kind=mandates, og kreditoren har intet PBS-nr. · `dpa_required` — R-22: live-kreditor uden accepteret databehandleraftale (ingen importrække gemmes) · Problem

413

`import_too_large` — over 5.000 rækker eller 5 MB. Apply er én transaktion; importen deles ikke op · Problem

422

`invalid_content` (filen kan ikke læses), `not_a_total_extract` (0603 der ikke er et totaludtræk), `not_supported_yet`, `reference_not_found` (kreditoren) eller `validation_failed` · Problem

curl
curl -X POST https://api.fortapay.dk/v1/imports \
  -H "Authorization: Bearer $FP_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "creditor_id": "…",
  "kind": "invoices",
  "format": "json"
}
JSON

Status, valideringsfejl pr. række, resultat

GET /imports/{importId}

stale beregnes live for en uanvendt prøve: er grundlaget ændret siden prøven, vil apply svare 409 import_stale.

Parametre

importId

path · string · påkrævet

Svar

200

OK · Import

404

Findes ikke eller uden for nøglens skop · Problem

curl
curl -X GET https://api.fortapay.dk/v1/imports/{importId} \
  -H "Authorization: Bearer $FP_KEY"

Anvend en valideret prøve-import (scope admin — som i kreditorfladen; pay-sikkerhed2 T6-10)

POST /imports/{importId}/apply

Én transaktion: alt eller intet. Grundlaget (de rækker importen rører) prøves igen under lås; er det ændret siden prøven → 409 import_stale og intet skrives — så giver apply altid samme tal som prøven. Allerede anvendt → 200 og 0 nye skrivninger.

Parametre

importId

path · string · påkrævet

Idempotency-Key

header · string (uuid) · påkrævet

Obligatorisk på alle POST/PATCH/DELETE. Lever 24 timer.

Svar

202

Anvendt nu (`status=applied`) · Import

200

Var allerede anvendt — intet skrevet · Import

404

Findes ikke eller uden for nøglens skop · Problem

409

`import_stale` (grundlaget ændret, eller en nyere prøve findes), `import_invalid`, `import_not_validated` · Problem

curl
curl -X POST https://api.fortapay.dk/v1/imports/{importId}/apply \
  -H "Authorization: Bearer $FP_KEY" \
  -H "Idempotency-Key: $(uuidgen)"