RRBEC-LocalServer/GUIA_API.md

Guia de Teste da API com Postman

Este documento explica como testar os endpoints da API do sistema Gestão Raul utilizando o Postman.

---

1. Passo 1: Obter o Token de Acesso (Login)

Como a API é protegida, você precisa primeiro de um token de autorização.

1. Abra o Postman e crie uma nova aba de requisição.
2. Mude o método para POST.
3. Coloque a URL: http://localhost:8000/api/v1/token/
4. Vá na aba Body, selecione a opção raw e escolha JSON no menu à direita.
5. Insira suas credenciais no formato abaixo:

   {
       "username": "seu_usuario_django",
       "password": "sua_senha_django"
   }
   

6. Clique em Send.
7. No resultado (JSON), copie o código que aparece no campo "access".

---

2. Passo 2: Acessar os Endpoints da API

Agora que você tem o token, pode acessar qualquer endpoint protegido (ex: Pedidos).

1. Crie uma nova aba de requisição no Postman.
2. Mude o método para GET.
3. Coloque a URL do endpoint que deseja testar, por exemplo: http://localhost:8000/api/v1/orders/
4. Vá na aba Authorization (fica logo abaixo da URL).
5. No campo Type, selecione Bearer Token.
6. No campo Token (à direita), cole o código "access" que você copiou no Passo 1.
7. Clique em Send.

Você deverá ver a lista de dados em formato JSON.

---

Dicas Rápidas

• Erro 401 Unauthorized: Significa que o token não foi enviado corretamente ou expirou. Obtenha um novo no Passo 1.
• CORS: O backend está configurado para aceitar requisições de outras origens (CORS), permitindo que seu frontend se conecte normalmente.
• Endpoints Disponíveis:
  • /api/v1/orders/ (Pedidos)
  • /api/v1/products/ (Produtos)
  • /api/v1/clients/ (Clientes)
  • /api/v1/mesas/ (Mesas)
  • /api/v1/comandas/ (Comandas)
  • /api/v1/items-comanda/ (Itens de Comanda)
  • /api/v1/categories/ (Categorias)
  • /api/v1/payment-types/ (Tipos de Pagamento)
  • /api/v1/payments/ (Registro de Pagamentos)

---

3. Ações Especiais (Custom Actions)

Apagar/Limpar Comanda Inteira

Esta ação exclui todos os itens vinculados à comanda e muda o seu status para CLOSED.

• Método: POST
• URL: http://localhost:8000/api/v1/comandas/{ID_DA_COMANDA}/apagar/
• Auth: Bearer Token necessário.
• Body: Vazio.

Apagar um Item Individual da Comanda

Esta ação exclui um único item e devolve a quantidade correspondente ao estoque.

• Método: DELETE
• URL: http://localhost:8000/api/v1/items-comanda/{ID_DO_ITEM}/
• Auth: Bearer Token necessário.
• Body: Vazio.

Pagar e Fechar Comanda

Esta ação registra um pagamento e fecha a comanda automaticamente.

• Método: POST
• URL: http://localhost:8000/api/v1/comandas/{ID_DA_COMANDA}/pagar/
• Auth: Bearer Token necessário.
• Body (JSON):

  {
      "value": 50.00,
      "type_pay": 1,        // ID do tipo de pagamento
      "client": null,       // ID do cliente (opcional)
      "description": "Pagamento total" // Opcional
  }
  

Listar Fiados de um Cliente

Retorna todas as comandas com status FIADO vinculadas a um cliente específico.

• Método: GET
• URL: http://localhost:8000/api/v1/clients/{ID_DO_CLIENTE}/fiados/
• Auth: Bearer Token necessário.
• Body: Vazio.

Pagar Múltiplos Fiados

Recebe uma lista de IDs de comandas com status FIADO, gera os pagamentos e fecha todas.

• Método: POST
• URL: http://localhost:8000/api/v1/clients/pagar_fiados/
• Auth: Bearer Token necessário.
• Body (JSON):

  {
      "ids": [10, 11, 15]  // IDs das comandas que deseja pagar
  }
  

---

4. Gerenciamento de Pedidos (Orders)

Editar Observação do Pedido

Altera as observações de um pedido específico.

• Método: PATCH
• URL: http://localhost:8000/api/v1/orders/{ID_DO_PEDIDO}/
• Auth: Bearer Token necessário.
• Body (JSON):

  {
      "obs": "Nova observação detalhada"
  }
  

Atualizar Status do Pedido

Ações para movimentar o fluxo da cozinha/atendimento.

• Método: POST
• URLs:
  • .../api/v1/orders/{ID_DO_PEDIDO}/preparing/ (Iniciar Preparo)
  • .../api/v1/orders/{ID_DO_PEDIDO}/finish/ (Marcar como Pronto)
  • .../api/v1/orders/{ID_DO_PEDIDO}/deliver/ (Marcar como Entregue)
  • .../api/v1/orders/{ID_DO_PEDIDO}/cancel/ (Cancelar Pedido)
• Auth: Bearer Token necessário.
• Body: Vazio.