API de Advanta para financiadores

GET/v1/health

Si la API está funcionando. Pública: sin clave, sin datos, sin acceso a la base de datos.

Ámbito

Ninguna: pública, sin clave

Devuelve

200{ status, api_version, time }

Errores

Ninguno

Advanta consulta esta ruta cada 5 minutos; los resultados están en la página de estado pública.

curl -s "$BASE/v1/health"

GET/v1/me

Quién llama: la clave, su financiador, su entorno y sus ámbitos.

Ámbito

Cualquier clave válida

Devuelve

200{ api_version, environment, funder, key }

Errores

405method_not_allowed

key.prefix son los 12 primeros caracteres de la clave. key.expires_at es null para una clave que no caduca; key.prospect indica a quién se emitió una clave de 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

Las solicitudes que se le han enviado (puede actuar sobre ellas) y aquellas sobre las que ya actuó (solo lectura, incluso tras un reenvío a otro financiador), de la más reciente a la más antigua, cada una con su propia oferta en my_offer si la hizo.

Ámbito

requests:read

Devuelve

200{ funder, count, requests[] }

Errores

Solo los comunes (401, 403, 500).

Una solicitud trae id, request_ref, type (factoring o confirming), status, total_amount, advance_amount, el cedente en company_name y company_nif, invoice_count, assigned_bank_id, consent_level_required (lo que cada deudor debe firmar antes de poder financiarla, fijado cuando se envió), sus fechas y, por deudor, debtor_consent. La especificación recoge todos los campos.

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}

El expediente de análisis de una solicitud: la solicitud, sus créditos, el Advanta Score más reciente del cedente, su propia oferta y risk, las señales de fraude y las impugnaciones de la solicitud, tal como las muestra su portal.

Ámbito

requests:read

Devuelve

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

Errores

404not_found

score va de 300 a 850, con una nota de la A a la E y sus dimensiones. Se calcula en el momento cuando el cedente aún no tiene ninguno, y es null si eso falla. Cada crédito tiene invoice_no, invoice_amount, invoice_date, invoice_due_date y el deudor en customer_name. debtor_consent da, por deudor, el estado de la notificación, el nivel exigido y el nivel firmado (level_achieved), meets_requirement, el canal, el texto de la declaración firmado y quién lo firmó.

risk.signals lista las señales de fraude aún abiertas o confirmadas, cada una con un code estable (por ejemplo amount_above_history) y una severity. Una señal hard (por ejemplo un importe cambiado mientras la factura está en una solicitud, una factura rectificativa contra ella o una impugnación abierta) detiene la asignación y la financiación hasta que el equipo de operaciones de Advanta la revise; las demás solo avisan. risk.disputes lista todas las impugnaciones registradas contra la solicitud.

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

POST/v1/requests/{id}/decision

Ofertar condiciones, rechazar, financiar o registrar una liquidación. La solicitud debe estar enviada a usted; si no, 409 not_routed_to_you.

El cuerpo tiene una de cuatro formas, según decision:

Ámbito

decisions:write

Devuelve

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)

Errores

400reason_required

403not_your_request (solo en settle: no es el financiador de la solicitud)

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

Subir lo que deben firmar los deudores de una solicitud. Solo hacia arriba, solo en una solicitud de factoring enviada a usted y en curso, y solo antes de que alguno de sus deudores haya respondido.

Ámbito

decisions:write

Devuelve

200{ request_id, consent_level_required, changed, from }

Errores

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

El expediente documental de una solicitud. Cuando la solicitud se le envió, y de nuevo cuando se financió, Advanta registró qué versión de cada documento que usted exige le dio conformidad: el nombre del fichero, el SHA-256, las fechas de emisión y de validez, y cuándo y cómo lo verificó Advanta. Ese registro no cambia nunca, aunque el cedente suba versiones más recientes; cada entrada dice también en qué situación está hoy el documento, y current recoge los documentos actuales del cedente.

Ámbito

requests:read

Devuelve

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

Errores

404not_found

Cada entrada con fichero trae una download_url válida durante dos minutos (url_expires_in), y cada URL emitida queda registrada. Compare el SHA-256 de lo que descargue con el registrado.

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

GET/v1/required-documents

Los documentos que exige a los cedentes, por país del cedente, y el catálogo del que se eligen: el código de cada documento, su nombre en siete idiomas, el emisor, la validez habitual y la sensibilidad. La validez habitual solo sirve para rellenar por defecto: cuenta la fecha impresa en el documento, que el cedente registra y Advanta comprueba.

Ámbito

requests:read

Devuelve

200{ funder, required, catalogue[] }

Errores

Solo los comunes (401, 403, 500).

Una solicitud solo se le envía, su oferta solo se registra y la solicitud solo se financia mientras todos los documentos de su lista para el país del cedente estén verificados por Advanta y vigentes en esa fecha; si no, 409 documents_missing_for_funder.

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

PUT/v1/required-documents

Sustituir su lista para un país de cedentes; una lista vacía la borra. Los códigos vienen del catálogo, y el cambio queda guardado en la cadena de evidencias de Advanta con note. Las solicitudes que ya tiene siguen con usted; su próxima oferta o financiación en una de ellas espera hasta que el cedente cumpla la nueva lista (open_requests_not_meeting las cuenta).

Ámbito

settings:write o decisions:write

Devuelve

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

Errores

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

Lo que sus deudores deben firmar antes de financiar: el nivel que cada deudor debe firmar antes de que pueda financiarse una solicitud de factoring enviada a usted (receipt, luego acknowledgment, luego acceptance), si solo cuentan los textos de declaración aprobados por un abogado, sus solicitudes abiertas por nivel, y qué niveles tiene cada ley aplicable en texto de declaración, y en qué idiomas.

Ámbito

requests:read

Devuelve

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

Errores

Solo los comunes (401, 403, 500).

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

PUT/v1/settings

Cambiar lo que sus deudores deben firmar. El cambio se aplica a las solicitudes que se le envíen a partir de ese momento; una solicitud ya enviada mantiene el nivel con el que se envió. reason queda guardado en la cadena de evidencias de Advanta.

Ámbito

settings:write o decisions:write

Devuelve

200{ …settings, changed, open_requests_keep_their_level }

Errores

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

Los términos de su programa: sus términos por defecto, los que fijó para empresas concretas, las empresas para las que puede fijar términos (las que tienen una solicitud enviada a usted y sus propios clientes) y sus solicitudes de factoring contadas por los términos que llevan. Una solicitud toma los términos vigentes cuando se le envía y los conserva.

Ámbito

requests:read

Devuelve

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

Errores

Solo los comunes (401, 403, 500).

disclosure: announced (por defecto): cada deudor recibe la notificación y confirma la cesión antes de que usted financie. confidential: cuando la solicitud se le envía, la notificación a cada deudor se prepara, con su huella (SHA-256), y se guarda lista para enviar, y la financiación no espera al deudor. Antes de financiar, todas las comprobaciones bloqueantes de las facturas deben superarse, las facturas deben venir de la contabilidad del propio cedente (ERP, factura electrónica o SAF-T), cada deudor debe tener una notificación preparada y vigente que le nombra a usted y una dirección a la que enviarla, y la verificación del cedente debe estar aprobada. Las notificaciones se envían cuando usted anuncia la solicitud y, automáticamente, en una solicitud financiada, cuando se cumple un disparador que activó: announce_overdue_days, announce_on_dispute, announce_on_kyc_lapse.

recourse: with (con recurso) o without (sin recurso). recourse_days: días tras el vencimiento de una factura hasta que una solicitud financiada aún no liquidada abre una reclamación (null: ninguna). bank_data: off, requested (se pide al cedente que conecte su cuenta bancaria de empresa para usted, solo lectura y con su consentimiento) o required (la financiación espera además a que la cuenta en la que usted paga se confirme como del propio cedente).

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

Cambiar sus términos por defecto (sin seller_id) o los de una empresa. Solo cambian las claves que envíe; {"reset": true} con un seller_id devuelve esa empresa a sus términos por defecto. El cambio se aplica a las solicitudes que se le envíen a partir de ese momento; las ya enviadas conservan sus términos. reason queda guardado en la cadena de evidencias de Advanta.

Ámbito

settings:write o decisions:write

Devuelve

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

Errores

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

Anunciar una solicitud confidencial enviada a usted: pasa a anunciada y las notificaciones preparadas para ella se envían a sus deudores, que después las confirman como en un programa anunciado. Posible mientras la solicitud está pendiente, en estudio, con condiciones enviadas, aprobada o financiada. Le sigue un evento request.announced; una vez enviada una notificación, la solicitud queda anunciada.

Ámbito

decisions:write

Devuelve

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

Errores

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

Las notificaciones de cesión de la solicitud, una por deudor, cada una con su documento preparado cuando lo hay: el asunto y el HTML exactos que recibe el deudor, su idioma, la ley aplicable y su SHA-256. Para una solicitud enviada a usted, o una en la que ya actuó.

Ámbito

requests:read

Devuelve

200{ request_id, count, notices[] }

Errores

404not_found

El HTML lleva un marcador, ACK_LINK entre llaves dobles, donde va el enlace de confirmación del deudor; el enlace contiene un secreto y nunca se muestra. current indica si el documento aún coincide con las facturas y el importe de la notificación.

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

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

Lo que el cedente comparte con usted de su cuenta bancaria de empresa, solo lectura y con su consentimiento, a través de un proveedor autorizado de información sobre cuentas: la conexión, sus cuentas (los cuatro últimos caracteres de cada IBAN) y sus saldos, doce meses de movimientos por mes y la comprobación de su cuenta de cobro. cash_flow es null mientras el cedente no haya conectado una cuenta para usted.

Ámbito

requests:read

Devuelve

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

Errores

404not_found

bank_data_problems indica lo que la financiación aún espera cuando sus términos exigen datos bancarios. payment_alerts son los pagos que el cedente recibió de un deudor de esta solicitud después de que usted la financiara en términos confidenciales. El consentimiento de un cedente se da a un financiador: usted solo ve lo que comparte con usted.

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

GET/v1/recourse

Sus solicitudes de factoring financiadas por tipo de recurso (with, without, y not_recorded para las enviadas antes del 28 de septiembre de 2026), las reclamaciones contadas por tipo y estado, y las propias reclamaciones, primero las abiertas. Se abre una reclamación por solicitud cuando una solicitud financiada no está liquidada recourse_days después del vencimiento de una factura: recourse, contra el cedente, por el importe anticipado más sus comisiones, menos lo que ya cobró; debtor_default, sin recurso, para su propio recobro y seguro.

Ámbito

requests:read

Devuelve

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

Errores

422status_invalid

El cedente reembolsa una reclamación de recurso en pay_to_iban indicando pay_reference. Cuando los pagos que usted registre desde entonces (una línea de extracto que confirma, o la decisión settle) cubren claim_amount, la reclamación queda liquidada y la solicitud se cierra como liquidada por recurso: las facturas vuelven al cedente, aún impagadas por el deudor.

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

POST/v1/recourse/{id}/close

Cerrar una reclamación suya abierta: una reclamación de recurso queda withdrawn (renunció a ella, o acordó otra cosa con el cedente), un impago del deudor queda written_off (pasó a su recobro o a su aseguradora). reason queda guardado en la cadena de evidencias de Advanta.

Ámbito

decisions:write

Devuelve

200{ claim_id, status }

Errores

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

Su propia cuenta de cobro, conectada por su administrador en el portal y leída del mismo modo: sus movimientos pasan por la misma conciliación que POST /v1/statements, de modo que los cobros casan con sus solicitudes financiadas sin enviar ficheros. También cuántos cedentes comparten su cuenta con usted, las alertas de pago en sus solicitudes (los últimos 180 días) y los costes del proveedor registrados a su cargo, por mes.

Ámbito

requests:read

Devuelve

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

Errores

Solo los comunes (401, 403, 500).

unit_price_eur y amount_eur son null hasta que se fije el precio del proveedor.

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

GET/v1/credit-limits

Su libro por deudor: su límite y lo que está vivo, comprometido, ofertado y aún disponible, en euros.

Ámbito

limits:read o requests:read

Devuelve

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

Errores

Solo los comunes (401, 403, 500).

Cada deudor trae debtor_key, debtor_name, debtor_country, limit_status, limit_amount, outstanding, committed, offered, available, overdue_count, oldest_overdue, frozen, decided_at y note.

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

PUT/v1/credit-limits

Fijar o revisar su límite para un deudor, o rechazar al deudor. La base de datos rechaza cualquier oferta posterior que este límite no pueda cubrir.

Ámbito

limits:write o decisions:write

Devuelve

200{ credit_limit }

Errores

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

Cargar hasta 2.000 límites sobre deudores en una sola llamada: su propio libro, o los límites de su aseguradora de crédito. Cada fila se comprueba exactamente como PUT /v1/credit-limits comprueba uno y recibe su propia respuesta: una fila que falla no detiene a las demás, y un deudor que aparece dos veces en la misma llamada se rechaza la segunda vez.

Ámbito

limits:write o decisions:write

Devuelve

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

Errores

413too_many_rows

422rows_required, invalid_source, source_ref_invalid, source_ref_too_long

Cada límite escrito registra su origen y su referencia, en el límite y en su historial. La respuesta cuenta received, written y refused, y responde a cada fila con row (contando desde 1), debtor_tax_id y ok: una fila escrita añade debtor_key, status y amount; una fila rechazada da su error (invalid_amount, debtor_tax_id_required, duplicate_debtor, invalid_status, amount_required, invalid_country, row_invalid o invalid_limit) y puede añadir 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

Su libro por cedente, con las mismas cifras que el libro de deudores.

Ámbito

limits:read o requests:read

Devuelve

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

Errores

Solo los comunes (401, 403, 500).

Cada cedente trae seller_id, seller_name, seller_nif, seller_country y los mismos campos de límite y exposición que un deudor.

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

PUT/v1/seller-limits

Fijar o revisar su límite para un cedente, o rechazar al cedente.

Ámbito

limits:write o decisions:write

Devuelve

200{ seller_limit }

Errores

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

Cómo paga un comprador a sus proveedores, solo en agregado, a partir de la contabilidad de los proveedores conectados a Advanta. El historial se publica cuando al menos tres proveedores observan al comprador; si no, status explica por qué y todas las cifras son null. Solo puede leerlo para un comprador que esté en una solicitud de su ámbito o en su lista de deudores; una clave de sandbox lee el historial del plano de demostración.

Ámbito

limits:read o requests:read

Devuelve

200{ funder, payer_record }

Errores

404not_found (el comprador no está en ninguna solicitud de su ámbito ni en su lista de deudores)

422tax_id_required

Las cifras incluyen observers, invoice_count, avg_days_to_pay, median_days_to_pay, on_time_pct, el retraso en el pago (avg_settle_delay_days, median_settle_delay_days, p75_settle_delay_days, worst_settle_delay_days), recuentos abiertos y vencidos, window_from y refreshed_at. payer_record es null cuando no hay historial.

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

GET/v1/requests/{id}/debtors

Lo que Advanta sabe de cada deudor de una solicitud de factoring enviada a usted, o de una en la que ya actuó: su level en Advanta desde level_since (notice: conoce Advanta solo por la notificación; account: activó su cuenta de pagador; books: conectó su sistema contable; buyer: tiene un programa de comprador, y buyer_programme es true), el historial del propio cedente con él, su periodo medio de pago oficial cuando es un organismo público, y su límite sobre él.

Ámbito

requests:read

Devuelve

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

Errores

404not_found

score es la puntuación del propio deudor (clase, de 0 a 100, cuándo y con qué versión del modelo). Solo se da cuando el deudor comparte sus datos con los financiadores que financian facturas que él debe, está en el nivel books o buyer, y la solicitud está enviada a usted (no una en la que solo actuó); si no, es null. pair_history es el historial del cedente con este deudor a lo largo de 36 meses, con las reglas del historial de pagador: solo facturas reales, y retraso solo frente a fechas de vencimiento que constan en el documento o en el ERP. public_payment_period es el periodo medio de pago oficial más reciente de un organismo público (DGAL para los municipios portugueses, Hacienda para las entidades locales españolas). credit_limit es su límite sobre el deudor, de dónde viene (source, source_ref) y lo que está usado (exposure: vivo más comprometido más ofertado, en euros).

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

POST/v1/statements

Enviar el extracto de su cuenta de cobro para conciliarlo: un fichero CAMT.053 (XML) o CSV, como máximo 4 MiB y 5.000 movimientos. Cada abono se concilia con sus propias solicitudes financiadas, primero por la referencia que indicó el deudor. No se liquida nada hasta que usted confirme una coincidencia en el portal. El mismo fichero enviado dos veces se rechaza, por su SHA-256.

Ámbito

statements:write o decisions:write

Devuelve

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

Errores

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

Su propio enlace abierto (prescriber_id null) y el enlace actual de cada prescriptor, con su state (active, disabled o expired) y su url mientras funciona.

Ámbito

requests:read, clients:write o decisions:write

Devuelve

200{ funder, count, client_links[] }

Errores

422lang_invalid

Una empresa que abre un enlace da su nombre, su número fiscal, su país y su correo, y recibe su invitación por correo. Cuando la acepta, pasa a ser su cliente: sus solicitudes se le envían solo a usted, y su origen (el enlace, el prescriptor, la fecha) queda registrado. Abrir un enlace nunca crea una cuenta por sí solo.

Cada enlace lleva también arrivals (las empresas cuya primera llegada a usted fue por él) y claims_last_day (las altas por él en las últimas 24 horas; un enlace admite como mucho 20 por hora y 100 por día).

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

POST/v1/client-links

Emitir su propio enlace abierto, o el de un prescriptor con prescriber_id. Hay un enlace activo por titular: mientras uno siga funcionando, envíe replace: true para sustituirlo (el anterior deja de funcionar enseguida); si no, 409 link_exists. Solo se guarda el SHA-256 del token del enlace, y la emisión queda registrada en la cadena de evidencias de Advanta.

Ámbito

clients:write o decisions:write

Devuelve

201{ client_link }

Errores

404not_found

409link_exists

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

Un enlace emitido con una clave de sandbox solo genera invitaciones de prueba, y la clave necesita decisions:write: los enlaces del financiador de demostración los comparten todas las demostraciones.

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

Desactivar un enlace. Deja de funcionar enseguida; las empresas que ya llegaron por él conservan su origen. Desactivar un enlace ya desactivado no cambia nada (changed es false). Para dar uno nuevo, llame a POST /v1/client-links.

Ámbito

clients:write o decisions:write

Devuelve

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

Errores

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

Sus prescriptores, las personas y firmas que le traen clientes (gestorías, asesores, intermediarios), primero los activos, cada uno con su enlace actual y el número de empresas que llegaron por él. Son suyos, no socios de Advanta. La misma lista que la página Clientes de su portal.

Ámbito

requests:read, clients:write o decisions:write

Devuelve

200{ funder, count, prescribers[] }

Errores

422lang_invalid

Una clave de sandbox lee los prescriptores del financiador de demostración, que comparten todas las demostraciones.

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

POST/v1/prescribers

Añadir un prescriptor. Su propio enlace abierto se emite con él, en prescriber.link.url. Su nombre y su correo quedan fuera de la cadena de evidencias de Advanta: solo entran sus hashes.

Ámbito

clients:write o decisions:write

Devuelve

201{ prescriber }

Errores

409prescriber_exists

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

Con una clave de sandbox esto cambia el estado de demostración compartido, así que la clave necesita 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

Desactivar un prescriptor. Su enlace deja de funcionar enseguida; las empresas que trajo siguen atribuidas a él. Desactivar un prescriptor ya desactivado no cambia nada (changed es false). Queda registrado en la cadena de evidencias de Advanta.

Ámbito

clients:write o decisions:write

Devuelve

200{ prescriber, changed }

Errores

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

Lo que le trajo cada prescriptor: un grupo por prescriptor, después su propio enlace (own_link), sus invitaciones por nombre (named) y sus enlaces de alta (api). Por grupo y por empresa: cuándo llegó, cuándo se abrió su cuenta (joined), cuándo se aprobó la verificación de la empresa (onboarded), las solicitudes enviadas a usted, el importe solicitado y el importe financiado. Las mismas cifras que su portal.

Ámbito

requests:read, clients:write o decisions:write

Devuelve

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

Errores

405method_not_allowed

Una empresa cuenta una vez, para quien se la trajo primero. El importe financiado es el anticipo (o, si no lo hay, el total) de las solicitudes financiadas o liquidadas, en euros; totals suma todos los grupos. Solo sus datos y solo empresas de su plano de datos: una clave de sandbox no ve lo que otras claves de sandbox hicieron por la 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

Todas sus invitaciones, las más recientes primero: por un enlace, por nombre en el portal o con un enlace de alta. Cada una indica cómo llegó la empresa (via: link, named o api), el prescriptor que la trajo, si lo hay, su state (pending, accepted, revoked o expired), la empresa, el contacto y las fechas.

Ámbito

requests:read, clients:write o decisions:write

Devuelve

200{ funder, count, invitations[] }

Errores

405method_not_allowed

Solo su propio plano de datos. Una clave de sandbox no ve las invitaciones que hicieron otras claves de sandbox.

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

GET/v1/opportunities

El resumen de un día, de sus propios clientes (las empresas de las que usted es el financiador de origen) que le permiten ver sus facturas. Cada mañana hacia las 06:30, hora de Madrid, después de la precalificación nocturna, Advanta lista las facturas que han pasado a cumplir sus reglas desde el resumen anterior (kind new) y lo que ha cambiado en las que ya se le mostraron: paid, disputed (el cliente registró que su deudor la impugna) o no_longer_eligible.

Ámbito

requests:read

Devuelve

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

Errores

404not_found

405method_not_allowed

422invalid_date

Una línea trae la factura, el deudor con su NIF, el importe aún pendiente, la fecha de vencimiento, y el cliente con su sector (sección NACE), clase y tamaño; primero las líneas nuevas, después los cambios. no_longer_eligible tiene un reason: requested (el cliente pidió financiarla), cancelled, removed (ya no está en los libros del cliente), left_programme, not_shared (el cliente dejó de compartir) o rules (ya no cumple sus reglas).

digest lleva los totales: cuántos clientes comparten y cuántos aún no, lo que es elegible hoy, lo que es nuevo y lo que ha cambiado. stale es true cuando la lectura nocturna no terminó: esa mañana no se comparó nada. Un resumen es una lista que calculó la base de datos, no una oferta: una solicitud se comprueba de nuevo cuando se hace, y usted decide sobre ella como siempre. El webhook opportunities.daily avisa cuando hay un resumen con algo 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

Sus endpoints activos, sin sus secretos, y los tipos de evento a los que puede suscribirse. Una clave de sandbox solo ve los endpoints que creó.

Ámbito

webhooks:write, decisions:write o requests:read

Devuelve

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

Errores

Solo los comunes (401, 403, 500).

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

POST/v1/webhooks

Registrar un endpoint. La respuesta trae su secreto de firma, que no se vuelve a mostrar.

Ámbito

webhooks:write o decisions:write

Devuelve

201{ webhook, secret, signature }

Errores

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

Como máximo 10 endpoints activos.

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}

Detener un endpoint. Las entregas aún pendientes se cancelan y sus secretos se borran.

Ámbito

webhooks:write o decisions:write

Devuelve

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

Errores

404not_found

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

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

Un nuevo secreto de firma, que se muestra una sola vez. El secreto anterior sigue firmando, como segundo v1 en la cabecera, durante keep_previous_hours, para que pueda cambiar sin perder eventos.

Ámbito

webhooks:write o decisions:write

Devuelve

200{ webhook, secret, previous_secret_valid_until }

Errores

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

Poner en cola un evento webhook.test para este endpoint. La siguiente ejecución del despachador lo entrega, en torno a un minuto.

Ámbito

webhooks:write o decisions:write

Devuelve

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

Errores

404not_found

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

GET/v1/webhooks/{id}/deliveries

El registro de entregas de un endpoint, de la más reciente a la más antigua: estado (pending, delivered, failed o cancelled), intentos, código de respuesta, último error, próximo intento y el SHA-256 del cuerpo exacto enviado.

Ámbito

webhooks:write, decisions:write o requests:read

Devuelve

200{ count, deliveries[] }

Errores

404not_found

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

POST/v1/onboarding-links

Un enlace de alta de un solo uso para uno de sus proveedores, atribuido a usted. Advanta no envía ningún correo: entregue la url a su proveedor. Cuando el proveedor haya enviado la verificación de su empresa, usted recibe onboarding.completed, y el proveedor vuelve a su return_url con un estado firmado.

Ámbito

onboarding:write o decisions:write

Devuelve

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

Errores

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 respuesta trae return_secret (ors_ seguido de 64 caracteres hexadecimales), que se muestra una sola vez: guárdelo ya. Solo se guarda el SHA-256 del token del enlace. Un enlace creado con una clave de sandbox registra al proveedor como empresa de prueba en el plano de demostración.

Cuando el proveedor vuelve, la return_url lleva advanta_onboarding (el id del enlace), advanta_status (completed), advanta_ts (segundos Unix) y advanta_sig: el HMAC-SHA256 en hexadecimal de <advanta_onboarding>.<advanta_status>.<advanta_ts>, con su return_secret como clave. Verifíquelo antes de que su página se fíe del estado y rechace una vuelta a más de 600 segundos de su reloj; el último ejemplo de abajo hace ambas cosas.

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

Sus enlaces de alta, los más recientes primero, cada uno con su status: pending, account_created, completed, expired o revoked. Una clave de sandbox ve los enlaces que creó.

Ámbito

onboarding:write, decisions:write o requests:read

Devuelve

200{ count, onboarding_links[] }

Errores

Solo los comunes (401, 403, 500).

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

GET/v1/onboarding-links/{id}

Un enlace de alta y en qué punto está el proveedor. Una vez completado, seller_id es el id que usa GET /v1/seller-limits.

Ámbito

onboarding:write, decisions:write o requests:read

Devuelve

200{ onboarding_link }

Errores

404not_found

405method_not_allowed

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

POST/v1/exports

Inicia una exportación de todo lo que su financiador puede ver: solicitudes y su historial, ofertas, facturas con su verificación, vendedores (datos de la empresa, el resumen KYC que puede ver, la verificación del representante), deudores, notificaciones con las respuestas de los deudores y los datos de los certificados, las entradas de la cadena de evidencia sobre sus operaciones con los hashes y las raíces diarias para verificarlas, liquidaciones y extractos, rechazos de los controles, sus reglas y límites, su equipo, endpoints de webhook (nunca un secreto), claves de API (nunca una clave), su registro de auditoría y sus documentos. Se genera en segundo plano, normalmente en menos de un minuto; export.ready avisa cuando está.

Ámbito

exports:write o decisions:write

Devuelve

202{ funder, export }

Errores

403export_live_key_required

409export_in_progress

422body_invalid, lang_invalid

429export_rate_limited

Solo una clave de producción: una clave de sandbox responde 403 export_live_key_required (el financiador de demostración es compartido). Una exportación cada vez, como máximo 10 en 24 horas. La misma exportación está en la página Exportación del portal, en los ajustes.

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

Sus exportaciones, del portal y de la API, las más recientes primero, con su estado, su tamaño y manifest_sha256.

Ámbito

exports:write o decisions:write

Devuelve

200{ funder, count, exports[] }

Errores

403export_live_key_required

405method_not_allowed

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

GET/v1/exports/{id}

Una exportación. Mientras se genera: status queued o running, con progress. Cuando está ready, y durante 24 horas: files, cada volumen con un enlace válido como máximo una hora (nunca más allá de esas 24 horas). Vuelva a pedirla para tener enlaces nuevos; cada llamada que devuelve enlaces queda registrada. A las 24 horas los archivos se borran y el registro se conserva.

Ámbito

exports:write o decisions:write

Devuelve

200{ funder, export, files[] }

Errores

403export_live_key_required

404not_found

405method_not_allowed

manifest_sha256 es el SHA-256 del manifest.json escrito sin ese campo, con las claves ordenadas y sin espacios. Advanta registró el mismo valor en la cadena de evidencia (entrada export.ready); verify.py lo recalcula y comprueba cada archivo y las entradas de evidencia.

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

Cuando los documentos eran demasiado grandes para incluirlos (documents_mode links): cada documento de la exportación con un enlace válido durante 15 minutos, una página cada vez. La lista se calcula cuando la pide, así que un documento que ya no puede leer no aparece.

Ámbito

exports:write o decisions:write

Devuelve

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

Errores

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"