API de Freelancing

Esta documentação define os endpoints, modelos de dados e rotas para a API da plataforma.

1. Autenticação (/api/auth)

Rotas para registro, login e gerenciamento de sessão. A autenticação será baseada em JWT (JSON Web Token).

2. Usuários (/api/users)

Rotas para gerenciar informações dos usuários. A maioria das ações aqui exige autenticação e, em alguns casos, permissão de administrador.

Modelo de Usuário (User Model) - Atualizado 


        {
        "id": "uuid-gerado-automaticamente",
        "role": "freelancer", // "client" || "admin"
        "email": "user@email.com", // Adicionado para login
        "username": "cool-user",
        "passwordHash": "hash_da_senha_com_bcrypt", // NUNCA armazene a senha em texto plano
        "name": "João Silva",
        "avatarUrl": "https://url-da-imagem.com/avatar.png",
        "createdAt": "2025-09-15T18:00:00Z", // Adicionado
        "updatedAt": "2025-09-15T18:00:00Z"  // Adicionado
        }

3. Perfis (/api/profiles)

Rotas para os detalhes do perfil, que são mais extensos que o modelo de usuário. Um perfil é criado automaticamente com o usuário.

Modelo de Perfil (Profile Model) 


        {
        "userId": "uuid-do-usuario-vinculado",
        "title": "Desenvolvedor Web Sênior | React & Node.js", // Título profissional
        "bio": "10 anos de experiência em desenvolvimento de aplicações web de alta performance...",
        "skills": ["React", "Node.js", "TypeScript", "PostgreSQL", "Docker"], // Array de strings
        "portfolio": [
        // Array de projetos no portfólio
        {
        "title": "E-commerce de Roupas",
        "description": "Desenvolvimento completo do front-end e back-end.",
        "url": "https://link-do-projeto.com"
        }
        ],
        "hourlyRate": 150, // Valor/hora em R$ (BRL)
        "country": "Brasil",
        "city": "Blumenau"
        }

4. Projetos (/api/projects)

Rotas para criar e gerenciar projetos postados por clientes.

Modelo de Projeto (Project Model) - Atualizado 


        {
        "id": "uuid-gerado-automaticamente",
        "clientId": "uuid-do-usuario-cliente", // Renomeado para clareza
        "freelancerId": null, // Preenchido quando uma proposta é aceita
        "title": "Desenvolvimento de Landing Page",
        "description": "Preciso de uma landing page responsiva com React e formulário de contato...", // Pode ser string longa ou markdown
        "budget": 1500, // Orçamento em R$ (BRL)
        "deadline": "2025-10-30T23:59:59Z", // Prazo final
        "skillsRequired": ["React", "HTML5", "CSS3", "UI/UX Design"],
        "status": "open", // "open", "in_progress", "completed", "cancelled"
        "createdAt": "2025-09-15T18:30:00Z",
        "updatedAt": "2025-09-15T18:30:00Z"
        }

5. Propostas (/api/proposals)

Rotas para que freelancers enviem propostas para projetos. As rotas são aninhadas dentro dos projetos para uma melhor organização.

Modelo de Proposta (Proposal Model) 


        {
        "id": "uuid-gerado-automaticamente",
        "projectId": "uuid-do-projeto",
        "freelancerId": "uuid-do-freelancer",
        "coverLetter": "Olá, tenho vasta experiência com React e posso entregar sua landing page em 10 dias...",
        "proposedPrice": 1400, // Valor proposto pelo freelancer
        "estimatedDays": 10, // Prazo estimado pelo freelancer
        "status": "pending", // "pending", "accepted", "rejected"
        "createdAt": "2025-09-16T09:00:00Z"
        }

6. Avaliações (/api/reviews)

Rotas para permitir que clientes e freelancers se avaliem após a conclusão de um projeto.

Modelo de Avaliação (Review Model) 


        {
        "id": "uuid-gerado-automaticamente",
        "projectId": "uuid-do-projeto-concluido",
        "reviewerId": "uuid-de-quem-avalia", // Pode ser o cliente ou o freelancer
        "revieweeId": "uuid-de-quem-e-avaliado", // Pode ser o freelancer ou o cliente
        "rating": 5, // Nota de 1 a 5
        "comment": "Ótimo trabalho! Entregou antes do prazo e com muita qualidade.",
        "createdAt": "2025-11-10T14:00:00Z"
        }

Você tem toda a razão! Peço desculpas, a parte de mensagens é absolutamente crucial.

Aqui está a seção que faltava, completando a especificação da API com o sistema de chat.

7. Mensagens (/api/conversations e /api/messages)

Rotas para gerenciar a comunicação direta entre usuários. A estrutura é baseada em “Conversas” (ou chats), que contêm as “Mensagens”. Uma conversa é tipicamente iniciada entre um cliente e um freelancer dentro do contexto de um projeto.

Rotas de Conversas

Rotas de Mensagens (Aninhadas em Conversas)

Modelo de Conversa (Conversation Model) 


        {
        "id": "uuid-gerado-automaticamente",
        "projectId": "uuid-do-projeto-relacionado",
        "participants": ["uuid-do-usuario-1", "uuid-do-usuario-2"],
        "lastMessage": {
        "content": "Ok, combinado! Começo amanhã.",
        "senderId": "uuid-do-usuario-1",
        "timestamp": "2025-09-18T10:30:00Z"
        },
        "createdAt": "2025-09-17T14:20:00Z",
        "updatedAt": "2025-09-18T10:30:00Z"
        }

Modelo de Mensagem (Message Model) 


        {
        "id": "uuid-gerado-automaticamente",
        "conversationId": "uuid-da-conversa-pai",
        "senderId": "uuid-de-quem-enviou",
        "content": "Claro, podemos discutir os detalhes. Qual o melhor horário para você?",
        "isRead": false,
        "createdAt": "2025-09-17T14:25:10Z"
        }

Nota Importante sobre Real-Time:
Enquanto a API REST é excelente para criar conversas e buscar o histórico, a entrega de mensagens em tempo real (a experiência de “chat”) deve ser implementada com WebSockets (usando bibliotecas como Socket.IO ou um serviço como Pusher). O fluxo seria:

  1. O usuário envia uma mensagem via POST /api/.../messages.
  2. O servidor salva a mensagem no banco de dados.
  3. O servidor emite um evento via WebSocket para o destinatário com os dados da nova mensagem.
  4. O frontend do destinatário recebe esse evento e exibe a mensagem instantaneamente, sem precisar fazer uma nova requisição GET.