Documentación API

TechOST API — Facturación electrónica SRI. Integra tu sistema con el SRI a través de una API REST moderna, segura y auditable.

Entorno de pruebas. Autentícate con ambiente: 1 y emite comprobantes sin valor fiscal. Usa RUC 1790012344001 y números de documento ficticios (001-001-000000001).

Inicio rápido

TechOST API expone 3 grupos principales de recursos bajo https://api.techost.ec:

Base path	Descripción
`/sri`	Emisión, consulta, autorización y verificación de comprobantes electrónicos SRI
`/auth`, `/api-keys`, `/emisores`, `/puntos-emision`, `/secuenciales`	Gestión de autenticación y recursos maestros
`/webhooks`, `/payphone`	Notificaciones automáticas y pagos integrados

Ejemplo de emisión — factura electrónica:

curl https://api.techost.ec/sri/factura \
  -X POST \
  -H "Authorization: Bearer TU_JWT_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
  "comprador": { "identificacion": "1712345678001", "razonSocial": "Cliente Ejemplo S.A.", "tipoIdentificacion": "04", "dirMatriz": "Quito", "obligadoContabilidad": "SI" },
  "emisor": { "ruc": "1790012344001", "razonSocial": "TechOST S.A.", "nombreComercial": "TechOST", "codEstablecimiento": "001", "puntoEmision": "001", "dirMatriz": "Quito", "contribuyenteEspecial": "", "obligadoContabilidad": "SI" },
  "detalles": [{ "codigoPrincipal": "001", "descripcion": "Servicio de consultoría", "cantidad": 1, "precioUnitario": 100.00, "impuestos": [{ "codigo": "2", "codigoPorcentaje": "0", "tarifa": 0, "baseImponible": 100.00, "valor": 0 }] }],
  "pagos": [{ "formaPago": "01", "total": 100.00, "plazo": 0, "unidadTiempo": "DÍAS" }]
}'

Respuesta exitosa (201 Created):

{
  "claveAcceso": "0107202501179001234400110010010000000011234567812",
  "numero": "001-001-000000001",
  "fecha": "2025-07-01T12:00:00.000Z",
  "estado": "PENDIENTE",
  "ambiente": 1,
  "valorTotal": 100.00
}

Autenticación

TechOST API usa JWT (Bearer token) como mecanismo de autenticación. Todas las rutas de negocio (/sri/*, /emisores/*, etc.) están protegidas por un guardia global JwtAuthGuard.

IMPORTANTE. No existe middleware HMAC para peticiones entrantes. La verificación HMAC solo se usa en webhooks salientes (ver sección webhooks).

Obtener token JWT

Regístrate en techost.ec para obtener tus credenciales. El endpoint /auth/login recibe email y contraseña:

curl https://api.techost.ec/auth/login \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{ "email": "tusuario@ejemplo.com", "password": "tucontraseña" }'

Respuesta:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}

Usar el token

Incluye el token en el header Authorization en todos los requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Refresh token

Cuando el token expire, usa /auth/refresh con el refresh_token en el body (protegido con JwtAuthGuard):

curl https://api.techost.ec/auth/refresh \
  -X POST \
  -H "Authorization: Bearer TU_JWT_AQUI" \
  -H "Content-Type: application/json" \
  -d '{ "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }'

Perfil de usuario

Obtén los datos del usuario autenticado:

curl https://api.techost.ec/auth/perfil \
  -X GET \
  -H "Authorization: Bearer TU_JWT_AQUI"

Manejo de errores

La API sigue convenciones REST estándar con códigos HTTP y respuestas estructuradas:

Código	Significado	Descripción
`200`	OK	Operación exitosa
`201`	Created	Recurso creado exitosamente
`400`	Bad Request	DTO inválido, validación fallida o error de negocio (ej. emisor no encontrado)
`401`	Unauthorized	Token JWT no provisto, expirado o inválido
`403`	Forbidden	API Key inactiva o límite de rate excedido
`404`	Not Found	Recurso no existe (emisor, comprobante, etc.)
`409`	Conflict	Comprobante duplicado o estado no válido para la operación
`422`	Unprocessable Entity	Error de negocio SRI (firma, esquema XML, autorización)
`429`	Too Many Requests	Rate limit excedido
`500`	Internal Server Error	Error inesperado del servidor

Estructura de error estándar:

{
  "statusCode": 400,
  "message": "El comprador debe tener una identificación válida",
  "error": "Bad Request"
}

Emisión de comprobantes

Todos los endpoints de emisión requieren autenticación JWT y comparten la misma estructura base. El campo ambiente determina el entorno: 1 = Pruebas, 2 = Producción.

POST /sri/factura

Crea y envía al SRI una factura electrónica. Rate limit: 10 req/min por API Key.

// CreateFacturaDto — estructura completa
{
  "comprador": {
    "identificacion": "1712345678001",    // RUC 13 dígitos o cédula 10
    "razonSocial": "Cliente Ejemplo S.A.",
    "tipoIdentificacion": "04",              // 04=RUC, 05=Cédula, 06=Consumidor Final, 07=Pasaporte
    "dirMatriz": "Quito",
    "obligadoContabilidad": "SI",              // Opcional. "SI" | "NO"
    "email": "cliente@ejemplo.com"              // Opcional. Para envío automático
  },
  "emisor": {
    "ruc": "1790012344001",
    "razonSocial": "TechOST S.A.",
    "nombreComercial": "TechOST",
    "codEstablecimiento": "001",
    "puntoEmision": "001",                    // Nombre exacto del campo (NO ptoEmision)
    "dirMatriz": "Quito",
    "contribuyenteEspecial": "",               // Opcional. Número resolución
    "obligadoContabilidad": "SI",
    "dirEstablecimiento": "Quito",                // Opcional
    "llaveFirma": "-----BEGIN PRIVATE KEY-----...",// Opcional. Sobre-escribe llave del emisor
    "certificadoFirma": "-----BEGIN CERTIFICATE-----..." // Opcional
  },
  "detalles": [{
    "codigoPrincipal": "001",
    "codigoAuxiliar": "",                         // Opcional
    "descripcion": "Servicio de consultoría",
    "cantidad": 1,
    "precioUnitario": 100.00,
    "descuento": 0,                                    // Opcional
    "impuestos": [{
      "codigo": "2",                                   // 2=IVA, 3=ICE, 5=IRBPNR
      "codigoPorcentaje": "0",                         // 0=0%, 2=12%, 4=Exento, 6=No objeto, 7=15%, 8=5%, etc.
      "tarifa": 0,                                      // Porcentaje numérico
      "baseImponible": 100.00,
      "valor": 0
    }]
  }],
  "pagos": [{
    "formaPago": "01",                               // 01=Sin utilización, 15=Compensación deudas, 19=Otros, 20=Transferencia, 21=Tarjeta crédito...
    "total": 100.00,
    "plazo": 0,
    "unidadTiempo": "DÍAS"
  }],
  "informacionAdicional": [{                         // Opcional
    "nombre": "Email",
    "valor": "cliente@ejemplo.com"
  }],
  "ambiente": 1,                                     // Opcional. Default: 1 (Pruebas)
  "tipoEmision": "1"                               // Opcional. Default: "1" (Normal)
}

Respuesta exitosa:

{
  "id": "uuid-del-comprobante",
  "claveAcceso": "0107202501179001234400110010010000000011234567812",
  "numero": "001-001-000000001",
  "fecha": "2025-07-01T12:00:00.000Z",
  "estado": "PENDIENTE",
  "ambiente": 1,
  "tipoEmision": "1",
  "tipoDocumento": "01",
  "valorTotal": 100.00,
  "fechaAutorizacion": null,
  "numeroAutorizacion": null,
  "comprobanteXml": null
}

POST /sri/nota-credito

Emite una nota de crédito electrónica. Requiere el número de factura que se modifica.

{
  "comprador": { /* mismo schema que factura */ },
  "emisor": { /* mismo schema que factura */ },
  "detalles": [{
    "codigoPrincipal": "001",
    "descripcion": "Devolución parcial",
    "cantidad": 1,
    "precioUnitario": 50.00,
    "descuento": 0,
    "impuestos": [{ /* mismo schema que factura */ }]
  }],
  "pagos": [{ /* mismo schema que factura */ }],
  "moneda": "DOLAR",                              // Opcional
  "fechaEmisionDocSustento": "2025-07-01",       // Fecha de la factura original
  "numDocSustento": "001-001-000000001",
  "codDocSustento": "01",                        // 01=factura, 04=nota-credito, 06=guia, etc.
  "motivo": "Devolución parcial de productos",
  "ambiente": 1,
  "tipoEmision": "1"
}

POST /sri/guia-remision

Emite una guía de remisión electrónica.

{
  "emisor": { /* mismo schema que factura */ },
  "destinatarios": [{
    "identificacion": "1712345678001",
    "razonSocial": "Cliente Ejemplo S.A.",
    "tipoIdentificacion": "04",
    "dirEstablecimiento": "Quito",
    "dirDestinatario": "Av. Siempre Viva 123",
    "motivoTraslado": "Venta de productos",
    "detalles": [{
      "codigoPrincipal": "001",
      "descripcion": "Widget",
      "cantidad": 10
    }]
  }],
  "fechaIniTransporte": "2025-07-01",             // Opcional
  "fechaFinTransporte": "2025-07-02",            // Opcional
  "placa": "PBC-1234",                              // Opcional
  "ambiente": 1,
  "tipoEmision": "1"
}

POST /sri/comprobante-retencion

Emite un comprobante de retención electrónico.

{
  "emisor": { /* mismo schema que factura */ },
  "sujetoRetenido": {
    "identificacion": "1712345678001",
    "razonSocial": "Proveedor Ejemplo S.A.",
    "tipoIdentificacion": "04",
    "dirMatriz": "Quito",
    "obligadoContabilidad": "SI",
    "email": "proveedor@ejemplo.com"
  },
  "infoRetencion": {
    "fechaEmisionDocSustento": "2025-07-01",
    "numDocSustento": "001-001-000000001",
    "codDocSustento": "01",
    "tipoRegimen": "ORDINARIO",
    "impuestos": [{
      "codigo": "1",                                   // 1=Renta, 2=IVA, 6=ISD
      "codigoRetencion": "1",                         // Según impuesto y tipo
      "baseImponible": 100.00,
      "porcentajeRetener": 2.00,                          // Opcional
      "valorRetenido": 2.00,
      "codDocSustento": "01",
      "numDocSustento": "001-001-000000001",
      "fechaEmisionDocSustento": "2025-07-01"
    }]
  },
  "ambiente": 1,
  "tipoEmision": "1"
}

Consulta y gestión de comprobantes

GET /sri/comprobantes

Lista comprobantes con paginación y filtros.

Parámetros query:

Parámetro	Tipo	Descripción
`page`	number	Número de página (default: 1)
`limit`	number	Items por página (default: 10, max: 100)
`estado`	string	Filtrar por estado: PENDIENTE, AUTORIZADO, RECHAZADO, DEVUELTO, ANULADO
`tipoDocumento`	string	Filtrar por tipo: 01, 04, 06, 07
`desde`	ISO date	Fecha inicio
`hasta`	ISO date	Fecha fin

curl "https://api.techost.ec/sri/comprobantes?page=1&limit=20&estado=AUTORIZADO" \
  -H "Authorization: Bearer TU_JWT_AQUI"

GET /sri/comprobantes/:claveAcceso

Obtiene un comprobante por su clave de acceso (49 dígitos).

PATCH /sri/comprobantes/:claveAcceso/anular

Anula un comprobante emitido. Solo puede anularse en estado AUTORIZADO.

curl https://api.techost.ec/sri/comprobantes/0107202501179001234400110010010000000011234567812/anular \
  -X PATCH \
  -H "Authorization: Bearer TU_JWT_AQUI" \
  -H "Content-Type: application/json" \
  -d '{ "motivo": "Anulación por error del cliente" }'

POST /sri/comprobantes/:claveAcceso/reintentar

Reintenta el envío al SRI de un comprobante en estado PENDIENTE o RECHAZADO.

Verificación con el SRI

GET /sri/autorizar/:claveAcceso

Consulta al SRI el estado de autorización de un comprobante. Actualiza el registro local y retorna el estado actual.

GET /sri/verificar/:claveAcceso

Verifica si un comprobante existe en el SRI sin actualizar el registro local. Retorna información pública del comprobante.

Preview y validación

POST /sri/preview/factura

Genera el XML firmado de una factura sin enviarlo al SRI. Útil para depuración y previsualización.

curl https://api.techost.ec/sri/preview/factura \
  -X POST \
  -H "Authorization: Bearer TU_JWT_AQUI" \
  -H "Content-Type: application/json" \
  -d '{ /* mismo payload que POST /sri/factura */ }'

Respuesta: { "xmlFirmado": "<?...>" }

POST /sri/validar

Valida un archivo XML firmado contra los esquemas XSD del SRI. Acepta multipart/form-data con el campo archivo.

POST /sri/debug/factura-firmada

Endpoint de depuración que retorna el XML firmado generado internamente durante el flujo de emisión. Recibe el mismo payload que factura.

Sincronización

POST /sri/sincronizar

Fuerza la sincronización de comprobantes pendientes con el SRI. Procesa todos los comprobantes del usuario autenticado cuyo estado sea PENDIENTE, consultando al SRI y actualizando cada uno.

curl https://api.techost.ec/sri/sincronizar \
  -X POST \
  -H "Authorization: Bearer TU_JWT_AQUI"

Respuesta: { "procesados": 5, "autorizados": 3, "rechazados": 1, "errores": 1, "detalle": [ ... ] }

Catálogos SRI

Endpoints públicos que devuelven los catálogos de referencia del SRI. No requieren autenticación.

Endpoint	Descripción
GET `/sri/catalogos/tipos-identificacion`	Tipos de identificación (04=RUC, 05=Cédula, etc.)
GET `/sri/catalogos/tipos-documento`	Tipos de comprobante (01=Factura, 04=Nota de Crédito, etc.)
GET `/sri/catalogos/impuestos`	Códigos de impuestos (2=IVA, 3=ICE, 5=IRBPNR)
GET `/sri/catalogos/formas-pago`	Formas de pago (01=Sin utilización, 20=Transferencia, etc.)
GET `/sri/catalogos/tarifas-iva`	Tarifas IVA con códigos SRI
GET `/sri/catalogos/retenciones`	Códigos y porcentajes de retención

Emisores

CRUD completo para gestionar los datos del emisor (tu empresa). Requiere JWT.

Método	Endpoint	Descripción
POST	`/emisores`	Crear emisor con sus datos fiscales y certificado de firma
GET	`/emisores`	Listar emisores del usuario
GET	`/emisores/:id`	Obtener emisor por ID
PUT	`/emisores/:id`	Actualizar datos del emisor
DELETE	`/emisores/:id`	Eliminar emisor
POST	`/emisores/onboarding`	Onboarding completo: crea emisor + puntos de emisión + secuenciales

Puntos de emisión

Método	Endpoint	Descripción
POST	`/puntos-emision`	Crear punto de emisión
GET	`/puntos-emision`	Listar puntos de emisión
GET	`/puntos-emision/:id`	Obtener punto de emisión
PUT	`/puntos-emision/:id`	Actualizar punto de emisión
DELETE	`/puntos-emision/:id`	Eliminar punto de emisión

Secuenciales

Gestión de la numeración correlativa por establecimiento, punto de emisión y tipo de documento.

Método	Endpoint	Descripción
POST	`/secuenciales`	Crear secuencial
GET	`/secuenciales`	Listar secuenciales
GET	`/secuenciales/:id`	Obtener secuencial
PUT	`/secuenciales/:id`	Actualizar secuencial
DELETE	`/secuenciales/:id`	Eliminar secuencial

API Keys

Gestiona las API Keys asociadas a tu cuenta. Cada key tiene un tier (basic/pro/enterprise) que define el rate limit.

Método	Endpoint	Descripción
POST	`/api-keys`	Crear nueva API Key
GET	`/api-keys`	Listar API Keys
GET	`/api-keys/:id`	Obtener API Key por ID
PUT	`/api-keys/:id`	Actualizar API Key (nombre, estado, tier)
DELETE	`/api-keys/:id`	Eliminar API Key
POST	`/api-keys/:id/rotate`	Rotar (regenerar) el secret de una API Key

Webhooks

Recibe notificaciones automáticas cuando el estado de tus comprobantes cambie. TechOST API envía un POST firmado con HMAC-SHA256 a la URL configurada.

IMPORTANTE. La verificación HMAC aplica exclusivamente a webhooks salientes. No existe HMAC middleware para peticiones API entrantes.

Para verificar la firma de un webhook entrante (en tu servidor):

const crypto = require('crypto');
const payload = JSON.stringify(req.body);
const signature = crypto.createHmac('sha256', webhookSecret).update(payload).digest('hex');
const headerSignature = req.headers['x-techost-signature'];
const isValid = signature === headerSignature;

Gestión de webhooks

Método	Endpoint	Descripción
GET	`/webhooks`	Listar webhooks configurados
POST	`/webhooks`	Crear webhook
GET	`/webhooks/:id`	Obtener webhook
PUT	`/webhooks/:id`	Actualizar webhook
DELETE	`/webhooks/:id`	Eliminar webhook
GET	`/webhooks/:id/logs`	Obtener historial de entregas del webhook

Eventos de webhook

Evento	Disparo
`DOCUMENTO.AUTORIZADO`	El SRI autorizó el comprobante
`DOCUMENTO.RECHAZADO`	El SRI rechazó el comprobante
`DOCUMENTO.DEVUELTO`	El SRI devolvió el comprobante (errores de formato)
`DOCUMENTO.ANULADO`	El comprobante fue anulado manualmente
`DOCUMENTO.PENDIENTE`	Comprobante creado y pendiente de autorización
`DOCUMENTO.GENERADO`	Comprobante generado localmente (antes del envío al SRI)
`DOCUMENTO.REENVIADO`	Comprobante re-enviado al SRI por reintento

Payload del webhook:

{
  "event": "DOCUMENTO.AUTORIZADO",
  "claveAcceso": "0107202501179001234400110010010000000011234567812",
  "estado": "AUTORIZADO",
  "numero": "001-001-000000001",
  "tipoDocumento": "01",
  "fechaAutorizacion": "2025-07-01T12:05:00.000Z",
  "numeroAutorizacion": "0107202501179001234400110010010000000011234567812",
  "ambiente": 1,
  "timestamp": "2025-07-01T12:05:00.000Z"
}

Payphone

Webhook para pagos integrados con Payphone. Recibe notificaciones de transacciones procesadas a través de la pasarela Payphone.

Método	Endpoint	Descripción
POST	`/payphone/webhook`	Notificación de transacción Payphone
GET	`/payphone/transactions`	Listar transacciones Payphone

Estadísticas de uso

GET /sri/estadisticas

Obtiene estadísticas de uso del usuario autenticado: total de comprobantes emitidos, desglose por tipo y por período.

curl https://api.techost.ec/sri/estadisticas \
  -H "Authorization: Bearer TU_JWT_AQUI"

Estado del sistema

GET /sri/status

Endpoint público de health check. Retorna el estado general de la API y sus dependencias.

{
  "status": "ok",
  "timestamp": "2025-07-01T12:00:00.000Z",
  "uptime": 1234567,
  "dependencies": {
    "database": "connected",
    "sri": "reachable"
  }
}

Límites y rate limiting

La API implementa rate limiting en tres capas:

Capa	Límite	Alcance
Global	100 requests/min	Todos los endpoints autenticados. ThrottlerModule de NestJS
Por endpoint (factura)	10 requests/min	`POST /sri/factura`
Por tier de API Key	Basic: 30/min · Pro: 120/min · Enterprise: 600/min	Definido en servicio (guardia API Key no activo aún)

Headers de rate limit. Incluidos en cada respuesta: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Versiones y changelog

Versión	Fecha	Cambios
`v1.0.0`	Julio 2025	Lanzamiento oficial. Emisión de facturas, NC, guías, retenciones. Webhooks. Catálogos.

La API usa versionado por header (Accept: application/json; version=1). La versión estable actual es v1.