API Export

elpizzero hesabınızdaki verileri —siparişler, menü, bölgeler, restoran ve metrikler— kendi sistemlerinize (CRM, BI, muhasebe, ekranlar vb.) aktarmak için salt okunur REST API. Değişikliklere gerçek zamanlı tepki verebilmeniz için canlı akış (SSE) ve giden webhooks içerir.

• Base URL: https://elpizzero.com/api/export
• Auth: her istekte Authorization: Bearer <token>.
• Biçim: JSON UTF-8. Tutarlar tam sayı cent olarak, tarihler ISO-8601 UTC.
• Yöntemler: tüm kaynaklarda GET; POST/DELETE yalnızca webhooks yönetimi için.

Kimlik doğrulama

Başlıkta Bearer token. Token'lar elp_live_<32hex> veya elp_test_<32hex> biçimindedir.

Authorization: Bearer elp_live_3b8f0c2a1d4e5f6079a8b7c6d5e4f3a2

Token'ları Panel → Entegrasyonlar → API Anahtarları bölümünde izinlerini seçerek oluşturun ve iptal edin. Token yalnızca bir kez tam olarak gösterilir.

İzinler

Gerekli scope'u olmayan token → 403 alcance_insuficiente.

Ortamlar

elp_live_ ve elp_test_ aynı gerçek verileri okur; simüle verili bir sandbox yoktur. Önek, token'larınızı ayırt etmeniz için yalnızca bir etikettir.

Rate limit

Token başına dakikada 60 istek. Her yanıtta başlıklar: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Aşıldığında → 429 + Retry-After.

Kurallar

• Para: tam sayı cent (total_cents: 820 = 8,20 €). Para birimi ayrı bir alanda (moneda: "EUR").
• Tarihler: Z ile ISO-8601 UTC (2026-05-31T20:42:15Z).
• ID'ler: tür önekli opak değerler — ped_, prod_, cat_, tam_, grp_, opt_, zon_, rest_, itm_, wh_. Bunları string olarak ele alın.
• İzolasyon: her token bir restorana bağlıdır; yalnızca o restoranın verilerini döndürür.
• Sayfalama: cursor ile (cursor → paginacion.siguiente), varsayılan sıralama azalan.

Hatalar

Tekdüze gövde + tutarlı HTTP kodu:

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

Siparişleri listele

Restoranın siparişleri, id azalan sırada, cursor ile sayfalama.

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 }
}

Bir siparişi getir

Sipariş nesnesini döndürür. {id} önekli, ör. ped_ni. Size ait değilse 404 no_encontrado.

Bir siparişin geçmişi

{
  "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":{} }
  ]
}

Menü

Kategoriler → ürünler → boyutlar → seçenek grupları → seçenekler şeklinde tam ağaç. ?solo_disponibles=true gizli/tükenmiş öğeleri hariç tutar.

{
  "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 }] }]
    }]
  }]
}

Teslimat bölgeleri

Çokgenli bölgeler GeoJSON olarak (koordinatlar [lng, lat], kapalı halka).

{ "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], /* … */]] }
}] }

Restoran

Restoran kartı: iletişim, konum, güne göre çalışma saatleri, marka, kanala göre diller, itibar. Hassas vergi verileri yok.

{
  "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 }
}

Özet / metrikler

periodo ∈ hoyayer7d30dmes_actual. Restoranın saat diliminde hesaplanır; iptal edilen/reddedilenleri hariç tutar.

{
  "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 }]
}

Canlı akış (SSE)

Server-Sent Events. Olayları anında iletir. Kimlik doğrulama query ile (EventSource başlık desteklemez). Last-Event-ID ile her 5 dakikada yerel yeniden bağlanma; yaklaşık her 25 sn'de bir conexion.ping.

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);
});

İsteğe bağlı filtre ?eventos=pedido.nuevo,pedido.aceptado. Yayımlanan türler:

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

Giden webhooks

Pull → push alternatifi: bir sipariş değiştiğinde URL'nize POST göndeririz. Yalnızca giden.

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 }

Olaylar: akıştakiler + pedido.* ve * joker karakterleri.  GET /webhooks listeler · DEL /webhooks/{id} siler.

Teslimat ve imza

Her gönderim şu başlıkları içerir; gövde akıştaki nesnenin aynısıdır:

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);

Sipariş nesnesi

/pedidos, /pedidos/{id}, akış ve webhooks tarafından döndürülen yapı. Örnekteki müşteri verileri anonimleştirilmiştir. direccion/mesa/entrega/fiscal geçerli olmadığında null olur.

{
  "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
}

Örnek: mutfak TV ekranı

Kendi içinde çalışan HTML+JS (salt okunur): token'ınızı yapıştırın, bir TV'de açın; siparişler akış üzerinden canlı gelir.

→ Mutfak TV örneğini aç