Clientes e CPF
Por que o cadastro do cliente é obrigatório e como o CPF protege a ativação.
Todo pedido é vinculado a um cliente cadastrado na agência. O cadastro não é burocracia: ele cumpre dois papéis concretos no fluxo de emissão.
1. É o canal da emissão
O eSIM é ativado por um link enviado ao cliente. Os dados de contato do cadastro definem por onde esse link chega:
- E-mail (
email) — canal principal do link de ativação. - Telefone (
phone, formato E.164) — usado para o envio via WhatsApp.
Sem um canal válido, o cliente não recebe o link. Você sempre pode enviar o link
por conta própria usando o activationUrl retornado no pedido, mas o cadastro é
o que permite o envio automático pela plataforma.
2. O CPF é a trava de segurança na ativação
A página de ativação é pública (qualquer pessoa com o link a acessa). Para proteger a emissão, a plataforma exige que o cliente confirme os 5 primeiros dígitos do CPF cadastrado antes de revelar os dados do eSIM ou ativá-lo.
Se os 5 dígitos não conferirem com o CPF do cadastro, a ativação é recusada
(CPF incorreto) e nenhum dado do eSIM é exposto. Por isso o CPF precisa estar
correto no cadastro — é ele que autentica o cliente na hora de emitir.
Regras do cadastro
| Campo | Regra |
|---|---|
fullName | Obrigatório. |
document (CPF) | Obrigatório, validado, único por agência. Com ou sem máscara. |
email | Opcional, mas necessário para o envio do link por e-mail. |
phone | Opcional, E.164 (ex.: +5511999998888), necessário para o WhatsApp. |
Como o CPF é único por agência, tentar cadastrar um CPF que já existe retorna
409 Conflict. Nesse caso, reutilize o cliente existente: busque por
GET /v1/agencies/{agencyId}/customers?document=... e use o id retornado no
pedido.
Fluxo recomendado antes de criar um pedido: busque o cliente por CPF; se não
existir, cadastre; então use o id no pedido.
Atualizando o contato do cliente
Se o cliente trocar de e-mail ou telefone, atualize o cadastro para que
o link de ativação chegue no canal certo. Use
PATCH /v1/agencies/{agencyId}/customers/{id} enviando apenas os campos que
mudaram:
curl -X PATCH https://api.esimdeviagem.com.br/v1/agencies/{agencyId}/customers/{id} \
-H "Authorization: Bearer ong_sk_..." \
-H "Content-Type: application/json" \
-d '{ "email": "novo@exemplo.com", "phone": "+5511988887777" }'Dá para atualizar fullName, email e phone. Envie null em email ou
phone para limpar o canal.
O CPF não é editável pela API — ele é a trava de segurança da ativação e é único por agência. Se o CPF estiver errado, cadastre um novo cliente.