# Firux Partner API

> API REST para crear cobros Bre-B en Colombia y recibir su confirmación por webhook firmado. URL base: https://api.firux.co/v1. Montos en pesos colombianos enteros.

Firux Pay es una plataforma de cobros Bre-B para negocios en Colombia. La API crea y consulta cobros; no permite retiros: los retiros se autorizan solo desde el panel web de la cuenta.

## Lo esencial

- Autenticación: header `Authorization: Bearer firux_live_...` en producción o `firux_test_...` en pruebas. La llave se genera en el panel (Ajustes, Conexiones API) y se muestra una sola vez.
- Crear un cobro: `POST /v1/charges` con el header `Idempotency-Key` y el cuerpo `{"amount": 50000, "external_reference": "FACT-123", "description": "Pedido 123"}`. Responde 201 con `id`, `status`, `payment_url` y `qr_emv`.
- Consultar: `GET /v1/charges/{id}` o `GET /v1/charges?external_reference=FACT-123`.
- Estados del cobro: `PENDING`, `PAID`, `EXPIRED` y `FAILED`. Vence en 24 horas por defecto; `expires_at` (UTC) lo cambia.
- Quién pagó: con el cobro en `PAID`, y también en `charge.paid`, llegan `payer_name`, `payer_bank`, `payer_document` (enmascarado, nunca completo) y `receipt_url` (el comprobante de Firux de ese pago).
- Montos: desde $2.000 hasta $12.000.000 por cobro.
- Webhooks: evento `charge.paid` (y `payment.notified` con el Verificador de Pagos). Headers `Firux-Event-Id`, `Firux-Event-Type`, `Firux-Timestamp` y `Firux-Signature` (`v1=<hex>`).
- Firma: HMAC-SHA256 de `{timestamp}.{cuerpo crudo}` con el secreto `whsec_...`, comparada en tiempo constante; rechaza timestamps de más de 300 segundos. Durante una rotación pueden venir dos firmas.
- Reintentos de los webhooks: a los 1, 5 y 30 minutos, y a las 2 y 6 horas. Usa `Firux-Event-Id` para no procesar dos veces el mismo evento.
- Errores: `{"error":{"type":"...","message":"..."}}`. 400 sin `Idempotency-Key`, 401 credenciales inválidas, 409 referencia pagada o en proceso, 422 validación, 503 Bre-B no disponible por un momento.
- Modo prueba: `POST /v1/charges/{id}/simulate_payment` con credenciales de prueba dispara el webhook firmado sin mover dinero.

## Documentación

- [Documentación completa](https://developers.firux.co/): autenticación, cobros, idempotencia, webhooks, firma (con ejemplos en Node.js y PHP), errores y modo prueba.
- [OpenAPI](https://developers.firux.co/openapi.yaml): la especificación completa, con el ejemplo de la firma en Python.
- [Estado del servicio](https://developers.firux.co/estado) y [en JSON](https://developers.firux.co/estado.json).
- [Términos de uso de la API](https://firux.co/empresas/legal/api).

## Opcional

- [Firux para empresas](https://firux.co/empresas/): Cobros, Dispersiones, industrias y precios.
- [Precios](https://firux.co/empresas/precios).
- Soporte: soporte@firux.co