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
Passo a passo
1. Criar um cliente
201:
2. Usar o cliente numa cobrança
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:
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 buscar um cliente específico, use GET /v1/customers/{id}:
cURL
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
200 traz o cadastro do cliente, no mesmo formato da consulta.
5. Excluir um cliente
cURL
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:- Guarde o
idda Finvia no cadastro do comprador no seu sistema e use sempre esseidquando ele existir. - Procure antes de criar. Se o seu sistema não tem o
id, consulteGET /v1/customers?email=...ou?documentId=.... Crie só se a busca vier vazia. - 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. - Use o objeto
customercom cuidado. Na cobrança e na assinatura, o objetocustomercria 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.
Erros comuns
Perguntas frequentes
Preciso cadastrar o cliente antes de cobrar?
Preciso cadastrar o cliente antes de cobrar?
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.Posso corrigir um CPF digitado errado?
Posso corrigir um CPF digitado errado?
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.Posso cadastrar cliente estrangeiro?
Posso cadastrar cliente estrangeiro?
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 API impede a criação de dois clientes com o mesmo e-mail?
A API impede a criação de dois clientes com o mesmo e-mail?
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.Excluir o cliente apaga as cobranças dele?
Excluir o cliente apaga as cobranças dele?
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.

