API Machine-to-Machine (M2M)
Bienvenido a la API Machine-to-Machine (M2M) oficial de Proyexa. Esta suite de integración ha sido diseñada meticulosamente bajo los más altos estándares de seguridad y escalabilidad para habilitar la comunicación programática directa entre instituciones financieras, pasarelas de pago o sistemas de terceros y el núcleo del ecosistema ERP de Proyexa.
A través de esta API, los integradores autorizados pueden consultar información financiera en tiempo real, validar saldos pendientes, aplicar pagos de manera automatizada y afectar la contabilidad de la empresa destino sin fricciones. Toda transacción realizada por esta vía genera trazas de auditoría completas, asegurando una conciliación bancaria transparente y en tiempo real.
Todas las peticiones M2M deben realizarse directamente desde el backend de tu integración apuntando al subdominio específico de tu cliente en Proyexa (ej. https://{tenant}.proyexa.app).
Estructura y Modelos de Datos
Nuestra API REST sigue esquemas predecibles e inmutables (JSON). Conoce la estructura de las entidades principales para mapear con precisión las respuestas hacia tu sistema de gestión o pasarela bancaria.
| Entidad | Propósito y Alcance |
|---|---|
Invoice | Datos fiscales de facturación, desglose de impuestos, saldo y estado del documento. |
Customer | Identificación comercial, nombre o razón social y RTN / DNI del cliente. |
Currency | Monedas configuradas en el tenant, código ISO y tasas de cambio oficiales. |
InvoiceItem | Artículos o servicios desglosados en el detalle de la factura. |
Receipt | Comprobante oficial de abono contable generado tras procesar un pago. |
SubscriberDetails | Estado de cuenta, cobertura en red, deuda y opciones de cobro precalculadas para telecomunicaciones (ISP). |
Invoice (Factura)
| Propiedad | Tipo | Descripción |
|---|---|---|
id | string (ULID) | Identificador único del registro en base de datos. |
number | string | Número fiscal oficial (CAI) o correlativo de la factura. |
payment_code | string | null | Código de pago rápido para ventanilla bancaria. |
date | string (datetime) | Fecha de emisión de la factura (ISO 8601). |
due_date | string (date) | null | Fecha de vencimiento para pago. |
subtotal | string (decimal) | Monto antes de impuestos y descuentos (2 decimales). |
discount | string (decimal) | Monto total de descuentos concedidos (2 decimales). |
tax_amount | string (decimal) | Monto total de impuestos cargados (2 decimales). |
total | string (decimal) | Monto total original del documento (2 decimales). |
balance | string (decimal) | Saldo pendiente actual después de abonos previos (2 decimales). |
status | string | Estado: active, partially_paid, paid. |
customer | object (Customer) | Información básica del cliente titular. |
currency | object (Currency) | Moneda aplicada (código, símbolo y tasa de cambio). |
items | array (InvoiceItem) | null | Líneas de detalle de la factura (disponible en la vista de detalle). |
Customer (Cliente)
| Propiedad | Tipo | Descripción |
|---|---|---|
name | string | null | Razón social o nombre completo del cliente. |
rtn | string | null | Registro Tributario Nacional (RTN / DNI / NIT) del cliente. |
Currency (Moneda)
| Propiedad | Tipo | Descripción |
|---|---|---|
id | string (ULID) | ID interno de la moneda en el tenant. |
code | string | Código ISO de la moneda (ej. HNL, USD). |
name | string | Nombre descriptivo (ej. Lempiras, Dólares). |
symbol | string | Símbolo comercial (ej. L, $). |
purchase_rate | string (decimal) | Tasa de compra oficial registrada en el ERP (4 decimales). |
sale_rate | string (decimal) | Tasa de venta oficial registrada en el ERP (4 decimales). |
is_default | boolean | Indica si es la moneda principal del tenant. |
SubscriberDetails (Suscriptor Telecom ISP)
| Propiedad | Tipo | Descripción |
|---|---|---|
subscription_id | string (ULID) | Identificador único de la suscripción de internet. |
subscriber_code | string | Código de abonado en ventanilla (ej. SUB-2003). |
customer_name | string | Nombre completo o razón social del titular del contrato. |
rtn | string | null | Número de identidad o RTN tributario. |
plan_name | string | Nombre comercial del plan contratado (ej. Plan Fibra 100 Mbps). |
monthly_amount | number | Tarifa mensual exacta del servicio contratado. |
paid_until | string | null (date) | Fecha hasta la cual el servicio se encuentra pagado (YYYY-MM-DD). |
extension_until | string | null (date) | Fecha de prórroga activa o promesa de pago si aplica. |
is_solvent | boolean | true si está al día o con prórroga; false si presenta mora vencida. |
status | string | Estado: active, suspended, cancelled. |
billing_day | integer | Día del mes en que se efectúa el corte y renovación (1 al 28). |
months_overdue | integer | Cantidad de mensualidades acumuladas en mora (0 si está al día). |
amount_overdue | number | Monto total de deuda acumulada (months_overdue * monthly_amount). |
allow_partial_payments | boolean | Configuración de la credencial M2M: si permite abonos libres o cuotas exactas. |
payment_options | array[PaymentOption] | Opciones precalculadas de pago sugeridas para el canal bancario. |
Entornos Disponibles
Ofrecemos dos ambientes completamente independientes para garantizar que tus ciclos de prueba se desarrollen de manera segura antes de procesar transacciones fiscales en producción.
| Entorno | URL Base |
|---|---|
Sandbox (Pruebas) Datos ficticios, ideal para desarrollo y homologación. | https://sandbox.proyexa.app |
Producción Transacciones fiscales, conciliación contable y red real. | https://{tenant-del-cliente}.proyexa.app |
Para proteger la estabilidad del ecosistema ERP, la API M2M procesa un máximo de 60 peticiones por minuto por IP. Si superas este límite, recibirás un error HTTP 429 Too Many Requests. Asegúrate de cachear tu token de acceso y de no realizar llamadas en bucles descontrolados.
Autenticación OAuth 2.0
La API M2M de Proyexa utiliza el protocolo estándar OAuth 2.0 (Client Credentials Grant). Antes de realizar cualquier consulta financiera o registrar pagos, tu integración debe intercambiar sus credenciales por un Bearer Token temporal firmado criptográficamente.
Los tokens de acceso tienen una vigencia de 60 minutos. Solicitar un token nuevo antes de cada llamada es una mala práctica que agotará tus límites de petición. Almacena el token en la memoria de tu servidor y renuévalo únicamente cuando recibas un error 401 Unauthorized.
Parámetros del Cuerpo (JSON)
Valor fijo obligatorio: client_credentials.
Identificador público de la credencial M2M provista en el portal de Proyexa.
Llave secreta asociada a la credencial. Debe mantenerse protegida en tus variables de entorno.
curl -X POST https://{tenant}.proyexa.app/oauth/token \
-H "Content-Type: application/json" \
-d '{
"grant_type": "client_credentials",
"client_id": "99b0c034-7a2e-4cb8-9f12-019348a2bc41",
"client_secret": "kYxP9z2w1v0uT8s7r6q5p4o3n2m1lK"
}'$response = Http::post('https://{tenant}.proyexa.app/oauth/token', [
'grant_type' => 'client_credentials',
'client_id' => '99b0c034-7a2e-4cb8-9f12-019348a2bc41',
'client_secret' => 'kYxP9z2w1v0uT8s7r6q5p4o3n2m1lK',
]);
$token = $response->json('access_token');HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://{tenant}.proyexa.app/oauth/token"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString("""
{
"grant_type": "client_credentials",
"client_id": "99b0c034-7a2e-4cb8-9f12-019348a2bc41",
"client_secret": "kYxP9z2w1v0uT8s7r6q5p4o3n2m1lK"
}
"""))
.build();var client = new HttpClient();
var payload = new {
grant_type = "client_credentials",
client_id = "99b0c034-7a2e-4cb8-9f12-019348a2bc41",
client_secret = "kYxP9z2w1v0uT8s7r6q5p4o3n2m1lK"
};
var content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://{tenant}.proyexa.app/oauth/token", content);{
"token_type": "Bearer",
"expires_in": 3600,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."
}{
"error": "invalid_client",
"error_description": "Client authentication failed"
}Manejo de Errores Globales
Todas las respuestas de fallo en la API M2M siguen una estructura JSON consistente. Puedes configurar un interceptor centralizado en tu cliente HTTP para capturar y deserializar los mensajes sin requerir lógica condicional aislada.
Esquema Estándar de Error
| Campo | Tipo | Descripción |
|---|---|---|
status | string | Siempre devuelve el literal "error". |
message | string | Explicación clara del motivo de rechazo en lenguaje legible. |
errors | object | null | En errores 422, mapea las validaciones por campo específico. |
{
"status": "error",
"message": "No autenticado. Token inválido o ausente.",
"data": null,
"pagination": null,
"errors": null
}{
"status": "error",
"message": "El cliente M2M no tiene el permiso requerido: view_currencies.",
"data": null,
"pagination": null,
"errors": null
}{
"status": "error",
"message": "El recurso solicitado no existe.",
"data": null,
"pagination": null,
"errors": null
}