Berria VERI*FACTU 2027an dator, eta elpizzero prest dago jada. Jakin nola Hitz egingo dugu?Partners: para agencias

elpizzero

API Export

Irakurketa soilekoa den REST API bat, zure elpizzero kontuko datuak —eskaerak, karta, eremuak, jatetxea eta metrikak— zure sistemetara (CRM, BI, kontabilitatea, pantailak, etab.) esportatzeko. Zuzeneko stream-a (SSE) eta irteerako webhook-ak ditu, aldaketei denbora errealean erreakzionatzeko.

Oinarrizko URL-a: https://elpizzero.com/api/export
Autentifikazioa: Authorization: Bearer <token> eskaera bakoitzean.
Formatua: JSON UTF-8. Zenbatekoak zenbaki oso gisa zentimotan, datak ISO-8601 UTC formatuan.
Metodoak: GET baliabide guztietan; POST/DELETE zure webhook-ak kudeatzeko bakarrik.

Irismena. API honek ez ditu eskaerak sortzen ez aldatzen. Eskaerak elpizzero-ra sartzea ez da publikoa eta ez da hemen dokumentatzen: kontuka gaitzen da, aldez aurretik baliozkotu ondoren. Horrelako zerbait behar baduzu, idatzi iezaguzu helbide honetara: api@elpizzero.com.

Autentifikazioa

Bearer token goiburuaren bidez. Token-ek elp_live_<32hex> edo elp_test_<32hex> formatua dute.

Authorization: Bearer elp_live_3b8f0c2a1d4e5f6079a8b7c6d5e4f3a2

Token-ak Panela → Integrazioak → API giltzak atalean sortu eta baliogabetzen dira, baimenak aukeratuz. Token-a osorik behin bakarrik erakusten da.

Baimenak

Scope	Gaitzen du
`pedidos.leer`	`/pedidos`, `/pedidos/{id}`, `/pedidos/{id}/historial`, `/resumen`
`carta.leer`	`/carta`
`restaurante.leer`	`/restaurante`, `/zonas`
`stream.escuchar`	`/stream` (SSE)
`webhook.recibir`	`/webhooks` (alta/baja/zerrenda)

Beharrezko scope-rik gabeko token-a → 403 alcance_insuficiente.

Inguruneak

elp_live_ eta elp_test_ datu errealak berak irakurtzen dituzte; ez dago datu simulatuko sandbox-ik. Aurrizkia zure token-ak bereizteko etiketa bat besterik ez da.

Rate limit

60 eskaera/min token bakoitzeko. Erantzun bakoitzeko goiburuak: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Gainditzen bada → 429 + Retry-After.

Konbentzioak

Dirua: zentimo osoak (total_cents: 820 = 8,20 €). Moneta eremu bereizian doa (moneda: "EUR").
Datak: ISO-8601 UTC, Z amaierarekin (2026-05-31T20:42:15Z).
ID-ak: opakoak, motaren aurrizkiarekin — ped_, prod_, cat_, tam_, grp_, opt_, zon_, rest_, itm_, wh_. Tratatu itzazu string gisa.
Isolamendua: token bakoitza jatetxe bati lotuta dago; haren datuak bakarrik itzultzen ditu.
Paginazioa: cursor bidezkoa (cursor → paginacion.siguiente), ordena lehenetsia beheranzkoa.

Erroreak

Gorputz uniformea + HTTP kode koherentea:

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

HTTP	codigo
401	`llave_ausente` · `llave_invalida` · `llave_revocada` · `llave_expirada`
403	`alcance_insuficiente` · `restaurante_inactivo`
400	`parametro_invalido` (`valores_validos` barne)
404	`no_encontrado`
405 / 429	`metodo_invalido` · `limite_alcanzado`

Eskaerak zerrendatu

GET /pedidos

Jatetxearen eskaerak, id beheranzko ordenan, cursor bidezko paginazioarekin.

Query	Tipo	Deskribapena
`estado`	csv	pendienteconfirmadoen_preparacionlistoen_repartoentregadocancelado
`tipo`	enum	repartorecogidamesa
`desde` / `hasta`	ISO	`creado_en` eremuaren gaineko tartea (`desde` ≤ x < `hasta`).
`limite`	int	1–100, lehenetsia 25.
`cursor`	string	Aurreko orriaren `paginacion.siguiente` balioa.

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

Iteratu cursor = paginacion.siguiente erabiliz null izan arte, historia osoa jaso ahal izateko.

Eskaera bat lortu

GET /pedidos/{id}

Eskaera objektua itzultzen du. {id} aurrizkiarekin, adib. ped_ni. 404 no_encontrado zurea ez bada.

Eskaera baten historia

GET /pedidos/{id}/historial

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

Karta

GET /carta

Zuhaitz osoa: kategoriak → produktuak → tamainak → aukera-taldeak → aukerak. ?solo_disponibles=true aukerak ezkutuko/agortutakoa baztertzen du.

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

Banaketa-guneak

GET /zonas

Eremuak GeoJSON poligonoarekin (koordenatuak [lng, lat], eraztun itxia).

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

Jatetxea

GET /restaurante

Jatetxearen fitxa: kontaktua, kokapena, eguneko ordutegia, branding-a, kanal bakoitzeko hizkuntzak, ospea. Datu fiskal sentikorrik gabe.

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

Laburpena / metrikak

GET /resumen?periodo=30d

periodo ∈ hoyayer7d30dmes_actual. Jatetxearen ordu-eremuan kalkulatzen da; bertan behera utzitakoak/baztertutakoak kanpoan.

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

Zuzeneko stream-a (SSE)

GET /stream

Server-Sent Events. Gertaerak berehala bidaltzen ditu. Autentifikazioa query bidez (EventSource-k ez ditu goiburuak onartzen). Birkonexio natiboa 5 minuturo Last-Event-ID bidez; conexion.ping ~25 s-ro.

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

Aukerako iragazkia: ?eventos=pedido.nuevo,pedido.aceptado. Igortzen diren motak:

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

Irteerako webhook-ak

Pull-etik push-erako alternatiba: POST bat egiten dugu zure URL-ra eskaera bat aldatzen denean. Irteera soilik.

POST /webhooks

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 }

Gertaerak: streamekoak + pedido.* eta * komodinak. GET /webhooks zerrendatu · DEL /webhooks/{id} ezabatu.

Entrega eta sinadura

Bidalketa bakoitzak goiburu hauek ditu; gorputza streamekoa den objektu bera da:

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

Hutsegitean berriro saiatzen gara (X-Elp-Intento gehitzen doa). Deduplikatu X-Elp-Id bidez.

Eskaera objektua

/pedidos, /pedidos/{id}, streamak eta webhook-ek itzultzen duten egitura. Adibidean bezeroaren datuak anonimizatuta daude. direccion/mesa/entrega/fiscal null dira ezer aplikatzen ez denean.

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

Adibidea: sukaldeko telebista pantaila

HTML+JS autonomoa (irakurketa soilik): itsatsi zure token-a, ireki telebista batean eta eskaerak zuzenean sartuko dira streamaren bidez.

→ Ireki sukaldeko telebistaren adibidea