routes.md 23 KB

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)

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

cURL Example

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

Responses

200 OK (Success)

{
  "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)

{
  "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)

{
  "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": "12345678900",
  "company_id": 1,
  "role_id": 2
}

cURL Example

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": "12345678900",
  "company_id": 1,
  "role_id": 1
}'

Responses

200 OK (Success)

{
  "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

    {
    "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 /company/user/create

Headers

Content-Type: application/json

Request Body (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",
  "cnpj": "00000000000001"
}

cURL Example

curl --location 'http://localhost:8000/company/user/create' \
  -H 'Content-Type: application/json' \
  --data '{
    "company_name": "MixTech",
    "username": "LuvasLuvas",
    "email": "Luvas@email.com",
    "password": "secret123",
    "phone": "+55 16 93939-2222",
    "address": "Rua A, 123",
    "city": "Sao Paulo",
    "state": "SP",
    "zip": "01234-567",
    "country": "BR",
    "kyc": 1,
    "birthdate": 631152000,
    "cpf": "12345678900",
    "cnpj": "00000000000030"
  }'

Responses

200 OK (Success)

{
  "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)

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

500 Internal Server Error (Wallet/DB issues)

{
  "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)

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

cURL Example

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)

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

400 Bad Request (Validation Errors)

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

401 Unauthorized

{
  "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)

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

cURL Example

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)

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

400 Bad Request (Validation Errors)

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

401 Unauthorized

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

6. Commodities — List

Returns all commodities. No request body required. Requires JWT.

Endpoint

POST /commodities/get

Headers

Authorization: Bearer <JWT>

cURL Example

curl --location -X POST 'http://localhost:8000/commodities/get' \
  -H 'Authorization: Bearer <JWT>'

Responses

200 OK

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

204 No Content

{
  "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)

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

cURL Example

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

Responses

200 OK (Created)

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

400 Bad Request (Missing name)

{
  "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)

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

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

cURL Example

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

Responses

200 OK

{
  "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

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

204 No Content

{
  "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)

{
  "commodities_id": 10
}

cURL Example

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

Responses

200 OK (Deleted)

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

400 Bad Request

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

204 No Content

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

10. Token Get

Returns all tokens filtered by token_uf and commodities_name. Requires JWT.

Endpoint

POST /token/get

Headers

Content-Type: application/json

Authorization: Bearer <JWT>

Request Body (JSON)

{
  "token_uf": "SP",
  "commodities_name": "soja"
}

cURL Example

curl --location 'http://localhost:8000/token/get' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <JWT>' \
  --data '{
  "token_uf": "SP",
  "commodities_name": "soja"
}'

Responses

200 OK

{
  "status": "ok",
  "msg": "[100] Request ok.",
  "code": "S_OK",
  "data": [
    {
      "token_id": 1,
      "token_external_id": "abc123",
      "token_commodities_amount": 1000,
      "token_commodities_value": 5000,
      "token_uf": "SP",
      "token_city": "Sao Paulo",
      "token_content": "financial instrument",
      "token_flag": "a",
      "wallet_id": 1,
      "chain_id": 1,
      "commodities_id": 1,
      "cpr_id": 1,
      "user_id": 1
    }
  ]
}

204 No Content

{
  "status": "fail",
  "msg": "Token Not Found",
  "code": "E_DATABASE",
  "data": []
}

11. B3 — CPR Register

Receives a CPR payload in the flat format used by our database, saves it in the cpr table, converts it to the B3 nested format, automatically obtains a B3 access token (mTLS), and sends it to the B3 CPR registration endpoint.

Endpoint

POST /b3/cpr/register

Headers

Content-Type: application/json

Authorization: Bearer <JWT>

Request Body (JSON)

{
  "cpr": {
    "cpr_type_code": "P",
    "cpr_otc_register_account_code": "64359.40-5",
    "cpr_otc_payment_agent_account_code": "64359.40-5",
    "cpr_otc_custodian_account_code": "64359.00-3",
    "cpr_internal_control_number": "NA",
    "cpr_electronic_emission_indicator": "SIM",
    "cpr_isin_code": "NA",
    "cpr_issue_date": "2025-11-28",
    "cpr_maturity_date": "2026-09-30",
    "cpr_issue_quantity": 1,
    "cpr_issue_value": 1710000.00,
    "cpr_issue_financial_value": 1710000.00,
    "cpr_unit_value": 1710000.00,
    "cpr_reference_date": "2025-12-09",
    "cpr_profitability_start_date": "2025-12-09",
    "cpr_automatic_expiration_indicator": "NÃO",
    "cpr_collateral_type_code": "Penhor",
    "cpr_collateral_type_name": "NA",
    "cpr_constitution_process_indicator": "SIM",
    "cpr_otc_bondsman_account_code": "NA",
    "cpr_collaterals_document_number": "NA",
    "cpr_product_name": "MILHO",
    "cpr_product_class_name": "MILHO (EM GRAOS)",
    "cpr_product_harvest": "2026/2026",
    "cpr_product_description": "Milho brasileiro em grãos, tipo exportação.",
    "cpr_product_quantity": 2700000,
    "cpr_measure_unit_name": "QUILO",
    "cpr_packaging_way_name": "SACA (60 KG)",
    "cpr_product_status_code": "A PRODUZIR",
    "cpr_production_type_code": "PROPRIA",
    "cpr_issuer_name": "MARCELO VINCENZI",
    "cpr_finality_code": "NA",
    "cpr_ipoc_code": "NA",
    "cpr_calculation_type_code": "NA",
    "cpr_initial_exchange_value": "NA",
    "cpr_fixing_type_code": "NA",
    "cpr_data_source_type_code": "NA",
    "cpr_adjustment_frequency_type_code": "NA",
    "cpr_adjustment_pro_rata_type_code": "NA",
    "cpr_adjustment_type_code": "NA",
    "cpr_creditor_name": "TOO EASY TRADING LTDA",
    "cpr_ballast_type_code": "NA",
    "cpr_lot_number": "NA",
    "cpr_ballast_quantity": "NA",
    "cpr_currency_code": "NA",
    "cpr_transaction_identification": "NA",
    "cpr_additional_text": "NA",
    "cpr_number": "NA",
    "cpr_contract_number": "NA",
    "cpr_event_type_code": "NA",
    "cpr_event_original_date": "NA",
    "cpr_unit_price_value": 1710000.00,
    "cpr_interest_unit_price_value": 0.00,
    "cpr_residual_value": "NA",
    "cpr_amortization_percentage": "NA",
    "cpr_event_quantity": "NA",
    "cpr_production_place_name": "FAZENDA CORAÇÃO DE MARIA",
    "cpr_property_registration_number": "14406",
    "cpr_notary_name": "NA",
    "cpr_total_production_area_in_hectares_number": "NA",
    "cpr_total_area_in_hectares_number": 670,
    "cpr_car_code": "NA",
    "cpr_latitude_code": "NA",
    "cpr_longitude_code": "NA",
    "cpr_zip_code": "78560000",
    "cpr_green_cpr_indicator": "NA",
    "cpr_green_cpr_certificate_name": "NA",
    "cpr_green_cpr_certificate_cnpj_number": "NA",
    "cpr_green_cpr_georeferencing_description": "NA",
    "cpr_green_cpr_declaration_indicator": "NA",
    "cpr_document_deadline_days_number": "NA",
    "cpr_place_name": "NA",
    "cpr_guarantee_limit_type_code": "NA",
    "cpr_mother_code": "NA",
    "cpr_issuers_person_type_acronym": "PF",
    "cpr_issuers_state_acronym": "MT",
    "cpr_issuers_city_name": "SINOP",
    "cpr_issuers_ibge_code": "NA",
    "cpr_issuer_legal_nature_code": "02",
    "cpr_otc_favored_account_code": "64359.00-3",
    "cpr_issuers_document_number": "867.308.271-49",
    "cpr_deposit_person_type_acronym": "PF",
    "cpr_self_number": "NA",
    "cpr_settlement_modality_type_code": "NA",
    "cpr_otc_settlement_bank_account_code": "NA",
    "cpr_deposit_quantity": 1,
    "cpr_deposit_unit_price_value": "NA",
    "cpr_payment_method_code": "NA",
    "cpr_index_code": "NA",
    "cpr_index_short_name": "NA",
    "cpr_vcp_indicator_type_code": "NA",
    "cpr_indexador_percentage_value": "NA",
    "cpr_interest_rate_spread_percentage": "NA",
    "cpr_interest_rate_criteria_type_code": "NA",
    "cpr_interest_payment_date": "NA",
    "cpr_interest_payment_value": "NA",
    "cpr_interest_payment_frequency_code": "NA",
    "cpr_interest_months_quantity": "NA",
    "cpr_interestPaymentFlow_time_unit_type_code": "NA",
    "cpr_interestPaymentFlow_deadline_type_code": "NA",
    "cpr_payment_start_date": "NA",
    "cpr_amortization_type_code": "NA",
    "cpr_amortization_months_quantity": "NA",
    "cpr_amortizationPaymentFlow_time_unit_type_code": "NA",
    "cpr_amortizationPaymentFlow_deadline_type_code": "NA",
    "cpr_amortization_start_date": "NA",
    "cpr_scr_type_code": "N",
    "cpr_scr_customer_detail": "NA",
    "cpr_scr_person_type_acronym": "NA",
    "cpr_deposit_document_number": "NA",
    "cpr_scr_document_number": "NA",
    "cpr_creditor_document_number": "47.175.222/0001-09",
    "cpr_contract_code": "00700",
    "cpr_operation_modality_type_code": "NA",
    "cpr_bacen_reference_code": "NA",
    "cpr_deliveryPlace_state_acronym": "MT",
    "cpr_deliveryPlace_city_name": "PORTO DOS GAÚCHOS",
    "cpr_deliveryPlace_ibge_code": "NA FAZENDA EM PRODUÇÃO",
    "cpr_children_codes": ["NA"]
  }
}

cURL Example

curl --location 'http://localhost:8000/b3/cpr/register' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <JWT>' \
  --data '{
    "cpr_type_code": "P",
    "cpr_otc_register_account_code": "64359.40-5",
    "cpr_otc_payment_agent_account_code": "64359.40-5",
    "cpr_otc_custodian_account_code": "64359.00-3",
    "cpr_internal_control_number": "NA",
    "cpr_electronic_emission_indicator": "SIM",
    "cpr_isin_code": "NA",
    "cpr_issue_date": "2025-11-28",
    "cpr_maturity_date": "2026-09-30",
    "cpr_issue_quantity": 1,
    "cpr_issue_value": 1710000.00,
    "cpr_issue_financial_value": 1710000.00,
    "cpr_unit_value": 1710000.00,
    "cpr_reference_date": "2025-12-09",
    "cpr_profitability_start_date": "2025-12-09",
    "cpr_automatic_expiration_indicator": "NÃO",
    "cpr_collateral_type_code": "Penhor",
    "cpr_collateral_type_name": "NA",
    "cpr_constitution_process_indicator": "SIM",
    "cpr_otc_bondsman_account_code": "NA",
    "cpr_collaterals_document_number": "NA",
    "cpr_product_name": "MILHO",
    "cpr_product_class_name": "MILHO (EM GRAOS)",
    "cpr_product_harvest": "2026/2026",
    "cpr_product_description": "Milho brasileiro em grãos, tipo exportação.",
    "cpr_product_quantity": 2700000,
    "cpr_measure_unit_name": "QUILO",
    "cpr_packaging_way_name": "SACA (60 KG)",
    "cpr_product_status_code": "A PRODUZIR",
    "cpr_production_type_code": "PROPRIA",
    "cpr_issuer_name": "MARCELO VINCENZI",
    "cpr_finality_code": "NA",
    "cpr_ipoc_code": "NA",
    "cpr_calculation_type_code": "NA",
    "cpr_initial_exchange_value": "NA",
    "cpr_fixing_type_code": "NA",
    "cpr_data_source_type_code": "NA",
    "cpr_adjustment_frequency_type_code": "NA",
    "cpr_adjustment_pro_rata_type_code": "NA",
    "cpr_adjustment_type_code": "NA",
    "cpr_creditor_name": "TOO EASY TRADING LTDA",
    "cpr_ballast_type_code": "NA",
    "cpr_lot_number": "NA",
    "cpr_ballast_quantity": "NA",
    "cpr_currency_code": "NA",
    "cpr_transaction_identification": "NA",
    "cpr_additional_text": "NA",
    "cpr_number": "NA",
    "cpr_contract_number": "NA",
    "cpr_event_type_code": "NA",
    "cpr_event_original_date": "NA",
    "cpr_unit_price_value": 1710000.00,
    "cpr_interest_unit_price_value": 0.00,
    "cpr_residual_value": "NA",
    "cpr_amortization_percentage": "NA",
    "cpr_event_quantity": "NA",
    "cpr_production_place_name": "FAZENDA CORAÇÃO DE MARIA",
    "cpr_property_registration_number": "14406",
    "cpr_notary_name": "NA",
    "cpr_total_production_area_in_hectares_number": "NA",
    "cpr_total_area_in_hectares_number": 670,
    "cpr_car_code": "NA",
    "cpr_latitude_code": "NA",
    "cpr_longitude_code": "NA",
    "cpr_zip_code": "78560000",
    "cpr_green_cpr_indicator": "NA",
    "cpr_green_cpr_certificate_name": "NA",
    "cpr_green_cpr_certificate_cnpj_number": "NA",
    "cpr_green_cpr_georeferencing_description": "NA",
    "cpr_green_cpr_declaration_indicator": "NA",
    "cpr_document_deadline_days_number": "NA",
    "cpr_place_name": "NA",
    "cpr_guarantee_limit_type_code": "NA",
    "cpr_mother_code": "NA",
    "cpr_issuers_person_type_acronym": "PF",
    "cpr_issuers_state_acronym": "MT",
    "cpr_issuers_city_name": "SINOP",
    "cpr_issuers_ibge_code": "NA",
    "cpr_issuer_legal_nature_code": "02",
    "cpr_otc_favored_account_code": "64359.00-3",
    "cpr_issuers_document_number": "867.308.271-49",
    "cpr_deposit_person_type_acronym": "PF",
    "cpr_self_number": "NA",
    "cpr_settlement_modality_type_code": "NA",
    "cpr_otc_settlement_bank_account_code": "NA",
    "cpr_deposit_quantity": 1,
    "cpr_deposit_unit_price_value": "NA",
    "cpr_payment_method_code": "NA",
    "cpr_index_code": "NA",
    "cpr_index_short_name": "NA",
    "cpr_vcp_indicator_type_code": "NA",
    "cpr_indexador_percentage_value": "NA",
    "cpr_interest_rate_spread_percentage": "NA",
    "cpr_interest_rate_criteria_type_code": "NA",
    "cpr_interest_payment_date": "NA",
    "cpr_interest_payment_value": "NA",
    "cpr_interest_payment_frequency_code": "NA",
    "cpr_interest_months_quantity": "NA",
    "cpr_interestPaymentFlow_time_unit_type_code": "NA",
    "cpr_interestPaymentFlow_deadline_type_code": "NA",
    "cpr_payment_start_date": "NA",
    "cpr_amortization_type_code": "NA",
    "cpr_amortization_months_quantity": "NA",
    "cpr_amortizationPaymentFlow_time_unit_type_code": "NA",
    "cpr_amortizationPaymentFlow_deadline_type_code": "NA",
    "cpr_amortization_start_date": "NA",
    "cpr_scr_type_code": "N",
    "cpr_scr_customer_detail": "NA",
    "cpr_scr_person_type_acronym": "NA",
    "cpr_deposit_document_number": "NA",
    "cpr_scr_document_number": "NA",
    "cpr_creditor_document_number": "47.175.222/0001-09",
    "cpr_contract_code": "00700",
    "cpr_operation_modality_type_code": "NA",
    "cpr_bacen_reference_code": "NA",
    "cpr_deliveryPlace_state_acronym": "MT",
    "cpr_deliveryPlace_city_name": "PORTO DOS GAÚCHOS",
    "cpr_deliveryPlace_ibge_code": "NA FAZENDA EM PRODUÇÃO",
    "cpr_children_codes": ["NA"]
  }'

Responses

200 OK (Success)

Returns the JSON body from B3.

400 Bad Request

Returned if the JSON is invalid or CPR payload is missing.

401 Unauthorized

Returned if the JWT is missing/invalid.

502 Bad Gateway

Returned if the request to B3 fails.