API di Advanta per i finanziatori

GET/v1/health

Se l’API è attiva. Pubblica: nessuna chiave, nessun dato, nessun accesso al database.

Ambito

Nessuna: pubblica, senza chiave

Risposta

200{ status, api_version, time }

Errori

Nessuno

Advanta interroga questa route ogni 5 minuti; i risultati sono sulla pagina di stato pubblica.

curl -s "$BASE/v1/health"

GET/v1/me

Chi sta chiamando: la chiave, il suo finanziatore, il suo ambiente e i suoi ambiti.

Ambito

Qualsiasi chiave valida

Risposta

200{ api_version, environment, funder, key }

Errori

405method_not_allowed

key.prefix sono i primi 12 caratteri della chiave. key.expires_at è null per una chiave che non scade; key.prospect indica a chi è stata emessa una chiave sandbox.

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

Le richieste a Lei assegnate (può agire su di esse) e quelle su cui ha già agito (in sola lettura, anche dopo una riassegnazione), dalla più recente, ciascuna con la Sua offerta in my_offer, se l’ha fatta.

Ambito

requests:read

Risposta

200{ funder, count, requests[] }

Errori

Solo quelli comuni (401, 403, 500).

Una richiesta contiene id, request_ref, type (factoring o confirming), status, total_amount, advance_amount, il cedente in company_name e company_nif, invoice_count, assigned_bank_id, consent_level_required (ciò che ogni debitore deve firmare prima che possa essere finanziata, fissato all’assegnazione), le sue date e, per ogni debitore, debtor_consent. La specifica elenca ogni campo.

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}

Il fascicolo di valutazione di una richiesta: la richiesta, i suoi crediti, l’Advanta Score più recente del cedente, la Sua offerta e risk, i segnali di frode e le contestazioni della richiesta, come li mostra il Suo portale.

Ambito

requests:read

Risposta

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

Errori

404not_found

score va da 300 a 850, con un giudizio da A a E e le sue dimensioni. Viene calcolato al momento se il cedente non ne ha ancora uno, ed è null se il calcolo non riesce. Ogni credito ha invoice_no, invoice_amount, invoice_date, invoice_due_date e il debitore in customer_name. debtor_consent indica, per ogni debitore, lo stato della notifica, il livello richiesto e il livello firmato (level_achieved), meets_requirement, il canale, il testo della dichiarazione firmato e chi l’ha firmato.

risk.signals elenca i segnali di frode ancora aperti o confermati, ognuno con un code stabile (per esempio amount_above_history) e una severity. Un segnale hard (per esempio un importo cambiato mentre la fattura è in una richiesta, una nota di credito sulla fattura o una contestazione aperta) blocca l’assegnazione e il finanziamento finché il team operativo di Advanta non lo esamina; gli altri si limitano a segnalare. risk.disputes elenca tutte le contestazioni registrate sulla richiesta.

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

POST/v1/requests/{id}/decision

Offrire condizioni, rifiutare, finanziare o registrare un incasso. La richiesta deve essere assegnata a Lei, altrimenti 409 not_routed_to_you.

Il body ha una di quattro forme, scelta da decision:

Ambito

decisions:write

Risposta

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)

Errori

400reason_required

403not_your_request (solo per settle: non è il finanziatore della richiesta)

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

Alzare ciò che i debitori di una richiesta devono firmare. Solo verso l’alto, solo su una richiesta di factoring a Lei assegnata e in corso, e solo prima che uno dei suoi debitori abbia risposto.

Ambito

decisions:write

Risposta

200{ request_id, consent_level_required, changed, from }

Errori

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

Il fascicolo documentale di una richiesta. Quando la richiesta Le è stata assegnata, e di nuovo quando è stata finanziata, Advanta ha registrato quale versione di ogni documento da Lei richiesto La soddisfaceva: nome del file, SHA-256, date di emissione e di validità, e quando e come Advanta l’ha verificato. Questa registrazione non cambia mai, anche quando il cedente carica versioni più recenti; ogni voce indica anche la situazione odierna del documento, e current elenca i documenti attuali del cedente.

Ambito

requests:read

Risposta

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

Errori

404not_found

Ogni voce con un file porta un download_url valido due minuti (url_expires_in), e ogni URL emesso viene registrato. Confronti lo SHA-256 di ciò che scarica con quello registrato.

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

GET/v1/required-documents

I documenti che richiede ai cedenti, per paese del cedente, e il catalogo da cui sono scelti: il codice di ogni documento, il nome in sette lingue, l’ente emittente, la validità abituale e la sensibilità. La validità abituale serve solo come precompilazione: conta la data stampata sul documento, che il cedente registra e Advanta controlla.

Ambito

requests:read

Risposta

200{ funder, required, catalogue[] }

Errori

Solo quelli comuni (401, 403, 500).

Una richiesta Le viene assegnata, la Sua offerta viene registrata e la richiesta viene finanziata solo finché ogni documento della Sua lista per il paese del cedente è verificato da Advanta e valido in quella data; altrimenti 409 documents_missing_for_funder.

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

PUT/v1/required-documents

Sostituire la Sua lista per un paese dei cedenti; una lista vuota la cancella. I codici provengono dal catalogo, e la modifica resta registrata nella catena di evidenze di Advanta con note. Le richieste già presso di Lei restano Sue; la Sua prossima offerta o il prossimo finanziamento su una di esse attende finché il cedente non soddisfa la nuova lista (open_requests_not_meeting le conta).

Ambito

settings:write o decisions:write

Risposta

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

Errori

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

Ciò che i Suoi debitori devono firmare prima del finanziamento: il livello che ogni debitore deve firmare prima che una richiesta di factoring a Lei assegnata possa essere finanziata (receipt, poi acknowledgment, poi acceptance), se contano solo i testi di dichiarazione approvati da un avvocato, le Sue richieste aperte per livello, e per quali livelli ogni legge applicabile ha un testo di dichiarazione, e in quali lingue.

Ambito

requests:read

Risposta

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

Errori

Solo quelli comuni (401, 403, 500).

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

PUT/v1/settings

Cambiare ciò che i Suoi debitori devono firmare. La modifica si applica alle richieste assegnate a Lei da quel momento; una richiesta già assegnata mantiene il livello con cui è stata assegnata. reason resta registrato nella catena di evidenze di Advanta.

Ambito

settings:write o decisions:write

Risposta

200{ …settings, changed, open_requests_keep_their_level }

Errori

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

Le condizioni del Suo programma: le Sue condizioni predefinite, quelle fissate per aziende specifiche, le aziende per cui può fissarle (quelle con una richiesta a Lei assegnata, e i Suoi clienti) e le Sue richieste di factoring contate per le condizioni che portano. Una richiesta prende le condizioni in vigore quando Le viene assegnata e le mantiene.

Ambito

requests:read

Risposta

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

Errori

Solo quelli comuni (401, 403, 500).

disclosure: announced (predefinito): ogni debitore riceve la notifica e conferma la cessione prima che Lei finanzi. confidential: quando la richiesta Le viene assegnata, la notifica a ogni debitore viene preparata, con la sua impronta (SHA-256), e conservata pronta all’invio, e il finanziamento non attende il debitore. Prima del finanziamento devono essere superati tutti i controlli bloccanti sulle fatture, le fatture devono provenire dalla contabilità del cedente stesso (ERP, fattura elettronica o SAF-T), ogni debitore deve avere una notifica preparata e aggiornata che nomina Lei e un indirizzo a cui inviarla, e la verifica del cedente deve essere approvata. Le notifiche vengono inviate quando Lei notifica la richiesta e, automaticamente, su una richiesta finanziata, quando si verifica un evento che ha attivato: announce_overdue_days, announce_on_dispute, announce_on_kyc_lapse.

recourse: with (pro solvendo) o without (pro soluto). recourse_days: giorni dopo la scadenza di una fattura prima che una richiesta finanziata non ancora saldata apra una richiesta di regresso (null: nessuna). bank_data: off, requested (si chiede al cedente di collegare per Lei il suo conto aziendale, in sola lettura e con il suo consenso) o required (il finanziamento attende anche che il conto su cui Lei paga sia confermato come del cedente stesso).

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

Cambiare le Sue condizioni predefinite (senza seller_id) o quelle di un’azienda. Cambiano solo le chiavi inviate; {"reset": true} con un seller_id riporta quell’azienda alle Sue condizioni predefinite. La modifica si applica alle richieste assegnate a Lei da quel momento; quelle già assegnate mantengono le loro condizioni. reason resta registrato nella catena di evidenze di Advanta.

Ambito

settings:write o decisions:write

Risposta

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

Errori

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

Notificare una richiesta confidenziale a Lei assegnata: diventa notificata e le notifiche preparate per essa vengono inviate ai suoi debitori, che poi le confermano come in un programma notificato. Possibile finché la richiesta è in attesa, in esame, con condizioni inviate, approvata o finanziata. Segue un evento request.announced; una volta inviata una notifica, la richiesta resta notificata.

Ambito

decisions:write

Risposta

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

Errori

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

Le notifiche di cessione della richiesta, una per debitore, ciascuna con il suo documento preparato quando c’è: l’oggetto e l’HTML esatti che il debitore riceve, la lingua, la legge applicabile e lo SHA-256. Per una richiesta a Lei assegnata, o una su cui ha già agito.

Ambito

requests:read

Risposta

200{ request_id, count, notices[] }

Errori

404not_found

L’HTML contiene un segnaposto, ACK_LINK tra doppie parentesi graffe, dove va il link di conferma del debitore; il link contiene un segreto e non viene mai mostrato. current dice se il documento corrisponde ancora alle fatture e all’importo della notifica.

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

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

Ciò che il cedente condivide con Lei del suo conto aziendale, in sola lettura e con il suo consenso, tramite un prestatore autorizzato di servizi di informazione sui conti: il collegamento, i conti (gli ultimi quattro caratteri di ogni IBAN) e i saldi, dodici mesi di movimenti per mese e la verifica del suo conto di accredito. cash_flow è null finché il cedente non ha collegato un conto per Lei.

Ambito

requests:read

Risposta

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

Errori

404not_found

bank_data_problems dice cosa attende ancora il finanziamento quando le Sue condizioni richiedono i dati bancari. payment_alerts sono i pagamenti che il cedente ha ricevuto da un debitore di questa richiesta dopo che Lei l’ha finanziata a condizioni confidenziali. Il consenso di un cedente è dato a un finanziatore: Lei vede solo ciò che condivide con Lei.

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

GET/v1/recourse

Le Sue richieste di factoring finanziate per tipo di regresso (with, without, e not_recorded per quelle assegnate prima del 28 settembre 2026), le richieste di regresso contate per tipo e stato, e le richieste stesse, prima quelle aperte. Se ne apre una per richiesta quando una richiesta finanziata non è saldata recourse_days dopo la scadenza di una fattura: recourse, verso il cedente, per l’importo anticipato più le Sue commissioni, meno quanto già incassato; debtor_default, pro soluto, per il Suo recupero crediti e la Sua assicurazione.

Ambito

requests:read

Risposta

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

Errori

422status_invalid

Il cedente rimborsa una richiesta di regresso su pay_to_iban indicando pay_reference. Quando i pagamenti che Lei registra da quel momento (una riga di estratto conto che conferma, o la decisione settle) coprono claim_amount, la richiesta di regresso è saldata e la richiesta si chiude come saldata per regresso: le fatture tornano al cedente, ancora non pagate dal debitore.

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

POST/v1/recourse/{id}/close

Chiudere una Sua richiesta di regresso aperta: una richiesta di regresso diventa withdrawn (vi ha rinunciato, o ha concordato altro con il cedente), un inadempimento del debitore diventa written_off (passato al Suo recupero crediti o al Suo assicuratore). reason resta registrato nella catena di evidenze di Advanta.

Ambito

decisions:write

Risposta

200{ claim_id, status }

Errori

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

Il Suo conto di incasso, collegato dal Suo amministratore nel portale e letto allo stesso modo: i movimenti passano per la stessa riconciliazione di POST /v1/statements, così gli incassi si abbinano alle Sue richieste finanziate senza inviare file. Inoltre: quanti cedenti condividono il loro conto con Lei, gli avvisi di pagamento sulle Sue richieste (gli ultimi 180 giorni) e i costi del prestatore registrati a Suo carico, per mese.

Ambito

requests:read

Risposta

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

Errori

Solo quelli comuni (401, 403, 500).

unit_price_eur e amount_eur sono null finché il prezzo del prestatore non è fissato.

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

GET/v1/credit-limits

Il Suo registro per debitore: il Suo limite e ciò che è in essere, impegnato, offerto e ancora disponibile, in euro.

Ambito

limits:read o requests:read

Risposta

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

Errori

Solo quelli comuni (401, 403, 500).

Ogni debitore contiene debtor_key, debtor_name, debtor_country, limit_status, limit_amount, outstanding, committed, offered, available, overdue_count, oldest_overdue, frozen, decided_at e note.

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

PUT/v1/credit-limits

Fissare o rivedere il Suo limite su un debitore, o rifiutare il debitore. Il database rifiuta ogni offerta successiva che questo limite non può sostenere.

Ambito

limits:write o decisions:write

Risposta

200{ credit_limit }

Errori

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

Caricare fino a 2.000 limiti su debitori in una sola chiamata: il Suo registro, o i limiti della Sua assicurazione crediti. Ogni riga è verificata esattamente come PUT /v1/credit-limits ne verifica uno e riceve una risposta propria: una riga che non passa non ferma le altre, e un debitore che compare due volte nella stessa chiamata viene rifiutato la seconda volta.

Ambito

limits:write o decisions:write

Risposta

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

Errori

413too_many_rows

422rows_required, invalid_source, source_ref_invalid, source_ref_too_long

Ogni limite scritto registra la sua fonte e il suo riferimento, sul limite e nel suo storico. La risposta conta received, written e refused, e risponde a ogni riga con row (contando da 1), debtor_tax_id e ok: una riga scritta aggiunge debtor_key, status e amount; una riga rifiutata dà il suo error (invalid_amount, debtor_tax_id_required, duplicate_debtor, invalid_status, amount_required, invalid_country, row_invalid o invalid_limit) e può aggiungere un detail.

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

Il Suo registro per cedente, con le stesse cifre del registro dei debitori.

Ambito

limits:read o requests:read

Risposta

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

Errori

Solo quelli comuni (401, 403, 500).

Ogni cedente contiene seller_id, seller_name, seller_nif, seller_country e gli stessi campi di limite ed esposizione di un debitore.

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

PUT/v1/seller-limits

Fissare o rivedere il Suo limite su un cedente, o rifiutare il cedente.

Ambito

limits:write o decisions:write

Risposta

200{ seller_limit }

Errori

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

Come un acquirente paga i propri fornitori, solo in forma aggregata, dalla contabilità dei fornitori collegati ad Advanta. Il profilo è pubblicato quando almeno tre fornitori osservano l’acquirente; altrimenti status dice perché e ogni cifra è null. Può leggerlo solo per un acquirente presente in una richiesta del Suo ambito o nella Sua lista di debitori; una chiave sandbox legge il profilo del piano dimostrativo.

Ambito

limits:read o requests:read

Risposta

200{ funder, payer_record }

Errori

404not_found (l’acquirente non è in nessuna richiesta del Suo ambito né nella Sua lista di debitori)

422tax_id_required

Le cifre comprendono observers, invoice_count, avg_days_to_pay, median_days_to_pay, on_time_pct, il ritardo di pagamento (avg_settle_delay_days, median_settle_delay_days, p75_settle_delay_days, worst_settle_delay_days), i conteggi di fatture aperte e scadute, window_from e refreshed_at. payer_record è null quando non c’è un profilo.

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

GET/v1/requests/{id}/debtors

Ciò che Advanta sa di ogni debitore di una richiesta di factoring a Lei assegnata, o di una su cui ha già agito: il suo level su Advanta da level_since (notice: conosce Advanta solo dalla notifica; account: ha attivato il suo conto pagatore; books: ha collegato il suo sistema contabile; buyer: gestisce un programma acquirente, e buyer_programme è true), lo storico del cedente stesso con lui, il suo tempo medio di pagamento ufficiale quando è un ente pubblico, e il Suo limite su di lui.

Ambito

requests:read

Risposta

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

Errori

404not_found

score è il punteggio del debitore stesso (classe, da 0 a 100, quando e con quale versione del modello). È dato solo quando il debitore condivide i suoi dati con i finanziatori che finanziano fatture dovute da lui, è al livello books o buyer, e la richiesta è a Lei assegnata (non una su cui ha solo agito); altrimenti è null. pair_history è lo storico del cedente con questo debitore su 36 mesi, con le regole del profilo di pagamento: solo fatture reali, e ritardo solo rispetto alle scadenze indicate sul documento o nell’ERP. public_payment_period è il più recente tempo medio di pagamento ufficiale di un ente pubblico (DGAL per i comuni portoghesi, Hacienda per gli enti locali spagnoli). credit_limit è il Suo limite sul debitore, da dove viene (source, source_ref) e quanto è utilizzato (exposure: in essere più impegnato più offerto, in euro).

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

POST/v1/statements

Inviare l’estratto del Suo conto di incasso per la riconciliazione: un file CAMT.053 (XML) o CSV, al massimo 4 MiB e 5.000 movimenti. Ogni accredito viene riconciliato con le Sue richieste finanziate, prima di tutto sul riferimento indicato dal debitore. Nulla viene registrato come incassato finché Lei non conferma un abbinamento nel portale. Lo stesso file inviato due volte viene rifiutato, in base al suo SHA-256.

Ambito

statements:write o decisions:write

Risposta

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

Errori

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

Il Suo link aperto (prescriber_id null) e il link attuale di ogni segnalatore, con il suo state (active, disabled o expired) e il suo url finché funziona.

Ambito

requests:read, clients:write o decisions:write

Risposta

200{ funder, count, client_links[] }

Errori

422lang_invalid

Un’azienda che apre un link indica nome, numero fiscale, paese ed email, e riceve il Suo invito via email. Quando lo accetta, diventa Sua cliente: le sue richieste vengono assegnate solo a Lei, e la sua origine (il link, il segnalatore, la data) viene registrata. Aprire un link non crea mai da solo un account.

Ogni link riporta anche arrivals (le aziende arrivate da Lei per la prima volta tramite quel link) e claims_last_day (le iscrizioni tramite il link nelle ultime 24 ore; un link ne accetta al massimo 20 all’ora e 100 al giorno).

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

POST/v1/client-links

Emettere il Suo link aperto, o quello di un segnalatore con prescriber_id. C’è un solo link funzionante per titolare: finché ne funziona uno, invii replace: true per sostituirlo (il precedente smette subito di funzionare); altrimenti 409 link_exists. Si conserva solo lo SHA-256 del token del link, e l’emissione viene registrata nella catena di evidenze di Advanta.

Ambito

clients:write o decisions:write

Risposta

201{ client_link }

Errori

404not_found

409link_exists

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

Un link emesso con una chiave sandbox crea solo inviti di test, e la chiave ha bisogno di decisions:write: i link del finanziatore dimostrativo sono condivisi da tutte le dimostrazioni.

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

Disattivare un link. Smette subito di funzionare; le aziende già arrivate tramite il link mantengono la loro origine. Disattivare un link già disattivato non cambia nulla (changed è false). Per darne uno nuovo, chiami POST /v1/client-links.

Ambito

clients:write o decisions:write

Risposta

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

Errori

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

I Suoi segnalatori, le persone e gli studi che Le portano clienti (commercialisti, consulenti, mediatori), prima quelli attivi, ognuno con il suo link attuale e il numero di aziende arrivate tramite esso. Sono Suoi, non partner di Advanta. Lo stesso elenco della pagina Clienti del Suo portale.

Ambito

requests:read, clients:write o decisions:write

Risposta

200{ funder, count, prescribers[] }

Errori

422lang_invalid

Una chiave sandbox legge i segnalatori del finanziatore dimostrativo, condivisi da tutte le dimostrazioni.

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

POST/v1/prescribers

Aggiungere un segnalatore. Il suo link aperto viene emesso insieme a lui, in prescriber.link.url. Il suo nome e la sua email restano fuori dalla catena di evidenze di Advanta: vi entrano solo i loro hash.

Ambito

clients:write o decisions:write

Risposta

201{ prescriber }

Errori

409prescriber_exists

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

Con una chiave sandbox questo cambia lo stato dimostrativo condiviso, quindi la chiave ha bisogno di 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

Disattivare un segnalatore. Il suo link smette subito di funzionare; le aziende che ha portato restano attribuite a lui. Disattivare un segnalatore già disattivato non cambia nulla (changed è false). Registrato nella catena di evidenze di Advanta.

Ambito

clients:write o decisions:write

Risposta

200{ prescriber, changed }

Errori

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

Che cosa Le ha portato ogni segnalatore: un gruppo per segnalatore, poi il Suo link (own_link), i Suoi inviti per nome (named) e i Suoi link di onboarding (api). Per gruppo e per azienda: quando è arrivata, quando è stato aperto il suo account (joined), quando è stata approvata la verifica dell’azienda (onboarded), le richieste assegnate a Lei, l’importo richiesto e l’importo finanziato. Gli stessi numeri del Suo portale.

Ambito

requests:read, clients:write o decisions:write

Risposta

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

Errori

405method_not_allowed

Un’azienda conta una volta, per chi l’ha portata da Lei per primo. L’importo finanziato è l’anticipo (altrimenti il totale) delle richieste finanziate o incassate, in euro; totals somma tutti i gruppi. Solo i Suoi dati e solo aziende del Suo piano di dati: una chiave sandbox non vede ciò che altre chiavi sandbox hanno fatto tramite l’API.

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

Tutti i Suoi inviti, dal più recente: tramite un link, per nome nel portale o con un link di onboarding. Ognuno indica come è arrivata l’azienda (via: link, named o api), il segnalatore che l’ha portata, se c’è, il suo state (pending, accepted, revoked o expired), l’azienda, il contatto e le date.

Ambito

requests:read, clients:write o decisions:write

Risposta

200{ funder, count, invitations[] }

Errori

405method_not_allowed

Solo il Suo piano di dati. Una chiave sandbox non vede gli inviti fatti da altre chiavi sandbox.

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

GET/v1/opportunities

Il riepilogo di un giorno, dai Suoi clienti (le aziende di cui Lei è il finanziatore di riferimento) che Le permettono di vedere le loro fatture. Ogni mattina verso le 06:30 ora di Madrid, dopo la prequalifica notturna, Advanta elenca le fatture diventate ammissibili secondo le Sue regole dal riepilogo precedente (kind new) e ciò che è cambiato in quelle che Le sono già state mostrate: paid, disputed (il cliente ha registrato che il suo debitore la contesta) o no_longer_eligible.

Ambito

requests:read

Risposta

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

Errori

404not_found

405method_not_allowed

422invalid_date

Una riga porta la fattura, il debitore con il suo codice fiscale, l’importo ancora dovuto, la scadenza, e il cliente con il suo settore (sezione NACE), la classe e la dimensione; prima le righe nuove, poi i cambiamenti. no_longer_eligible ha un reason: requested (il cliente ha chiesto di finanziarla), cancelled, removed (non è più nei libri del cliente), left_programme, not_shared (il cliente ha smesso di condividere) o rules (non rispetta più le Sue regole).

digest riporta i totali: quanti clienti condividono e quanti non ancora, cosa è ammissibile oggi, cosa è nuovo e cosa è cambiato. stale è true quando l’elaborazione notturna non è terminata: quella mattina non è stato confrontato nulla. Un riepilogo è un elenco calcolato dal database, non un’offerta: una richiesta viene verificata di nuovo quando viene fatta, e Lei decide come sempre. Il webhook opportunities.daily dice quando è pronto un riepilogo con qualcosa dentro.

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

I Suoi endpoint attivi, senza i segreti, e i tipi di evento a cui può abbonarsi. Una chiave sandbox vede solo gli endpoint che ha creato.

Ambito

webhooks:write, decisions:write o requests:read

Risposta

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

Errori

Solo quelli comuni (401, 403, 500).

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

POST/v1/webhooks

Registrare un endpoint. La risposta contiene il suo segreto di firma, che non viene più mostrato.

Ambito

webhooks:write o decisions:write

Risposta

201{ webhook, secret, signature }

Errori

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

Al massimo 10 endpoint attivi.

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}

Fermare un endpoint. Le consegne ancora in attesa vengono annullate e i suoi segreti eliminati.

Ambito

webhooks:write o decisions:write

Risposta

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

Errori

404not_found

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

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

Un nuovo segreto di firma, mostrato una sola volta. Il segreto precedente continua a firmare, come secondo v1 nell’header, per keep_previous_hours, così può passare al nuovo senza perdere eventi.

Ambito

webhooks:write o decisions:write

Risposta

200{ webhook, secret, previous_secret_valid_until }

Errori

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

Mettere in coda un evento webhook.test verso questo endpoint. La prossima esecuzione del dispatcher lo consegna, entro circa un minuto.

Ambito

webhooks:write o decisions:write

Risposta

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

Errori

404not_found

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

GET/v1/webhooks/{id}/deliveries

Il registro di consegna di un endpoint, dalla più recente: stato (pending, delivered, failed o cancelled), tentativi, codice di risposta, ultimo errore, prossimo tentativo e lo SHA-256 del body esatto inviato.

Ambito

webhooks:write, decisions:write o requests:read

Risposta

200{ count, deliveries[] }

Errori

404not_found

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

POST/v1/onboarding-links

Un link di onboarding a uso singolo per uno dei Suoi fornitori, attribuito a Lei. Advanta non invia email: è Lei a dare l’url al Suo fornitore. Quando il fornitore ha inviato la verifica della sua azienda, Lei riceve onboarding.completed, e il fornitore viene rimandato al Suo return_url con uno stato firmato.

Ambito

onboarding:write o decisions:write

Risposta

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

Errori

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

La risposta contiene return_secret (ors_ seguito da 64 caratteri esadecimali), mostrato una sola volta: lo conservi subito. Si conserva solo lo SHA-256 del token del link. Un link creato con una chiave sandbox registra il fornitore come azienda di test sul piano dimostrativo.

Quando il fornitore torna, il return_url porta advanta_onboarding (l’id del link), advanta_status (completed), advanta_ts (secondi Unix) e advanta_sig: l’HMAC-SHA256 esadecimale di <advanta_onboarding>.<advanta_status>.<advanta_ts>, con il Suo return_secret come chiave. Lo verifichi prima che la Sua pagina si fidi dello stato, e rifiuti un ritorno a più di 600 secondi dal Suo orologio; l’ultimo esempio qui sotto fa entrambe le cose.

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

I Suoi link di onboarding, dal più recente, ognuno con il suo status: pending, account_created, completed, expired o revoked. Una chiave sandbox vede i link che ha creato.

Ambito

onboarding:write, decisions:write o requests:read

Risposta

200{ count, onboarding_links[] }

Errori

Solo quelli comuni (401, 403, 500).

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

GET/v1/onboarding-links/{id}

Un link di onboarding e a che punto è il fornitore. Una volta completato, seller_id è l’id che usa GET /v1/seller-limits.

Ambito

onboarding:write, decisions:write o requests:read

Risposta

200{ onboarding_link }

Errori

404not_found

405method_not_allowed

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

POST/v1/exports

Avvia un’esportazione di tutto ciò che il Suo finanziatore può vedere: richieste e la loro cronologia, offerte, fatture con la loro verifica, venditori (dati dell’azienda, il riepilogo KYC che può vedere, la verifica del rappresentante), debitori, notifiche con le risposte dei debitori e i dati dei certificati, le voci della catena di prova sulle Sue operazioni con gli hash e le radici giornaliere per verificarle, incassi ed estratti conto, rifiuti dei controlli, le Sue regole e i Suoi limiti, il Suo team, endpoint dei webhook (mai un segreto), chiavi API (mai una chiave), il Suo registro di audit e i Suoi documenti. Viene generata in background, di solito in meno di un minuto; export.ready avvisa quando è pronta.

Ambito

exports:write o decisions:write

Risposta

202{ funder, export }

Errori

403export_live_key_required

409export_in_progress

422body_invalid, lang_invalid

429export_rate_limited

Solo una chiave di produzione: una chiave sandbox risponde 403 export_live_key_required (il finanziatore dimostrativo è condiviso). Un’esportazione alla volta, al massimo 10 in 24 ore. La stessa esportazione è nella pagina Esportazione del portale, nelle impostazioni.

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

Le Sue esportazioni, dal portale e dall’API, dalla più recente, con stato, dimensione e manifest_sha256.

Ambito

exports:write o decisions:write

Risposta

200{ funder, count, exports[] }

Errori

403export_live_key_required

405method_not_allowed

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

GET/v1/exports/{id}

Un’esportazione. Mentre viene generata: status queued o running, con progress. Una volta ready, e per 24 ore: files, ogni volume con un link valido al massimo un’ora (mai oltre quelle 24 ore). La richieda di nuovo per link nuovi; ogni chiamata che restituisce link viene registrata. Dopo 24 ore i file vengono cancellati e il record resta.

Ambito

exports:write o decisions:write

Risposta

200{ funder, export, files[] }

Errori

403export_live_key_required

404not_found

405method_not_allowed

manifest_sha256 è lo SHA-256 di manifest.json scritto senza quel campo, con le chiavi ordinate e senza spazi. Advanta ha registrato lo stesso valore nella catena di prova (voce export.ready); verify.py lo ricalcola e controlla ogni file e le voci di prova.

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

Quando i documenti erano troppo grandi per essere inclusi (documents_mode links): ogni documento dell’esportazione con un link valido per 15 minuti, una pagina alla volta. L’elenco viene calcolato al momento della richiesta: un documento che non può più leggere non compare.

Ambito

exports:write o decisions:write

Risposta

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

Errori

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"