Antes de empezar

Ruby 3.0 o superior

Y un proyecto Rails 7 o superior.

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 la API key

bashterminal

export FLASHPI_API_KEY="tu_api_key_de_pruebas"

En producción, guárdala en credentials o en el gestor de secretos de tu plataforma.

Paso 2 · Crea el cliente

rubyapp/services/flashpi_client.rb

# app/services/flashpi_client.rb
require "net/http"
require "json"
require "uri"

class FlashpiClient
  BASE_URL = "https://api.flashpi.ec/v1".freeze

  class Error < StandardError; end

  def initialize(api_key: ENV.fetch("FLASHPI_API_KEY"))
    @api_key = api_key
  end

  def emitir_factura(factura)
    uri = URI("#{BASE_URL}/facturas")

    request = Net::HTTP::Post.new(uri)
    request["Authorization"] = "Bearer #{@api_key}"
    request["Content-Type"] = "application/json"
    request.body = factura.to_json

    response = Net::HTTP.start(uri.host, uri.port, use_ssl: true, read_timeout: 30) do |http|
      http.request(request)
    end

    unless response.is_a?(Net::HTTPSuccess)
      raise Error, "Flashpi #{response.code}: #{response.body}"
    end

    JSON.parse(response.body)
  end
end

Paso 3 · Úsalo

rubycontrolador, job o consola de Rails

# Desde un controlador, un job o la consola de Rails
factura = {
  comprador: {
    tipo_identificacion: "cedula",
    identificacion: "0102030405",
    razon_social: "Cliente de ejemplo",
    email: "[email protected]"
  },
  detalles: [
    { descripcion: "Servicio de ejemplo", cantidad: 1, precio_unitario: 25.0 }
  ]
}

resultado = FlashpiClient.new.emitir_factura(factura)
puts resultado["estado"], resultado["clave_acceso"]

Paso 4 · Emítela en segundo plano

Rails te da Active Job. Llama a FlashpiClient dentro de un job con retry_on para reintentar ante fallos de red, y guarda la clave_acceso en tu modelo de venta. 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 Actualiza tu modelo sin consultar. Prueba en el ambiente de pruebas Antes de pasar a producción.

Cómo integrar facturación electrónica en Ruby on Rails con una API