Cadastrar cliente
Cadastra um cliente sem abrir assinatura, para usar depois em customerId. Recusa duplicatas com 409.
apiKeyAuthorizationBearer <token>Chave de API da conta: Authorization: Bearer <chave de API>.
application/json- body
Dados do cliente. Exige name e pelo menos um entre email e phone.
O que mais é necessário depende do meio de pagamento: veja as regras de
Criar assinatura.
name*stringNome do cliente.
1 <= length <= 150email?stringE-mail. Obrigatório se phone não vier.
emaillength <= 255phone?stringTelefone com DDI e DDD. A pontuação é removida. Obrigatório se email não vier.
length <= 32taxID?stringCPF (11 dígitos) ou CNPJ (14), com ou sem pontuação. Tudo que não é
dígito é removido: um texto sem dígitos é gravado como null.
length <= 20address?Endereço do cliente. Todos os campos são opcionais no formato, mas o Pix
Automático exige o endereço completo (todos, menos complement).
Cliente cadastrado.
application/json- response
Cliente da conta. taxID, email e phone vêm mascarados; o endereço
vem em campos separados (addressZipcode, addressStreet…).
id?stringId do cliente (ULID). É o valor de customerId em Criar assinatura.
name?stringtaxID?|CPF/CNPJ mascarado (três primeiros e dois últimos dígitos).
email?|E-mail mascarado (dois primeiros caracteres e domínio).
phone?|Telefone mascarado (dois primeiros e dois últimos dígitos).
addressZipcode?string|nulladdressStreet?string|nulladdressNumber?string|nulladdressNeighborhood?string|nulladdressCity?string|nulladdressState?string|nulladdressComplement?string|nulladdressCountry?string|nullstatus?CustomerStatusACTIVE ou BLOCKED (bloqueado por você).
"ACTIVE""BLOCKED"customerIdentityId?|Preenchido quando o cliente cria acesso ao portal do assinante. null até lá.
invitedAt?|Quando o convite foi emitido (modo B).
date-timeactivatedAt?|Quando o cadastro ficou completo. No modo A, na criação.
date-timecreatedAt?stringdate-timeupdatedAt?stringdate-timemode?stringA: cadastro completo (nome, documento, e-mail, telefone e
endereço). B: falta algum desses dados e um convite foi emitido.
"A""B"invite?|Convite do modo B. null no modo A.
curl -X POST 'https://api.gates2b.com/customer' \ -H 'Content-Type: application/json' \ -d '{ "name": "João da Silva", "taxID": "12345678909", "email": "cliente@example.com", "phone": "5511999999999", "address": { "zipcode": "01310100", "street": "Avenida Paulista", "number": "1000", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BR" }}'{ "id": "01JB7Z1A2B3C4D5E6F7G8H9J0K", "name": "João da Silva", "taxID": "123******09", "email": "cl*****@example.com", "phone": "55*******99", "addressZipcode": "01310100", "addressStreet": "Avenida Paulista", "addressNumber": "1000", "addressNeighborhood": "Bela Vista", "addressCity": "São Paulo", "addressState": "SP", "addressComplement": null, "addressCountry": "BR", "status": "ACTIVE", "customerIdentityId": null, "invitedAt": null, "activatedAt": "2026-05-28T12:58:00.000Z", "createdAt": "2026-05-28T12:58:00.000Z", "updatedAt": "2026-05-28T12:58:00.000Z", "mode": "A", "invite": null}Como funciona
Cadastre o cliente antes quando ele vai ter mais de uma assinatura, ou quando
você quer validar os dados antes de abrir o contrato. Depois, crie as
assinaturas com customerId.
Se faltar algum dado que o Pix Automático exige, o cliente recebe um convite para completar o cadastro:
- VocêCadastro incompletoResposta com mode B e invite.url.
- VocêRepasse o conviteValidade em invite.expiresInSeconds (padrão de 72 h).
- ClienteCliente completa os dadosDocumento, telefone e endereço.
- Autorização liberadaAssinaturas Pix em PENDING_CUSTOMER vão para AWAITING_PAYER_AUTHORIZATION.
Regras
- Obrigatórios:
namee pelo menos um entreemailephone. Sem os dois, a resposta é400. - Não exige a verificação da conta (KYC/KYB): cadastrar cliente não gera cobrança.
- O mesmo cadastro pode nascer dentro de
Criar assinatura, no campo
customer, com a mesma validação. A diferença: lá um cliente novo é sempre criado; aqui a duplicata é recusada.
Modo A e modo B
O payload decide o modo; não há campo para escolher.
- Modo A:
name,taxID,email,phonee endereço completo (menoscomplement).invitevoltanull. - Modo B: falta algum desses dados. A resposta traz
invite.url, um link para o cliente completar o cadastro, válido porinvite.expiresInSeconds. Repasse o link ao cliente, principalmente se ele não tem e-mail.
O modo descreve o cadastro, não o que a assinatura vai exigir. Um cliente em modo B com nome e e-mail já serve para um plano de cartão. Só o plano Pix precisa do cadastro completo.
Duplicata
- Um cliente da conta com o mesmo e-mail ou telefone responde
409comcode: CUSTOMER_ALREADY_EXISTS. Cliente bloqueado também conta. - E-mail é comparado sem diferenciar maiúsculas; telefone, só pelos dígitos.
- A resposta não traz o id do cliente existente. Encontre-o em
Listar clientes com o filtro
emailouphonee use-o emcustomerId. Se ele estiver bloqueado, desbloqueie em vez de cadastrar de novo.