📦 Sistema de Rastreamento Correios API

Uma aplicação web completa para rastreamento de encomendas dos Correios, construída com Next.js 15 e tecnologia moderna. Este sistema implementa múltiplas fontes de dados dos Correios para fornecer informações em tempo real sobre o status de pacotes e correspondências.

🚀 Funcionalidades Principais

✨ Recursos Implementados

🔍 Rastreamento em Tempo Real - Consulta direta aos sistemas dos Correios
🌐 Múltiplas Fontes API - 4 endpoints diferentes para máxima disponibilidade
📱 Interface Responsiva - Design moderno que funciona em todos os dispositivos
🎨 UI/UX Profissional - Interface escura com gradientes e animações suaves
📋 Histórico Completo - Timeline detalhado com todos os eventos
💾 Buscas Recentes - Salva automaticamente suas últimas consultas
📋 Copiar Código - Copie códigos com um clique
🔄 Atualização Automática - Atualize os dados facilmente

🛠️ Características Técnicas

Next.js 15 com App Router
TypeScript 5 para type safety
Tailwind CSS 4 para estilização
shadcn/ui componentes modernos
API Routes para backend
CORS habilitado para uso externo
Error handling robusto
Validação de formatos múltiplos

📋 Formatos Suportados

O sistema aceita diversos formatos de códigos de rastreamento:

Formato	Exemplo	Descrição
`AA123456789BR`	`DG049186226BR`	Padrão internacional
`AA123456789012BR`	`PX123456789012BR`	Formato estendido
`AA123456789BR`	`AB123456789BR`	2 letras + 9 dígitos
`A123456789BR`	`D123456789BR`	1 letra + 9 dígitos
`12345678901234`	`12345678901234`	Apenas números

Serviços suportados:

📦 SEDEX (todas modalidades)
📬 PAC (todos os tipos)
📄 Cartas Registradas
🚚 Encomendas Internacionais
📦 SEDEX 10/12/Hoje
📬 Mini Envelopes

🛠️ Pré-requisitos

Node.js 18+ (recomendado 20.x)
npm 9+ ou yarn 1.22+
Git para controle de versão

🚀 Instalação e Execução

1. Clonar o Repositório

git clone <url-do-repositorio>
cd correios-tracking-api

2. Instalar Dependências

# Usando npm (recomendado)
npm install

# Ou usando yarn
yarn install

3. Configurar Variáveis de Ambiente (Opcional)

# Criar arquivo .env.local
cp .env.example .env.local

# Editar com suas configurações
# TOKEN_CORREIOS=seu_token_aqui
# NEXT_PUBLIC_API_URL=http://localhost:3000

4. Iniciar Servidor de Desenvolvimento

# Usando npm
npm run dev

# Ou usando yarn
yarn dev

5. Acessar a Aplicação

Abra seu navegador e acesse: http://127.0.0.1:3000

📁 Estrutura do Projeto

correios-tracking-api/
├── src/
│   ├── app/
│   │   ├── api/
│   │   │   └── tracking/
│   │   │       └── route.ts          # API principal de rastreamento
│   │   │   └── health/
│   │   │       └── route.ts          # Endpoint de saúde
│   │   ├── globals.css               # Estilos globais
│   │   ├── layout.tsx                # Layout principal
│   │   └── page.tsx                  # Página inicial
│   ├── components/
│   │   └── ui/                       # Componentes shadcn/ui
│   ├── lib/
    ├── ├── correios.ts               # Configuração dos Endpoints
│   │   ├── utils.ts                  # Utilitários
│   │   ├── db.ts                     # Configuração do banco
│   │   └── socket.ts                 # WebSocket (opcional)
│   └── hooks/
│       ├── use-toast.ts              # Hook de notificações
│       └── use-mobile.ts             # Hook de responsividade
├── public/
│   ├── logo.png                      # Logo da aplicação
│   └── favicon.ico                   # Favicon
├── prisma/
│   └── schema.prisma                 # Schema do banco
├── package.json                      # Dependências e scripts
├── next.config.ts                    # Configuração do Next.js
├── tailwind.config.ts                # Configuração do Tailwind
├── tsconfig.json                     # Configuração do TypeScript
└── README.md                         # Este arquivo

🔧 Scripts Disponíveis

# Desenvolvimento
npm run dev          # Inicia servidor de desenvolvimento
npm run build        # Build para produção
npm run start        # Inicia servidor de produção
npm run lint         # Verifica código com ESLint

# Banco de Dados
npm run db:push      # Push schema para o banco
npm run db:generate  # Gera Prisma Client
npm run db:migrate   # Roda migrações
npm run db:reset     # Reseta banco de dados

🌐 API Endpoints

POST /api/tracking

Endpoint principal para rastreamento de encomendas.

Request:

{
  "codigo": "DG049186226BR"
}

Response (Sucesso):

{
  "codigo": "DG049186226BR",
  "servico": "SEDEX",
  "status": "Entregue",
  "eventos": [
    {
      "data": "2024-01-15",
      "hora": "14:30",
      "status": "Entregue",
      "local": "São Paulo/SP",
      "descricao": "Entregue ao destinatário",
      "codigoObjeto": "DG049186226BR",
      "dataCompleta": "2024-01-15T14:30"
    }
  ],
  "modalidade": "SEDEX 10",
  "fromAPI": true
}

Response (Erro):

{
  "error": "Código não encontrado",
  "details": "Verifique se o código está correto",
  "suggestion": "Tente novamente mais tarde"
}

GET /api/health

Endpoint para verificar saúde da API.

Response:

{
  "status": "ok",
  "timestamp": "2024-01-15T14:30:00Z",
  "version": "1.0.0"
}

🔍 Fontes de Dados

O sistema implementa múltiplas fontes para garantir máxima disponibilidade:

Site Principal Correios - www.correios.com.br
Rastreamento App - https://apihom.correios.com.br/srorastro
API Pública GET - Endpoint alternativo
API Homologação - Ambiente de teste

Estratégia de Fallback

Tenta cada fonte em ordem de prioridade
Parse inteligente de HTML responses
Tratamento específico para captcha
Error handling detalhado

🎨 Interface do Usuário

Design System

Cores: Esquema escuro profissional
Tipografia: Inter, system fonts
Componentes: shadcn/ui
Animações: Framer Motion
Ícones: Lucide React

Componentes Principais

Search Card: Input de busca com ações
Timeline: Visualização cronológica
Status Badges: Indicadores visuais
Recent Searches: Histórico rápido
Error Alerts: Mensagens de erro

🔒 Segurança

CORS Configurado

'Access-Control-Allow-Origin': '*'
'Access-Control-Allow-Methods': 'GET, POST, OPTIONS'
'Access-Control-Allow-Headers': 'Content-Type, Authorization'

Validação de Input

Sanitização de códigos
Validação de formatos
Rate limiting implícito
Error handling seguro

🚀 Deploy

Vercel (Recomendado)

# Instalar Vercel CLI
npm i -g vercel

# Deploy
vercel --prod

Docker

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]

Railway/Render

Conecte seu repositório
Configure build command: npm run build
Configure start command: npm start
Porta: 3000

🐛 Troubleshooting

Problemas Comuns

Código não encontrado:

Verifique se o código está correto
Confirme se o objeto já foi postado
Tente novamente em alguns minutos

Erro de CORS:

Verifique se o endpoint está correto
Confirme headers de requisição
Use modo development para debug

Timeout:

Serviços dos Correios podem estar lentos
Tente novamente mais tarde
Verifique sua conexão

Logs e Debug

# Ver logs de desenvolvimento
tail -f dev.log

# Ver logs de produção
tail -f server.log

# Verificar erros
npm run lint

🤝 Contribuição

Fork o projeto
Crie branch para sua feature: git checkout -b feature/nova-funcionalidade
Commit suas mudanças: git commit -m 'Add nova funcionalidade'
Push para o branch: git push origin feature/nova-funcionalidade
Abra um Pull Request

📝 Licença

Este projeto está sob licença MIT. Veja o arquivo LICENSE para detalhes.

🙏 Agradecimentos

Correios - Pelos dados de rastreamento
Next.js - Framework incrível
shadcn/ui - Componentes maravilhosos
Tailwind CSS - Styling poderoso

📞 Suporte

Email: gaoliveira2077@gmail.com
Github: https://github.com/gaog-dev/
Linkedin: https://linkedin.com/in/gaoliveira277/

Desenvolvido por Guilherme Oliveira

Este sistema utiliza os serviços dos Correios de acordo com seus termos de uso. Respeitamos rate limits e diretrizes de uso.

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
db		db
prisma		prisma
public		public
src		src
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
README.md		README.md
components.json		components.json
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
server.ts		server.ts
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json

gaog-dev/Rastreamento_API

Folders and files

Latest commit

History

Repository files navigation