Facturación & Cobranza
Endpoints diseñados para la gestión contable y financiera de documentos mercantiles. Permiten consultar las tasas de cambio de monedas registradas en el tenant, recuperar facturas pendientes de cobro con amortización al crédito, obtener el detalle desglosado de ítems tributarios y asentar pagos monetarios con emisión de recibos y conciliación automática.
Monedas y Tasas de Conversión
Consulta las monedas habilitadas en el tenant y sus tasas oficiales de conversión contable. Indispensable cuando tu pasarela opera en dólares u otras denominaciones internacionales y requieres calcular el equivalente exacto en moneda local.
curl -X GET https://{tenant}.proyexa.app/m2m/billing/currencies \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"$response = Http::withToken($token)
->acceptJson()
->get('https://{tenant}.proyexa.app/m2m/billing/currencies');HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://{tenant}.proyexa.app/m2m/billing/currencies"))
.header("Authorization", "Bearer " + token)
.header("Accept", "application/json")
.GET()
.build();var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
var response = await client.GetAsync("https://{tenant}.proyexa.app/m2m/billing/currencies");{
"status": "success",
"message": "Monedas obtenidas exitosamente.",
"data": [
{
"id": "01J2Z4M0N98B7Q4Q3",
"code": "HNL",
"name": "Lempiras",
"symbol": "L",
"purchase_rate": "1.0000",
"sale_rate": "1.0000",
"is_default": true
},
{
"id": "01J2Z4M1K87B5X2R1",
"code": "USD",
"name": "Dólares Americanos",
"symbol": "$",
"purchase_rate": "24.5000",
"sale_rate": "24.8000",
"is_default": false
}
],
"pagination": null,
"errors": null
}{
"status": "error",
"message": "No autenticado. Token inválido o ausente.",
"data": null,
"pagination": null,
"errors": null
}Listar Facturas Pendientes
Devuelve el catálogo paginado de todas las facturas al crédito con saldo pendiente de pago (estados active o partially_paid). Soporta filtros directos por cliente o número de RTN.
Parámetros de Consulta (Query Params)
Filtra facturas correspondientes a un cliente específico.
Búsqueda exacta por RTN o número de identidad del cliente.
Número de página solicitada para navegar el listado.
Cantidad máxima de facturas a retornar por página.
curl -X GET "https://{tenant}.proyexa.app/m2m/billing/invoices?rtn=0801199012345&per_page=15" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"$response = Http::withToken($token)->get('https://{tenant}.proyexa.app/m2m/billing/invoices', [
'rtn' => '0801199012345',
'per_page' => 15,
]);HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://{tenant}.proyexa.app/m2m/billing/invoices?rtn=0801199012345&per_page=15"))
.header("Authorization", "Bearer " + token)
.header("Accept", "application/json")
.GET()
.build();var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
var response = await client.GetAsync("https://{tenant}.proyexa.app/m2m/billing/invoices?rtn=0801199012345&per_page=15");{
"status": "success",
"message": "Facturas pendientes obtenidas exitosamente.",
"data": [
{
"id": "01J2X8K9M34Q7QE2VQWKCK72X6",
"number": "000-001-01-00000042",
"payment_code": "42",
"date": "2026-06-30T10:00:00.000000Z",
"due_date": "2026-07-30T06:00:00.000000Z",
"subtotal": "1304.35",
"discount": "0.00",
"tax_amount": "195.65",
"total": "1500.00",
"balance": "1500.00",
"status": "active",
"customer": {
"name": "Inversiones del Norte S. de R.L.",
"rtn": "0801199012345"
},
"currency": {
"code": "HNL",
"symbol": "L",
"exchange_rate": "1.0000"
}
}
],
"pagination": {
"current_page": 1,
"last_page": 1,
"per_page": 15,
"total": 1,
"has_more_pages": false
},
"errors": null
}{
"status": "error",
"message": "No autenticado. Token inválido o ausente.",
"data": null,
"pagination": null,
"errors": null
}Detalle de Factura
Obtiene la información exhaustiva de un documento específico, incluyendo el saldo al instante y el desglose de productos y servicios facturados en sus líneas de detalle (items).
Consulta siempre este endpoint inmediatamente antes de asentar un abono para verificar el saldo en tiempo real. Otro canal o ventanilla física pudo haber amortizado la factura segundos antes.
Parámetro de Ruta (Path Param)
Admite indistintamente: el identificador ULID interno, el número fiscal CAI (ej. 000-001-01-00000042) o el código de pago corto (payment_code).
curl -X GET "https://{tenant}.proyexa.app/m2m/billing/invoices/000-001-01-00000042" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"$response = Http::withToken($token)
->get('https://{tenant}.proyexa.app/m2m/billing/invoices/000-001-01-00000042');HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://{tenant}.proyexa.app/m2m/billing/invoices/000-001-01-00000042"))
.header("Authorization", "Bearer " + token)
.header("Accept", "application/json")
.GET()
.build();var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
var response = await client.GetAsync("https://{tenant}.proyexa.app/m2m/billing/invoices/000-001-01-00000042");{
"status": "success",
"message": "Detalle de factura obtenido exitosamente.",
"data": {
"id": "01J2X8K9M34Q7QE2VQWKCK72X6",
"number": "000-001-01-00000042",
"payment_code": "42",
"date": "2026-06-30T10:00:00.000000Z",
"due_date": "2026-07-30T06:00:00.000000Z",
"subtotal": "1304.35",
"discount": "0.00",
"tax_amount": "195.65",
"total": "1500.00",
"balance": "1500.00",
"status": "active",
"customer": {
"name": "Inversiones del Norte S. de R.L.",
"rtn": "0801199012345"
},
"currency": {
"code": "HNL",
"symbol": "L",
"exchange_rate": "1.0000"
},
"items": [
{
"description": "Servicio de Consultoría y Enlace Dedicado",
"quantity": 1.0,
"price": "1304.35",
"subtotal": "1304.35",
"discount_amount": "0.00",
"tax_rate": "15.00",
"tax_amount": "195.65",
"total": "1500.00"
}
]
},
"pagination": null,
"errors": null
}{
"status": "error",
"message": "Factura no encontrada.",
"data": null,
"pagination": null,
"errors": null
}{
"status": "error",
"message": "No autenticado. Token inválido o ausente.",
"data": null,
"pagination": null,
"errors": null
}Registrar Pago de Factura
Aplica un abono monetario contra una factura pendiente. Proyexa validará los alcances de la credencial M2M (si se autorizan o no pagos parciales), amortizará el balance y generará el recibo contable correspondiente de forma inmediata.
El campo reference_number actúa como clave de idempotencia única. Si ocurre un corte de red durante la comunicación y tu cliente reenvía la petición con la misma referencia bancaria, Proyexa detectará el pago previo y retornará 422 Unprocessable Entity para evitar duplicar cargos monetarios.
Parámetros del Cuerpo (JSON)
Monto exacto a abonar. Será rechazado si excede el saldo pendiente de la factura.
Código o número de comprobante único generado por el banco o pasarela de pagos.
Código de moneda (ej. HNL, USD). Si se omite, se asume la moneda base del tenant.
curl -X POST "https://{tenant}.proyexa.app/m2m/billing/invoices/000-001-01-00000042/payments" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"amount": 1500.00,
"reference_number": "TRX-BANCO-88229",
"currency_code": "HNL"
}'$response = Http::withToken($token)->post('https://{tenant}.proyexa.app/m2m/billing/invoices/000-001-01-00000042/payments', [
'amount' => 1500.00,
'reference_number' => 'TRX-BANCO-88229',
'currency_code' => 'HNL',
]);HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://{tenant}.proyexa.app/m2m/billing/invoices/000-001-01-00000042/payments"))
.header("Authorization", "Bearer " + token)
.header("Content-Type", "application/json")
.header("Accept", "application/json")
.POST(HttpRequest.BodyPublishers.ofString("""
{
"amount": 1500.00,
"reference_number": "TRX-BANCO-88229",
"currency_code": "HNL"
}
"""))
.build();var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
var payload = new {
amount = 1500.00,
reference_number = "TRX-BANCO-88229",
currency_code = "HNL"
};
var content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://{tenant}.proyexa.app/m2m/billing/invoices/000-001-01-00000042/payments", content);{
"status": "success",
"message": "Pago aplicado exitosamente.",
"data": {
"id": "01J2Z9K0L12N3P4Q5",
"number": "REC-000001",
"date": "2026-07-01T10:00:00.000000Z",
"amount": "1500.00",
"reference": "TRX-BANCO-88229",
"notes": "M2M: Pago vía [Canal Bancario] Transacción: TRX-BANCO-88229 (1500.00 HNL)",
"status": "active",
"invoice": {
"id": "01J2X8K9M34Q7QE2VQWKCK72X6",
"number": "000-001-01-00000042",
"balance": "0.00",
"status": "paid"
}
},
"pagination": null,
"errors": null
}{
"status": "error",
"message": "Esta credencial M2M no autoriza pagos parciales. El monto convertido debe ser exactamente el saldo pendiente (1500.00).",
"data": null,
"pagination": null,
"errors": null
}{
"status": "error",
"message": "Esta factura no está pendiente de pago (Estado actual: paid).",
"data": null,
"pagination": null,
"errors": null
}{
"status": "error",
"message": "No autenticado. Token inválido o ausente.",
"data": null,
"pagination": null,
"errors": null
}