📦 Documentação da API

Sistema de Gestão de Inventário com controle de movimentações, permissões e workflow de aprovação.

Autenticação

Token Bearer com Sanctum, verificação de licença integrada.

Workflow

Sistema de aprovação para todas as movimentações de itens.

Permissões

Controle granular baseado em roles e permissões específicas.

Base URL

https://estoque-api.tantotelecom.com.br/api

Headers Comuns

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

Autenticação

Todos os endpoints (exceto os públicos) requerem autenticação via Bearer Token.

POST

Login

/api/login

Autentica um usuário e retorna um token de acesso.

Permissões

Pública

Body Parameters
Parâmetro Tipo Obrigatório Descrição
email string Sim Email do usuário
password string Sim Senha do usuário
Exemplo de Requisição
POST /api/login

{
  "email": "admin@exemplo.com",
  "password": "senha123"
}
Exemplo de Resposta (200 OK)
200 OK 
{
  "access_token": "1|AbCdEfGhIjKlMnOpQrStUvWxYz1234567890",
  "token_type": "Bearer",
  "user": {
    "id": 1,
    "name": "Administrador",
    "email": "admin@exemplo.com",
    "role": "admin",
    "permissions": [
      "user-list",
      "user-create",
      "item-list",
      "item-create",
      "product-list",
      "product-create"
    ]
  }
}
Curl Example
curl -X POST \
-H "Content-Type: application/json" \
-d '{"email":"admin@exemplo.com","password":"senha123"}' \
https://estoque-api.tantotelecom.com.br/api/login
GET

Meus Dados

/api/me

Retorna informações do usuário atual e verifica status da licença.

Permissões

Autenticado

Headers
Authorization: Bearer {token}
Exemplo de Resposta (200 OK)
200 OK 
{
  "success": true,
  "message": "Dados do usuário obtidos com sucesso",
  "user": {
    "id": 1,
    "name": "Administrador",
    "email": "admin@exemplo.com",
    "role": "admin",
    "permissions": [...]
  },
  "license": {
    "status": "success",
    "expired": false,
    "expires_at": "2024-12-31"
  },
  "license_valid_until": "2024-12-31"
}
Resposta de Licença Expirada
200 OK 
{
  "success": false,
  "message": "Licença do sistema inválida ou expirada",
  "user": null,
  "license": {
    "status": "success",
    "expired": true,
    "expires_at": "2023-12-31"
  },
  "requires_logout": true,
  "logout_reason": "license_expired"
}

Códigos de Status HTTP

200 OK

Requisição bem-sucedida

201 Created

Recurso criado com sucesso

400 Bad Request

Erro na requisição do cliente

401 Unauthorized

Token inválido ou ausente

403 Forbidden

Usuário não tem permissão

422 Unprocessable Entity

Erro de validação nos dados

Fluxo de Trabalho

Os movimentos de itens seguem um sistema de aprovação:

1
Solicitação

Usuário solicita uma ação (checkout, checkin, assign, etc.)

2
Movimento Pendente

Sistema cria um movimento com status pending

3
Confirmação/Rejeição

Usuário autorizado confirma ou rejeita o movimento

4
Aplicação

Se confirmado, o item é atualizado; se rejeitado, nada muda

Gestão de Itens

GET

Listar Itens

/api/items

Retorna lista de itens com filtros avançados. Usuários não-admin veem apenas itens designados a si.

Permissões

item-list

Query Parameters
Parâmetro Tipo Obrigatório Descrição
product_id integer Não Filtrar por produto
category_id integer Não Filtrar por categoria
stock_status string Não disponivel, em_uso, reservado, baixado
condition_status string Não novo, usado, danificado, em_manutencao
search string Não Busca por código, serial ou nome do produto
Exemplo de Requisição
GET /api/items?stock_status=disponivel&category_id=1
Authorization: Bearer {token}
Exemplo de Resposta (200 OK)
200 OK 
{
  "data": [
    {
      "id": 1,
      "code": "NTB-DELL-001",
      "stock_status": "disponivel",
      "stock_status_label": "Disponível",
      "condition_status": "novo",
      "condition_status_label": "Novo",
      "product": {
        "id": 1,
        "name": "Notebook Dell Inspiron",
        "category": { "id": 1, "name": "Eletrônicos" }
      },
      "assigned_user": null,
      "serials": [
        { "serial_number": "SN123456", "type": { "name": "Serial Principal" } }
      ]
    }
  ],
  "totals": {
    "total_items": 100,
    "available_items": 80,
    "reserved_items": 10,
    "in_use_items": 5,
    "written_off_items": 5
  },
  "count": 10,
  "user_role": "admin"
}
POST

Solicitar Checkout

/api/items/{item}/request-checkout

Solicita retirada de um item. Cria movimento pendente para aprovação.

Permissões

item-checkout

Body Parameters
Parâmetro Tipo Obrigatório Descrição
notes string Não Observações sobre o checkout
metadata object Não Metadados adicionais
Exemplo de Requisição
POST /api/items/1/request-checkout
Authorization: Bearer {token}

{
  "notes": "Retirada para uso no projeto Alpha",
  "metadata": {
    "projeto": "Alpha",
    "prazo_devolucao": "2024-12-31"
  }
}
Exemplo de Resposta (200 OK)
200 OK 
{
  "message": "Solicitação de checkout criada. Aguardando confirmação.",
  "movement": {
    "id": 1,
    "item_id": 1,
    "user_id": 1,
    "movement_type": "checkout",
    "status": "pending",
    "notes": "Retirada para uso no projeto Alpha",
    "created_at": "2024-01-15T10:30:00.000000Z"
  },
  "item": {
    "id": 1,
    "code": "NTB-DELL-001",
    "stock_status": "disponivel"
  }
}
POST

Confirmar Movimento

/api/items/movements/{movement}/confirm

Confirma um movimento pendente. Atualiza o item se for confirmado.

Permissões

Baseado nas regras de confirmação

Regras de Confirmação
Exemplo de Requisição
POST /api/items/movements/1/confirm
Authorization: Bearer {token}
Content-Type: application/json
Exemplo de Resposta (200 OK)
200 OK 
{
  "message": "Movimento confirmado com sucesso.",
  "movement": {
    "id": 1,
    "item_id": 1,
    "status": "confirmed",
    "confirmed_at": "2024-01-15T10:35:00.000000Z",
    "reviewer_id": 2
  },
  "item": {
    "id": 1,
    "code": "NTB-DELL-001",
    "stock_status": "em_uso",
    "assigned_to": 1
  }
}

Dashboard & Relatórios

GET

Resumo do Dashboard

/api/dashboard/summary

Retorna dados para dashboard com gráficos e estatísticas.

Query Parameters
Parâmetro Tipo Obrigatório Descrição
date_from date Não Data inicial (YYYY-MM-DD)
date_to date Não Data final (YYYY-MM-DD)
user_id integer Não Filtrar por usuário (apenas admin/manager)
include_users boolean Não Incluir lista de usuários
Exemplo de Requisição
GET /api/dashboard/summary?date_from=2024-01-01&date_to=2024-01-31
Authorization: Bearer {token}
Exemplo de Resposta (200 OK)
200 OK 
{
  "chart_data": {
    "assign": { "rejected": 0, "pending": 2, "confirmed": 5 },
    "checkin": { "rejected": 1, "pending": 1, "confirmed": 3 },
    "checkout": { "rejected": 0, "pending": 0, "confirmed": 10 },
    "transfer": { "rejected": 0, "pending": 1, "confirmed": 2 }
  },
  "totals": {
    "assign": 7, "checkout": 10, "checkin": 5, "transfer": 3,
    "pending": 4, "confirmed": 20, "rejected": 1
  },
  "date_from": "2024-01-01",
  "date_to": "2024-01-31",
  "user_id": null,
  "is_filtered_by_current_user": false,
  "users": [
    { "id": 1, "name": "Admin", "email": "admin@exemplo.com" }
  ],
  "user_access": {
    "role": "admin",
    "has_full_access": true,
    "user_id": 1
  }
}

Gestão de Compras

GET

Listar Compras

/api/purchases

Retorna lista de compras com filtros.

Permissões

purchase-list

Query Parameters
Parâmetro Tipo Obrigatório Descrição
product_id integer Não Filtrar por produto
status string Não pendente, processando, concluida, cancelada
month integer Não Mês da compra (1-12)
year integer Não Ano da compra
search string Não Busca em nota fiscal, notas ou nome do produto
Exemplo de Resposta (200 OK)
200 OK 
{
  "data": [
    {
      "id": 1,
      "product_id": 1,
      "purchase_date": "2024-01-10",
      "unit_price": 5000.00,
      "quantity": 5,
      "total_price": 25000.00,
      "invoice_number": "NF001",
      "status": "processando",
      "items_count": 2,
      "remaining_quantity": 3,
      "product": {
        "id": 1,
        "name": "Notebook Dell"
      }
    }
  ]
}
POST

Gerar Itens da Compra

/api/purchases/{purchase}/generate-items

Gera itens a partir de uma compra. Com seriais se o modelo exigir.

Permissões

purchase-process

Exemplo para Modelo COM Seriais
POST /api/purchases/1/generate-items
Authorization: Bearer {token}

{
  "serials": [
    { "serial": "SN123456", "type_id": 1 },
    { "serial": "SN123457", "type_id": 2 }
  ]
}
Exemplo para Modelo SEM Seriais (em lote)
POST /api/purchases/1/generate-items
Authorization: Bearer {token}

{
  "generate_all": true,
  "without_serials": true
}
Exemplo de Resposta (200 OK)
200 OK 
{
  "message": "Item 1 gerado com 2 serial(is) com sucesso.",
  "item": {
    "id": 1,
    "code": "NTB-DELL-20240110-0001-001",
    "stock_status": "disponivel",
    "serials": [
      { "serial_number": "SN123456", "type": { "name": "Serial Principal" } },
      { "serial_number": "SN123457", "type": { "name": "Serial Secundário" } }
    ]
  },
  "remaining_items": 4,
  "purchase": {
    "id": 1,
    "status": "processando",
    "items_count": 1
  }
}

Gestão de Usuários

POST

Criar Usuário

/api/users

Cria um novo usuário no sistema.

Permissões

user-create

Body Parameters
Parâmetro Tipo Obrigatório Descrição
name string Sim Nome do usuário
email string Sim Email único
password string Sim Senha (mínimo 8 caracteres)
password_confirmation string Sim Confirmação da senha
role string Não Role para atribuir (ex: "user", "manager")
Exemplo de Requisição
POST /api/users
Authorization: Bearer {token}

{
  "name": "João Silva",
  "email": "joao@exemplo.com",
  "password": "senha123",
  "password_confirmation": "senha123",
  "role": "user"
}
Exemplo de Resposta (201 Created)
201 Created 
{
  "data": {
    "id": 2,
    "name": "João Silva",
    "email": "joao@exemplo.com",
    "role": "user",
    "permissions": ["item-list", "item-checkout"]
  }
}
GET

Status da API

/api/status

Verifica se a API está online.

Permissões

Pública

Exemplo de Resposta (200 OK)
200 OK 
{
  "status": "success"
}