Plataforma — integra a tus clientes
Con Plataforma integras la facturación electrónica en el sistema de cada uno de tus clientes (su ERP, su punto de venta, su tienda) y la administras desde un solo lugar.
Tú (desarrollador) └─ Cliente: Casa Barista ← su propio espacio, aislado ├─ Su empresa y credenciales del MH ├─ Sus sucursales y puntos de venta ├─ Sus documentos, receptores y productos └─ Sus claves de API ← tu sistema emite a su nombre con ellas └─ Cliente: Ferretería El Clavo ← otro espacio, otro aislamientoAislamiento. Cada cliente es una organización propia: su número de control, sus documentos y sus credenciales (cifradas) son sólo suyos. La clave de un cliente no ve nada de ti ni de tus otros clientes, y tus claves no emiten a nombre de nadie. Tu cliente puede desconectarse cuando quiera: sus datos siguen siendo suyos.
El flujo completo
Sección titulada «El flujo completo»-
Habilita una clave tuya para Plataforma. En el panel: Clientes → Acceso por API. Sólo las claves que habilites ahí administran clientes. Base de la API:
https://app.openfactura.co/cloud/plataforma. -
Crea el cliente. Lo que ya sabes de él llega prellenado a su alta.
Ventana de terminal curl https://app.openfactura.co/cloud/plataforma/clientes \-H "Authorization: Bearer $OPENFACTURA_PLATAFORMA" \-H "Content-Type: application/json" \-d '{"nombre": "Casa Barista","externalId": "cliente-482","datos": { "nit": "0614-290786-102-3", "razonSocial": "CASA BARISTA, S.A. DE C.V.", "correo": "[email protected]" }}'Su espacio existe desde ese momento (
organizationId): puedes configurarlo antes de que el cliente llegue (desde el panel, Clientes → el cliente → Su cuenta) y crear sus claves y webhooks. En producción emite cuando el cliente activa su cuenta. -
Envíale su enlace de alta. Un solo uso; vence en 72 h (de 1 a 168 con
expiraEnHoras).Ventana de terminal curl -X POST https://app.openfactura.co/cloud/plataforma/clientes/cli_…/enlace \-H "Authorization: Bearer $OPENFACTURA_PLATAFORMA"# → { "url": "https://app.openfactura.co/cloud/alta/…", "expira": 1763… }Con el enlace, tu cliente crea su usuario y activa su cuenta: queda como dueño, revisa lo que configuraste y completa lo que falte (sus credenciales de Hacienda, si no las cargaste tú). Si ya usa Open Factura con su empresa, puede conectar ésa en su lugar. Si al crear su usuario le pedimos confirmar el correo, el enlace del correo lo trae de vuelta a su alta para terminar.
-
Entérate cuando esté listo. Suscribe un webhook a
cliente.listo: llega una vez cuando el cliente puede emitir en pruebas y otra cuando puede en producción, a cualquier webhook suscrito (creado con clave de pruebas, de producción o en el panel). Con la CLI:openfactura webhooks add <url> --eventos cliente.listo. También puedes consultarGET /clientes/:id:preparacion(conectado,pruebas,produccion) yfalta(lo que le falta). -
Crea su clave de API. Funciona sólo en su espacio. Guárdala en el sistema de tu cliente.
Ventana de terminal curl https://app.openfactura.co/cloud/plataforma/clientes/cli_…/claves \-H "Authorization: Bearer $OPENFACTURA_PLATAFORMA" \-H "Content-Type: application/json" \-d '{ "nombre": "POS Casa Barista", "modo": "live", "scopes": ["dte:emit", "dte:read"] }'# → { "clave": "of_live_…" } (sólo aparece esta vez) -
Emite desde el sistema de tu cliente con la API de siempre y su clave. Open Factura valida el documento, lo firma, lo transmite a Hacienda y te devuelve el sello, el PDF y el JSON. En producción, si el receptor tiene correo, le llega con el PDF (con el logo de tu cliente) y el JSON oficial: ver Marca y correo.
Ventana de terminal curl https://app.openfactura.co/api/v1/dte \-H "Authorization: Bearer $CLAVE_DEL_CLIENTE" \-H "Idempotency-Key: venta-10931" \-H "Content-Type: application/json" \-d '{ "tipoDte": "01", "puntoVentaId": "pv_sucursal_centro", "datos": { … } }'
Sucursales
Sección titulada «Sucursales»Cada cliente registra sus establecimientos y puntos de venta (/api/v1/establecimientos,
/api/v1/puntos-venta, con su clave). Cada documento indica quién emite con puntoVentaId, y cada
punto de venta lleva su propia numeración. Un cliente con tres tiendas emite desde las tres con una
sola integración.
Webhooks multi-tenant
Sección titulada «Webhooks multi-tenant»Tus webhooks reciben también los eventos de todos tus clientes (dte.procesado,
dte.rechazado, dte.contingencia, dte.invalidado…) con cliente en datos para saber de quién
es. Tu cliente sigue recibiendo los suyos, sin cliente. Como todo webhook, uno creado con una clave
de pruebas sólo recibe eventos de pruebas (Ambientes).
¿El sistema de un cliente debe recibir sólo sus eventos? Crea el webhook en su espacio:
POST /clientes/:id/webhooks (o en el panel, Nuevo webhook → ¿Para quién?). Ese webhook no queda
atado a un ambiente (ambiente: null): recibe los eventos de pruebas y de producción de tu cliente,
aunque lo crees con una clave de pruebas. Usa ambiente del cuerpo para separarlos.
{ "evento": "dte.procesado", "organizacion": "org_de_tu_plataforma", "ambiente": "01", "datos": { "codigoGeneracion": "0862382B-…", "cliente": { "id": "cli_…", "externalId": "cliente-482", "nombre": "Casa Barista", "organizationId": "org_…" } }}cliente.listo lleva { id, externalId, nombre, organizationId, preparacion }.
Con tu agente de IA (MCP)
Sección titulada «Con tu agente de IA (MCP)»Con una clave habilitada para Plataforma, el MCP suma estas herramientas:
| Herramienta | Hace |
|---|---|
plataforma_clientes_listar |
Tus clientes, su estado y qué les falta |
plataforma_cliente_crear |
Agrega un cliente (con datos prellenados) |
plataforma_cliente_enlace |
Su enlace de alta |
plataforma_cliente_clave_crear |
Una clave de API en su espacio |
«Agrega a Casa Barista, NIT 0614-290786-102-3, y dame su enlace de alta.»
Marca blanca
Sección titulada «Marca blanca»Con el plan Platform tus clientes ven tu marca, no la de Open Factura. Tú eliges el nombre, el logo y el color. Abajo está, sin adornos, qué lleva tu marca y qué no.
Configúrala en el panel (Marca → Marca blanca para tus clientes) o por API
(/api/v1/ext/marca/plataforma*, con emisor:write; consultar pide emisor:read):
curl -X PUT https://app.openfactura.co/api/v1/ext/marca/plataforma \ -H "Authorization: Bearer $OPENFACTURA_PLATAFORMA" \ -H "Content-Type: application/json" \ -d '{ "nombre": "Tu Marca", "color": "#3b82f6", "correoSoporte": "[email protected]", "activa": true }'| Campo | Reglas |
|---|---|
nombre |
2 a 40 caracteres, sólo letras latinas, números y . , ' & ( ) + ! ? -, sin enlaces. Se rechazan las imitaciones de Open Factura o de Hacienda (letras de otro alfabeto, números por letras, separadores). |
slug |
Minúsculas, números y guiones (3 a 32). Algunos están reservados. Único: 409 slug_en_uso si otra plataforma lo tiene. |
color |
#rrggbb, con contraste suficiente sobre fondo oscuro. |
| Logo | PUT /plataforma/logo con { "base64": "…" }: PNG o JPG, hasta 200 KB y 2000 px. Sin SVG. |
| Soporte | correoSoporte y whatsappSoporte: sólo correo y teléfono. |
Qué ve tu cliente
Sección titulada «Qué ve tu cliente»Lleva tu marca:
- Alta. El enlace de alta lleva tu logo, tu nombre y tu color, sin mencionar a Open Factura.
- Panel. En tu dominio, el panel muestra tu nombre, logo, color, título y favicon, y sólo lo de su negocio (emisor, documentos, clientes, productos, WhatsApp). No ve planes, claves de API, webhooks ni nada de desarrollo.
- Correos. Los de su cuenta (confirmar correo, restablecer contraseña) y los de sus documentos salen con tu nombre y tu soporte.
- PDF. El PDF lleva el logo de tu cliente y, en sus metadatos, tu nombre como productor.
- Bot de WhatsApp. El texto del bot habla con tu nombre y tu soporte.
No la lleva (todavía):
- El número de WhatsApp. Es compartido: el nombre del perfil sigue diciendo Open Factura y el
enlace
wa.melleva ese número. Un número dedicado por plataforma llegará más adelante. - La dirección del remitente de los correos, salvo que tengas un remitente neutro o un dominio de envío propio. Sin eso, el nombre es el tuyo pero la dirección conserva el dominio de Open Factura.
- El código del panel. Quien mire el código fuente de la página (view-source) puede encontrar textos de Open Factura en el JavaScript.
- El destino del CNAME. En el DNS de tu dominio se ve el host de respaldo de Open Factura, salvo que uses un subdominio neutro.
- Ingreso con GitHub. No está disponible en los hosts de marca.
Tu subdominio neutro es automático: con la marca activa, tu panel queda en
https://<slug>.<dominio neutro>/app y los enlaces de alta y los correos lo usan. No hace falta
DNS de tu lado. Los remitentes neutros o propios los configuramos nosotros: escríbenos y los
habilitamos.
Qué responde un host de marca
Sección titulada «Qué responde un host de marca»En el dominio de una marca sólo se atiende lo que el panel de un cliente necesita: el panel, el
alta, el inicio de sesión y las rutas de /api/v1 de su negocio (emisor, documentos, clientes,
productos, eventos, catálogos, WhatsApp, correo y certificación), siempre con la sesión del
navegador: una petición con Authorization ahí responde 404. Todo lo demás, incluidos openapi.json,
claves, webhooks, planes, plataforma y ext/marca/plataforma*, responde un 404 No encontrado
neutro. Tus claves de API y tu integración siguen usando app.openfactura.co.
Dentro de ese host sólo entran personas cuyas empresas son todas clientes tuyos. Una cuenta nueva sin empresas queda ligada a la plataforma donde se registró.
En modo marca tu cliente no ve la acción Desconectar: el vínculo lo administras tú desde tu
panel (Clientes → Desactivar). Tu cliente sigue siendo dueño de su cuenta y puede escribirnos.
Si llega al tope de DTE de su plan, el 429 limite_plan le pide contactar a su proveedor (tú).
Plan y vigencia
Sección titulada «Plan y vigencia»La marca blanca es del plan Platform. Si el plan vence, no se borra nada: tu portal en dominio
propio responde «Portal en pausa» de inmediato, y los correos, los PDF y el bot vuelven a la marca
de Open Factura. Al renovar, todo se restaura. GET /api/v1/ext/marca/vigente devuelve la marca que
ve la cuenta de quien llama (o null), con tieneLogo en lugar del logo; la imagen está en
GET /api/v1/ext/marca/vigente/logo (404 si no hay).
El cupo de empresas depende de tu plan (3 en Pro y 25 en Platform, contando la tuya). El
panel de Clientes muestra cuántas usas; al llegar al cupo, crear un cliente responde
429 limite_plan con el limite en details. Si necesitas más, escríbenos para ampliarlo.
Dominio propio
Sección titulada «Dominio propio»Tu portal puede vivir en un subdominio tuyo, por ejemplo facturas.tumarca.com. Sólo subdominios
(no el dominio raíz), hasta 3 por plataforma.
-
Agrégalo. En el panel: Marca → Dirección → Dominio propio. O por API:
Ventana de terminal curl -X POST https://app.openfactura.co/api/v1/ext/marca/plataforma/dominios \-H "Authorization: Bearer $OPENFACTURA_PLATAFORMA" \-H "Content-Type: application/json" \-d '{ "host": "facturas.tumarca.com" }' -
Crea el CNAME en el DNS de tu dominio: el nombre del subdominio apuntando al destino que te muestra el panel (o
destinoenGET …/dominios). -
Agrega los registros TXT que aparezcan (verificación de propiedad y de certificado), si hay. Cada registro del campo
dnstrae su tipo, nombre y valor. -
Espera a que diga «Activo». Puede tardar unos minutos. Para no esperar, pulsa Revisar ahora (
POST …/dominios/:id/revisar). Estados:pendiente,verificando,activo,error.
Cuando está activo, tus enlaces de alta usan ese dominio y tu panel responde en él. Si el plan vence, el dominio deja de servirse hasta que renueves.
Reglas del host:
- Sólo subdominios (
facturas.tumarca.com), con letras ASCII, números y guiones. Sin IDN ni etiquetasxn--, sin puertos, rutas ni comodines; el dominio de nivel superior son sólo letras. No se aceptan dominios de Open Factura ni de servicios comoworkers.dev. - Hasta 3 dominios por plataforma.
- Un dominio que ya reclamó otra plataforma da
409 dominio_en_uso. Si ese reclamo no se activó (pendiente,verificandooerror) y tiene más de 24 h, lo puedes reemplazar con el tuyo (así nadie bloquea un dominio ajeno); unoactivonunca se reemplaza. - Un dominio que no llega a activarse en 7 días (
pendiente,verificandooerror) se elimina; puedes agregarlo de nuevo. - Al eliminar una organización de plataforma sin clientes, sus dominios se quitan también del proveedor de certificados.
Si tu registro usa verificación anti-bots, avísanos para habilitar tu dominio.
Errores: 400 host_invalido, 409 dominio_en_uso, 409 limite_dominios, 429 limite_excedido
(también al borrar o revisar dominios con demasiada frecuencia), 502 cloudflare_no_disponible,
503 dominios_no_disponibles (el servidor aún no los tiene habilitados).
Errores de la marca blanca
Sección titulada «Errores de la marca blanca»| Código | Cuándo |
|---|---|
400 datos_invalidos |
Nombre, slug, color, soporte o logo que no cumplen las reglas. |
400 host_invalido |
El dominio no cumple las reglas del host. |
402 plan_requerido |
La cuenta no tiene el plan Platform o la administra otra plataforma. |
404 |
El dominio o el logo no existen. |
409 slug_en_uso |
Otra plataforma ya usa ese slug. |
409 dominio_en_uso |
El host ya está reclamado (por ti, o por otra plataforma con un reclamo activo o de menos de 24 h). |
409 limite_dominios |
Ya tienes 3 dominios. |
429 limite_excedido |
Demasiados intentos por hora (alta 5, revisar 20, borrar 20). Trae reintentarEn. |
502 cloudflare_no_disponible |
El proveedor de dominios no respondió. |
503 dominios_no_disponibles |
Los dominios propios no están habilitados en el servidor. |
Referencia
Sección titulada «Referencia»Cada endpoint, con sus campos, respuestas y errores, está en la Referencia de Open Factura Cloud. Resumen:
Base: https://app.openfactura.co/cloud/plataforma, con Authorization: Bearer <clave habilitada para Plataforma>. Errores con el formato de siempre.
| Método y ruta | Descripción |
|---|---|
POST /clientes |
Crea un cliente pendiente. Cuerpo: nombre (2–120), externalId? (único en tu cuenta), datos? telefono. 201. |
GET /clientes |
Lista. Filtros: ?estado=pendiente|activo|desactivado, ?externalId=. |
GET /clientes/:id |
Un cliente: estado, preparacion, falta, enlaceExpira, aceptado, organizationId. |
DELETE /clientes/:id |
Pendiente: lo elimina. Activo: lo desactiva (sus datos siguen siendo suyos). |
POST /clientes/:id/enlace |
Enlace de alta. Cuerpo opcional { expiraEnHoras: 1–168 }. Uno nuevo invalida al anterior. 409 cliente_no_pendiente si ya conectó. |
GET /clientes/:id/empresa |
Su empresa ante Hacienda (NIT, NRC, razón social, actividad, ambiente) y qué credenciales cargó. Nunca las credenciales. |
GET /clientes/:id/uso |
DTE de producción del mes (?periodo=AAAA-MM). |
POST /clientes/:id/claves |
Clave en su espacio: nombre, modo (test|live), scopes, expiraEnDias?. 201. |
GET /clientes/:id/claves |
Las claves que creaste para él (sin el secreto). |
DELETE /clientes/:id/claves/:clave |
Revoca una de esas claves. |
POST /clientes/:id/webhooks |
Webhook en su espacio: recibe sólo sus eventos (sin cliente). Cuerpo como POST /api/v1/webhooks. El secreto sólo aparece aquí. 201. |
GET /clientes/:id/webhooks |
Los webhooks que creaste para él. |
DELETE /clientes/:id/webhooks/:webhook |
Borra uno de esos webhooks. |
Errores propios: 402 plan_requerido (Plataforma es de los planes Pro y Platform), 403 clave_sin_plataforma
(la clave no está habilitada), 403 modo_no_permitido, 409 external_id_repetido, 429 limite_plan (empresas del plan).
Esta función es exclusiva de la versión administrada y no forma parte del código abierto.
Para asistentes de IA: llms.txt ·llms-full.txt ·cada página en Markdown añadiendo .md a su ruta.