📄 Documentos do Cliente

📋 Visão Geral

O módulo de Documentos do Cliente permite que o cliente autenticado gerencie seus documentos de identificação de forma autônoma, sem necessidade de intervenção administrativa.

Os documentos são utilizados em fluxos que exigem identificação formal, como emissão de nota fiscal, validação cadastral e processos de compra que requerem CPF ou CNPJ.

O salvamento opera como upsert por tipo: se o documento do tipo informado já existir, será atualizado; caso contrário, será criado. Isso permite enviar múltiplos documentos em uma única requisição, sem necessidade de verificar previamente quais já estão cadastrados.

🔄 Entidades Envolvidas

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

Documento do Cliente (CustomerDocument)

Representa um documento de identificação vinculado ao cliente autenticado. Cada registro é composto por:

• 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 com erro 400. O tipo cnpj também aceita o formato alfanumérico oficial da Receita Federal (letras A-Z nas 12 primeiras posições, dígitos verificadores sempre numéricos). Os tipos document1, document2 e document3 são documentos personalizados sem validação de formato, aceitando qualquer valor textual.

Cada tipo só pode existir uma vez por cliente — não há duplicidade de tipo. O cliente é identificado automaticamente pelo token de autenticação, sem necessidade de informar o customerId na requisição.

📌 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 (/document/{documentType}), não no corpo da requisição.
• CPF e CNPJ são validados matematicamente — dígitos verificadores incorretos resultam em erro de validação.

📄 Listagem de Documentos do Cliente

📋 Descrição

Endpoint responsável por retornar todos os documentos cadastrados do cliente autenticado.

A resposta contém todos os documentos do cliente, sem paginação.

🔐 Permissão

• CustomerAuth — autenticação do cliente via token JWT

📝 Parâmetros

🏷️ Headers Obrigatórios

💡 Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/customer/document' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

HTTP Status: 200 OK

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

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

> Este endpoint não possui erros específicos da aplicação além dos erros padrão de autenticação.

💾 Salvar Documentos do Cliente

📋 Descrição

Endpoint responsável por salvar ou atualizar documentos do cliente autenticado.

Opera como upsert por tipo: se o documento do tipo informado já existir, o valor será atualizado; caso contrário, o documento será criado. É possível enviar múltiplos documentos em uma única requisição.

🔐 Permissão

• CustomerAuth — autenticação do cliente via token JWT

📝 Parâmetros

🏷️ Headers Obrigatórios

📦 Parâmetros do Corpo

💡 Exemplo de Requisição

1curl --request PUT \
2  --url '{{MAIN_URL}}/customer/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

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

🗑️ Remover Documento do Cliente

📋 Descrição

Endpoint responsável por remover permanentemente um documento do cliente autenticado pelo seu tipo.

A exclusão é definitiva e irreversível — o documento não pode ser recuperado após a remoção.

🔐 Permissão

• CustomerAuth — autenticação do cliente via token JWT

📝 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros de URL

💡 Exemplo de Requisição

1curl --request DELETE \
2  --url '{{MAIN_URL}}/customer/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

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.