GET

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.

Endpoint

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

Base URL: https://app.veltrixpagamentos.com

Autenticacao

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

Modo	Headers/Token	Observacoes de Escopo
API Key	`X-Client-Id` + `X-API-Key`	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.

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

Query Parameters

q(string)Obrigatorio

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

Campos avaliados na busca:

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

companyId(integer)Opcional

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

Resposta de Sucesso - Match Unico (200 OK)

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

{
  "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"
  }
}

Obs: 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:

{
  "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

HTTP	Quando Ocorre	Exemplo de Resposta
400	q ausente ou invalido	`{ "message": "Query q e obrigatoria." }`
403	Credenciais invalidas ou sem permissao	`{ "message": "Credenciais invalidas de API KEY." }`
404	Nenhum saque encontrado no escopo	`{ "message": "Saque nao encontrado para o parametro informado." }`
500	Erro interno inesperado	`{ "message": "Erro interno.", "detail": "..." }`

Exemplos

Buscar por ID

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

Buscar por EndToEnd

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

Buscar por TID

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

JavaScript / Node.js

const q = '1390'; // ID, EndToEnd, TID, ProviderPaymentId ou IdempotencyKey

const response = await fetch(
  `https://app.veltrixpagamentos.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.