Atualizar um cliente

Atualize os dados de um cliente existente a partir do seu id. Use PUT quando quiser sobrescrever o conjunto de campos permitido de uma vez, ou PATCH quando quiser alterar apenas alguns campos sem reenviar o objeto inteiro. Útil para corrigir cadastros, enriquecer perfis e manter contato e documento sempre atualizados.

PUT /v1/customers/{customerId} · PATCH /v1/customers/{customerId}

Como funciona

A Selectwin expõe duas formas de atualizar um cliente, com o mesmo conjunto de campos editáveis:

• PUT — substituição. Sobrescreve o bloco de campos permitido do cliente com o que você enviar. É a operação "estado completo": pense nela como "este passa a ser o cadastro do cliente". Por isso reenvie também os campos que não mudaram.
• PATCH — atualização parcial. Aplica só os campos presentes no corpo, deixando o resto intacto. Ideal para sincronizar um campo pontual (ex.: trocar o e-mail) sem precisar carregar o objeto inteiro antes.

Em ambos os casos a operação é síncrona: a resposta 200 OK já traz o cliente atualizado, com updatedAt refletindo o momento da gravação. O id, o createdAt e os relacionamentos do cliente (addresses, cards) são preservados — esta operação não cria nem remove endereços ou cartões; ela edita apenas os dados de perfil (nome, documento, contato, e-mails, metadados).

Quando usar

• PATCH — para mudanças pontuais (novo telefone, novo e-mail, ajustar metadata). É a escolha padrão na maioria das integrações, porque evita sobrescrever campos sem querer.
• PUT — quando o seu sistema é a fonte da verdade e você quer garantir que o cadastro fique exatamente igual ao payload enviado (sincronização "espelho" a partir do seu CRM).

Quando não usar:

• Para criar um cliente novo, use Criar cliente.
• Para ler o cadastro atual sem alterar nada, use Consultar cliente.
• Para adicionar/editar endereços, use o recurso Endereços — não este endpoint.

Requisição

Headers

Use o header SelectKey para autenticar — nunca Authorization: Bearer ou Basic.

Parâmetro de caminho

Corpo da requisição

O mesmo conjunto de campos vale para PUT e PATCH. Em PUT, reenvie também os campos não alterados; em PATCH, envie só o que muda.

Exemplo — PUT (substituição)

curl -X PUT https://api.selectwin.io/v1/customers/cus_01hqzvabc \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 4d2b1c9a-7e3f-4a10-9c8e-2f6a1b0d3e55" \
  -d '{
    "document": { "type": "cpf", "number": "12345678901" },
    "telephone": { "countryCode": "55", "areaCode": "11", "number": "999999999" },
    "firstName": "João",
    "lastName": "Silva",
    "email": "[email protected]",
    "externalReference": "CRM-USER-001",
    "gender": "male",
    "birthdate": "1990-01-15",
    "additionalEmails": ["[email protected]"],
    "metadata": { "crmId": "lead-42" }
  }'

Exemplo — PATCH (atualização parcial)

Trocar apenas o e-mail e um campo de metadata:

curl -X PATCH https://api.selectwin.io/v1/customers/cus_01hqzvabc \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "João",
    "lastName": "Silva",
    "email": "[email protected]",
    "metadata": { "crmId": "lead-42" }
  }'

firstName, lastName e email são obrigatórios no contrato e devem estar presentes mesmo em PATCH.

Resposta

Em sucesso, o status é 200 OK e o corpo é o objeto cliente atualizado, incluindo os relacionamentos em projeção leve (addresses[], cards[]) e os _links (HATEOAS) para as próximas ações.

{
  "id": "cus_01hqzvabc",
  "firstName": "João",
  "lastName": "Silva",
  "email": "[email protected]",
  "birthdate": "1990-01-15",
  "gender": "male",
  "document": { "type": "cpf", "number": "12345678901" },
  "telephone": {
    "countryCode": "55",
    "areaCode": "11",
    "number": "999999999",
    "line": "5511999999999"
  },
  "geolocation": null,
  "available": true,
  "delinquent": false,
  "externalReference": "CRM-USER-001",
  "additionalEmails": ["[email protected]"],
  "addresses": [
    {
      "id": "addr_01hqzvabc",
      "street": "Av. Paulista",
      "number": "1000",
      "complement": "Sala 1",
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR",
      "postcode": "01310100",
      "line": "Av. Paulista, 1000 - Bela Vista, São Paulo - SP, 01310100",
      "primary": true,
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:33.000Z"
    }
  ],
  "cards": [],
  "metadata": { "crmId": "lead-42" },
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "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."
    },
    "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."
    }
  }
}

Campos-chave da resposta

Erros

Trate sempre pelo error.code (estável), não pela message. Veja o envelope em Tratamento de Erros e a lista completa em Códigos de Erro.

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

{
  "error": {
    "code": "invalidParameters",
    "statusCode": 400,
    "category": "validation",
    "message": "Validation errors occurred.",
    "params": [
      { "firstName": "The firstName field must be between 3 and 40 characters." }
    ]
  }
}

Boas práticas

• Prefira PATCH para mudanças pontuais. Ele só mexe nos campos enviados e evita apagar dados sem querer; reserve PUT para sincronizações de espelho onde o seu sistema é a fonte da verdade.
• Leia antes de um PUT. Busque o estado atual com Consultar cliente, aplique suas mudanças e reenvie o objeto completo — assim nenhum campo se perde.
• Não tente atualizar endereço por aqui. O address não faz parte do corpo; gerencie endereços pelo recurso Endereços.
• Normalize os documentos e telefones. document.number e os campos de telephone aceitam apenas dígitos (sem pontos, traços ou parênteses) para cpf/cnpj.
• Envie X-Idempotency-Key se houver risco de reenvio (timeout, retry automático), garantindo que a mesma atualização não seja aplicada de formas conflitantes. Veja Idempotência.
• Use externalReference e metadata para casar o cliente com o registro equivalente no seu CRM e facilitar conciliação.
• Trate o id como opaco e confie no campo id da resposta, não no formato do prefixo. Veja Convenções.
• Reaja por estados, não por polling. Para acompanhar mudanças de cliente em escala, prefira webhooks a varredura periódica.

Veja também

• Visão geral de Clientes
• Criar cliente
• Consultar cliente
• Listar clientes
• Excluir cliente
• Endereços — para gerenciar os endereços do cliente
• Convenções da API · Códigos de Erro · Idempotência