Desarrolladores · bknode

API REST

Integra TPVs, eCommerce y sistemas externos con bknode. API REST pura con JSON, autenticación estática por clave y soporte multi-centro.

URL base

Todas las peticiones en producción se dirigen a:

https://api.bknode.com/api/v1

Las respuestas siempre son application/json. En caso de error, el motor devolverá un código HTTP adecuado (400, 401, 409, 500) junto con la propiedad { "error": "descripción..." }.

Autenticación

La API está diseñada para la comunicación máquina a máquina. Usa la cabecera personalizada X-Api-Key. Puedes generar y revocar estas claves en el ERP, desde la sección de configuración de cada Centro/TPV.

curl https://api.bknode.com/api/v1/ping/authenticated \
  -H "X-Api-Key: tpv_xxxx_xxxxxxxxxxxxxxxxxxxxxxxx"

Las claves inyectan automáticamente en la API tu TenantId y CenterId por seguridad, asegurando que un TPV no pueda emitir facturas en nombre de otro centro.

Endpoints de Facturación (TPV)

GET/ping/authenticatedVerificar conectividad y validez de la API Key

POST/facturasEmitir ticket (Factura Simplificada F2) desde TPV

Próximamente...

GET/itemsSincronizar catálogo de artículos y precios

GET/clientesSincronizar cartera de clientes

Ejemplo: Emitir un Ticket (TPV)

Este endpoint crea una Factura Simplificada (F2) asignada automáticamente al centro del TPV y al cliente genérico. Si no especificas el taxId en una línea, el motor heredará el IVA por defecto configurado en la ficha del artículo.

curl -X POST https://api.bknode.com/api/v1/facturas \
  -H "X-Api-Key: tpv_suc1_abcdef1234567890" \
  -H "Content-Type: application/json" \
  -d '{
  "issueDate": "2026-05-28T17:30:00Z",
  "tpvReference": "TICKET-2026-001",
  "notes": "Mesa 5, camarero Juan",
  "lines": [
    {
      "itemId": "16d20697-55c2-4fc6-b343-3d5c4def08d0",
      "quantity": 2,
      "unitPrice": 12.50,
      "discountPercentage": 0
    }
  ]
}'

Respuesta 200 OK (El asiento contable y la actualización de stock se procesan automáticamente):

{
  "invoiceId": "9f26917a-1a19-4d79-a450-a90474f70408",
  "series": "TPV",
  "invoiceNumber": "00001",
  "documentNumber": "TPV-00001",
  "issueDate": "2026-05-28T00:00:00",
  "totalNet": 25.00,
  "totalTaxes": 5.25,
  "totalAmount": 30.25,
  "verifactuStatus": "PENDING",
  "warnings": []
}

Límites de uso y Buenas Prácticas

No existe un Rate Limit agresivo configurado actualmente, pero se recomienda evitar llamadas en bucle. Para el despliegue de catálogos y clientes futuros, utiliza la paginación y la sincronización basada en la última fecha de modificación (updated_at).