Antes de empezar

PHP 8.1 o superior

Y un proyecto Laravel 10 u 11.

Una API key de pruebas de Flashpi

Guárdala en una variable de entorno, nunca en el código ni en el repositorio.

Solicítala aquí

Tu certificado de firma .p12

Cargado en la cuenta de pruebas.

Cargar el certificado

Tus datos de emisor

RUC, establecimiento y punto de emisión configurados en tu cuenta.

Paso 1 · Configura las variables de entorno

bash.env

# .env
FLASHPI_API_KEY=tu_api_key_de_pruebas
FLASHPI_URL=https://api.flashpi.ec/v1

Y regístralas en la configuración:

phpconfig/services.php

// config/services.php
return [
    // ...
    'flashpi' => [
        'url' => env('FLASHPI_URL', 'https://api.flashpi.ec/v1'),
        'key' => env('FLASHPI_API_KEY'),
    ],
];

Paso 2 · Crea el servicio

Guárdalo en app/Services/FlashpiService.php:

phpapp/Services/FlashpiService.php

<?php

namespace App\Services;

use Illuminate\Support\Facades\Http;
use RuntimeException;

class FlashpiService
{
    public function emitirFactura(array $factura): array
    {
        $respuesta = Http::withToken(config('services.flashpi.key'))
            ->acceptJson()
            ->timeout(30)
            ->post(config('services.flashpi.url') . '/facturas', $factura);

        if ($respuesta->failed()) {
            throw new RuntimeException(
                'Flashpi ' . $respuesta->status() . ': ' . $respuesta->body()
            );
        }

        return $respuesta->json();
    }
}

Paso 3 · Úsalo desde un controlador

phpapp/Http/Controllers/FacturaController.php

<?php

namespace App\Http\Controllers;

use App\Services\FlashpiService;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

class FacturaController extends Controller
{
    public function store(Request $request, FlashpiService $flashpi): JsonResponse
    {
        $datos = $request->validate([
            'comprador.identificacion' => 'required|string',
            'comprador.razon_social' => 'required|string',
            'comprador.email' => 'required|email',
            'detalles' => 'required|array|min:1',
        ]);

        $datos['comprador']['tipo_identificacion'] = 'cedula';

        $resultado = $flashpi->emitirFactura($datos);

        return response()->json($resultado, 201);
    }
}

Registra la ruta en routes/api.php: Route::post('/facturas', [FacturaController::class, 'store']);

Paso 4 · Pruébalo

bashterminal

php artisan serve
curl -X POST http://localhost:8000/api/facturas \
  -H "Content-Type: application/json" \
  -d '{"comprador":{"identificacion":"0102030405","razon_social":"Cliente de ejemplo",
       "email":"[email protected]"},"detalles":[{"descripcion":"Servicio de ejemplo",
       "cantidad":1,"precio_unitario":25.00}]}'

Paso 5 · Emite en segundo plano (recomendado)

No dejes que el usuario espere al SRI. Envuelve la llamada en un Job de cola con reintentos, para que una lentitud del SRI no frene tu aplicación. Mira colas y reintentos.

Errores frecuentes

Síntoma	Causa probable	Qué hacer	Referencia
`401 Unauthorized`	API key ausente, inválida o de otro ambiente.	Revisa el header `Authorization` y que uses la key del ambiente correcto.	Ver detalle
`422 Esquema XML`	Algún campo no cumple la estructura esperada.	Lee el detalle del error y corrige el campo indicado.	Ver detalle
`SRI 43`	Clave de acceso ya registrada.	No reenvíes: consulta el estado del comprobante por su clave de acceso.	Ver detalle
`SRI 70`	Clave de acceso en procesamiento.	Espera unos segundos y consulta el estado. No reenvíes el comprobante.	Ver detalle

Siguientes pasos

Referencia del endpoint de factura Endpoint de factura electrónica. Webhooks para conocer el estado Actualiza tu base de datos sin consultar. Probar en el ambiente de pruebas del SRI Antes de pasar a producción.

Cómo integrar facturación electrónica en PHP y Laravel con una API