# API Routes Documentation

This document outlines the available endpoints based on the provided controllers (**LoginController** and **RegisterController**).

**Base URL Placeholder:** `http://localhost:8000`

---

## 1. User Login

Authenticates a user and returns a JWT token.

### **Endpoint**

`POST /login`

### **Headers**

`Content-Type: application/json`

### **Request Body (JSON)**

```json
{
  "email": "john.doe@example.com",
  "password": "securepassword123"
}
```

### **cURL Example**

```bash
curl --location 'http://localhost:8000/login' \
--header 'Content-Type: application/json' \
--data '{
    "email": "john.doe@example.com",
    "password": "securepassword123"
}'
```

### **Responses**

#### **200 OK (Success)**

```json
{
  "status": "ok",
  "msg": "[100] Request ok.",
  "code": "S_OK",
  "data": {
    "token": "<jwt>",
    "user_id": 1,
    "company_id": 1
  }
}
```

#### **401 Unauthorized (Missing fields or Invalid credentials)**

```json
{
  "status": "fail",
  "message": "Invalid credentials",
  "code": "E_VALIDATE"
}
```

---

## 2. User Register

Creates a new user account in the database.

### **Endpoint**

`POST /register`

### **Headers**

`Content-Type: application/json`

### **Request Body (JSON)**

```json
{
  "username": "John Doe",
  "email": "john.doe@example.com",
  "password": "securepassword123",
  "phone": "+15550199",
  "address": "123 Tech Street",
  "city": "Silicon Valley",
  "state": "CA",
  "zip": "94000",
  "country": "USA",
  "kyc": 1,
  "birthdate": 631152000,
  "cpf": "123.456.789-00",
  "company_id": 1,
  "role_id": 2
}
```

### **cURL Example**

```bash
curl --location 'http://localhost:8000/register' \
--header 'Content-Type: application/json' \
--data '{
  "username": "John Doe",
  "email": "john.doe@example.com",
  "password": "securepassword123",
  "phone": "+15550199",
  "address": "123 Tech Street",
  "city": "Silicon Valley",
  "state": "CA",
  "zip": "94000",
  "country": "USA",
  "kyc": 1,
  "birthdate": 631152000,
  "cpf": "123.456.789-00",
  "company_id": 1,
  "role_id": 1
}'
```

### **Responses**

#### **200 OK (Success)**

```json
{
  "status": "success",
  "code": "S_CREATED",
  "data": {
    "user_id": 45,
    "user_name": "John Doe",
    "user_email": "john.doe@example.com",
    "company_id": 1,
    "role_id": 2
  }
}
```

#### **400 Bad Request (Validation Errors)**

* Missing required fields
* Invalid email format
* Password too short (< 8 characters)
* Email already exists

```json
{
  "status": "fail",
  "message": "Missing field: phone",
  "code": "E_VALIDATE"
}
```


---

## 3. Create Company with User and Wallet

Creates a company, a user linked to it, and a wallet (address/publicKey/privateKey) in a single transaction. Public endpoint (no auth).

### **Endpoint**

`POST /companyWithUser/create`

### **Headers**

`Content-Type: application/json`

### **Request Body (JSON)**

```json
{
  "company_name": "Acme Corp",
  "username": "John Doe",
  "email": "john.doe@example.com",
  "password": "secret123",
  "phone": "+55 11 99999-9999",
  "address": "Rua A, 123",
  "city": "Sao Paulo",
  "state": "SP",
  "zip": "01234-567",
  "country": "BR",
  "kyc": 1,
  "birthdate": 631152000,
  "cpf": "123.456.789-00"
}
```

### **cURL Example**

```bash
curl --location 'http://localhost:8000/companyWithUser/create' \
  -H 'Content-Type: application/json' \
  --data '{
    "company_name": "Acme Corp",
    "username": "John Doe",
    "email": "john.doe@example.com",
    "password": "secret123",
    "phone": "+55 11 99999-9999",
    "address": "Rua A, 123",
    "city": "Sao Paulo",
    "state": "SP",
    "zip": "01234-567",
    "country": "BR",
    "kyc": 1,
    "birthdate": 631152000,
    "cpf": "123.456.789-00"
  }'
```

### **Responses**

#### **200 OK (Success)**

```json
{
  "status": "ok",
  "msg": "[100] Request ok.",
  "code": "S_CREATED",
  "data": {
    "company_id": 1,
    "role_id": 1,
    "user": {
      "user_id": 1,
      "user_name": "John Doe",
      "user_email": "john.doe@example.com",
      "company_id": 1,
      "role_id": 1
    },
    "wallet_id": 1,
    "wallet_address": "0x8AC9615b1a555BeA2938778aAef1ead35205c167"
  }
}
```

#### **400 Bad Request (Validation Errors)**

```json
{
  "status": "failed",
  "msg": "Password must be at least 8 characters",
  "code": "E_VALIDATE",
  "data": []
}
```

#### **500 Internal Server Error (Wallet/DB issues)**

```json
{
  "status": "failed",
  "msg": "Wallet generation failed",
  "code": "E_INTERNAL",
  "data": []
}
```


---

## 4. Change User Email

Updates the authenticated user's email. Requires JWT.

### **Endpoint**

`POST /user/change-email`

### **Headers**

`Content-Type: application/json`

`Authorization: Bearer <JWT>`

### **Request Body (JSON)**

```json
{
  "email": "new.email@example.com"
}
```

### **cURL Example**

```bash
curl --location 'http://localhost:8000/user/change-email' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <JWT>' \
  --data '{"email":"new.email@example.com"}'
```

### **Responses**

#### **200 OK (Updated)**

```json
{
  "status": "ok",
  "msg": "[100] Request ok.",
  "code": "S_UPDATED",
  "data": {
    "user_id": 1,
    "user_email": "new.email@example.com"
  }
}
```

#### **400 Bad Request (Validation Errors)**

```json
{
  "status": "failed",
  "msg": "Email already in use or update failed",
  "code": "E_VALIDATE",
  "data": []
}
```

#### **401 Unauthorized**

```json
{
  "status": "failed",
  "msg": "Unauthorized",
  "code": "E_VALIDATE",
  "data": []
}
```


---

## 5. Change User Password

Changes the authenticated user's password. Requires JWT.

### **Endpoint**

`POST /user/change-password`

### **Headers**

`Content-Type: application/json`

`Authorization: Bearer <JWT>`

### **Request Body (JSON)**

```json
{
  "current_password": "minhaSenhaAtual",
  "new_password": "novaSenhaForte123"
}
```

### **cURL Example**

```bash
curl --location 'http://localhost:8000/user/change-password' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <JWT>' \
  --data '{"current_password":"minhaSenhaAtual","new_password":"novaSenhaForte123"}'
```

### **Responses**

#### **200 OK (Updated)**

```json
{
  "status": "ok",
  "msg": "[100] Request ok.",
  "code": "S_UPDATED",
  "data": {
    "user_id": 1
  }
}
```

#### **400 Bad Request (Validation Errors)**

```json
{
  "status": "failed",
  "msg": "Invalid current password or update failed",
  "code": "E_VALIDATE",
  "data": []
}
```

#### **401 Unauthorized**

```json
{
  "status": "failed",
  "msg": "Unauthorized",
  "code": "E_VALIDATE",
  "data": []
}
```

## 6. Commodities — List

Returns a list of commodities filtered by `flag` or all if `flag=all`.

### **Endpoint**

`GET /commodities`

### **cURL Example**

```bash
curl --location 'http://localhost:8000/commodities?flag=all'
```

### **Responses**

#### **200 OK**

```json
{
  "status": "ok",
  "msg": "[100] Request ok.",
  "code": "S_OK",
  "data": [
    {
      "commodities_id": 1,
      "name": "Gold",
      "flag": "a"
    }
  ]
}
```

#### **204 No Content**

```json
{
  "status": "fail",
  "msg": "Commodities Not Found",
  "code": "E_DATABASE",
  "data": []
}
```

---

## 7. Commodity Create

Creates a new commodity.

### **Endpoint**

`POST /commodity/create`

### **Headers**

`Content-Type: application/json`

### **Request Body (JSON)**

```json
{
  "name": "Gold",
  "flag": "a"
}
```

### **cURL Example**

```bash
curl --location 'http://localhost:8000/commodity/create' \
  -H 'Content-Type: application/json' \
  --data '{
    "name": "Gold",
    "flag": "a"
  }'
```

### **Responses**

#### **200 OK (Created)**

```json
{
  "status": "ok",
  "msg": "[100] Request ok.",
  "code": "S_CREATED",
  "data": {
    "commodities_id": 10,
    "name": "Gold",
    "flag": "a"
  }
}
```

#### **400 Bad Request (Missing name)**

```json
{
  "status": "fail",
  "msg": "Validation failed: name is required",
  "code": "E_VALIDATE",
  "data": []
}
```

---

## 8. Commodity Update

Updates an existing commodity.

### **Endpoint**

`POST /commodity/update`

### **Headers**

`Content-Type: application/json`

### **Request Body (JSON)**

```json
{
  "commodities_id": 10,
  "name": "Silver",
  "flag": "b"
}
```

You may send **only name**, **only flag**, or both.

### **cURL Example**

```bash
curl --location 'http://localhost:8000/commodity/update' \
  -H 'Content-Type: application/json' \
  --data '{
    "commodities_id": 10,
    "name": "Silver",
    "flag": "b"
  }'
```

### **Responses**

#### **200 OK**

```json
{
  "status": "ok",
  "msg": "[100] Request ok.",
  "code": "S_UPDATED",
  "data": {
    "commodities_id": 10,
    "name": "Silver",
    "flag": "b"
  }
}
```

#### **400 Bad Request**

* Missing commodities_id
* Empty name
* No fields to update

```json
{
  "status": "fail",
  "msg": "Validation failed: nothing to update",
  "code": "E_VALIDATE",
  "data": []
}
```

#### **204 No Content**

```json
{
  "status": "fail",
  "msg": "Commodity Not Found or Not Updated",
  "code": "E_DATABASE",
  "data": []
}
```

---

## 9. Commodity Delete

Deletes a commodity by ID.

### **Endpoint**

`POST /commodity/delete`

### **Headers**

`Content-Type: application/json`

### **Request Body (JSON)**

```json
{
  "commodities_id": 10
}
```

### **cURL Example**

```bash
curl --location 'http://localhost:8000/commodity/delete' \
  -H 'Content-Type: application/json' \
  --data '{"commodities_id":10}'
```

### **Responses**

#### **200 OK (Deleted)**

```json
{
  "status": "ok",
  "msg": "[100] Request ok.",
  "code": "S_DELETED",
  "data": {
    "deleted": true
  }
}
```

#### **400 Bad Request**

```json
{
  "status": "fail",
  "msg": "Validation failed: invalid commodities_id",
  "code": "E_VALIDATE",
  "data": []
}
```

#### **204 No Content**

```json
{
  "status": "fail",
  "msg": "Commodity Not Found",
  "code": "E_DATABASE",
  "data": []
}
```
