Guía de la API de pedidos

Qué puedes hacer

• Ver el catálogo con los precios de tu empresa y el inventario disponible.
• Validar un pedido completo sin crearlo.
• Crear pedidos a cualquiera de tus sedes, desde tu ERP, una hoja de cálculo o un agente de IA.
• Consultar el estado de tus pedidos.

Cada pedido que nos envías entra a SumiMega igual que uno hecho en sumimega.com: lo revisa nuestro equipo y lo ves también en tu panel.

Antes de empezar

1. Pide la habilitación

Inicia sesión en sumimega.com con la cuenta principal de tu empresa y entra a Mi Panel → Desarrollador (con tu empresa seleccionada). Pulsa Solicitar habilitación. Verificamos tu NIT y te avisamos por correo.

2. Crea una clave

En ese mismo espacio crea una clave (empieza por smg_test_). Te pedimos tu contraseña y solo te la mostramos una vez: guárdala en el gestor de secretos de tu sistema. Crea una por cada sistema que se conecte; así puedes revocar una sin afectar a las demás.

3. Compruébala

Envía la clave en la cabecera Authorization de todas las peticiones:

export SUMIMEGA_API_KEY=smg_test_...

curl https://api.sandbox.sumimega.com/publica/v1/cuenta \
  -H "Authorization: Bearer $SUMIMEGA_API_KEY"

Si la respuesta trae "lista_para_pedidos": true, ya puedes enviar pedidos. Si es false, el campo avisos dice qué falta.

4. (Opcional) Autoriza tus IP

Para mayor seguridad, en Desarrollador puedes indicar las IP públicas de tus servidores: desde ese momento solo aceptamos peticiones que salgan de ellas. GET /cuenta te dice en ip_vista con qué IP te vemos.

Tu primer pedido

Paso 1. Elige la sede

curl https://api.sandbox.sumimega.com/publica/v1/puntos-envio \
  -H "Authorization: Bearer $SUMIMEGA_API_KEY"

{
  "datos": [
    {
      "codigo": "000",
      "nombre": "Sede principal",
      "direccion": "CR 50 # 10-20",
      "activo": true
    },
    {
      "codigo": "01",
      "nombre": "Bodega Itagüí",
      "direccion": "CR 50 # 79 SUR-101",
      "activo": true
    },
    {
      "codigo": "07",
      "nombre": "Almacén Centro",
      "direccion": "CL 44 # 52-31",
      "activo": true
    }
  ],
  "obligatorio": true,
  "codigo_por_defecto": null
}

Usa el codigo tal cual, como texto. Si obligatorio es true, tu empresa tiene varias sedes y debes indicar una en cada pedido.

Paso 2. Busca los productos

curl "https://api.sandbox.sumimega.com/publica/v1/productos?q=resma&con_stock=true" \
  -H "Authorization: Bearer $SUMIMEGA_API_KEY"

curl "https://api.sandbox.sumimega.com/publica/v1/productos?sku=1100123&sku=1200456" \
  -H "Authorization: Bearer $SUMIMEGA_API_KEY"

{
  "datos": [
    {
      "producto_id": 20870,
      "sku": "1100123",
      "nombre": "Resma Papel Carta 75Gr",
      "marca": "REPROGRAF",
      "categoria_id": 118,
      "unidad": "UND",
      "imagen": "https://api.sumimega.com/api/v1/storage/product-images/public/1100123.jpg",
      "precio_unitario": 23800.0,
      "precio_unitario_sin_iva": 20000.0,
      "iva_porcentaje": 19.0,
      "precio_acordado": false,
      "disponible": 320,
      "actualizado_en": "2026-11-03T08:10:00-05:00"
    }
  ],
  "siguiente_cursor": null
}

precio_unitario incluye IVA y es el de tu empresa. disponible es lo que hay libre en este momento. Para traer el catálogo completo, repite la consulta con cursor=<siguiente_cursor> hasta que siguiente_cursor sea null.

Paso 3. Simula el pedido

curl -X POST https://api.sandbox.sumimega.com/publica/v1/pedidos/simular \
  -H "Authorization: Bearer $SUMIMEGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d @pedido.json

Donde pedido.json es:

{
  "punto_envio": "07",
  "metodo_pago": "credito",
  "orden_compra": "OC-2026-0091",
  "notas": "Recibe Juan Pérez, bodega 3. Horario 7:00-15:00.",
  "lineas": [
    {
      "sku": "1100123",
      "cantidad": 40
    },
    {
      "producto_id": 20871,
      "cantidad": 12
    }
  ]
}

Cada línea lleva sku o producto_id (uno de los dos) y cantidad (entero). Los precios no se envían: los calculamos nosotros. La simulación siempre responde 200; míralo en valido y problemas:

{
  "valido": true,
  "problemas": [],
  "pedido": {
    "lineas": [
      {
        "producto_id": 20870,
        "sku": "1100123",
        "nombre": "Resma Papel Carta 75Gr",
        "cantidad": 40,
        "precio_unitario": 23800.0,
        "total": 952000.0
      },
      {
        "producto_id": 20871,
        "sku": "1200456",
        "nombre": "Guantes Nitrilo Talla M X100",
        "cantidad": 12,
        "precio_unitario": 11900.0,
        "total": 142800.0
      }
    ],
    "totales": {
      "subtotal": 920000.0,
      "iva": 174800.0,
      "descuento": 0,
      "total": 1094800.0,
      "moneda": "COP"
    },
    "punto_envio": {
      "codigo": "07",
      "nombre": "Almacén Centro",
      "direccion": "CL 44 # 52-31"
    },
    "metodo_pago": "credito",
    "compra_minima": {
      "monto": 150000,
      "incluye_iva": false,
      "aplica": true,
      "cumple": true
    }
  },
  "avisos": [
    {
      "code": "precios_vigentes",
      "message": "Los precios se recalculan al crear el pedido; envía total_esperado para blindarlo."
    }
  ]
}

Paso 4. Crea el pedido

Envía el mismo cuerpo más total_esperado (el total de la simulación). Si el precio cambió entre tanto, no creamos nada y te respondemos 409 precio_cambio: así nunca compras a un precio que no viste. Genera una Idempotency-Key nueva para este pedido y guárdala antes de enviar (más abajo te explicamos por qué).

CLAVE=$(uuidgen)

curl -i -X POST https://api.sandbox.sumimega.com/publica/v1/pedidos \
  -H "Authorization: Bearer $SUMIMEGA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $CLAVE" \
  -d @pedido.json

Con total_esperado, pedido.json queda así:

{
  "punto_envio": "07",
  "metodo_pago": "credito",
  "orden_compra": "OC-2026-0091",
  "notas": "Recibe Juan Pérez, bodega 3. Horario 7:00-15:00.",
  "total_esperado": 1094800.0,
  "lineas": [
    {
      "sku": "1100123",
      "cantidad": 40
    },
    {
      "producto_id": 20871,
      "cantidad": 12
    }
  ]
}

Respuesta 201, con el número y la referencia que debes guardar:

{
  "pedido": {
    "numero": 4123,
    "referencia": "WEB-4123",
    "origen": "api",
    "estado": "recibido",
    "pago": {
      "metodo": "credito",
      "estado": "en_revision"
    },
    "creado_en": "2026-11-03T09:42:11-05:00",
    "actualizado_en": "2026-11-03T09:42:11-05:00",
    "empresa": {
      "id": "3f1c9a52-7d0e-4c1b-9a35-2b8e6d4f1a70",
      "nombre": "Comercial Andina SAS",
      "nit": "900123456"
    },
    "punto_envio": {
      "codigo": "07",
      "nombre": "Almacén Centro",
      "direccion": "CL 44 # 52-31"
    },
    "orden_compra": "OC-2026-0091",
    "clave_idempotencia": "7b0c1f0e-52c5-4a59-9c1d-5f3f1a7e2d10",
    "notas": "Recibe Juan Pérez, bodega 3. Horario 7:00-15:00.",
    "lineas": [
      {
        "producto_id": 20870,
        "sku": "1100123",
        "nombre": "Resma Papel Carta 75Gr",
        "cantidad": 40,
        "precio_unitario": 23800.0,
        "total": 952000.0
      },
      {
        "producto_id": 20871,
        "sku": "1200456",
        "nombre": "Guantes Nitrilo Talla M X100",
        "cantidad": 12,
        "precio_unitario": 11900.0,
        "total": 142800.0
      }
    ],
    "totales": {
      "subtotal": 920000.0,
      "iva": 174800.0,
      "descuento": 0,
      "total": 1094800.0,
      "moneda": "COP"
    },
    "inventario": {
      "reservado": true,
      "reservado_hasta": "2026-11-06T09:42:11-05:00"
    },
    "confirmacion": {
      "estado": "pendiente",
      "documento": null
    }
  },
  "avisos": [
    {
      "code": "reserva_temporal",
      "message": "El inventario queda apartado mientras SumiMega revisa el pedido. Si no se confirma en 3 días, se libera y el pedido sigue vigente."
    },
    {
      "code": "redondeo_factura",
      "message": "La factura se liquida con el precio neto redondeado a pesos: puede diferir unos pesos del total."
    }
  ]
}

En el entorno de pruebas no enviamos correos.

Después de crearlo

El pedido entra a revisión de nuestro equipo y el inventario queda apartado. Consúltalo por su número o referencia:

curl https://api.sandbox.sumimega.com/publica/v1/pedidos/WEB-4123 \
  -H "Authorization: Bearer $SUMIMEGA_API_KEY"

Cómo leer el pedido

Enterarte de los cambios

Consulta cada cierto tiempo los pedidos que cambiaron (recomendado: cada 5 a 15 minutos):

curl "https://api.sandbox.sumimega.com/publica/v1/pedidos?actualizado_desde=2026-11-03T00:00:00-05:00" \
  -H "Authorization: Bearer $SUMIMEGA_API_KEY"

• Llegan del más antiguo al más reciente. Si trae siguiente_cursor, pide la siguiente página con &cursor=....
• Guarda el actualizado_en de la última fila: tu próxima consulta empieza desde ahí.
• Descarta los repetidos comparando numero y actualizado_en.
• Solo salen cambios de hace más de 2 minutos. Para ver un pedido al instante usa GET /pedidos/{referencia}.

GET /pedidos también filtra por desde, hasta, estado, origen (api, web o todos) y orden_compra. Incluye los pedidos que hiciste en la tienda.

Reintentar sin duplicar

Si la conexión se corta justo después de enviar, no sabes si el pedido se creó. La Idempotency-Key resuelve eso: es un identificador que tú generas (un UUID v4) una vez por pedido. Si repites la petición con la misma clave y el mismo cuerpo, nunca se crea un segundo pedido: te devolvemos el original con la cabecera Idempotent-Replayed: true.

¿No estás seguro de si llegó? Pregúntalo por la clave; funciona en cualquier momento:

curl "https://api.sandbox.sumimega.com/publica/v1/pedidos?clave_idempotencia=$CLAVE" \
  -H "Authorization: Bearer $SUMIMEGA_API_KEY"

Usa una clave nueva solo para un pedido distinto. La clave admite de 8 a 128 caracteres (letras, números, punto, guion, guion bajo y dos puntos) y es por empresa: si cambias tu clave de API, tus reintentos siguen funcionando.

Sedes

Cada sede tiene un código de texto: "07" y "7" son sedes distintas, así que no quites ni agregues ceros. Si envías el código como número, te lo rechazamos.

• Varias sedes: indica punto_envio en cada pedido.
• Una sola sede: puedes omitirlo; te la asignamos y te avisamos en avisos.
• ¿Falta una sede o cambió su dirección? Pídeselo a tu asesor de SumiMega.

Límites

Cada respuesta trae las cabeceras RateLimit-Remaining y RateLimit-Reset. Si superas un límite recibes 429 con Retry-After (segundos a esperar). GET /cuenta te da las cifras vigentes de tu empresa. Si tu operación necesita topes más altos, habla con tu asesor.

Cuida tu clave

• Quien tenga tu clave puede crear pedidos a nombre de tu empresa. Guárdala como una contraseña.
• Nunca la pongas en una URL (la rechazamos), en el código de una página web, en un correo ni en un chat.
• Las claves vencen (te avisamos por correo a los 14 y a los 3 días). Crea la nueva, cámbiala en tu sistema y revoca la anterior.

Si crees que se expuso, revócala ya desde Desarrollador o desde tu propio sistema, y crea otra:

curl -X POST https://api.sandbox.sumimega.com/publica/v1/credencial/revocar \
  -H "Authorization: Bearer $SUMIMEGA_API_KEY"

Errores

Todos los errores tienen la misma forma. Tu sistema debe decidir con code (no cambia), no con message (puede mejorar con el tiempo). Si nos escribes por un error, cita el request_id.

{
  "detail": {
    "code": "pedido_invalido",
    "message": "El pedido tiene 1 problema(s). No se creó.",
    "request_id": "req_6f1d0c2a9b8e4c17a3d5e0f1",
    "errores": [
      {
        "code": "punto_envio_requerido",
        "message": "Tu empresa tiene varias sedes: indica a cuál va el pedido en «punto_envio».",
        "campo": "punto_envio",
        "puntos_validos": [
          "000",
          "01",
          "07"
        ]
      }
    ]
  }
}

Problemas de un pedido

Vienen en errores (al crear) y en problemas (al simular). Te los decimos todos a la vez, para que corrijas de una sola vez:

Preguntas frecuentes