Clientes em Lote

A entidade Clientes em Lote permite alterar e excluir múltiplos Clientes 🔗 de uma só vez no Mercos.

Este endpoint é uma forma de otimizar o tempo de resposta da API e as operações de sincronização da ferramenta integrada, pois permite que uma única requisição atualize ou exclua vários clientes. Alterações e exclusões podem ser misturadas no mesmo lote.

Parâmetros de Envio - Alterar (POST)

Esse endpoint requer um JSON com Lista de objetos no Body, em que cada objeto representa um cliente. Somente os campos enviados são alterados: os campos ausentes permanecem com o valor atual do cliente.

O comportamento das listas (emails, telefones, contatos e enderecos_adicionais) e dos campos extras é o mesmo do endpoint individual, descrito na entidade Clientes 🔗.

Parâmetros de Envio - Excluir (POST)

Para excluir um cliente, envie o id com o campo excluido igual a true.

Exemplo de envio misturando alteração e exclusão:

[
  {
    "id": 1234,
    "razao_social": "Mercearia Boa Vista LTDA",
    "emails": [
      {
        "email": "[email protected]"
      }
    ]
  },
  {
    "id": 1235,
    "bloqueado": true,
    "motivo_bloqueio_id": 42
  },
  {
    "id": 1236,
    "excluido": true
  }
]

Estrutura da Resposta (POST)

Sucesso

Caso a requisição seja um sucesso, a resposta terá status 200 e retornará no body a lista dos clientes processados, na mesma ordem em que foram enviados, com os seguintes campos:

Erro

Caso a requisição encontre um ou mais erros, a resposta terá status 422 e informará o índice do item no lote, o campo e o tipo de erro:

{
  "mensagem": "Ocorreram erros de validação",
  "erros": [
    ["clientes[0].id", "O cliente não existe."],
    ["clientes[1].limite_credito_disponivel", "O limite disponível precisa ser menor ou igual ao limite total."]
  ]
}

Principais validações do lote:

Quando a conta possui campos obrigatórios adicionais no cadastro do cliente, enviá-los vazios também retorna erro: Este campo é obrigatório. para campos simples e No mínimo 1 telefone é requerido / No mínimo 1 e-mail é requerido para as listas.

Diferenças em relação ao endpoint de Clientes

• Este endpoint não cria clientes: para incluir um novo cadastro utilize POST /v1/clientes.
• O campo id é obrigatório em todos os itens, e o mesmo cliente não pode aparecer duas vezes na mesma requisição.
• A exclusão é feita pelo próprio item do lote, com excluido igual a true.
• A resposta traz apenas os dados cadastrais do cliente, além de excluido e ultima_alteracao. Os campos emails, telefones, contatos, enderecos_adicionais, limite_credito, tags e criador_id não são retornados.