Clientes

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": "maria@example.com",
    "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.

Comece aqui

Recursos

Criar cliente

Listar clientes

Remover clientes

Criar um cliente

Campos da requisição

Listar clientes

Filtrar clientes

Consultar pelo identificador

Remover um cliente

Campos retornados

Criar cliente

Listar clientes

Remover clientes

​Criar um cliente

​Campos da requisição

​Listar clientes

​Filtrar clientes

​Consultar pelo identificador

​Remover um cliente

​Campos retornados

Criar um cliente

Campos da requisição

Listar clientes

Filtrar clientes

Consultar pelo identificador

Remover um cliente

Campos retornados