flashpi 0.1.0

data/README.md

@@ -0,0 +1,383 @@
+# Flashpi para Ruby
+
+SDK oficial de [Flashpi](https://flashpi.com.ec), la API de facturación electrónica del SRI de
+Ecuador, para Ruby.
+
+[English](https://github.com/flashpi1/flashpi-ruby/blob/main/README.en.md)
+
+- Las 45 operaciones de la API: los seis comprobantes, documentos (XML, RIDE en PDF, correo),
+  emisores con establecimientos, puntos de emisión y certificados .p12, webhooks y eventos.
+- Un cliente (`Flashpi::Client`) que puedes compartir entre hilos y que reutiliza sus conexiones.
+- Firmas RBS generadas del documento OpenAPI de la API: Steep y los editores que leen RBS conocen
+  cada campo.
+- Reintentos seguros: cada emisión lleva un `Idempotency-Key`, así un reintento nunca emite dos
+  veces.
+- Errores tipados (RFC 9457) con su `code`, los errores por campo y el `request_id`.
+- Paginación automática: cada lista es `Enumerable` y pide las páginas a medida que avanzas.
+- Verificación de firmas de webhooks (Standard Webhooks) para Rails, Sinatra o cualquier app Rack.
+- Ruby 3.3 o superior. Sin dependencias: solo la biblioteca estándar (net/http).
+
+## Instalación
+
+```bash
+bundle add flashpi
+```
+
+O sin Bundler: `gem install flashpi`.
+
+## Primeros pasos
+
+Crea una clave de API en la [consola](https://flashpi.com.ec/app/) y guárdala en la variable de
+entorno `FLASHPI_API_KEY`. Una clave `fp_test_` emite en el ambiente de pruebas del SRI; una
+`fp_live_` emite comprobantes reales en producción.
+
+```ruby
+require "flashpi"
+
+# Lee FLASHPI_API_KEY; también puedes pasarla: Flashpi::Client.new(api_key: "fp_test_...")
+flashpi = Flashpi::Client.new
+
+invoice = flashpi.invoices.create(
+  {
+    issuerId: "<id del emisor demo o del tuyo>",
+    establishment: "001",
+    emissionPoint: "001",
+    customer: {
+      idType: "ruc",
+      id: "1760013210001",
+      name: "PRUEBAS SERVICIO DE RENTAS INTERNAS",
+      address: "Av. Amazonas y Villalengua, Quito"
+    },
+    items: [
+      {
+        code: "P-001",
+        description: "Servicio de prueba",
+        quantity: "1",
+        unitPrice: "1.00",
+        taxes: [{ type: "vat", rate: "15" }]
+      }
+    ],
+    payments: [{ method: "cash", amount: "1.15" }],
+    options: { waitForAuthorization: true }
+  }
+)
+
+puts invoice[:status], invoice[:accessKey]
+```
+
+Las peticiones y las respuestas son hashes con las claves de la API en camelCase, como símbolos
+(`invoice[:accessKey]`), con sus tipos en `Flashpi::Types` (`Flashpi::Types::create_invoice`,
+`Flashpi::Types::document`). Los montos y cantidades son **textos** (`"1.15"`), nunca números,
+para no perder decimales. Escribe el cuerpo entre llaves, `create({ ... })`: sin ellas, Ruby lo
+tomaría como opciones de la llamada.
+
+Con el **emisor demo** puedes emitir en pruebas sin subir un certificado: su id está en el
+Resumen de la consola (hasta 50 comprobantes al día). Más en
+[Sandbox y emisor demo](https://flashpi.com.ec/docs/sandbox/).
+
+Un cliente mantiene abiertas sus conexiones para las siguientes peticiones y se puede compartir
+entre hilos: crea uno y reutilízalo (en Rails, por ejemplo, en un initializer). `flashpi.close`
+cierra esas conexiones.
+
+## Emitir comprobantes
+
+| Comprobante           | Método                                      |
+| --------------------- | ------------------------------------------- |
+| Factura               | `flashpi.invoices.create(body)`             |
+| Nota de crédito       | `flashpi.credit_notes.create(body)`         |
+| Nota de débito        | `flashpi.debit_notes.create(body)`          |
+| Liquidación de compra | `flashpi.purchase_settlements.create(body)` |
+| Guía de remisión      | `flashpi.waybills.create(body)`             |
+| Retención             | `flashpi.withholdings.create(body)`         |
+
+Todos devuelven el documento. Por defecto la respuesta llega enseguida con el estado
+`processing` y el resultado del SRI llega por webhook. Con
+`options: { waitForAuthorization: true }` la API espera la respuesta del SRI (15 s por defecto,
+hasta 30 s con `waitTimeoutSeconds`) y devuelve `authorized`, `rejected` o `failed`; si el SRI
+tarda más, devuelve `processing` o `pending_sri` y el documento sigue su curso.
+
+## Documentos
+
+```ruby
+document = flashpi.documents.get(invoice[:id])
+puts document[:status]
+
+xml = flashpi.documents.xml(invoice[:id]) # xml[:kind]: "authorized" cuando ya lo autorizó el SRI
+pdf = flashpi.documents.pdf(invoice[:id]) # el RIDE, en bytes
+File.binwrite("#{invoice[:accessKey]}.pdf", pdf)
+puts xml[:xml] if xml[:kind] == "authorized"
+
+flashpi.documents.send_email(invoice[:id]) # reenvía RIDE y XML al correo del comprador
+```
+
+## Listas y paginación
+
+Una lista devuelve una página que es `Enumerable`: `each` recorre todas las páginas, que se
+piden a medida que avanzas, y `first(10)` solo pide las que necesita.
+
+```ruby
+flashpi.documents.list({ status: "authorized", issueDateFrom: "2026-11-01" }).each do |document|
+  puts document[:accessKey]
+end
+
+page = flashpi.documents.list({ limit: 50 })
+puts page.data.size # los documentos de esta página
+page = page.next_page if page.has_next_page?
+```
+
+Los filtros usan los nombres de la API (`issueDateFrom`, `issuerId`) y van en un hash entre
+llaves, antes de las opciones de la llamada.
+
+## Errores
+
+Cada error de la API es una subclase de `Flashpi::APIError` según su estado HTTP. Decide según
+`code`, que es estable y en inglés; `message` sigue el idioma pedido.
+
+```ruby
+begin
+  flashpi.invoices.create(body)
+rescue Flashpi::UnprocessableEntityError => e
+  puts e.code # "validation_failed", "total_mismatch", ...
+  e.errors.each { |field| puts "#{field[:field]}: #{field[:message]}" }
+  raise
+rescue Flashpi::APIError => e
+  puts e.status, e.code, e.request_id # comparte request_id con soporte
+  raise
+end
+```
+
+| Clase                               | Estado | Ejemplos de `code`                                          |
+| ----------------------------------- | ------ | ----------------------------------------------------------- |
+| `Flashpi::BadRequestError`          | 400    | `malformed_json`, `invalid_idempotency_key`                 |
+| `Flashpi::AuthenticationError`      | 401    | `authentication_required`, `invalid_api_key`                |
+| `Flashpi::PermissionDeniedError`    | 403    | `key_read_only`, `key_scope_mismatch`, `ip_not_allowed`     |
+| `Flashpi::NotFoundError`            | 404    | `not_found`                                                 |
+| `Flashpi::ConflictError`            | 409    | `sequential_already_used`, `ride_not_available`             |
+| `Flashpi::UnprocessableEntityError` | 422    | `validation_failed`, `total_mismatch`                       |
+| `Flashpi::RateLimitError`           | 429    | `demo_issuer_quota_exceeded`, `account_email_limit_reached` |
+| `Flashpi::InternalServerError`      | 5xx    | `internal_error`                                            |
+| `Flashpi::APIConnectionError`       | —      | sin respuesta (red); `APITimeoutError` si se agotó el plazo |
+
+Todas derivan de `Flashpi::Error`. Algunos errores traen datos extra en `error.problem`, por
+ejemplo `documentId`, `limit`, `resetsAt` o `rideStatus`. Para recibir los mensajes en español:
+`Flashpi::Client.new(language: "es")`.
+
+## Reintentos e idempotencia
+
+El SDK reintenta hasta 2 veces, con espera creciente, los errores de red, los tiempos agotados y
+las respuestas 408, 429 y 5xx (si piden esperar 60 s o menos; no 501 ni
+`demo_issuer_unavailable`). Cada POST lleva un `Idempotency-Key` que se repite en sus reintentos,
+así que la API nunca emite dos veces:
+
+- Si un reintento descubre que el primer intento sí creó el documento, el SDK devuelve ese
+  documento.
+- Si el primer intento sigue en curso en la API (por ejemplo, se cortó la conexión mientras
+  esperaba al SRI), el SDK espera a que termine con la misma clave, hasta el tiempo límite de la
+  llamada, sin gastar reintentos.
+
+Para usar tu propia clave (por ejemplo el id de tu pedido), pásala a la llamada:
+
+```ruby
+flashpi.invoices.create(body, idempotency_key: "pedido-#{order.id}")
+```
+
+Si una emisión falla igual, el error (un `Flashpi::Error`) trae la clave que usó en
+`error.idempotency_key`. Reintentar con `idempotency_key: error.idempotency_key` nunca emite un
+segundo documento: dentro de 24 horas la API devuelve la primera respuesta; después (o si la API
+perdió el primer intento), la llamada falla con un 422 `idempotency_key_reused` cuyo
+`error.problem[:documentId]` es el documento que ya existe (léelo con `flashpi.documents.get`).
+
+```ruby
+begin
+  flashpi.invoices.create(body)
+rescue Flashpi::Error => e
+  save_for_retry(body, e.idempotency_key) if e.idempotency_key # tu cola de reintentos
+  raise
+end
+```
+
+Una llamada que interrumpes desde fuera (con `Timeout.timeout`, o al detener el proceso o el
+hilo) no lanza un `Flashpi::Error` ni trae la clave: si lo haces con emisiones, pasa tu propio
+`idempotency_key`.
+
+Los límites diarios (como la cuota del emisor demo) no se reintentan: se lanzan como
+`Flashpi::RateLimitError` con `retry_after` en segundos.
+
+## Webhooks
+
+Verifica cada webhook con el cuerpo **tal cual llegó** (sin parsear) y el secreto `whsec_` del
+endpoint. `Flashpi::Webhooks.unwrap` no necesita clave de API (también está en
+`flashpi.webhooks`). Acepta las cabeceras como un hash, el `env` de Rack o `request.headers` de
+Rails.
+
+Con Rails:
+
+```ruby
+class FlashpiWebhooksController < ApplicationController
+  skip_forgery_protection
+
+  def create
+    event = Flashpi::Webhooks.unwrap(request.raw_post, request.headers, ENV.fetch("FLASHPI_WEBHOOK_SECRET"))
+
+    case event[:type]
+    when "webhook_endpoint.verification"
+      # La activación del endpoint: responde el desafío.
+      return render(json: { challenge: event[:data][:challenge] })
+    when "invoice.authorized"
+      Rails.logger.info("Autorizada #{event[:data][:accessKey]}") # event[:data] es el documento
+    when "invoice.rejected"
+      Rails.logger.info("Rechazada #{event[:data][:sriMessages]}")
+    end
+    head :no_content
+  rescue Flashpi::WebhookVerificationError
+    head :bad_request
+  end
+end
+```
+
+Con Sinatra (o cualquier app Rack, con su `env`):
+
+```ruby
+require "sinatra"
+require "flashpi"
+
+post "/webhooks/flashpi" do
+  event = Flashpi::Webhooks.unwrap(request.body.read, request.env, ENV.fetch("FLASHPI_WEBHOOK_SECRET"))
+  if event[:type] == "webhook_endpoint.verification"
+    content_type :json
+    JSON.generate({ challenge: event[:data][:challenge] })
+  else
+    handle_event(event) # tu código, como las ramas del ejemplo de Rails
+    204
+  end
+rescue Flashpi::WebhookVerificationError
+  400
+end
+```
+
+Guarda el `event[:id]` y descarta los repetidos: un evento puede llegar más de una vez. Durante
+una rotación del secreto, Flashpi firma con el nuevo y el anterior, así que cualquiera de los dos
+sirve. Si el endpoint usa el modo `thin` (sin `data`), pide el evento con
+`flashpi.events.get(event[:id])`.
+
+## Emisores y certificados
+
+Estas operaciones necesitan una clave de toda la cuenta con acceso de lectura y escritura.
+
+Un emisor nace de su firma electrónica (.p12): Flashpi la verifica, lee el RUC y consulta al SRI,
+y te devuelve un `prefill` con lo que encontró para que armes el emisor.
+
+```ruby
+onboarding = flashpi.issuer_onboardings.create(
+  { file: File.binread("firma.p12"), password: ENV.fetch("P12_PASSWORD") }
+)
+while onboarding[:status] == "verifying"
+  sleep 2
+  onboarding = flashpi.issuer_onboardings.get(onboarding[:id])
+end
+unless onboarding[:status] == "ready"
+  rejection = onboarding[:rejection]
+  raise(rejection ? rejection[:message] : onboarding[:status])
+end
+
+prefill = onboarding[:prefill]
+completed =
+  if onboarding[:existingIssuer]
+    # Ya tienes ese RUC: el certificado se agrega a ese emisor (una renovación).
+    flashpi.issuer_onboardings.complete(onboarding[:id])
+  else
+    # Un RUC nuevo: tú confirmas los datos del emisor, partiendo del prefill.
+    tax_profile = prefill && prefill[:taxProfile]
+    rimpe_regime = tax_profile && tax_profile[:rimpeRegime]
+    flashpi.issuer_onboardings.complete(
+      onboarding[:id],
+      {
+        legalName: (prefill && prefill[:legalName]) || "MI EMPRESA S.A.",
+        headOfficeAddress: (prefill && prefill[:headOfficeAddress]) || "Av. Amazonas N24-100, Quito",
+        taxProfile: {
+          keepsAccounting: tax_profile ? tax_profile[:keepsAccounting] == true : false,
+          # El régimen RIMPE, si lo tiene ("general" no es uno).
+          rimpeRegime: case rimpe_regime when "entrepreneur", "popular_business" then rimpe_regime end
+          # Si es contribuyente especial o agente de retención, agrega sus resoluciones.
+        }
+        # Si onboarding[:rucNeedsConfirmation] es true, envía también ruc:.
+      }
+    )
+  end
+
+flashpi.issuers.establishments.list(completed[:issuer][:id]).each do |establishment|
+  puts establishment[:code]
+end
+```
+
+El `file` puede ser el contenido del .p12 (`File.binread("firma.p12")`) o un archivo abierto en
+modo binario (`File.open("firma.p12", "rb")`), de hasta 1 MiB.
+
+Para **renovar la firma** de un emisor, para pruebas y producción a la vez, repite el mismo
+flujo con el .p12 nuevo: Flashpi reconoce el RUC (`existingIssuer`) y `complete` sin datos
+agrega el certificado. En cambio,
+`flashpi.issuers.certificates.upload(issuer_id, { file: ..., password: ... })` sube un
+certificado solo para el modo de la clave que usas (pruebas o producción).
+
+## Opciones
+
+```ruby
+flashpi = Flashpi::Client.new(
+  api_key: ENV.fetch("FLASHPI_API_KEY"), # por defecto, la variable FLASHPI_API_KEY
+  language: "es", # idioma de los mensajes: "en" (por defecto) o "es"
+  timeout: 60, # segundos por intento (con waitForAuthorization, al menos la espera + 15 s)
+  max_retries: 2 # 0 desactiva los reintentos
+)
+```
+
+Cada método acepta además, como argumentos con nombre, opciones de esa petición:
+`idempotency_key`, `timeout`, `max_retries`, `language`, `correlation_id` (tu propio id, que
+Flashpi registra) y `extra_headers`.
+
+```ruby
+document = flashpi.documents.get(document_id, timeout: 10, language: "es", correlation_id: "pedido-42")
+```
+
+Para ver la respuesta HTTP y el id de la petición, llama al método a través de `with_response`:
+
+```ruby
+result = flashpi.documents.with_response.get(document_id)
+puts result.data[:status], result.status, result.request_id
+```
+
+El tiempo límite es uno solo por intento, desde que se envía hasta que se lee toda la respuesta:
+conectar, el saludo TLS y cada lectura y escritura cuentan contra él (solo la consulta DNS puede
+pasarse). Las peticiones salen por net/http con el proxy de las variables de entorno
+(`https_proxy` o `HTTPS_PROXY`, una URL `http://`, y `no_proxy`), que se leen al crear el cliente,
+y el SDK nunca sigue redirecciones. En tus pruebas, WebMock o VCR pueden responder en lugar de la
+API.
+
+## Tipos
+
+El gem trae sus firmas RBS en `sig/`. Con [Steep](https://github.com/soutaro/steep),
+`rbs collection install` las encuentra en tu `Gemfile.lock`, y Steep revisa los nombres de los
+campos, sus valores posibles y las opciones de cada llamada. Las firmas necesitan rbs 3.5 o
+superior (Steep 1.7 o superior); Ruby 3.3 trae rbs 3.4.
+
+```ruby
+# @type var body: Flashpi::Types::create_invoice
+body = {
+  issuerId: "<id del emisor>",
+  establishment: "001",
+  emissionPoint: "001",
+  customer: { idType: "final_consumer" },
+  items: [{ description: "Pan", quantity: "2", unitPrice: "0.50", taxes: [{ type: "vat", rate: "15" }] }],
+  payments: [{ method: "cash", amount: "1.15" }]
+}
+document = flashpi.invoices.create(body) # Flashpi::Types::document
+puts document[:accessKey]
+```
+
+## Solo en el servidor
+
+Tu clave de API es secreta: usa el SDK en tus servidores, nunca en código que corre en los
+dispositivos de tus usuarios. `flashpi.inspect` muestra el ambiente y la URL, nunca la clave.
+
+## Licencia
+
+[MIT](https://github.com/flashpi1/flashpi-ruby/blob/main/LICENSE) © 2026 SIGNIADIGITAL S.A.

data/lib/flashpi/api_response.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Flashpi
+  # The data of a call together with the HTTP answer it came from, returned by the methods of a
+  # resource's `with_response` view:
+  #
+  #   result = flashpi.documents.with_response.get(document_id)
+  #   result.data[:status]
+  #   result.status      # 200
+  #   result.request_id  # share it with support
+  class APIResponse
+    # @return [Object] what the method returns
+    attr_reader :data
+    # @return [Integer] the HTTP status
+    attr_reader :status
+    # @return [Hash{String => String}] the response headers, by lowercase name
+    attr_reader :headers
+    # @return [String, nil] Flashpi's id of the request (`x-request-id`)
+    attr_reader :request_id
+
+    def initialize(data:, status:, headers:, request_id:)
+      @data = data
+      @status = status
+      @headers = headers
+      @request_id = request_id
+      freeze
+    end
+
+    def inspect
+      "#<#{self.class.name} status=#{status} request_id=#{request_id.inspect} data=#{(_ = data).inspect}>"
+    end
+  end
+end

data/lib/flashpi/client.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Flashpi
+  # The address of the Flashpi API.
+  DEFAULT_BASE_URL = "https://api.flashpi.com.ec"
+  # Seconds each attempt of a request may take, from sending it to reading the whole answer (the
+  # Node SDK's 60 000 ms).
+  DEFAULT_TIMEOUT = 60.0
+  # Retries after network errors, timeouts, 429 and 5xx.
+  DEFAULT_MAX_RETRIES = 2
+
+  # The Flashpi API client.
+  #
+  #   flashpi = Flashpi::Client.new # reads FLASHPI_API_KEY
+  #   invoice = flashpi.invoices.create({ ... })
+  #
+  # An `fp_test_` key issues in the SRI test environment (pruebas); an `fp_live_` key issues real
+  # documents in production. Use it on servers only: the key must stay secret. A client is safe
+  # to share between threads and keeps its connections open for the next requests: create one
+  # and reuse it.
+  class Client
+    # @return [String] `"test"` for fp_test_ keys (SRI pruebas), `"live"` for fp_live_ keys (SRI
+    #   production)
+    attr_reader :environment
+    # @return [Resources::Invoices] invoices (facturas)
+    attr_reader :invoices
+    # @return [Resources::CreditNotes] credit notes (notas de crédito)
+    attr_reader :credit_notes
+    # @return [Resources::DebitNotes] debit notes (notas de débito)
+    attr_reader :debit_notes
+    # @return [Resources::PurchaseSettlements] purchase settlements (liquidaciones de compra)
+    attr_reader :purchase_settlements
+    # @return [Resources::Waybills] waybills (guías de remisión)
+    attr_reader :waybills
+    # @return [Resources::Withholdings] withholding receipts (comprobantes de retención)
+    attr_reader :withholdings
+    # @return [Resources::Documents] every issued document: search, XML, RIDE (PDF) and email
+    attr_reader :documents
+    # @return [Resources::Issuers] issuers (RUCs) with their establishments, emission points and
+    #   certificates
+    attr_reader :issuers
+    # @return [Resources::IssuerOnboardings] create an issuer from its .p12 certificate
+    attr_reader :issuer_onboardings
+    # @return [Resources::WebhookEndpoints] the URLs Flashpi sends events to
+    attr_reader :webhook_endpoints
+    # @return [Resources::Events] events of documents, certificates and email sending
+    attr_reader :events
+    # @return [Resources::Status] the API's status
+    attr_reader :status
+
+    # Creates a client.
+    #
+    # @param api_key [String, nil] the API key (`fp_test_...` or `fp_live_...`); defaults to the
+    #   FLASHPI_API_KEY environment variable
+    # @param base_url [String, nil] the API's address (default https://api.flashpi.com.ec)
+    # @param timeout [Integer, Float, nil] seconds each attempt of a request may take, from
+    #   sending it to reading the whole answer (default 60). Issuing with
+    #   `options: { waitForAuthorization: true }` raises it to the wait plus 15 seconds. Only a
+    #   DNS lookup can run past it.
+    # @param max_retries [Integer, nil] retries after network errors, timeouts, 429 and 5xx
+    #   (default 2; 0 turns them off)
+    # @param language [String, Symbol, nil] language of the API's messages: `"en"` (default) or
+    #   `"es"`. Error codes do not change.
+    # @param default_headers [Hash{String => String}, nil] headers sent with every request (not
+    #   `Idempotency-Key`: that one is per request)
+    # @raise [Flashpi::Error] for a missing or bad API key, base URL, timeout or max_retries
+    def initialize(api_key: nil, base_url: nil, timeout: nil, max_retries: nil, language: nil, default_headers: nil)
+      config = Internal::Settings.configure(api_key, base_url:, timeout:, max_retries:, language:, default_headers:)
+      @environment = config.api_key.start_with?("fp_test_") ? "test" : "live"
+      @transport = Internal::Transport.new(config.base_url)
+      @engine = Internal::Engine.new(config, @transport)
+      @invoices = Resources::Invoices.new(@engine)
+      @credit_notes = Resources::CreditNotes.new(@engine)
+      @debit_notes = Resources::DebitNotes.new(@engine)
+      @purchase_settlements = Resources::PurchaseSettlements.new(@engine)
+      @waybills = Resources::Waybills.new(@engine)
+      @withholdings = Resources::Withholdings.new(@engine)
+      @documents = Resources::Documents.new(@engine)
+      @issuers = Resources::Issuers.new(@engine)
+      @issuer_onboardings = Resources::IssuerOnboardings.new(@engine)
+      @webhook_endpoints = Resources::WebhookEndpoints.new(@engine)
+      @events = Resources::Events.new(@engine)
+      @status = Resources::Status.new(@engine)
+    end
+
+    # Verify the signature of the webhooks you receive (no API key needed).
+    #
+    # @return [Module] {Flashpi::Webhooks}
+    def webhooks
+      Webhooks
+    end
+
+    # @return [String] the API's address
+    def base_url
+      @engine.config.base_url
+    end
+
+    # Closes the connections kept open for the next requests. The client can still be used: it
+    # opens new ones.
+    #
+    # @return [nil]
+    def close
+      @transport.close
+    end
+
+    # Never the API key.
+    def inspect
+      "#<#{self.class.name} environment=#{environment.inspect} base_url=#{base_url.inspect}>"
+    end
+    alias to_s inspect
+  end
+end

data/lib/flashpi/errors.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Flashpi
+  # Every error this gem raises extends this class, except for invalid arguments (`ArgumentError`
+  # and `TypeError`, as for any Ruby method).
+  class Error < StandardError
+    # The Idempotency-Key a failed POST used (the caller's or the one the SDK made), or nil. To try
+    # the same operation again later without issuing twice, pass it back:
+    # `create(body, idempotency_key: error.idempotency_key)`.
+    attr_accessor :idempotency_key
+  end
+
+  # The API answered with an error status.
+  #
+  # Branch on {#code} (stable English slugs such as `validation_failed`), never on {#message},
+  # which follows the requested language.
+  class APIError < Error
+    # @return [Integer] HTTP status of the answer.
+    attr_reader :status
+
+    # @return [String, nil] Error code, or nil when the answer had no Problem Details (a 502).
+    attr_reader :code
+
+    # @return [String, nil] Short summary of the problem type.
+    attr_reader :title
+
+    # @return [String, nil] What went wrong in this request.
+    attr_reader :detail
+
+    # @return [Array<Hash{Symbol => Object}>] Field-level problems of a request body or query.
+    attr_reader :errors
+
+    # @return [String, nil] Flashpi's id of the request (`x-request-id`): share it with support.
+    attr_reader :request_id
+
+    # @return [Hash{Symbol => Object}, nil] The full Problem Details body, with its extension
+    #   members (`documentId`, `limit`, `resetsAt`, ...), when there was one.
+    attr_reader :problem
+
+    # @return [Hash{String => String}] Response headers, by lowercase name.
+    attr_reader :headers
+
+    # @param status [Integer]
+    # @param headers [Hash{String => String}] by lowercase name
+    # @param problem [Hash{Symbol => Object}, nil]
+    # @param body_text [String]
+    def initialize(status, headers, problem, body_text = "")
+      super(Internal::Problems.message(status, problem, body_text))
+      @status = status
+      @headers = headers
+      @problem = problem
+      members = problem || {}
+      @code = Internal::Problems.text(members[:code])
+      @title = Internal::Problems.text(members[:title])
+      @detail = Internal::Problems.text(members[:detail])
+      errors = members[:errors]
+      @errors = errors.is_a?(Array) ? errors : []
+      @request_id = Internal::Problems.text(members[:requestId]) || headers["x-request-id"]
+    end
+
+    # Seconds the API asked to wait before trying again (`Retry-After`), or nil.
+    #
+    # Daily quota errors point at the next midnight in Ecuador, so this can be hours.
+    #
+    # @return [Integer, nil]
+    def retry_after
+      Internal::Problems.retry_after(headers["retry-after"])
+    end
+  end
+
+  # 400: the request could not be read (malformed JSON, invalid Idempotency-Key, ...).
+  class BadRequestError < APIError; end
+
+  # 401: the API key is missing, malformed, unknown or revoked.
+  class AuthenticationError < APIError; end
+
+  # 403: the key may not do this (read-only, another issuer, IP allowlist, suspended account).
+  class PermissionDeniedError < APIError; end
+
+  # 404: the resource does not exist in this mode (test or live) for this account.
+  class NotFoundError < APIError; end
+
+  # 409: the request conflicts with the current state (sequential used, RIDE not ready, ...).
+  class ConflictError < APIError; end
+
+  # 422: the request is well formed but invalid (`validation_failed`, `total_mismatch`, ...).
+  class UnprocessableEntityError < APIError; end
+
+  # 429: a limit was reached; see {#retry_after} and the `limit` and `resetsAt` members.
+  class RateLimitError < APIError; end
+
+  # 5xx: Flashpi failed to answer. Requests are retried automatically before this is raised.
+  class InternalServerError < APIError; end
+
+  # The request never got an answer (DNS, TLS, connection reset, ...).
+  class APIConnectionError < Error; end
+
+  # The request took longer than the `timeout` option.
+  class APITimeoutError < APIConnectionError; end
+
+  # A webhook did not come from Flashpi, was altered, or is too old: answer 400 and ignore it.
+  class WebhookVerificationError < Error
+    # Why it was rejected: `:missing_headers`, `:invalid_timestamp`, `:timestamp_out_of_range`,
+    # `:no_matching_signature`, `:invalid_secret` or `:invalid_payload`.
+    #
+    # @return [Symbol]
+    attr_reader :reason
+
+    # @param reason [Symbol]
+    # @param message [String]
+    def initialize(reason, message)
+      super(message)
+      @reason = reason
+    end
+  end
+end