Skip to main content
POST
/
api
/
v1
/
grafo
/
sincronizar-envio
Synchronize Shipment
curl --request POST \
  --url https://api.example.com/api/v1/grafo/sincronizar-envio \
  --header 'Content-Type: application/json' \
  --data '
{
  "idCliente": "<string>",
  "nombreCliente": "<string>",
  "dniCliente": "<string>",
  "telefonoCliente": "<string>",
  "correoCliente": "<string>",
  "idEnvio": "<string>",
  "codigoSeguimiento": "<string>",
  "estadoEnvio": "<string>",
  "precio": 123,
  "fechaEnvio": "<string>",
  "fechaEntrega": "<string>",
  "placaVehiculo": "<string>",
  "nombreDestinatario": "<string>",
  "dniDestinatario": "<string>",
  "ciudadOrigen": "<string>",
  "ciudadDestino": "<string>",
  "sucursalOrigen": "<string>",
  "sucursalDestino": "<string>",
  "pesoEncomienda": 123,
  "descripcionEncomienda": "<string>",
  "dimensiones": "<string>"
}
'
{
  "message": "<string>"
}

​
Endpoint

POST /api/v1/grafo/sincronizar-envio
Synchronize a shipment and its related entities (client, package, branches) into the semantic knowledge graph. This creates RDF triples following the OWL ontology structure.

​
Request Body

​
Client Information

​
idCliente
string
required
Unique client identifier
​
nombreCliente
string
required
Client full name
​
dniCliente
string
required
Client DNI (national ID)
​
telefonoCliente
string
Client phone number
​
correoCliente
string
Client email address

​
Shipment Information

​
idEnvio
string
required
Unique shipment identifier
​
codigoSeguimiento
string
required
Tracking code
​
estadoEnvio
string
required
Current shipment status: PENDIENTE, EN_TRANSITO, DISPONIBLE, ENTREGADO, or CANCELADO
​
precio
number
required
Shipment price
​
fechaEnvio
string
required
Shipment date (ISO format: YYYY-MM-DD or YYYY-MM-DDTHH:mm:ss)
​
fechaEntrega
string
Delivery date (ISO format, nullable)
​
placaVehiculo
string
Vehicle plate number (optional)

​
Recipient Information

​
nombreDestinatario
string
required
Recipient full name
​
dniDestinatario
string
required
Recipient DNI

​
Route Information

​
ciudadOrigen
string
required
Origin city name
​
ciudadDestino
string
required
Destination city name
​
sucursalOrigen
string
Origin branch office name
​
sucursalDestino
string
Destination branch office name

​
Package Information

​
pesoEncomienda
number
required
Package weight in kilograms
​
descripcionEncomienda
string
required
Package description
​
dimensiones
string
Package dimensions (e.g., “30x40x20 cm”)

​
Response

​
message
string
Success message confirming the data was synchronized

​
Example Request

curl -X POST http://localhost:8080/api/v1/grafo/sincronizar-envio \
  -H "Content-Type: application/json" \
  -d '{
    "idCliente": "1",
    "nombreCliente": "María García",
    "dniCliente": "12345678",
    "telefonoCliente": "987654321",
    "correoCliente": "[email protected]",
    "idEnvio": "42",
    "codigoSeguimiento": "ENV-20260309-ABCD1234",
    "estadoEnvio": "EN_TRANSITO",
    "precio": 25.50,
    "fechaEnvio": "2026-03-09T10:30:00",
    "fechaEntrega": null,
    "placaVehiculo": "ABC-123",
    "nombreDestinatario": "Juan Pérez",
    "dniDestinatario": "87654321",
    "ciudadOrigen": "Lima",
    "ciudadDestino": "Cusco",
    "sucursalOrigen": "Lima Centro",
    "sucursalDestino": "Cusco Principal",
    "pesoEncomienda": 2.5,
    "descripcionEncomienda": "Documentos importantes",
    "dimensiones": "30x40x20 cm"
  }'

​
Example Response

"Tripleta OWL registrada correctamente en el grafo semántico."

​
What Gets Created

This endpoint creates the following RDF triples in the knowledge graph:

​
Shipment Entity

<http://jchilon3mas.org/envio/42> a onto:Envio ;
  onto:tieneCodigoSeguimiento "ENV-20260309-ABCD1234" ;
  onto:tieneEstado "EN_TRANSITO" ;
  onto:tienePrecio 25.50 ;
  onto:tieneFechaEnvio "2026-03-09T10:30:00" ;
  onto:enviadoPor <http://jchilon3mas.org/cliente/1> ;
  onto:destinadoA "Juan Pérez" ;
  onto:origen <http://jchilon3mas.org/sucursal/Lima> ;
  onto:destino <http://jchilon3mas.org/sucursal/Cusco> ;
  onto:contieneEncomienda <http://jchilon3mas.org/encomienda/42> ;
  onto:transportadoEn <http://jchilon3mas.org/vehiculo/ABC-123> .

​
Client Entity

<http://jchilon3mas.org/cliente/1> a onto:Cliente ;
  onto:tieneNombre "María García" ;
  onto:tieneDNI "12345678" ;
  onto:tieneTelefono "987654321" ;
  onto:tieneCorreo "[email protected]" .

​
Package Entity

<http://jchilon3mas.org/encomienda/42> a onto:Encomienda ;
  onto:tienePeso 2.5 ;
  onto:tieneDescripcion "Documentos importantes" ;
  onto:tieneDimensiones "30x40x20 cm" .

​
Branch Entities

<http://jchilon3mas.org/sucursal/Lima> a onto:Sucursal ;
  onto:tieneCiudad "Lima" ;
  onto:tieneNombreSucursal "Lima Centro" .

<http://jchilon3mas.org/sucursal/Cusco> a onto:Sucursal ;
  onto:tieneCiudad "Cusco" ;
  onto:tieneNombreSucursal "Cusco Principal" .

​
Vehicle Entity

<http://jchilon3mas.org/vehiculo/ABC-123> a onto:Vehiculo ;
  onto:tienePlaca "ABC-123" .

​
When to Synchronize

Synchronize shipment data to the semantic graph in these scenarios:
  1. After Shipment Creation - Sync new shipments immediately after creation
  2. Status Updates - Re-sync when shipment status changes
  3. Delivery - Update with delivery timestamp when package is picked up
  4. Bulk Import - Sync existing database records to populate the graph

​
Integration Pattern

Typical workflow: 
// 1. Create shipment via REST API
const shipmentResponse = await fetch('http://localhost:8080/api/v1/envios', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(shipmentData)
});

const shipment = await shipmentResponse.json();

// 2. Synchronize to semantic graph
await fetch('http://localhost:8080/api/v1/grafo/sincronizar-envio', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    idEnvio: shipment.id.toString(),
    codigoSeguimiento: shipment.codigoSeguimiento,
    estadoEnvio: shipment.estado,
    nombreCliente: shipment.remitente.nombreCompleto,
    // ... map all required fields
  })
});
The semantic graph is a separate data store from the relational database. Synchronization must be done explicitly via this endpoint.

​
Automatic Synchronization

For automatic synchronization, consider:
  1. Event-Driven Architecture - Use message queues (Kafka, RabbitMQ) to trigger sync on database changes
  2. Database Triggers - Set up triggers to call this endpoint on INSERT/UPDATE
  3. Scheduled Batch Jobs - Periodically sync all recent changes
Duplicate synchronization with the same idEnvio will update existing triples rather than creating duplicates. However, ensure data consistency by syncing the complete, current state of the shipment.

​
Benefits of Synchronization

Once synchronized, shipments become queryable via:
  • Natural language search
  • SPARQL queries
  • Relationship-based queries
  • Semantic inference

​
Error Handling

If synchronization fails: 
{
  "error": "SemanticSyncException",
  "message": "Failed to create RDF triples: Invalid ontology property"
}
Common issues:
  • Missing required fields
  • Invalid data types
  • Ontology constraint violations

Build docs developers (and LLMs) love

Get started for freeTalk to us