← Guía de integración

Referencia para desarrolladores

Consulta las operaciones que puedes usar desde tu integración. Descarga OpenAPI para importar el contrato completo.

32 operaciones

GET/v1/healthComprobar vida del servicio

Liveness propio; no comprueba Shalom.

PúblicoRespuesta 200
GET/v1/capabilitiesConsultar capacidades verificadas

Capacidades live desactivadas hasta validación real.

connections:read120 / 60 s por negocioRespuesta 200
GET/v1/connectionsListar conexiones propias

Solo conexiones permitidas a la identidad; sin secretos.

connections:read30 / 60 s por negocioRespuesta 200
POST/v1/connectionsCrear conexión local

Crea pending_authorization local; no hace login externo.

Propietario30 / 60 s por negocioRespuesta 201

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.

connections:read30 / 60 s por negocioRespuesta 200
PATCH/v1/connections/{connection_id}Configurar remitente y origen

Propietario cambia solo datos logísticos propios; no credenciales.

connections:configure30 / 60 s por negocioRespuesta 200

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.

Propietario30 / 60 s por negocioRespuesta 204
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.

connections:authorize1 / 300 s por negocioRespuesta 202

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.

connections:read120 / 60 s por negocioRespuesta 200
GET/v1/keysListar metadatos de claves

Solo propietario; no devuelve secretos ni hashes.

Propietario10 / 60 s por negocioRespuesta 200
POST/v1/keysEmitir clave restringida

Secreto una vez, sin replay por idempotencia. Ante respuesta perdida, listar/revocar y crear otra. Verifica conexión/entorno.

Propietario10 / 60 s por negocioRespuesta 201

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.

Propietario10 / 60 s por negocioRespuesta 204
GET/v1/agenciesBuscar agencias habilitadas

Catálogo normalizado y fecha de actualización; no infiere servicios solo por distrito.

catalog:read120 / 60 s por negocioRespuesta 200
GET/v1/package-typesConsultar embalajes

Solo entrega medidas normalizadas verificadas; no catálogo comercial de Kova.

catalog:read120 / 60 s por negocioRespuesta 200
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.

quotes:write12 / 60 s por negocioRespuesta 201

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.

recipients:write30 / 60 s por negocioRespuesta 201

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.

recipients:read30 / 60 s por negocioRespuesta 200

Cuerpo de la solicitud

{
  "document": {
    "type": "DNI",
    "number": "00000000"
  }
}
GET/v1/recipients/{recipient_id}Consultar destinatario propio

Datos privados locales autorizados por negocio.

recipients:read30 / 60 s por negocioRespuesta 200
GET/v1/shipmentsListar envíos propios

Historial persistido propio; filtros siempre acotados al negocio.

shipments:read120 / 60 s por negocioRespuesta 200
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.

shipments:write6 / 60 s por negocioRespuesta 202

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.

shipments:read120 / 60 s por negocioRespuesta 200
GET/v1/shipments/{shipment_id}/eventsConsultar eventos del envío

Fuente y fechas observadas; sin cronología ni llegada inventadas.

shipments:read120 / 60 s por negocioRespuesta 200
POST/v1/shipments/{shipment_id}/refreshSolicitar actualización de seguimiento

Programa lectura; no recrea envío. Agrupa mientras exista refresh activo y limita frecuencia.

shipments:read4 / 60 s por negocioRespuesta 202
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.

documents:read30 / 60 s por negocioRespuesta 200
GET/v1/operations/{operation_id}Consultar resultado de tarea

Estado persistido. succeeded no implica entrega física.

operations:read120 / 60 s por negocioRespuesta 200
GET/v1/usageConsultar consumo propio

Contadores propios. No paga ni factura. Alta confirmada se cuenta una vez; reintentos internos no son otra alta.

usage:read30 / 60 s por negocioRespuesta 200
GET/public/agenciesConsultar copia pública de agencias

Catálogo observado con procedencia/fecha. El estado reportado no es disponibilidad en tiempo real.

PúblicoRespuesta 200
GET/public/agencies.geojsonConsultar puntos de agencias

Solo coordenadas capturadas válidas, sin llamadas nuevas a Shalom.

PúblicoRespuesta 200
GET/openapi.jsonDescargar contrato OpenAPI

Contrato propio de este servicio; no contrato interno de Shalom.

PúblicoRespuesta 200
GET/limits.jsonConsultar políticas de límites

Límites iniciales de Kova; no cuotas oficiales ni garantía contra bloqueos.

PúblicoRespuesta 200
GET/llms.txtLeer índice para agentes

Referencia pública sin credenciales ni datos de clientes.

PúblicoRespuesta 200
GET/downloads/{artifact}Descargar MCP, skill o ejemplo

Artefactos locales preparados; no implica publicación en npm.

PúblicoRespuesta 200

Ejemplo de cotización

Usa la clave desde tu servidor. Los campos de quote están en la operación de cotización.

JavaScript
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();