Consultar carteira

Quick Reference

WhatRecuperar detalhes da carteira por UUID, e-mail ou ID do cliente

WhyVerificação de saldo, conciliação e relatórios multi-moeda

Reading Time3 min

DifficultyBeginner

PrerequisitesAutenticação → UUID da Carteira ou e-mail ou customer_id

GET/api/v1/bank/wallet/Bearer TokenRecuperar uma carteira

Quando usar este endpoint

Sem consulta de carteira	Com consulta de carteira
Adivinhar se os fundos chegaram	Verificar o saldo exato antes de criar cobranças
Sem visibilidade do estado da carteira	Consultar status, moeda e data de criação da carteira
Conciliação manual em planilhas	Conciliação automatizada — comparar esperado vs. real
UUIDs de carteira fixos no código	Busca dinâmica por e-mail ou customer_id
Impossível construir painéis multi-moeda	Consultar cada carteira por moeda e agregar para relatórios

---

Fluxo de conciliação

---

Autenticação

Requer token Bearer. Veja Autenticação.

Parâmetros de consulta

Campo	Tipo	Obrigatório	Descrição
wallet_uuid	string (UUID)	Pelo menos um	Busca direta da carteira por UUID
email	string	Pelo menos um	Encontrar carteira pelo e-mail associado
customer_id	string	Pelo menos um	Encontrar carteira pelo seu ID interno de cliente

Busca flexível

Forneça pelo menos um parâmetro. Você pode combiná-los para refinar os resultados — por exemplo, ?customer_id=cust_12345&currency=BRL encontra a carteira BRL daquele cliente.

---

Exemplos de código

Busca por UUID da carteira

cURL

curl -s -G https://core-manager.a55.tech/api/v1/bank/wallet/ \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "wallet_uuid=f47ac10b-58cc-4372-a567-0e02b2c3d479"

Python

import requests
import os

token = os.environ["A55_API_TOKEN"]

wallet = requests.get(
    "https://core-manager.a55.tech/api/v1/bank/wallet/",
    params={"wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479"},
    headers={"Authorization": f"Bearer {token}"},
).json()

print(f"Wallet: {wallet['wallet_uuid']}")
print(f"Currency: {wallet['currency']}")
print(f"Email: {wallet['email']}")

JavaScript

const token = process.env.A55_API_TOKEN;

const params = new URLSearchParams({
  wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
});

const wallet = await fetch(
  `https://core-manager.a55.tech/api/v1/bank/wallet/?${params}`,
  { headers: { Authorization: `Bearer ${token}` } }
).then((r) => r.json());

console.log(`Wallet: ${wallet.wallet_uuid}`);
console.log(`Currency: ${wallet.currency}`);
console.log(`Email: ${wallet.email}`);

Busca por e-mail

cURL

curl -s -G https://core-manager.a55.tech/api/v1/bank/wallet/ \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "email=financeiro@loja-sp.com.br"

Python

wallet = requests.get(
    "https://core-manager.a55.tech/api/v1/bank/wallet/",
    params={"email": "financeiro@loja-sp.com.br"},
    headers={"Authorization": f"Bearer {token}"},
).json()
print(f"Found wallet: {wallet['wallet_uuid']} ({wallet['currency']})")

JavaScript

const params = new URLSearchParams({ email: "financeiro@loja-sp.com.br" });

const wallet = await fetch(
  `https://core-manager.a55.tech/api/v1/bank/wallet/?${params}`,
  { headers: { Authorization: `Bearer ${token}` } }
).then((r) => r.json());

console.log(`Found wallet: ${wallet.wallet_uuid} (${wallet.currency})`);

Busca por ID do cliente

cURL

curl -s -G https://core-manager.a55.tech/api/v1/bank/wallet/ \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "customer_id=cust_12345"

Python

wallet = requests.get(
    "https://core-manager.a55.tech/api/v1/bank/wallet/",
    params={"customer_id": "cust_12345"},
    headers={"Authorization": f"Bearer {token}"},
).json()
print(f"Found wallet: {wallet['wallet_uuid']} ({wallet['currency']})")

JavaScript

const params = new URLSearchParams({ customer_id: "cust_12345" });

const wallet = await fetch(
  `https://core-manager.a55.tech/api/v1/bank/wallet/?${params}`,
  { headers: { Authorization: `Bearer ${token}` } }
).then((r) => r.json());

console.log(`Found wallet: ${wallet.wallet_uuid} (${wallet.currency})`);

---

Resposta

Sucesso (200 OK)

{
  "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "email": "financeiro@loja-sp.com.br",
  "customer_id": "cust_12345",
  "currency": "BRL",
  "date": "2026-03-15T10:30:00-03:00"
}

Campos da resposta

Campo	Tipo	Descrição
wallet_uuid	string (UUID)	Identificador único da carteira
email	string	E-mail associado à carteira
customer_id	string	Seu ID interno do cliente
currency	string	Código de moeda ISO 4217 (BRL, MXN, CLP, ARS)
date	string (ISO 8601)	Data e hora de criação da carteira

Resposta de erro

{
  "error": "not_found",
  "message": "Wallet not found",
  "code": "errors.wallet.not_found"
}

Status	Código	Descrição	Resolução
400	validation_error	Nenhum parâmetro de consulta fornecido	Informe pelo menos um entre wallet_uuid, email ou customer_id
401	unauthorized	Token Bearer inválido ou expirado	Renove seu token de acesso
404	errors.wallet.not_found	Nenhuma carteira corresponde à consulta	Verifique o identificador ou crie uma carteira primeiro

---

Exemplo completo — script de conciliação diária

Um script prático que verifica o estado da carteira e compara com seus registros esperados:

cURL

#!/bin/bash
# Conciliação diária de carteiras — executar via cron
TOKEN="$A55_API_TOKEN"
BASE="https://core-manager.a55.tech/api/v1/bank/wallet/"

WALLETS=("cust_12345" "cust_67890" "cust_24680")

for CUST_ID in "${WALLETS[@]}"; do
  RESPONSE=$(curl -s -G "$BASE" \
    -H "Authorization: Bearer $TOKEN" \
    --data-urlencode "customer_id=$CUST_ID")

  WALLET_UUID=$(echo "$RESPONSE" | jq -r '.wallet_uuid')
  CURRENCY=$(echo "$RESPONSE" | jq -r '.currency')

  if [ "$WALLET_UUID" = "null" ]; then
    echo "MISSING: No wallet for customer $CUST_ID"
  else
    echo "OK: $CUST_ID → $WALLET_UUID ($CURRENCY)"
  fi
done

Python

import requests
import os

token = os.environ["A55_API_TOKEN"]
base = "https://core-manager.a55.tech/api/v1/bank/wallet/"
headers = {"Authorization": f"Bearer {token}"}

expected_wallets = {
    "cust_12345": "BRL",
    "cust_67890": "MXN",
    "cust_24680": "BRL",
}

reconciliation = {"matched": 0, "missing": 0, "mismatch": 0}

for customer_id, expected_currency in expected_wallets.items():
    response = requests.get(
        base,
        params={"customer_id": customer_id},
        headers=headers,
    )

    if response.status_code == 404:
        print(f"MISSING: {customer_id} — no wallet found")
        reconciliation["missing"] += 1
        continue

    wallet = response.json()
    if wallet["currency"] != expected_currency:
        print(f"MISMATCH: {customer_id} — expected {expected_currency}, got {wallet['currency']}")
        reconciliation["mismatch"] += 1
    else:
        print(f"OK: {customer_id} → {wallet['wallet_uuid']} ({wallet['currency']})")
        reconciliation["matched"] += 1

print(f"\nReconciliation: {reconciliation}")

JavaScript

const token = process.env.A55_API_TOKEN;
const base = "https://core-manager.a55.tech/api/v1/bank/wallet/";

const expectedWallets = {
  cust_12345: "BRL",
  cust_67890: "MXN",
  cust_24680: "BRL",
};

const results = { matched: 0, missing: 0, mismatch: 0 };

for (const [customerId, expectedCurrency] of Object.entries(expectedWallets)) {
  const params = new URLSearchParams({ customer_id: customerId });
  const response = await fetch(`${base}?${params}`, {
    headers: { Authorization: `Bearer ${token}` },
  });

  if (response.status === 404) {
    console.log(`MISSING: ${customerId} — no wallet found`);
    results.missing++;
    continue;
  }

  const wallet = await response.json();
  if (wallet.currency !== expectedCurrency) {
    console.log(`MISMATCH: ${customerId} — expected ${expectedCurrency}, got ${wallet.currency}`);
    results.mismatch++;
  } else {
    console.log(`OK: ${customerId} → ${wallet.wallet_uuid} (${wallet.currency})`);
    results.matched++;
  }
}

console.log("\nReconciliation:", results);

---

Dicas

Faça cache dos UUIDs das carteiras

Após a primeira consulta, armazene o wallet_uuid no seu banco de dados. Buscas diretas por UUID são mais rápidas que consultas por e-mail ou customer_id. Recorra à busca por e-mail/customer_id apenas quando o UUID em cache retornar 404 (carteira foi excluída e recriada).

Limites de taxa

Consultas de carteira compartilham o limite de taxa global de 100 requisições/minuto por token. Para conciliação em alto volume, espalhe suas consultas com um pequeno intervalo entre requisições em vez de disparar todas de uma vez.

Não faça polling para mudanças de saldo

Use webhooks para reagir a mudanças de status de cobrança em tempo real. Reserve consultas de carteira para jobs de conciliação agendados, não como substituto de uma arquitetura orientada a eventos.

Criar carteira →Configure uma nova carteira para um comerciante e moeda.Criar cobrança →Processe um pagamento nesta carteira.Listar cobranças →Recupere todas as cobranças de uma carteira com filtros e paginação.