API M2M v1.0.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.

Modelos

Los modelos dentro del API Rest brindan estructuras predefinidas (JSON) para facilitar la interacción con entidades de Proyexa, como ser facturación, clientes, impuestos, etc.

Es muy importante conocer todas las utilidades de estos modelos para poder explotar su potencial al máximo. Dentro de los modelos podemos encontrar:

• Invoice : datos de facturación e historial de cobros
• Customer : datos del cliente asociado a la factura
• Currency : datos de monedas y tipos de cambio
• InvoiceItem : todo tipo de artículos a la venta facturados
• Receipt : datos de recibos y comprobantes de pago

Todas las respuestas de error de la API (a excepción del endpoint de OAuth) devuelven una estructura de datos estandarizada. No es necesario adivinar el formato de error para cada petición individual; puedes programar tu interceptor de manera centralizada.

{
  "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
}

Proyexa utiliza el estándar OAuth 2.0 (Client Credentials Grant). Obtén un token temporal para firmar tus peticiones.

curl -X POST https://{tenant}.proyexa.app/oauth/token \
-H "Content-Type: application/json" \
-d '{
  "grant_type": "client_credentials",
  "client_id": "99b0c...",
  "client_secret": "kYxP9..."
}'

$response = Http::post('https://{t}.proyexa.app/oauth/token', [
    'grant_type' => 'client_credentials',
    'client_id' => '99b0c...',
    'client_secret' => 'kYxP9...'
]);

HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("https://{t}.proyexa.app/oauth/token"))
  .header("Content-Type", "application/json")
  .POST(BodyPublishers.ofString("{\"grant_type\":\"client_credentials\"...}"))
  .build();

var client = new HttpClient();
var content = new StringContent("{\"grant_type\":\"client_credentials\"...}", 
    Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://{t}.proyexa.app/oauth/token", content);

{
  "token_type": "Bearer",
  "expires_in": 31536000,
  "access_token": "eyJ0eXAiOiJKV1QiLC..."
}

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

Consulta las monedas configuradas en el tenant y su tasa de conversión oficial. Indispensable para procesar pagos en dólares u otras denominaciones soportadas.

curl -X GET https://{tenant}.proyexa.app/m2m/billing/currencies \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

$response = Http::withToken($token)->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": "019...",
      "code": "HNL",
      "name": "Lempiras",
      "symbol": "L",
      "purchase_rate": "1.0000",
      "sale_rate": "1.0000",
      "is_default": true
    },
    {
      "id": "019...",
      "code": "USD",
      "name": "Dólares",
      "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
}

Devuelve la lista paginada de todas las facturas pendientes de pago (estado active o partially_paid). Puedes buscar por ID de cliente o RTN.

curl -X GET "https://{tenant}.proyexa.app/m2m/billing/invoices?customer_id=01H9&per_page=15" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

$response = Http::withToken($token)->get('https://{tenant}.proyexa.app/m2m/billing/invoices', [
    'customer_id' => '01H9...',
    'per_page' => 15
]);

HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("https://{tenant}.proyexa.app/m2m/billing/invoices?customer_id=01H9&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?customer_id=01H9&per_page=15");

{
  "status": "success",
  "message": "Facturas pendientes obtenidas exitosamente.",
  "data": [
    {
      "id": "01J2X...",
      "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": "Empresa S.A.",
        "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
}

Aplica un abono monetario a la factura. Proyexa validará los alcances configurados en el ERP para determinar si tienes permitido registrar pagos parciales y generará el recibo contable automáticamente.

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-88",
  "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-88',
    '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(BodyPublishers.ofString("{\"amount\": 1500.00, \"reference_number\": \"TRX-88\", \"currency_code\": \"HNL\"}"))
  .build();

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
var content = new StringContent("{\"amount\": 1500.00, \"reference_number\": \"TRX-88\", \"currency_code\": \"HNL\"}", System.Text.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": "01J2Z...",
    "number": "REC-000001",
    "date": "2026-07-01T10:00:00.000000Z",
    "amount": "1500.00",
    "reference": "M2M-TRX-88",
    "notes": "M2M: Pago vía [Integración Banco] Transacción: TRX-88 (1500.00 HNL)",
    "status": "active",
    "invoice": {
      "id": "01J2X...",
      "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
}