Feature de novo Endpoint para verificação de área de risco dos Correios por CEP by SenaJesus · Pull Request #557 · BrasilAPI/BrasilAPI

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

sonarqubecloud · 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

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

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

-    "cors": "2.8.5",
+    "cors": "^2.8.5",
    "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

+// 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

+        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

+// 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

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


Suggested change

"isDeliverable": false

"is_deliverable": false

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

+        "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

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

+// 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

+            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

+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

+}
+
+// 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

+        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

+        }
+
+        // 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

+];
+
+// 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

+        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

+        }
+
+        // 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?

lucianopf · 2026-04-11T22:48:46Z

Olá @SenaJesus, a proposta de verificar áreas de risco dos Correios por CEP é socialmente relevante! Mas há problemas fundamentais antes do merge.

Bloqueador principal: web scraping do site dos Correios

A própria descrição confirma: "Realizamos engenharia reversa nas requisições HTTP do site dos Correios, extraindo informações de HTML com técnicas de parsing usando JSDOM".

Web scraping não é aceito na BrasilAPI:

O Correios pode alterar o HTML/formulário a qualquer momento, quebrando o endpoint
Parsing de HTML de sites é frágil e não é uma fonte de dados oficial
O Correios pode bloquear requisições automatizadas

Se os Correios tiverem uma API pública e oficial para restrições de entrega, use-a. Caso contrário, esta funcionalidade não pode entrar no projeto no momento.

Outros problemas técnicos:

Mistura CommonJS e ESM: O service usa const axios = require('axios') e exports.requestHtmlCorreios = ... enquanto o handler usa import. Escolha um padrão (o projeto usa ESM).
require('jsdom') no handler: Mistura de require() com import.
axios.defaults.headers.post modificado globalmente no service — afeta todos os requests axios do projeto, não só os seus.

.json() recebendo uma string em vez de objeto:

// ❌ — double-encoded: {"response": "CEP em zona restrita"...} vira uma string no JSON
response.status(200).json('{\"response\": \"CEP em zona restrita\", ...}');

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

Serviço inválido retorna InternalError (500) — deveria ser BadRequestError (400).
Mudança em app.js (só whitespace) não deve estar neste PR.

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

	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;

Conversation

SenaJesus commented Nov 30, 2023

Uh oh!

vercel bot commented Nov 30, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sonarqubecloud bot commented Dec 1, 2023

Uh oh!

LorhanSohaky left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lucianopf Dec 3, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lucianopf commented Apr 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vercel bot commented Nov 30, 2023 •

edited

Loading

lucianopf Dec 3, 2023 •

edited

Loading