Riferimento API

Rischio fornitori

Che cosa merita uno sguardo per ogni fornitore: dati bancari, verifica delle sanzioni e documenti mancanti.

Altro su questa risorsa

Pleaxy tiene tre controlli su ogni fornitore di un acquirente e li riassume in un livello: ok, attention o blocked. Dati bancari: il conto su cui ogni fattura chiede di essere pagata viene registrato per canale di fatturazione, e una fattura che indica un conto nuovo o diverso attende l’approvazione di una persona prima di poter essere esportata per il pagamento. Verifica delle sanzioni: quando è attiva, i nomi del fornitore vengono confrontati con le liste OFAC, UE, Regno Unito e ONU, e i pagamenti attendono mentre una possibile corrispondenza viene esaminata. Questionari: risposte segnalate e documenti mancanti. Questi endpoint leggono soltanto. Approvare un conto bancario e decidere su una corrispondenza della verifica spetta a una persona che ha effettuato l’accesso a Pleaxy.

Elencare il rischio fornitori

Elenca il livello di rischio di ogni fornitore e i controlli su cui si basa.

GET/v1/workspaces/{regionId}/supplier-risk

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Restituisce il livello di ogni fornitore con le sue righe: bank, screening, flaggedAnswers e missingDocuments, ciascuna con uno stato ok, attention, blocked o none. In questo elenco una verifica senza segnalazioni compare come none; leggi un fornitore con GetSupplierRisk per il suo stato bancario e di verifica completo.

Richiede l’accesso 'view' ai fornitori.

Campi della risposta

  • level"ok" | "attention" | "blocked"

    Lo stato più grave tra le righe che il workspace considera per il livello. blocked significa una corrispondenza di sanzioni confermata. È un livello, mai un punteggio.

  • bankobject

    I conti bancari registrati del fornitore: waiting conta i conti in attesa di approvazione.

  • screeningobject

    La verifica delle sanzioni del fornitore: il suo stato e quando è stata eseguita l’ultima volta. status è off finché la verifica non è attiva.

  • flaggedAnswersobject

    Quante risposte del questionario del fornitore sono segnalate per l’esame.

  • missingDocumentsobject

    Le etichette dei documenti obbligatori del questionario che il fornitore non ha fornito.

Errori

  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
GET /v1/workspaces/{regionId}/supplier-risk
Richiesta
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/supplier-risk" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 200 OK
[
   {
      "connectionId": "string",
      "supplierName": "string",
      "level": "ok" | "attention" | "blocked",
      "bank": { "state": "ok" | "attention" | "blocked" | "none", "waiting": number, "status": "none" | "approved" | "waiting" | "changing" },
      "screening": { "state": "ok" | "attention" | "blocked" | "none", "status": "off" | "not_screened" | "clear" | "possible_match" | "confirmed_match", "checkedAt": "string" },
      "flaggedAnswers": { "state": "ok" | "attention" | "blocked" | "none", "count": number },
      "missingDocuments": { "state": "ok" | "attention" | "blocked" | "none", "fields": [ "string" ] }
   }
]

Ottenere il rischio di un fornitore

Ottiene il livello di rischio di un fornitore e i controlli su cui si basa.

GET/v1/workspaces/{regionId}/supplier-risk/{connectionId}

Parametri

  • connectionIdstringObbligatorio

    L’id di connessione del fornitore in questo workspace.

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Restituisce il rischio di un fornitore come fa ListSupplierRisk, con bank.status e con lo stato e checkedAt della verifica compilati.

Richiede l’accesso 'view' ai fornitori.

Campi della risposta

  • level"ok" | "attention" | "blocked"

    Lo stato più grave tra le righe che il workspace considera per il livello. blocked significa una corrispondenza di sanzioni confermata. È un livello, mai un punteggio.

  • bankobject

    I conti bancari registrati del fornitore: waiting conta i conti in attesa di approvazione.

  • screeningobject

    La verifica delle sanzioni del fornitore: il suo stato e quando è stata eseguita l’ultima volta. status è off finché la verifica non è attiva.

  • flaggedAnswersobject

    Quante risposte del questionario del fornitore sono segnalate per l’esame.

  • missingDocumentsobject

    Le etichette dei documenti obbligatori del questionario che il fornitore non ha fornito.

Errori

  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
GET /v1/workspaces/{regionId}/supplier-risk/{connectionId}
Richiesta
GET /v1/workspaces/reg_01k5x8p9j3q7vn2mhb4tzc6rde.buyer/supplier-risk/SC-1A2B3C4D
Risposta · 200 OK
{
   "connectionId": "SC-1A2B3C4D",
   "supplierName": "Northwind Hosting",
   "level": "attention",
   "bank": { "state": "attention", "waiting": 1, "status": "changing" },
   "screening": { "state": "ok", "status": "clear", "checkedAt": "2026-11-10T06:00:00.000Z" },
   "flaggedAnswers": { "state": "ok", "count": 0 },
   "missingDocuments": { "state": "ok", "fields": [] }
}

Elencare i conti bancari da approvare

Elenca i conti bancari dei fornitori in attesa dell’approvazione di una persona.

GET/v1/workspaces/{regionId}/bank-accounts/review

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Restituisce i conti bancari in attesa di approvazione: il primo conto di un canale di fatturazione (stato unverified), oppure una modifica a un conto già approvato (stato changing, con pendingChange). Le fatture da pagare su quei conti attendono finché una persona non li approva.

Richiede l’accesso 'view' alle fatture. Approvare un conto, rifiutare una modifica e mostrare i numeri completi spetta a una persona che ha effettuato l’accesso a Pleaxy.

Campi della risposta

  • laneKeystring

    Il canale di fatturazione a cui appartiene il conto: un beneficiario e una valuta di questo fornitore.

  • detailsobject

    I dati di pagamento registrati, con i numeri di conto mascherati tranne gli ultimi quattro caratteri.

  • status"unverified" | "verified" | "changing"

    unverified: il primo conto del canale, in attesa di approvazione. verified: approvato. changing: una fattura ha indicato altri dati, conservati in pendingChange finché una persona non li approva o li rifiuta.

  • approvalobject

    Come è stato approvato il conto. verification è supplier_confirmed, buyer_approved o paid_before, e check.method indica come l’acquirente lo ha verificato.

  • historyArray<object>

    Gli eventi più recenti del conto, con il numero di conto mascherato.

Errori

  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
GET /v1/workspaces/{regionId}/bank-accounts/review
Richiesta
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/bank-accounts/review" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 200 OK
[
   {
      "id": "string",
      "connectionId": "string",
      "supplierName": "string",
      "supplierKey": "string",
      "laneKey": "string",
      "payeeName": "string",
      "currency": "string",
      "details": { "method": "bank_transfer" | "wire" | "ach" | "check" | "other", "payeeName": "string", "bankName": "string", "iban": "string", "accountNumber": "string", "bic": "string", "routingNumber": "string", "mailingAddress": "string", "paymentReference": "string", "notes": "string" },
      "status": "unverified" | "verified" | "changing",
      "learnedFrom": { "invoiceId": "string", "side": "buyer" | "supplier" },
      "approval": {
         "verification": "supplier_confirmed" | "buyer_approved" | "paid_before",
         "at": "string",
         "by": { "sub": "string", "name": "string", "side": "buyer" | "supplier" },
         "check": { "method": "call" | "email" | "bank_letter" | "supplier_portal" | "other" | "none", "detail": "string", "note": "string" },
         "invoiceId": "string"
      },
      "pendingChange": { "details": { ... }, "invoiceId": "string", "side": "buyer" | "supplier", "at": "string" },
      "history": [
         { "at": "string", "event": "learned" | "seeded" | "approved" | "change_proposed" | "change_rejected", "masked": "string", "invoiceId": "string", "by": "string" }
      ],
      "version": number,
      "createdAt": "string",
      "updatedAt": "string"
   }
]

Elencare i conti bancari di un fornitore

Elenca i conti bancari registrati di un fornitore, con il modo in cui ciascuno è stato approvato.

GET/v1/workspaces/{regionId}/bank-accounts/suppliers/{connectionId}

Parametri

  • connectionIdstringObbligatorio

    L’id di connessione del fornitore in questo workspace.

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Restituisce i conti bancari registrati di un fornitore, uno per canale di fatturazione (un beneficiario e una valuta), con lo stato di ogni conto, come è stato approvato e i suoi ultimi 10 eventi.

Richiede l’accesso 'view' alle fatture. Approvare un conto, rifiutare una modifica e mostrare i numeri completi spetta a una persona che ha effettuato l’accesso a Pleaxy.

Campi della risposta

  • laneKeystring

    Il canale di fatturazione a cui appartiene il conto: un beneficiario e una valuta di questo fornitore.

  • detailsobject

    I dati di pagamento registrati, con i numeri di conto mascherati tranne gli ultimi quattro caratteri.

  • status"unverified" | "verified" | "changing"

    unverified: il primo conto del canale, in attesa di approvazione. verified: approvato. changing: una fattura ha indicato altri dati, conservati in pendingChange finché una persona non li approva o li rifiuta.

  • approvalobject

    Come è stato approvato il conto. verification è supplier_confirmed, buyer_approved o paid_before, e check.method indica come l’acquirente lo ha verificato.

  • historyArray<object>

    Gli eventi più recenti del conto, con il numero di conto mascherato.

Errori

  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
GET /v1/workspaces/{regionId}/bank-accounts/suppliers/{connectionId}
Richiesta
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/bank-accounts/suppliers/{connectionId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 200 OK
[
   {
      "id": "string",
      "connectionId": "string",
      "supplierName": "string",
      "supplierKey": "string",
      "laneKey": "string",
      "payeeName": "string",
      "currency": "string",
      "details": { "method": "bank_transfer" | "wire" | "ach" | "check" | "other", "payeeName": "string", "bankName": "string", "iban": "string", "accountNumber": "string", "bic": "string", "routingNumber": "string", "mailingAddress": "string", "paymentReference": "string", "notes": "string" },
      "status": "unverified" | "verified" | "changing",
      "learnedFrom": { "invoiceId": "string", "side": "buyer" | "supplier" },
      "approval": {
         "verification": "supplier_confirmed" | "buyer_approved" | "paid_before",
         "at": "string",
         "by": { "sub": "string", "name": "string", "side": "buyer" | "supplier" },
         "check": { "method": "call" | "email" | "bank_letter" | "supplier_portal" | "other" | "none", "detail": "string", "note": "string" },
         "invoiceId": "string"
      },
      "pendingChange": { "details": { ... }, "invoiceId": "string", "side": "buyer" | "supplier", "at": "string" },
      "history": [
         { "at": "string", "event": "learned" | "seeded" | "approved" | "change_proposed" | "change_rejected", "masked": "string", "invoiceId": "string", "by": "string" }
      ],
      "version": number,
      "createdAt": "string",
      "updatedAt": "string"
   }
]

Ottenere il conto bancario di una fattura

Dice se il pagamento di una fattura attende per via del conto bancario del suo fornitore.

GET/v1/workspaces/{regionId}/invoices/{invoiceId}/bank-account

Parametri

  • invoiceIdstringObbligatorio

    L’id della fattura, ad es. INV-7F3A9C21.

  • buyerstring

    Per un chiamante fornitore, l’acquirente a cui appartiene la fattura, come in GetInvoice.

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Dice se questa fattura attende per via del conto bancario del suo fornitore. hold è first_payment quando il conto del canale di fatturazione non è ancora approvato, differs_from_file quando la fattura indica dati diversi da quelli del conto approvato, ed è assente quando la fattura può essere pagata. Finché attende, la fattura non può essere esportata per il pagamento; registrare un pagamento fatto altrove e pagare tramite Pleaxy non vengono trattenuti.

Richiede l’accesso 'view' alle fatture. Un chiamante fornitore riceve solo hold.

Campi della risposta

  • hold"first_payment" | "differs_from_file"

    Perché il pagamento attende. Assente quando non attende.

  • accountobject

    Il conto registrato del canale di fatturazione, con i numeri mascherati tranne gli ultimi quattro caratteri.

Errori

  • 404 Not Found - Nessuna fattura con questo id che il chiamante possa vedere.
  • 409 Conflict - Solo per i chiamanti Fornitore. Codice INVOICE_ID_AMBIGUOUS: più di uno dei tuoi acquirenti ha una tua fattura con questo id (gli id sono univoci solo all’interno di un acquirente), quindi Pleaxy non tira a indovinare quale intendi. Nulla viene letto o modificato. Il campo buyers del corpo elenca l’ID del workspace e il nome di ogni acquirente: ripeti la chiamata con ?buyer=<quell’ID del workspace>.
  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
GET /v1/workspaces/{regionId}/invoices/{invoiceId}/bank-account
Richiesta
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/invoices/{invoiceId}/bank-account" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 200 OK
{
   "hold": "first_payment" | "differs_from_file",
   "account": {
      "id": "string",
      "connectionId": "string",
      "supplierName": "string",
      "supplierKey": "string",
      "laneKey": "string",
      "payeeName": "string",
      "currency": "string",
      "details": { "method": "bank_transfer" | "wire" | "ach" | "check" | "other", "payeeName": "string", "bankName": "string", "iban": "string", "accountNumber": "string", "bic": "string", "routingNumber": "string", "mailingAddress": "string", "paymentReference": "string", "notes": "string" },
      "status": "unverified" | "verified" | "changing",
      "learnedFrom": { "invoiceId": "string", "side": "buyer" | "supplier" },
      "approval": {
         "verification": "supplier_confirmed" | "buyer_approved" | "paid_before",
         "at": "string",
         "by": { "sub": "string", "name": "string", "side": "buyer" | "supplier" },
         "check": { "method": "call" | "email" | "bank_letter" | "supplier_portal" | "other" | "none", "detail": "string", "note": "string" },
         "invoiceId": "string"
      },
      "pendingChange": { "details": { ... }, "invoiceId": "string", "side": "buyer" | "supplier", "at": "string" },
      "history": [
         { "at": "string", "event": "learned" | "seeded" | "approved" | "change_proposed" | "change_rejected", "masked": "string", "invoiceId": "string", "by": "string" }
      ],
      "version": number,
      "createdAt": "string",
      "updatedAt": "string"
   },
   "supplierKey": "string"
}

Elencare le corrispondenze della verifica

Elenca i fornitori la cui verifica delle sanzioni ha una corrispondenza da esaminare o una confermata.

GET/v1/workspaces/{regionId}/screening/review

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Restituisce i fornitori il cui stato di verifica è possible_match o confirmed_match. I pagamenti a loro favore attendono, e un fornitore con una corrispondenza confermata non riceve nuovi ordini né fatture inserite dall’acquirente. L’elenco è vuoto finché la verifica è disattivata. Una corrispondenza è una somiglianza tra nomi che una persona deve esaminare, non una constatazione che il fornitore sia sanzionato.

Richiede l’accesso 'view' ai fornitori. Scartare o confermare una corrispondenza spetta a una persona che ha effettuato l’accesso a Pleaxy.

Campi della risposta

  • status"not_screened" | "clear" | "possible_match" | "confirmed_match"

    possible_match: almeno una corrispondenza attende l’esame di una persona. confirmed_match: una persona ha confermato che il fornitore è la parte presente nella lista.

  • subjectsArray<object>

    I nomi che sono stati verificati: il nome del fornitore, un nome precedente e i beneficiari dei suoi conti bancari.

  • listVersionsobject

    La versione di ogni lista di sanzioni rispetto a cui il fornitore è stato verificato l’ultima volta.

  • matchesArray<object>

    Ogni voce di lista a cui un nome verificato somiglia: la lista, i nomi, i paesi e i programmi della voce, e il punteggio. state è open finché una persona non la scarta o la conferma, con chi ha deciso e perché. closed significa che la voce è uscita dalla lista o non corrisponde più.

Errori

  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
GET /v1/workspaces/{regionId}/screening/review
Richiesta
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/screening/review" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 200 OK
[
   {
      "connectionId": "string",
      "supplierKey": "string",
      "supplierName": "string",
      "status": "not_screened" | "clear" | "possible_match" | "confirmed_match",
      "checkedAt": "string",
      "listVersions": { "ofac": "string", "eu": "string", "uk": "string", "un": "string" },
      "subjects": [ { "role": "name" | "former_name" | "payee", "name": "string" } ],
      "countries": [ "string" ],
      "matches": [
         {
            "id": "string",
            "entryId": "string",
            "list": "ofac" | "eu" | "uk" | "un" | "jurisdiction",
            "entryName": "string",
            "matchedName": "string",
            "subject": { "role": "name" | "former_name" | "payee", "name": "string" },
            "score": number,
            "countryMismatch": boolean,
            "entry": { "kind": "entity" | "individual" | "other", "names": [ "string" ], "countries": [ "string" ], "programmes": [ "string" ], "listedOn": "string" },
            "state": "open" | "dismissed" | "confirmed" | "closed",
            "foundAt": "string",
            "decidedAt": "string",
            "decidedBy": { "sub": "string", "name": "string" },
            "reason": "string",
            "closedReason": "entry_removed" | "no_longer_matches"
         }
      ],
      "history": [ { "at": "string", "event": "screened" | "dismissed" | "confirmed" | "reopened" | "closed", "matchId": "string", "by": "string" } ],
      "version": number
   }
]

Ottenere la verifica di un fornitore

Ottiene la verifica delle sanzioni di un fornitore e le sue corrispondenze.

GET/v1/workspaces/{regionId}/screening/suppliers/{connectionId}

Parametri

  • connectionIdstringObbligatorio

    L’id di connessione del fornitore in questo workspace.

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Restituisce se la verifica è attiva e, quando il fornitore è stato verificato, la sua verifica: i nomi verificati, le versioni delle liste e ogni corrispondenza con il suo stato.

Richiede l’accesso 'view' ai fornitori. Scartare o confermare una corrispondenza spetta a una persona che ha effettuato l’accesso a Pleaxy.

Campi della risposta

  • enabledboolean

    Se la verifica delle sanzioni è attiva.

  • status"not_screened" | "clear" | "possible_match" | "confirmed_match"

    possible_match: almeno una corrispondenza attende l’esame di una persona. confirmed_match: una persona ha confermato che il fornitore è la parte presente nella lista.

  • subjectsArray<object>

    I nomi che sono stati verificati: il nome del fornitore, un nome precedente e i beneficiari dei suoi conti bancari.

  • listVersionsobject

    La versione di ogni lista di sanzioni rispetto a cui il fornitore è stato verificato l’ultima volta.

  • matchesArray<object>

    Ogni voce di lista a cui un nome verificato somiglia: la lista, i nomi, i paesi e i programmi della voce, e il punteggio. state è open finché una persona non la scarta o la conferma, con chi ha deciso e perché. closed significa che la voce è uscita dalla lista o non corrisponde più.

Errori

  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
GET /v1/workspaces/{regionId}/screening/suppliers/{connectionId}
Richiesta
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/screening/suppliers/{connectionId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 200 OK
{
   "enabled": boolean,
   "screening": {
      "connectionId": "string",
      "supplierKey": "string",
      "supplierName": "string",
      "status": "not_screened" | "clear" | "possible_match" | "confirmed_match",
      "checkedAt": "string",
      "listVersions": { "ofac": "string", "eu": "string", "uk": "string", "un": "string" },
      "subjects": [ { "role": "name" | "former_name" | "payee", "name": "string" } ],
      "countries": [ "string" ],
      "matches": [
         {
            "id": "string",
            "entryId": "string",
            "list": "ofac" | "eu" | "uk" | "un" | "jurisdiction",
            "entryName": "string",
            "matchedName": "string",
            "subject": { "role": "name" | "former_name" | "payee", "name": "string" },
            "score": number,
            "countryMismatch": boolean,
            "entry": { "kind": "entity" | "individual" | "other", "names": [ "string" ], "countries": [ "string" ], "programmes": [ "string" ], "listedOn": "string" },
            "state": "open" | "dismissed" | "confirmed" | "closed",
            "foundAt": "string",
            "decidedAt": "string",
            "decidedBy": { "sub": "string", "name": "string" },
            "reason": "string",
            "closedReason": "entry_removed" | "no_longer_matches"
         }
      ],
      "history": [ { "at": "string", "event": "screened" | "dismissed" | "confirmed" | "reopened" | "closed", "matchId": "string", "by": "string" } ],
      "version": number
   }
}
Contattaci