Desarrolladores · API Conecta

Cómo funciona

La API Conecta es REST con JSON. Cada empresa crea sus llaves en Conecta (API) dentro de la aplicación, y cada llave tiene solo los permisos que le des. Todas las respuestas usan valores en pesos colombianos (números con hasta 2 decimales).

Base: https://baronapos-baronaenterprise.azurewebsites.net/api/v1
Autenticación: encabezado Authorization: Bearer bc_live_…
Especificación OpenAPI: /api/v1/openapi.json
Límite: 240 solicitudes por minuto por llave.

Permisos de las llaves

Permiso	Qué permite
`lectura`	Consultar empresa, terceros, productos, facturas y reportes
`terceros`	Crear terceros (también al facturar a un cliente nuevo)
`productos`	Crear productos y servicios
`facturacion`	Emitir facturas, notas crédito y recibos de caja
`compras`	Registrar compras y gastos
`contabilidad`	Registrar comprobantes contables (notas de contabilidad)

Emitir una factura

El cliente se puede enviar por su id, por su documento (si no existe y la llave tiene permiso terceros, se crea) o como {"consumidorFinal": true}. La factura queda contabilizada al instante.

POST /api/v1/facturas
Authorization: Bearer bc_live_xxxxxxxx
Idempotency-Key: pedido-10482
Content-Type: application/json

{
  "cliente": { "tipoId": "13", "numero": "1070123456", "tipoPersona": "2",
               "nombres": "Laura", "apellidos": "Rojas", "email": "laura@correo.co" },
  "lineas": [
    { "codigo": "CAM-01", "descripcion": "Camisa guayabera", "cantidad": 2, "precio": 89900, "iva": "19" }
  ],
  "formaPago": "1",
  "medioPago": "47",
  "referencia": "pedido-10482"
}

Respuesta 201 con la factura completa: número, totales, retenciones y estado ante la DIAN. Valores de iva: 19, 5, E (exento) o X (excluido). Medios de pago: 10 efectivo, 47 transferencia, 48 tarjeta crédito, 49 tarjeta débito, 42 consignación.

Nunca dupliques una venta

Idempotency-Key: si repites la misma petición POST con la misma llave de idempotencia (24 horas), recibes la misma respuesta y el encabezado Idempotent-Replayed: true.
referencia: si envías el número de pedido de tu sistema, una segunda factura con la misma referencia devuelve la existente con "duplicada": true.

Otros recursos

Método y ruta	Permiso	Uso
`GET /api/v1/empresa`	lectura	Datos de la empresa
`GET /api/v1/terceros?numero=`	lectura	Buscar terceros
`POST /api/v1/terceros`	terceros	Crear tercero
`GET\|POST /api/v1/productos`	lectura / productos	Catálogo
`GET /api/v1/facturas?desde=&hasta=&referencia=`	lectura	Listar facturas
`GET /api/v1/facturas/{id}`	lectura	Detalle, CUFE y estado DIAN
`POST /api/v1/notas-credito`	facturacion	Nota crédito sobre una factura
`POST /api/v1/recibos`	facturacion	Registrar pagos de clientes
`POST /api/v1/compras`	compras	Registrar compras y gastos
`POST /api/v1/asientos`	contabilidad	Nota de contabilidad
`GET /api/v1/reportes/balance-prueba`	lectura	Balance de prueba
`GET /api/v1/reportes/resultados?desde=&hasta=`	lectura	Estado de resultados

Webhooks

Recibe avisos en tu servidor (solo HTTPS público) cuando ocurre algo: factura.creada, factura.dian (cambio de estado ante la DIAN), nota_credito.creada, nota_debito.creada, recibo.creado, compra.creada, tercero.creado y comprobante.creado. Si tu servidor no responde 2xx, reintentamos a los 10 segundos, 1 minuto y 10 minutos.

Cada aviso trae el encabezado X-BC-Signature: t=<unix>,v1=<hex>, donde v1 = HMAC-SHA256(secreto, t + "." + cuerpo). Verifícalo así (Node.js):

const crypto = require('crypto');
function verificar(secreto, firma, cuerpo) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(firma || '');
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;
  const esperado = crypto.createHmac('sha256', secreto).update(m[1] + '.' + cuerpo).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(m[2]));
}

Errores

Código	Significado
401	Llave inválida o revocada
402	La suscripción de la empresa no está activa
403	La llave no tiene el permiso necesario
422	Datos inválidos (el campo `error` explica qué corregir)
429	Superaste el límite de solicitudes

¿Necesitas ayuda para conectar tu sistema? Escríbenos a info@baronaenterprise.com.