ESC
Menú de Navegación

API Machine-to-Machine (M2M)

v1.0.0 EstableREST / JSON / OAuth 2.0

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.

Información Técnica de Enrutamiento

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.

EntidadPropósito y Alcance
InvoiceDatos fiscales de facturación, desglose de impuestos, saldo y estado del documento.
CustomerIdentificación comercial, nombre o razón social y RTN / DNI del cliente.
CurrencyMonedas configuradas en el tenant, código ISO y tasas de cambio oficiales.
InvoiceItemArtículos o servicios desglosados en el detalle de la factura.
ReceiptComprobante oficial de abono contable generado tras procesar un pago.
SubscriberDetailsEstado de cuenta, cobertura en red, deuda y opciones de cobro precalculadas para telecomunicaciones (ISP).

Invoice (Factura)

PropiedadTipoDescripción
idstring (ULID)Identificador único del registro en base de datos.
numberstringNúmero fiscal oficial (CAI) o correlativo de la factura.
payment_codestring | nullCódigo de pago rápido para ventanilla bancaria.
datestring (datetime)Fecha de emisión de la factura (ISO 8601).
due_datestring (date) | nullFecha de vencimiento para pago.
subtotalstring (decimal)Monto antes de impuestos y descuentos (2 decimales).
discountstring (decimal)Monto total de descuentos concedidos (2 decimales).
tax_amountstring (decimal)Monto total de impuestos cargados (2 decimales).
totalstring (decimal)Monto total original del documento (2 decimales).
balancestring (decimal)Saldo pendiente actual después de abonos previos (2 decimales).
statusstringEstado: active, partially_paid, paid.
customerobject (Customer)Información básica del cliente titular.
currencyobject (Currency)Moneda aplicada (código, símbolo y tasa de cambio).
itemsarray (InvoiceItem) | nullLíneas de detalle de la factura (disponible en la vista de detalle).

Customer (Cliente)

PropiedadTipoDescripción
namestring | nullRazón social o nombre completo del cliente.
rtnstring | nullRegistro Tributario Nacional (RTN / DNI / NIT) del cliente.

Currency (Moneda)

PropiedadTipoDescripción
idstring (ULID)ID interno de la moneda en el tenant.
codestringCódigo ISO de la moneda (ej. HNL, USD).
namestringNombre descriptivo (ej. Lempiras, Dólares).
symbolstringSímbolo comercial (ej. L, $).
purchase_ratestring (decimal)Tasa de compra oficial registrada en el ERP (4 decimales).
sale_ratestring (decimal)Tasa de venta oficial registrada en el ERP (4 decimales).
is_defaultbooleanIndica si es la moneda principal del tenant.

SubscriberDetails (Suscriptor Telecom ISP)

PropiedadTipoDescripción
subscription_idstring (ULID)Identificador único de la suscripción de internet.
subscriber_codestringCódigo de abonado en ventanilla (ej. SUB-2003).
customer_namestringNombre completo o razón social del titular del contrato.
rtnstring | nullNúmero de identidad o RTN tributario.
plan_namestringNombre comercial del plan contratado (ej. Plan Fibra 100 Mbps).
monthly_amountnumberTarifa mensual exacta del servicio contratado.
paid_untilstring | null (date)Fecha hasta la cual el servicio se encuentra pagado (YYYY-MM-DD).
extension_untilstring | null (date)Fecha de prórroga activa o promesa de pago si aplica.
is_solventbooleantrue si está al día o con prórroga; false si presenta mora vencida.
statusstringEstado: active, suspended, cancelled.
billing_dayintegerDía del mes en que se efectúa el corte y renovación (1 al 28).
months_overdueintegerCantidad de mensualidades acumuladas en mora (0 si está al día).
amount_overduenumberMonto total de deuda acumulada (months_overdue * monthly_amount).
allow_partial_paymentsbooleanConfiguración de la credencial M2M: si permite abonos libres o cuotas exactas.
payment_optionsarray[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.

EntornoURL 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
Límites de Petición (Rate Limiting)

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.

POST/oauth/token
Duración y Patrón de Integración Recomendado

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)

grant_typeRequeridostring

Valor fijo obligatorio: client_credentials.

client_idRequeridostring (UUID)

Identificador público de la credencial M2M provista en el portal de Proyexa.

client_secretRequeridostring

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

CampoTipoDescripción
statusstringSiempre devuelve el literal "error".
messagestringExplicación clara del motivo de rechazo en lenguaje legible.
errorsobject | nullEn 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
}