Consultar Saque por Lookup

Consulta um saque por multiplos identificadores (ID, EndToEnd, TID, ProviderPaymentId, IdempotencyKey).

Versao 1.0 - Este endpoint permite buscar um saque usando um unico parametro (q) que pode conter qualquer identificador do saque. Em modo API Key, o escopo e automaticamente limitado a empresa da credencial.

GET/api/Withdraw/lookup?q={identificador}

Autenticacao

O endpoint exige autenticacao. Voce pode usar API Key ou JWT.

API Key

X-Client-Id: <client_id> | X-API-Key: <secret>

Escopo sempre limitado a empresa da credencial. Se enviar companyId diferente: 403.

JWT

Authorization: Bearer <jwt>

Admin/Manager: pode consultar geral e filtrar por companyId. Usuario comum: somente propria empresa.

ATENCAO: Nao registre (log) o valor de X-API-Key. Use variaveis de ambiente e rotacao de segredo quando necessario.

Query Parameters

Parametro	Tipo	Descricao
`q`*	string	Chave de busca: Id (numerico), ProviderEndToEndId (EndToEnd), ProviderTid (TID), ProviderPaymentId, IdempotencyKey
`companyId`	integer	Filtro opcional (apenas util para Admin/Manager via JWT). Em modo API Key, deve ser omitido ou igual a empresa da credencial.

q

Obrigatoriostring

Chave de busca: Id (numerico), ProviderEndToEndId (EndToEnd), ProviderTid (TID), ProviderPaymentId, IdempotencyKey

companyId

integer

Filtro opcional (apenas util para Admin/Manager via JWT). Em modo API Key, deve ser omitido ou igual a empresa da credencial.

Campos avaliados na busca:

Id (apenas quando q for numerico)
ProviderEndToEndId (EndToEnd)
ProviderTid (TID)
ProviderPaymentId
IdempotencyKey

Resposta de Sucesso - Match Unico (200 OK)

Quando 1 saque e encontrado, o endpoint retorna ok=true, o objeto withdraw e o bloco keys.

Response

{
  "ok": true,
  "withdraw": {
    "id": 1390,
    "companyId": 1,
    "value": 1112.00,
    "currency": "BRL",
    "pixKey": "12505368473",
    "pixKeyType": "CPF",
    "creditorDocument": "44444444444444",
    "enTransaction": "Successful",
    "provider": "A55",
    "providerPaymentId": "175b4f3a-2d71-401c-9dd2-1f33cb32fc7a",
    "providerTid": "wld-00001390",
    "providerEndToEndId": "E48756121202602031458MHoTfthbxEq",
    "providerStatus": "successful",
    "providerPayload": "{... string JSON do provedor ...}"
  },
  "keys": {
    "id": 1390,
    "companyId": 1,
    "providerTid": "wld-00001390",
    "providerPaymentId": "175b4f3a-2d71-401c-9dd2-1f33cb32fc7a",
    "end2end": "E48756121202602031458MHoTfthbxEq",
    "idempotencyKey": "2ce66db9-7d2f-4761-a5d4-46799ab8709f"
  }
}

INFO: providerPayload e retornado como string JSON (auditoria/debug). Se precisar ler campos internos, faca parse do JSON no cliente.

Resposta Ambigua - Multiplos Matches (200 OK)

Quando mais de 1 saque e encontrado:

Response (Ambiguous)

{
  "ok": true,
  "ambiguous": true,
  "count": 2,
  "items": [
    {
      "id": 1001,
      "companyId": 1,
      "value": 10.00,
      "status": "Successful",
      "providerTid": "wld-00001001"
    },
    {
      "id": 1002,
      "companyId": 1,
      "value": 10.00,
      "status": "Successful",
      "providerTid": "wld-00001002"
    }
  ],
  "hint": "Use o Id retornado e consulte /api/Withdraw/{id}."
}

Codigos de Erro

400q ausente ou invalido

{ "message": "Query q e obrigatoria." }

403Credenciais invalidas ou sem permissao

{ "message": "Credenciais invalidas de API KEY." }

404Nenhum saque encontrado no escopo

{ "message": "Saque nao encontrado para o parametro informado." }

500Erro interno inesperado

{ "message": "Erro interno.", "detail": "..." }

Exemplos cURL

Buscar por ID:

cURL

curl -sS "https://vorexy.com/api/Withdraw/lookup?q=1390" \
  -H "X-Client-Id: <client_id>" \
  -H "X-API-Key: <secret>"

Buscar por EndToEnd:

cURL

curl -sS "https://vorexy.com/api/Withdraw/lookup?q=E123...XYZ" \
  -H "X-Client-Id: <client_id>" \
  -H "X-API-Key: <secret>"

Buscar por TID:

cURL

curl -sS "https://vorexy.com/api/Withdraw/lookup?q=wld-00001390" \
  -H "X-Client-Id: <client_id>" \
  -H "X-API-Key: <secret>"

Exemplo JavaScript / Node.js

JavaScript

const q = '1390'; // ID, EndToEnd, TID, ProviderPaymentId ou IdempotencyKey
const response = await fetch(
  `https://vorexy.com/api/Withdraw/lookup?q=${encodeURIComponent(q)}`,
  {
    method: 'GET',
    headers: {
      'X-Client-Id': '<client_id>',
      'X-API-Key': '<secret>'
    }
  }
);
const data = await response.json();
if (data.ok && !data.ambiguous) {
  console.log('Saque encontrado:', data.withdraw);
  console.log('Identificadores:', data.keys);
} else if (data.ambiguous) {
  console.log(`${data.count} saques encontrados. Use ID especifico.`);
  console.log(data.items);
}

Recomendacoes de Performance

Para consultas frequentes, recomenda-se criar indices (PostgreSQL) nos campos:

(CompanyId, ProviderEndToEndId)
(CompanyId, ProviderTid)
(CompanyId, ProviderPaymentId)
(CompanyId, IdempotencyKey)

Em modo API Key, o filtro por CompanyId reduz o conjunto de dados e melhora significativamente a latencia.