Facturación electrónica SUNAT desde Laravel

Del registro a tu primera prueba

1. Crea tu cuenta y registra el RUC de tu empresa.
2. Abre Configuración asistida: sube tu certificado .p12/.pfx, comprueba la clave y configura el usuario secundario SOL.
3. Mantén el ambiente beta. Genera una llave ff_test_…. Puedes volver a verla y copiarla en Configuración, en API key del ambiente actual.
4. Emite la factura de prueba. Un HTTP 202 indica que el documento quedó en cola.
5. Consulta GET /api/sunat/{ruc}/transactions/{id} hasta obtener el resultado de SUNAT y descarga el XML y CDR.

Para producción completa una prueba aceptada, activa el ambiente y genera una llave ff_live_…. La llave beta no puede emitir en producción.

Integra desde el backend de Laravel

Configura la URL del shard y la API key en .env y léelas desde config/services.php. Puedes usar el cliente HTTP de Laravel; el ejemplo PHP de abajo también funciona con cURL. No publiques la llave en Blade ni JavaScript del navegador.

Guarda la Idempotency-Key junto a la venta para conservarla en un reintento. Tras recibir 202, consulta la transacción desde un job o proceso de seguimiento; no marques la venta como aceptada sin verificar su estado final.

Un request, cinco lenguajes

Reemplaza TU_SHARD, TU_RUC, la llave, la fecha y el correlativo. El shard asignado aparece al seleccionar la empresa. Usa la fecha actual de Perú.

<?php
$payload = json_decode('{
  "tipo_doc": "01",
  "tipo_operacion": "0101",
  "serie": "FT01",
  "correlativo": "1",
  "fecha_emision": "2026-11-12",
  "tipo_moneda": "PEN",
  "client": {
    "tipo_doc": "6",
    "num_doc": "20123456789",
    "rzn_social": "CLIENTE DE PRUEBA"
  },
  "mto_oper_gravadas": 100,
  "mto_igv": 18,
  "total_impuestos": 18,
  "valor_venta": 100,
  "sub_total": 118,
  "mto_imp_venta": 118,
  "items": [
    {
      "cod_producto": "TEST",
      "descripcion": "Servicio de prueba beta",
      "unidad": "ZZ",
      "cantidad": 1,
      "valor_unitario": 100,
      "precio_unitario": 118,
      "valor_venta": 100,
      "base_igv": 100,
      "igv": 18,
      "total_impuestos": 18,
      "tipo_afe_igv": "10",
      "porcentaje_igv": 18
    }
  ]
}', true);
$ch = curl_init("https://TU_SHARD/api/sunat/TU_RUC/generate-invoice");
curl_setopt_array($ch, [
  CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POSTFIELDS => json_encode($payload),
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', "Authorization: Bearer TU_API_KEY", "Idempotency-Key: GUARDA_UN_UUID_POR_OPERACION"]
]);
echo curl_exec($ch);
curl_close($ch);

Guarda la llave en una variable de entorno de tu servidor. Evita incluirla en el código del navegador o en repositorios.

En Laravel puedes usar el cliente HTTP del framework con Http::withToken(config('services.factuflash.key')). Configura la URL y llave en .env; conserva la Idempotency-Key en tu registro de venta.

Reintentos e idempotencia

Genera un UUID por operación y envíalo en Idempotency-Key. Guarda ese UUID junto a la venta. Si hay un timeout, reintenta con la misma llave y el mismo JSON. Cambiar la llave representa otra operación.

HTTP 409 indica que la llave corresponde a otro contenido o que la operación original sigue en curso. Consulta el estado antes de emitir otro número. La respuesta repetida incluye Idempotency-Replayed: true.

Referencia de la API

La especificación completa es pública. El envío interactivo está deshabilitado en esta vista para que puedas explorar sin emitir.

Conectar un agente por MCP

Conecta FactuFlash con Claude o ChatGPT desde tu cuenta, y comprueba las conexiones autorizadas en un solo lugar.

El servicio MCP remoto usa OAuth con PKCE. Agrega la URL MCP configurada por tu administrador, selecciona las empresas y elige si permites acciones. Cada empresa usa su ambiente actual. En producción, las acciones preparan una vista previa y requieren una segunda llamada de confirmación.

El conector necesita un despliegue independiente. Consulta su disponibilidad antes de configurarlo en Claude, ChatGPT o Codex.