Estás viendo placeholders genéricos

Inicia sesión para ver ejemplos con tu nombre, client_id y API key real.

API REST de Bre-Check

Versión actual: v1 · Base URL: https://bre-check.com/api/v1

Esta API te permite integrar tus propios sistemas (POS, ERP, app móvil, dashboard custom) con Bre-Check. Puedes consultar verificaciones, cajeros y sucursales, y recibir webhooks en tiempo real cuando ocurren eventos importantes.

Introducción

La API sigue convenciones REST estándar. Todas las peticiones se hacen sobre HTTPS y todas las respuestas son JSON con encoding UTF-8.

Versionado: el path empieza con /api/v1/. Cuando lancemos v2, v1 seguirá funcionando por al menos 12 meses.
Compatibilidad: nunca rompemos contratos existentes en una misma versión. Solo agregamos campos opcionales y nuevos endpoints.
Idempotencia: los endpoints GET son idempotentes por definición. Los POST de escritura aceptan el header Idempotency-Key.
Paginación: usamos cursor-based pagination — más rápida y consistente que offset.

Autenticación

Todas las peticiones requieren autenticación vía API key en el header Authorization:

bash

curl https://bre-check.com/api/v1/ping \
  -H "Authorization: Bearer brk_live_AbCdEf1234567890..."

Cómo obtener tu API key:

Entra a tu panel de Bre-Check en Configuración → API & Webhooks
Click en "Crear API Key" y dale un nombre descriptivo
Elige entorno (live para producción, test para pruebas) y permisos (read o read:write)
Copia la key inmediatamente — por seguridad solo la mostramos una vez

Guarda tu key como un secreto. Nunca la pongas en código frontend, en repositorios públicos o en logs. Si se compromete, revócala desde el panel y crea una nueva.

Entornos

Bre-Check ofrece dos entornos completamente separados con keys diferentes:

Entorno	Prefijo	Uso
Producción	`brk_live_...`	Datos reales de tu cuenta. Las llamadas tienen efecto real.
Pruebas (sandbox)	`brk_test_...`	Datos de prueba aislados. No afecta verificaciones reales ni dispara sync a integraciones contables.

Rate limits

Cada API key tiene un límite por separado. Cuando excedes el límite, recibes 429 Too Many Requests con el header Retry-After indicando los segundos a esperar.

Endpoints GET: 300 req/min por key
Endpoints POST/PUT/DELETE: 60 req/min por key
Bursting: permitimos hasta 30 requests en ráfaga (1 segundo) antes de aplicar el throttle

Los headers de respuesta te dicen tu estado actual: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Códigos de error

Todos los errores tienen estructura consistente con código y mensaje legible:

json

{
  "error": {
    "code": "invalid_key",
    "message": "API key inválida o revocada"
  }
}

HTTP	Code	Significado
400	`invalid_param`	Parámetro inválido o faltante. El mensaje detalla cuál.
401	`unauthorized`	Header Authorization ausente o malformado
401	`invalid_key`	API key inválida, revocada o con formato incorrecto
401	`expired_key`	API key expirada
403	`insufficient_scope`	La key no tiene permisos para esta operación
403	`client_inactive`	La cuenta Bre-Check está cancelada o pausada
404	`not_found`	Recurso no existe o no pertenece a tu cuenta
429	`rate_limited`	Excediste el rate limit. Espera y reintenta.
500	`internal_error`	Error interno. Reintenta con exponential backoff.

GET /ping

Endpoint de health-check. Útil para validar conectividad y que tus credenciales sean correctas.

bash

curl https://bre-check.com/api/v1/ping \
  -H "Authorization: Bearer brk_live_AbCdEf1234567890..."

Respuesta 200:

json

{
  "ok": true,
  "environment": "live",
  "client": {
    "id": "clz4q3kj30000abc",
    "name": "Mi Empresa SAS"
  },
  "timestamp": "2026-05-26T12:34:56.789Z"
}

GET /verifications

Lista las verificaciones de tu cuenta, ordenadas por fecha descendente.

Query params

Param	Tipo	Descripción
`status`	string	Filtrar por estado: `verified`, `fake`, `used`, `pending`
`from`	ISO date	Solo verificaciones con `received_at >= from`
`to`	ISO date	Solo verificaciones con `received_at <= to`
`limit`	integer	1–200 (default 50)
`cursor`	string	Para paginar: pasa el `next_cursor` de la respuesta anterior

Ejemplo

bash

curl "https://bre-check.com/api/v1/verifications?status=verified&limit=10" \
  -H "Authorization: Bearer brk_live_AbCdEf1234567890..."

Respuesta 200

json

{
  "data": [
    {
      "id": "clz4q3kj30001abc",
      "short_id": "BC-A1B2C3",
      "status": "verified",
      "amount": 120000,
      "currency": "COP",
      "payer_name": "María González",
      "reference": "M22974167",
      "bank_reference": "BC2026051815483217",
      "bank_name": "Bancolombia",
      "cashier_name": "ABBY",
      "cashier_phone": "+573001112234",
      "branch_name": "Sucursal Central",
      "photo_url": "https://bre-check.com/uploads/...",
      "notes": null,
      "duration_ms": 12340,
      "received_at": "2026-05-26T20:35:42.000Z",
      "verified_at": "2026-05-26T20:35:54.000Z"
    }
  ],
  "pagination": {
    "next_cursor": "clz4q3kj30001abc",
    "has_more": true
  }
}

GET /verifications/:id

Devuelve el detalle completo de una verificación. Si no existe o no pertenece a tu cuenta, devuelve 404.

bash

curl https://bre-check.com/api/v1/verifications/clz4q3kj30001abc \
  -H "Authorization: Bearer brk_live_AbCdEf1234567890..."

GET /cashiers

Lista los cajeros (números autorizados de WhatsApp) de tu cuenta.

bash

curl https://bre-check.com/api/v1/cashiers \
  -H "Authorization: Bearer brk_live_AbCdEf1234567890..."

json

{
  "data": [
    {
      "id": "clz4q...",
      "name": "ABBY",
      "phone": "+573001112234",
      "role": "cashier",
      "active": true,
      "branch_id": "clz5...",
      "branch_name": "Sucursal Central",
      "created_at": "2026-04-12T10:00:00.000Z"
    }
  ]
}

GET /branches

Lista las sucursales activas de tu cuenta.

bash

curl https://bre-check.com/api/v1/branches \
  -H "Authorization: Bearer brk_live_AbCdEf1234567890..."

Webhooks

Los webhooks te permiten recibir notificaciones en tiempo real cuando ocurren eventos en tu cuenta Bre-Check — sin necesidad de hacer polling.

Configúralos en Configuración → API & Webhooks. Cada webhook tiene:

URL HTTPS: tu endpoint público que recibe el POST
Eventos suscritos: qué tipos de eventos quieres recibir
Secret: usado para firmar HMAC SHA-256 del payload (te lo damos al crear el webhook)

Bre-Check entrega los eventos con un timeout de 5 segundos. Si tu endpoint responde 2xx, consideramos el evento entregado. Si responde error o timeout, reintentamos hasta 5 veces con exponential backoff (1s, 5s, 30s, 2min, 10min).

Eventos disponibles

Evento	Cuándo se dispara
`verification.created`	Cuando se recibe un nuevo comprobante por WhatsApp
`verification.verified`	Cuando un comprobante se confirma como válido
`verification.fake`	Cuando un comprobante se detecta como falso o sin match bancario
`verification.used`	Cuando un comprobante ya había sido usado antes (duplicado)
`integration.sync_failed`	Cuando falla la sincronización con Siigo/Alegra/etc.

Estructura del payload

json

{
  "event": "verification.verified",
  "id": "evt_clz4...",
  "created_at": "2026-05-26T20:35:54.000Z",
  "data": {
    "id": "clz4q3kj30001abc",
    "short_id": "BC-A1B2C3",
    "status": "verified",
    "amount": 120000,
    "currency": "COP",
    "payer_name": "María González",
    "reference": "M22974167",
    "bank_name": "Bancolombia",
    "received_at": "2026-05-26T20:35:42.000Z",
    "verified_at": "2026-05-26T20:35:54.000Z"
  }
}

Verificar la firma HMAC

Cada webhook trae 2 headers que te permiten validar que viene realmente de Bre-Check:

X-Bre-Check-Signature: HMAC SHA-256 hex del raw body firmado con tu secret
X-Bre-Check-Timestamp: timestamp UNIX del momento del envío

Ejemplo de verificación en Node.js:

javascript

const crypto = require('crypto')

function verifySignature(rawBody, signature, timestamp, secret) {
  // Rechazar webhooks de más de 5 minutos (anti-replay)
  if (Date.now() / 1000 - Number(timestamp) > 300) return false

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex')

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  )
}

Ejemplos en distintos lenguajes

cURL

bash

curl https://bre-check.com/api/v1/verifications \
  -H "Authorization: Bearer brk_live_AbCdEf1234567890..."

JavaScript / Node

javascript

const response = await fetch('https://bre-check.com/api/v1/verifications?status=verified', {
  headers: { Authorization: `Bearer ${process.env.BRECHECK_API_KEY}` },
})
const { data, pagination } = await response.json()
console.log(data)

Python

python

import os, requests

resp = requests.get(
    "https://bre-check.com/api/v1/verifications",
    headers={"Authorization": f"Bearer {os.environ['BRECHECK_API_KEY']}"},
    params={"status": "verified", "limit": 50},
)
resp.raise_for_status()
print(resp.json())

PHP

php

<?php
$ch = curl_init("https://bre-check.com/api/v1/verifications");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Bearer " . getenv("BRECHECK_API_KEY"),
]);
$response = curl_exec($ch);
$data = json_decode($response, true);

Changelog

v1.0.0 · 2026-05-26 — Lanzamiento inicial de la API REST pública. Endpoints: ping, verifications (list/detail), cashiers, branches. Webhooks con firma HMAC SHA-256.

Soporte

¿Necesitas ayuda? Tenemos varios canales:

WhatsApp: +57 301 500 4577
Email: [email protected]
Status: GET /api/v1/ping para health-check tiempo real