Appi · Store | Droni.co

El catálogo público solo expone productos activos. Los pedidos se calculan siempre en el servidor: tu frontend envía productos y cantidades, y appi toma los precios reales y aplica el cupón.

Flujo típico de checkout: el usuario arma el carrito → POST /store/orders → procesas el cobro con tu pasarela → POST /store/payments para registrar la transacción → el owner confirma el pago y avanza el estado del pedido.

Catálogo

GET/store/products Público

Listar productos activos

Query string

`page`	`number`	Página a consultar (por defecto 1).
`per_page`	`number`	Resultados por página (por defecto 10).
`q`	`string`	Búsqueda por nombre o descripción.
`tags`	`string \| string[]`	Filtra por etiquetas (todas deben coincidir).

Ejemplo de respuesta

{
  "meta": {
    "total": 15,
    "perPage": 10,
    "currentPage": 1,
    "lastPage": 2,
    "firstPage": 1
  },
  "data": [
    {
      "id": "uuid",
      "slug": "camiseta-negra",
      "name": "Camiseta negra",
      "description": "100% algodón",
      "content": "Descripción larga…",
      "picture": "https://…",
      "price": "45000.00",
      "stock": 20,
      "tags": ["ropa"],
      "sizeW": 30, "sizeH": 2, "sizeD": 40, "weight": 0.2,
      "active": true,
      "attributes": [{ "id": "uuid", "name": "Talla", "value": "M" }]
    }
  ]
}

GET/store/products/:slug Público

Obtener un producto por slug

Parámetros de ruta

slugrequerido string Slug del producto.

Ejemplo de respuesta

{
  "id": "uuid",
  "slug": "camiseta-negra",
  "name": "Camiseta negra",
  "description": "100% algodón",
  "content": "Descripción larga…",
  "picture": "https://…",
  "price": "45000.00",
  "stock": 20,
  "tags": ["ropa"],
  "sizeW": 30, "sizeH": 2, "sizeD": 40, "weight": 0.2,
  "active": true,
  "attributes": [{ "id": "uuid", "name": "Talla", "value": "M" }]
}

Direcciones del usuario

GET/store/addresses Autenticado

Listar mis direcciones

Incluye la ciudad y su departamento cuando existen.

POST/store/addresses Autenticado

Crear una dirección

Cuerpo (JSON)

`address_line1`requerido	`string`	Dirección principal.
`address_line2`	`string \| null`	Complemento (apto, torre…).
`city_id`	`number \| null`	Ciudad.
`postal_code`	`string \| null`	Código postal.
`phone`	`string \| null`	Teléfono de contacto.
`comments`	`string \| null`	Indicaciones para la entrega.

Ejemplo de petición

{ "address_line1": "Calle 1 # 2-3", "postal_code": "110111", "phone": "3001234567" }

GET/store/addresses/:id Autenticado

Obtener una dirección propia

Parámetros de ruta

idrequerido string ID de la dirección.

PUT/store/addresses/:id Autenticado

Actualizar una dirección propia

Todos los campos son opcionales.

Parámetros de ruta

idrequerido string ID de la dirección.

Cuerpo (JSON)

`address_line1`	`string`	Dirección principal.
`address_line2`	`string \| null`	Complemento (apto, torre…).
`city_id`	`number \| null`	Ciudad.
`postal_code`	`string \| null`	Código postal.
`phone`	`string \| null`	Teléfono de contacto.
`comments`	`string \| null`	Indicaciones para la entrega.

DELETE/store/addresses/:id Autenticado

Eliminar una dirección propia

Parámetros de ruta

idrequerido string ID de la dirección.

Pedidos y pagos

GET/store/orders Autenticado

Listar mis pedidos

Query string

`page`	`number`	Página a consultar (por defecto 1).
`per_page`	`number`	Resultados por página (por defecto 10).

Ejemplo de respuesta

{
  "meta": {
    "total": 15,
    "perPage": 10,
    "currentPage": 1,
    "lastPage": 2,
    "firstPage": 1
  },
  "data": [
    {
      "id": "uuid",
      "status": "pending",
      "total": "81000",
      "shippingAddress": { "addressLine1": "Calle 1 # 2-3", "city": "Bogotá" },
      "billingAddress": null,
      "items": [{ "id": "uuid", "productId": "uuid", "quantity": 2, "price": "45000.00" }],
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

POST/store/orders Autenticado

Crear un pedido

Cuerpo (JSON)

`items`requerido	`{ product_id: string, quantity: number }[]`	Al menos un item; quantity ≥ 1.
`shipping_address`	`object`	Dirección de envío (objeto libre; puedes copiar una de /store/addresses).
`billing_address`	`object`	Dirección de facturación.
`coupon_code`	`string \| null`	Código de cupón (no distingue mayúsculas).

Ejemplo de petición

{
  "items": [{ "product_id": "uuid", "quantity": 2 }],
  "shipping_address": { "addressLine1": "Calle 1 # 2-3", "city": "Bogotá" },
  "coupon_code": "BIENVENIDA10"
}

Ejemplo de respuesta

{
  "id": "uuid",
  "status": "pending",
  "total": "81000",
  "shippingAddress": { "addressLine1": "Calle 1 # 2-3", "city": "Bogotá" },
  "billingAddress": null,
  "items": [{ "id": "uuid", "productId": "uuid", "quantity": 2, "price": "45000.00" }],
  "createdAt": "2026-01-01T00:00:00.000Z"
}

El pedido se crea con estado pending.
Responde 400 si algún producto no existe o está inactivo, o si el cupón es inválido, expiró o no alcanza el pedido mínimo.

GET/store/orders/:id Autenticado

Obtener un pedido propio

Incluye los items con su producto y los pagos registrados.

Parámetros de ruta

idrequerido string ID del pedido.

GET/store/payments Autenticado

Listar mis pagos

Query string

`page`	`number`	Página a consultar (por defecto 1).
`per_page`	`number`	Resultados por página (por defecto 10).

POST/store/payments Autenticado

Registrar un pago

Cuerpo (JSON)

`order_id`requerido	`string`	Pedido propio al que corresponde.
`payment_method`requerido	`string`	Medio de pago (ej. credit_card, pse).
`amount`requerido	`number`	Monto pagado.
`currency`	`string`	Moneda ISO (por defecto USD).
`transaction_id`	`string \| null`	Referencia de la transacción en tu pasarela.

Ejemplo de petición

{ "order_id": "uuid", "payment_method": "credit_card", "amount": 81000, "currency": "COP", "transaction_id": "txn_abc123" }

Ejemplo de respuesta

{
  "id": "uuid",
  "orderId": "uuid",
  "paymentMethod": "credit_card",
  "paymentStatus": "pending",
  "amount": "81000",
  "currency": "COP",
  "transactionId": "txn_abc123"
}

El pago siempre se registra como pending. Su confirmación la hace el owner (o tu backend con credenciales de owner) tras validar la transacción con la pasarela; nunca marques un pedido como pagado basándote solo en lo que reporta el navegador.

GET/store/payments/:id Autenticado

Obtener un pago propio

Parámetros de ruta

idrequerido string ID del pago.

Ejemplo de respuesta

{
  "id": "uuid",
  "orderId": "uuid",
  "paymentMethod": "credit_card",
  "paymentStatus": "pending",
  "amount": "81000",
  "currency": "COP",
  "transactionId": "txn_abc123"
}

Administración de la tienda

Solo owner del sitio

Estas rutas solo responden a usuarios con rol owner. Úsalas desde un panel de administración privado, nunca desde el frontend público de tu sitio.

GET/admin/store/products Owner del sitio

Listar todos los productos

Query string

`page`	`number`	Página a consultar (por defecto 1).
`per_page`	`number`	Resultados por página (por defecto 10).
`q`	`string`	Búsqueda.

POST/admin/store/products Owner del sitio

Crear un producto

Cuerpo (JSON)

`name`requerido	`string`	Nombre. El slug se genera a partir de él.
`price`requerido	`number`	Precio unitario (≥ 0).
`stock`requerido	`number`	Unidades disponibles (≥ 0).
`description`	`string \| null`	Resumen.
`content`	`string \| null`	Descripción larga.
`picture`	`string \| null`	URL de la imagen.
`tags`	`string[] \| null`	Etiquetas.
`size_w / size_h / size_d`	`number \| null`	Dimensiones en cm.
`weight`	`number \| null`	Peso en kg.
`active`	`boolean`	Visible en el catálogo público.

Ejemplo de petición

{ "name": "Camiseta negra", "price": 45000, "stock": 20, "tags": ["ropa"], "active": true }

GET/admin/store/products/:id Owner del sitio

Obtener un producto por id

Parámetros de ruta

idrequerido string ID del producto.

PUT/admin/store/products/:id Owner del sitio

Actualizar un producto

Parámetros de ruta

idrequerido string ID del producto.

Cuerpo (JSON)

`name`	`string`	Nombre. El slug se genera a partir de él.
`price`	`number`	Precio unitario (≥ 0).
`stock`	`number`	Unidades disponibles (≥ 0).
`description`	`string \| null`	Resumen.
`content`	`string \| null`	Descripción larga.
`picture`	`string \| null`	URL de la imagen.
`tags`	`string[] \| null`	Etiquetas.
`size_w / size_h / size_d`	`number \| null`	Dimensiones en cm.
`weight`	`number \| null`	Peso en kg.
`active`	`boolean`	Visible en el catálogo público.

DELETE/admin/store/products/:id Owner del sitio

Eliminar un producto

Parámetros de ruta

idrequerido string ID del producto.

GET/admin/store/products/:product_id/attributes Owner del sitio

Listar atributos de un producto

Parámetros de ruta

product_idrequerido string ID del producto.

POST/admin/store/products/:product_id/attributes Owner del sitio

Agregar un atributo

Parámetros de ruta

product_idrequerido string ID del producto.

Cuerpo (JSON)

`name`requerido	`string`	Clave (ej. Talla).
`value`requerido	`string`	Valor (ej. M).

Ejemplo de petición

{ "name": "Talla", "value": "M" }

DELETE/admin/store/products/:product_id/attributes/:id Owner del sitio

Eliminar un atributo

Parámetros de ruta

`product_id`requerido	`string`	ID del producto.
`id`requerido	`string`	ID del atributo.

GET/admin/store/orders Owner del sitio

Listar pedidos del sitio

Query string

`page`	`number`	Página a consultar (por defecto 1).
`per_page`	`number`	Resultados por página (por defecto 10).
`status`	`string`	Filtra por estado.

GET/admin/store/orders/:id Owner del sitio

Ver un pedido

Parámetros de ruta

idrequerido string ID del pedido.

PUT/admin/store/orders/:id Owner del sitio

Cambiar el estado de un pedido

Parámetros de ruta

idrequerido string ID del pedido.

Cuerpo (JSON)

statusrequerido 'pending' | 'paid' | 'shipped' | 'completed' | 'canceled' Nuevo estado.

Ejemplo de petición

{ "status": "shipped" }

GET/admin/store/payments Owner del sitio

Listar pagos del sitio

Query string

`page`	`number`	Página a consultar (por defecto 1).
`per_page`	`number`	Resultados por página (por defecto 10).
`status`	`string`	Filtra por estado.

GET/admin/store/payments/:id Owner del sitio

Ver un pago

Parámetros de ruta

idrequerido string ID del pago.

PUT/admin/store/payments/:id Owner del sitio

Confirmar o rechazar un pago

Parámetros de ruta

idrequerido string ID del pago.

Cuerpo (JSON)

payment_statusrequerido 'pending' | 'completed' | 'failed' Nuevo estado del pago.

Ejemplo de petición

{ "payment_status": "completed" }

GET/admin/store/coupons Owner del sitio

Listar cupones

Query string

`page`	`number`	Página a consultar (por defecto 1).
`per_page`	`number`	Resultados por página (por defecto 10).

POST/admin/store/coupons Owner del sitio

Crear un cupón

Cuerpo (JSON)

`code`requerido	`string`	Código; se guarda en mayúsculas.
`discount`requerido	`number`	Valor del descuento.
`discount_type`requerido	`'percentage' \| 'fixed'`	Porcentaje sobre el subtotal o monto fijo.
`minimum_order_value`	`number \| null`	Subtotal mínimo para aplicarlo.
`expiration_date`	`string \| null`	Fecha ISO de expiración.
`active`	`boolean`	Si puede usarse.

Ejemplo de petición

{ "code": "BIENVENIDA10", "discount": 10, "discount_type": "percentage", "minimum_order_value": 50000 }

GET/admin/store/coupons/:id Owner del sitio

Obtener un cupón

Parámetros de ruta

idrequerido string ID del cupón.

PUT/admin/store/coupons/:id Owner del sitio

Actualizar un cupón

Parámetros de ruta

idrequerido string ID del cupón.

Cuerpo (JSON)

`code`	`string`	Código; se guarda en mayúsculas.
`discount`	`number`	Valor del descuento.
`discount_type`	`'percentage' \| 'fixed'`	Porcentaje sobre el subtotal o monto fijo.
`minimum_order_value`	`number \| null`	Subtotal mínimo para aplicarlo.
`expiration_date`	`string \| null`	Fecha ISO de expiración.
`active`	`boolean`	Si puede usarse.

DELETE/admin/store/coupons/:id Owner del sitio

Eliminar un cupón

Parámetros de ruta

idrequerido string ID del cupón.

GET/admin/store/shipping-rules Owner del sitio

Listar reglas de envío

Query string

`page`	`number`	Página a consultar (por defecto 1).
`per_page`	`number`	Resultados por página (por defecto 10).

POST/admin/store/shipping-rules Owner del sitio

Crear una regla de envío

Cuerpo (JSON)

`name`requerido	`string`	Nombre de la regla.
`price`requerido	`number`	Costo base.
`state_id`	`number \| null`	Departamento/estado al que aplica.
`city_id`	`number \| null`	Ciudad a la que aplica.
`price_per_kg`	`number \| null`	Recargo por kilogramo.
`price_per_cm3`	`number \| null`	Recargo por volumen.
`active`	`boolean`	Si está vigente.

Ejemplo de petición

{ "name": "Envío nacional", "price": 12000, "price_per_kg": 2000 }

GET/admin/store/shipping-rules/:id Owner del sitio

Obtener una regla de envío

Parámetros de ruta

idrequerido string ID de la regla.

PUT/admin/store/shipping-rules/:id Owner del sitio

Actualizar una regla de envío

Parámetros de ruta

idrequerido string ID de la regla.

Cuerpo (JSON)

`name`	`string`	Nombre de la regla.
`price`	`number`	Costo base.
`state_id`	`number \| null`	Departamento/estado al que aplica.
`city_id`	`number \| null`	Ciudad a la que aplica.
`price_per_kg`	`number \| null`	Recargo por kilogramo.
`price_per_cm3`	`number \| null`	Recargo por volumen.
`active`	`boolean`	Si está vigente.

DELETE/admin/store/shipping-rules/:id Owner del sitio

Eliminar una regla de envío

Parámetros de ruta

idrequerido string ID de la regla.