Editar um cliente do programa de fidelidade

Atualizar os dados cadastrais de um cliente já registrado no programa de fidelidade de um estabelecimento.

Envie apenas os campos que deseja alterar: qualquer campo omitido do payload mantém o valor que já está salvo no cadastro do cliente. Somente id_parceiro e id_cliente, que vão na URL, são obrigatórios.

bash

curl --location --request PATCH 'https://sandbox.fidelizii.com.br/api/v4/estabelecimentos/99999/clientes/4381641/editar' \
--header 'app-token: {{app-token}}' \
--header 'access-token: {{access-token}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
    "celular": "+5521988772222",
    "cpf": "52660023018",
    "nome": "Fulano Nepo",
    "email": "fulano_teste2@email.com",
    "data_nascimento": "1999-07-01",
    "genero": "M",
    "cep": "72006430",
    "endereco": "Rua 6, 251, Lote 35",
    "bairro": "Vicente Pires",
    "cidade": "Brasília",
    "estado": "DF"
}'

Na URL, deverá conter:

Parâmetro	Descrição	Exemplo
id_parceiro	ID do estabelecimento (Obrigatório)	99999
id_cliente	ID do cliente que será editado (Obrigatório)	4381641

No payload enviado, deverá conter:

Parâmetro	Descrição	Exemplo
nome	Nome completo do cliente (Opcional — máximo 200 caracteres, precisa conter ao menos um sobrenome; é salvo em maiúsculas)	Fulano Nepo
celular	Celular do cliente (Opcional — formato E.164, máximo 15 caracteres, não pode pertencer a outro cliente)	+5521988772222
cpf	CPF do cliente (Opcional — exatamente 11 dígitos, não pode pertencer a outro cliente)	52660023018
email	E-mail do cliente (Opcional — e-mail válido, máximo 200 caracteres)	fulano_teste2@email.com
data_nascimento	Data de nascimento (Opcional — formato `YYYY-MM-DD`, anterior a hoje e posterior a 1900-01-01)	1999-07-01
genero	Gênero do cliente (Opcional — `M`: Masculino, `F`: Feminino, `O`: Outro, `NA`: Não informado)	M
cep	CEP do cliente (Opcional — apenas números; obrigatório quando qualquer outro campo de localização for enviado)	72006430
endereco	Endereço do cliente (Opcional — máximo 100 caracteres, separado por `,` em rua, número e complemento; obrigatório quando qualquer outro campo de localização for enviado)	Rua 6, 251, Lote 35
bairro	Bairro do cliente (Opcional — máximo 50 caracteres; obrigatório quando qualquer outro campo de localização for enviado)	Vicente Pires
cidade	Cidade do cliente (Opcional — máximo 100 caracteres, precisa existir na base e pertencer ao estado enviado; obrigatório quando qualquer outro campo de localização for enviado)	Brasília
estado	Estado do cliente (Opcional — sigla UF de 2 caracteres, precisa existir na base; obrigatório quando qualquer outro campo de localização for enviado)	DF

Para não alterar um campo, omita a chave

Campos enviados como null ou como texto vazio ("") são recusados com 422 — eles não são interpretados como "não alterar" nem como "limpar o campo". Se você não quer mexer no email, por exemplo, simplesmente não envie a chave email no payload.

Localização é um bloco: os cinco campos vão juntos

cep, endereco, bairro, cidade e estado precisam ser enviados na mesma requisição. Enviar só um deles (ou quatro dos cinco) retorna 422 com a mensagem Os campos cep, endereco, bairro, cidade e estado devem ser enviados juntos na mesma requisição.

Endereço em partes

O valor de endereco é quebrado internamente pelo separador , em rua, número e complemento, nessa ordem. Enviar "Rua 6, 251, Lote 35" grava rua Rua 6, número 251 e complemento Lote 35.

Cidade depende do estado

A cidade é procurada dentro do estado enviado na requisição — que sempre acompanha a cidade, por causa do bloco de localização. Se a cidade não existir naquele estado, a requisição é recusada com 400.

O cliente precisa já estar no programa

Este endpoint edita apenas clientes já registrados no estabelecimento. Para clientes novos, use Cadastrar cliente.

No retorno deverá conter:

json

{
    "success": true,
    "message": "Cliente atualizado com sucesso.",
    "data": {
        "id_cliente": 4381641,
        "nome": "FULANO NEPO",
        "email": "fulano_teste2@email.com",
        "data_cadastro": "2025-01-01 00:00:00",
        "celular": "+5521988772222",
        "data_nascimento": "1999-07-01",
        "genero": "M",
        "cep": "72006430",
        "endereco": "Rua 6, 251, Lote 35",
        "bairro": "Vicente Pires",
        "cidade": "Brasília",
        "uf": "DF",
        "carteira": {
            "saldo": 0,
            "saldo_carencia": 0,
            "pontos_vencidos": [],
            "pontos_vencendo": []
        },
        "receita": 0,
        "compras": 0,
        "primeira_compra": null,
        "ultima_compra": null,
        "conquistados_premio_fidelidade": 0,
        "conquistados_brinde_roleta": 0,
        "conquistados_premio_surpresa": 0,
        "conquistados_premio_campanha": 0,
        "conquistados_premio_game": 0,
        "pendente_resgate_premio_fidelidade": 0,
        "pendente_resgate_brinde_roleta": 0,
        "pendente_resgate_premio_surpresa": 0,
        "pendente_resgate_premio_campanha": 0,
        "pendente_resgate_premio_game": 0,
        "resgatado_premio_fidelidade": 0,
        "resgatado_brinde_roleta": 0,
        "resgatado_premio_surpresa": 0,
        "resgatado_premio_campanha": 0,
        "resgatado_premio_game": 0,
        "expirado_premio_fidelidade": 0,
        "expirado_brinde_roleta": 0,
        "expirado_premio_surpresa": 0,
        "expirado_premio_campanha": 0,
        "expirado_premio_game": 0
    }
}

Respostas de erro

Status	Quando ocorre	Mensagem
401	Headers `app-token` / `access-token` ausentes ou inválidos	`51 - Acesso negado.`
400	`id_cliente` não existe	`Cliente não encontrado.`
400	Cliente existe, mas não está registrado neste estabelecimento	`Você não participa do programa de fidelidade deste estabelecimento.`
400	`estado` (UF) informado não existe na base	`Estado não encontrado.`
400	`cidade` não existe no estado enviado	`Cidade não encontrada.`
400	`cpf` com 11 dígitos, mas com dígitos verificadores inválidos	`CPF inválido.`
422	Falha de validação do payload (ver casos abaixo)	Primeiro erro encontrado, com o detalhamento em `errors`
429	Limite de 60 requisições por minuto excedido	`Too Many Attempts.`

Principais casos de validação (422):

qualquer campo enviado como null ou "" → O campo <campo> deve ter um valor.
bloco de localização incompleto → Os campos cep, endereco, bairro, cidade e estado devem ser enviados juntos na mesma requisição.
nome sem sobrenome → O campo nome deve conter pelo menos um sobrenome.
celular fora do padrão E.164 → O campo celular deve seguir o padrão E.164 (ex: +5519999999999).
celular já usado por outro cliente → erro de unicidade em celular
cpf com tamanho diferente de 11 dígitos → erro de tamanho em cpf
cpf já usado por outro cliente → erro de unicidade em cpf

Exemplo de erro de validação (422):

json

{
    "message": "O campo nome deve conter pelo menos um sobrenome.",
    "errors": {
        "nome": [
            "O campo nome deve conter pelo menos um sobrenome."
        ]
    }
}

Exemplo de erro de validação com o bloco de localização incompleto (422) — payload enviado apenas com cep:

json

{
    "message": "Os campos cep, endereco, bairro, cidade e estado devem ser enviados juntos na mesma requisição.",
    "errors": {
        "endereco": [
            "Os campos cep, endereco, bairro, cidade e estado devem ser enviados juntos na mesma requisição."
        ],
        "bairro": [
            "Os campos cep, endereco, bairro, cidade e estado devem ser enviados juntos na mesma requisição."
        ],
        "cidade": [
            "Os campos cep, endereco, bairro, cidade e estado devem ser enviados juntos na mesma requisição."
        ],
        "estado": [
            "Os campos cep, endereco, bairro, cidade e estado devem ser enviados juntos na mesma requisição."
        ]
    }
}

Exemplo de erro de regra de negócio (400):

json

{
    "message": "Cidade não encontrada.",
    "errors": {
        "cliente.cidade_not_found": [
            "Cidade não encontrada."
        ]
    }
}

Exemplo de erro de autenticação (401):

json

{
    "error": "51 - Acesso negado."
}

Editar um cliente do programa de fidelidade ​

Respostas de erro ​

Editar um cliente do programa de fidelidade

Respostas de erro