Facturación electrónica del SRI para startups

Si estás construyendo un producto en Ecuador, la facturación electrónica te llega por uno de dos caminos. En el primero, tu startup factura a sus clientes: cobras una suscripción o un pedido y tienes que entregar un comprobante autorizado por el SRI. Eso se resuelve con una cuenta normal de Contadeo, y la API, los webhooks y el servidor MCP entran también en el plan gratis.

En el segundo, tu plataforma emite por sus clientes: tu ERP, tu punto de venta o tu marketplace factura a nombre de otros contribuyentes, cada uno con su RUC, su numeración y su certificado. Ese es el programa OEM. Esta página cubre los dos carriles en ese orden, y termina con lo que todavía no hacemos.

Ojo: los dos carriles necesitan un RUC y una firma electrónica .p12 reales, también en el ambiente de Pruebas del SRI. No tenemos un certificado de pruebas compartido: el ambiente de Pruebas es el del propio SRI y cada comprobante se firma con el certificado del emisor. Dónde se saca el .p12 y cuánto cuesta, en la guía de firma electrónica.

Tu startup factura a sus clientes

Una cuenta normal, la misma que usa cualquier empresa, operada desde tu código:

Plan gratis permanente: 10 comprobantes al mes, sin tarjeta. Al agotarlo, la API responde 402 hasta el mes siguiente.
La API, los webhooks y el MCP entran en todos los planes, también en el gratis. No hay un "plan API" aparte ni un cargo por integrarte.
Ambiente de Pruebas con tope propio: 500 comprobantes al mes que no consumen el cupo de tu plan. Es el ambiente de certificación del SRI, así que lo que pruebas ahí es lo que emitirás en Producción.
Planes de pago: $39, $89 y $179 al año sin IVA (Emprendedor, Pyme y Empresa). En los planes de pago la emisión no se corta al llegar al cupo: el excedente se tarifa por tramos anunciados de antemano. El detalle, en precios.
Seis tipos de comprobante del SRI: factura (01), liquidación de compra (03), nota de crédito (04), nota de débito (05), guía de remisión (06) y comprobante de retención (07). El gratis incluye 01 y 04; los seis entran desde Pyme (ver la matriz de capacidades).
Emisión asíncrona: el POST valida, reserva el secuencial y responde 202; firmar y transmitir al SRI ocurre en segundo plano. Con el header Idempotency-Key un reintento devuelve el mismo comprobante en vez de duplicarlo o quemar otro secuencial.
Lote de hasta 100 facturas por request, con semántica parcial: una inválida se reporta con su índice sin frenar a las demás.
Hasta 5 API keys activas por cuenta, con roles limitados (emisor, contador, lector, webhooks) y revocación instantánea.

Tu primera factura por API

La cadena completa, desde cero hasta el PDF, está en la documentación para integradores; estos son los pasos en orden:

POST /tenants/register crea la cuenta y el usuario owner en plan free y devuelve los tokens.
Crea tu API key en el panel (Configuración → API), con rol owner o admin. Se muestra una sola vez y no expira. No hay endpoint público para crearla: es una acción del panel, a propósito.
Registra el emisor (POST /emisores), su establecimiento y su punto de emisión. Si el RUC ya facturaba con otro sistema, sincroniza el secuencial con PATCH /emisores/:id/secuenciales.
Sube el certificado con POST /certificados, en JSON: p12Base64, passphrase y un alias. Se cifra en reposo y solo se descifra en memoria al firmar.
Emite con POST /comprobantes/factura y tu Idempotency-Key:

curl -X POST https://contadeo.com/api/comprobantes/factura \
  -H "authorization: Bearer cdo_tu_api_key" \
  -H 'content-type: application/json' \
  -H "Idempotency-Key: pedido-8841" -d '{
  "emisorId":"<uuid>","certificadoId":"<uuid>",
  "establecimiento":"001","puntoEmision":"001",
  "infoFactura":{
    "tipoIdentificacionComprador":"05",
    "razonSocialComprador":"JUAN PEREZ","identificacionComprador":"1745678902",
    "obligadoContabilidad":"NO",
    "totalSinImpuestos":10,"totalDescuento":0,
    "totalConImpuestos":[{"codigo":"2","codigoPorcentaje":"4",
      "baseImponible":10,"tarifa":15,"valor":1.5}],
    "importeTotal":11.5,"pagos":[{"formaPago":"01","total":11.5}]},
  "detalles":[{"descripcion":"Producto","cantidad":1,"precioUnitario":10,
    "descuento":0,"precioTotalSinImpuesto":10,
    "impuestos":[{"codigo":"2","codigoPorcentaje":"4","tarifa":15,
      "baseImponible":10,"valor":1.5}]}]
}'
# → 202 { "comprobanteId": "...", "claveAcceso": "49 dígitos", "estado": "BORRADOR" }

Consulta GET /comprobantes/:id cada ~3 segundos hasta AUTORIZADO, RECHAZADO o DEVUELTA — el SRI suele resolver en 5 a 30 segundos — o registra un webhook y te avisamos sin que preguntes.
Descarga el RIDE (PDF) con GET /comprobantes/:id/ride y el XML autorizado con /xml: los dos devuelven URLs prefirmadas que expiran en una hora.

Todos los endpoints con sus esquemas y errores están en la referencia OpenAPI, y el spec descargable sirve para generar el cliente de tu lenguaje.

Cobros recurrentes

Si cobras una suscripción, el patrón es corto:

Usa el id del cobro como Idempotency-Key. Si tu job de facturación se reintenta —o tu pasarela te reenvía el mismo evento— recibes el mismo comprobante con reutilizado: true, no uno nuevo. La clave no caduca: un reintento de hace un mes sigue devolviendo el original.
Escucha el webhook firmado en vez de hacer polling. Cada entrega llega con X-Contadeo-Signature: t=<timestamp>,v1=<hex>, donde hex es HMAC_SHA256(secret, "<timestamp>.<cuerpo crudo>"). Verifica sobre el cuerpo crudo y en tiempo constante; el timestamp es el anti-replay. Hay 8 reintentos con backoff y bitácora de entregas.
Pon el correo del comprador en infoAdicional y el RIDE le llega solo al autorizarse, sin que montes tu propio envío.
Un reembolso se documenta con una nota de crédito (04) sobre la factura original. Fuera del plazo legal de anulación, es la única vía correcta.

O factura conversando

El servidor MCP expone 37 tools que preparan, emiten y autorizan comprobantes reales ante el SRI desde un asistente de IA. Dos formas de conectarlo:

Remoto: https://contadeo.com/api/mcp, con OAuth 2.1 y PKCE. Pegas la URL en tu cliente, inicias sesión y autorizas.
Local: npx -y contadeo-mcp con una API key cdo_ en la variable CONTADEO_API_KEY.

La matemática tributaria la hace siempre el servidor, no el modelo: preparar_factura calcula líneas, IVA y totales con el redondeo oficial y devuelve un resumen que el asistente tiene que confirmar contigo antes de emitir. emitir_factura re-valida el cuadre y rechaza payloads calculados a mano.

Tu plataforma emite por sus clientes (OEM)

Cuando tu producto factura a nombre de otros contribuyentes, la pieza es el programa OEM:

Una sola credencial, la partner key cdop_. Sin el header X-Cuenta gestionas tu portafolio; con X-Cuenta: <tenantId> operas un cliente concreto con rol administrador.
Un tenant por cliente: cada uno con su numeración, sus certificados y su historial separados. Tu partner key solo alcanza a los tenants que tú aprovisionaste, y el aislamiento está garantizado en la base de datos.
Webhooks firmados al estado final de cada comprobante, sin datos personales del comprador, con reintentos y reenvío manual.
Cortes mensuales al partner: Contadeo te factura a ti el consumo del período (tenants gestionados y comprobantes autorizados) y tus clientes no le pagan a Contadeo. La tarifa mayorista se acuerda al aprobarte.
Sin mínimos de volumen. No exigimos un número mínimo de facturas al mes: el programa está pensado también para plataformas que recién arrancan.
Aprobación manual: revisamos la solicitud y hay una conversación de arranque antes de entregarte la credencial y tu cupo inicial.
Portal propio en /portal-oem: consumo en vivo, cortes, estado del webhook, equipo con roles y dos pasos, y el co-branding de los correos que salen a los compradores de tus clientes (nombre, color y logo).

Cómo funciona en detalle, en la página del programa OEM; el alta, en /solicitar-oem.

Qué no hacemos (todavía)

Para que decidas con la información completa:

No hay certificado de pruebas compartido. Ni siquiera para probar: el ambiente de Pruebas del SRI exige tu propio .p12 y tu RUC.
No hay plugins de Shopify ni de WooCommerce. La integración es por API, SDK o MCP.
El SDK oficial es solo de TypeScript/Node (contadeo-sdk). Para otros lenguajes está el spec OpenAPI 3.1 con los payloads de emisión tipados: cualquier generador produce un cliente utilizable.
No hay app nativa. El panel es una PWA: se instala desde el navegador y se ve en el móvil, pero no está en las tiendas.

Preguntas frecuentes

¿Necesito RUC para probar?

Sí. El emisor de un comprobante es un contribuyente con RUC, y el ambiente de Pruebas es el del SRI, no un simulador nuestro: valida el RUC y la firma igual que Producción. Lo que cambia es que esos comprobantes no tienen validez tributaria y no consumen el cupo de tu plan.

¿Cuenta normal u OEM?

Si el RUC que emite es el tuyo, cuenta normal. Si emites a nombre de terceros —cada cliente con su propio RUC, su numeración y su certificado— es OEM: una API key cdo_ nunca puede administrar cuentas, y el modelo de un tenant por cliente es lo que mantiene los historiales separados.

¿Cuánto cuesta el OEM?

La tarifa mayorista se acuerda contigo al aprobar tu empresa y se cobra en cortes mensuales sobre el consumo del período. No hay mínimos de volumen. Los planes de cuenta normal sí tienen precio de lista público en /precios.

¿Puedo llevarme mis datos?

Sí. Los datos de tu cuenta son tuyos y los exportas cuando quieras: clientes y comprobantes en CSV, y los XML y RIDE de cada comprobante. En el OEM, un cliente puede llevarse su empresa. Lo que se conserva por obligación del Código Tributario son los comprobantes emitidos, 7 años. Está en los Términos.

¿Emitir en Pruebas cuesta algo?

No. El ambiente de Pruebas tiene su propio tope de 500 comprobantes al mes y no toca el cupo de tu plan, así que puedes certificar cada tipo de comprobante sin gastar el gratis.

Cómo empezar

Crea tu cuenta gratis y prueba la API entera en el ambiente de Pruebas: 10 comprobantes de Producción al mes, sin tarjeta.
Si tu plataforma va a emitir por sus clientes, solicita acceso OEM.
¿Dudas antes de decidir el carril? Escríbenos y lo conversamos.

Lo que no tienes que programar es lo de siempre: el XML de la ficha técnica vigente, la firma XAdES-BES, los reintentos ante el SRI y el cuadre de impuestos, que se valida antes de enviar.