Skip to main content
Get your semantic web package shipping system running in minutes. This guide walks you through setting up both microservices, creating your first shipment, and testing semantic search.

​
Prerequisites

Before you begin, ensure you have:
  • Java 17 or higher
  • MySQL 8.0+
  • Maven 3.6+
  • curl or Postman for API testing

​
Quick Setup

1

Start MySQL Database

Create the database for the shipment service:
CREATE DATABASE bd_envio_encomienda;
The tables will be created automatically when you start the service.
2

Start the Semantic Service

Navigate to the semantic service directory and run:
cd svc-web-semantica
mvn spring-boot:run
The service will start on port 8081 and create a tdb_data/ directory for storing RDF triples.
The semantic service must be running before the shipment service to enable automatic synchronization.
3

Start the Shipment Service

In a new terminal, navigate to the shipment service:
cd svc-envio-encomienda
mvn spring-boot:run
The service will start on port 8080 and automatically:
  • Create database tables
  • Connect to the semantic service at http://localhost:8081
4

Create Your First Shipment

Create a client first:
curl -X POST http://localhost:8080/api/v1/clientes \
  -H "Content-Type: application/json" \
  -d '{
    "nombreCompleto": "Juan Pérez",
    "dni": "12345678",
    "telefono": "987654321",
    "correo": "[email protected]"
  }'
Then create a shipment (assuming client ID 1, sucursales with IDs 1 and 2 exist):
curl -X POST http://localhost:8080/api/v1/envios \
  -H "Content-Type: application/json" \
  -d '{
    "remitenteId": 1,
    "encomienda": {
      "descripcion": "Laptop Dell XPS 15",
      "peso": 2.5,
      "dimensiones": "40x30x10"
    },
    "nombreDestinatario": "María García",
    "dniDestinatario": "87654321",
    "sucursalOrigenId": 1,
    "sucursalDestinoId": 2,
    "precio": 35.50
  }'
The tracking code is auto-generated with format ENV-{timestamp} and a 4-digit delivery password is created automatically.
5

Test Semantic Search

Now query using natural language:
curl -X GET "http://localhost:8081/api/v1/grafo/buscar?texto=envios+pendientes"
Try more complex queries:
# Search by weight range
curl -X GET "http://localhost:8081/api/v1/grafo/buscar?texto=envios+entre+2+y+5+kg"

# Search by date
curl -X GET "http://localhost:8081/api/v1/grafo/buscar?texto=envios+de+hoy"

# Search by city
curl -X GET "http://localhost:8081/api/v1/grafo/buscar?texto=envios+a+Lima"

​
What Happens Behind the Scenes

When you create a shipment:
  1. Shipment Service saves the data to MySQL
  2. Automatically sends the shipment data to Semantic Service
  3. Semantic Service converts it to RDF triples using the OWL ontology
  4. Stores triples in Apache Jena TDB for semantic querying
  5. Natural language queries are translated to SPARQL and executed against the knowledge graph

​
State Transitions

Shipments follow this lifecycle: 
PENDIENTE → EN_TRANSITO → DISPONIBLE → ENTREGADO
    ↓
CANCELADO (only from PENDIENTE)
Update shipment states: 
# Assign vehicle (PENDIENTE → EN_TRANSITO)
curl -X POST http://localhost:8080/api/v1/envios/asignar-placa \
  -H "Content-Type: application/json" \
  -d '{"envioId": 1, "placa": "ABC-123"}'

# Mark as available for pickup (EN_TRANSITO → DISPONIBLE)
curl -X PUT http://localhost:8080/api/v1/envios/1/disponible

# Deliver package (DISPONIBLE → ENTREGADO)
curl -X POST http://localhost:8080/api/v1/envios/retirar \
  -H "Content-Type: application/json" \
  -d '{"codigoSeguimiento": "ENV-1234567890", "contrasenaEntrega": "1234"}'

​
Next Steps

Architecture Overview

Understand how the microservices communicate

Semantic Search Guide

Master natural language queries

SPARQL Queries

Write custom SPARQL queries

Ontology Reference

Explore the OWL ontology structure

​
Troubleshooting

Ensure the semantic service is running on port 8081 before starting the shipment service. Check the logs for connection errors.
Update credentials in svc-envio-encomienda/src/main/resources/application.properties:
spring.datasource.username=your_username
spring.datasource.password=your_password
The shipment may not have been synchronized to the semantic graph. Check if both services are running and try creating a new shipment.

Build docs developers (and LLMs) love

Get started for freeTalk to us