📄 Documentos do Cliente (Admin)

📋 Visão Geral

O módulo de Documentos do Cliente permite que usuários administrativos gerenciem os documentos de identificação dos clientes cadastrados na loja.

Entre os documentos suportados estão CPF, CNPJ, RG, Inscrição Estadual, além de tipos personalizados (document1, document2, document3), oferecendo flexibilidade conforme a necessidade do negócio.

🔄 Entidades Envolvidas

O módulo opera sobre uma única entidade principal:

Documento do Cliente (CustomerDocument)

Representa um documento de identificação vinculado a um cliente específico. Cada registro contém dois campos essenciais:

• type — categoria do documento: cpf, cnpj, rg, ie, document1, document2 ou document3
• document — número ou valor do documento, com limite máximo de 100 caracteres

Os tipos cpf e cnpj passam por validação matemática de dígitos verificadores — valores com sequências inválidas são rejeitados automaticamente. Os tipos document1, document2 e document3 são documentos personalizados sem validação de formato, aceitando qualquer valor textual.

O salvamento de documentos opera como upsert por tipo: se o cliente já possuir um documento do tipo informado, o valor será atualizado; caso contrário, será criado. Cada tipo só pode existir uma vez por cliente — não há duplicidade de tipo.

📌 Notas e Considerações

• A remoção de um documento é permanente e irreversível — não é possível recuperá-lo após a exclusão.
• O campo type na operação de remoção é passado via parâmetro de URL, não no corpo da requisição.

Salvar Documentos do Cliente

Descrição

Endpoint que permite aos usuários administrativos salvar ou atualizar documentos de um cliente 📄.

É possível enviar múltiplos documentos em uma única requisição, facilitando operações em lote no contexto administrativo.

Ao processar os documentos, as seguintes regras são aplicadas:

• Criação: caso o documento não exista, ele será criado
• Atualização: se já existir um documento do mesmo tipo, ele será atualizado
• Múltiplos documentos: é permitido enviar vários documentos na mesma requisição

Essa abordagem garante flexibilidade e consistência na gestão documental do cliente.

Parâmetros de Query

Headers Obrigatórios

Parâmetros de URL

Parâmetros do Corpo

Exemplo de Requisição

1curl --request PUT \
2  --url '{{MAIN_URL}}/customers/123/document' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "documents": [
7      {
8        "type": "cpf",
9        "document": "12345678901"
10      },
11      {
12        "type": "rg",
13        "document": "123456789"
14      }
15    ]
16  }'

✅ Resposta de Sucesso

HTTP Status: 201 Created

1{
2  "status": true,
3  "data": [
4    {
5      "type": "cpf",
6      "document": "12345678901"
7    },
8    {
9      "type": "rg",
10      "document": "123456789"
11    }
12  ]
13}

⚠️ Possíveis erros:

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

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Remoção de Documento do Cliente

Descrição

Endpoint que permite aos usuários administrativos remover um documento específico de um cliente 📄.

A exclusão é definitiva e permanente, impactando diretamente os registros vinculados ao cadastro do cliente.

Ao remover um documento, aplicam-se as seguintes regras:

• Remoção definitiva: o documento é excluído permanentemente do banco de dados
• Sem restauração: não é possível recuperar um documento após a remoção

Essa operação deve ser realizada com cautela, considerando a irreversibilidade da ação.

Parâmetros de Query

Headers Obrigatórios

Parâmetros de URL

Exemplo de Requisição

1curl --request DELETE \
2  --url '{{MAIN_URL}}/customers/123/document/cpf' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": true
4}

⚠️ Possíveis erros:

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

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.