Finanzierer-API von Advanta

GET/v1/health

Ob die API läuft. Öffentlich: kein Schlüssel, keine Daten, kein Datenbankzugriff.

Scope

Keiner: öffentlich, ohne Schlüssel

Antwort

200{ status, api_version, time }

Fehler

Keine

Advanta ruft diese Route alle 5 Minuten ab; die Ergebnisse stehen auf der öffentlichen Statusseite.

curl -s "$BASE/v1/health"

GET/v1/me

Wer aufruft: der Schlüssel, sein Finanzierer, seine Umgebung und seine Scopes.

Scope

Jeder gültige Schlüssel

Antwort

200{ api_version, environment, funder, key }

Fehler

405method_not_allowed

key.prefix sind die ersten 12 Zeichen des Schlüssels. key.expires_at ist null für einen Schlüssel ohne Ablauf; key.prospect nennt, an wen ein Sandbox-Schlüssel ausgestellt wurde.

curl -s "$BASE/v1/me" \
  -H "Authorization: Bearer $ADVANTA_KEY"

{
  "api_version": "2026-09-23",
  "environment": "sandbox",
  "funder": {
    "bank_id": "6d164c92-02cc-4f9a-ae8d-3f7f5ef043d3",
    "name": "Compartment Demo (LU)"
  },
  "key": {
    "id": "0b3c6a52-5d0e-4b53-9d0e-1c2b3a4d5e6f",
    "name": "sandbox · Example prospect",
    "prefix": "adv_fk_1a2b3",
    "scopes": ["requests:read", "limits:read", "webhooks:write"],
    "created_at": "2026-09-23T18:00:00Z",
    "expires_at": "2026-10-07T18:00:00Z",
    "prospect": "Example prospect"
  }
}

GET/v1/requests

Die an Sie weitergeleiteten Anfragen (Sie können darauf handeln) und die, auf die Sie bereits gehandelt haben (nur lesend, auch nach einer Weiterleitung an andere), neueste zuerst, jeweils mit Ihrem eigenen Angebot in my_offer, falls Sie eines abgegeben haben.

Scope

requests:read

Antwort

200{ funder, count, requests[] }

Fehler

Nur die allgemeinen (401, 403, 500).

Eine Anfrage enthält id, request_ref, type (factoring oder confirming), status, total_amount, advance_amount, den Verkäufer in company_name und company_nif, invoice_count, assigned_bank_id, consent_level_required (was jeder Schuldner vor der Auszahlung unterschreiben muss, bei der Weiterleitung festgelegt), ihre Zeitstempel und, je Schuldner, debtor_consent. Die Spezifikation listet jedes Feld.

curl -s "$BASE/v1/requests?status=all&limit=50" \
  -H "Authorization: Bearer $ADVANTA_KEY"

const BASE = 'https://bzsengbmlzzhztjfvcag.supabase.co/functions/v1/funder-api';
const headers = { Authorization: `Bearer ${process.env.ADVANTA_KEY}` };

const res = await fetch(`${BASE}/v1/requests?status=open&limit=200`, { headers });
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const { funder, requests } = await res.json();

// Routed to you (you can act on them) and not priced by you yet
const toPrice = requests.filter((r) => r.assigned_bank_id === funder.bank_id && !r.my_offer);
for (const r of toPrice) console.log(r.request_ref, r.type, r.total_amount, r.company_name);

{
  "funder": {
    "bank_id": "6d164c92-02cc-4f9a-ae8d-3f7f5ef043d3",
    "name": "Compartment Demo (LU)"
  },
  "count": 1,
  "requests": [
    {
      "id": "4c1e0d2a-8f3b-4f6e-9a55-3c2b1d0e9f87",
      "request_ref": "FR-2026-0042",
      "type": "factoring",
      "status": "terms_sent",
      "total_amount": 18450.00,
      "company_name": "Example Seller, S.L.",
      "invoice_count": 3,
      "assigned_bank_id": "6d164c92-02cc-4f9a-ae8d-3f7f5ef043d3",
      "consent_level_required": "acknowledgment",
      "created_at": "2026-09-22T09:12:00Z",
      "my_offer": {
        "funding_request_id": "4c1e0d2a-8f3b-4f6e-9a55-3c2b1d0e9f87",
        "rate": 2.4,
        "advance_pct": 90,
        "days": 60,
        "status": "pending",
        "submitted_at": "2026-09-23T10:30:00Z",
        "accepted_at": null
      },
      "debtor_consent": [
        {
          "debtor_name": "Example Buyer, S.A.",
          "debtor_tax_id": "A00000000",
          "status": "pending",
          "level_required": "acknowledgment",
          "level_achieved": null,
          "meets_requirement": false
        }
      ]
    }
  ]
}

GET/v1/requests/{id}

Die Prüfungsunterlagen einer Anfrage: die Anfrage, ihre Forderungen, der aktuelle Advanta Score des Verkäufers, Ihr eigenes Angebot und risk, die Betrugssignale und Beanstandungen der Anfrage, so wie Ihr Portal sie zeigt.

Scope

requests:read

Antwort

200{ request, debtor_consent[], receivables[], score, my_offer, risk }

Fehler

404not_found

score reicht von 300 bis 850, mit einer Note von A bis E und ihren Dimensionen. Er wird sofort berechnet, wenn der Verkäufer noch keinen hat, und ist null, wenn das fehlschlägt. Jede Forderung hat invoice_no, invoice_amount, invoice_date, invoice_due_date und den Schuldner in customer_name. debtor_consent nennt je Schuldner den Status der Anzeige, die geforderte und die unterschriebene Stufe (level_achieved), meets_requirement, den Kanal, den unterschriebenen Erklärungstext und wer unterschrieben hat.

risk.signals listet die noch offenen oder bestätigten Betrugssignale, jedes mit einem stabilen code (etwa amount_above_history) und einer severity. Ein hard-Signal (etwa ein Betrag, der sich geändert hat, während die Rechnung in einer Anfrage ist, eine Gutschrift dazu oder eine offene Beanstandung) stoppt Weiterleitung und Auszahlung, bis das Operations-Team von Advanta es prüft; die übrigen markieren nur. risk.disputes listet jede gegen die Anfrage erfasste Beanstandung.

curl -s "$BASE/v1/requests/4c1e0d2a-8f3b-4f6e-9a55-3c2b1d0e9f87" \
  -H "Authorization: Bearer $ADVANTA_KEY"

POST/v1/requests/{id}/decision

Konditionen anbieten, ablehnen, auszahlen oder einen Zahlungseingang erfassen. Die Anfrage muss an Sie weitergeleitet sein, sonst 409 not_routed_to_you.

Der Body hat eine von vier Formen, gewählt über decision:

Scope

decisions:write

Antwort

201{ decision, request_id, offer_id, expires_at, status } (offer)

200{ decision, request_id, status } (decline)

200{ decision, request_id, status, funded_at } (fund)

200{ decision, request_id, settlement_id, status, received_total, request_total, outstanding } (settle)

Fehler

400reason_required

403not_your_request (nur bei settle: Sie sind nicht der Finanzierer der Anfrage)

404not_found

409not_routed_to_you, invalid_state, credit_limit, funding_gate_failed, funding_amount_mismatch, debtor_not_eligible_for_funder, documents_missing_for_funder

422invalid_terms, invalid_amount, invalid_received_at, invalid_funding_details, step_back_message_required, invalid_decision

curl -s -X POST "$BASE/v1/requests/4c1e0d2a-8f3b-4f6e-9a55-3c2b1d0e9f87/decision" \
  -H "Authorization: Bearer $ADVANTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"decision":"offer","rate":2.4,"advance_pct":90,"days":60,"valid_days":7,"notes":"Subject to the notice being acknowledged"}'

async function offer(requestId, terms) {
  const res = await fetch(`${BASE}/v1/requests/${requestId}/decision`, {
    method: 'POST',
    headers: { ...headers, 'Content-Type': 'application/json' },
    body: JSON.stringify({ decision: 'offer', ...terms }),
  });
  const body = await res.json();
  if (res.status === 201) return body; // { decision, request_id, offer_id, expires_at, status }
  const { code, message, debtors } = body.error;
  if (code === 'debtor_not_eligible_for_funder') {
    for (const d of debtors) console.warn(d.name ?? d.debtor_key, d.reason, d.invoices);
  }
  throw new Error(`${res.status} ${code}: ${message}`);
}

await offer('4c1e0d2a-8f3b-4f6e-9a55-3c2b1d0e9f87', { rate: 2.4, advance_pct: 90, days: 60, valid_days: 7 });

{
  "decision": "offer",
  "request_id": "4c1e0d2a-8f3b-4f6e-9a55-3c2b1d0e9f87",
  "offer_id": "7a9e3c1b-2d4f-4e6a-8b0c-5d1e2f3a4b5c",
  "expires_at": "2026-09-30T10:30:00Z",
  "status": "terms_sent"
}

{ "decision": "decline", "reason": "concentration", "notes": "We cannot fund this buyer this quarter", "internal_note": "Group exposure above our internal limit" }

{ "decision": "fund", "value_date": "2026-10-01", "reference": "TRF-2026-1001-07" }

{ "decision": "settle", "amount": 12500.00, "received_at": "2026-10-30T10:00:00Z", "reference": "ADV-A1F51301-1000" }

POST/v1/requests/{id}/consent-level

Anheben, was die Schuldner einer Anfrage unterschreiben müssen. Nur nach oben, nur bei einer an Sie weitergeleiteten, laufenden Factoring-Anfrage und nur, bevor einer ihrer Schuldner geantwortet hat.

Scope

decisions:write

Antwort

200{ request_id, consent_level_required, changed, from }

Fehler

404not_found

409not_routed_to_you, level_lower, notice_already_decided, not_factoring, request_not_in_flight

422level_invalid, reason_required

curl -s -X POST "$BASE/v1/requests/4c1e0d2a-8f3b-4f6e-9a55-3c2b1d0e9f87/consent-level" \
  -H "Authorization: Bearer $ADVANTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"level":"acceptance","reason":"Credit committee asked for acceptance on this buyer"}'

GET/v1/requests/{id}/documents

Die Dokumentenakte einer Anfrage. Als die Anfrage an Sie weitergeleitet wurde, und erneut bei der Auszahlung, hat Advanta festgehalten, welche Version jedes von Ihnen geforderten Dokuments Ihre Anforderung erfüllt hat: Dateiname, SHA-256, Ausstellungs- und Gültigkeitsdatum sowie wann und wie Advanta es geprüft hat. Dieser Eintrag ändert sich nie, auch wenn der Verkäufer neuere Versionen hochlädt; jeder Eintrag sagt außerdem, wo das Dokument heute steht, und current listet die aktuellen Dokumente des Verkäufers.

Scope

requests:read

Antwort

200{ request_id, seller_country, today, required_now, snapshots[], current[] }

Fehler

404not_found

Jeder Eintrag mit Datei trägt eine download_url, die zwei Minuten gültig ist (url_expires_in), und jede ausgegebene URL wird protokolliert. Vergleichen Sie den SHA-256 des Heruntergeladenen mit dem festgehaltenen.

curl -s "$BASE/v1/requests/4c1e0d2a-8f3b-4f6e-9a55-3c2b1d0e9f87/documents" \
  -H "Authorization: Bearer $ADVANTA_KEY"

GET/v1/required-documents

Die Dokumente, die Sie von Verkäufern verlangen, je Land des Verkäufers, und der Katalog, aus dem sie gewählt werden: Code jedes Dokuments, Name in sieben Sprachen, Aussteller, übliche Gültigkeit und Vertraulichkeitsstufe. Die übliche Gültigkeit dient nur als Vorbelegung: Es zählt das auf dem Dokument gedruckte Datum, das der Verkäufer erfasst und Advanta prüft.

Scope

requests:read

Antwort

200{ funder, required, catalogue[] }

Fehler

Nur die allgemeinen (401, 403, 500).

Eine Anfrage wird nur an Sie weitergeleitet, Ihr Angebot nur erfasst und die Anfrage nur ausgezahlt, solange jedes Dokument Ihrer Liste für das Land des Verkäufers von Advanta geprüft und an diesem Datum gültig ist; sonst 409 documents_missing_for_funder.

curl -s "$BASE/v1/required-documents" \
  -H "Authorization: Bearer $ADVANTA_KEY"

PUT/v1/required-documents

Ihre Liste für ein Verkäuferland ersetzen; eine leere Liste löscht sie. Die Codes stammen aus dem Katalog, und die Änderung wird mit note in der Nachweiskette von Advanta festgehalten. Anfragen, die schon bei Ihnen liegen, bleiben bei Ihnen; Ihr nächstes Angebot oder Ihre nächste Auszahlung darauf wartet, bis der Verkäufer die neue Liste erfüllt (open_requests_not_meeting zählt sie).

Scope

settings:write oder decisions:write

Antwort

200{ …required documents, changed, country, codes, open_requests_not_meeting }

Fehler

422body_required, country_invalid, codes_invalid, note_invalid, country_without_catalogue, document_code_unknown

curl -s -X PUT "$BASE/v1/required-documents" \
  -H "Authorization: Bearer $ADVANTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country":"PT","codes":["cert_hacienda","cert_seguridad_social","cirbe"],"note":"Credit committee of 23 September"}'

GET/v1/settings

Was Ihre Schuldner vor einer Auszahlung unterschreiben müssen: die Stufe, die jeder Schuldner unterschreiben muss, bevor eine an Sie weitergeleitete Factoring-Anfrage ausgezahlt werden kann (receipt, dann acknowledgment, dann acceptance), ob nur von einem Anwalt freigegebene Erklärungstexte zählen, Ihre offenen Anfragen je Stufe, und für welche Stufen jedes anwendbare Recht Erklärungstexte hat, in welchen Sprachen.

Scope

requests:read

Antwort

200{ funder, debtor_consent_level, require_counsel_approved_texts, open_requests_by_level, levels, levels_by_law, texts_counsel_approved }

Fehler

Nur die allgemeinen (401, 403, 500).

curl -s "$BASE/v1/settings" \
  -H "Authorization: Bearer $ADVANTA_KEY"

PUT/v1/settings

Ändern, was Ihre Schuldner unterschreiben müssen. Die Änderung gilt für Anfragen, die ab dann an Sie weitergeleitet werden; eine bereits weitergeleitete Anfrage behält ihre Stufe. reason wird in der Nachweiskette von Advanta festgehalten.

Scope

settings:write oder decisions:write

Antwort

200{ …settings, changed, open_requests_keep_their_level }

Fehler

422level_invalid, invalid_flag, reason_required

curl -s -X PUT "$BASE/v1/settings" \
  -H "Authorization: Bearer $ADVANTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"debtor_consent_level":"acknowledgment","reason":"Credit committee decision of 22 September"}'

GET/v1/programme

Ihre Programmkonditionen: Ihr Standard, die Konditionen, die Sie für bestimmte Unternehmen festgelegt haben, die Unternehmen, für die Sie Konditionen festlegen können (mit einer an Sie weitergeleiteten Anfrage, und Ihre eigenen Kunden), und Ihre Factoring-Anfragen gezählt nach ihren Konditionen. Eine Anfrage übernimmt die Konditionen, die bei ihrer Weiterleitung an Sie gelten, und behält sie.

Scope

requests:read

Antwort

200{ funder, bank_id, default, companies[], sellers[], requests }

Fehler

Nur die allgemeinen (401, 403, 500).

disclosure: announced (Standard): Jeder Schuldner wird benachrichtigt und bestätigt die Abtretung, bevor Sie auszahlen. confidential: Wird die Anfrage an Sie weitergeleitet, wird die Abtretungsanzeige an jeden Schuldner vorbereitet, mit ihrem Fingerabdruck (SHA-256) versehen und versandbereit gespeichert, und die Auszahlung wartet nicht auf den Schuldner. Vor der Auszahlung müssen alle blockierenden Rechnungsprüfungen bestanden sein, die Rechnungen aus der eigenen Buchhaltung des Verkäufers stammen (ERP, E-Rechnung oder SAF-T), jeder Schuldner eine aktuelle vorbereitete Anzeige haben, die Sie nennt, und eine Adresse, an die sie geht, und die Prüfung des Verkäufers freigegeben sein. Die Anzeigen werden versandt, wenn Sie die Anfrage offenlegen, und automatisch bei einer ausgezahlten Anfrage, wenn ein Auslöser eintritt, den Sie eingeschaltet haben: announce_overdue_days, announce_on_dispute, announce_on_kyc_lapse.

recourse: with (mit Regress) oder without (ohne Regress). recourse_days: Tage nach der Fälligkeit einer Rechnung, bis eine ausgezahlte, noch nicht beglichene Anfrage eine Forderung eröffnet (null: keine). bank_data: off, requested (der Verkäufer wird gebeten, sein Geschäftskonto für Sie zu verbinden, nur lesend und mit seiner Einwilligung) oder required (die Auszahlung wartet zusätzlich, bis das Konto, auf das Sie zahlen, als das eigene des Verkäufers bestätigt ist).

curl -s "$BASE/v1/programme" \
  -H "Authorization: Bearer $ADVANTA_KEY"

{
  "funder": { "bank_id": "6d164c92-02cc-4f9a-ae8d-3f7f5ef043d3", "name": "Example Funder" },
  "default": {
    "disclosure": "announced",
    "recourse": "with",
    "recourse_days": 30,
    "announce_overdue_days": null,
    "announce_on_dispute": false,
    "announce_on_kyc_lapse": false,
    "bank_data": "requested",
    "source": "funder_default",
    "updated_at": "2026-09-28T10:00:00Z"
  },
  "companies": [
    {
      "seller_id": "2f6d8a4e-1b3c-4d5e-9f70-8a1b2c3d4e5f",
      "company_name": "Example Seller, S.L.",
      "tax_id": "B00000000",
      "terms": { "disclosure": "confidential", "recourse": "with", "recourse_days": 30, "announce_overdue_days": 15, "announce_on_dispute": true, "announce_on_kyc_lapse": true, "bank_data": "required", "source": "seller" },
      "reason": "Credit committee of 28 September"
    }
  ],
  "requests": { "announced:with:open": 4, "confidential:with:funded": 1 }
}

PUT/v1/programme

Ihren Standard (ohne seller_id) oder die Konditionen eines Unternehmens ändern. Nur die gesendeten Schlüssel ändern sich; {"reset": true} mit einer seller_id setzt dieses Unternehmen auf Ihren Standard zurück. Die Änderung gilt für Anfragen, die ab dann an Sie weitergeleitet werden; bereits weitergeleitete behalten ihre Konditionen. reason wird in der Nachweiskette von Advanta festgehalten.

Scope

settings:write oder decisions:write

Antwort

200{ funder, bank_id, seller_id, terms, changed, open_requests_keep_their_terms }

Fehler

422body_invalid, seller_id_invalid, terms_invalid, terms_key_unknown, reason_required, seller_not_in_programme

curl -s -X PUT "$BASE/v1/programme" \
  -H "Authorization: Bearer $ADVANTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seller_id":"2f6d8a4e-1b3c-4d5e-9f70-8a1b2c3d4e5f","terms":{"disclosure":"confidential","announce_overdue_days":15,"announce_on_dispute":true,"announce_on_kyc_lapse":true,"bank_data":"required"},"reason":"Credit committee of 28 September"}'

POST/v1/requests/{id}/announce

Eine an Sie weitergeleitete stille Anfrage offenlegen: Sie wird offen, und die für sie vorbereiteten Abtretungsanzeigen gehen an ihre Schuldner, die sie dann wie in einem offenen Programm bestätigen. Möglich, solange die Anfrage offen, in Prüfung, mit gesendeten Konditionen, angenommen oder ausgezahlt ist. Es folgt ein Ereignis request.announced; sobald eine Anzeige versandt ist, bleibt die Anfrage offen.

Scope

decisions:write

Antwort

200{ request_id, disclosure, trigger, notices, sending_queued }

Fehler

403not_routed_to_you

404not_found

422body_invalid, reason_required, already_announced, request_closed

curl -s -X POST "$BASE/v1/requests/4c1e0d2a-8f3b-4f6e-9a55-3c2b1d0e9f87/announce" \
  -H "Authorization: Bearer $ADVANTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Invoice 2026-118 is 20 days overdue"}'

GET/v1/requests/{id}/notices

Die Abtretungsanzeigen der Anfrage, eine je Schuldner, jede mit ihrem vorbereiteten Dokument, wenn es eines gibt: genau der Betreff und das HTML, die der Schuldner erhält, Sprache, anwendbares Recht und SHA-256. Für eine an Sie weitergeleitete Anfrage oder eine, bei der Sie schon gehandelt haben.

Scope

requests:read

Antwort

200{ request_id, count, notices[] }

Fehler

404not_found

Das HTML enthält einen Platzhalter, ACK_LINK in doppelten geschweiften Klammern, an der Stelle des Bestätigungslinks des Schuldners; der Link enthält ein Geheimnis und wird nie gezeigt. current sagt, ob das Dokument noch zu den Rechnungen und dem Betrag der Anzeige passt.

curl -s "$BASE/v1/requests/4c1e0d2a-8f3b-4f6e-9a55-3c2b1d0e9f87/notices" \
  -H "Authorization: Bearer $ADVANTA_KEY"

GET/v1/requests/{id}/cash-flow

Was der Verkäufer von seinem Geschäftskonto mit Ihnen teilt, nur lesend und mit seiner Einwilligung, über einen zugelassenen Kontoinformationsdienst: die Verbindung, seine Konten (die letzten vier Zeichen jeder IBAN) und ihre Salden, zwölf Monate Umsätze je Monat und die Prüfung seines Auszahlungskontos. cash_flow ist null, solange der Verkäufer kein Konto für Sie verbunden hat.

Scope

requests:read

Antwort

200{ request_id, bank_data, cash_flow, bank_data_problems[], payment_alerts[] }

Fehler

404not_found

bank_data_problems sagt, worauf die Auszahlung noch wartet, wenn Ihre Konditionen Bankdaten verlangen. payment_alerts sind die Zahlungen, die der Verkäufer von einem Schuldner dieser Anfrage erhalten hat, nachdem Sie sie zu stillen Konditionen ausgezahlt haben. Die Einwilligung eines Verkäufers gilt einem Finanzierer: Sie sehen nur, was er mit Ihnen teilt.

curl -s "$BASE/v1/requests/4c1e0d2a-8f3b-4f6e-9a55-3c2b1d0e9f87/cash-flow" \
  -H "Authorization: Bearer $ADVANTA_KEY"

GET/v1/recourse

Ihre ausgezahlten Factoring-Anfragen nach Regressart (with, without, und not_recorded für vor dem 28. September 2026 weitergeleitete), die Forderungen gezählt nach Art und Status, und die Forderungen selbst, offene zuerst. Eine Forderung wird einmal je Anfrage eröffnet, wenn eine ausgezahlte Anfrage recourse_days nach der Fälligkeit einer Rechnung nicht beglichen ist: recourse, gegen den Verkäufer, über den ausgezahlten Betrag zuzüglich Ihrer Gebühren, abzüglich dessen, was Sie schon vereinnahmt haben; debtor_default, ohne Regress, für Ihr eigenes Inkasso und Ihre Versicherung.

Scope

requests:read

Antwort

200{ funder, bank_id, currency, as_of, by_type[], claims[], list[] }

Fehler

422status_invalid

Der Verkäufer zahlt eine Regressforderung auf pay_to_iban zurück und gibt pay_reference an. Decken die Zahlungen, die Sie ab dann erfassen (eine Auszugszeile, die Sie bestätigen, oder die Entscheidung settle), claim_amount, ist die Forderung beglichen und die Anfrage wird als durch Regress beglichen geschlossen: Die Rechnungen gehen an den Verkäufer zurück, vom Schuldner weiterhin unbezahlt.

curl -s "$BASE/v1/recourse?status=open" \
  -H "Authorization: Bearer $ADVANTA_KEY"

POST/v1/recourse/{id}/close

Eine offene Forderung von Ihnen schließen: Eine Regressforderung wird withdrawn (Sie verzichten darauf oder haben mit dem Verkäufer etwas anderes vereinbart), ein Zahlungsausfall des Schuldners wird written_off (an Ihr Inkasso oder Ihren Versicherer übergeben). reason wird in der Nachweiskette von Advanta festgehalten.

Scope

decisions:write

Antwort

200{ claim_id, status }

Fehler

403not_your_claim

404not_found

422body_invalid, status_invalid, reason_required, close_invalid, claim_closed

curl -s -X POST "$BASE/v1/recourse/$CLAIM_ID/close" \
  -H "Authorization: Bearer $ADVANTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"withdrawn","reason":"Payment plan agreed with the seller on 2 October"}'

GET/v1/bank-data

Ihr eigenes Inkassokonto, von Ihrem Administrator im Portal verbunden und auf dieselbe Weise gelesen: Seine Umsätze laufen durch denselben Abgleich wie POST /v1/statements, sodass Zahlungseingänge ohne Datei-Upload zu Ihren ausgezahlten Anfragen passen. Außerdem, wie viele Verkäufer ihr Konto mit Ihnen teilen, die Zahlungswarnungen zu Ihren Anfragen (die letzten 180 Tage) und die Kosten des Anbieters, die Ihnen zugerechnet werden, je Monat.

Scope

requests:read

Antwort

200{ funder, bank_id, own_accounts[], sellers_sharing, payment_alerts[], charges[] }

Fehler

Nur die allgemeinen (401, 403, 500).

unit_price_eur und amount_eur sind null, bis der Preis des Anbieters feststeht.

curl -s "$BASE/v1/bank-data" \
  -H "Authorization: Bearer $ADVANTA_KEY"

GET/v1/credit-limits

Ihr Buch je Schuldner: Ihr Limit und was ausstehend, zugesagt, angeboten und noch verfügbar ist, in Euro.

Scope

limits:read oder requests:read

Antwort

200{ funder, currency, count, debtors[] }

Fehler

Nur die allgemeinen (401, 403, 500).

Jeder Schuldner enthält debtor_key, debtor_name, debtor_country, limit_status, limit_amount, outstanding, committed, offered, available, overdue_count, oldest_overdue, frozen, decided_at und note.

curl -s "$BASE/v1/credit-limits" \
  -H "Authorization: Bearer $ADVANTA_KEY"

PUT/v1/credit-limits

Ihr Limit für einen Schuldner setzen oder ändern, oder den Schuldner ablehnen. Die Datenbank lehnt jedes spätere Angebot ab, das dieses Limit nicht tragen kann.

Scope

limits:write oder decisions:write

Antwort

200{ credit_limit }

Fehler

422debtor_tax_id_required, invalid_amount, invalid_limit

curl -s -X PUT "$BASE/v1/credit-limits" \
  -H "Authorization: Bearer $ADVANTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"debtor_tax_id":"A00000000","debtor_country":"ES","debtor_name":"Example Buyer, S.A.","amount":250000,"status":"active"}'

POST/v1/credit-limits/import

Bis zu 2.000 Limits für Schuldner in einem Aufruf laden: Ihr eigenes Buch oder die Limits Ihres Kreditversicherers. Jede Zeile wird genau so geprüft, wie PUT /v1/credit-limits ein Limit prüft, und einzeln beantwortet: Eine fehlerhafte Zeile hält die anderen nicht auf, und ein Schuldner, der zweimal im selben Aufruf vorkommt, wird beim zweiten Mal abgelehnt.

Scope

limits:write oder decisions:write

Antwort

200{ funder, source, source_ref, received, written, refused, rows[] }

Fehler

413too_many_rows

422rows_required, invalid_source, source_ref_invalid, source_ref_too_long

Jedes geschriebene Limit hält seine Quelle und Referenz fest, am Limit und in seiner Historie. Die Antwort zählt received, written und refused und beantwortet jede Zeile mit row (ab 1 gezählt), debtor_tax_id und ok: Eine geschriebene Zeile ergänzt debtor_key, status und amount; eine abgelehnte Zeile nennt ihren error (invalid_amount, debtor_tax_id_required, duplicate_debtor, invalid_status, amount_required, invalid_country, row_invalid oder invalid_limit) und kann ein detail ergänzen.

curl -s -X POST "$BASE/v1/credit-limits/import" \
  -H "Authorization: Bearer $ADVANTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source":"insurer","source_ref":"Insurer limits 2026-09","rows":[{"debtor_tax_id":"A00000000","debtor_country":"ES","debtor_name":"Example Buyer, S.A.","amount":250000},{"debtor_tax_id":"500000000","debtor_country":"PT","status":"refused"}]}'

GET/v1/seller-limits

Ihr Buch je Verkäufer, mit denselben Zahlen wie das Schuldnerbuch.

Scope

limits:read oder requests:read

Antwort

200{ funder, currency, count, sellers[] }

Fehler

Nur die allgemeinen (401, 403, 500).

Jeder Verkäufer enthält seller_id, seller_name, seller_nif, seller_country und dieselben Limit- und Exposure-Felder wie ein Schuldner.

curl -s "$BASE/v1/seller-limits" \
  -H "Authorization: Bearer $ADVANTA_KEY"

PUT/v1/seller-limits

Ihr Limit für einen Verkäufer setzen oder ändern, oder den Verkäufer ablehnen.

Scope

limits:write oder decisions:write

Antwort

200{ seller_limit }

Fehler

404not_found

422seller_id_required, invalid_amount, invalid_limit

curl -s -X PUT "$BASE/v1/seller-limits" \
  -H "Authorization: Bearer $ADVANTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seller_id":"2f6d8a4e-1b3c-4d5e-9f70-8a1b2c3d4e5f","amount":100000,"status":"active","note":"Annual review"}'

GET/v1/payer-record

Wie ein Käufer seine Lieferanten bezahlt, nur aggregiert, aus der Buchhaltung der mit Advanta verbundenen Lieferanten. Das Profil wird veröffentlicht, wenn mindestens drei Lieferanten den Käufer beobachten; sonst sagt status, warum, und jede Zahl ist null. Sie können es nur für einen Käufer lesen, der auf einer Anfrage in Ihrem Bereich oder auf Ihrer Schuldnerliste steht; ein Sandbox-Schlüssel liest das Profil der Demonstrationsebene.

Scope

limits:read oder requests:read

Antwort

200{ funder, payer_record }

Fehler

404not_found (der Käufer steht auf keiner Anfrage in Ihrem Bereich und nicht auf Ihrer Schuldnerliste)

422tax_id_required

Die Zahlen umfassen observers, invoice_count, avg_days_to_pay, median_days_to_pay, on_time_pct, den Zahlungsverzug (avg_settle_delay_days, median_settle_delay_days, p75_settle_delay_days, worst_settle_delay_days), offene und überfällige Anzahlen, window_from und refreshed_at. payer_record ist null, wenn es kein Profil gibt.

curl -s "$BASE/v1/payer-record?tax_id=A00000000&country=ES" \
  -H "Authorization: Bearer $ADVANTA_KEY"

GET/v1/requests/{id}/debtors

Was Advanta über jeden Schuldner einer an Sie weitergeleiteten Factoring-Anfrage weiß, oder einer, bei der Sie schon gehandelt haben: sein level bei Advanta seit level_since (notice: er kennt Advanta nur aus der Anzeige; account: er hat sein Zahlerkonto aktiviert; books: er hat seine Buchhaltung verbunden; buyer: er führt ein Käuferprogramm, und buyer_programme ist true), die eigene Historie des Verkäufers mit ihm, seine amtliche Zahlungsdauer, wenn er eine öffentliche Stelle ist, und Ihr Limit für ihn.

Scope

requests:read

Antwort

200{ funder, request_id, count, debtors[] }

Fehler

404not_found

score ist der eigene Score des Schuldners (Klasse, 0 bis 100, wann und mit welcher Modellversion). Er wird nur angegeben, wenn der Schuldner seine Daten mit den Finanzierern teilt, die von ihm geschuldete Rechnungen finanzieren, auf Stufe books oder buyer steht und die Anfrage an Sie weitergeleitet ist (nicht eine, bei der Sie nur gehandelt haben); sonst ist er null. pair_history ist die Historie des Verkäufers mit diesem Schuldner über 36 Monate, nach den Regeln des Zahlungsprofils: nur echte Rechnungen, und Verspätung nur gegenüber Fälligkeiten, die auf dem Dokument oder im ERP stehen. public_payment_period ist die jüngste amtliche durchschnittliche Zahlungsdauer einer öffentlichen Stelle (DGAL für portugiesische Gemeinden, Hacienda für spanische Gebietskörperschaften). credit_limit ist Ihr Limit für den Schuldner, seine Herkunft (source, source_ref) und was davon genutzt ist (exposure: ausstehend plus zugesagt plus angeboten, in Euro).

curl -s "$BASE/v1/requests/4c1e0d2a-8f3b-4f6e-9a55-3c2b1d0e9f87/debtors" \
  -H "Authorization: Bearer $ADVANTA_KEY"

POST/v1/statements

Den Auszug Ihres Inkassokontos zum Abgleich senden: eine CAMT.053- (XML) oder CSV-Datei, höchstens 4 MiB und 5.000 Buchungen. Jede Gutschrift wird mit Ihren eigenen ausgezahlten Anfragen abgeglichen, zuerst über die Referenz, die der Schuldner angegeben hat. Nichts wird verbucht, bevor Sie einen Treffer im Portal bestätigen. Dieselbe Datei wird kein zweites Mal angenommen, erkannt an ihrem SHA-256.

Scope

statements:write oder decisions:write

Antwort

201{ import_id, file_sha256, lines, credits, duplicates, proposed, suggested, unmatched, ignored, … }

Fehler

409statement_already_imported

413file_too_large, too_many_lines

422file_required, file_unreadable, file_empty, statement_unreadable, statement_has_no_transactions, line_invalid

curl -s -X POST "$BASE/v1/statements?file_name=statement-2026-10-30.xml&kind=camt053" \
  -H "Authorization: Bearer $ADVANTA_KEY" \
  -H "Content-Type: application/xml" \
  --data-binary @statement-2026-10-30.xml

GET/v1/client-links

Ihr eigener offener Link (prescriber_id null) und der aktuelle Link jedes Vermittlers, mit seinem state (active, disabled oder expired) und seiner url, solange er funktioniert.

Scope

requests:read, clients:write oder decisions:write

Antwort

200{ funder, count, client_links[] }

Fehler

422lang_invalid

Ein Unternehmen, das einen Link öffnet, gibt Namen, Steuernummer, Land und E-Mail an und erhält Ihre Einladung per E-Mail. Nimmt es sie an, wird es Ihr Kunde: Seine Anfragen gehen nur an Sie, und seine Herkunft (der Link, der Vermittler, das Datum) wird erfasst. Das Öffnen eines Links legt nie von sich aus ein Konto an.

Jeder Link trägt außerdem arrivals (die Unternehmen, die über ihn zum ersten Mal zu Ihnen kamen) und claims_last_day (Registrierungen über ihn in den letzten 24 Stunden; ein Link nimmt höchstens 20 pro Stunde und 100 pro Tag an).

curl -s "$BASE/v1/client-links?lang=es" \
  -H "Authorization: Bearer $ADVANTA_KEY"

POST/v1/client-links

Ihren eigenen offenen Link ausstellen, oder mit prescriber_id den eines Vermittlers. Je Inhaber gibt es einen funktionierenden Link: Solange einer funktioniert, senden Sie replace: true, um ihn zu ersetzen (der alte funktioniert sofort nicht mehr); sonst 409 link_exists. Gespeichert wird nur der SHA-256 des Link-Tokens, und die Ausstellung wird in der Nachweiskette von Advanta festgehalten.

Scope

clients:write oder decisions:write

Antwort

201{ client_link }

Fehler

404not_found

409link_exists

422body_invalid, prescriber_id_invalid, expires_at_invalid, reason_invalid, replace_invalid, lang_invalid

Ein mit einem Sandbox-Schlüssel ausgestellter Link erzeugt nur Testeinladungen, und der Schlüssel braucht decisions:write: Die Links des Demonstrations-Finanzierers teilen sich alle Demonstrationen.

curl -s -X POST "$BASE/v1/client-links" \
  -H "Authorization: Bearer $ADVANTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"replace":true,"reason":"The old link was forwarded too widely","lang":"es"}'

{
  "client_link": {
    "id": "8d3e1f2a-4b5c-4d6e-9f70-1a2b3c4d5e6f",
    "prescriber_id": null,
    "state": "active",
    "created_at": "2026-09-26T10:00:00Z",
    "expires_at": null,
    "disabled_at": null,
    "disabled_reason": null,
    "replaced_by": null,
    "arrivals": 0,
    "claims_last_day": 0,
    "url": "https://app.advanta.capital/join?link=…&lang=es"
  }
}

POST/v1/client-links/{id}/disable

Einen Link abschalten. Er funktioniert sofort nicht mehr; Unternehmen, die bereits darüber kamen, behalten ihre Herkunft. Einen schon abgeschalteten Link abzuschalten ändert nichts (changed ist false). Einen neuen stellen Sie mit POST /v1/client-links aus.

Scope

clients:write oder decisions:write

Antwort

200{ link_id, changed, state: "disabled" }

Fehler

404not_found

405method_not_allowed

422body_invalid, reason_invalid

curl -s -X POST "$BASE/v1/client-links/$LINK_ID/disable" \
  -H "Authorization: Bearer $ADVANTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Campaign ended"}'

GET/v1/prescribers

Ihre Vermittler, die Personen und Kanzleien, die Ihnen Kunden bringen (Steuerberater, Berater, Makler), aktive zuerst, jeder mit seinem aktuellen Link und der Zahl der Unternehmen, die darüber kamen. Sie gehören Ihnen und sind keine Partner von Advanta. Dieselbe Liste wie die Seite Kunden in Ihrem Portal.

Scope

requests:read, clients:write oder decisions:write

Antwort

200{ funder, count, prescribers[] }

Fehler

422lang_invalid

Ein Sandbox-Schlüssel liest die Vermittler des Demonstrations-Finanzierers, die sich alle Demonstrationen teilen.

curl -s "$BASE/v1/prescribers?lang=es" \
  -H "Authorization: Bearer $ADVANTA_KEY"

POST/v1/prescribers

Einen Vermittler anlegen. Sein eigener offener Link wird mit ihm ausgestellt, in prescriber.link.url. Name und E-Mail bleiben außerhalb der Nachweiskette von Advanta: Dort stehen nur ihre Hashes.

Scope

clients:write oder decisions:write

Antwort

201{ prescriber }

Fehler

409prescriber_exists

422body_required, name_required, name_invalid, email_invalid, email_not_reserved, notes_too_long, lang_invalid

Mit einem Sandbox-Schlüssel ändert das gemeinsam genutzte Demonstrationsdaten, deshalb braucht der Schlüssel decisions:write.

curl -s -X POST "$BASE/v1/prescribers" \
  -H "Authorization: Bearer $ADVANTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Gestoría Norte","email":"ana@gestoria-norte.example","notes":"Accountant in Bilbao","lang":"es"}'

{
  "prescriber": {
    "id": "5f1c2a8e-3b7d-4e0a-9c61-2d4b8e7f9a10",
    "name": "Gestoría Norte",
    "email": "ana@gestoria-norte.example",
    "notes": "Accountant in Bilbao",
    "active": true,
    "created_at": "2026-09-10T09:00:00Z",
    "disabled_at": null,
    "link": {
      "id": "1e2f3a4b-5c6d-4e7f-8a9b-0c1d2e3f4a5b",
      "prescriber_id": "5f1c2a8e-3b7d-4e0a-9c61-2d4b8e7f9a10",
      "state": "active",
      "expires_at": null,
      "arrivals": 0,
      "url": "https://app.advanta.capital/join?link=…&lang=es"
    }
  }
}

POST/v1/prescribers/{id}/disable

Einen Vermittler abschalten. Sein Link funktioniert sofort nicht mehr; die Unternehmen, die er gebracht hat, bleiben ihm zugeordnet. Einen schon abgeschalteten Vermittler abzuschalten ändert nichts (changed ist false). Wird in der Nachweiskette von Advanta festgehalten.

Scope

clients:write oder decisions:write

Antwort

200{ prescriber, changed }

Fehler

404not_found

405method_not_allowed

422body_invalid, reason_invalid

curl -s -X POST "$BASE/v1/prescribers/$PRESCRIBER_ID/disable" \
  -H "Authorization: Bearer $ADVANTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Agreement ended"}'

GET/v1/prescribers/report

Was Ihnen jeder Vermittler gebracht hat: eine Gruppe je Vermittler, dann Ihr eigener Link (own_link), Ihre namentlichen Einladungen (named) und Ihre Onboarding-Links (api). Je Gruppe und je Unternehmen: wann es ankam, wann sein Konto eröffnet wurde (joined), wann seine Unternehmensprüfung genehmigt wurde (onboarded), die an Sie weitergeleiteten Anfragen, der angefragte und der finanzierte Betrag. Dieselben Zahlen wie in Ihrem Portal.

Scope

requests:read, clients:write oder decisions:write

Antwort

200{ funder, plane, generated_at, currency, totals, groups[] }

Fehler

405method_not_allowed

Ein Unternehmen zählt einmal, für den, der es Ihnen zuerst gebracht hat. Der finanzierte Betrag ist die Auszahlung (sonst der Gesamtbetrag) ausgezahlter oder beglichener Anfragen, in Euro; totals summiert alle Gruppen. Nur Ihre Daten und nur Unternehmen auf Ihrer Datenebene: Ein Sandbox-Schlüssel sieht nicht, was andere Sandbox-Schlüssel über die API angelegt haben.

curl -s "$BASE/v1/prescribers/report" \
  -H "Authorization: Bearer $ADVANTA_KEY"

{
  "funder": {
    "bank_id": "6d164c92-02cc-4f9a-ae8d-3f7f5ef043d3",
    "name": "Compartment Demo (LU)"
  },
  "plane": "sandbox",
  "generated_at": "2026-09-26T10:00:00Z",
  "currency": "EUR",
  "totals": { "arrived": 1, "joined": 1, "onboarded": 1, "requests": 1, "amount_requested": 18450.00, "amount_funded": 16605.00 },
  "groups": [
    {
      "kind": "prescriber",
      "prescriber_id": "5f1c2a8e-3b7d-4e0a-9c61-2d4b8e7f9a10",
      "name": "Gestoría Norte",
      "active": true,
      "since": "2026-09-10T09:00:00Z",
      "arrived": 1,
      "joined": 1,
      "onboarded": 1,
      "requests": 1,
      "amount_requested": 18450.00,
      "amount_funded": 16605.00,
      "companies": [
        {
          "company_name": "Example Seller, S.L.",
          "company_tax_id": "B00000000",
          "country": "ES",
          "arrived_at": "2026-09-15T11:02:00Z",
          "joined_at": "2026-09-15T11:20:00Z",
          "onboarded_at": "2026-09-16T09:15:00Z",
          "requests": 1,
          "amount_requested": 18450.00,
          "amount_funded": 16605.00
        }
      ]
    }
  ]
}

GET/v1/client-invitations

Alle Ihre Einladungen, die neuesten zuerst: über einen Link, namentlich im Portal oder mit einem Onboarding-Link. Jede nennt, wie das Unternehmen kam (via: link, named oder api), gegebenenfalls den Vermittler, der es brachte, ihren state (pending, accepted, revoked oder expired), das Unternehmen, den Kontakt und die Daten.

Scope

requests:read, clients:write oder decisions:write

Antwort

200{ funder, count, invitations[] }

Fehler

405method_not_allowed

Nur Ihre eigene Datenebene. Ein Sandbox-Schlüssel sieht die Einladungen anderer Sandbox-Schlüssel nicht.

curl -s "$BASE/v1/client-invitations?limit=50" \
  -H "Authorization: Bearer $ADVANTA_KEY"

GET/v1/opportunities

Die Übersicht eines Tages, aus Ihren eigenen Kunden (den Unternehmen, deren Hausfinanzierer Sie sind), die Ihnen erlauben, ihre Rechnungen zu sehen. Jeden Morgen gegen 06:30 Uhr Madrider Zeit, nach der nächtlichen Vorqualifizierung, listet Advanta die Rechnungen, die seit der vorigen Übersicht nach Ihren Regeln finanzierbar wurden (kind new), und was sich bei denen geändert hat, die Ihnen schon gezeigt wurden: paid, disputed (der Kunde hat erfasst, dass sein Schuldner sie bestreitet) oder no_longer_eligible.

Scope

requests:read

Antwort

200{ funder, date, digest, lines[] }

Fehler

404not_found

405method_not_allowed

422invalid_date

Eine Zeile enthält die Rechnung, den Schuldner mit seiner Steuernummer, den noch offenen Betrag, die Fälligkeit und den Kunden mit Branche (NACE-Abschnitt), Klasse und Größenklasse; zuerst die neuen Zeilen, dann die Änderungen. no_longer_eligible hat einen reason: requested (der Kunde hat ihre Finanzierung beantragt), cancelled, removed (nicht mehr in den Büchern des Kunden), left_programme, not_shared (der Kunde teilt nicht mehr) oder rules (sie erfüllt Ihre Regeln nicht mehr).

digest enthält die Summen: wie viele Kunden teilen und wie viele noch nicht, was heute finanzierbar ist, was neu ist und was sich geändert hat. stale ist true, wenn der nächtliche Lauf nicht fertig wurde: An diesem Morgen wurde nichts verglichen. Eine Übersicht ist eine von der Datenbank berechnete Liste, kein Angebot: Eine Anfrage wird bei ihrer Stellung erneut geprüft, und Sie entscheiden wie immer. Der Webhook opportunities.daily sagt, wann eine Übersicht mit Inhalt bereitsteht.

curl -s "$BASE/v1/opportunities?date=2026-10-07" \
  -H "Authorization: Bearer $ADVANTA_KEY"

{
  "funder": { "bank_id": "6d164c92-02cc-4f9a-ae8d-3f7f5ef043d3", "name": "Example Funder" },
  "date": "2026-10-07",
  "digest": {
    "digest_id": "9b2d4c1e-0f3a-4e5b-8c6d-7a8b9c0d1e2f",
    "date": "2026-10-07",
    "stale": false,
    "snapshot_at": "2026-10-07T03:30:12Z",
    "clients": { "sharing": 9, "not_sharing": 1 },
    "eligible": { "count": 42, "total": 318450.00 },
    "new": { "count": 6, "total": 41200.00 },
    "changes": { "paid": 2, "disputed": 0, "no_longer_eligible": 1 },
    "currency": "EUR",
    "lines": "/v1/opportunities?date=2026-10-07"
  },
  "lines": [
    {
      "kind": "new",
      "reason": null,
      "invoice_id": "0c5e7f3a-2b4d-4c6e-9f81-3a5b7c9d1e2f",
      "number": "FV 2026/1184",
      "debtor": { "name": "Example Buyer, S.A.", "tax_id": "A00000000", "country": "ES" },
      "amount": 12400.00,
      "currency": "EUR",
      "due_date": "2026-12-15",
      "client": { "seller_id": "2f6d8a4e-1b3c-4d5e-9f70-8a1b2c3d4e5f", "name": "Example Seller, S.L.", "tax_id": "B00000000", "sector": "C", "grade": "B", "size_band": "small" }
    }
  ]
}

GET/v1/webhooks

Ihre aktiven Endpunkte, ohne ihre Secrets, und die Ereignistypen, die Sie abonnieren können. Ein Sandbox-Schlüssel sieht nur die Endpunkte, die er angelegt hat.

Scope

webhooks:write, decisions:write oder requests:read

Antwort

200{ count, webhooks[], event_types[] }

Fehler

Nur die allgemeinen (401, 403, 500).

curl -s "$BASE/v1/webhooks" \
  -H "Authorization: Bearer $ADVANTA_KEY"

POST/v1/webhooks

Einen Endpunkt registrieren. Die Antwort enthält sein Signatur-Secret, das nicht noch einmal angezeigt wird.

Scope

webhooks:write oder decisions:write

Antwort

201{ webhook, secret, signature }

Fehler

409too_many_endpoints

422body_required, url_required, url_invalid, url_too_long, url_must_be_https, url_has_credentials, url_port_not_allowed, url_host_not_allowed, url_not_allowed, events_invalid, unknown_event_type, invalid_description

Höchstens 10 aktive Endpunkte.

curl -s -X POST "$BASE/v1/webhooks" \
  -H "Authorization: Bearer $ADVANTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/advanta","events":["request.routed","notice.acknowledged","notice.disputed","request.funded","settlement.recorded"],"description":"Credit desk"}'

const res = await fetch(`${BASE}/v1/webhooks`, {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    url: 'https://hooks.example.com/advanta',
    events: ['request.routed', 'notice.acknowledged', 'notice.disputed', 'request.funded', 'settlement.recorded'],
    description: 'Credit desk',
  }),
});
const body = await res.json();
if (res.status !== 201) throw new Error(`${res.status} ${body.error.code}: ${body.error.message}`);

// The secret is shown once: store it now, in your own secret store.
await secretStore.put(`advanta-webhook-${body.webhook.id}`, body.secret);

{
  "webhook": {
    "id": "e3b1c2d4-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
    "url": "https://hooks.example.com/advanta",
    "description": "Credit desk",
    "events": ["notice.acknowledged", "notice.disputed", "request.funded", "request.routed", "settlement.recorded"],
    "active": true,
    "secret_prefix": "whsec_1a2b3c",
    "created_via": "api"
  },
  "secret": "whsec_…",
  "signature": { "header": "Advanta-Signature", "scheme": "HMAC-SHA256 of \"<t>.<raw body>\"", "tolerance_seconds": 300 }
}

DELETE/v1/webhooks/{id}

Einen Endpunkt stoppen. Noch ausstehende Zustellungen werden storniert und seine Secrets gelöscht.

Scope

webhooks:write oder decisions:write

Antwort

200{ id, active: false, deleted: true, cancelled_deliveries }

Fehler

404not_found

curl -s -X DELETE "$BASE/v1/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $ADVANTA_KEY"

POST/v1/webhooks/{id}/rotate-secret

Ein neues Signatur-Secret, einmal angezeigt. Das vorherige Secret signiert weiter, als zweites v1 im Header, für keep_previous_hours, damit Sie ohne Ereignisverlust wechseln können.

Scope

webhooks:write oder decisions:write

Antwort

200{ webhook, secret, previous_secret_valid_until }

Fehler

404not_found

422invalid_keep_previous_hours

curl -s -X POST "$BASE/v1/webhooks/$WEBHOOK_ID/rotate-secret" \
  -H "Authorization: Bearer $ADVANTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keep_previous_hours":24}'

POST/v1/webhooks/{id}/test

Ein webhook.test-Ereignis für diesen Endpunkt einreihen. Der nächste Lauf des Dispatchers stellt es zu, in etwa einer Minute.

Scope

webhooks:write oder decisions:write

Antwort

202{ endpoint_id, event_id, delivery_id, status: "pending" }

Fehler

404not_found

curl -s -X POST "$BASE/v1/webhooks/$WEBHOOK_ID/test" \
  -H "Authorization: Bearer $ADVANTA_KEY"

GET/v1/webhooks/{id}/deliveries

Das Zustellprotokoll eines Endpunkts, neueste zuerst: Status (pending, delivered, failed oder cancelled), Versuche, Antwortcode, letzter Fehler, nächster Versuch und der SHA-256 des exakt gesendeten Bodys.

Scope

webhooks:write, decisions:write oder requests:read

Antwort

200{ count, deliveries[] }

Fehler

404not_found

curl -s "$BASE/v1/webhooks/$WEBHOOK_ID/deliveries?limit=20" \
  -H "Authorization: Bearer $ADVANTA_KEY"

POST/v1/onboarding-links

Ein einmal nutzbarer Onboarding-Link für einen Ihrer Lieferanten, Ihnen zugeordnet. Advanta sendet keine E-Mail: Sie geben die url an Ihren Lieferanten. Hat der Lieferant seine Unternehmensprüfung eingereicht, erhalten Sie onboarding.completed, und der Lieferant wird mit einem signierten Status zu Ihrer return_url zurückgeschickt.

Scope

onboarding:write oder decisions:write

Antwort

201{ onboarding_link, url, expires_at, environment, return_secret, return }

Fehler

409company_already_registered, email_has_account, invitation_pending_exists, country_not_served

422body_required, country_invalid, company_vat_invalid, contact_email_invalid, contact_name_invalid, company_name_invalid, company_name_required, return_url_invalid, return_url_not_allowed, metadata_invalid, locale_invalid, valid_days_invalid, country_not_served

Die Antwort enthält return_secret (ors_ gefolgt von 64 Hexadezimalzeichen), nur einmal angezeigt: Speichern Sie es sofort. Gespeichert wird nur der SHA-256 des Link-Tokens. Ein mit einem Sandbox-Schlüssel erstellter Link erfasst den Lieferanten als Testunternehmen auf der Demonstrationsebene.

Kommt der Lieferant zurück, trägt die return_url advanta_onboarding (die Id des Links), advanta_status (completed), advanta_ts (Unix-Sekunden) und advanta_sig: den hexadezimalen HMAC-SHA256 von <advanta_onboarding>.<advanta_status>.<advanta_ts>, mit Ihrem return_secret als Schlüssel. Prüfen Sie ihn, bevor Ihre Seite dem Status vertraut, und lehnen Sie einen Rücksprung ab, der mehr als 600 Sekunden von Ihrer Uhr abweicht; das letzte Beispiel unten tut beides.

curl -s -X POST "$BASE/v1/onboarding-links" \
  -H "Authorization: Bearer $ADVANTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company_vat":"PT500000000","country":"PT","contact_email":"ana@fornecedor.example","contact_name":"Ana Sousa","company_name":"Fornecedor Exemplo, Lda.","return_url":"https://portal.example.com/onboarding/done","metadata":{"supplier_ref":"S-42"},"locale":"pt"}'

{
  "onboarding_link": {
    "id": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f",
    "status": "pending",
    "company_name": "Fornecedor Exemplo, Lda.",
    "country": "PT",
    "return_url": "https://portal.example.com/onboarding/done",
    "metadata": { "supplier_ref": "S-42" },
    "expires_at": "2026-10-10T10:00:00Z",
    "completed_at": null,
    "seller_id": null
  },
  "url": "https://app.advanta.capital/accept-invite?invitation=…&lang=pt",
  "expires_at": "2026-10-10T10:00:00Z",
  "environment": "sandbox",
  "return_secret": "ors_…",
  "return": {
    "parameters": ["advanta_onboarding", "advanta_status", "advanta_ts", "advanta_sig"],
    "signature": "hex HMAC-SHA256(return_secret, \"<advanta_onboarding>.<advanta_status>.<advanta_ts>\")"
  }
}

import crypto from 'node:crypto';

// On the page behind your return_url.
// url:          the full address the supplier came back to
// returnSecret: the "ors_…" string POST /v1/onboarding-links returned, stored when you made the link
export function verifyAdvantaReturn(url, returnSecret, nowSeconds = Math.floor(Date.now() / 1000)) {
  const q = new URL(url).searchParams;
  const id = q.get('advanta_onboarding') ?? '';
  const status = q.get('advanta_status') ?? '';
  const ts = q.get('advanta_ts') ?? '';
  const sig = q.get('advanta_sig') ?? '';
  if (!id || !status || !/^[0-9]{1,12}$/.test(ts) || !/^[0-9a-f]{64}$/.test(sig)) return null;
  if (Math.abs(nowSeconds - Number(ts)) > 600) return null; // too old: ask your back end instead

  const expected = crypto.createHmac('sha256', returnSecret).update(`${id}.${status}.${ts}`).digest();
  if (!crypto.timingSafeEqual(Buffer.from(sig, 'hex'), expected)) return null;
  return { onboardingLinkId: id, status }; // status is "completed"
}

GET/v1/onboarding-links

Ihre Onboarding-Links, die neuesten zuerst, jeder mit seinem status: pending, account_created, completed, expired oder revoked. Ein Sandbox-Schlüssel sieht die Links, die er erstellt hat.

Scope

onboarding:write, decisions:write oder requests:read

Antwort

200{ count, onboarding_links[] }

Fehler

Nur die allgemeinen (401, 403, 500).

curl -s "$BASE/v1/onboarding-links?limit=20" \
  -H "Authorization: Bearer $ADVANTA_KEY"

GET/v1/onboarding-links/{id}

Ein Onboarding-Link und wo der Lieferant steht. Ist er abgeschlossen, ist seller_id die Id, die GET /v1/seller-limits verwendet.

Scope

onboarding:write, decisions:write oder requests:read

Antwort

200{ onboarding_link }

Fehler

404not_found

405method_not_allowed

curl -s "$BASE/v1/onboarding-links/$ONBOARDING_ID" \
  -H "Authorization: Bearer $ADVANTA_KEY"

POST/v1/exports

Startet einen Export von allem, was Ihr Finanzierer sehen kann: Anfragen und ihr Verlauf, Angebote, Rechnungen mit ihrer Prüfung, Verkäufer (Unternehmensdaten, die KYC-Zusammenfassung, die Sie sehen dürfen, die Prüfung des Vertreters), Schuldner, Anzeigen mit den Antworten der Schuldner und den Daten der Zertifikate, die Einträge der Nachweiskette zu Ihren Geschäften mit den Hashes und Tageswurzeln zu ihrer Prüfung, Zahlungseingänge und Kontoauszüge, Ablehnungen durch die Kontrollen, Ihre Regeln und Limits, Ihr Team, Webhook-Endpunkte (nie ein Geheimnis), API-Schlüssel (nie ein Schlüssel), Ihr Prüfprotokoll und Ihre Dokumente. Er wird im Hintergrund erstellt, meist in weniger als einer Minute; export.ready meldet, wann.

Scope

exports:write oder decisions:write

Antwort

202{ funder, export }

Fehler

403export_live_key_required

409export_in_progress

422body_invalid, lang_invalid

429export_rate_limited

Nur ein Produktionsschlüssel: Ein Sandbox-Schlüssel erhält 403 export_live_key_required (der Demonstrations-Finanzierer wird geteilt). Ein Export zur Zeit, höchstens 10 in 24 Stunden. Derselbe Export steht auf der Seite Export des Portals, unter den Einstellungen.

curl -s -X POST "$BASE/v1/exports" \
  -H "Authorization: Bearer $ADVANTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lang":"es"}'

{
  "funder": { "bank_id": "6d164c92-02cc-4f9a-ae8d-3f7f5ef043d3", "name": "Example Funder" },
  "export": {
    "id": "5e1f0a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
    "subject": "funder",
    "status": "queued",
    "plane": "live",
    "requested_via": "api",
    "actor_role": "api:treasury",
    "lang": "es",
    "created_at": "2026-09-27T09:00:02.114000Z",
    "download_available": false,
    "manifest_sha256": null,
    "progress": { "entities_done": 0, "entities_total": 47, "rows": 0, "volumes_written": 0, "phase": "data" }
  }
}

GET/v1/exports

Ihre Exporte, aus dem Portal und der API, die neuesten zuerst, mit Status, Größe und manifest_sha256.

Scope

exports:write oder decisions:write

Antwort

200{ funder, count, exports[] }

Fehler

403export_live_key_required

405method_not_allowed

curl -s "$BASE/v1/exports?limit=20" \
  -H "Authorization: Bearer $ADVANTA_KEY"

GET/v1/exports/{id}

Ein Export. Während er erstellt wird: status queued oder running, mit progress. Sobald ready, und 24 Stunden lang: files, jeder Teil mit einem Link, der höchstens eine Stunde gilt (nie über diese 24 Stunden hinaus). Fragen Sie erneut für neue Links; jeder Aufruf, der Links liefert, wird festgehalten. Nach 24 Stunden werden die Dateien gelöscht, der Datensatz bleibt.

Scope

exports:write oder decisions:write

Antwort

200{ funder, export, files[] }

Fehler

403export_live_key_required

404not_found

405method_not_allowed

manifest_sha256 ist der SHA-256 von manifest.json, ohne dieses Feld, mit sortierten Schlüsseln und ohne Leerzeichen geschrieben. Advanta hat denselben Wert in der Nachweiskette festgehalten (Eintrag export.ready); verify.py berechnet ihn neu und prüft jede Datei und die Nachweiseinträge.

curl -s "$BASE/v1/exports/5e1f0a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b" \
  -H "Authorization: Bearer $ADVANTA_KEY"

{
  "funder": { "bank_id": "6d164c92-02cc-4f9a-ae8d-3f7f5ef043d3", "name": "Example Funder" },
  "export": {
    "id": "5e1f0a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
    "status": "ready",
    "completed_at": "2026-09-27T09:00:41.502000Z",
    "expires_at": "2026-09-28T09:00:41.502000Z",
    "download_available": true,
    "manifest_sha256": "1c822b8797ba58903eca0689cc0c93138e7d396e01a038d133b5c1f3aeec7497",
    "size_bytes": 482113,
    "file_count": 101,
    "documents_mode": "files",
    "row_counts": { "requests": 212, "invoices": 1480, "evidence_entries": 903 }
  },
  "files": [
    {
      "name": "advanta-export-2026-09-27-5e1f0a2b-v001.zip",
      "bytes": 482113,
      "sha256": "9b0e5c1d2a7f4e6b8c3d1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a291807",
      "url": "https://…/object/sign/data-exports/…",
      "url_expires_at": "2026-09-27T10:00:41.502000Z"
    }
  ]
}

# Every volume into one folder, then the checker the export carries
curl -s "$BASE/v1/exports/$EXPORT_ID" -H "Authorization: Bearer $ADVANTA_KEY" \
  | jq -r '.files[].url' | while read -r u; do curl -s -o "v$((++n)).zip" "$u"; done
for z in v*.zip; do unzip -q -o "$z" -d export; done
python3 export/advanta-export-*/verify.py   # files, manifest digest and evidence chain

GET/v1/exports/{id}/documents

Wenn die Dokumente zu groß waren, um sie aufzunehmen (documents_mode links): jedes Dokument des Exports mit einem Link, der 15 Minuten gilt, seitenweise. Die Liste wird bei der Anfrage berechnet: Ein Dokument, das Sie nicht mehr lesen dürfen, steht nicht darin.

Scope

exports:write oder decisions:write

Antwort

200{ funder, export_id, documents[], next_after }

Fehler

403export_live_key_required

404not_found

409export_not_ready, export_failed

410export_expired

curl -s "$BASE/v1/exports/5e1f0a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b/documents?limit=100" \
  -H "Authorization: Bearer $ADVANTA_KEY"