Reglas de envío

Automatiza la selección de paquetería y servicio con reglas SI/ENTONCES evaluadas en cada envío.

Las reglas de envío automatizan decisiones al crear cada envío: elegir paquetería, fijar servicio, asegurar automáticamente, cambiar el formato de guía y más. Se evalúan en orden de prioridad, antes de cotizar.

Endpoints

Método	Ruta	Descripción
`GET`	`/v1/shipping-rules`	Listar reglas (ordenadas por prioridad)
`POST`	`/v1/shipping-rules`	Crear una regla
`GET`	`/v1/shipping-rules/:id`	Obtener una regla
`PUT`	`/v1/shipping-rules/:id`	Actualizar una regla
`DELETE`	`/v1/shipping-rules/:id`	Eliminar (borrado suave)
`PATCH`	`/v1/shipping-rules/reorder`	Reordenar prioridades en bloque
`POST`	`/v1/shipping-rules/preview`	Simulacro: evaluar sin persistir

Parámetros del cuerpo (crear y actualizar)

PropType

prioritynumber

Orden de evaluación (1–9999). Única por organización.

Typenumber

conditionsobjeto

Árbol all/any de condiciones { field, op, value }. Ver la tabla de abajo.

Typeobjeto

actionsobjeto[]

Acciones a aplicar cuando la regla dispara. Ver la tabla de acciones.

Typeobjeto[]

name?string

Nombre descriptivo de la regla.

Typestring

isActive?boolean

Las reglas inactivas no se evalúan.

Typeboolean

Defaulttrue

curl -X POST https://api.sendit.mx/v1/shipping-rules \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "DHL para envíos pesados a Jalisco",
    "priority": 10,
    "conditions": {
      "all": [
        { "field": "parcel.weight", "op": ">=", "value": 5 },
        { "field": "to.state", "op": "==", "value": "JAL" }
      ]
    },
    "actions": [{ "type": "select_carrier", "carrierCode": "DHL" }]
  }'

{
  "success": true,
  "data": {
    "id": "clxrule1",
    "name": "DHL para envíos pesados a Jalisco",
    "priority": 10,
    "isActive": true,
    "conditions": { "all": [ { "field": "parcel.weight", "op": ">=", "value": 5 }, { "field": "to.state", "op": "==", "value": "JAL" } ] },
    "actions": [{ "type": "select_carrier", "carrierCode": "DHL" }],
    "createdAt": "2026-07-18T10:00:00.000Z"
  }
}

Las secciones siguientes detallan la sintaxis de conditions y actions.

Escribe condiciones

Las condiciones se anidan con all (Y) y any (O):

{
  "all": [
    { "field": "parcel.weight", "op": ">=", "value": 5 },
    { "any": [
      { "field": "to.state", "op": "in", "value": ["CDMX", "JAL", "NLE"] },
      { "field": "to.isResidential", "op": "==", "value": false }
    ]}
  ]
}

Campos disponibles

Campo	Tipo	Descripción
`parcel.weight`	number	Peso en kg
`parcel.length` / `width` / `height`	number	Dimensiones en cm
`parcel.packagingType`	string	Tipo de empaque
`to.country`	string	País destino (ISO)
`to.state`	string	Estado destino
`to.postalCode`	string	Código postal destino
`to.isResidential`	boolean	Entrega residencial
`order.totalPrice`	number	Total de la orden (MXN)
`order.channel`	string	`SHOPIFY`, `WOOCOMMERCE`, …
`shipment.declaredValue`	number	Valor declarado
`shipment.isInternational`	boolean	Envío internacional

Operadores

==, !=, >, >=, <, <=, in, not_in, contains, starts_with

Define acciones

Acción	Campos	Efecto
`select_carrier`	`carrierCode`	Cotizar solo con esta paquetería
`select_service`	`carrierCode`, `serviceCode`	Fijar un servicio específico
`exclude_carrier`	`carrierCode`	Excluir una paquetería
`add_insurance`	`declaredValue`	Asegurar automáticamente
`set_label_format`	`format`	Cambiar el formato de guía: `PDF`, `ZPL` o `PNG`
`add_signature_required`	—	Exigir firma de recibido
`tag`	`tags: string[]`	Etiquetar el envío

Prioridad y cascada

Las reglas se evalúan en orden de priority ascendente. Todas las que coinciden se aplican, y las posteriores pueden sobreescribir a las anteriores:

Prioridad 1: select_carrier DHL
Prioridad 2: select_service DHL EXPRESS   ← refina lo que fijó la prioridad 1

Prueba antes de activar

preview evalúa un envío hipotético sin escribir nada:

curl -X POST https://api.sendit.mx/v1/shipping-rules/preview \
  -H "X-API-Key: sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "shipment": {
      "parcel": { "weight": 8, "length": 40, "width": 30, "height": 20 },
      "to": { "country": "MX", "state": "JAL", "postalCode": "44100" },
      "shipment": { "declaredValue": 5000, "isInternational": false }
    }
  }'

{
  "success": true,
  "data": {
    "finalActions": {
      "carrierCode": "DHL",
      "serviceCode": "EXPRESS"
    },
    "evaluations": [
      { "ruleId": "clxrule1", "fired": true, "actionsApplied": [{ "type": "select_carrier", "carrierCode": "DHL" }] },
      { "ruleId": "clxrule2", "fired": true, "actionsApplied": [{ "type": "select_service", "carrierCode": "DHL", "serviceCode": "EXPRESS" }] }
    ]
  }
}

evaluations[] muestra la cascada exacta: qué regla disparó, qué condiciones evaluó y qué acciones aplicó. La misma información queda registrada en cada envío real para auditoría.

Límites y utilidades

Máximo 100 reglas activas por organización.
La prioridad es única por organización (1–9999).
Para depurar, salta todas las reglas en una petición con el encabezado SendIt-Rules: skip.