Cadastro Unificado de Usuário com Endereço

Implementamos uma melhoria nos endpoints de cadastro de usuários que permite o envio do endereço de entrega e/ou faturamento diretamente no mesmo payload de criação do perfil. Com isso, o processo que antes exigia duas requisições separadas passa a ser resolvido em uma única chamada, eliminando inconsistências de dados e simplificando integrações

Como era antes?

Anteriormente, a criação de um usuário e a vinculação de seu endereço ocorriam em etapas distintas: primeiro uma requisição para criar o perfil e, em seguida, outra para associar o endereço. Quando a segunda chamada falhava por qualquer motivo — instabilidade, dado inválido ou erro operacional — o usuário era criado na base sem endereço, gerando registros incompletos que prejudicavam o fluxo de checkout e a experiência do cliente final.

O que mudou?

O campo enderecos foi adicionado como array opcional nos dois endpoints de cadastro de usuários, permitindo o envio de um ou mais endereços na mesma requisição de criação do perfil.

1. Cadastro Individual — POST/usuarios
   Permite criar o usuário já com seus endereços vinculados em uma única chamada. O campo enderecos é opcional — caso não seja enviado, o comportamento anterior é mantido. Se o array contiver algum endereço inválido, a operação inteira é revertida: o usuário não é criado e nenhum dado é salvo.).
2. Cadastro em Lote — POST/usuarios/lote
   Permite o envio simultâneo de múltiplos usuários, cada um com seus respectivos endereços. O processamento é isolado por item: se um usuário do lote tiver endereço inválido, apenas aquele cadastro falha — os demais são criados normalmente. Cada falha é reportada individualmente na resposta, sem cancelar o lote inteiro.

Estrutura do array enderecos

O campo enderecos pode ser omitido, enviado como array vazio [], ou com um ou mais endereços. Quando informado com itens, cada endereço deve conter os seguintes campos obrigatórios:

Os demais campos (nomeEndereco, complemento, referencia, bairro) são opcionais.

Comportamento em caso de endereço inválido

O comportamento difere entre os dois endpoints:

• POST /usuarios — rollback total
  A validação ocorre antes de qualquer persistência. Se qualquer item do array enderecos for inválido, a requisição retorna 422 Unprocessable Entity e nenhum dado é salvo — nem o usuário, nem os demais endereços do array.

POST /usuarios → 422 Unprocessable Entity
"Endereço [2]: O(s) campo(s) CEP deve(m) ser preenchido(s)"

• POST /usuarios/lote — isolamento por item
  Cada usuário do lote é processado de forma independente. Um endereço inválido em um item não afeta os demais. A resposta detalha exatamente quais cadastros foram criados e quais falharam, com a mensagem de erro por item.

{
 "totalProcessados": 2,
 "totalCriados": 1,
 "totalFalhas": 1,
 "sucessos": [
   { "indice": 0, "email": "[email protected]", "usuarioId": 356325 }
 ],
 "falhas": [
   { "indice": 1, "email": "[email protected]", "codigoErro": 1007,
     "mensagem": "Endereço [1]: O(s) campo(s) CEP deve(m) ser preenchido(s)" }
 ]
}

Benefícios e Ganhos

• Menos chamadas, mais eficiência: O que antes exigia duas requisições agora é resolvido em uma, simplificando integrações e reduzindo a complexidade operacional.
• Integridade total dos dados: No cadastro individual, as validações são executadas antes de qualquer persistência — em caso de erro, toda a operação é revertida, garantindo que não existam usuários com perfis incompletos na base.
• Suporte a múltiplos endereços: É possível cadastrar endereços de entrega e faturamento distintos em uma única requisição.
• Erros claros e rastreáveis: A API identifica exatamente qual campo e qual endereço do array apresentou problema, tanto no individual quanto no lote.
• Resiliência em lote: No POST /usuarios/lote, cadastros válidos são processados normalmente mesmo quando outros itens do lote falham — sem comprometer toda a operação.