Clientes

Crie, filtre, consulte e remova clientes do merchant.

Clientes representam as pessoas associadas às cobranças do merchant. O id retornado em todas as operações pode ser usado no campo opcional customerId de POST /checkouts.

Criar cliente

Requer uma API key FULL_ACCESS.

Listar clientes

Aceita API keys READ_ONLY e FULL_ACCESS.

Remover clientes

A remoção exige uma API key FULL_ACCESS.

Criar um cliente

curl --request POST 'https://api-sandbox.fortalpay.tech/v1/customers' \
  --header 'Authorization: ApiKey <full_access_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Maria Silva",
    "email": "[e-mail]",
    "document": "529.982.247-25",
    "phone": "(85) 99999-9999"
  }'

Campos da requisição

Campo	Obrigatório	Regra
name	Sim	Não pode ser vazio e aceita até 150 caracteres.
email	Sim	Não pode ser vazio e deve ser um e-mail válido com até 150 caracteres.
document	Não	CPF ou CNPJ com até 20 caracteres. A formatação é removida antes do armazenamento.
phone	Não	Telefone com até 20 caracteres. A formatação é removida antes do armazenamento.

O nome é normalizado, o e-mail é armazenado em letras minúsculas e documento e telefone ficam somente com dígitos. Se o documento já estiver associado à conta do merchant, a API reutiliza o cliente existente.

A criação retorna HTTP 200 e expõe o identificador público no campo id, assim como as rotas de listagem e consulta.

Listar clientes

curl --request GET 'https://api-sandbox.fortalpay.tech/v1/customers?page=0&size=20' \
  --header 'Authorization: ApiKey <api_key>'

A listagem retorna somente clientes associados ao merchant da API key, ordenados pela data de criação em ordem decrescente. O tamanho efetivo da página é limitado a 100.

Filtrar clientes

Use search para buscar de uma vez por nome, e-mail, documento ou telefone:

curl --request GET 'https://api-sandbox.fortalpay.tech/v1/customers?search=Maria&page=0&size=20' \
  --header 'Authorization: ApiKey <api_key>'

Também é possível combinar filtros específicos. Todos os filtros informados são aplicados em conjunto.

Parâmetro	Comportamento
search	Busca parcial geral por nome, e-mail, documento e telefone.
name	Busca parcial sem diferenciar maiúsculas e minúsculas.
email	Busca parcial sem diferenciar maiúsculas e minúsculas.
document	Busca parcial; pontuação de CPF ou CNPJ é ignorada.
phone	Busca parcial; formatação é ignorada.
status	Correspondência exata sem diferenciar maiúsculas e minúsculas.

Consultar pelo identificador

curl --request GET 'https://api-sandbox.fortalpay.tech/v1/customers/<customer_id>' \
  --header 'Authorization: ApiKey <api_key>'

Um identificador inexistente, removido ou pertencente a outro merchant retorna 404.

Remover um cliente

curl --request DELETE 'https://api-sandbox.fortalpay.tech/v1/customers/<customer_id>' \
  --header 'Authorization: ApiKey <full_access_api_key>'

A remoção é lógica e retorna HTTP 204 sem corpo. O cliente deixa de aparecer na listagem e não pode mais ser consultado ou usado em novas cobranças pelo merchant. Registros históricos permanecem preservados.

Campos retornados

Campo	Tipo	Descrição
id	UUID	Identificador público do cliente.
name	string	Nome normalizado.
email	string | null	E-mail normalizado em letras minúsculas.
document	string | null	CPF ou CNPJ somente com dígitos.
phone	string | null	Telefone somente com dígitos.
status	enum	Estado do cliente. Atualmente, ACTIVE.
created_at	date-time	Data de criação.
updated_at	date-time	Data da última atualização.