API pública de Start

Conecta tu propio sistema, tu landing o tu CRM: crea pedidos que entran directo a la línea de despacho y consulta su estado. Todo lo que crees dispara tus flujos de confirmación por WhatsApp.

Introducción

La API es REST sobre HTTPS y responde siempre JSON. La URL base es:

https://startco.online

Tres endpoints componen la API pública:

POST /api/publica/pedidos: crea un pedido (con API key).
GET /api/publica/pedidos: consulta pedidos por teléfono o número (con API key).
GET /api/publica/rastreo: rastreo para el cliente final (sin clave, con datos limitados).

Los pedidos creados por API nacen en estado pendiente, con origen manual y la etiqueta api. Si tienes un flujo activo con el trigger pedido_creado, la confirmación por WhatsApp sale en segundos.

Autenticación

Los endpoints de pedidos usan una API key por tienda. Genérala en el panel, en Conexiones → API, y envíala en el header x-api-key de cada petición. La clave empieza por pk_live_ y se muestra completa una sola vez al generarla: guárdala en un lugar seguro.

Header

x-api-key: TU_API_KEY

Usa la clave solo desde tu servidor. No la pongas en código que corra en el navegador ni en apps móviles: quien la tenga puede crear y leer pedidos de tu tienda.

Cada clave pertenece a una sola tienda: los pedidos se crean y se leen siempre en esa tienda. Si tienes varias tiendas, genera una clave por tienda.

Errores y límites

Los errores devuelven un código HTTP adecuado y un JSON con el campo error en español:

{ "error": "items[0].precio debe ser un número mayor o igual a 0." }

200 / 201	Éxito. 201 cuando se crea algo.
400	Datos inválidos o faltantes. El mensaje dice qué campo corregir.
401	API key ausente o inválida.
404	No se encontró lo que buscabas (por ejemplo, una guía).
429	Demasiadas consultas. Espera un minuto y reintenta.

El rastreo público limita las consultas por dirección IP (30 por minuto) y las PQR (5 por hora) para evitar abuso.

Crear pedido

POST/api/publica/pedidosRequiere x-api-key

Crea un pedido contraentrega. Envía el cuerpo como JSON con Content-Type: application/json.

Campo	Tipo	Obligatorio	Descripción
`cliente`	string	Sí	Nombre completo del cliente (2 a 120 caracteres).
`telefono`	string	Sí	Teléfono con indicativo si es posible. Mínimo 7 dígitos. Se usa para WhatsApp y para detectar repetidos.
`ciudad`	string	Sí	Ciudad de entrega.
`direccion`	string	Sí	Dirección de entrega.
`items`	array	Sí	Entre 1 y 50 productos. Ver abajo.
`departamento`	string	No	Departamento, provincia o estado.
`referencia`	string	No	Punto de referencia para el mensajero.
`email`	string	No	Correo del cliente.
`total`	number	No	Total del pedido. Si no lo envías, se suma cantidad por precio de cada item.
`metodo_pago`	string	No	Por defecto “contraentrega”.
`nota`	string	No	Nota interna (hasta 500 caracteres).
`etiquetas`	string[]	No	Hasta 10 etiquetas extra. La etiqueta “api” se agrega sola.

Cada elemento de items:

Campo	Tipo	Obligatorio	Descripción
`producto_id`	integer	No	ID de un producto de tu catálogo. Si lo envías, el nombre y el precio se toman del catálogo cuando faltan.
`nombre`	string	Sí*	Obligatorio si no envías producto_id.
`cantidad`	integer	No	De 1 a 999. Por defecto 1.
`precio`	number	Sí*	Precio unitario, 0 o mayor. Obligatorio si no envías producto_id.

cURL

curl -X POST https://startco.online/api/publica/pedidos \
  -H "x-api-key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cliente": "Ana Ríos",
    "telefono": "+573001234567",
    "ciudad": "Medellín",
    "departamento": "Antioquia",
    "direccion": "Calle 10 # 20-30, apto 301",
    "referencia": "Frente al parque",
    "items": [
      { "nombre": "Masajeador de cuello", "cantidad": 1, "precio": 89900 }
    ]
  }'

Node.js

const r = await fetch("https://startco.online/api/publica/pedidos", {
  method: "POST",
  headers: {
    "x-api-key": process.env.PEDIDOS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    cliente: "Ana Ríos",
    telefono: "+573001234567",
    ciudad: "Medellín",
    direccion: "Calle 10 # 20-30, apto 301",
    items: [{ producto_id: 12, cantidad: 2 }], // nombre y precio salen del catálogo
  }),
});
const datos = await r.json();

Respuesta 201

{
  "ok": true,
  "pedido": {
    "numero": 1043,
    "estado": "pendiente",
    "total": 89900,
    "creado_en": "2026-11-02T15:04:05.000Z"
  }
}

Consultar pedidos

GET/api/publica/pedidosRequiere x-api-key

Lista los pedidos de tu tienda, del más reciente al más antiguo. Debes enviar telefono o numero.

Campo	Tipo	Obligatorio	Descripción
`telefono`	string	Sí*	Teléfono del cliente. Coincide por los últimos 9 dígitos, sin importar el formato o el indicativo.
`numero`	integer	Sí*	Número de pedido. Úsalo en lugar de telefono para traer uno solo.
`limite`	integer	No	Cantidad máxima de resultados, de 1 a 50. Por defecto 20.

cURL

curl "https://startco.online/api/publica/pedidos?telefono=3001234567" \
  -H "x-api-key: TU_API_KEY"

Respuesta 200

{
  "pedidos": [
    {
      "numero": 1043,
      "cliente": "Ana Ríos",
      "telefono": "+573001234567",
      "ciudad": "Medellín",
      "departamento": "Antioquia",
      "direccion": "Calle 10 # 20-30, apto 301",
      "referencia": "Frente al parque",
      "items": [{ "producto_id": null, "nombre": "Masajeador de cuello", "cantidad": 1, "precio": 89900 }],
      "total": "89900",
      "metodo_pago": "contraentrega",
      "origen": "manual",
      "estado": "en_transito",
      "etiquetas": ["api"],
      "guia": "0240332415",
      "transportadora": "Servientrega",
      "creado_en": "2026-11-02T15:04:05.000Z",
      "actualizado": "2026-11-03T09:12:41.000Z"
    }
  ]
}

Rastreo público

GET/api/publica/rastreo?q=Pública, sin clave

Es la API detrás de la página de rastreo. No necesita clave. Busca por número de guía (suficiente por sí sola) o por teléfono junto con el número de pedido. Con teléfono + numero devuelve solo ese pedido; un teléfono sin número de pedido responde 400 (Agrega el número de pedido).

Campo	Tipo	Obligatorio	Descripción
`q`	string	Sí	Número de guía, o teléfono (últimos 9 dígitos) si envías numero. Mínimo 5 caracteres.
`numero`	integer	Con teléfono	Número de pedido. Obligatorio cuando q es un teléfono.

Por privacidad, esta respuesta nunca incluye teléfono, dirección, total ni notas: solo el nombre de pila, el estado, la transportadora, la guía y fechas.

cURL

curl "https://startco.online/api/publica/rastreo?q=0240332415"

Respuesta 200

{
  "resultados": [
    {
      "numero": 1043,
      "nombre": "Ana",
      "estado": "en_reparto",
      "estado_etiqueta": "En reparto",
      "etapa": "Tu paquete está en reparto y llega pronto.",
      "fase": "normal",
      "paso": 2,
      "transportadora": "Servientrega",
      "guia": "0240332415",
      "actualizado": "2026-11-04T13:20:00.000Z",
      "hitos": [
        { "clave": "con_guia", "etiqueta": "Guía generada", "fecha": "2026-11-03T09:12:41.000Z" },
        { "clave": "en_transito", "etiqueta": "En tránsito", "fecha": "2026-11-03T18:40:10.000Z" },
        { "clave": "en_reparto", "etiqueta": "En reparto", "fecha": "2026-11-04T13:20:00.000Z" },
        { "clave": "entregado", "etiqueta": "Entregado", "fecha": null }
      ],
      "eventos": [
        { "tipo": "pendiente", "etiqueta": "Pedido recibido", "fecha": "2026-11-02T15:04:05.000Z" },
        { "tipo": "con_guia", "etiqueta": "Guía generada", "fecha": "2026-11-03T09:12:41.000Z" }
      ]
    }
  ]
}

La línea de tiempo tiene 4 hitos (con_guia, en_transito, en_reparto, entregado). paso indica el hito activo (de 0 a 3; -1 si aún no hay guía). El campo fase es normal, entregado, novedad, oficina, devolucion o cancelado: las tres novedades se muestran como desvíos del hito activo.

Crear PQR

POST/api/publica/rastreo/pqrPública, sin clave

El cliente final radica una pregunta, queja, reclamo o devolución sobre su envío. Se crea un reclamo en la tienda dueña del pedido y se responde el número de radicado.

Campo	Tipo	Obligatorio	Descripción
`guia`	string	Sí	Número de guía del envío.
`tipo`	string	Sí	pregunta, queja, reclamo o devolucion.
`mensaje`	string	Sí	Entre 5 y 1000 caracteres.

cURL

curl -X POST https://startco.online/api/publica/rastreo/pqr \
  -H "Content-Type: application/json" \
  -d '{ "guia": "0240332415", "tipo": "reclamo", "mensaje": "El paquete llegó golpeado." }'

Respuesta 201

{ "ok": true, "radicado": "PQR-000123" }

Estados de pedido

El campo estado toma uno de estos valores:

`pendiente`	Recibido, esperando confirmación del cliente.
`confirmado`	El cliente confirmó. Listo para despachar.
`enviado`	Enviado a la plataforma logística, aún sin guía.
`con_guia`	Guía generada.
`en_transito`	El paquete va en camino.
`en_reparto`	En reparto, llega pronto.
`novedad`	Problema en la entrega (dirección, ausente, etc.).
`oficina`	Disponible para recoger en la oficina de la transportadora.
`entregado`	Entregado al cliente.
`devolucion`	El paquete regresa al remitente.
`cancelado`	Pedido cancelado.

¿Dudas o necesitas otro endpoint? Escríbenos a soporte@startco.online.