Referência da API

Risco de fornecedores

O que merece atenção em cada fornecedor: dados bancários, verificação de sanções e documentos faltantes.

Mais sobre este recurso

A Pleaxy mantém três verificações sobre cada fornecedor de um comprador e as resume em um nível: ok, attention ou blocked. Dados bancários: a conta em que cada fatura pede para ser paga fica registrada por canal de cobrança, e uma fatura que indica uma conta nova ou diferente aguarda a aprovação de uma pessoa antes de poder ser exportada para pagamento. Verificação de sanções: quando ativada, os nomes do fornecedor são comparados com as listas da OFAC, da UE, do Reino Unido e da ONU, e os pagamentos aguardam enquanto uma possível correspondência é analisada. Questionários: respostas sinalizadas e documentos faltantes. Estes endpoints apenas leem. Aprovar uma conta bancária e decidir sobre uma correspondência da verificação é feito por uma pessoa conectada na Pleaxy.

Listar risco de fornecedores

Lista o nível de risco de cada fornecedor e as verificações por trás dele.

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

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Retorna o nível de cada fornecedor com suas linhas: bank, screening, flaggedAnswers e missingDocuments, cada uma com um estado ok, attention, blocked ou none. Nesta lista, uma verificação sem nada sinalizado aparece como none; consulte um fornecedor com GetSupplierRisk para ver a situação completa da conta bancária e da verificação.

Precisa de acesso 'view' aos fornecedores.

Campos da resposta

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

    O estado mais grave entre as linhas que o espaço de trabalho considera para o nível. blocked significa uma correspondência de sanções confirmada. É um nível, nunca uma pontuação.

  • bankobject

    As contas bancárias registradas do fornecedor: waiting conta as contas que aguardam aprovação.

  • screeningobject

    A verificação de sanções do fornecedor: seu status e quando foi verificada pela última vez. status é off enquanto a verificação não está ativada.

  • flaggedAnswersobject

    Quantas respostas do questionário do fornecedor estão sinalizadas para análise.

  • missingDocumentsobject

    Os rótulos dos documentos obrigatórios do questionário que o fornecedor não forneceu.

Erros

  • 401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
  • 403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.
GET /v1/workspaces/{regionId}/supplier-risk
Requisição
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/supplier-risk" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Resposta · 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" ] }
   }
]

Obter risco de fornecedor

Obtém o nível de risco de um fornecedor e as verificações por trás dele.

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

Parâmetros

  • connectionIdstringObrigatório

    O id de conexão do fornecedor neste espaço de trabalho.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Retorna o risco de um fornecedor como ListSupplierRisk faz, com bank.status e o status e checkedAt da verificação preenchidos.

Precisa de acesso 'view' aos fornecedores.

Campos da resposta

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

    O estado mais grave entre as linhas que o espaço de trabalho considera para o nível. blocked significa uma correspondência de sanções confirmada. É um nível, nunca uma pontuação.

  • bankobject

    As contas bancárias registradas do fornecedor: waiting conta as contas que aguardam aprovação.

  • screeningobject

    A verificação de sanções do fornecedor: seu status e quando foi verificada pela última vez. status é off enquanto a verificação não está ativada.

  • flaggedAnswersobject

    Quantas respostas do questionário do fornecedor estão sinalizadas para análise.

  • missingDocumentsobject

    Os rótulos dos documentos obrigatórios do questionário que o fornecedor não forneceu.

Erros

  • 401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
  • 403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.
GET /v1/workspaces/{regionId}/supplier-risk/{connectionId}
Requisição
GET /v1/workspaces/reg_01k5x8p9j3q7vn2mhb4tzc6rde.buyer/supplier-risk/SC-1A2B3C4D
Resposta · 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": [] }
}

Listar contas bancárias a aprovar

Lista as contas bancárias de fornecedores que aguardam a aprovação de uma pessoa.

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

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Retorna as contas bancárias que aguardam aprovação: a primeira conta de um canal de cobrança (status unverified) ou uma alteração em uma já aprovada (status changing, com pendingChange). As faturas a serem pagas nessas contas aguardam até que uma pessoa as aprove.

Precisa de acesso 'view' às faturas. Aprovar uma conta, rejeitar uma alteração e mostrar os números completos é feito por uma pessoa conectada na Pleaxy.

Campos da resposta

  • laneKeystring

    O canal de cobrança ao qual a conta pertence: um favorecido e uma moeda deste fornecedor.

  • detailsobject

    Os dados de pagamento registrados, com os números da conta mascarados, exceto os últimos quatro caracteres.

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

    unverified: a primeira conta do canal, aguardando aprovação. verified: aprovada. changing: uma fatura indicou outros dados, guardados em pendingChange até que uma pessoa os aprove ou rejeite.

  • approvalobject

    Como a conta foi aprovada. verification é supplier_confirmed, buyer_approved ou paid_before, e check.method é como o comprador a conferiu.

  • historyArray<object>

    Os eventos mais recentes da conta, com o número da conta mascarado.

Erros

  • 401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
  • 403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.
GET /v1/workspaces/{regionId}/bank-accounts/review
Requisição
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/bank-accounts/review" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Resposta · 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"
   }
]

Listar contas bancárias de fornecedor

Lista as contas bancárias registradas de um fornecedor, com a forma como cada uma foi aprovada.

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

Parâmetros

  • connectionIdstringObrigatório

    O id de conexão do fornecedor neste espaço de trabalho.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Retorna as contas bancárias registradas de um fornecedor, uma por canal de cobrança (um favorecido e uma moeda), com o status de cada conta, como foi aprovada e seus últimos 10 eventos.

Precisa de acesso 'view' às faturas. Aprovar uma conta, rejeitar uma alteração e mostrar os números completos é feito por uma pessoa conectada na Pleaxy.

Campos da resposta

  • laneKeystring

    O canal de cobrança ao qual a conta pertence: um favorecido e uma moeda deste fornecedor.

  • detailsobject

    Os dados de pagamento registrados, com os números da conta mascarados, exceto os últimos quatro caracteres.

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

    unverified: a primeira conta do canal, aguardando aprovação. verified: aprovada. changing: uma fatura indicou outros dados, guardados em pendingChange até que uma pessoa os aprove ou rejeite.

  • approvalobject

    Como a conta foi aprovada. verification é supplier_confirmed, buyer_approved ou paid_before, e check.method é como o comprador a conferiu.

  • historyArray<object>

    Os eventos mais recentes da conta, com o número da conta mascarado.

Erros

  • 401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
  • 403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.
GET /v1/workspaces/{regionId}/bank-accounts/suppliers/{connectionId}
Requisição
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/bank-accounts/suppliers/{connectionId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Resposta · 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"
   }
]

Obter conta bancária da fatura

Diz se o pagamento de uma fatura aguarda a conta bancária do fornecedor.

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

Parâmetros

  • invoiceIdstringObrigatório

    O id da fatura, por exemplo INV-7F3A9C21.

  • buyerstring

    Para quem chama como fornecedor, o comprador ao qual a fatura pertence, como em GetInvoice.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Diz se esta fatura aguarda a conta bancária do seu fornecedor. hold é first_payment quando a conta do canal de cobrança ainda não foi aprovada, differs_from_file quando a fatura indica dados diferentes dos da conta aprovada, e fica ausente quando a fatura pode ser paga. Enquanto aguarda, a fatura não pode ser exportada para pagamento; registrar um pagamento feito por outro meio e pagar pela Pleaxy não ficam retidos.

Precisa de acesso 'view' às faturas. Quem chama como fornecedor recebe apenas hold.

Campos da resposta

  • hold"first_payment" | "differs_from_file"

    Por que o pagamento aguarda. Ausente quando não aguarda.

  • accountobject

    A conta registrada do canal de cobrança, com os números mascarados, exceto os últimos quatro caracteres.

Erros

  • 404 Not Found - Não há fatura com este id que quem chama possa ver.
  • 409 Conflict - Só para quem chama como Fornecedor. Código INVOICE_ID_AMBIGUOUS: mais de um dos seus compradores tem uma fatura sua com este id (os ids são únicos só dentro de um comprador), então a Pleaxy não tenta adivinhar a qual você se refere. Nada é lido nem alterado. O campo buyers do corpo lista o ID do espaço de trabalho e o nome de cada comprador: repita a chamada com ?buyer=<esse ID do espaço de trabalho>.
  • 401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
  • 403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.
GET /v1/workspaces/{regionId}/invoices/{invoiceId}/bank-account
Requisição
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/invoices/{invoiceId}/bank-account" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Resposta · 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"
}

Listar correspondências da verificação

Lista os fornecedores cuja verificação de sanções tem uma correspondência a analisar ou uma confirmada.

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

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Retorna os fornecedores cujo status de verificação é possible_match ou confirmed_match. Os pagamentos a eles aguardam, e um fornecedor com uma correspondência confirmada não recebe novos pedidos nem faturas lançadas pelo comprador. A lista fica vazia enquanto a verificação está desativada. Uma correspondência é uma semelhança entre nomes para uma pessoa analisar, não uma conclusão de que o fornecedor está sancionado.

Precisa de acesso 'view' aos fornecedores. Descartar ou confirmar uma correspondência é feito por uma pessoa conectada na Pleaxy.

Campos da resposta

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

    possible_match: pelo menos uma correspondência aguarda a análise de uma pessoa. confirmed_match: uma pessoa confirmou que o fornecedor é a parte listada.

  • subjectsArray<object>

    Os nomes que foram verificados: o nome do fornecedor, um nome anterior e os favorecidos das suas contas bancárias.

  • listVersionsobject

    A versão de cada lista de sanções contra a qual o fornecedor foi verificado pela última vez.

  • matchesArray<object>

    Cada entrada de lista com a qual um nome verificado se parece: a lista, os nomes, países e programas da entrada, e a pontuação. state é open até que uma pessoa a descarte ou confirme, com quem decidiu e por quê. closed significa que a entrada saiu da lista ou não corresponde mais.

Erros

  • 401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
  • 403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.
GET /v1/workspaces/{regionId}/screening/review
Requisição
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/screening/review" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Resposta · 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
   }
]

Obter verificação de fornecedor

Obtém a verificação de sanções de um fornecedor e suas correspondências.

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

Parâmetros

  • connectionIdstringObrigatório

    O id de conexão do fornecedor neste espaço de trabalho.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Retorna se a verificação está ativada e, quando o fornecedor já foi verificado, sua verificação: os nomes verificados, as versões das listas e cada correspondência com seu estado.

Precisa de acesso 'view' aos fornecedores. Descartar ou confirmar uma correspondência é feito por uma pessoa conectada na Pleaxy.

Campos da resposta

  • enabledboolean

    Se a verificação de sanções está ativada.

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

    possible_match: pelo menos uma correspondência aguarda a análise de uma pessoa. confirmed_match: uma pessoa confirmou que o fornecedor é a parte listada.

  • subjectsArray<object>

    Os nomes que foram verificados: o nome do fornecedor, um nome anterior e os favorecidos das suas contas bancárias.

  • listVersionsobject

    A versão de cada lista de sanções contra a qual o fornecedor foi verificado pela última vez.

  • matchesArray<object>

    Cada entrada de lista com a qual um nome verificado se parece: a lista, os nomes, países e programas da entrada, e a pontuação. state é open até que uma pessoa a descarte ou confirme, com quem decidiu e por quê. closed significa que a entrada saiu da lista ou não corresponde mais.

Erros

  • 401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
  • 403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.
GET /v1/workspaces/{regionId}/screening/suppliers/{connectionId}
Requisição
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/screening/suppliers/{connectionId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Resposta · 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
   }
}
Fale conosco