Identificação de Cliente e Logística Fiscal

Visão Geral

A identificação correta do comprador é uma etapa obrigatória para a evolução de qualquer carrinho administrativo para a fase de fechamento.

Sem um cliente vinculado, o sistema não possui base de dados para aplicar regras de impostos, políticas de fidelidade (como carteiras ou pontos) ou validar a elegibilidade de determinadas promoções.

Este módulo gerencia a associação de cadastros já existentes no CRM da plataforma ao contexto do carrinho através do prefixo /carts/{cartId}/customer. O fluxo é dividido em duas ações principais:

1. Identificação do Titular: Vincula o ID do cliente ao carrinho, definindo o responsável financeiro pela venda. 2. Definição Logística: Associa endereços específicos do cadastro do cliente para fins de entrega (delivery) e faturamento (billing).

---

Origem dos Dados

Este módulo não realiza a criação de novos clientes ou endereços. Ele atua como um seletor de dados já validados.

Caso os dados do cliente precisem de alteração ou um novo endereço precise ser cadastrado, o operador deve realizar estas ações nos módulos de Gestão de Clientes antes de proceder com o vínculo no carrinho.

Entidades Envolvidas

• Cliente (customerId): O registro mestre que contém e-mail, telefone e documento (CPF/CNPJ). É o nó central para todas as validações de fraude e emissão de nota fiscal.
• Endereço de Entrega (delivery): Define a base de cálculo para a cotação de frete e prazos logísticos.
• Endereço de Faturamento (billing): Utilizado para a emissão do documento fiscal e validação de métodos de pagamento (como cartão de crédito).
• Tipo de Endereço both: Utilizado quando o endereço de entrega e faturamento são idênticos, simplificando o payload da requisição.

Notas e Considerações

Validações de Consistência

O sistema impede o vínculo de endereços que não pertençam ao cliente já associado ao carrinho.

Além disso, uma vez que um cliente é vinculado, algumas lojas podem possuir políticas que impedem a troca do titular sem a limpeza prévia do carrinho, visando evitar inconsistências em regras de preço já calculadas.

---

Impacto Imediato

No momento em que o endereço é vinculado, o domínio de Store ganha contexto geográfico (CEP) para realizar a simulação de ordens (orders[]).

A partir deste ponto, o operador poderá avançar para o módulo de Frete para selecionar as opções de transporte disponíveis para aquela região específica.

Vínculo de Cliente no Carrinho (Admin)

Descrição

Este endpoint realiza a vinculação formal de um titular ao carrinho administrativo.

Esta ação é o "gatilho" que permite ao sistema identificar o perfil de compra, aplicar tabelas de preços específicas para aquele cliente (se houver) e habilitar o uso de benefícios acumulados, como saldos em carteira ou pontos de fidelidade.

Ao informar o customerId, o backend valida se o cliente existe e se o seu cadastro está ativo.

Uma vez vinculado, o objeto de resposta passará a incluir o bloco customer com os dados básicos de identificação, permitindo que a interface administrativa apresente o nome e o e-mail do titular na visualização do carrinho.

---

Regras de Negócio

• Titularidade Única: O sistema geralmente impede a re-vinculação de um cliente diferente se o carrinho já possuir um titular definido, visando evitar fraudes ou erros de processo. Caso seja necessário trocar o cliente, recomenda-se a criação de um novo carrinho ou a limpeza do atual.
• Estado do Cadastro: Clientes marcados como desativados no CRM não podem ser vinculados a novos carrinhos e retornarão um erro de autorização.

---

Dependências de Fechamento

A vinculação do cliente é um pré-requisito para o endpoint de Vínculo de Endereços. Sem a definição do titular, o sistema não tem contexto para listar ou validar endereços de entrega compatíveis.

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

1curl --request PUT \
2  --url '{{MAIN_URL}}/carts/CART123/customer/10' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": "CART-8f42dce0-20f0-4c4c-bb4f-9f8a16f6f471",
3  "currencyId": "BRL",
4  "countryCode": "BRA",
5  "quoteZipcode": "12123-123",
6  "subtotalValue": 259.9,
7  "shippingValue": 18.4,
8  "discountValue": 15,
9  "additionValue": 0,
10  "totalValue": 263.3,
11  "discountPreview": null,
12  "installments": [],
13  "requestedProductMap": [],
14  "discountMap": null,
15  "customer": {
16    "customerId": 345,
17    "nameCorporateName": "Mariana Souza",
18    "tradeName": "",
19    "email": "mariana.souza@cliente.com",
20    "document": "12345678909",
21    "gender": "female",
22    "isCorporate": false,
23    "nationality": "BRA",
24    "birthdate": "1992-08-14",
25    "phone": "+5511998765432"
26  },
27  "addresses": [],
28  "orders": [],
29  "errors": [],
30  "isMerged": false,
31  "createdAt": "2026-05-05 10:00:00",
32  "updatedAt": "2026-05-05 10:43:21"
33}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Vínculo de Endereço no Carrinho (Admin)

Descrição

O vínculo de endereços é a etapa que provê ao carrinho o contexto geográfico necessário para a simulação logística.

Através desta chamada, o operador define para onde os produtos devem ser despachados e qual o endereço de referência para o faturamento (emissão de NF).

A API suporta a definição de um único endereço que acumule ambas as funções (both) ou a separação explícita entre entrega (delivery) e faturamento (billing).

Esta distinção é fundamental para cenários B2B ou presentes, onde o destino da mercadoria difere da sede fiscal do comprador.

---

Comportamento de Cotação Automática

Assim que um endereço de entrega é validado e vinculado, o domínio de Store realiza uma tentativa automática de cotação junto às transportadoras cadastradas para o Canal de Venda atual.

A resposta retornará o objeto addresses atualizado e, caso o cálculo tenha sucesso, os primeiros valores de frete já poderão ser visualizados no array orders[].

---

Consistência de Dados

O sistema valida se os addressId informados pertencem de fato ao customerId vinculado ao carrinho. Tentativas de vincular endereços de outros clientes resultarão em erro, protegendo a integridade dos dados e evitando entregas indevidas.

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Parâmetros do Corpo

Exemplo de Requisição

1curl --request PUT \
2  --url '{{MAIN_URL}}/carts/CART123/customer/10/address' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "addresses": [
7      {
8        "addressId": 100,
9        "addressType": "both"
10      }
11    ]
12  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": "CART-8f42dce0-20f0-4c4c-bb4f-9f8a16f6f471",
3  "currencyId": "BRL",
4  "countryCode": "BRA",
5  "quoteZipcode": "12123-123",
6  "subtotalValue": 259.9,
7  "shippingValue": 18.4,
8  "discountValue": 15,
9  "additionValue": 0,
10  "totalValue": 263.3,
11  "discountPreview": null,
12  "installments": [],
13  "requestedProductMap": [],
14  "discountMap": null,
15  "customer": {
16    "customerId": 345,
17    "nameCorporateName": "Mariana Souza",
18    "tradeName": "",
19    "email": "mariana.souza@cliente.com",
20    "document": "12345678909",
21    "gender": "female",
22    "isCorporate": false,
23    "nationality": "BRA",
24    "birthdate": "1992-08-14",
25    "phone": "+5511998765432"
26  },
27  "addresses": [
28    {
29      "addressId": 31,
30      "type": "delivery",
31      "zipCode": "12123-123",
32      "identification": "Casa",
33      "street": "Rua das Flores",
34      "number": "120",
35      "city": "São José dos Campos",
36      "complement": "Apto 22",
37      "district": "Jardim Primavera",
38      "state": "São Paulo",
39      "stateCode": "SP",
40      "countryCode": "BRA",
41      "recipient": "Mariana Souza",
42      "createdAt": "2026-05-05 10:10:00",
43      "updatedAt": "2026-05-05 10:12:00"
44    }
45  ],
46  "orders": [],
47  "errors": [],
48  "isMerged": false,
49  "createdAt": "2026-05-05 10:00:00",
50  "updatedAt": "2026-05-05 10:43:21"
51}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.