Los CMS no piden cédula o RUC en el checkout por defecto: sin ese dato no hay factura.
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?
Lo que tendrás que resolver
Los precios con y sin impuestos pueden confundir el cálculo de los totales.
Un reembolso en el CMS debe reflejarse con una nota de crédito.
La API key debe vivir en el servidor, no en el tema ni en el navegador.
Cómo se integra con tu CMS
Tu software no necesita generar XML, firmarlo ni hablar con los servicios del SRI.
- 01 Conecta Genera tu API key y úsala solo desde tu backend.
- 02 Engánchate al evento correcto Cuando ocurra en tu sistema, envía los datos a Flashpi.
- 03 Guarda el resultado Registra la
clave_accesoy el estado en tu documento. - 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 CMS | Comprobante |
|---|---|
| Pedido completado o pagado | Factura |
| Reembolso | Nota 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:
<?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();
}Respuesta esperada al emitir:
{
"estado": "AUTORIZADO",
"clave_acceso": "(49 dígitos)",
"numero_autorizacion": "(número de autorización del SRI)",
"fecha_autorizacion": "(fecha y hora)"
}Buenas prácticas para tu CMS
- 1 Agrega el campo de identificación al checkout Cédula, RUC o pasaporte, y valídalo.
- 2 Guarda la
clave_accesoen el pedido Y úsala para no facturar dos veces. - 3 Guarda la API key fuera del tema En una opción protegida o en una constante del servidor.
- 4 Maneja los reembolsos Emitiendo una nota de crédito.
- 5 Muestra el estado Del comprobante al cliente y al administrador de la tienda.
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 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.