Oleada 5 · Documentación

Quick Start

Onboarding para desarrolladores: de cero a un pedido CUSTOM en menos de 15 minutos.

Checklist

☐ GET /health y /health/ready responden OK
☐ API key pk_ creada en el panel
☐ Tienda CUSTOM registrada (guardas shopId y webhookSecret)
☐ Primer pedido POST /custom/orders → 201
☐ Pedido visible en Envíos del panel
☐ (Opcional) Webhook entrante configurado

Variables de entorno (terminal)

export PUSHSLOG_API_BASE="https://api.pushslog.com"
export PUSHSLOG_API_KEY="pk_TU_CLAVE"
export PUSHSLOG_SHOP_ID="SHOP_ID_TRAS_REGISTRO"

En los ejemplos siguientes sustituye $PUSHSLOG_API_KEY y $PUSHSLOG_SHOP_ID, o pega los valores directamente.

1. Comprobar la API

curl -s "$PUSHSLOG_API_BASE/health"
curl -s "$PUSHSLOG_API_BASE/health/ready"

2. Cuenta y API key

Crea un usuario en el panel o pide acceso a tu tenant. Luego:

Inicia sesión.
Tiendas → Custom → API personalizada → Crear clave (pk_…).
Copia el pk_… (solo se muestra una vez).

Detalle de auth: Autenticación.

3. Registrar tienda CUSTOM

curl -s -X POST "$PUSHSLOG_API_BASE/api/v1/custom/shops/register" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PUSHSLOG_API_KEY" \
  -d '{
    "externalShopId": "demo.mi-tienda.com",
    "name": "Mi tienda demo"
  }'

Respuesta típica (201 si es nueva, 200 si ya existía el externalShopId):

{
  "success": true,
  "data": {
    "shopId": "clx00000000000000000000001",
    "externalShopId": "demo.mi-tienda.com",
    "name": "Mi tienda demo",
    "webhookEndpoint": "https://api.pushslog.com/api/v1/webhook/custom",
    "webhookSecret": "whsec_…",
    "headers": {
      "shopId": "X-PushSLog-Shop-Id",
      "signature": "X-PushSLog-Signature"
    }
  },
  "message": "Guarda webhookSecret; no se vuelve a mostrar si lo generamos nosotros."
}

Guarda data.shopId en PUSHSLOG_SHOP_ID, más webhookEndpoint y webhookSecret.

4. Enviar un pedido

curl -s -X POST "$PUSHSLOG_API_BASE/api/v1/custom/orders" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PUSHSLOG_API_KEY" \
  -d '{
    "shopId": "'"$PUSHSLOG_SHOP_ID"'",
    "orderId": "ORD-1001",
    "total": 129900,
    "currency": "COP",
    "shippingAddress": {
      "city": "Bogotá",
      "address": "Calle 123 #45-67",
      "zip": "110111"
    }
  }'

shippingAddress es opcional; ayuda a cotizar envío desde el panel. Respuesta 201:

{
  "success": true,
  "data": {
    "id": "clx00000000000000000000002",
    "orderNumber": "PS-1042",
    "externalId": "ORD-1001",
    "status": "pending",
    "total": "129900",
    "currency": "COP",
    "shopId": "clx00000000000000000000001"
  }
}

5. Errores frecuentes

HTTP	error	Cuándo
401	API_KEY_REQUIRED	Falta header x-api-key o Bearer pk_…
403	API_KEY_INVALID	Clave revocada, mal copiada o de otro tenant
400	BAD_REQUEST	Falta externalShopId, shopId, orderId o total en el body
400	CUSTOM_INVALID_SHOP_ID	externalShopId con formato no válido
404	CUSTOM_SHOP_NOT_FOUND	shopId no pertenece al tenant de la pk_
500	CUSTOM_REGISTER_FAILED / CUSTOM_ORDER_FAILED	Error interno; reintenta y contacta soporte con hora UTC

Más respuestas en FAQ técnica, Autenticación y Referencia API.

6. Verificar en el panel

Tras el 201, el pedido queda en operación logística. Revisa en Envíos buscando ORD-1001 o el orderNumber devuelto (ej. PS-1042). Desde ahí puedes cotizar, crear guía o seguir el flujo de tu plan.

Si no aparece: confirma que shopId y pk_ son del mismo tenant y que el body incluyó orderId y total.

7. Siguientes pasos

Configurar webhooks para eventos entrantes firmados.
Conectar Shopify, Woo, ML o Tienda Nube si aplica.
Inventario omnicanal — catálogo central, mapeos y sync multi-canal.
Referencia API completa y openapi.json.

¿Bloqueo en producción? Escribe a soporte con error, message y hora UTC.