Skip to main content
POST
Esta rota cadastra um cliente (objeto customer), a pessoa ou empresa que paga. O cadastro devolve um id que você guarda no seu sistema e reutiliza: para registrar o cartão no cofre, para criar uma assinatura ou para cobrar sem reenviar os dados pessoais a cada venda.

Quando usar

Antes de chamar

  • Tenha uma chave secreta (sk_) válida. A chave herda as permissões do usuário que a gerou, e esta rota devolve 403 quando a chave não tem permissão (Credenciais e ambientes).
  • Confira se o cliente já existe com Listar clientes filtrando por email ou documentId, para não duplicar o cadastro.
  • Se o cliente vai ter cartão salvo ou assinatura, colete e-mail e CPF ou CNPJ. Sem esses dois dados, o cartão não pode ser salvo.
O documento não pode ser alterado depois: Atualizar cliente muda só nome, e-mail e telefone. Para registrar cartão (em POST /v1/cards ou no cartão enviado direto em POST /v1/subscriptions), o cliente precisa ter e-mail e CPF ou CNPJ. O tipo é deduzido pela quantidade de dígitos de documentId: 11 dígitos é CPF e 14 é CNPJ. Qualquer outro documento (passaporte, RG) conta como cliente sem documento, e o cartão é recusado com 400.

Corpo da requisição

Campos obrigatórios: name, email, documentId e documentType.
string
required
Nome completo do cliente. Ex.: Joao Silva.
string
required
E-mail do cliente (formato email). Ex.: [email protected].
string
required
Número do documento de identificação. Ex.: 52998224725 (CPF, 11 dígitos) ou 11222333000181 (CNPJ, 14 dígitos).
string
required
Tipo do documento. Use cpf ou cnpj. Para salvar cartão, o que conta é a quantidade de dígitos de documentId, e não o valor deste campo.
string
Telefone do cliente (opcional). Ex.: +5511987654321.
Para o desenvolvedor: envie o documentId como string, sem pontos, barras ou traços, como nos exemplos (52998224725). Guarde o id da resposta na tabela de usuários do seu sistema: ele é a chave para todas as operações seguintes com esse cliente.

Respostas

string
Identificador único do cliente criado. Ex.: 2RhQg9M7ZCg3X3nMb9W1kX8Q. Use em customerId ao registrar um cartão ou criar uma assinatura, e em customer.id ao criar uma cobrança.
A resposta traz só o id. Para ver o cadastro completo, use Consultar cliente.
Para o negócio: ter o cliente cadastrado com CPF ou CNPJ e e-mail é a condição para oferecer recompra com cartão salvo e cobrança recorrente. Se o seu produto tem assinatura, peça esses dados já no cadastro do site ou do aplicativo, assim o cliente não precisa preencher nada a mais no momento da contratação.

Erros comuns

Veja também

Guia de clientes

Quando cadastrar e como reaproveitar o cliente.

Registrar cartão

Próximo passo do fluxo cards-first.

Cofre de cartões

Como os cartões ficam guardados e são reutilizados.

Visão geral de assinaturas

Cliente, plano e cartão na cobrança recorrente.