API da Advanta para financiadores

GET/v1/health

Se a API está a funcionar. Pública: sem chave, sem dados, sem acesso à base de dados.

Âmbito

Nenhuma: pública, sem chave

Devolve

200{ status, api_version, time }

Erros

Nenhum

A Advanta consulta esta rota a cada 5 minutos; os resultados estão na página de estado pública.

curl -s "$BASE/v1/health"

GET/v1/me

Quem está a chamar: a chave, o seu financiador, o seu ambiente e os seus âmbitos.

Âmbito

Qualquer chave válida

Devolve

200{ api_version, environment, funder, key }

Erros

405method_not_allowed

key.prefix são os primeiros 12 caracteres da chave. key.expires_at é null para uma chave que não expira; key.prospect indica a quem foi emitida uma chave 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

Os pedidos que lhe foram encaminhados (pode agir sobre eles) e aqueles sobre os quais já agiu (só leitura, mesmo depois de um reencaminhamento), do mais recente para o mais antigo, cada um com a sua própria oferta em my_offer, se a fez.

Âmbito

requests:read

Devolve

200{ funder, count, requests[] }

Erros

Apenas os comuns (401, 403, 500).

Um pedido traz id, request_ref, type (factoring ou confirming), status, total_amount, advance_amount, o cedente em company_name e company_nif, invoice_count, assigned_bank_id, consent_level_required (o que cada devedor tem de assinar antes de o pedido poder ser financiado, fixado quando foi encaminhado), as suas datas e, por devedor, debtor_consent. A especificação lista todos os 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}

O dossiê de análise de um pedido: o pedido, os seus créditos, o Advanta Score mais recente do cedente, a sua própria oferta e risk, os sinais de fraude e as contestações do pedido, tal como o seu portal os mostra.

Âmbito

requests:read

Devolve

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

Erros

404not_found

score vai de 300 a 850, com uma classe de A a E e as suas dimensões. É calculado na hora quando o cedente ainda não tem nenhum, e é null se isso falhar. Cada crédito tem invoice_no, invoice_amount, invoice_date, invoice_due_date e o devedor em customer_name. debtor_consent dá, por devedor, o estado da notificação, o nível exigido e o nível assinado (level_achieved), meets_requirement, o canal, o texto da declaração assinado e quem o assinou.

risk.signals lista os sinais de fraude ainda abertos ou confirmados, cada um com um code estável (por exemplo amount_above_history) e uma severity. Um sinal hard (por exemplo um montante alterado enquanto a fatura está num pedido, uma nota de crédito sobre ela ou uma contestação em aberto) trava o encaminhamento e o financiamento até a equipa de operações da Advanta o rever; os outros apenas assinalam. risk.disputes lista todas as contestações registadas contra o pedido.

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

POST/v1/requests/{id}/decision

Propor condições, recusar, financiar ou registar uma liquidação. O pedido tem de lhe estar encaminhado; caso contrário, 409 not_routed_to_you.

O corpo tem uma de quatro formas, escolhida por decision:

Âmbito

decisions:write

Devolve

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)

Erros

400reason_required

403not_your_request (só em settle: não é o financiador do pedido)

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 o que os devedores de um pedido têm de assinar. Só para cima, só num pedido de factoring que lhe está encaminhado e em curso, e só antes de algum dos seus devedores ter respondido.

Âmbito

decisions:write

Devolve

200{ request_id, consent_level_required, changed, from }

Erros

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

O dossiê documental de um pedido. Quando o pedido lhe foi encaminhado, e de novo quando foi financiado, a Advanta registou que versão de cada documento que exige o satisfez: o nome do ficheiro, o SHA-256, as datas de emissão e de validade, e quando e como a Advanta o verificou. Esse registo nunca muda, mesmo quando o cedente carrega versões mais recentes; cada entrada diz também em que ponto está hoje o documento, e current lista os documentos atuais do cedente.

Âmbito

requests:read

Devolve

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

Erros

404not_found

Cada entrada com ficheiro traz um download_url válido durante dois minutos (url_expires_in), e cada URL emitido fica registado. Compare o SHA-256 do que descarregar com o registado.

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

GET/v1/required-documents

Os documentos que exige aos cedentes, por país do cedente, e o catálogo de onde são escolhidos: o código de cada documento, o nome em sete línguas, a entidade emissora, a validade habitual e a sensibilidade. A validade habitual só serve de pré-preenchimento: conta a data impressa no documento, que o cedente regista e a Advanta verifica.

Âmbito

requests:read

Devolve

200{ funder, required, catalogue[] }

Erros

Apenas os comuns (401, 403, 500).

Um pedido só lhe é encaminhado, a sua oferta só é registada e o pedido só é financiado enquanto todos os documentos da sua lista para o país do cedente estiverem verificados pela Advanta e válidos nessa data; caso contrário, 409 documents_missing_for_funder.

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

PUT/v1/required-documents

Substituir a sua lista para um país de cedentes; uma lista vazia apaga-a. Os códigos vêm do catálogo, e a alteração fica guardada na cadeia de evidências da Advanta com note. Os pedidos que já tem continuam consigo; a sua próxima oferta ou financiamento num deles espera até o cedente cumprir a nova lista (open_requests_not_meeting conta-os).

Âmbito

settings:write ou decisions:write

Devolve

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

Erros

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

O que os seus devedores têm de assinar antes de financiar: o nível que cada devedor tem de assinar antes de um pedido de factoring encaminhado para si poder ser financiado (receipt, depois acknowledgment, depois acceptance), se só contam textos de declaração aprovados por um advogado, os seus pedidos em aberto por nível, e que níveis tem cada lei aplicável em texto de declaração, e em que línguas.

Âmbito

requests:read

Devolve

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

Erros

Apenas os comuns (401, 403, 500).

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

PUT/v1/settings

Alterar o que os seus devedores têm de assinar. A alteração aplica-se aos pedidos encaminhados para si a partir desse momento; um pedido já encaminhado mantém o nível com que foi encaminhado. reason fica guardado na cadeia de evidências da Advanta.

Âmbito

settings:write ou decisions:write

Devolve

200{ …settings, changed, open_requests_keep_their_level }

Erros

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

Os termos do seu programa: os seus termos por omissão, os termos que definiu para empresas concretas, as empresas para as quais pode definir termos (as que têm um pedido encaminhado para si e os seus próprios clientes) e os seus pedidos de factoring contados pelos termos que têm. Um pedido recebe os termos em vigor quando é encaminhado para si e mantém-nos.

Âmbito

requests:read

Devolve

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

Erros

Apenas os comuns (401, 403, 500).

disclosure: announced (por omissão): cada devedor é notificado e confirma a cessão antes de financiar. confidential: quando o pedido é encaminhado para si, a notificação a cada devedor é preparada, com a sua impressão digital (SHA-256), e guardada pronta a enviar, e o financiamento não espera pelo devedor. Antes de financiar, todas as verificações bloqueantes das faturas têm de passar, as faturas têm de vir da contabilidade do próprio cedente (ERP, fatura eletrónica ou SAF-T), cada devedor tem de ter uma notificação preparada e atual que o nomeia a si e um endereço para onde enviá-la, e a verificação do cedente tem de estar aprovada. As notificações são enviadas quando anuncia o pedido e, automaticamente, num pedido financiado, quando se cumpre um gatilho que ativou: announce_overdue_days, announce_on_dispute, announce_on_kyc_lapse.

recourse: with (com recurso) ou without (sem recurso). recourse_days: dias depois do vencimento de uma fatura até um pedido financiado ainda não liquidado abrir um acionamento (null: nenhum). bank_data: off, requested (pede-se ao cedente que ligue a sua conta bancária empresarial para si, só de leitura e com o seu consentimento) ou required (o financiamento espera também que a conta para onde paga seja confirmada como sendo do próprio 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

Alterar os seus termos por omissão (sem seller_id) ou os de uma empresa. Só mudam as chaves que enviar; {"reset": true} com um seller_id devolve essa empresa aos seus termos por omissão. A alteração aplica-se aos pedidos encaminhados para si a partir desse momento; os pedidos já encaminhados mantêm os seus termos. reason fica guardado na cadeia de evidências da Advanta.

Âmbito

settings:write ou decisions:write

Devolve

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

Erros

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 um pedido confidencial encaminhado para si: passa a anunciado e as notificações preparadas para ele são enviadas aos devedores, que depois as confirmam como num programa anunciado. Possível enquanto o pedido está pendente, em análise, com condições enviadas, aprovado ou financiado. Segue-se um evento request.announced; depois de uma notificação enviada, o pedido fica anunciado.

Âmbito

decisions:write

Devolve

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

Erros

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

As notificações de cessão do pedido, uma por devedor, cada uma com o seu documento preparado quando existe: o assunto e o HTML exatos que o devedor recebe, a língua, a lei aplicável e o SHA-256. Para um pedido encaminhado para si, ou um em que já atuou.

Âmbito

requests:read

Devolve

200{ request_id, count, notices[] }

Erros

404not_found

O HTML tem um marcador, ACK_LINK entre chavetas duplas, onde vai a ligação de confirmação do devedor; a ligação contém um segredo e nunca é mostrada. current diz se o documento ainda corresponde às faturas e ao montante da notificação.

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

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

O que o cedente partilha consigo da sua conta bancária empresarial, só de leitura e com o seu consentimento, através de um prestador licenciado de informação sobre contas: a ligação, as contas (os últimos quatro caracteres de cada IBAN) e os saldos, doze meses de movimentos por mês e a verificação da sua conta de pagamento. cash_flow é null enquanto o cedente não tiver ligado uma conta para si.

Âmbito

requests:read

Devolve

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

Erros

404not_found

bank_data_problems diz o que o financiamento ainda espera quando os seus termos exigem dados bancários. payment_alerts são os pagamentos que o cedente recebeu de um devedor deste pedido depois de o financiar em termos confidenciais. O consentimento de um cedente é dado a um financiador: só vê o que ele partilha consigo.

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

GET/v1/recourse

Os seus pedidos de factoring financiados por tipo de recurso (with, without, e not_recorded para os encaminhados antes de 28 de setembro de 2026), os acionamentos contados por tipo e estado, e os próprios acionamentos, primeiro os abertos. Abre-se um acionamento por pedido quando um pedido financiado não está liquidado recourse_days depois do vencimento de uma fatura: recourse, contra o cedente, pelo montante adiantado mais as suas comissões, menos o que já cobrou; debtor_default, sem recurso, para a sua própria cobrança e seguro.

Âmbito

requests:read

Devolve

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

Erros

422status_invalid

O cedente reembolsa um acionamento de recurso para pay_to_iban indicando pay_reference. Quando os pagamentos que registar a partir daí (uma linha de extrato que confirma, ou a decisão settle) cobrem claim_amount, o acionamento fica liquidado e o pedido fecha como liquidado por recurso: as faturas voltam ao cedente, ainda por pagar pelo devedor.

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

POST/v1/recourse/{id}/close

Fechar um acionamento seu em aberto: um acionamento de recurso fica withdrawn (prescindiu dele, ou acordou outra coisa com o cedente), um incumprimento do devedor fica written_off (passou para a sua cobrança ou para a sua seguradora). reason fica guardado na cadeia de evidências da Advanta.

Âmbito

decisions:write

Devolve

200{ claim_id, status }

Erros

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

A sua própria conta de cobrança, ligada pelo seu administrador no portal e lida da mesma forma: os movimentos passam pela mesma conciliação que POST /v1/statements, para que as cobranças correspondam aos seus pedidos financiados sem enviar ficheiros. Também quantos cedentes partilham a conta consigo, os alertas de pagamento nos seus pedidos (os últimos 180 dias) e os custos do prestador registados em seu nome, por mês.

Âmbito

requests:read

Devolve

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

Erros

Apenas os comuns (401, 403, 500).

unit_price_eur e amount_eur são null até o preço do prestador estar fixado.

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

GET/v1/credit-limits

O seu livro por devedor: o seu limite e o que está em dívida, comprometido, oferecido e ainda disponível, em euros.

Âmbito

limits:read ou requests:read

Devolve

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

Erros

Apenas os comuns (401, 403, 500).

Cada devedor traz debtor_key, debtor_name, debtor_country, limit_status, limit_amount, outstanding, committed, offered, available, overdue_count, oldest_overdue, frozen, decided_at e note.

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

PUT/v1/credit-limits

Definir ou rever o seu limite para um devedor, ou recusar o devedor. A base de dados recusa qualquer oferta posterior que este limite não comporte.

Âmbito

limits:write ou decisions:write

Devolve

200{ credit_limit }

Erros

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

Carregar até 2000 limites sobre devedores numa só chamada: o seu próprio livro, ou os limites da sua seguradora de crédito. Cada linha é verificada exatamente como PUT /v1/credit-limits verifica um limite e tem a sua própria resposta: uma linha que falha não trava as outras, e um devedor que aparece duas vezes na mesma chamada é recusado da segunda vez.

Âmbito

limits:write ou decisions:write

Devolve

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

Erros

413too_many_rows

422rows_required, invalid_source, source_ref_invalid, source_ref_too_long

Cada limite escrito regista a sua origem e referência, no limite e no seu histórico. A resposta conta received, written e refused, e responde a cada linha com row (a contar de 1), debtor_tax_id e ok: uma linha escrita acrescenta debtor_key, status e amount; uma linha recusada dá o seu error (invalid_amount, debtor_tax_id_required, duplicate_debtor, invalid_status, amount_required, invalid_country, row_invalid ou invalid_limit) e pode acrescentar um 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

O seu livro por cedente, com os mesmos números do livro de devedores.

Âmbito

limits:read ou requests:read

Devolve

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

Erros

Apenas os comuns (401, 403, 500).

Cada cedente traz seller_id, seller_name, seller_nif, seller_country e os mesmos campos de limite e exposição de um devedor.

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

PUT/v1/seller-limits

Definir ou rever o seu limite para um cedente, ou recusar o cedente.

Âmbito

limits:write ou decisions:write

Devolve

200{ seller_limit }

Erros

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

Como um comprador paga aos seus fornecedores, só em agregado, a partir da contabilidade dos fornecedores ligados à Advanta. O histórico é publicado quando pelo menos três fornecedores observam o comprador; caso contrário, status diz porquê e todos os números são null. Só o pode ler para um comprador num pedido no seu âmbito ou na sua lista de devedores; uma chave de sandbox lê o histórico do plano de demonstração.

Âmbito

limits:read ou requests:read

Devolve

200{ funder, payer_record }

Erros

404not_found (o comprador não está em nenhum pedido no seu âmbito nem na sua lista de devedores)

422tax_id_required

Os números incluem observers, invoice_count, avg_days_to_pay, median_days_to_pay, on_time_pct, o atraso no pagamento (avg_settle_delay_days, median_settle_delay_days, p75_settle_delay_days, worst_settle_delay_days), contagens em aberto e vencidas, window_from e refreshed_at. payer_record é null quando não há histórico.

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

GET/v1/requests/{id}/debtors

O que a Advanta sabe de cada devedor de um pedido de factoring encaminhado para si, ou de um em que já atuou: o seu level na Advanta desde level_since (notice: conhece a Advanta só pela notificação; account: ativou a sua conta de pagador; books: ligou o seu sistema de contabilidade; buyer: tem um programa de comprador, e buyer_programme é true), o histórico do próprio cedente com ele, o seu prazo médio de pagamento oficial quando é uma entidade pública, e o seu limite sobre ele.

Âmbito

requests:read

Devolve

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

Erros

404not_found

score é a pontuação do próprio devedor (classe, de 0 a 100, quando e com que versão do modelo). Só é dada quando o devedor partilha os seus dados com os financiadores que financiam faturas devidas por ele, está no nível books ou buyer, e o pedido está encaminhado para si (não um em que só atuou); caso contrário é null. pair_history é o histórico do cedente com este devedor ao longo de 36 meses, com as regras do histórico de pagador: só faturas reais, e atraso só face a datas de vencimento indicadas no documento ou no ERP. public_payment_period é o prazo médio de pagamento oficial mais recente de uma entidade pública (DGAL para os municípios portugueses, Hacienda para as entidades locais espanholas). credit_limit é o seu limite sobre o devedor, de onde veio (source, source_ref) e o que está usado (exposure: em dívida mais comprometido mais oferecido, em euros).

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

POST/v1/statements

Enviar o extrato da sua conta de cobrança para conciliação: um ficheiro CAMT.053 (XML) ou CSV, no máximo 4 MiB e 5000 movimentos. Cada crédito é conciliado com os seus próprios pedidos financiados, primeiro pela referência que o devedor indicou. Nada é liquidado até confirmar uma correspondência no portal. O mesmo ficheiro enviado duas vezes é recusado, pelo seu SHA-256.

Âmbito

statements:write ou decisions:write

Devolve

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

Erros

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

A sua própria ligação aberta (prescriber_id null) e a ligação atual de cada prescritor, com o seu state (active, disabled ou expired) e o seu url enquanto funciona.

Âmbito

requests:read, clients:write ou decisions:write

Devolve

200{ funder, count, client_links[] }

Erros

422lang_invalid

Uma empresa que abre uma ligação indica o nome, o número fiscal, o país e o email, e recebe o seu convite por email. Quando o aceita, passa a ser sua cliente: os pedidos dela são encaminhados só para si, e a sua origem (a ligação, o prescritor, a data) fica registada. Abrir uma ligação nunca cria uma conta por si só.

Cada ligação traz também arrivals (as empresas cuja primeira chegada até si foi por ela) e claims_last_day (as adesões por ela nas últimas 24 horas; uma ligação aceita no máximo 20 por hora e 100 por dia).

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

POST/v1/client-links

Emitir a sua própria ligação aberta, ou a de um prescritor com prescriber_id. Há uma ligação ativa por titular: enquanto uma ainda funciona, envie replace: true para a substituir (a anterior deixa de funcionar de imediato); caso contrário, 409 link_exists. Só fica guardado o SHA-256 do token da ligação, e a emissão fica registada na cadeia de evidências da Advanta.

Âmbito

clients:write ou decisions:write

Devolve

201{ client_link }

Erros

404not_found

409link_exists

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

Uma ligação emitida com uma chave de sandbox só gera convites de teste, e a chave precisa de decisions:write: as ligações do financiador de demonstração são partilhadas por todas as demonstrações.

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

Desativar uma ligação. Deixa de funcionar de imediato; as empresas que já chegaram por ela mantêm a sua origem. Desativar uma ligação já desativada não muda nada (changed é false). Para dar uma nova, chame POST /v1/client-links.

Âmbito

clients:write ou decisions:write

Devolve

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

Erros

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

Os seus prescritores, as pessoas e empresas que lhe trazem clientes (contabilistas, consultores, intermediários), os ativos primeiro, cada um com a sua ligação atual e o número de empresas que chegaram por ela. São seus, não parceiros da Advanta. A mesma lista da página Clientes do seu portal.

Âmbito

requests:read, clients:write ou decisions:write

Devolve

200{ funder, count, prescribers[] }

Erros

422lang_invalid

Uma chave de sandbox lê os prescritores do financiador de demonstração, que todas as demonstrações partilham.

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

POST/v1/prescribers

Adicionar um prescritor. A sua própria ligação aberta é emitida com ele, em prescriber.link.url. O nome e o email dele ficam fora da cadeia de evidências da Advanta: só os seus hashes lá entram.

Âmbito

clients:write ou decisions:write

Devolve

201{ prescriber }

Erros

409prescriber_exists

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

Com uma chave de sandbox isto altera o estado de demonstração partilhado, por isso a chave precisa 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

Desativar um prescritor. A ligação dele deixa de funcionar de imediato; as empresas que trouxe continuam atribuídas a ele. Desativar um prescritor já desativado não muda nada (changed é false). Fica registado na cadeia de evidências da Advanta.

Âmbito

clients:write ou decisions:write

Devolve

200{ prescriber, changed }

Erros

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

O que cada prescritor lhe trouxe: um grupo por prescritor, depois a sua própria ligação (own_link), os seus convites pelo nome (named) e as suas ligações de adesão (api). Por grupo e por empresa: quando chegou, quando a conta foi aberta (joined), quando a verificação da empresa foi aprovada (onboarded), os pedidos encaminhados para si, o montante pedido e o montante financiado. Os mesmos números do seu portal.

Âmbito

requests:read, clients:write ou decisions:write

Devolve

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

Erros

405method_not_allowed

Uma empresa conta uma vez, para quem a trouxe primeiro até si. O montante financiado é o adiantamento (ou, na falta dele, o total) dos pedidos financiados ou liquidados, em euros; totals soma todos os grupos. Só os seus dados e só empresas do seu plano de dados: uma chave de sandbox não vê o que outras chaves de sandbox fizeram pela 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

Todos os seus convites, os mais recentes primeiro: por uma ligação, pelo nome no portal ou com uma ligação de adesão. Cada um diz como a empresa chegou (via: link, named ou api), o prescritor que a trouxe, se houver, o seu state (pending, accepted, revoked ou expired), a empresa, o contacto e as datas.

Âmbito

requests:read, clients:write ou decisions:write

Devolve

200{ funder, count, invitations[] }

Erros

405method_not_allowed

Só o seu próprio plano de dados. Uma chave de sandbox não vê os convites feitos por outras chaves de sandbox.

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

GET/v1/opportunities

O resumo de um dia, dos seus próprios clientes (as empresas de que é o financiador de origem) que lhe permitem ver as faturas deles. Todas as manhãs, por volta das 06:30, hora de Madrid, depois da pré-qualificação noturna, a Advanta lista as faturas que passaram a cumprir as suas regras desde o resumo anterior (kind new) e o que mudou nas que já lhe foram mostradas: paid, disputed (o cliente registou que o devedor a contesta) ou no_longer_eligible.

Âmbito

requests:read

Devolve

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

Erros

404not_found

405method_not_allowed

422invalid_date

Uma linha traz a fatura, o devedor com o seu NIF, o valor ainda em dívida, a data de vencimento, e o cliente com o seu setor (secção NACE), classe e dimensão; primeiro as linhas novas, depois as alterações. no_longer_eligible tem um reason: requested (o cliente pediu para a financiar), cancelled, removed (já não está nos livros do cliente), left_programme, not_shared (o cliente deixou de partilhar) ou rules (já não cumpre as suas regras).

digest tem os totais: quantos clientes partilham e quantos ainda não, o que é elegível hoje, o que é novo e o que mudou. stale é true quando a leitura noturna não terminou: nessa manhã nada foi comparado. Um resumo é uma lista calculada pela base de dados, não uma oferta: um pedido é verificado de novo quando é feito, e decide sobre ele como sempre. O webhook opportunities.daily diz quando há um resumo com 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

Os seus endpoints ativos, sem os segredos, e os tipos de evento que pode subscrever. Uma chave de sandbox vê apenas os endpoints que criou.

Âmbito

webhooks:write, decisions:write ou requests:read

Devolve

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

Erros

Apenas os comuns (401, 403, 500).

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

POST/v1/webhooks

Registar um endpoint. A resposta traz o seu segredo de assinatura, que não volta a ser mostrado.

Âmbito

webhooks:write ou decisions:write

Devolve

201{ webhook, secret, signature }

Erros

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

No máximo 10 endpoints ativos.

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}

Parar um endpoint. As entregas ainda pendentes são canceladas e os seus segredos são apagados.

Âmbito

webhooks:write ou decisions:write

Devolve

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

Erros

404not_found

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

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

Um novo segredo de assinatura, mostrado uma só vez. O segredo anterior continua a assinar, como segundo v1 no cabeçalho, durante keep_previous_hours, para poder mudar sem perder eventos.

Âmbito

webhooks:write ou decisions:write

Devolve

200{ webhook, secret, previous_secret_valid_until }

Erros

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

Pôr em fila um evento webhook.test para este endpoint. A execução seguinte do despachante entrega-o, em cerca de um minuto.

Âmbito

webhooks:write ou decisions:write

Devolve

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

Erros

404not_found

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

GET/v1/webhooks/{id}/deliveries

O registo de entregas de um endpoint, do mais recente para o mais antigo: estado (pending, delivered, failed ou cancelled), tentativas, código de resposta, último erro, próxima tentativa e o SHA-256 do corpo exato enviado.

Âmbito

webhooks:write, decisions:write ou requests:read

Devolve

200{ count, deliveries[] }

Erros

404not_found

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

POST/v1/onboarding-links

Uma ligação de adesão de uso único para um dos seus fornecedores, atribuída a si. A Advanta não envia email: entregue o url ao seu fornecedor. Quando o fornecedor tiver submetido a verificação da empresa, recebe onboarding.completed, e o fornecedor é reencaminhado para o seu return_url com um estado assinado.

Âmbito

onboarding:write ou decisions:write

Devolve

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

Erros

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

A resposta traz return_secret (ors_ seguido de 64 caracteres hexadecimais), mostrado uma só vez: guarde-o já. Só fica guardado o SHA-256 do token da ligação. Uma ligação criada com uma chave de sandbox regista o fornecedor como empresa de teste no plano de demonstração.

Quando o fornecedor regressa, o return_url traz advanta_onboarding (o id da ligação), advanta_status (completed), advanta_ts (segundos Unix) e advanta_sig: o HMAC-SHA256 em hexadecimal de <advanta_onboarding>.<advanta_status>.<advanta_ts>, com o seu return_secret como chave. Verifique-o antes de a sua página confiar no estado e recuse um regresso a mais de 600 segundos do seu relógio; o último exemplo abaixo faz as duas coisas.

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

As suas ligações de adesão, as mais recentes primeiro, cada uma com o seu status: pending, account_created, completed, expired ou revoked. Uma chave de sandbox vê as ligações que criou.

Âmbito

onboarding:write, decisions:write ou requests:read

Devolve

200{ count, onboarding_links[] }

Erros

Apenas os comuns (401, 403, 500).

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

GET/v1/onboarding-links/{id}

Uma ligação de adesão e em que ponto está o fornecedor. Depois de concluída, seller_id é o id que GET /v1/seller-limits usa.

Âmbito

onboarding:write, decisions:write ou requests:read

Devolve

200{ onboarding_link }

Erros

404not_found

405method_not_allowed

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

POST/v1/exports

Inicia uma exportação de tudo o que o seu financiador pode ver: pedidos e o seu histórico, ofertas, faturas com a sua verificação, vendedores (dados da empresa, o resumo KYC que pode ver, a verificação do representante), devedores, notificações com as respostas dos devedores e os dados dos certificados, as entradas da cadeia de evidência sobre as suas operações com os hashes e as raízes diárias para as verificar, liquidações e extratos, recusas dos controlos, as suas regras e limites, a sua equipa, endpoints de webhook (nunca um segredo), chaves de API (nunca uma chave), o seu registo de auditoria e os seus documentos. É gerada em segundo plano, normalmente em menos de um minuto; export.ready avisa quando.

Âmbito

exports:write ou decisions:write

Devolve

202{ funder, export }

Erros

403export_live_key_required

409export_in_progress

422body_invalid, lang_invalid

429export_rate_limited

Só uma chave de produção: uma chave de sandbox responde 403 export_live_key_required (o financiador de demonstração é partilhado). Uma exportação de cada vez, no máximo 10 em 24 horas. A mesma exportação está na página Exportação do portal, nas definições.

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

As suas exportações, do portal e da API, as mais recentes primeiro, com o estado, o tamanho e manifest_sha256.

Âmbito

exports:write ou decisions:write

Devolve

200{ funder, count, exports[] }

Erros

403export_live_key_required

405method_not_allowed

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

GET/v1/exports/{id}

Uma exportação. Enquanto é gerada: status queued ou running, com progress. Quando ready, e durante 24 horas: files, cada volume com uma ligação válida no máximo durante uma hora (nunca para lá dessas 24 horas). Peça de novo para ter ligações novas; cada chamada que devolve ligações fica registada. Ao fim de 24 horas os ficheiros são apagados e o registo fica.

Âmbito

exports:write ou decisions:write

Devolve

200{ funder, export, files[] }

Erros

403export_live_key_required

404not_found

405method_not_allowed

manifest_sha256 é o SHA-256 do manifest.json escrito sem esse campo, com as chaves ordenadas e sem espaços. A Advanta registou o mesmo valor na cadeia de evidência (entrada export.ready); o verify.py recalcula-o e verifica cada ficheiro e as entradas de evidência.

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

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

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

GET/v1/exports/{id}/documents

Quando os documentos eram grandes demais para incluir (documents_mode links): cada documento da exportação com uma ligação válida durante 15 minutos, uma página de cada vez. A lista é calculada quando pede, por isso um documento que já não pode ler não aparece.

Âmbito

exports:write ou decisions:write

Devolve

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

Erros

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"