Feature de novo Endpoint para verificação de área de risco dos Correios por CEP #557

SenaJesus · 2023-11-30T11:56:51Z

Descrição da Nova Feature "Verificar Área de Risco dos Correios por CEP"

Implementamos uma nova funcionalidade no BrasilAPI que permite verificar se um CEP está localizado em uma área de risco, conforme classificado pelos Correios do Brasil. Esta feature é essencial para informar consumidores e empresas sobre restrições de entrega em determinados CEPs, reduzindo a incidência de surpresas desagradáveis e contribuindo para um planejamento mais eficaz de envios e recebimentos de encomendas.

Motivação

A motivação para o desenvolvimento desta funcionalidade surgiu da necessidade de mitigar os impactos da segregação social exacerbada pela falta de informação sobre áreas com restrição de entrega. Consumidores, especialmente em regiões periféricas, frequentemente enfrentam desafios ao receber encomendas devido a essas restrições, um problema pouco divulgado pelas empresas de distribuição. A transparência na verificação de CEPs em áreas de risco é também uma exigência do Código de Defesa do Consumidor brasileiro, reforçando a relevância desta funcionalidade.

Detalhes Técnicos

Análise de Arquitetura: A funcionalidade foi integrada respeitando a arquitetura existente dos endpoints do BrasilAPI, mantendo a coesão e a qualidade do código-fonte.
Engenharia Reversa e Parsing de Dados: Realizamos engenharia reversa nas requisições HTTP do site dos Correios, extraindo informações de HTML com técnicas de parsing usando JSDOM.
Tratamento de Erros e Exceções: Implementamos um sistema robusto para o manejo de erros, utilizando expressões regulares e constantes para mensagens de erro.
Requisições HTTP com Axios: Asseguramos requisições HTTP eficientes e corretas para a coleta dos dados necessários.
Otimizações de Código: Fizemos uma análise de complexidade do código, buscando otimizações por meio de modularização e reutilização de funções eficientes do JavaScript.
Documentação: A documentação segue as diretrizes do OpenAPI 3.0, detalhando esquemas de requisição, status de resposta, e parâmetros.
Testes Unitários: Foram realizados testes unitários abrangentes para garantir a confiabilidade e integridade da funcionalidade.

Benefícios para Empresas e Consumidores

Empresas de e-commerce, serviços de entrega, e consumidores se beneficiam diretamente desta funcionalidade. E-commerce, como a Magazine Luiza, poderá informar seus clientes antecipadamente sobre possíveis restrições de entrega em seus CEPs, aumentando a transparência e a satisfação do cliente. Serviços de entrega poderão planejar rotas mais eficientes, considerando as restrições existentes. Consumidores, por sua vez, estarão mais informados e poderão se planejar melhor para o recebimento de seus produtos.

Solicitação de Integração

Solicitamos a revisão desta implementação pela comunidade e a subsequente integração ao projeto principal do BrasilAPI, acreditando que esta funcionalidade agregará grande valor ao projeto e à sociedade brasileira.

… para os Correios

…correios

vercel · 2023-11-30T11:56:57Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
brasilapi	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Dec 1, 2023 3:55pm

sonarcloud · 2023-12-01T15:55:00Z

Kudos, SonarCloud Quality Gate passed!

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
No Duplication information

LorhanSohaky

Muito obrigado pela contribuição! Deixei alguns pedidos de melhoras

LorhanSohaky · 2023-12-01T01:41:40Z

package.json

É uma prática deste repositório deixar as versões pinadas

LorhanSohaky · 2023-12-02T19:45:28Z

package.json

    "dayjs": "1.11.7",
+    "dom-parser": "^1.1.5",


Pelo que vi essa dependência não é utilizada. Se for o caso, poderia remover?

LorhanSohaky · 2023-12-02T19:46:55Z

pages/api/correiosres/v1/index.js

+// Padrões de alertas dos Correios definidos por expressões regulares.
+const padroesAlertasCorreios = [
+    {
+        regex: /alert\(\'CEP de origem n.*o encontrado na base de dados dos Correios \(-1\).\'\)/,


Se com a expressão regular de baixo der certo, acho interessante adotar a estratégia não gulosa

Suggested change

regex: /alert\(\'CEP de origem n.*o encontrado na base de dados dos Correios \(-1\).\'\)/,

regex: /alert\(\'CEP de origem n.*?o encontrado na base de dados dos Correios \(-1\).\'\)/,

https://pt.stackoverflow.com/a/94104

Por qual motivo estamos lidando com matchers na acentuação? A ideia é garantir que mesmo sem saber o encoding a gnt lidar corretamente?

LorhanSohaky · 2023-12-02T19:49:22Z

pages/api/correiosres/v1/index.js

+        regex: /alert\(\'CEP de destino n.*o encontrado na base de dados dos Correios \(-2\).\'\)/,
+        mensagem: ERROR_MESSAGES['CEP_DESTINO_NOT_FOUND']
+    },
+    {
+        regex: /alert\(\'CEP de destino inv.*lido.\'\)/,
+        mensagem: ERROR_MESSAGES['CEP_DESTINO_INVALIDO']
+    },
+    {
+        regex: /alert\(\'CEP inv.*lido.\'\)/,
+        mensagem: ERROR_MESSAGES['CEP_ORIGEM_INVALIDO']
+    }


Suggested change

regex: /alert\(\'CEP de destino n.*o encontrado na base de dados dos Correios \(-2\).\'\)/,

mensagem: ERROR_MESSAGES['CEP_DESTINO_NOT_FOUND']

},

{

regex: /alert\(\'CEP de destino inv.*lido.\'\)/,

mensagem: ERROR_MESSAGES['CEP_DESTINO_INVALIDO']

},

{

regex: /alert\(\'CEP inv.*lido.\'\)/,

mensagem: ERROR_MESSAGES['CEP_ORIGEM_INVALIDO']

}

regex: /alert\(\'CEP de destino n.*?o encontrado na base de dados dos Correios \(-2\).\'\)/,

mensagem: ERROR_MESSAGES['CEP_DESTINO_NOT_FOUND']

},

{

regex: /alert\(\'CEP de destino inv.*?lido.\'\)/,

mensagem: ERROR_MESSAGES['CEP_DESTINO_INVALIDO']

},

{

regex: /alert\(\'CEP inv.*?lido.\'\)/,

mensagem: ERROR_MESSAGES['CEP_ORIGEM_INVALIDO']

}

LorhanSohaky · 2023-12-02T19:51:43Z

pages/api/correiosres/v1/index.js

+// Função para validar a presença dos CEPs de origem e destino.
+function validarCEP(cepOrigem, cepDestino) {
+    if (!cepOrigem || !cepDestino) {
+        throw new NotFoundError({


Creio que aqui faça mais sentido um bad request

Suggested change

throw new NotFoundError({

throw new BadRequestError({

LorhanSohaky · 2023-12-02T20:10:33Z

pages/docs/doc/correiosres.json

+                },
+                "example": {
+                    "response": "CEP em zona restrita",
+                    "isDeliverable": false


Suggested change

"isDeliverable": false

"is_deliverable": false

LorhanSohaky · 2023-12-02T20:10:42Z

pages/docs/doc/correiosres.json

+        "schemas": {
+            "cepInfo": {
+                "title": "Informação do CEP",
+                "required": ["response", "isDeliverable"],


Suggested change

"required": ["response", "isDeliverable"],

"required": ["response", "is_deliverable"],

LorhanSohaky · 2023-12-02T20:13:16Z

pages/api/correiosres/v1/index.js

Sugeriria de deixar aqui o mais simples possível e deixar a maioria das funções e constantes dentro do service

Será que vale criar uma rota mãe chamada /correios e colocar dentro dela /correios/cep e /correios/restricao?

Obviamente ainda mantendo um symlink do cep atual pra não deixar de funionar 🤔

LorhanSohaky · 2023-12-02T20:15:04Z

pages/api/correiosres/v1/index.js

+// Função principal que verifica restrições de entrega para um CEP.
+const verifyRestriction = async (request, response) => {
+    try {
+        const {cepOrigem, cepDestino, servico} = request.query;


Acho interessante adotar o padrão snake_case para as variáveis que vêm do cliente e vão para o cliente

Suggested change

const {cepOrigem, cepDestino, servico} = request.query;

const {cep_origem: cepOrigem, cep_destino: cepDestino, servico} = request.query;

LorhanSohaky · 2023-12-02T20:16:28Z

pages/api/correiosres/v1/index.js

+            response.status(200).json('{"response": "CEP em zona restrita", "isDeliverable": false}');
+            return;
+        }
+
+        if (positiveDiv) {
+            response.status(200).json('{"response": "CEP sem restricao de entrega", "isDeliverable": true}');


Suggested change

response.status(200).json('{"response": "CEP em zona restrita", "isDeliverable": false}');

return;

}

if (positiveDiv) {

response.status(200).json('{"response": "CEP sem restricao de entrega", "isDeliverable": true}');

response.status(200).json({message: "CEP em zona restrita", is_deliverable: false});

return;

}

if (positiveDiv) {

response.status(200).json({message:"CEP sem restricao de entrega", is_deliverable": true});

lucianopf · 2023-12-03T00:13:12Z

pages/api/correiosres/v1/index.js

+function verificarAlertasCorreios(correiosData) {
+    const padrao = padroesAlertasCorreios.find(p => p.regex.test(correiosData));
+    return padrao ? { alerta: true, mensagem: padrao.mensagem } : { alerta: false, mensagem: '' };
+}


Dado que o esperado é que na maioria das vezes não hajam alertas será que não é melhor primeiro validar se existe um alerta e caso exista a gnt iterar sobre os possíveis alertas pra mapear corretamente o erro? (pensando especialmente que fazer validações com Regex pode ser bem exaustivo)

lucianopf · 2023-12-03T00:14:23Z

pages/api/correiosres/v1/index.js

+}
+
+// Função para validar a presença dos CEPs de origem e destino.
+function validarCEP(cepOrigem, cepDestino) {


Seria interessante manter o nome das funções em inglês como o restante da codebase 🙏

lucianopf · 2023-12-03T00:49:17Z

pages/api/correiosres/v1/index.js

+        const {cepOrigem, cepDestino, servico} = request.query;
+
+        // Verifica se o serviço solicitado é válido.
+        if (!(servico in SERVICOS)) {


Pq fazer dessa forma e não da seguinte forma?

Suggested change

if (!(servico in SERVICOS)) {

if (!SERVICOS[servico]) {

lucianopf · 2023-12-03T00:50:31Z

pages/api/correiosres/v1/index.js

+        }
+
+        // Valida os CEPs fornecidos na requisição.
+        validarCEP(cepOrigem, cepDestino);


Será que aqui um nome melhor pra função não seria validateParams e nessa função validar os 3 parametros? 👀

lucianopf · 2023-12-03T00:55:02Z

pages/api/correiosres/v1/index.js

+];
+
+// Função para verificar se existe algum alerta na resposta dos Correios.
+function verificarAlertasCorreios(correiosData) {


Será que não seria mais interessante essa função se chamar getAlerts e caso não hajam alertas o retorno é null?

lucianopf · 2023-12-03T00:57:26Z

pages/api/correiosres/v1/index.js

+        const verificarAlerta = verificarAlertasCorreios(correiosData);
+
+        // Se um alerta for encontrado, lança um erro.
+        if (verificarAlerta['alerta']) {
+            throw new NotFoundError({
+                message: verificarAlerta['mensagem'],
+                type: 'cep_error',
+                name: 'CEP_NOT_FOUND',
+            });
+        }


Partindo do comentário https://github.com/BrasilAPI/BrasilAPI/pull/557/files#r1412902104

A gnt poderia reescrever esse trecho pra algo tipo

Suggested change

const verificarAlerta = verificarAlertasCorreios(correiosData);

// Se um alerta for encontrado, lança um erro.

if (verificarAlerta['alerta']) {

throw new NotFoundError({

message: verificarAlerta['mensagem'],

type: 'cep_error',

name: 'CEP_NOT_FOUND',

});

}

const foundAlert = getAlert(correiosData);

if (foundAlert) {

throw new NotFoundError({

message: foundAlert,

type: 'cep_error',

name: 'CEP_NOT_FOUND',

});

}

lucianopf · 2023-12-03T01:05:30Z

pages/api/correiosres/v1/index.js

+        }
+
+        // Processa o HTML para determinar restrições de entrega.
+        const { errorDiv, positiveDiv } = parseCorreiosHtml(correiosData);


Na prática mesmo o que a gnt ta querendo aqui é baseado no html definir se a entrega é possível ou não, correto?

Será que não seria melhor essa função na vdd retornar um boolean e baseado nisso a gnt define a resposta?

SenaJesus added 2 commits November 30, 2023 07:55

feat: Adiciona novo endpoint para verificação de CEP de área de risco…

80acd18

… para os Correios

feat: adicionando teste unitario para a feature de area de risco dos …

af7e3c1

…correios

vercel bot deployed to Preview November 30, 2023 11:58 View deployment

Fix(.eslintrc.js): conflitos de arquivo

578184f

vercel bot deployed to Preview December 1, 2023 15:54 View deployment

Merge branch 'main' into main

7f30a08

vercel bot deployed to Preview December 1, 2023 15:55 View deployment

LorhanSohaky requested changes Dec 2, 2023

View reviewed changes

lucianopf reviewed Dec 3, 2023

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Feature de novo Endpoint para verificação de área de risco dos Correios por CEP #557

Feature de novo Endpoint para verificação de área de risco dos Correios por CEP #557

SenaJesus commented Nov 30, 2023

vercel bot commented Nov 30, 2023 •

edited

sonarcloud bot commented Dec 1, 2023

LorhanSohaky left a comment

LorhanSohaky Dec 1, 2023

LorhanSohaky Dec 2, 2023

LorhanSohaky Dec 2, 2023

lucianopf Dec 3, 2023

LorhanSohaky Dec 2, 2023

LorhanSohaky Dec 2, 2023

LorhanSohaky Dec 2, 2023

LorhanSohaky Dec 2, 2023

LorhanSohaky Dec 2, 2023

lucianopf Dec 3, 2023 •

edited

LorhanSohaky Dec 2, 2023

LorhanSohaky Dec 2, 2023

lucianopf Dec 3, 2023

lucianopf Dec 3, 2023

lucianopf Dec 3, 2023

lucianopf Dec 3, 2023

lucianopf Dec 3, 2023

lucianopf Dec 3, 2023

lucianopf Dec 3, 2023

	regex: /alert\(\'CEP de origem n.*o encontrado na base de dados dos Correios \(-1\).\'\)/,
	regex: /alert\(\'CEP de origem n.*?o encontrado na base de dados dos Correios \(-1\).\'\)/,

	"required": ["response", "isDeliverable"],
	"required": ["response", "is_deliverable"],

	const {cepOrigem, cepDestino, servico} = request.query;
	const {cep_origem: cepOrigem, cep_destino: cepDestino, servico} = request.query;

Feature de novo Endpoint para verificação de área de risco dos Correios por CEP #557

Are you sure you want to change the base?

Feature de novo Endpoint para verificação de área de risco dos Correios por CEP #557

Conversation

SenaJesus commented Nov 30, 2023

vercel bot commented Nov 30, 2023 • edited

sonarcloud bot commented Dec 1, 2023

LorhanSohaky left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lucianopf Dec 3, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vercel bot commented Nov 30, 2023 •

edited

lucianopf Dec 3, 2023 •

edited