Ir al contenido

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 aislamiento

Aislamiento. 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.

  1. 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.

  2. 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.

  3. 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.

  4. 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 consultar GET /clientes/:id: preparacion (conectado, pruebas, produccion) y falta (lo que le falta).

  5. 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)
  6. 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": { … } }'

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.

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 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.»

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):

Ventana de terminal
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.

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.me lleva 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.

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ú).

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.

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.

  1. 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" }'
  2. Crea el CNAME en el DNS de tu dominio: el nombre del subdominio apuntando al destino que te muestra el panel (o destino en GET …/dominios).

  3. Agrega los registros TXT que aparezcan (verificación de propiedad y de certificado), si hay. Cada registro del campo dns trae su tipo, nombre y valor.

  4. 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 etiquetas xn--, sin puertos, rutas ni comodines; el dominio de nivel superior son sólo letras. No se aceptan dominios de Open Factura ni de servicios como workers.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, verificando o error) y tiene más de 24 h, lo puedes reemplazar con el tuyo (así nadie bloquea un dominio ajeno); uno activo nunca se reemplaza.
  • Un dominio que no llega a activarse en 7 días (pendiente, verificando o error) 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).

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.

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.