API financeur d’Advanta

GET/v1/health

Indique si l’API fonctionne. Publique : sans clé, sans données, sans accès à la base de données.

Portée

Aucune : publique, sans clé

Renvoie

200{ status, api_version, time }

Erreurs

Aucune

Advanta interroge cette route toutes les 5 minutes ; les résultats sont publiés sur la page d’état publique.

curl -s "$BASE/v1/health"

GET/v1/me

Qui appelle : la clé, son financeur, son environnement et ses portées.

Portée

Toute clé valide

Renvoie

200{ api_version, environment, funder, key }

Erreurs

405method_not_allowed

key.prefix correspond aux 12 premiers caractères de la clé. key.expires_at vaut null pour une clé qui n’expire pas ; key.prospect indique à qui une clé sandbox a été émise.

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

Les demandes qui vous sont adressées (vous pouvez agir dessus) et celles sur lesquelles vous avez déjà agi (en lecture seule, même après une réaffectation), de la plus récente à la plus ancienne, chacune avec votre propre offre dans my_offer si vous en avez fait une.

Portée

requests:read

Renvoie

200{ funder, count, requests[] }

Erreurs

Seulement les codes communs (401, 403, 500).

Une demande comporte id, request_ref, type (factoring ou confirming), status, total_amount, advance_amount, le cédant dans company_name et company_nif, invoice_count, assigned_bank_id, consent_level_required (ce que chaque débiteur doit signer avant qu’elle puisse être financée, fixé à son adressage), ses dates et, par débiteur, debtor_consent. La spécification liste tous les champs.

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}

Le dossier d’analyse d’une demande : la demande, ses créances, le dernier Advanta Score du cédant, votre propre offre et risk, les signaux de fraude et les contestations de la demande, tels que votre portail les montre.

Portée

requests:read

Renvoie

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

Erreurs

404not_found

score va de 300 à 850, avec une note de A à E et ses dimensions. Il est calculé à la volée quand le cédant n’en a pas encore, et vaut null si ce calcul échoue. Chaque créance a invoice_no, invoice_amount, invoice_date, invoice_due_date et le débiteur dans customer_name. debtor_consent donne, par débiteur, le statut de la notification, le niveau exigé et le niveau signé (level_achieved), meets_requirement, le canal, le texte de déclaration signé et le signataire.

risk.signals liste les signaux de fraude encore ouverts ou confirmés, chacun avec un code stable (par exemple amount_above_history) et une severity. Un signal hard (par exemple un montant modifié pendant que la facture est dans une demande, un avoir sur cette facture ou une contestation ouverte) bloque l’adressage et le financement jusqu’à ce que l’équipe des opérations d’Advanta l’examine ; les autres ne font que signaler. risk.disputes liste toutes les contestations enregistrées contre la demande.

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

POST/v1/requests/{id}/decision

Proposer des conditions, refuser, financer ou enregistrer un règlement. La demande doit vous être adressée ; sinon, 409 not_routed_to_you.

Le corps prend l’une de quatre formes, selon decision :

Portée

decisions:write

Renvoie

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)

Erreurs

400reason_required

403not_your_request (settle uniquement : vous n’êtes pas le financeur de la demande)

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

Relever ce que les débiteurs d’une demande doivent signer. Uniquement à la hausse, uniquement sur une demande d’affacturage qui vous est adressée et en cours, et uniquement avant qu’un de ses débiteurs ait répondu.

Portée

decisions:write

Renvoie

200{ request_id, consent_level_required, changed, from }

Erreurs

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

Le dossier documentaire d’une demande. Quand la demande vous a été adressée, puis quand elle a été financée, Advanta a enregistré quelle version de chaque document que vous exigez vous a donné satisfaction : nom du fichier, SHA-256, dates d’émission et de validité, et quand et comment Advanta l’a vérifié. Cet enregistrement ne change jamais, même quand le cédant dépose des versions plus récentes ; chaque entrée indique aussi où en est le document aujourd’hui, et current liste les documents actuels du cédant.

Portée

requests:read

Renvoie

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

Erreurs

404not_found

Chaque entrée avec un fichier porte une download_url valable deux minutes (url_expires_in), et chaque URL émise est journalisée. Comparez le SHA-256 de ce que vous téléchargez avec celui enregistré.

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

GET/v1/required-documents

Les documents que vous exigez des cédants, par pays du cédant, et le catalogue dans lequel ils sont choisis : le code de chaque document, son nom en sept langues, l’émetteur, la validité habituelle et la sensibilité. La validité habituelle ne sert qu’à pré-remplir : c’est la date imprimée sur le document qui compte, celle que le cédant saisit et qu’Advanta vérifie.

Portée

requests:read

Renvoie

200{ funder, required, catalogue[] }

Erreurs

Seulement les codes communs (401, 403, 500).

Une demande ne vous est adressée, votre offre n’est enregistrée et la demande n’est financée que tant que chaque document de votre liste pour le pays du cédant est vérifié par Advanta et valide à cette date ; sinon, 409 documents_missing_for_funder.

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

PUT/v1/required-documents

Remplacer votre liste pour un pays de cédants ; une liste vide l’efface. Les codes viennent du catalogue, et le changement est conservé dans la chaîne de preuves d’Advanta avec note. Les demandes déjà chez vous y restent ; votre prochaine offre ou votre prochain financement sur l’une d’elles attend que le cédant satisfasse la nouvelle liste (open_requests_not_meeting les compte).

Portée

settings:write ou decisions:write

Renvoie

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

Erreurs

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

Ce que vos débiteurs doivent signer avant que vous financiez : le niveau que chaque débiteur doit signer avant qu’une demande d’affacturage qui vous est adressée puisse être financée (receipt, puis acknowledgment, puis acceptance), si seuls comptent les textes de déclaration approuvés par un avocat, vos demandes ouvertes par niveau, et les niveaux pour lesquels chaque droit applicable a un texte de déclaration, et dans quelles langues.

Portée

requests:read

Renvoie

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

Erreurs

Seulement les codes communs (401, 403, 500).

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

PUT/v1/settings

Modifier ce que vos débiteurs doivent signer. Le changement s’applique aux demandes qui vous sont adressées à partir de ce moment ; une demande déjà adressée garde le niveau avec lequel elle l’a été. reason est conservé dans la chaîne de preuves d’Advanta.

Portée

settings:write ou decisions:write

Renvoie

200{ …settings, changed, open_requests_keep_their_level }

Erreurs

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

Les conditions de votre programme : vos conditions par défaut, celles que vous avez fixées pour certaines entreprises, les entreprises pour lesquelles vous pouvez en fixer (celles qui ont une demande qui vous est adressée, et vos propres clients) et vos demandes d’affacturage comptées selon les conditions qu’elles portent. Une demande prend les conditions en vigueur quand elle vous est adressée et les garde.

Portée

requests:read

Renvoie

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

Erreurs

Seulement les codes communs (401, 403, 500).

disclosure : announced (par défaut) : chaque débiteur reçoit la notification et confirme la cession avant que vous financiez. confidential : quand la demande vous est adressée, la notification à chaque débiteur est préparée, avec son empreinte (SHA-256), et conservée prête à l’envoi, et le financement n’attend pas le débiteur. Avant le financement, tous les contrôles bloquants des factures doivent être passés, les factures doivent venir de la comptabilité du cédant lui-même (ERP, facture électronique ou SAF-T), chaque débiteur doit avoir une notification préparée et à jour qui vous nomme et une adresse où l’envoyer, et la vérification du cédant doit être approuvée. Les notifications sont envoyées quand vous annoncez la demande, et automatiquement, sur une demande financée, quand un déclencheur que vous avez activé se produit : announce_overdue_days, announce_on_dispute, announce_on_kyc_lapse.

recourse : with (avec recours) ou without (sans recours). recourse_days : jours après l’échéance d’une facture avant qu’une demande financée pas encore réglée n’ouvre une réclamation (null : aucune). bank_data : off, requested (le cédant est invité à connecter pour vous son compte bancaire professionnel, en lecture seule et avec son consentement) ou required (le financement attend aussi que le compte sur lequel vous payez soit confirmé comme celui du cédant lui-même).

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

Modifier vos conditions par défaut (sans seller_id) ou celles d’une entreprise. Seules les clés envoyées changent ; {"reset": true} avec un seller_id ramène cette entreprise à vos conditions par défaut. Le changement s’applique aux demandes qui vous sont adressées à partir de ce moment ; les demandes déjà adressées gardent leurs conditions. reason est conservé dans la chaîne de preuves d’Advanta.

Portée

settings:write ou decisions:write

Renvoie

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

Erreurs

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

Annoncer une demande confidentielle qui vous est adressée : elle devient annoncée et les notifications préparées pour elle sont envoyées à ses débiteurs, qui les confirment ensuite comme dans un programme annoncé. Possible tant que la demande est en attente, à l’étude, avec des conditions envoyées, approuvée ou financée. Un événement request.announced suit ; une fois une notification envoyée, la demande reste annoncée.

Portée

decisions:write

Renvoie

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

Erreurs

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

Les notifications de cession de la demande, une par débiteur, chacune avec son document préparé quand il existe : l’objet et le HTML exacts que reçoit le débiteur, sa langue, le droit applicable et son SHA-256. Pour une demande qui vous est adressée, ou une sur laquelle vous avez déjà agi.

Portée

requests:read

Renvoie

200{ request_id, count, notices[] }

Erreurs

404not_found

Le HTML porte un marqueur, ACK_LINK entre doubles accolades, à l’endroit du lien de confirmation du débiteur ; le lien contient un secret et n’est jamais montré. current indique si le document correspond encore aux factures et au montant de la notification.

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

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

Ce que le cédant partage avec vous de son compte bancaire professionnel, en lecture seule et avec son consentement, par un prestataire agréé d’information sur les comptes : la connexion, ses comptes (les quatre derniers caractères de chaque IBAN) et leurs soldes, douze mois de mouvements par mois, et la vérification de son compte de versement. cash_flow vaut null tant que le cédant n’a pas connecté de compte pour vous.

Portée

requests:read

Renvoie

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

Erreurs

404not_found

bank_data_problems dit ce que le financement attend encore quand vos conditions exigent des données bancaires. payment_alerts sont les paiements que le cédant a reçus d’un débiteur de cette demande après que vous l’avez financée en conditions confidentielles. Le consentement d’un cédant est donné à un financeur : vous ne voyez que ce qu’il partage avec vous.

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

GET/v1/recourse

Vos demandes d’affacturage financées par type de recours (with, without, et not_recorded pour celles adressées avant le 28 septembre 2026), les réclamations comptées par type et statut, et les réclamations elles-mêmes, les ouvertes d’abord. Une réclamation s’ouvre une fois par demande, quand une demande financée n’est pas réglée recourse_days après l’échéance d’une facture : recourse, contre le cédant, pour le montant avancé plus vos frais, moins ce que vous avez déjà encaissé ; debtor_default, sans recours, pour votre propre recouvrement et votre assurance.

Portée

requests:read

Renvoie

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

Erreurs

422status_invalid

Le cédant rembourse une réclamation de recours sur pay_to_iban en indiquant pay_reference. Quand les paiements que vous enregistrez à partir de là (une ligne de relevé que vous confirmez, ou la décision settle) couvrent claim_amount, la réclamation est réglée et la demande se clôt comme réglée par recours : les factures reviennent au cédant, toujours impayées par le débiteur.

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

POST/v1/recourse/{id}/close

Clore une de vos réclamations ouvertes : une réclamation de recours devient withdrawn (vous y renoncez, ou vous avez convenu autre chose avec le cédant), un défaut du débiteur devient written_off (transmis à votre recouvrement ou à votre assureur). reason est conservé dans la chaîne de preuves d’Advanta.

Portée

decisions:write

Renvoie

200{ claim_id, status }

Erreurs

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

Votre propre compte d’encaissement, connecté par votre administrateur dans le portail et lu de la même façon : ses mouvements passent par le même rapprochement que POST /v1/statements, pour que les encaissements correspondent à vos demandes financées sans envoyer de fichier. Aussi : combien de cédants partagent leur compte avec vous, les alertes de paiement sur vos demandes (les 180 derniers jours) et les frais du prestataire enregistrés à votre charge, par mois.

Portée

requests:read

Renvoie

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

Erreurs

Seulement les codes communs (401, 403, 500).

unit_price_eur et amount_eur valent null tant que le prix du prestataire n’est pas fixé.

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

GET/v1/credit-limits

Votre registre par débiteur : votre limite et ce qui est en cours, engagé, proposé et encore disponible, en euros.

Portée

limits:read ou requests:read

Renvoie

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

Erreurs

Seulement les codes communs (401, 403, 500).

Chaque débiteur comporte debtor_key, debtor_name, debtor_country, limit_status, limit_amount, outstanding, committed, offered, available, overdue_count, oldest_overdue, frozen, decided_at et note.

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

PUT/v1/credit-limits

Fixer ou réviser votre limite sur un débiteur, ou refuser le débiteur. La base de données refuse toute offre ultérieure que cette limite ne peut pas absorber.

Portée

limits:write ou decisions:write

Renvoie

200{ credit_limit }

Erreurs

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

Charger jusqu’à 2 000 limites sur des débiteurs en un seul appel : votre propre registre, ou les limites de votre assureur-crédit. Chaque ligne est vérifiée exactement comme PUT /v1/credit-limits en vérifie une et reçoit sa propre réponse : une ligne en échec n’arrête pas les autres, et un débiteur présent deux fois dans le même appel est refusé la seconde fois.

Portée

limits:write ou decisions:write

Renvoie

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

Erreurs

413too_many_rows

422rows_required, invalid_source, source_ref_invalid, source_ref_too_long

Chaque limite écrite enregistre sa source et sa référence, sur la limite et dans son historique. La réponse compte received, written et refused, et répond à chaque ligne avec row (à partir de 1), debtor_tax_id et ok : une ligne écrite ajoute debtor_key, status et amount ; une ligne refusée donne son error (invalid_amount, debtor_tax_id_required, duplicate_debtor, invalid_status, amount_required, invalid_country, row_invalid ou invalid_limit) et peut ajouter 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

Votre registre par cédant, avec les mêmes chiffres que le registre des débiteurs.

Portée

limits:read ou requests:read

Renvoie

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

Erreurs

Seulement les codes communs (401, 403, 500).

Chaque cédant comporte seller_id, seller_name, seller_nif, seller_country et les mêmes champs de limite et d’exposition qu’un débiteur.

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

PUT/v1/seller-limits

Fixer ou réviser votre limite sur un cédant, ou refuser le cédant.

Portée

limits:write ou decisions:write

Renvoie

200{ seller_limit }

Erreurs

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

Comment un acheteur paie ses fournisseurs, uniquement en agrégé, à partir de la comptabilité des fournisseurs connectés à Advanta. L’historique est publié quand au moins trois fournisseurs observent l’acheteur ; sinon, status dit pourquoi et tous les chiffres valent null. Vous ne pouvez le lire que pour un acheteur présent sur une demande de votre périmètre ou sur votre liste de débiteurs ; une clé sandbox lit l’historique du plan de démonstration.

Portée

limits:read ou requests:read

Renvoie

200{ funder, payer_record }

Erreurs

404not_found (l’acheteur n’est sur aucune demande de votre périmètre ni sur votre liste de débiteurs)

422tax_id_required

Les chiffres comprennent observers, invoice_count, avg_days_to_pay, median_days_to_pay, on_time_pct, le retard de paiement (avg_settle_delay_days, median_settle_delay_days, p75_settle_delay_days, worst_settle_delay_days), des comptes de factures ouvertes et échues, window_from et refreshed_at. payer_record vaut null quand il n’y a pas d’historique.

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

GET/v1/requests/{id}/debtors

Ce qu’Advanta sait de chaque débiteur d’une demande d’affacturage qui vous est adressée, ou d’une sur laquelle vous avez déjà agi : son level sur Advanta depuis level_since (notice : il ne connaît Advanta que par la notification ; account : il a activé son compte de payeur ; books : il a connecté son logiciel comptable ; buyer : il gère un programme acheteur, et buyer_programme vaut true), l’historique du cédant lui-même avec lui, son délai moyen de paiement officiel quand c’est un organisme public, et votre limite sur lui.

Portée

requests:read

Renvoie

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

Erreurs

404not_found

score est le score propre du débiteur (note, de 0 à 100, quand et avec quelle version du modèle). Il n’est donné que si le débiteur partage ses données avec les financeurs qui financent des factures qu’il doit, est au niveau books ou buyer, et que la demande vous est adressée (pas une sur laquelle vous avez seulement agi) ; sinon il vaut null. pair_history est l’historique du cédant avec ce débiteur sur 36 mois, selon les règles de l’historique de paiement : uniquement des factures réelles, et un retard mesuré seulement par rapport aux échéances indiquées sur le document ou dans l’ERP. public_payment_period est le dernier délai moyen de paiement officiel d’un organisme public (DGAL pour les communes portugaises, Hacienda pour les collectivités locales espagnoles). credit_limit est votre limite sur le débiteur, son origine (source, source_ref) et ce qui est utilisé (exposure : en cours plus engagé plus proposé, en euros).

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

POST/v1/statements

Envoyer le relevé de votre compte d’encaissement pour rapprochement : un fichier CAMT.053 (XML) ou CSV, au plus 4 Mio et 5 000 opérations. Chaque crédit est rapproché de vos propres demandes financées, d’abord sur la référence indiquée par le débiteur. Rien n’est réglé tant que vous n’avez pas confirmé un rapprochement dans le portail. Le même fichier envoyé deux fois est refusé, d’après son SHA-256.

Portée

statements:write ou decisions:write

Renvoie

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

Erreurs

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

Votre propre lien ouvert (prescriber_id null) et le lien actuel de chaque prescripteur, avec son state (active, disabled ou expired) et son url tant qu’il fonctionne.

Portée

requests:read, clients:write ou decisions:write

Renvoie

200{ funder, count, client_links[] }

Erreurs

422lang_invalid

Une entreprise qui ouvre un lien donne son nom, son numéro fiscal, son pays et son e-mail, et reçoit votre invitation par e-mail. Quand elle l’accepte, elle devient votre cliente : ses demandes ne sont adressées qu’à vous, et son origine (le lien, le prescripteur, la date) est enregistrée. Ouvrir un lien ne crée jamais de compte à lui seul.

Chaque lien porte aussi arrivals (les entreprises dont la première arrivée chez vous est passée par lui) et claims_last_day (les inscriptions par ce lien sur les dernières 24 heures ; un lien en accepte au plus 20 par heure et 100 par jour).

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

POST/v1/client-links

Émettre votre propre lien ouvert, ou celui d’un prescripteur avec prescriber_id. Il y a un lien actif par titulaire : tant qu’un lien fonctionne, envoyez replace: true pour le remplacer (l’ancien cesse aussitôt de fonctionner) ; sinon 409 link_exists. Seul le SHA-256 du jeton du lien est conservé, et l’émission est enregistrée dans la chaîne de preuves d’Advanta.

Portée

clients:write ou decisions:write

Renvoie

201{ client_link }

Erreurs

404not_found

409link_exists

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

Un lien émis avec une clé sandbox ne crée que des invitations de test, et la clé a besoin de decisions:write : les liens du financeur de démonstration sont partagés par toutes les démonstrations.

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

Désactiver un lien. Il cesse aussitôt de fonctionner ; les entreprises déjà arrivées par lui gardent leur origine. Désactiver un lien déjà désactivé ne change rien (changed vaut false). Pour en donner un nouveau, appelez POST /v1/client-links.

Portée

clients:write ou decisions:write

Renvoie

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

Erreurs

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

Vos prescripteurs, les personnes et cabinets qui vous apportent des clients (experts-comptables, conseillers, courtiers), les actifs d’abord, chacun avec son lien actuel et le nombre d’entreprises arrivées par ce lien. Ce sont les vôtres, pas des partenaires d’Advanta. La même liste que la page Clients de votre portail.

Portée

requests:read, clients:write ou decisions:write

Renvoie

200{ funder, count, prescribers[] }

Erreurs

422lang_invalid

Une clé sandbox lit les prescripteurs du financeur de démonstration, que toutes les démonstrations partagent.

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

POST/v1/prescribers

Ajouter un prescripteur. Son propre lien ouvert est émis avec lui, dans prescriber.link.url. Son nom et son e-mail restent hors de la chaîne de preuves d’Advanta : seuls leurs hachages y figurent.

Portée

clients:write ou decisions:write

Renvoie

201{ prescriber }

Erreurs

409prescriber_exists

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

Avec une clé sandbox, cela modifie l’état de démonstration partagé : la clé a donc besoin de 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

Désactiver un prescripteur. Son lien cesse aussitôt de fonctionner ; les entreprises qu’il a apportées lui restent attribuées. Désactiver un prescripteur déjà désactivé ne change rien (changed vaut false). Enregistré dans la chaîne de preuves d’Advanta.

Portée

clients:write ou decisions:write

Renvoie

200{ prescriber, changed }

Erreurs

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

Ce que chaque prescripteur vous a apporté : un groupe par prescripteur, puis votre propre lien (own_link), vos invitations par nom (named) et vos liens d’entrée en relation (api). Par groupe et par entreprise : quand elle est arrivée, quand son compte a été ouvert (joined), quand la vérification de l’entreprise a été approuvée (onboarded), les demandes qui vous ont été adressées, le montant demandé et le montant financé. Les mêmes chiffres que votre portail.

Portée

requests:read, clients:write ou decisions:write

Renvoie

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

Erreurs

405method_not_allowed

Une entreprise compte une fois, pour qui vous l’a apportée en premier. Le montant financé est l’avance (à défaut, le total) des demandes financées ou réglées, en euros ; totals additionne tous les groupes. Seulement vos données et seulement les entreprises de votre plan de données : une clé sandbox ne voit pas ce que d’autres clés sandbox ont fait par 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

Toutes vos invitations, les plus récentes d’abord : par un lien, par nom dans le portail ou avec un lien d’entrée en relation. Chacune indique comment l’entreprise est arrivée (via : link, named ou api), le prescripteur qui l’a apportée le cas échéant, son state (pending, accepted, revoked ou expired), l’entreprise, le contact et les dates.

Portée

requests:read, clients:write ou decisions:write

Renvoie

200{ funder, count, invitations[] }

Erreurs

405method_not_allowed

Seulement votre propre plan de données. Une clé sandbox ne voit pas les invitations faites par d’autres clés sandbox.

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

GET/v1/opportunities

Le résumé d’un jour, pour vos propres clients (les entreprises dont vous êtes le financeur d’origine) qui vous permettent de voir leurs factures. Chaque matin vers 6 h 30, heure de Madrid, après la préqualification de la nuit, Advanta liste les factures devenues éligibles selon vos règles depuis le résumé précédent (kind new) et ce qui a changé dans celles qui vous ont déjà été montrées : paid, disputed (le client a enregistré que son débiteur la conteste) ou no_longer_eligible.

Portée

requests:read

Renvoie

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

Erreurs

404not_found

405method_not_allowed

422invalid_date

Une ligne porte la facture, le débiteur avec son numéro fiscal, le montant encore dû, l’échéance, et le client avec son secteur (section NACE), sa note et sa taille ; d’abord les nouvelles lignes, puis les changements. no_longer_eligible a un reason : requested (le client a demandé à la financer), cancelled, removed (elle n’est plus dans les livres du client), left_programme, not_shared (le client a cessé de partager) ou rules (elle ne respecte plus vos règles).

digest donne les totaux : combien de clients partagent et combien pas encore, ce qui est éligible aujourd’hui, ce qui est nouveau et ce qui a changé. stale vaut true quand le traitement de la nuit ne s’est pas terminé : rien n’a été comparé ce matin-là. Un résumé est une liste calculée par la base de données, pas une offre : une demande est vérifiée à nouveau quand elle est faite, et vous décidez comme toujours. Le webhook opportunities.daily signale qu’un résumé avec du contenu est prêt.

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

Vos endpoints actifs, sans leurs secrets, et les types d’événements auxquels vous pouvez vous abonner. Une clé sandbox ne voit que les endpoints qu’elle a créés.

Portée

webhooks:write, decisions:write ou requests:read

Renvoie

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

Erreurs

Seulement les codes communs (401, 403, 500).

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

POST/v1/webhooks

Enregistrer un endpoint. La réponse contient son secret de signature, qui ne sera plus affiché.

Portée

webhooks:write ou decisions:write

Renvoie

201{ webhook, secret, signature }

Erreurs

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

Au plus 10 endpoints actifs.

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}

Arrêter un endpoint. Les livraisons encore en attente sont annulées et ses secrets sont supprimés.

Portée

webhooks:write ou decisions:write

Renvoie

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

Erreurs

404not_found

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

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

Un nouveau secret de signature, affiché une seule fois. L’ancien secret continue de signer, en second v1 dans l’en-tête, pendant keep_previous_hours, pour que vous puissiez basculer sans perdre d’événements.

Portée

webhooks:write ou decisions:write

Renvoie

200{ webhook, secret, previous_secret_valid_until }

Erreurs

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

Mettre en file un événement webhook.test vers cet endpoint. La prochaine exécution du répartiteur le livre, en une minute environ.

Portée

webhooks:write ou decisions:write

Renvoie

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

Erreurs

404not_found

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

GET/v1/webhooks/{id}/deliveries

Le journal de livraison d’un endpoint, du plus récent au plus ancien : statut (pending, delivered, failed ou cancelled), tentatives, code de réponse, dernière erreur, prochaine tentative, et le SHA-256 du corps exact envoyé.

Portée

webhooks:write, decisions:write ou requests:read

Renvoie

200{ count, deliveries[] }

Erreurs

404not_found

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

POST/v1/onboarding-links

Un lien d’entrée en relation à usage unique pour l’un de vos fournisseurs, qui vous est attribué. Advanta n’envoie aucun e-mail : c’est vous qui remettez url à votre fournisseur. Quand le fournisseur a soumis la vérification de son entreprise, vous recevez onboarding.completed, et le fournisseur est renvoyé vers votre return_url avec un statut signé.

Portée

onboarding:write ou decisions:write

Renvoie

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

Erreurs

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 réponse contient return_secret (ors_ suivi de 64 caractères hexadécimaux), affiché une seule fois : conservez-le tout de suite. Seul le SHA-256 du jeton du lien est conservé. Un lien créé avec une clé sandbox enregistre le fournisseur comme entreprise de test sur le plan de démonstration.

Quand le fournisseur revient, return_url porte advanta_onboarding (l’id du lien), advanta_status (completed), advanta_ts (secondes Unix) et advanta_sig : le HMAC-SHA256 hexadécimal de <advanta_onboarding>.<advanta_status>.<advanta_ts>, avec votre return_secret pour clé. Vérifiez-le avant que votre page se fie au statut, et refusez un retour à plus de 600 secondes de votre horloge ; le dernier exemple ci-dessous fait les deux.

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

Vos liens d’entrée en relation, les plus récents d’abord, chacun avec son status : pending, account_created, completed, expired ou revoked. Une clé sandbox voit les liens qu’elle a créés.

Portée

onboarding:write, decisions:write ou requests:read

Renvoie

200{ count, onboarding_links[] }

Erreurs

Seulement les codes communs (401, 403, 500).

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

GET/v1/onboarding-links/{id}

Un lien d’entrée en relation et l’étape où en est le fournisseur. Une fois terminé, seller_id est l’id qu’utilise GET /v1/seller-limits.

Portée

onboarding:write, decisions:write ou requests:read

Renvoie

200{ onboarding_link }

Erreurs

404not_found

405method_not_allowed

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

POST/v1/exports

Lance un export de tout ce que votre financeur peut voir : demandes et leur historique, offres, factures avec leur vérification, vendeurs (données de l’entreprise, le résumé KYC que vous pouvez voir, la vérification du représentant), débiteurs, notifications avec les réponses des débiteurs et les données des certificats, les entrées de la chaîne de preuve sur vos opérations avec les hachages et les racines quotidiennes pour les vérifier, règlements et relevés, refus des contrôles, vos règles et limites, votre équipe, endpoints de webhook (jamais un secret), clés d’API (jamais une clé), votre piste d’audit et vos documents. Il est généré en arrière-plan, en général en moins d’une minute ; export.ready vous prévient.

Portée

exports:write ou decisions:write

Renvoie

202{ funder, export }

Erreurs

403export_live_key_required

409export_in_progress

422body_invalid, lang_invalid

429export_rate_limited

Une clé de production uniquement : une clé sandbox répond 403 export_live_key_required (le financeur de démonstration est partagé). Un export à la fois, au plus 10 en 24 heures. Le même export est sur la page Export du portail, dans les réglages.

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

Vos exports, depuis le portail et l’API, les plus récents d’abord, avec leur état, leur taille et manifest_sha256.

Portée

exports:write ou decisions:write

Renvoie

200{ funder, count, exports[] }

Erreurs

403export_live_key_required

405method_not_allowed

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

GET/v1/exports/{id}

Un export. Pendant sa génération : status queued ou running, avec progress. Une fois ready, et pendant 24 heures : files, chaque volume avec un lien valable une heure au plus (jamais au-delà de ces 24 heures). Redemandez-le pour de nouveaux liens ; chaque appel qui renvoie des liens est enregistré. Après 24 heures les fichiers sont supprimés et l’enregistrement reste.

Portée

exports:write ou decisions:write

Renvoie

200{ funder, export, files[] }

Erreurs

403export_live_key_required

404not_found

405method_not_allowed

manifest_sha256 est le SHA-256 de manifest.json écrit sans ce champ, clés triées, sans espaces. Advanta a enregistré la même valeur dans la chaîne de preuve (entrée export.ready) ; verify.py la recalcule et vérifie chaque fichier et les entrées de preuve.

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

Quand les documents étaient trop volumineux pour être inclus (documents_mode links) : chaque document de l’export avec un lien valable 15 minutes, une page à la fois. La liste est calculée au moment de la demande : un document que vous ne pouvez plus lire n’y figure pas.

Portée

exports:write ou decisions:write

Renvoie

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

Erreurs

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"