📘 API ResolveJá – Documentação

Esta documentação descreve os principais endpoints da API para clientes e prestadores, incluindo autenticação, serviços e pedidos.

🔑 Autenticação & Registro

Registro de Cliente

POST domain/api/register

Headers

Content-Type: application/json

Body

{
  "name": "João Cliente",
  "email": "joao@example.com",
  "password": "123456",
  "phone": "900000001",
  "role": "cliente"
}

Registro de Prestador

POST domain/api/register

Headers

Content-Type: application/json
Accept: application/json

Body

{
  "name": "Teste",
  "email": "provider@example.com",
  "phone": "99999999",
  "password": "123456",
  "password_confirmation": "123456",
  "role": "provider"
}

Login

POST domain/api/login

Headers

Content-Type: application/json

Body

{
  "email": "provider@example.com",
  "password": "123456"
}

Resposta (exemplo)

{
  "token": "5|SeAdY03gxnjCVXrOP6tp02j2N9riqP64gVucptaL6c8d81ed",
  "user": {
    "id": 1,
    "name": "Teste",
    "role": "provider"
  }
}

🛠️ Criar Serviço do Prestador (Provider Service)

Endpoint usado para o prestador cadastrar o seu serviço, incluindo fotos em Base64.

Endpoint

POST domain/api/provider-services

Headers

Content-Type: application/json
Authorization: Bearer {TOKEN}
Accept: application/json

Body

{
  "provider_id": 1,
  "service_id": 1,
  "category_id": 1,
  "price_range": "10.000 - 20.000 Kz",
  "description": "Manutenção e instalação de equipamentos",
  "is_active": true,
  "photos": [
    "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAASABIAA...",
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  ]
}

Observações:

category_id é obrigatório e deve referenciar uma categoria existente em service_categories.
photos é opcional e recebe um array de imagens em Base64.
Cada imagem será salva no servidor e associada ao serviço via tabela provider_service_images.
O usuário autenticado deve ser o próprio prestador.

Resposta (exemplo)

{
  "message": "Serviço cadastrado com sucesso",
  "data": {
    "id": 3,
    "provider_id": 1,
    "service_id": 1,
    "price_range": "10.000 - 20.000 Kz",
    "description": "Manutenção e instalação de equipamentos",
    "is_active": true,
    "created_at": "2025-11-25T12:00:00.000000Z",
    "updated_at": "2025-11-25T12:00:00.000000Z",
    "images": [
      "https://domain.com/imagens/9837sd87sd.jpg",
      "https://domain.com/imagens/77asdas8d7sa.png"
    ]
  }
}

🔍 Serviços

Buscar serviços por localização + nome

GET domain/api/services?lat=-8.838&lng=13.234&service_name=canaliz

Retorna prestadores e serviços filtrados por latitude, longitude e nome do serviço.

Buscar todos os serviços (sem filtros)

GET domain/api/services

Retorna todos os serviços cadastrados com seus respectivos prestadores.

Detalhe de um serviço

GET domain/api/services/1

Retorna as informações detalhadas de um serviço específico.

📁 Categorias

Listar todas as categorias

GET domain/api/categories

Headers

Accept: application/json

Retorna todas as categorias disponíveis para serem utilizadas ao cadastrar serviços de prestadores.

Resposta (exemplo)

{
  "success": true,
  "count": 5,
  "data": [
    {
      "id": 1,
      "name": "Canalização",
      "created_at": "2025-09-01T10:00:00.000000Z",
      "updated_at": "2025-09-01T10:00:00.000000Z"
    },
    {
      "id": 2,
      "name": "Eletricidade",
      "created_at": "2025-09-01T10:00:00.000000Z",
      "updated_at": "2025-09-01T10:00:00.000000Z"
    }
  ]
}

Observações:

Este endpoint não requer autenticação.
As categorias retornadas devem ser usadas no campo category_id ao criar um Provider Service.

📦 Pedidos (Requests)

Criar novo pedido

POST domain/api/requests

Headers

Content-Type: application/json
Authorization: Bearer {TOKEN}
Accept: application/json

Body

{
  "service_provider_id": 1,
  "description": "teste",
  "location": "Luanda, Vila Alice"
}

Resposta (exemplo)

{
  "message": "Pedido criado com sucesso!",
  "data": {
    "id": 15,
    "client_id": 2,
    "provider_id": 1,
    "service_id": 1,
    "status": "pending",
    "description": "teste",
    "location": "Luanda, Vila Alice",
    "scheduled_at": null,
    "created_at": "2025-09-03T20:15:10.000000Z",
    "updated_at": "2025-09-03T20:15:10.000000Z"
  }
}

Listar pedidos do cliente autenticado

GET domain/api/requests

Headers

Authorization: Bearer {TOKEN}
Accept: application/json

Resposta (exemplo)

{
  "success": true,
  "count": 2,
  "data": [
    {
      "id": 15,
      "service": {
        "id": 1,
        "name": "Canalização",
        "category": "Serviços Domésticos"
      },
      "provider": {
        "id": 1,
        "name": "Prestador Teste"
      },
      "status": "pending",
      "location": "Luanda, Vila Alice",
      "created_at": "2025-09-03T20:15:10.000000Z"
    }
  ]
}

🔄 Atualizar Estado de um Pedido

Este endpoint permite alterar o estado de um pedido conforme o tipo do usuário autenticado:

Regras de Permissão

Provider pode alterar para:
accepted, in_progress, completed
Cliente só pode alterar para:
cancelled

📌 Estados Possíveis

pending – Criado pelo cliente, aguardando ação do provider
accepted – Provider aceitou o pedido
- ⚠️ Ação automática: Chat é criado automaticamente e mensagem de boas-vindas é enviada do prestador para o cliente
in_progress – Provider iniciou o trabalho
completed – Provider concluiu o serviço
- ⚠️ Ação automática: Mensagem solicitando avaliação de satisfação é enviada automaticamente
cancelled – Cancelado pelo cliente

📡 Endpoint

PUT domain/api/requests/{id}/status

Headers

Content-Type: application/json
Authorization: Bearer {TOKEN}
Accept: application/json

Body

{
  "status": "accepted"
}

✔ Exemplo de Resposta (Provider)

{
  "message": "Status atualizado com sucesso",
  "data": {
    "id": 15,
    "status": "accepted",
    "updated_at": "2025-12-06T11:22:10.000000Z"
  }
}

✔ Exemplo de Resposta (Cliente cancelando)

{
  "message": "Pedido cancelado com sucesso",
  "data": {
    "id": 15,
    "status": "cancelled"
  }
}

❌ Exemplo de resposta não permitida

{
  "message": "Clientes só podem cancelar pedidos."
}

📋 Listar Planos

Retorna todos os planos disponíveis para subscrição por parte dos prestadores.

📡 Endpoint

GET domain/api/plans

Headers

Accept: application/json

✔ Exemplo de Resposta

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Plano Mensal",
      "price": "15000.00",
      "duration_days": 30,
      "features": [
        "Mais visibilidade",
        "Destaque nas buscas"
      ]
    },
    {
      "id": 2,
      "name": "Plano Trimestral",
      "price": "40000.00",
      "duration_days": 90,
      "features": [
        "Economia 10%",
        "Maior prioridade"
      ]
    }
  ]
}

📝 Criar Subscrição

O prestador escolhe um plano e envia o comprovativo de pagamento para validação no backoffice.

📡 Endpoint

POST domain/api/subscriptions

Headers

Accept: application/json
Authorization: Bearer
Content-Type: multipart/form-data

📦 Body (multipart/form-data)

plan_id: 1
proof_file: (jpg, png, jpeg, pdf)

✔ Exemplo via REST Client

POST domain/api/subscriptions
Authorization: Bearer TOKEN
Content-Type: multipart/form-data

--boundary
Content-Disposition: form-data; name="plan_id"

1
--boundary
Content-Disposition: form-data; name="proof_file"; filename="comprovativo.jpg"
Content-Type: image/jpeg

< /caminho/local/do/ficheiro/comprovativo.jpg
--boundary--

✔ Exemplo de Resposta

{
  "message": "Subscrição criada e enviada para validação.",
  "data": {
    "id": 8,
    "plan_id": 1,
    "status": "pending_validation",
    "proof_file": "uploads/proofs/proof_8.jpg"
  }
}

📄 Minha Subscrição (My Subscription)

Retorna a subscrição ativa do prestador autenticado, incluindo informações do plano, datas e status.

📡 Endpoint

GET domain/api/subscriptions

Headers

Authorization: Bearer
Accept: application/json

✔ Exemplo de Resposta (Prestador com subscrição ativa)

{
  "success": true,
  "subscription": {
    "id": 5,
    "provider_id": 12,
    "plan": {
      "id": 1,
      "name": "Plano Mensal",
      "price": "15000.00",
      "duration_days": 30,
      "features": [
        "Destaque nas buscas",
        "Atendimento prioritário",
        "Mais pedidos"
      ]
    },
    "status": "active",
    "start_date": "2025-12-01",
    "end_date": "2026-01-01"
  }
}

✔ Exemplo sem subscrição

{
  "success": true,
  "subscription": null,
  "message": "Nenhuma subscrição ativa encontrada."
}

💬 Chat entre Cliente e Prestador

❗ Regra Crítica

O chat só pode ser criado e utilizado quando a reserva (request) estiver no status accepted.

Regras de Acesso

Apenas o cliente do serviço pode enviar e ler mensagens
Apenas o prestador do serviço pode enviar e ler mensagens

🤖 Mensagens Automáticas

Quando o prestador aceita o serviço: O chat é criado automaticamente e uma mensagem de boas-vindas é enviada do prestador para o cliente
Quando o serviço é concluído: Uma mensagem automática é enviada solicitando avaliação de satisfação

Criar Chat

POST domain/api/chats

Headers

Content-Type: application/json
Authorization: Bearer {TOKEN}
Accept: application/json

Body

{
  "request_id": 1
}

Resposta (exemplo)

{
  "message": "Chat criado com sucesso.",
  "data": {
    "id": 1,
    "request_id": 1,
    "created_at": "2025-12-06T10:30:00.000000Z",
    "request": {
      "id": 1,
      "status": "accepted"
    },
    "messages": []
  }
}

❌ Erro se request não estiver 'accepted'

{
  "message": "O chat só pode ser criado quando a reserva estiver no status \"accepted\".",
  "current_status": "pending"
}

Ver Histórico do Chat

GET domain/api/chats/{id}

Headers

Authorization: Bearer {TOKEN}
Accept: application/json

Resposta (exemplo)

{
  "chat": {
    "id": 1,
    "request_id": 1,
    "request_status": "accepted",
    "created_at": "2025-12-06T10:30:00.000000Z"
  },
  "messages": [
    {
      "id": 1,
      "sender": {
        "id": 2,
        "name": "João Cliente",
        "email": "joao@example.com"
      },
      "message_text": "Olá, quando podemos agendar?",
      "message_type": "text",
      "sent_at": "2025-12-06T10:35:00.000000Z",
      "created_at": "2025-12-06T10:35:00.000000Z"
    },
    {
      "id": 2,
      "sender": {
        "id": 1,
        "name": "Prestador Teste",
        "email": "provider@example.com"
      },
      "message_text": "Podemos agendar para amanhã às 14h.",
      "message_type": "text",
      "sent_at": "2025-12-06T10:40:00.000000Z",
      "created_at": "2025-12-06T10:40:00.000000Z"
    }
  ],
  "participants": {
    "client": {
      "id": 2,
      "name": "João Cliente"
    },
    "provider": {
      "id": 1,
      "name": "Prestador Teste"
    }
  }
}

Enviar Mensagem

POST domain/api/chats/{id}/messages

Headers

Content-Type: application/json
Authorization: Bearer {TOKEN}
Accept: application/json

Body

{
  "message_text": "Olá, quando podemos agendar o serviço?",
  "message_type": "text"
}

Tipos de mensagem: text, image, file

Resposta (exemplo)

{
  "message": "Mensagem enviada com sucesso.",
  "data": {
    "id": 3,
    "sender": {
      "id": 2,
      "name": "João Cliente",
      "email": "joao@example.com"
    },
    "message_text": "Olá, quando podemos agendar o serviço?",
    "message_type": "text",
    "sent_at": "2025-12-06T10:45:00.000000Z",
    "created_at": "2025-12-06T10:45:00.000000Z"
  }
}

❌ Erro se request não estiver 'accepted'

{
  "message": "Mensagens só podem ser enviadas quando a reserva estiver no status \"accepted\".",
  "current_status": "pending"
}

⚡ Chat em Tempo Real (WebSocket)

O sistema utiliza Laravel Broadcasting para comunicação em tempo real. Quando uma mensagem é enviada, um evento é disparado automaticamente para todos os participantes do chat.

Configuração Necessária

Configure o driver de broadcasting no arquivo .env:

BROADCAST_DRIVER=pusher
PUSHER_APP_ID=your-app-id
PUSHER_APP_KEY=your-app-key
PUSHER_APP_SECRET=your-app-secret
PUSHER_APP_CLUSTER=mt1

Canal Privado

Cada chat utiliza um canal privado: private-chat.{chatId}

Apenas o cliente e o prestador do serviço podem acessar o canal.

Evento Broadcast

Quando uma mensagem é enviada, o evento message.sent é disparado no canal privado com os seguintes dados:

{
  "id": 3,
  "chat_id": 1,
  "sender": {
    "id": 2,
    "name": "João Cliente",
    "email": "joao@example.com"
  },
  "message_text": "Olá, quando podemos agendar?",
  "message_type": "text",
  "sent_at": "2025-12-06T10:45:00.000000Z",
  "created_at": "2025-12-06T10:45:00.000000Z"
}

Integração Flutter

Para integrar com Flutter, use o pacote pusher_channels_flutter ou laravel_echo:

// Exemplo com pusher_channels_flutter
import 'package:pusher_channels_flutter/pusher_channels_flutter.dart';

// Conectar ao Pusher
final pusher = PusherChannelsFlutter.getInstance();
await pusher.init(
  apiKey: 'YOUR_PUSHER_KEY',
  cluster: 'mt1',
  onConnectionStateChange: onConnectionStateChange,
  onError: onError,
  onSubscriptionSucceeded: onSubscriptionSucceeded,
  onEvent: onEvent,
  onSubscriptionError: onSubscriptionError,
  onDecryptionFailure: onDecryptionFailure,
  onMemberAdded: onMemberAdded,
  onMemberRemoved: onMemberRemoved,
);

// Autenticar e subscrever ao canal privado
await pusher.subscribe(
  channelName: 'private-chat.1',
  onEvent: (event) {
    if (event.eventName == 'message.sent') {
      // Processar nova mensagem recebida
      final messageData = jsonDecode(event.data);
      // Atualizar UI com nova mensagem
    }
  },
);

// Autenticação do canal privado
// Você precisa implementar um endpoint de autenticação
// POST /broadcasting/auth com o token do usuário

Endpoint de Autenticação

O Laravel já fornece automaticamente o endpoint de autenticação em:

POST /broadcasting/auth

Envie o token de autenticação no header Authorization: Bearer {TOKEN} e o nome do canal no body.

⭐ Avaliações (Reviews)

Regras de Avaliação

Apenas o cliente pode avaliar o serviço
Apenas é possível avaliar serviços com status completed
Cada serviço pode ser avaliado apenas uma vez
A avaliação atualiza automaticamente o rating médio do prestador

Criar Avaliação

POST domain/api/reviews

Headers

Content-Type: application/json
Authorization: Bearer {TOKEN}
Accept: application/json

Body

{
  "request_id": 1,
  "rating": 5,
  "comment": "Excelente serviço! Muito profissional e pontual."
}

Parâmetros:

request_id (obrigatório) - ID do pedido concluído
rating (obrigatório) - Nota de 1 a 5
comment (opcional) - Comentário sobre o serviço (máx. 1000 caracteres)

Resposta (exemplo)

{
  "message": "Avaliação criada com sucesso.",
  "data": {
    "id": 1,
    "request_id": 1,
    "client_id": 2,
    "provider_id": 1,
    "rating": 5,
    "comment": "Excelente serviço! Muito profissional e pontual.",
    "created_at": "2025-12-06T12:00:00.000000Z",
    "client": {
      "id": 2,
      "name": "João Cliente"
    },
    "provider": {
      "id": 1,
      "name": "Prestador Teste"
    }
  }
}

❌ Erro se serviço não estiver concluído

{
  "message": "Apenas é possível avaliar serviços concluídos.",
  "current_status": "in_progress"
}

❌ Erro se já foi avaliado

{
  "message": "Este serviço já foi avaliado.",
  "data": { ... }
}

Listar Avaliações de um Prestador

GET domain/api/providers/{id}/reviews

Headers

Accept: application/json

Resposta (exemplo)

{
  "success": true,
  "stats": {
    "total": 15,
    "average": 4.5,
    "distribution": {
      "5": 8,
      "4": 5,
      "3": 2,
      "2": 0,
      "1": 0
    }
  },
  "data": [
    {
      "id": 1,
      "request_id": 1,
      "client_id": 2,
      "provider_id": 1,
      "rating": 5,
      "comment": "Excelente serviço!",
      "created_at": "2025-12-06T12:00:00.000000Z",
      "client": {
        "id": 2,
        "name": "João Cliente"
      },
      "request": {
        "id": 1,
        "service": {
          "id": 1,
          "name": "Canalização"
        }
      }
    }
  ]
}

📌 Observações

O campo role no registro define se o usuário é cliente ou provider.
Authorization deve ser sempre enviado como:
```
Bearer {TOKEN}
```
O campo service_provider_id faz referência à tabela provider_services.
O campo scheduled_at pode ser usado para agendamentos futuros (ex.: "2025-09-05 15:00:00").