Facturator Facturator.
Apéndice

Buenas prácticas

Una lista corta de prácticas que evitarán la mayoría de los problemas que vemos en integraciones reales. No son requisitos, son hábitos recomendados.

Seguridad

  • Almacena la API Key en un gestor de secretos (Vault, AWS Secrets Manager, env vars cifradas). Nunca en el repositorio.
  • Restringe IPs por API Key cuando sea viable.
  • Rota las claves periódicamente. Genera una nueva en paralelo, migra y luego desactiva la antigua.
  • Llama al API desde tu backend, no desde una SPA ni desde una app móvil.

Modelado de datos

  • Persiste localmente el id de cada negocio, cliente, item y documento que crees: lo necesitarás para llamadas futuras.
  • Mantén una correlación entre tu identificador de venta interno y el id del documento Facturator, para idempotencia y para reportes.
  • Trata los catálogos como datos de solo lectura y cachéalos con TTL.

Confiabilidad

  • Implementa backoff exponencial para 429, 5xx y timeouts. No reintentes 4xx que no sean 429.
  • Cuando una emisión falle con timeout, consulta antes de reemitir. Evita el doble registro a toda costa.
  • Loguea siempre el instance del Problem Details: te dará la traza en soporte.

Diseño de tu cliente HTTP

  • Define un cliente único que añada X-API-Key y Accept: application/json a cada request por defecto.
  • Centraliza el manejo de errores: convierte 4xx/5xx en excepciones tipadas (AuthError, ValidationError, RateLimitError, UpstreamError).
  • Configura timeouts razonables (≥ 30 s para POST /documents con emit: true, porque incluye la ida y vuelta al SRI).

UX para tu usuario final

  • Cuando recibas 422, mapea errors[].field a los inputs de tu UI y muestra el mensaje exacto del API.
  • Muestra al usuario el estado actual del documento (draft, recepted, authorizated, rejected) y un botón "Reintentar autorización" cuando aplique.
  • Cuando descargues el PDF, respeta el Content-Disposition sugerido por la API.

Operación

  • Monitorea tu cupo: alerta cuando X-RateLimit-Remaining baje de un umbral.
  • Mantén un dashboard del estado de los documentos: cuántos en autorización, cuántos rechazados, cuántos pendientes.
  • Verifica la vigencia de la firma electrónica al menos cada 24 horas usando POST /businesses/{id}/signature:verify.