Referencia para desarrolladores
Consulta las operaciones que puedes usar desde tu integración. Descarga OpenAPI para importar el contrato completo.
GET/v1/healthComprobar vida del servicio
Liveness propio; no comprueba Shalom.
GET/v1/capabilitiesConsultar capacidades verificadas
Capacidades live desactivadas hasta validación real.
GET/v1/connectionsListar conexiones propias
Solo conexiones permitidas a la identidad; sin secretos.
POST/v1/connectionsCrear conexión local
Crea pending_authorization local; no hace login externo.
Cuerpo de la solicitud
{
"provider": "shalom",
"label": "REEMPLAZAR",
"environment": "sandbox"
}GET/v1/connections/{connection_id}Consultar conexión propia
Estado y capacidades, sin credenciales. En live, data.authorization indica el ?ltimo intento de conexi?n si existe.
PATCH/v1/connections/{connection_id}Configurar remitente y origen
Propietario cambia solo datos logísticos propios; no credenciales.
Cuerpo de la solicitud
{
"label": "REEMPLAZAR"
}DELETE/v1/connections/{connection_id}Desconectar acceso del servicio
Revoca uso local, bloquea nuevas tareas y conserva historial. No cancela envíos ni garantiza invalidar sesiones remotas.
POST/v1/connections/{connection_id}/authorization-sessionsIniciar autorización del propietario
Inicia conexión normal a la cuenta Pro del negocio mediante navegador y trabajo persistente. Requiere configurar el conector experimental y una suscripción activa. No es OAuth ni API oficial de Shalom. Si aparece una verificación manual se detiene. La contraseña es writeOnly y se elimina al terminar el intento. Una solicitud con un intento vigente en cola o en ejecuci?n devuelve el mismo intento. La cuota se aplica al iniciar uno nuevo; Retry-After indica cu?ndo reintentar si se recibe 429.
Cuerpo de la solicitud
{
"email": "REEMPLAZAR",
"password": "REEMPLAZAR"
}GET/v1/authorization-sessions/{authorization_session_id}Consultar autorización propia
Consulta el estado del intento propio sin devolver contraseña, cookies ni tokens de Pro.
GET/v1/keysListar metadatos de claves
Solo propietario; no devuelve secretos ni hashes.
POST/v1/keysEmitir clave restringida
Secreto una vez, sin replay por idempotencia. Ante respuesta perdida, listar/revocar y crear otra. Verifica conexión/entorno.
Cuerpo de la solicitud
{
"label": "REEMPLAZAR",
"environment": "sandbox",
"scopes": [
"connections:read"
],
"connection_ids": [
"00000000-0000-4000-8000-000000000001"
]
}DELETE/v1/keys/{key_id}Revocar clave propia
Bloquea nuevas solicitudes; conserva auditoría y no cancela efectos externos ya ejecutados.
GET/v1/agenciesBuscar agencias habilitadas
Catálogo normalizado y fecha de actualización; no infiere servicios solo por distrito.
GET/v1/package-typesConsultar embalajes
Solo entrega medidas normalizadas verificadas; no catálogo comercial de Kova.
POST/v1/quotesObtener cotización estimada
Cotiza y persiste precio y paquetes; no registra envío. valid_until es política del servicio, no garantía de tarifa del proveedor.
Cuerpo de la solicitud
{
"connection_id": "00000000-0000-4000-8000-000000000001",
"origin_agency_id": "00000000-0000-4000-8000-000000000101",
"destination_agency_id": "00000000-0000-4000-8000-000000000102",
"packages": [
{
"quantity": 1,
"weight_g": 1000,
"length_mm": 200,
"width_mm": 200,
"height_mm": 200
}
]
}POST/v1/recipientsGuardar destinatario local
Guarda localmente; alta remota cuando corresponda dentro del trabajo de envío. Valida persona/empresa.
Cuerpo de la solicitud
{
"recipient": {
"kind": "person",
"person": {
"document": {
"type": "DNI",
"number": "00000000"
},
"given_names": "REEMPLAZAR",
"paternal_surname": "REEMPLAZAR",
"phone": "+51900000000"
}
}
}POST/v1/recipients/searchBuscar destinatarios propios
Documento en cuerpo privado. Coincidencia local exacta; no directorio global ni consulta RENIEC.
Cuerpo de la solicitud
{
"document": {
"type": "DNI",
"number": "00000000"
}
}GET/v1/recipients/{recipient_id}Consultar destinatario propio
Datos privados locales autorizados por negocio.
GET/v1/shipmentsListar envíos propios
Historial persistido propio; filtros siempre acotados al negocio.
POST/v1/shipmentsSolicitar registro idempotente de envío
Transacción crea envío, operación y tarea.202 no acredita registro externo. Requiere capacidad verificada y conexión habilitada. Unicidad permanente negocio+conexión+external_reference. Resultados inciertos requieren reconciliación. El envio usa las agencias de origen y destino de la cotizacion vigente. El origen guardado en la conexion es opcional.
Cuerpo de la solicitud
{
"connection_id": "00000000-0000-4000-8000-000000000001",
"external_reference": "PEDIDO-DEMO-001",
"quote_id": "00000000-0000-4000-8000-000000000001",
"recipient_id": "00000000-0000-4000-8000-000000000001",
"content_description": "REEMPLAZAR",
"delivery_method": "agency_pickup",
"freight_payer": "sender"
}GET/v1/shipments/{shipment_id}Consultar envío propio
Procesamiento y transporte separados; referencias externas solo con evidencia. No devuelve claves de recojo.
GET/v1/shipments/{shipment_id}/eventsConsultar eventos del envío
Fuente y fechas observadas; sin cronología ni llegada inventadas.
POST/v1/shipments/{shipment_id}/refreshSolicitar actualización de seguimiento
Programa lectura; no recrea envío. Agrupa mientras exista refresh activo y limita frecuencia.
GET/v1/shipments/{shipment_id}/documents/{kind}Obtener acceso temporal a documento
Documento propio ya disponible;409 document_not_ready si falta. No crea envío. Acceso proveedor pendiente de validación real.
GET/v1/operations/{operation_id}Consultar resultado de tarea
Estado persistido. succeeded no implica entrega física.
GET/v1/usageConsultar consumo propio
Contadores propios. No paga ni factura. Alta confirmada se cuenta una vez; reintentos internos no son otra alta.
GET/public/agenciesConsultar copia pública de agencias
Catálogo observado con procedencia/fecha. El estado reportado no es disponibilidad en tiempo real.
GET/public/agencies.geojsonConsultar puntos de agencias
Solo coordenadas capturadas válidas, sin llamadas nuevas a Shalom.
GET/openapi.jsonDescargar contrato OpenAPI
Contrato propio de este servicio; no contrato interno de Shalom.
GET/limits.jsonConsultar políticas de límites
Límites iniciales de Kova; no cuotas oficiales ni garantía contra bloqueos.
GET/llms.txtLeer índice para agentes
Referencia pública sin credenciales ni datos de clientes.
GET/downloads/{artifact}Descargar MCP, skill o ejemplo
Artefactos locales preparados; no implica publicación en npm.
Ejemplo de cotización
Usa la clave desde tu servidor. Los campos de quote están en la operación de cotización.
const response = await fetch(`${process.env.KOVA_API_URL}/v1/quotes`, {
method: "POST",
headers: {
"X-API-Key": process.env.KOVA_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify(quote),
});
const result = await response.json();