API Export

واجهة REST API للقراءة فقط لتصدير بيانات حسابك في elpizzero —الطلبات والقائمة والمناطق والمطعم والمقاييس— إلى أنظمتك الخاصة (CRM وBI والمحاسبة والشاشات وغيرها). تتضمن بثًا مباشرًا (SSE) وwebhooks صادرة للتفاعل مع التغييرات في الوقت الفعلي.

• Base URL: https://elpizzero.com/api/export
• Auth: Authorization: Bearer <token> مع كل طلب.
• التنسيق: JSON UTF-8. المبالغ بالسنتات كأعداد صحيحة، والتواريخ بصيغة ISO-8601 UTC.
• الطرق: GET لجميع الموارد؛ وPOST/DELETE فقط لإدارة webhooks الخاصة بك.

المصادقة

Bearer token في الترويسة. تأخذ الـ tokens الصيغة elp_live_<32hex> أو elp_test_<32hex>.

Authorization: Bearer elp_live_3b8f0c2a1d4e5f6079a8b7c6d5e4f3a2

أنشئ الـ tokens وألغِها من اللوحة ← التكاملات ← مفاتيح API مع اختيار صلاحياتها. يظهر الـ token كاملًا مرة واحدة فقط.

الصلاحيات

token بدون الـ scope المطلوب ← 403 alcance_insuficiente.

البيئات

elp_live_ وelp_test_ يقرآن البيانات الحقيقية نفسها؛ لا توجد بيئة sandbox ببيانات محاكاة. البادئة مجرد وسم لتمييز الـ tokens الخاصة بك.

Rate limit

60 طلبًا/دقيقة لكل token. الترويسات في كل استجابة: X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset. عند التجاوز ← 429 + Retry-After.

الاصطلاحات

• المال: سنتات كأعداد صحيحة (total_cents: 820 = 8,20 €). العملة في حقل منفصل (moneda: "EUR").
• التواريخ: ISO-8601 UTC مع Z (2026-05-31T20:42:15Z).
• المعرّفات: مبهمة مع بادئة نوع — ped_, prod_, cat_, tam_, grp_, opt_, zon_, rest_, itm_, wh_. تعامل معها كسلاسل نصية (strings).
• العزل: كل token مرتبط بمطعم واحد؛ ولا يُرجع إلا بياناته.
• ترقيم الصفحات: بواسطة cursor (cursor ← paginacion.siguiente)، والترتيب الافتراضي تنازلي.

الأخطاء

جسم موحّد + رمز HTTP متسق:

{
  "ok": false,
  "error": "Esta llave no tiene el alcance necesario: pedidos.leer",
  "codigo": "alcance_insuficiente",
  "doc": "https://elpizzero.com/docs/api/export#auth"
}

عرض الطلبات

طلبات المطعم، بترتيب id تنازلي، مع ترقيم صفحات بواسطة cursor.

curl "https://elpizzero.com/api/export/pedidos?estado=entregado&desde=2026-05-01&limite=50" \
  -H "Authorization: Bearer elp_live_..."

{
  "datos": [ /* Objeto Pedido */ ],
  "paginacion": { "limite":50, "siguiente":"ni", "anterior":null, "total_aprox":494 }
}

الحصول على طلب

يُرجع كائن الطلب. {id} مع البادئة، مثل ped_ni. 404 no_encontrado إذا لم يكن يخصك.

سجل طلب

{
  "pedido_id": "ped_ni",
  "eventos": [
    { "momento":"2026-05-31T20:42:15Z", "accion":"order_created",
      "origen":"sistema", // sistema|panel|tpv|apk_recepcion|api
      "usuario":null, "detalle":{} }
  ]
}

القائمة

الشجرة الكاملة: الفئات ← المنتجات ← الأحجام ← مجموعات الخيارات ← الخيارات. ?solo_disponibles=true يستبعد المخفي/النافد.

{
  "restaurante_id":"rest_1", "restaurante_slug":"tu-restaurante",
  "moneda":"EUR", "idioma_origen":"es", "generado_en":"2026-06-01T18:41:27Z",
  "categorias": [{
    "id":"cat_v", "nombre":"Pizzas", "activa":true,
    "visible_dias":["lun","mar","mie","jue","vie","sab","dom"], "visible_horario":null,
    "productos": [{
      "id":"prod_3J", "nombre":"Margarita", "precio_cents":680,
      "disponible":true, "destacado":false, "alergenos":["gluten","lacteos"],
      "tamaños":[{ "id":"tam_11", "nombre":"mediana", "precio_cents":680, "predeterminado":true }],
      "grupos_opcion":[{ "id":"grp_73", "nombre":"Extras", "requerido":false,
        "min_seleccion":0, "max_seleccion":5,
        "opciones":[{ "id":"opt_8", "nombre":"Extra queso", "precio_cents":120 }] }]
    }]
  }]
}

مناطق التوصيل

مناطق بمضلع بصيغة GeoJSON (الإحداثيات [lng, lat]، حلقة مغلقة).

{ "datos": [{
  "id":"zon_8", "nombre":"Albatera", "slug":"albatera",
  "color":"#44c3e5", "tarifa_cents":250, "pedido_minimo_cents":2000,
  "minutos_estimados":40, "activa":true,
  "poligono":{ "tipo":"Polygon", "coordenadas":[[[-0.872,38.186], /* … */]] }
}] }

المطعم

بطاقة المطعم: الاتصال، الموقع، ساعات العمل لكل يوم، الهوية البصرية، اللغات لكل قناة، السمعة. بدون بيانات ضريبية حساسة.

{
  "id":"rest_1", "slug":"tu-restaurante", "nombre":"Tu Restaurante",
  "moneda":"EUR", "zona_horaria":"Europe/Madrid",
  "acepta_pedidos":true, "pedido_minimo_cents":500,
  "horario":{ "viernes":[{"desde":"18:45","hasta":"23:30"}] /* … */ },
  "contacto":{ "email":"…", "telefono":"…", "web":"…" },
  "ubicacion":{ "direccion":"…", "ciudad":"…", "lat":38.14, "lng":-0.88 },
  "branding":{ "logo_url":"…", "color_primario":"…", "galeria":[] },
  "reputacion":{ "puntuacion":4.7, "votos":128 }
}

ملخص / مقاييس

periodo ∈ hoyayer7d30dmes_actual. يُحسب بالمنطقة الزمنية للمطعم؛ ويستبعد الملغاة/المرفوضة.

{
  "periodo":"30d", "desde":"2026-05-03T00:00:00+02:00", "hasta":"2026-06-02T00:00:00+02:00",
  "zona_horaria":"Europe/Madrid",
  "kpis":{ "pedidos_total":442, "pedidos_cancelados":52, "clientes_distintos":413,
    "ventas_cents":893435, "ticket_medio_cents":2021, "moneda":"EUR" },
  "mix_tipo":{ "reparto":268, "recogida":171, "mesa":3 },
  "top_productos":[{ "producto_id":"prod_3K", "nombre":"Margarita", "unidades":150, "ventas_cents":113845 }]
}

البث المباشر (SSE)

Server-Sent Events. يدفع الأحداث فورًا. المصادقة عبر query (لا يدعم EventSource الترويسات). إعادة اتصال أصلية كل 5 دقائق عبر Last-Event-ID؛ وconexion.ping كل ~25 ثانية.

const es = new EventSource("https://elpizzero.com/api/export/stream?llave=elp_live_...");
es.addEventListener("pedido.nuevo", e => {
  const ev = JSON.parse(e.data);   // ev.datos.pedido = Objeto Pedido
  console.log(ev.datos.pedido.numero);
});

مرشّح اختياري ?eventos=pedido.nuevo,pedido.aceptado. الأنواع المُرسَلة:

pedido.nuevopedido.aceptadopedido.rechazadopedido.estado_cambiadopedido.item_modificadopedido.entregadopedido.cancelado

Webhooks الصادرة

بديل pull ← push: نرسل POST إلى عنوان URL الخاص بك عند تغيّر طلب. صادرة فقط.

curl -X POST "https://elpizzero.com/api/export/webhooks" \
  -H "Authorization: Bearer elp_live_..." -H "Content-Type: application/json" \
  -d '{"url":"https://tu-sistema.com/hook","nombre":"Mi CRM","eventos":["pedido.aceptado","pedido.entregado"]}'

{ "id":"wh_3", "url":"https://tu-sistema.com/hook",
  "eventos":["pedido.aceptado","pedido.entregado"],
  "secreto_firma":"a1b2…(64 hex, se muestra UNA vez)", "activo":true }

الأحداث: أحداث البث + الرموز البديلة pedido.* و*.  GET /webhooks يعرض · DEL /webhooks/{id} يحذف.

التسليم والتوقيع

يتضمن كل إرسال هذه الترويسات؛ والجسم هو نفس كائن البث:

X-Elp-Evento: pedido.aceptado
X-Elp-Id: 84213            # úsalo como clave de idempotencia
X-Elp-Firma: <hmac_sha256_hex(secreto, cuerpo_crudo)>
X-Elp-Intento: 1

// Verificación (Node)
const firma = crypto.createHmac("sha256", SECRETO).update(rawBody).digest("hex");
if (firma !== req.headers["x-elp-firma"]) return res.sendStatus(401);

كائن الطلب

البنية المُرجعة من /pedidos و/pedidos/{id} والبث وwebhooks. بيانات العميل مجهّلة في المثال. تكون direccion/mesa/entrega/fiscal بقيمة null عندما لا تنطبق.

{
  "id":"ped_ni", "numero":"20260531-095",
  "tipo":"reparto",          // reparto|recogida|mesa
  "estado":"en_preparacion",
  "fuente":"web_publica",    // web_publica|tpv|manual|admin
  "creado_en":"2026-05-31T20:42:15Z", "aceptado_en":"…Z",
  "entregado_en":null, "programado_para":null,

  "restaurante":{ "id":"rest_1", "slug":"tu-restaurante", "nombre":"Tu Restaurante" },
  "cliente":{ "nombre":"Juan Pérez", "telefono":"+34 600 000 000",
    "email":"cliente@ejemplo.com", "consintio_marketing":false },
  "direccion":{ "linea":"Calle Mayor 22", "codigo_postal":null, "pais":"ES", "lat":38.154, "lng":-0.880 },
  "mesa":null,

  "items":[{ "id":"itm_A3", "producto_id":"prod_3K", "nombre":"Margarita",
    "tamaño":"mediana", "cantidad":1,
    "precio_unitario_cents":720, "opciones_total_cents":120, "total_cents":840,
    "estado_cocina":"pendiente",
    "opciones":[{ "id":"opc_5", "grupo":"Extras", "nombre":"Extra queso", "cantidad":1, "precio_cents":120 }] }],

  "totales":{ "moneda":"EUR", "subtotal_cents":840, "descuento_cents":0, "propina_cents":0,
    "tarifa_reparto_cents":100, "impuestos_cents":85, "total_cents":1025,
    "iva_desglose":[{ "tipo_porcentaje":10, "base_cents":940, "iva_cents":85 }] },
  "pago":{ "metodo":"online", "estado":"pagado", "proveedor":"stripe",
    "referencia_externa":"pi_3Td…", "pagos":[] },
  "entrega":{ "repartidor_nombre":null, "zona_id":"zon_a", "zona_nombre":"Granja de Rocamora", "tarifa_cents":100 },
  "fiscal":{ "factura_numero":"FA-1132/2026", "factura_fecha":"…Z", "factura_pdf":"https://…/factura.pdf" },
  "instrucciones":null
}

مثال: شاشة تلفاز المطبخ

HTML+JS مستقل (للقراءة فقط): الصق الـ token الخاص بك وافتحه على تلفاز وستصل الطلبات مباشرة عبر البث.

← فتح مثال تلفاز المطبخ