Atualizar um cliente

Visão Geral

Este endpoint permite atualizar informações de um cliente existente, oferecendo a capacidade de modificar os dados pessoais, documentos, informações de contato e endereços. É especialmente útil para manter registros atualizados, corrigir informações incorretas e complementar dados parcialmente fornecidos anteriormente.

Precauções

ATENÇÃO! Por favor, leia estas informações importantes antes de usar este endpoint.

• Dados Sensíveis: As informações de clientes são consideradas dados sensíveis e devem ser tratadas conforme as regulamentações de proteção de dados (LGPD/GDPR).
• ID do Cliente: Certifique-se de fornecer o ID correto do cliente para evitar atualizações em registros errados.
• Atualização Parcial (PATCH): Este endpoint usa o método PATCH e aceita atualizações parciais. Todos os campos do corpo são opcionais — envie apenas os campos que deseja alterar; os campos omitidos permanecem inalterados.

Descrição

O endpoint Atualizar Cliente permite modificar as informações de um cliente existente a partir de seu ID único. Como é uma atualização parcial, envie apenas os campos a alterar.

Requisição

PATCH /v1/customers/{customerId}

O método deste endpoint é PATCH. (O link update no bloco _links das respostas anuncia PUT por convenção do HATEOAS, mas a rota efetiva é PATCH.)

Parâmetros de Caminho (Path)

Corpo da Requisição (Body)

{
  "lastName": "Silva Santos",
  "telephone": {
    "countryCode": "55",
    "areaCode": "11",
    "number": "987654321",
    "line": "11987654321"
  },
  "metadata": {
    "source": "website",
    "category": "premium",
    "lastPurchase": "2023-06-15"
  },
  "externalReference": "CUSTOMER_ID_12345",
  "additionalEmails": [
    "[email protected]",
    "[email protected]"
  ]
}

Endereços não fazem parte do corpo do cliente — gerencie endereços pelo recurso Endereços.

Atributos do Corpo da Requisição

Todos os campos são opcionais (atualização parcial). As mesmas regras de validação do Criar Cliente aplicam-se a cada campo enviado.

Resposta - 200 OK

Se a requisição for bem-sucedida, o servidor retornará um código de status HTTP 200 OK e os detalhes atualizados do cliente.

Exemplo de Resposta

{
  "id": "cus_01hqzvabc",
  "firstName": "João",
  "lastName": "Silva Santos",
  "email": "[email protected]",
  "document": {
    "type": "cpf",
    "number": "12345678900"
  },
  "telephone": {
    "countryCode": "55",
    "areaCode": "11",
    "number": "987654321",
    "line": "11987654321"
  },
  "birthdate": "1990-01-01",
  "gender": "male",
  "available": true,
  "delinquent": false,
  "externalReference": "CUSTOMER_ID_12345",
  "additionalEmails": [
    "[email protected]"
  ],
  "metadata": {
    "source": "website"
  },
  "createdAt": "2026-04-12T17:56:33.000Z",
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/customers/cus_01hqzvabc",
      "method": "GET",
      "description": "Read a customer."
    },
    "create": {
      "href": "https://api.selectwin.io/v1/customers",
      "method": "POST",
      "description": "Create a new customer."
    },
    "update": {
      "href": "https://api.selectwin.io/v1/customers/cus_01hqzvabc",
      "method": "PUT",
      "description": "Update the customer."
    },
    "delete": {
      "href": "https://api.selectwin.io/v1/customers/cus_01hqzvabc",
      "method": "DELETE",
      "description": "Delete the customer."
    },
    "list": {
      "href": "https://api.selectwin.io/v1/customers",
      "method": "GET",
      "description": "List all customers."
    }
  }
}

Atributos da Resposta

Update retorna o objeto base do cliente (mesmo shape do create, sem os embeds transactions/subscriptions/addresses/cards) + merchant + _links.

Respostas de Erro

400 Bad Request

Ocorre quando a requisição contém dados inválidos ou está mal formatada.

{
  "error": {
    "status": "Bad Request",
    "statusCode": 400,
    "category": "validation",
    "message": "Validation errors occurred.",
    "params": [
      {
        "firstName": "The firstName field must be between 2 and 255 characters."
      }
    ]
  }
}

404 Not Found

Ocorre quando o customerId não existe ou não pertence à sua conta (customerNotFound).

{
  "error": {
    "status": "Not Found",
    "statusCode": 404,
    "category": "resource",
    "message": "Customer not found."
  }
}

Casos de Uso

1. Atualização de Perfil: Permitir que clientes atualizem suas informações pessoais
2. Correção de Informações: Corrigir dados incorretos ou desatualizados
3. Enriquecimento de Dados: Adicionar informações complementares ao perfil do cliente
4. Mudança de Endereço: Atualizar informações de endereçamento quando o cliente se muda

Melhores Práticas

1. Consultar Antes de Atualizar: Use o endpoint Consultar Cliente para obter os dados atuais antes de enviar atualizações
2. Validar Dados: Implemente validações do lado do cliente para todos os campos antes de enviar a requisição
3. Manter Consistência: Tenha cuidado ao atualizar documentos, pois podem estar vinculados a outras operações
4. Informar Mudanças: Notifique o cliente sobre alterações importantes em seus dados, como e-mail ou telefone

Integração com Outros Endpoints

• Use Consultar Cliente para verificar os dados do cliente antes e após a atualização
• Use Criar Endereço para adicionar endereços secundários ao cliente
• Veja Endereços para gerenciar os endereços associados ao cliente