Obter Comprador

Recuperar informações detalhadas de um comprador específico pelo seu UUID. Este endpoint retorna todos os dados do comprador, incluindo informações pessoais, documento, endereço e metadados de criação.

Parâmetro do Path

buyerUuid

string

required

O UUID único do comprador que você deseja recuperar

Exemplo de Requisição

curl -X GET "https://api-gateway.firebanking.com.br/v1/buyer/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: SUA_CHAVE_DE_API"

Exemplo de Resposta

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "name": "João da Silva Teste",
  "email": "[email protected]",
  "document": {
    "documentNumber": "11144477735",
    "documentType": "cpf",
    "documentNation": "BR"
  },
  "phone": "11999999999",
  "countryCode": "+55",
  "alternativeEmail": "[email protected]",
  "address": {
    "street": "Rua das Flores",
    "number": "123",
    "complement": "Apto 45",
    "district": "Centro",
    "city": "São Paulo",
    "state": "SP",
    "country": "BR",
    "zipCode": "01000000"
  },
  "createdAt": "2024-01-15T14:30:00Z",
  "updatedAt": "2024-01-15T14:30:00Z"
}

Campos de Resposta

uuid

string

UUID único do comprador no sistema

name

string

Nome completo do comprador

string

Endereço de email principal do comprador

document

object

Informações do documento do comprador

Mostrar document

document.documentNumber

string

Número do documento (CPF ou CNPJ)

document.documentType

string

Tipo do documento: cpf ou cnpj

document.documentNation

string

Código do país do documento (ex: BR)

phone

string

Número de telefone com código de área

countryCode

string

Código do país com prefixo + (ex: +55)

alternativeEmail

string

Endereço de email alternativo (opcional)

address

object

Endereço completo do comprador (opcional)

Mostrar address

address.street

string

Nome da rua/logradouro

address.number

string

Número da residência/estabelecimento

address.complement

string

Complemento do endereço (apto, sala, etc.)

address.district

string

Bairro/distrito

address.city

string

Nome da cidade

address.state

string

Código do estado (ex: SP)

address.country

string

Código do país (ex: BR)

address.zipCode

string

CEP/código postal

createdAt

string

Data e hora de criação do comprador (ISO 8601)

updatedAt

string

Data e hora da última atualização (ISO 8601)

Casos de Uso Comuns

Verificar Dados Antes do Pagamento

async function validateBuyerBeforePayment(buyerUuid) {
  try {
    const response = await fetch(`https://api-gateway.firebanking.com.br/v1/buyer/${buyerUuid}`, {
      headers: {
        'x-api-key': 'SUA_CHAVE_DE_API'
      }
    });

    if (response.status === 404) {
      throw new Error('Comprador não encontrado');
    }

    const buyer = await response.json();

    // Verificar se dados estão completos
    if (!buyer.address) {
      console.warn('Comprador sem endereço cadastrado');
    }

    return buyer;
  } catch (error) {
    console.error('Erro ao verificar comprador:', error);
    throw error;
  }
}

Exibir Perfil do Cliente

function displayBuyerProfile(buyer) {
  const profileHtml = `
    <div class="buyer-profile">
      <h3>${buyer.name}</h3>
      <p><strong>Email:</strong> ${buyer.email}</p>
      <p><strong>Telefone:</strong> ${buyer.phone}</p>
      <p><strong>Documento:</strong> ${buyer.document.documentNumber}</p>
      ${buyer.address ? `
        <div class="address">
          <strong>Endereço:</strong>
          <p>${buyer.address.street}, ${buyer.address.number}</p>
          <p>${buyer.address.district}, ${buyer.address.city} - ${buyer.address.state}</p>
          <p>CEP: ${buyer.address.zipCode}</p>
        </div>
      ` : ''}
      <small>Cliente desde: ${new Date(buyer.createdAt).toLocaleDateString('pt-BR')}</small>
    </div>
  `;

  document.getElementById('buyer-profile').innerHTML = profileHtml;
}

Validar Dados para Compliance

function validateBuyerCompliance(buyer) {
  const validations = {
    hasValidDocument: buyer.document && buyer.document.documentNumber,
    hasEmail: buyer.email && buyer.email.includes('@'),
    hasPhone: buyer.phone && buyer.phone.length >= 10,
    hasAddress: buyer.address && buyer.address.zipCode
  };

  const isCompliant = Object.values(validations).every(v => v);

  if (!isCompliant) {
    console.warn('Comprador não está em compliance completo:', validations);
  }

  return {
    isCompliant,
    validations,
    missingFields: Object.keys(validations).filter(key => !validations[key])
  };
}

Códigos de Erro

Código HTTP	Código de Erro	Descrição
400	`INVALID_UUID`	UUID fornecido não está no formato válido
401	`UNAUTHORIZED`	Chave de API inválida ou ausente
404	`BUYER_NOT_FOUND`	Comprador não encontrado com o UUID fornecido
500	`INTERNAL_SERVER_ERROR`	Erro interno do servidor

Boas Práticas

Cache de Dados

Cache os dados do comprador localmente para evitar consultas desnecessárias
Implemente TTL (time-to-live) de 1-4 horas para dados do comprador
Invalide o cache quando o comprador for atualizado

Tratamento de Erros

async function getBuyerSafely(buyerUuid) {
  try {
    const response = await fetch(`/v1/buyer/${buyerUuid}`);

    if (response.status === 404) {
      return null; // Comprador não existe
    }

    if (!response.ok) {
      throw new Error(`Erro ${response.status}: ${response.statusText}`);
    }

    return await response.json();
  } catch (error) {
    console.error('Erro ao buscar comprador:', error);
    return null;
  }
}

Segurança

Sempre valide o UUID antes de fazer a requisição
Nunca exponha UUIDs de compradores em URLs públicas
Implemente rate limiting para prevenir abuso

Próximos Passos

Criar Pagamento

Use os dados do comprador para processar pagamentos

Listar Compradores

Busque compradores por filtros específicos

Criar Comprador

Cadastre novos compradores no sistema

Tokenizar Cartão

Crie tokens seguros para o comprador

Authorizations

x-api-key

string

header

required

Chave de API para autenticação

Path Parameters

buyerUuid

string<uuid>

required

UUID do comprador

Response

Comprador recuperado com sucesso

uuid

string<uuid>

UUID do comprador

name

string

Nome do comprador

string

Endereço de email

document

object

Mostrar atributos filhos

document.documentNumber

string

required

Número do documento

Example:

"36880261019"

document.documentType

enum<string>

required

Tipo de documento

Opções disponíveis:

cpf,

cnpj

Example:

"cpf"

document.documentNation

string

required

Código do país do documento

Example:

"BR"

phone

string

Número de telefone

createdAt

string<date-time>

Timestamp de criação

Visão Geral

Fluxo de Integração

Pagamentos

Tokenização

Assinaturas

Gestão de Compradores

Webhooks

Parâmetro do Path

Exemplo de Requisição

Exemplo de Resposta

Campos de Resposta

Casos de Uso Comuns

Verificar Dados Antes do Pagamento

Exibir Perfil do Cliente

Validar Dados para Compliance

Códigos de Erro

Boas Práticas

Cache de Dados

Tratamento de Erros

Segurança

Próximos Passos

Criar Pagamento

Listar Compradores

Criar Comprador

Tokenizar Cartão

Authorizations

Path Parameters

Response

Visão Geral

Fluxo de Integração

Pagamentos

Tokenização

Assinaturas

Gestão de Compradores

Webhooks

​Parâmetro do Path

​Exemplo de Requisição

​Exemplo de Resposta

​Campos de Resposta

​Casos de Uso Comuns

​Verificar Dados Antes do Pagamento

​Exibir Perfil do Cliente

​Validar Dados para Compliance

​Códigos de Erro

​Boas Práticas

​Cache de Dados

​Tratamento de Erros

​Segurança

​Próximos Passos

Criar Pagamento

Listar Compradores

Criar Comprador

Tokenizar Cartão

Authorizations

Path Parameters

Response

Parâmetro do Path

Exemplo de Requisição

Exemplo de Resposta

Campos de Resposta

Casos de Uso Comuns

Verificar Dados Antes do Pagamento

Exibir Perfil do Cliente

Validar Dados para Compliance

Códigos de Erro

Boas Práticas

Cache de Dados

Tratamento de Erros

Segurança

Próximos Passos