Skip to main content
O cadastro de clientes guarda os dados de quem compra de você: nome, e-mail, documento e telefone. Com o cliente cadastrado, cobranças, cartões salvos e assinaturas passam a apontar para o mesmo registro, o que facilita localizar o histórico de um comprador e evita digitar os mesmos dados a cada venda.
Para o negócio: um cadastro único por comprador é o que permite oferecer recompra com cartão salvo e assinaturas, e também facilita o atendimento: com o e-mail ou o CPF do cliente, o seu time encontra o cadastro. Para operações de venda avulsa, o cadastro prévio é opcional, porque a própria cobrança pode criar o cliente.

Quando usar

Como funciona

O desenho abaixo mostra como o cadastro do cliente se liga às cobranças, aos cartões salvos e às assinaturas.
1

Crie o cliente

POST /v1/customers com nome, e-mail e documento. A resposta traz o id.
2

Guarde o id

Grave o id no cadastro do comprador no seu sistema.
3

Use o id nas operações

Em cobranças, envie customer.id. Em cartões, customerId. Em assinaturas, customerId.
4

Mantenha o cadastro atualizado

Atualize nome, e-mail e telefone com PUT /v1/customers/{id} quando o comprador alterar os dados.

Criar o cliente antes ou na cobrança

Há dois caminhos, e eles podem conviver na mesma integração.
Quando a cobrança recebe customer.id, os outros campos de customer ficam opcionais e o cadastro existente é usado como está. Os dados enviados junto não atualizam o cadastro. Para mudar nome, e-mail ou telefone, use PUT /v1/customers/{id}.

Regras de negócio

Se o cliente vai ter cartão salvo ou assinatura, cadastre com CPF ou CNPJ e e-mail desde o início. Sem isso, o cadastro do cartão responde 400 com Failed to register card: O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador. Como o documento não pode ser alterado, um cliente criado com outro documento (passaporte, RG) não serve para esses fluxos, e será preciso criar outro cadastro.

Passo a passo

1. Criar um cliente

Resposta 201:

2. Usar o cliente numa cobrança

A alternativa sem cadastro prévio é enviar os dados no próprio customer:

3. Buscar e listar clientes

GET /v1/customers devolve uma lista paginada, dos clientes mais recentes para os mais antigos, e aceita estes filtros:
A resposta 200 usa o envelope plano das listagens da API: { data, total, page, size, pages }. Para percorrer todos os clientes, avance page até chegar a pages. Os campos de cada cliente em data serão publicados na referência da rota quando o time técnico liberar o formato final.
Para o desenvolvedor: o tamanho da página vai em size. Um limit na URL é ignorado sem erro, e a página continua com 10 itens.
Para buscar um cliente específico, use GET /v1/customers/{id}:
cURL
A resposta 200 traz o cadastro do cliente. Os campos estão descritos em Consultar cliente.

4. Atualizar um cliente

PUT /v1/customers/{id} altera nome, e-mail e telefone. Todos os campos são opcionais: envie só o que mudou. O documento (documentId e documentType) não pode ser alterado.
cURL
A resposta 200 traz o cadastro do cliente, no mesmo formato da consulta.

5. Excluir um cliente

cURL
A exclusão é lógica (soft delete): o cliente é marcado como removido. A resposta é 204, sem corpo.
A documentação não detalha o efeito da exclusão do cliente sobre cartões salvos e assinaturas já existentes. Antes de excluir um cliente com assinatura ativa, cancele a assinatura e exclua os cartões pelas rotas próprias.

Boas práticas para evitar duplicidade

Clientes duplicados dificultam o atendimento e espalham o histórico de um comprador em vários registros. Algumas práticas ajudam:
  1. Guarde o id da Finvia no cadastro do comprador no seu sistema e use sempre esse id quando ele existir.
  2. Procure antes de criar. Se o seu sistema não tem o id, consulte GET /v1/customers?email=... ou ?documentId=.... Crie só se a busca vier vazia.
  3. Padronize os dados. Envie o documento só com números (52998224725) e o e-mail em minúsculas, para que as buscas exatas encontrem o registro.
  4. Use o objeto customer com cuidado. Na cobrança e na assinatura, o objeto customer cria ou localiza o cliente (na assinatura, a busca é pelo e-mail). Se o mesmo comprador usar e-mails diferentes, podem surgir dois cadastros. Na assinatura, quando já existe um cliente com o mesmo e-mail, vale o documento desse cadastro, e não o enviado na requisição.
O desenho abaixo resume essas práticas em uma sequência de decisões.

Erros comuns

Perguntas frequentes

Não. A cobrança aceita o objeto customer com name e email (ou phone) e cria ou localiza o cliente. O cadastro prévio é necessário para salvar cartão e recomendado para recompra e assinaturas.
Não. O documento não pode ser alterado depois da criação. Crie um novo cadastro com o documento correto e passe a usar o novo id (em assinaturas, envie customerId). Se você enviar o objeto customer com o mesmo e-mail do cadastro antigo, a assinatura usa o documento do cadastro antigo.
Cartão salvo e assinaturas exigem CPF ou CNPJ: o tipo é deduzido pela quantidade de dígitos do documento, e um passaporte conta como cliente sem documento. Para vendas avulsas, a cobrança pode ser feita com os dados do cliente na própria requisição.
A documentação não informa se há bloqueio de duplicidade em POST /v1/customers. Procure o cliente antes de criar, como mostrado em Boas práticas.
A exclusão é lógica (soft delete). A documentação não descreve o efeito sobre as cobranças já feitas para esse cliente.

Como testar

O cadastro de clientes funciona com a chave de teste (sk_test_). Crie, atualize e exclua um cliente no sandbox antes de ir para produção. O cadastro de cartão e as assinaturas não têm modo de teste: veja Cofre de cartões.

Veja também

Cofre de cartões

Salve cartões vinculados ao cliente.

Assinaturas

Cobrança recorrente a partir do cliente cadastrado.

Criar cliente

Contrato completo da rota.

Listar clientes

Filtros e paginação.