Documentación API de facturación electrónica

1. Empieza en 5 minutos

Sigue estos 4 pasos en orden. No hace falta leer el resto todavía.

Alcance producción (GA): factura (01) IVA 0%/15%. Los tipos 03–07 están en la API; pruébalos con ks_test_ antes de volumen. Sin ICE/IRBP. El RIDE al comprador final lo genera tu sistema (XML con includeXml=1).

1. Paso 1 — Cuenta + email

   Ve a /signup. Confirma el correo de info@kaltiro.com. Al confirmar te mostramos una sola vez tu clave ks_test_…. Guárdala.

2. Paso 2 — Emisor real + .p12

   En Emisores crea tu RUC y sube el .p12. Luego en Pruebas rápidas generas ks_test_ + JSON. Claves también en /console/keys.

3. Paso 3 — Un request completo (cabeceras + body)

   Las líneas -H son cabeceras. El -d es el body JSON.

   # MÉTODO + URL
   curl -sS -X POST 'https://sello.kaltiro.com/api/v1/invoices' \
   
   # CABECERAS (headers) — no van en el JSON
     -H 'Authorization: Bearer ks_test_TU_CLAVE' \
     -H 'Content-Type: application/json' \
   
   # BODY (JSON) — aquí van emitterId, receptor, items…
     -d '{
       "emitterId": "TU_EMITTER_ID",
       "establecimiento": "001",
       "puntoEmision": "001",
       "receptor": {
         "tipoDoc": "CEDULA",
         "numDoc": "0102030405",
         "razonSocial": "Cliente Demo",
         "email": "cliente@ejemplo.com"
       },
       "items": [{
         "codigo": "P001",
         "descripcion": "Servicio de demostración",
         "cantidad": 1,
         "precioUnitario": 10,
         "ivaCodigoPorcentaje": 4,
         "ivaTarifa": 15
       }],
       "metodoPago": "transferencia"
     }'

4. Paso 4 — Lee la respuesta

   Código 201 con id, estado y claveAcceso. Con ks_test_ no se descuenta crédito.

Siguiente: cabeceras vs body (1 minuto) → luego el comprobante que necesites.

2. Cabeceras vs body (léelo una vez)

Cada llamada a la API tiene 3 partes. Si mezclas la clave dentro del JSON, fallará.

Parte B — Cabeceras obligatorias

En Postman: pestaña Headers. En fetch/axios: objeto headers. Nunca dentro del body.

Authorization: Bearer ks_test_xxxxxxxx
Content-Type: application/json

# Producción (cobra crédito si autoriza):
Authorization: Bearer ks_live_xxxxxxxx

Parte C — Body (ejemplo mínimo)

Esto es lo único que va en el JSON. Sin Authorization aquí.

{
  "emitterId": "clx_tu_emisor",
  "establecimiento": "001",
  "puntoEmision": "001",
  "receptor": { "tipoDoc": "CEDULA", "numDoc": "0102030405", "razonSocial": "Demo" },
  "items": [{
    "codigo": "P001",
    "descripcion": "Servicio",
    "cantidad": 1,
    "precioUnitario": 10,
    "ivaCodigoPorcentaje": 4,
    "ivaTarifa": 15
  }],
  "metodoPago": "transferencia"
}

Postman / JavaScript

3. Conceptos clave

Base URL

https://sello.kaltiro.com — paths /api/v1/…

Emisor

El RUC que factura. Lo identificas con emitterId en el body.

Punto de emisión

001-001 → body: establecimiento + puntoEmision, o emissionPointId.

Clave de acceso

49 dígitos del SRI. Sirve para consultar sin reemitir.

Sandbox vs prod

Header ks_test_ = pruebas gratis. ks_live_ = prod, 1 crédito si autoriza.

precioUnitario

Siempre base sin IVA. El IVA sale de ivaTarifa.

4. Checklist: qué debe ir sí o sí

Si falta algo de esta lista, Sello responde 400 o el SRI rechaza el XML. Léelo antes de integrar en producción.

En tu cuenta / emisor

• Emisor con certificado .p12 y clave cargados (consola → Emisores).
• Al menos un punto de emisión (ej. 001-001).
• Clave API ks_test_ (pruebas) o ks_live_ (producción) + créditos si usas live.
• Email de la cuenta verificado (si no, la clave no autentica).

En cada request de emisión

Lo que Sello pone solo (no lo mandes a pisar)

• RUC Proveedor (Anexo 26) en infoAdicional. Lo inyectamos nosotros. Si lo mandas en camposAdicionales, se ignora.
• Leyenda RIMPE si el emisor (o el body) tiene régimen RIMPE.
• Clave de acceso 49 dígitos, secuencial, firma XAdES, envío al SRI.

Por tipo de comprobante (extra)

Factura electrónica (codDoc 01)

Es el caso más común: vendes un producto o servicio y quieres la autorización SRI (claveAcceso + estado).

Request completo (curl)

curl -sS -X POST 'https://sello.kaltiro.com/api/v1/invoices' \
  -H 'Authorization: Bearer ks_test_TU_CLAVE' \
  -H 'Content-Type: application/json' \
  -d '{ …body de abajo… }'

Body (cédula + IVA 15%)

{
  "emitterId": "clx_tu_emisor",
  "establecimiento": "001",
  "puntoEmision": "001",
  "receptor": {
    "tipoDoc": "CEDULA",
    "numDoc": "0102030405",
    "razonSocial": "María Pérez",
    "email": "maria@ejemplo.com",
    "direccion": "Cuenca"
  },
  "items": [
    {
      "codigo": "SERV-01",
      "descripcion": "Consultoría",
      "cantidad": 1,
      "precioUnitario": 100,
      "descuento": 0,
      "ivaCodigoPorcentaje": 4,
      "ivaTarifa": 15
    }
  ],
  "metodoPago": "transferencia",
  "externalRef": "pedido-4587",
  "camposAdicionales": [
    { "nombre": "Pedido", "valor": "4587" },
    { "nombre": "Observación", "valor": "Entrega en 48h" }
  ]
}

Qué significa cada campo

Respuesta típica (201)

{
  "id": "clx_doc_abc",
  "estado": "autorizada",
  "claveAcceso": "1603202601179999999900110010010000000011234567812",
  "numeroAutorizacion": "1603202601179999999900110010010000000011234567812",
  "tipo": "01",
  "ambiente": "pruebas",
  "secuencial": 1,
  "externalRef": "pedido-4587",
  "credited": false,
  "creditsLeft": 0
}

Variantes de factura (mismo endpoint)

Mismas cabeceras. Solo cambia el body según el caso.

Consumidor final (tope $50 con IVA)

{
  "emitterId": "clx_tu_emisor",
  "establecimiento": "001",
  "puntoEmision": "001",
  "receptor": {
    "tipoDoc": "CONSUMIDOR_FINAL",
    "numDoc": "9999999999999",
    "razonSocial": "CONSUMIDOR FINAL"
  },
  "items": [{
    "codigo": "P01",
    "descripcion": "Producto",
    "cantidad": 1,
    "precioUnitario": 20,
    "ivaCodigoPorcentaje": 4,
    "ivaTarifa": 15
  }],
  "metodoPago": "efectivo"
}

Cliente con RUC + RIMPE emprendedor

{
  "emitterId": "clx_tu_emisor",
  "establecimiento": "001",
  "puntoEmision": "001",
  "regimenTributario": "RIMPE_EMPRENDEDOR",
  "receptor": {
    "tipoDoc": "RUC",
    "numDoc": "1790012345001",
    "razonSocial": "Cliente SA"
  },
  "items": [{
    "codigo": "S01",
    "descripcion": "Servicio",
    "cantidad": 1,
    "precioUnitario": 50,
    "ivaCodigoPorcentaje": 4,
    "ivaTarifa": 15
  }],
  "metodoPago": "transferencia"
}

Exportación (comercio exterior)

{
  "emitterId": "clx_tu_emisor",
  "establecimiento": "001",
  "puntoEmision": "001",
  "receptor": {
    "tipoDoc": "IDENTIFICACION_EXTERIOR",
    "numDoc": "US123456789",
    "razonSocial": "Buyer LLC",
    "direccion": "Miami, FL"
  },
  "items": [{
    "codigo": "EXP1",
    "descripcion": "Producto exportación",
    "cantidad": 1,
    "precioUnitario": 1000,
    "ivaCodigoPorcentaje": 0,
    "ivaTarifa": 0
  }],
  "metodoPago": "transferencia",
  "comercioExterior": {
    "incoTermFactura": "FOB",
    "lugarIncoTerm": "GUAYAQUIL",
    "paisOrigen": "593",
    "puertoEmbarque": "GUAYAQUIL",
    "puertoDestino": "MIAMI",
    "paisDestino": "139",
    "incoTermTotalSinImpuestos": "FOB"
  }
}

Factura de reembolso

{
  "emitterId": "clx_tu_emisor",
  "establecimiento": "001",
  "puntoEmision": "001",
  "receptor": {
    "tipoDoc": "RUC",
    "numDoc": "1790012345001",
    "razonSocial": "Cliente Reembolso"
  },
  "items": [{
    "codigo": "R001",
    "descripcion": "Reembolso de gastos",
    "cantidad": 1,
    "precioUnitario": 100,
    "ivaCodigoPorcentaje": 4,
    "ivaTarifa": 15
  }],
  "metodoPago": "transferencia",
  "reembolsos": [{
    "tipoIdentificacionProveedor": "RUC",
    "identificacionProveedor": "1790012345001",
    "codPaisPago": "593",
    "tipoProveedor": "02",
    "codDocReembolso": "01",
    "estabDocReembolso": "001",
    "ptoEmiDocReembolso": "001",
    "secuencialDocReembolso": "000000001",
    "fechaEmisionDocReembolso": "2026-03-10",
    "numeroAutorizacionDocReemb": "1234567890",
    "impuestos": [{
      "codigo": "2",
      "codigoPorcentaje": "4",
      "tarifa": 15,
      "baseImponibleReembolso": 100,
      "impuestoReembolso": 15
    }]
  }]
}

Nota de crédito (codDoc 04)

Úsala para anular o devolver (total o parcial) una factura o liquidación ya emitida. Debes indicar el documento modificado.

Body

{
  "emitterId": "clx_tu_emisor",
  "establecimiento": "001",
  "puntoEmision": "001",
  "receptor": {
    "tipoDoc": "CEDULA",
    "numDoc": "0102030405",
    "razonSocial": "María Pérez"
  },
  "items": [{
    "codigo": "P001",
    "descripcion": "Devolución",
    "cantidad": 1,
    "precioUnitario": 10,
    "ivaCodigoPorcentaje": 4,
    "ivaTarifa": 15
  }],
  "motivo": "Devolución total",
  "codDocModificado": "01",
  "numDocModificado": "001-001-000000001",
  "fechaEmisionDocSustento": "2026-03-15"
}

Nota de débito (codDoc 05)

Para cargos adicionales (intereses, recargos) sobre una factura o liquidación.

Body

{
  "emitterId": "clx_tu_emisor",
  "establecimiento": "001",
  "puntoEmision": "001",
  "receptor": {
    "tipoDoc": "CEDULA",
    "numDoc": "0102030405",
    "razonSocial": "María Pérez"
  },
  "motivos": [{ "razon": "Interés por mora", "valor": 5 }],
  "impuestos": [{
    "ivaCodigoPorcentaje": 4,
    "ivaTarifa": 15,
    "baseImponible": 5,
    "valor": 0.75
  }],
  "codDocModificado": "01",
  "numDocModificado": "001-001-000000001",
  "fechaEmisionDocSustento": "2026-03-15"
}

Liquidación de compra (codDoc 03)

Cuando compras a un proveedor informal (sin factura). Aquí el “receptor” es el proveedor (no admite consumidor final).

Body

{
  "emitterId": "clx_tu_emisor",
  "establecimiento": "001",
  "puntoEmision": "001",
  "proveedor": {
    "tipoDoc": "CEDULA",
    "numDoc": "0102030405",
    "razonSocial": "Proveedor Informal"
  },
  "items": [{
    "codigo": "C001",
    "descripcion": "Compra de insumos",
    "cantidad": 1,
    "precioUnitario": 20,
    "ivaCodigoPorcentaje": 4,
    "ivaTarifa": 15
  }],
  "metodoPago": "efectivo"
}

Guía de remisión (codDoc 06)

Traslado de mercadería. Puedes omitir el documento sustento si aún no hay factura.

Body

{
  "emitterId": "clx_tu_emisor",
  "establecimiento": "001",
  "puntoEmision": "001",
  "dirPartida": "Cuenca, Av. Principal 100",
  "transportista": {
    "tipoDoc": "RUC",
    "numDoc": "1790012345001",
    "razonSocial": "Transporte Demo SA"
  },
  "fechaIniTransporte": "2026-03-15",
  "fechaFinTransporte": "2026-03-16",
  "placa": "ABC1234",
  "destinatarios": [{
    "tipoDoc": "CEDULA",
    "numDoc": "0102030405",
    "razonSocial": "Destinatario Demo",
    "direccion": "Quito",
    "motivoTraslado": "Venta",
    "items": [
      { "codigo": "P1", "descripcion": "Caja de producto", "cantidad": 2 }
    ]
  }]
}

Retención (codDoc 07)

Cuando actúas como agente de retención. El periodoFiscal va como MM/AAAA. El sustento puede ser factura (01) o liquidación (03).

Body (liquidación + renta 311 @ 3%)

{
  "emitterId": "clx_tu_emisor",
  "establecimiento": "001",
  "puntoEmision": "001",
  "sujetoRetenido": {
    "tipoDoc": "CEDULA",
    "numDoc": "1710034065",
    "razonSocial": "Proveedor Informal"
  },
  "periodoFiscal": "09/2026",
  "docsSustento": [{
    "codDocSustento": "03",
    "numDocSustento": "001-001-000000001",
    "fechaEmisionDocSustento": "2026-09-19",
    "numAutDocSustento": "1909202603…clave49digitos…",
    "totalSinImpuestos": 10,
    "importeTotal": 11.5,
    "codSustento": "01",
    "impuestos": [{
      "codigoPorcentaje": 4,
      "tarifa": 15,
      "baseImponible": 10,
      "valorImpuesto": 1.5
    }],
    "retenciones": [{
      "tipo": "renta",
      "codigo": "1",
      "codigoRetencion": "311",
      "baseImponible": 10,
      "tarifa": 3,
      "valorRetenido": 0.3
    }]
  }]
}

Consultar y reintentar (sin reemitir)

Si el SRI tarda o se cae, no crees otra factura. Consulta o reautoriza. Así no quemas secuencial ni crédito.

Listar comprobantes

curl -sS 'https://sello.kaltiro.com/api/v1/invoices?estado=autorizada&limit=20' \
  -H 'Authorization: Bearer ks_test_TU_CLAVE'

Por ID interno

curl -sS 'https://sello.kaltiro.com/api/v1/invoices/clx_doc_abc' \
  -H 'Authorization: Bearer ks_test_TU_CLAVE'

Por clave de acceso (49 dígitos)

curl -sS 'https://sello.kaltiro.com/api/v1/documents/by-clave/16032026…1234567812?refresh=1' \
  -H 'Authorization: Bearer ks_test_TU_CLAVE'

# Query opcionales:
#   refresh=1     → reconsulta al SRI si está en_proceso
#   includeXml=1  → incluye XML en la respuesta

Reautorizar (quedó en_proceso)

curl -sS -X POST 'https://sello.kaltiro.com/api/v1/documents/clx_doc_abc/authorize' \
  -H 'Authorization: Bearer ks_test_TU_CLAVE'

Webhook y límites

Si configuras webhookUrl en tu cuenta (pídelo por WhatsApp), Sello hace POST best-effort tras emitir o reautorizar. Solo HTTPS (o localhost). Timeout 5s.

Headers:
  Content-Type: application/json
  X-Sello-Event: document.updated
  X-Sello-Timestamp: 1726800000
  X-Sello-Signature: sha256=<hmac_hex>

Body:
{
  "id": "clx_doc_abc",
  "tipo": "01",
  "estado": "autorizada",
  "claveAcceso": "…49 dígitos…",
  "numeroAutorizacion": "…",
  "credited": false,
  "externalRef": "pedido-4587"
}

Cuenta y créditos

curl -sS 'https://sello.kaltiro.com/api/v1/account' \
  -H 'Authorization: Bearer ks_live_TU_CLAVE'

Te devuelve saldo, uso reciente y últimos documentos.

• ks_test_ nunca descuenta.
• ks_live_ descuenta 1 crédito solo si el SRI autoriza.
• Si el SRI rechaza → no hay cobro.
• Sin saldo en producción → HTTP 402.
• Aviso automático por correo (desde info@kaltiro.com) cuando el saldo baja del umbral (por defecto 50).

Errores y cómo solucionarlos

Respuesta típica de error: { "error": "…", "details": { … } }. Mira details (Zod) para el campo exacto.

HTTP de Sello (antes del SRI)

400 de validación (los más comunes)

Estados del comprobante (después del SRI)

Tablas de referencia rápida

tipoDoc del receptor

IVA en ítems

infoAdicional automático

Endpoints de un vistazo

SDK Node — @kaltiro/sello

Cliente tipado, cero dependencias, Node ≥ 18. Ideal si tu backend ya está en TypeScript/JavaScript.

# Desde el repo k-facturador:
npm install ./sdk/node

import { createSelloClient } from '@kaltiro/sello';

const sello = createSelloClient({
  apiKey: process.env.SELLO_API_KEY!, // ks_test_… o ks_live_…
});

const doc = await sello.createInvoice({
  emitterId: 'clx_tu_emisor',
  establecimiento: '001',
  puntoEmision: '001',
  receptor: {
    tipoDoc: 'CEDULA',
    numDoc: '0102030405',
    razonSocial: 'Cliente Demo',
  },
  items: [{
    codigo: 'P001',
    descripcion: 'Servicio',
    cantidad: 1,
    precioUnitario: 10,
    ivaCodigoPorcentaje: 4,
    ivaTarifa: 15,
  }],
  metodoPago: 'transferencia',
});

console.log(doc.estado, doc.claveAcceso);