Un marketplace factura por sus vendedores: un RUC cada uno, una sola integración

Publicado el 4 de septiembre de 2026

Tu plataforma cobra al comprador y liquida al vendedor. La parte de pagos ya la resolviste. La que aparece después es más incómoda: cada vendedor de tu marketplace tiene su propio RUC, y el comprobante de esa venta sale a nombre de ese RUC, no del tuyo.

Eso significa numeración propia por vendedor, certificado de firma propio por vendedor, ambiente e historial propios por vendedor. Con veinte vendedores ya es un problema de arquitectura; con doscientos, es el proyecto entero.

Aquí está el modelo con el que se resuelve sin abrir doscientas cuentas a mano: el programa OEM de Contadeo, con una sola credencial de servidor, un tenant por cliente y aislamiento a nivel de base de datos. Qué es, cómo se integra, qué recibes por webhook, cómo se factura y qué hace falta para entrar.

Ojo: quién debe emitir el comprobante de cada venta —el vendedor, la plataforma o los dos, y bajo qué figura— depende de cómo esté estructurada tu relación comercial, y eso lo define tu contador. Este artículo empieza donde esa decisión ya está tomada: cada vendedor emite con su propio RUC.

Lo que no se puede compartir entre vendedores

Antes de elegir una arquitectura conviene ver qué es lo que obliga a separar. No es el gusto por el multi-tenant: son cuatro cosas que pertenecen al RUC, no a la plataforma.

Cualquier atajo aquí —un RUC compartido, una numeración global, un certificado para todos— se paga después, cuando un vendedor pide su historial o cuando dos ventas simultáneas se pelean el mismo secuencial.

Una credencial, dos planos: partner y tenant

El OEM te da una partner key con prefijo cdop_. A diferencia de una API key normal cdo_, que nunca puede administrar una cuenta, la partner key sí aprovisiona y gestiona cuentas: pero solo las que tú creaste.

Con esa única credencial operas en dos planos, según envíes o no el header X-Cuenta:

• Plano partner (Authorization: Bearer cdop_…, sin X-Cuenta): creas y gestionas tu portafolio de clientes y configuras tu webhook.
• Plano tenant (la misma key más X-Cuenta: <tenantId>): operas un vendedor concreto con rol administrador —subes su certificado, emites sus comprobantes, descargas su RIDE y su XML— reutilizando los endpoints normales de la API.

En la práctica, la integración que ya escribiste contra la API de Contadeo sirve tal cual: le añades una cabecera y apunta al vendedor que toque.

El aislamiento no es una promesa: es la base de datos

Cada vendedor vive en su propio tenant, con su numeración, sus certificados y sus datos separados. Una partner key solo alcanza a los tenants que tú aprovisionaste, nunca a los de otro integrador. Un identificador de otra cuenta no devuelve un 403 con pistas: devuelve 404, porque para esa credencial ese recurso no existe.

Ese aislamiento es también lo que te deja crecer sin renegociar nada interno: el vendedor número 300 es un POST más, no una migración.

Cada vendedor arranca en Pruebas y pasa a Producción cuando le toca

Todo tenant aprovisionado nace en el ambiente de Pruebas del SRI —certificación, sin validez tributaria—, así que puedes montar el alta completa de un vendedor y probarla de punta a punta antes de que emita un solo documento real. El paso a Producción es por vendedor, no global: los que ya certificaron emiten mientras el resto sigue probando.

El alta típica son tres llamadas: creas el tenant, subes el .p12 del vendedor con POST /certificados y registras su emisor con establecimiento y punto de emisión. A partir de ahí, emitir es el mismo POST /comprobantes/factura de siempre.

Consejo: por defecto un tenant aprovisionado se opera solo desde tu plataforma, sin usuario propio: el vendedor nunca ve Contadeo. Si alguno quiere además entrar al panel, le habilitas un usuario al crearlo. Decidirlo al principio te ahorra explicar dos productos a la vez.

Un webhook para todo tu portafolio

No registras un endpoint por vendedor. El plano partner tiene un único webhook que recibe los estados finales de los comprobantes de todos tus clientes: un POST firmado con HMAC-SHA256 y esquema anti-replay cuando un comprobante queda AUTORIZADO, RECHAZADO o DEVUELTA.

Trae la clave de acceso, el número de autorización, el tenantId y el estado, y no lleva datos personales del comprador: el aviso viaja por internet y se reintenta, así que ahí solo van identificadores. Incluye reintentos con backoff, historial de entregas y reenvío manual de una entrega concreta, que es lo que salva la tarde cuando tu servidor estuvo caído.

Si prefieres no depender del webhook, el comprobante se consulta por API con la misma credencial.

Quién le paga a quién: cortes mensuales, sin mínimos

El modelo comercial es mayorista y va en una sola dirección: tus clientes no le pagan a Contadeo. Contadeo genera un corte mensual con tu consumo —clientes gestionados y comprobantes autorizados del período— y tú cobras a tus vendedores como prefieras dentro de tu producto, con el margen que decidas.

El consumo se cuenta por fecha de emisión, igual que el reporte de ventas, para que puedas reconciliar tu corte contra tus propios números sin discutir criterios.

Dos cosas que conviene decir en claro:

• Sin mínimos de volumen. No hay un piso de facturas al mes para que te aprueben: el programa está pensado también para plataformas que recién arrancan.
• La aprobación es manual. Dejas los datos de tu empresa, validamos el RUC y hay una conversación de arranque. No es un formulario que devuelve una key al instante, y es a propósito: al otro lado hay documentos tributarios reales de terceros.

Al aprobarte recibes tu cupo inicial de clientes y tu primera partner key, que se muestra una sola vez. Si prefieres que la genere tu equipo, te la entregamos por un enlace de canje de un solo uso.

El portal, tu equipo y los correos con tu marca

Tu persona de contacto entra al portal OEM con su correo y ve el consumo del mes en vivo, los cortes de facturación y el estado del webhook. Desde ahí invitas al resto del equipo con rol de administrador o de solo lectura, y cada persona activa su verificación en dos pasos.

En ese mismo portal configuras la marca con la que salen los correos a los compradores de tus vendedores: nombre, color y logo. El comprador recibe su RIDE con tu identidad, no con la nuestra.

La partner key no se usa para entrar al portal: es la credencial de tu servidor y se revoca por separado de las personas.

Preguntas frecuentes

¿Necesito una cuenta por cada vendedor? Sí, y es lo que quieres: un tenant por vendedor mantiene su numeración, sus certificados y su historial aislados, y te deja darle plan y cupo por separado. Los creas tú desde tu plataforma, en segundos.

¿Cada vendedor tiene que conseguir su firma electrónica? Sí. El comprobante se firma con el certificado .p12 de quien vende, así que cada vendedor necesita el suyo, también para el ambiente de Pruebas. Tú lo subes por API al aprovisionarlo.

¿Puedo probar el flujo antes de tener clientes reales? Sí. Todo tenant nace en Pruebas y ese es el ambiente real del SRI: lo que certificas ahí es lo que emitirás en Producción.

¿Qué pasa si supero mi cupo de clientes? La API responde con un error claro y pides ampliación. El cupo se fija al aprobarte y se amplía según crezcas.

¿Y si prefiero empezar por la API normal? Es un camino válido para el prototipo: montas la emisión de un solo RUC con una API key cdo_ y, cuando el modelo esté claro, pasas al OEM para multiplicarlo por vendedor sin reescribir la integración.

Cómo empezar

Si quieres ver la API funcionando antes de solicitar nada, crea tu cuenta gratis y emite en el ambiente de Pruebas con la documentación para integradores. Cuando el modelo por vendedor sea el que necesitas, la página del programa OEM tiene el detalle completo y el acceso se pide en solicitar OEM: razón social, RUC, email y teléfono de contacto. Al aprobarte llegan la partner key y el cupo inicial, y puedes empezar a aprovisionar vendedores el mismo día.

Contadeo — Facturación electrónica del SRI (Ecuador) para plataformas. Programa OEM · Solicitar acceso · Documentación de la API