Descrição

O webservice saveClientes permite cadastrar e atualizar dados de clientes na plataforma através de requisições HTTP POST em formato JSON.

Endpoint

POST https://suaurl.com.br/webservices/saveClientes

Autenticação

A chave de acesso (Token) deve ser enviada no cabeçalho da requisição.

Header	Valor
`token`	`[SEU_TOKEN_DE_ACESSO]`
`Content-Type`	`application/json`

Estrutura da Requisição

A requisição deve conter um objeto clientes com um array cliente contendo os dados dos clientes a serem cadastrados ou atualizados.

Formato JSON

json

{
    "clientes": {
        "cliente": [
            {
                // dados do cliente
            }
        ]
    }
}

Parâmetros da Requisição

Campos Obrigatórios

Campo	Tipo	Descrição	Exemplo
`cpf_cnpj`	string	CPF ou CNPJ do cliente	"123.456.789-00"
`email`	string	E-mail principal do cliente	"joao.silva@email.com"

⚠️ Importante: Se cpf_cnpj ou email não forem informados, o cliente será ignorado.

Campos de Controle

Campo	Tipo	Descrição	Exemplo
`atualiza`	boolean/string	Define se deve atualizar caso o cliente já exista. Valores: `true`, `false`, `"1"`, `"0"`	`true`

Campos Opcionais - Dados Pessoais

Campo	Tipo	Descrição	Exemplo
`contato`	string	Nome de contato	"João Silva"
`rg`	string	Número do RG	"12.345.678-9"
`data_nascimento`	string	Data de nascimento (formato: dd/mm/YYYY)	"15/03/1990"
`tipo_pessoa`	string	Tipo de pessoa: "fisica" ou "juridica"	"fisica"
`genero`	string	Gênero: "M" (masculino) ou "F" (feminino)	"M"

Campos Opcionais - Dados Fiscais

Campo	Tipo	Descrição	Exemplo
`inscricao_estadual`	string	Número da inscrição estadual	"123456789"
`inscricao_estadual_isento`	string	Isento de IE: "0" (não) ou "1" (sim)	"0"

Campos Opcionais - Endereço

Campo	Tipo	Descrição	Exemplo
`cep`	string	CEP do endereço	"90230-043"
`endereco`	string	Logradouro	"Rua das Flores"
`numero`	string	Número do endereço	"123"
`complemento`	string	Complemento do endereço	"Apto 45"
`instrucoes`	string	Instruções de entrega	"Deixar com o porteiro"
`bairro`	string	Bairro	"Centro"
`cidade`	string	Cidade	"Porto Alegre"
`estado`	string	UF (sigla do estado)	"RS"
`pais`	string	País	BRA

Campos Opcionais - Contato

Campo	Tipo	Descrição	Exemplo
`telefone_residencial`	string	Telefone residencial	"(83) 3333-4444"
`telefone_celular`	string	Telefone celular	"(83) 98888-7777"

Campos Opcionais - Configurações

Campo	Tipo	Descrição	Exemplo
`status`	string	Status do cliente: "0" (inativo) ou "1" (ativo)	"1"
`bloqueado`	string	Cliente bloqueado: "0" (não) ou "1" (sim)	"0"
`sms`	string	Aceita SMS: "0" (não) ou "1" (sim)	"1"
`newsletter`	string	Aceita newsletter: "0" (não) ou "1" (sim)	"1"

Campos Estendidos (Personalizados)

Campo	Tipo	Descrição
`cadastro_estendido`	object	Objeto contendo campos personalizados do cadastro estendido

Exemplos de Requisição

Exemplo 1: Cadastro Pessoa Física Completo

json

{
    "clientes": {
        "cliente": [
            {
                "cpf_cnpj": "123.456.789-00",
                "email": "joao.silva@email.com",
                "atualiza": true,
                "nome": "João da Silva",
                "contato": "João Silva",
                "rg": "12.345.678-9",
                "data_nascimento": "15/03/1990",
                "tipo_pessoa": "fisica",
                "genero": "M",
                "contribuinte": "0",
                "cep": "58400-000",
                "endereco": "Rua das Flores",
                "numero": "123",
                "complemento": "Apto 45",
                "instrucoes": "Deixar com o porteiro",
                "bairro": "Centro",
                "cidade": "Campina Grande",
                "pais": "Brasil",
                "estado": "PB",
                "telefone_residencial": "(83) 3333-4444",
                "telefone_celular": "(83) 98888-7777",
                "status": "1",
                "bloqueado": "0",
                "sms": "1",
                "newsletter": "1"
            }
        ]
    }
}

bash

curl -X POST 'https://suaurl.com.br/webservices/saveClientes' \
--header 'Content-Type: application/json' \
--header 'token: XXXXXXXXXXXX' \
--data '{
    "clientes": {
        "cliente": [
            {
                "cpf_cnpj": "123.456.789-00",
                "email": "joao.silva@email.com",
                "atualiza": true,
                "nome": "João da Silva",
                "contato": "João Silva",
                "rg": "12.345.678-9",
                "data_nascimento": "15/03/1990",
                "tipo_pessoa": "fisica",
                "genero": "M",
                "contribuinte": "0",
                "cep": "58400-000",
                "endereco": "Rua das Flores",
                "numero": "123",
                "complemento": "Apto 45",
                "instrucoes": "Deixar com o porteiro",
                "bairro": "Centro",
                "cidade": "Campina Grande",
                "pais": "Brasil",
                "estado": "PB",
                "telefone_residencial": "(83) 3333-4444",
                "telefone_celular": "(83) 98888-7777",
                "status": "1",
                "bloqueado": "0",
                "sms": "1",
                "newsletter": "1"
            }
        ]
    }
}'

Resposta da Requisição

Sucesso

json

{
    "status": "success",
    "message": "Cliente(s) cadastrado(s) com sucesso"
}

Erro de Autenticação

json

{
    "status": "error",
    "message": "Acesso não autorizado"
}

Erro de Validação

json

{
    "status": "error",
    "message": "Dados inválidos",
    "errors": [
        "O campo 'nome' é obrigatório",
        "O campo 'email' deve ser um e-mail válido"
    ]
}

Regras de Negócio

Atualização de Clientes

Se um cliente com o mesmo CPF/CNPJ ou e-mail já existir, os dados serão atualizados
Durante a atualização, os campos cpf_cnpj e email não são alterados
Para forçar um novo cadastro ao invés de atualização, altere o CPF/CNPJ ou e-mail

Conversão de Dados

tipo_pessoa: "fisica" é convertido para 0, "juridica" para 1
genero: "M" é convertido para 0 (masculino), "F" para 1 (feminino)
data_nascimento: Formato dd/mm/YYYY é convertido para YYYY-mm-dd
Campos nulos: Campos com valor null ou não informados são ignorados

Validações

CPF/CNPJ: Deve ser válido (com ou sem formatação)
E-mail: Deve ser um endereço de e-mail válido
CEP: Aceita formato com ou sem hífen (12345-678 ou 12345678)
Data de nascimento: Deve estar no formato dd/mm/YYYY

Códigos de Status HTTP

Código	Descrição
200	Requisição processada com sucesso
400	Erro de validação nos dados enviados
401	Falha na autenticação
500	Erro interno do servidor

Mais sobre Webservice

Consulte nossa tabela de retorno aqui.

Não conhece todos os métodos webservice da Moovin? Veja nossa lista completa aqui.

Caso tenha dúvidas em como realizar o envio ou formatos de envio, veja nesta nossa documentação aqui.

saveClientes - Webservice

Descrição

Endpoint

Autenticação

Estrutura da Requisição

Formato JSON

Parâmetros da Requisição

Campos Obrigatórios

Campos de Controle

Campos Opcionais - Dados Pessoais

Campos Opcionais - Dados Fiscais

Campos Opcionais - Endereço

Campos Opcionais - Contato

Campos Opcionais - Configurações

Campos Estendidos (Personalizados)

Exemplos de Requisição

Exemplo 1: Cadastro Pessoa Física Completo

Resposta da Requisição

Sucesso

Erro de Autenticação

Erro de Validação

Regras de Negócio

Atualização de Clientes

Conversão de Dados

Validações

Códigos de Status HTTP

Mais sobre Webservice