Autenticación

Dos claves, dos usos

Cada dispositivo tiene dos credenciales en el dashboard (Configuración → Comercio → Dispositivos). Nunca las mezcle:

Clave	Formato	Se usa en
API Key	UUID4 (p. ej. a1b2c3d4-0000-4000-8000-000000000000)	Header X-Device-Id de todas las peticiones REST.
Secret Key	Hexadecimal	Solo para verificar HMAC de webhooks entrantes. Nunca se envía en peticiones.

Cabecera obligatoria

Cada petición a pos.b4bit.com/api/v1/* debe incluir:

X-Device-Id: <tu-api-key>

cURL

curl -H "X-Device-Id: $B4BIT_API_KEY" \
https://pos.b4bit.com/api/v1/currencies

Node (undici)

import { fetch } from 'undici';

const res = await fetch('https://pos.b4bit.com/api/v1/currencies', {
headers: { 'X-Device-Id': process.env.B4BIT_API_KEY },
});

Python

import os, requests

res = requests.get(
  'https://pos.b4bit.com/api/v1/currencies',
  headers={'X-Device-Id': os.environ['B4BIT_API_KEY']},
)

PHP

$ch = curl_init('https://pos.b4bit.com/api/v1/currencies');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-Device-Id: ' . getenv('B4BIT_API_KEY')]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$res = curl_exec($ch);

Precaución

Nota sobre Swagger: el Swagger original de B4bit Pay declara securityDefinitions.Basic, pero el backend no usa Basic Auth. La autenticación real es con el header X-Device-Id. El OpenAPI 3 que publicamos ya corrige este desajuste.

Dónde se configura el webhook

La URL del webhook (donde B4bit Pay le enviará las notificaciones de cambio de estado) se configura en el campo notification_url del dispositivo, no se gestiona por API. La firma se verifica con la Secret Key hexadecimal — ver webhook.

Seguridad

Peligro

• No commitee la API Key ni la Secret Key a git.
• No las exponga en el frontend (todas las peticiones deben ir por su backend).
• No las loggee.
• Rótelas si sospecha exposición (contacte a support@b4bit.com).

Errores de autenticación

• HTTP 403 — Falta X-Device-Id o es inválida.
• HTTP 500 — Error interno del servidor. Reintente con backoff exponencial.

Ver errores para la lista completa.