Pular para o conteúdo principal
GET
/
credit-card
/
v1
/
buyer
Listar Compradores
curl --request GET \
  --url https://api-gateway.firebanking.dev/credit-card/v1/buyer \
  --header 'x-api-key: <api-key>'
[
  {
    "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "email": "<string>",
    "document": {
      "documentNumber": "36880261019",
      "documentType": "cpf",
      "documentNation": "BR"
    },
    "phone": "<string>",
    "createdAt": "2023-11-07T05:31:56Z"
  }
]
Recuperar uma lista de compradores com capacidades de filtragem opcionais. Este endpoint suporta paginação e vários filtros de busca para ajudar você a encontrar compradores específicos.

​
Parâmetros de Consulta

​
document
string
Filtrar compradores por número de documento (CPF ou CNPJ)
​
name
string
Filtrar compradores por nome (correspondência parcial suportada)
​
email
string
Filtrar compradores por endereço de email
​
page
integer
default:"0"
Número da página para paginação (baseado em 0)
​
size
integer
default:"10"
Número de itens por página (1-100)

​
Exemplos de Requisições

​
Listar Todos os Compradores (Sem Filtros)

cURL
curl -X GET "https://api-gateway.firebanking.com.br/v1/buyer" \
  -H "x-api-key: SUA_CHAVE_DE_API"

​
Filtrar por Documento

cURL
curl -X GET "https://api-gateway.firebanking.com.br/v1/buyer?document=25201246010&page=0&size=10" \
  -H "x-api-key: SUA_CHAVE_DE_API"

​
Filtrar por Nome e Email

cURL
curl -X GET "https://api-gateway.firebanking.com.br/v1/buyer?name=João&[email protected]&page=0&size=20" \
  -H "x-api-key: SUA_CHAVE_DE_API"

​
Exemplo de Resposta

Resposta
{
  "buyers": [
    {
      "uuid": "buyer-uuid-12345",
      "document": {
        "documentNumber": "36880261019",
        "documentType": "cpf",
        "documentNation": "BR"
      },
      "name": "João Silva",
      "email": "[email protected]",
      "phone": "11999999999",
      "countryCode": "+55",
      "createdAt": "2024-01-15T14:30:00Z",
      "lastTransactionAt": "2024-01-20T10:15:00Z",
      "totalTransactions": 5,
      "totalAmount": 1500
    },
    {
      "uuid": "buyer-uuid-67890",
      "document": {
        "documentNumber": "98765432100",
        "documentType": "cpf",
        "documentNation": "BR"
      },
      "name": "Maria Santos",
      "email": "[email protected]",
      "phone": "11888888888",
      "countryCode": "+55",
      "createdAt": "2024-01-10T09:20:00Z",
      "lastTransactionAt": "2024-01-18T16:45:00Z",
      "totalTransactions": 3,
      "totalAmount": 750
    }
  ],
  "pagination": {
    "currentPage": 0,
    "totalPages": 1,
    "totalElements": 2,
    "pageSize": 10,
    "hasNext": false,
    "hasPrevious": false
  }
}

​
Campos da Resposta

​
buyers
array
Array de objetos de comprador que correspondem aos critérios de filtro
​
pagination
object
Informações de paginação para o conjunto de resultados
​
totalTransactions
integer
Número total de transações bem-sucedidas para este comprador
​
totalAmount
integer
Valor total (em reais) de todas as transações bem-sucedidas
​
lastTransactionAt
string
Timestamp da transação mais recente do comprador

​
Capacidades de Busca

​
Busca por Nome

  • Correspondência parcial: Busca dentro do campo nome
  • Insensível a maiúsculas: “joão” corresponde a “João Silva”
  • Múltiplas palavras: “Silva João” corresponde a “João Silva”

​
Busca por Documento

  • Correspondência exata: Deve corresponder ao número completo do documento
  • Formato flexível: Aceita com ou sem formatação

​
Busca por Email

​
Paginação

Baseada em Página

Usa números de página começando de 0

Controle de Tamanho

Configure itens por página (máx 100)

​
Casos de Uso

Busca de Cliente

Encontrar clientes durante chamadas de suporte

Gerenciamento de Conta

Navegar e gerenciar contas de clientes

Análises

Exportar dados de clientes para análise

Reconciliação

Corresponder compradores com sistemas externos
Use filtros específicos para reduzir o tamanho da resposta e melhorar o desempenho. Evite buscar todos os compradores sem filtros em produção.

​
Dicas de Performance

  1. Use filtros - Sempre aplique filtros relevantes para reduzir transferência de dados
  2. Limite tamanho da página - Use tamanhos de página apropriados (10-50 itens)
  3. Cache resultados - Faça cache de dados de comprador acessados frequentemente
  4. Buscas indexadas - Buscas por documento e email são otimizadas
  5. Evite exportações grandes - Para operações em lote, use nossas APIs de exportação

​
Cenários de Erro

  • Tamanho de página inválido: Tamanho da página excede o máximo (100)
  • Número de página inválido: Números de página negativos
  • Formato de documento inválido: Documento não corresponde ao formato CPF/CNPJ
  • Sem resultados: Retorna array vazio quando nenhum comprador corresponde aos critérios

Authorizations

​
x-api-key
string
header
required

Chave de API para autenticação

Query Parameters

​
document
string

Filtrar por número de documento

​
name
string

Filtrar por nome do comprador

​
email
string

Filtrar por endereço de email

​
page
integer
default:0

Número da página para paginação

Intervalo obrigatório: x >= 0
​
size
integer
default:10

Número de itens por página

Intervalo obrigatório: 1 <= x <= 100

Response

200 - application/json

Compradores recuperados com sucesso

​
uuid
string<uuid>

UUID do comprador

​
name
string

Nome do comprador

​
email
string

Endereço de email

​
document
object
​
phone
string

Número de telefone

​
createdAt
string<date-time>

Timestamp de criação