Documentación técnica completa
Esta documentación proporciona toda la información necesaria para integrar tu sistema con el API de Capital Tech OMS.
/oms/integrations/ordersx-api-key{
"operation": "SHIPMENT",
"origin": {
"street_name": "Av. Principal",
"street_number": "1234",
"address_floor": "3",
"address_apartment": "A",
"address_neighborhood": "Centro",
"zip_code": "1000",
"city_name": "Ciudad Ejemplo",
"state_name": "Provincia Ejemplo",
"country_name": "Argentina",
"observation": "Edificio con acceso por puerta principal"
},
"destination": {
"street_name": "Calle Secundaria",
"street_number": "567",
"address_floor": null,
"address_apartment": null,
"address_neighborhood": "Barrio Norte",
"zip_code": "2000",
"city_name": "Ciudad Destino",
"state_name": "Provincia Destino",
"country_name": "Argentina",
"observation": "Casa con portón negro"
},
"external_reference": "ORD-2024-001",
"items": [
{
"external_reference": "ITEM-001",
"code": "PROD-001",
"name": "Producto Ejemplo 1",
"quantity": 2
},
{
"external_reference": "ITEM-002",
"code": "PROD-002",
"name": "Producto Ejemplo 2",
"quantity": 1
}
],
"contact": {
"fullname": "Juan Pérez",
"document": "12345678",
"email": "juan.perez@example.com",
"phone_number": "1123456789",
"area_code": "+54"
}
}| CAMPO | TIPO | REQUERIDO | DESCRIPCIÓN |
|---|---|---|---|
operation | Enum | No | Tipo de operación: "SHIPMENT" o "PICKUP". Default: "SHIPMENT" |
external_reference | String | No | Referencia externa de la orden |
origin | Object | Sí | Ubicación de origen |
destination | Object | Sí | Ubicación de destino |
items | Array | Sí | Lista de items (mínimo 1) |
contact | Object | Sí | Información de contacto |
| CAMPO | TIPO | REQUERIDO | DESCRIPCIÓN |
|---|---|---|---|
street_name | String | Sí | Nombre de la calle |
street_number | String | Sí | Número de la calle |
address_floor | String | No | Piso |
address_apartment | String | No | Departamento |
address_neighborhood | String | No | Barrio |
zip_code | String | Sí | Código postal |
city_name | String | Sí | Ciudad |
state_name | String | Sí | Provincia/Estado |
country_name | String | Sí | País |
observation | String | No | Observaciones adicionales |
| CAMPO | TIPO | REQUERIDO | DESCRIPCIÓN |
|---|---|---|---|
external_reference | String | No | Referencia externa del item |
code | String | No | Código del producto |
name | String | Sí | Nombre del producto |
quantity | Number | Sí | Cantidad (debe ser mayor a 0) |
| CAMPO | TIPO | REQUERIDO | DESCRIPCIÓN |
|---|---|---|---|
fullname | String | Sí | Nombre completo |
document | String | Sí | Documento de identidad |
email | String | No | Email (requerido si no hay phone_number) |
phone_number | String | No | Teléfono (requerido si no hay email) |
area_code | String | No | Código de área |
* Al menos uno de email o phone_number debe estar presente.
origin y destination: Objetos requeridos con todas las validaciones de ubicaciónitems: Array requerido con mínimo 1 item, cada item debe tener name y quantity > 0contact: Objeto requerido, debe tener al menos email o phone_number400 Bad Request - Validación fallida
{
"error": {
"message": "Validation failed",
"details": [
{
"field": "items",
"message": "items must contain at least 1 element"
}
]
}
}401 Unauthorized - API Key inválido o faltante
{
"error": {
"message": "Unauthorized",
"details": "Invalid or missing API key"
}
}404 Not Found - Cliente no encontrado
{
"error": {
"message": "Resource not found",
"details": "Client with id 550e8400-e29b-41d4-a716-446655440000 not found"
}
}Los webhooks se disparan automáticamente cuando ocurren cambios en el estado de las órdenes.
El payload enviado al endpoint configurado tiene la siguiente estructura:
| CAMPO | TIPO | REQUERIDO | DESCRIPCIÓN |
|---|---|---|---|
event_code | String | Sí | Código del evento ("ORDER_STATUS_CHANGED", etc.) |
order_id | UUID | Sí | ID de la orden afectada |
timestamp | ISO 8601 | Sí | Fecha y hora del evento |
retry_count | Number | Sí | Número de intento (0 = primer intento) |
retryDelaySeconds * retryCount segundosretry_count se incrementa en cada reintento1 + 5 intentos fallidos, el mensaje se descarta y se registra una observación conservando la información.| Intento | Delay (segundos) | Delay Acumulado |
|---|---|---|
| 1 | 0 (inmediato) | 0 |
| 2 | 60 | 60 |
| 3 | 120 | 180 |
| 4 | 180 | 360 |
| 5 | 240 | 600 |
| 6 | 300 | 900 |
Después del intento 6, si sigue fallando, el mensaje se descarta.
Nota: El endpoint debe responder en menos de 30 segundos para evitar timeouts.
Request:
curl -X POST https://api.example.com/oms/integrations/orders \
-H "x-api-key: your-api-key-here" \
-H "Content-Type: application/json" \
-d '{
"client_id": "550e8400-e29b-41d4-a716-446655440000",
"origin": {
"street_name": "Av. Principal",
"street_number": "1234",
"zip_code": "1000",
"city_name": "Ciudad Ejemplo",
"state_name": "Provincia Ejemplo",
"country_name": "Argentina"
},
"destination": {
"street_name": "Calle Secundaria",
"street_number": "567",
"zip_code": "2000",
"city_name": "Ciudad Destino",
"state_name": "Provincia Destino",
"country_name": "Argentina"
},
"items": [
{
"name": "Producto Ejemplo",
"quantity": 1
}
],
"contact": {
"fullname": "Juan Pérez",
"document": "12345678",
"email": "juan.perez@example.com"
}
}'Request:
Implementación de ejemplo (Node.js/Express):
app.post('/webhooks/orders', async (req, res) => {
try {
const { data, metadata } = req.body;
// Validar que el webhook es válido
if (!data || !metadata) {
return res.status(400).json({ error: 'Invalid webhook payload' });
}
// Procesar el evento
const { event_code, order_id, timestamp } = metadata;
const order = data;
console.log(`Received webhook: ${event_code} for order ${order_id}`);
// Tu lógica de procesamiento aquí
await processOrderUpdate(order, event_code);
// Responder con 200 para indicar éxito
res.status(200).json({
message: 'Webhook processed successfully',
order_id,
timestamp
});
} catch (error) {
console.error('Error processing webhook:', error);
// Responder con error para que se reintente
res.status(500).json({ error: 'Internal server error' });
}
});Escenario: Un e-commerce necesita crear órdenes automáticamente cuando un cliente completa una compra.
/oms/integrations/orders con los datos de la ordenexternal_reference para mantener la referencia del pedido del e-commerceexternal_referenceEscenario: Un sistema externo necesita ser notificado cuando una orden cambia de estado.
Escenario: Mantener sincronizado el estado de órdenes entre múltiples sistemas.
retry_count en metadata para identificar reintentosEscenario: Crear una orden con múltiples productos.
Ejemplo de Request:
Escenario: El endpoint del webhook está temporalmente caído.
order_id y timestampÚltima actualización: 19 Noviembre 2025
Para más información o soporte, contacta al equipo de desarrollo.