Integrá tu POS con
Dos contratos de API y una guía paso a paso. Tu POS recibe órdenes vía webhook firmado con HMAC, las confirma por REST y avanza el estado hasta la entrega.
Contratos API
Lenguajes soportados
Bits HMAC-SHA
Tres recursos, una integración
La integración con BipBip se compone de dos contratos de API complementarios y una guía paso a paso para unirlos.
Webhook Spec
BipBip envía cada orden nueva a tu POS vía POST /v1/order/{remoteId}. Verificá la firma HMAC y respondé 200 OK.
REST API Reference
Tu POS llama a BipBip para aceptar, rechazar, avanzar el estado y consultar órdenes. Autenticá con X-Bipbip-Api-Key y mandá un Idempotency-Key en cada mutación.
Guía de integración
Quickstart paso a paso con código real en 4 lenguajes, verificación HMAC con samples probados, troubleshooting y glosario completo de términos del contrato.
Leer la guía →Diseñado para integraciones confiables
Firma HMAC-SHA256
Cada webhook se firma con HMAC-SHA256 sobre {timestamp}.{rawBody}. Rechazá requests mayores a 5 minutos para bloquear replays.
Entrega at-least-once
Cada intento lleva el mismo X-Bipbip-Delivery-Id. Deduplica con ese UUID y tolerá reintentos sin crear órdenes duplicadas.
Idempotency-Key obligatoria
Mandá un UUID único por intento lógico en cada mutación REST. 24h de caché, reintentos seguros sin efectos dobles.
Samples en 4 lenguajes
Node.js, Python, C# y PHP. Todos usan solo librería estándar — sin dependencias externas. Copy-paste y andá.
Máquina de estados clara
Pending → Accepted → Preparing → Ready → HandedOver. Rejected y Cancelled son terminales. Sin ambigüedades.
Versionado en el path
Todo corre bajo /v1/. Cuando llegue v2 podrás correrlas en paralelo mientras migrás — sin breaking changes sorpresivos.
Verificá cada webhook con HMAC
BipBip firma cada request con HMAC-SHA256 sobre {timestamp}.{rawBody}. Capturá los bytes crudos, validá el timestamp (máx. 300s de skew) y compará en tiempo constante.
- Solo librería estándar — sin dependencias externas
-
timingSafeEqual/compare_digest/hash_equals - Capturá el raw body antes de
JSON.parse
// HMAC-SHA256 verification — Node.js (built-in crypto) const crypto = require('crypto'); function verifyBipBipSignature(secret, timestamp, rawBody, signature) { // Reject requests older than 5 minutes (replay protection) const now = Math.floor(Date.now() / 1000); if (Math.abs(now - parseInt(timestamp, 10)) > 300) return false; // Sign the RAW body — never JSON.parse + re-serialize const message = `${timestamp}.${rawBody}`; const computed = crypto .createHmac('sha256', secret) .update(message, 'utf8') .digest('hex'); const expected = `sha256=${computed}`; // Timing-safe comparison (never use === on signatures) const a = Buffer.from(expected, 'utf8'); const b = Buffer.from(signature, 'utf8'); if (a.length !== b.length) return false; return crypto.timingSafeEqual(a, b); }
# HMAC-SHA256 verification — Python (stdlib only) import hmac, hashlib, time def verify_bipbip_signature(secret: str, timestamp: str, raw_body: bytes, signature: str) -> bool: # Reject requests older than 5 minutes if abs(int(time.time()) - int(timestamp)) > 300: return False # Build the exact message BipBip signed: "{ts}.{rawBody}" message = f"{timestamp}.".encode("utf-8") + raw_body computed = hmac.new(secret.encode("utf-8"), message, hashlib.sha256).hexdigest() expected = f"sha256={computed}" # Timing-safe comparison return hmac.compare_digest(expected, signature)
// HMAC-SHA256 verification — C# (.NET 6+) using System.Security.Cryptography; using System.Text; public static bool VerifyBipBipSignature(string secret, string timestamp, byte[] rawBody, string signature) { // Reject requests older than 5 minutes var now = DateTimeOffset.UtcNow.ToUnixTimeSeconds(); if (Math.Abs(now - long.Parse(timestamp)) > 300) return false; var prefix = Encoding.UTF8.GetBytes($"{timestamp}."); var message = prefix.Concat(rawBody).ToArray(); using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret)); var computed = Convert.ToHexString(hmac.ComputeHash(message)).ToLowerInvariant(); var expected = Encoding.UTF8.GetBytes($"sha256={computed}"); var received = Encoding.UTF8.GetBytes(signature); return CryptographicOperations.FixedTimeEquals(expected, received); }
// HMAC-SHA256 verification — PHP 7.2+ function verify_bipbip_signature(string $secret, string $timestamp, string $rawBody, string $signature): bool { // Reject requests older than 5 minutes if (abs(time() - (int)$timestamp) > 300) return false; // Sign the raw body — never re-serialize the parsed JSON $message = $timestamp . '.' . $rawBody; $computed = hash_hmac('sha256', $message, $secret); $expected = 'sha256=' . $computed; // Constant-time comparison to avoid timing oracles return hash_equals($expected, $signature); }
Los 4 pasos para estar en vivo
De "tengo mis credenciales" a "recibí y confirmé mi primera orden" sin intervención del equipo BipBip.
Implementá el webhook
Exponé POST /v1/order/{remoteId} en tu POS. Capturá el raw body antes de parsear el JSON.
Verificá la firma HMAC
Recomputá HMAC-SHA256 sobre {timestamp}.{rawBody} y comparalo en tiempo constante.
Respondé con remoteOrderId
Devolvé HTTP 200 con { "remoteOrderId": "..." }. Sin ese campo BipBip reintenta.
Aceptá por REST API
Llamá POST /api/v1/Orders/{orderKey}/accept con X-Bipbip-Api-Key e Idempotency-Key.
Antes de arrancar
BipBip te entrega estos elementos durante el onboarding
- HMAC Secret (una por cuenta)
- API Key (
X-Bipbip-Api-Key) - remoteId (uno por tienda)
- Base URL registrada (pública)
¿Listo para integrar tu POS con BipBip?
Coordiná con el equipo para recibir tus credenciales y arrancá el piloto en producción.