Integración · CMS y tiendas web

API de facturación electrónica para CMS y tiendas web

Emite la factura de cada pedido de tu tienda de forma automática, desde el CMS que ya usas.

EVENTOS EN TU CMS→ comprobante

Pedido #1042 completado Factura

Pedido #1038 pagado Factura

Reembolso pedido #1021 Nota de crédito

Para quién es esta página

Agencias, desarrolladores de plugins y administradores técnicos de tiendas en WordPress, WooCommerce, Shopify y otros CMS.

¿Eres dueño de una tienda online?

El reto

Lo que tendrás que resolver

01

Los CMS no piden cédula o RUC en el checkout por defecto: sin ese dato no hay factura.

02

Los precios con y sin impuestos pueden confundir el cálculo de los totales.

03

Un reembolso en el CMS debe reflejarse con una nota de crédito.

04

La API key debe vivir en el servidor, no en el tema ni en el navegador.

Cómo se integra

Cómo se integra con tu CMS

Tu software no necesita generar XML, firmarlo ni hablar con los servicios del SRI.

  1. 01 Conecta Genera tu API key y úsala solo desde tu backend.
  2. 02 Engánchate al evento correcto Cuando ocurra en tu sistema, envía los datos a Flashpi.
  3. 03 Guarda el resultado Registra la clave_acceso y el estado en tu documento.
  4. 04 Mantén el estado al día Recibe webhooks o consulta el comprobante cuando lo necesites.

En qué momento emitir cada comprobante

Evento en tu CMSComprobante
Pedido completado o pagadoFactura
ReembolsoNota de crédito

Dónde engancharte en cada plataforma

  • WooCommerce. El hook woocommerce_order_status_completed.

  • Shopify. El webhook orders/paid, recibido por tu backend, que luego llama a Flashpi.

  • Otros CMS. El evento equivalente de «pedido pagado» o «pedido completado».

Ejemplo: plugin mínimo para WooCommerce

Este fragmento emite la factura cuando el pedido pasa a «completado» y guarda la clave de acceso en el pedido:

phpflashpi-facturacion.php
<?php
/**
 * Plugin Name: Flashpi Facturación (ejemplo)
 */

add_action('woocommerce_order_status_completed', 'flashpi_emitir_factura', 10, 1);

function flashpi_emitir_factura($order_id)
{
    $order = wc_get_order($order_id);

    // Evita facturar dos veces el mismo pedido
    if (!$order || $order->get_meta('_flashpi_clave_acceso')) {
        return;
    }

    $detalles = [];
    foreach ($order->get_items() as $item) {
        $cantidad = max(1, $item->get_quantity());
        $detalles[] = [
            'descripcion'     => $item->get_name(),
            'cantidad'        => $cantidad,
            'precio_unitario' => round($item->get_total() / $cantidad, 2),
        ];
    }

    $cuerpo = [
        'comprador' => [
            'tipo_identificacion' => 'cedula',
            // WooCommerce no pide cédula o RUC por defecto: agrega este campo al checkout
            'identificacion'      => $order->get_meta('_billing_identificacion'),
            'razon_social'        => $order->get_formatted_billing_full_name(),
            'email'               => $order->get_billing_email(),
        ],
        'detalles' => $detalles,
    ];

    $respuesta = wp_remote_post('https://api.flashpi.ec/v1/facturas', [
        'timeout' => 30,
        'headers' => [
            'Authorization' => 'Bearer ' . get_option('flashpi_api_key'),
            'Content-Type'  => 'application/json',
        ],
        'body'    => wp_json_encode($cuerpo),
    ]);

    if (is_wp_error($respuesta) || wp_remote_retrieve_response_code($respuesta) >= 400) {
        $order->add_order_note('Flashpi: no se pudo emitir la factura.');
        return;
    }

    $datos = json_decode(wp_remote_retrieve_body($respuesta), true);
    $order->update_meta_data('_flashpi_clave_acceso', $datos['clave_acceso'] ?? '');
    $order->save();
}
Es un ejemplo mínimo, no un plugin listo para producción. Falta una pantalla de ajustes para la API key, el campo de cédula o RUC en el checkout y el manejo de reembolsos. En Shopify, el patrón es el mismo, pero la lógica vive en tu backend.

Respuesta esperada al emitir:

json200 OK · comprobante autorizado
{
  "estado": "AUTORIZADO",
  "clave_acceso": "(49 dígitos)",
  "numero_autorizacion": "(número de autorización del SRI)",
  "fecha_autorizacion": "(fecha y hora)"
}
Buenas prácticas

Buenas prácticas para tu CMS

  1. 1 Agrega el campo de identificación al checkout Cédula, RUC o pasaporte, y valídalo.
  2. 2 Guarda la clave_acceso en el pedido Y úsala para no facturar dos veces.
  3. 3 Guarda la API key fuera del tema En una opción protegida o en una constante del servidor.
  4. 4 Maneja los reembolsos Emitiendo una nota de crédito.
  5. 5 Muestra el estado Del comprobante al cliente y al administrador de la tienda.
Incluido

Lo que Flashpi te da

  • API REST con JSON Versionada en /v1 y descrita con OpenAPI 3.1. Ver referencia
  • Ambiente de pruebas del SRI Valida tu integración antes de producción. Cómo probarlo
  • Colección de Postman Para explorar los endpoints.
  • SDKs open source en GitHub
  • Webhooks Para recibir el estado de cada comprobante.
  • Ejemplos por lenguaje y soporte técnico
  • Estado del servicio en tiempo real status.flashpi.ec
Preguntas frecuentes

Preguntas sobre la integración con CMS

¿Existe un plugin listo para WordPress o WooCommerce?

El ejemplo de arriba es un punto de partida para tu desarrollador.

¿Funciona con Shopify?

Sí, mediante un backend intermedio que recibe el webhook orders/paid y llama a Flashpi.

¿Y si el cliente no escribe su cédula o RUC?

Sin ese dato no puedes emitir la factura a su nombre. Hazlo obligatorio en el checkout. Para consumidor final, confirma las condiciones vigentes.

¿Cómo se maneja un reembolso?

Con una nota de crédito que referencia la factura del pedido.

Empieza hoy

Integra tu CMS con el SRI

Prueba la API en el ambiente de pruebas y cuéntanos tu caso. Te ayudamos a planear la integración.