A entidade clientes permite incluir, alterar e excluir clientes no Mercos.
Nessa entidade, também é possível realizar a configuração específica sobre as exceções fiscais das configurações de ICMS-ST definas pela integração 🔗, ou manualmente no sistema Mercos.
Filtro disponível
Você pode aplicar o seguinte filtro na consulta GET:
- excluido:
- 0 ou false = Não excluído
- 1 ou true = Excluído
Exemplo: ?excluido=false
Estrutura de Retorno (GET)
| Campo | Tipo | Descrição |
|---|---|---|
| id | Integer | Identificador único |
| razao_social | String: 100 | Razão social para pessoa jurídica. Nome do cliente para pessoa física. |
| nome_fantasia | String: 100 | Nome fantasia (pessoa jurídica) / Apelido (pessoa física). |
| tipo | String: 1 | J para pessoa jurídica, F para pessoa física. |
| cnpj | String: 18 | CNPJ para pessoa jurídica, CPF para pessoa física. Apenas números, sem pontuação. |
| inscricao_estadual | String: 30 | Identificação da inscrição estadual do cliente. |
| suframa | String: 20 | Código Suframa para clientes da Zona Franca de Manaus. Caso seja informado, todos os pedidos deste cliente terão IPI zerado (isento). |
| rua | String: 100 | Rua do endereço do cliente |
| numero | String: 100 | Número do endereço do cliente |
| complemento | String: 50 | Informações adicinais do endereço do cliente. |
| cep | String: 9 | Pode ser informado com ou sem hífen. |
| bairro | String: 30 | Bairro do cliente |
| cidade | String: 50 | Cidade do cliente |
| estado | String: 2 | Sigla do Estado. |
| observacao | String: 500 | Utilize para guardar quaisquer informações que não tenham campos específicos. |
| emails | List | Lista de objetos Email com os emails do cliente. - e-mail (String: 75) |
| telefones | List | Lista de objetos Telefone com os telefones do cliente. - numero (String: 30) |
| contatos | List | Lista de objetos Contato com os contatos do cliente. - nome (String: 50) - cargo (String: 30) - excluido (Boolean) - emails (List) - telefones (List) |
| nome_excecao_fiscal | String: 20 | Exceção fiscal que identifica o(s) cliente(s) sujeito(s) a esta configuração de ICMS-ST. Ex: “SIMPLES”. |
| criador_id | Integer | Identificador do criador do cliente. Este campo foi introduzido em 2021, registros antigos podem não retornar criador. |
| segmento_id | Integer | Identificador do segmento do cliente para diferenciação em relatórios e políticas comerciais. Ex: 123. |
| rede_id | Integer | Identificador da rede do cliente para diferenciação em relatórios. Ex: 456. |
| bloqueado_b2b | Boolean | Indica se o cliente possui bloqueio de acesso ao E-commerce B2B. |
| excluido | Boolean | Indica se o cliente está excluído. |
| bloqueado | Boolean | Indica se o cliente está bloqueado. |
| motivo_bloqueio_id | Integer | Identificador único do motivo de bloqueio do cliente. |
| enderecos_adicionais | List | Lista de objetos EnderecoAdicional do cliente. - cep (String: 9) Pode ser informado com ou sem hífen. - endereco (String: 200) - numero (String: 100) - complemento (String: 200) - bairro (String: 200) - cidade (String: 200) - estado (String: 2) |
| limite_credito | List | Lista de objetos LimiteCreditoCliente, cada elemento da lista é um objeto no formato: {"limite_disponivel": Float, "limite_total": Float} |
| tags | List | Lista de IDs das tags vinculadas ao cliente. Ex: [1, 5, 12]. |
| ultima_alteracao | DateTime | Data e hora da última modificação deste cliente no Mercos. |
Parâmetros do JSON de envio de Cliente (POST)
Os campos obrigatórios por padrão são: Razão Social e Tipo. Caso o cliente selecione mais campos para serem obrigatórios no cadastro do cliente, por dentro do sistema, os mesmos também devem ser enviados no JSON.
| Campo | Tipo | Descrição |
|---|---|---|
| razao_social (obrigatório) | String: 100 | Razão social para pessoa jurídica. Nome do cliente para pessoa física. |
| nome_fantasia | String: 100 | Nome fantasia (pessoa jurídica) / Apelido (pessoa física). |
| tipo (obrigatório) | String: 1 | J para pessoa jurídica, F para pessoa física. |
| cnpj | String: 18 | CNPJ para pessoa jurídica, CPF para pessoa física. Apenas números, sem pontuação. |
| inscricao_estadual | String: 30 | Identificação da inscrição estadual do cliente. |
| suframa | String: 20 | Código Suframa para clientes da Zona Franca de Manaus. Caso seja informado, todos os pedidos deste cliente terão IPI zerado (isento). |
| rua | String: 100 | Rua do endereço do cliente |
| numero | String: 100 | Número do endereço do cliente |
| complemento | String: 50 | Informações adicinais do endereço do cliente. |
| cep | String: 9 | Pode ser informado com ou sem hífen. |
| bairro | String: 30 | Bairro do cliente |
| cidade | String: 50 | Cidade do cliente |
| estado | String: 2 | Sigla do Estado. |
| observacao | String: 500 | Utilize para guardar quaisquer informações que não tenham campos específicos. |
| emails | List | Lista de objetos Email com os emails do cliente. - e-mail (String: 75) |
| telefones | List | Lista de objetos Telefone com os telefones do cliente. - numero (String: 30) |
| contatos | List | Lista de objetos Contato com os contatos do cliente. - nome (String: 50) - cargo (String: 30) - excluido (Boolean) - emails (List) - telefones (List) |
| nome_excecao_fiscal | String: 20 | Exceção fiscal que identifica o(s) cliente(s) sujeito(s) a esta configuração de ICMS-ST. Ex: “SIMPLES”. |
| segmento_id | Integer | Identificador do segmento do cliente para diferenciação em relatórios e políticas comerciais. Ex: 123. |
| rede_id | Integer | Identificador da rede do cliente para diferenciação em relatórios. Ex: 456. |
| bloqueado_b2b | Boolean | Indica se o cliente possui bloqueio de acesso ao E-commerce B2B. |
| bloqueado | Boolean | Indica se o cliente está bloqueado. (Ao desbloquear um cliente, motivo_bloqueio_id será alterado para null) |
| motivo_bloqueio_id | Integer | Identificador único do motivo de bloqueio do cliente. (Obrigatório bloqueado=true ao passar um ID neste campo) |
| enderecos_adicionais | List | Lista de objetos EnderecoAdicional do cliente. - cep (String: 9) Pode ser informado com ou sem hífen. - endereco (String: 200) - numero (String: 100) - complemento (String: 200) - bairro (String: 200) - cidade (String: 200) - estado (String: 2) |
| limite_credito_disponivel | Float | Valor do limite de crédito disponível para o cliente |
| limite_credito_total | Float | Valor do limite de crédito total do cliente |
| extras | List | Lista de campos extras do cliente |
Estrutura de Retorno de Campos extras do cliente
| Campo | Tipo | Descrição |
|---|---|---|
| campo_extra_id | Integer | Identificador único do campo extra. |
| nome | String | Nome do campo extra. |
| tipo | String | (“0”) Texto , (“1”) Data, ("2") Numérico, ("3") Lista, ("4") Arquivo |
| valor_texto | String | Retorna um texto se o campo for do tipo texto. |
| valor_data | String | Retorna uma data se o campo for do tipo data. |
| valor_decimal | Double | Retorna um Double se o campo for do tipo numérico. |
| nome_arquivo | String | Retorna o nome do arquivo se o campo for do tipo arquivo. |
| valor_arquivo | String | Retorna o valor do arquivo se o campo for do tipo arquivo. |
| valor_lista | List | Retorna uma lista de ids e valores dos itens da lista, ex: [[1, "sp"], [2, "sc"]]. |
| valor | String | O tipo deste atributo depende do tipo do campo extra como descrito na tabela abaixo. |
Tipos dos Campos extras do cliente
| Tipo do campo extra | Tipo | Formato |
|---|---|---|
| Texto("0") | String | Máximo de 100 caracteres. |
| Data("1") | String | "yyyy-dd-mm", ex: "2018-21-02". |
| Numérico("2") | Double | Valor máximo: 99999999.99999. |
| Lista("3") | List | Retorna uma lista de ids e valores dos itens da lista, ex: [[1, "sp"], [2, "sc"]]. |
| Arquivo("4") | String | Retorna a url do arquivo. |
Estrutura de Envio de Campos extras do cliente
Importante: Diferentemente do endpoint de pedidos, campos que não tiverem preenchimentos recebidos dentro da chave "extras" não serão atualizados nem excluídos.
| Campo | Tipo | Descrição |
|---|---|---|
| campo_id | Integer | Identificador único do campo extra. |
| valor | O tipo deste atributo depende do tipo do campo extra como descrito na tabela abaixo. |
Tipos dos Campos extras do cliente
| Tipo do campo extra | Tipo | Formato |
|---|---|---|
| Texto("0") | String: 50 | Texto simples |
| Data("1") | String: 10 | "yyyy-dd-mm", ex: "2018-21-02" |
| Numérico("2") | Double: 18 | Valor máximo: 99999999.99999. OBS: Devem ser respeitadas a quantidade de casas decimais, valores suportados de 0 a 5. |
| Lista("3") | List[int] | Lista de ids dos itens selecionados, se atributo lista_multipla for verdadeiro pode ser enviado mais de 1 id na lista. |
| Arquivo("4") | Object | {"nome_arquivo": "arquivo_teste.pdf", "arquivo_base64": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMgMCBSL0Zp"} |
Contatos Adicionais para Clientes
Cada contato adicional associado ao cadastro do cliente, contém uma Lista de objetos.
Na alteração do cliente (PUT), caso não sejam referenciados os ids nos campos de telefone, email e enderecos_adicionais, o sistema Mercos irá respeitar sempre as informações dos registros que forem mencionados no JSON. Já para contatos, existe a exclusão através do campo excluido igual a True ou False.
Um detalhe importante é que para o campo de contatos é possível adicionar mais de um email e telefone, que se obtém o mesmo comportamento dos campos de telefone, email e enderecos_adicionais. Por exemplo:
[...]
"contatos": [
{
"nome": "Nome do Contato",
"cargo": "Comercial",
"emails": [
{
"email": "[email protected]"
},
{
"email": "[email protected]"
}
],
"telefones": [
{
"numero": "4730303030"
},
{
"numero": "4799999999"
}
]
}
]
[...]