Plataforma — onboard your customers
With Plataforma you build e-invoicing into each of your customers’ systems (their ERP, their point of sale, their store) and manage it all from one place.
You (developer) └─ Customer: Casa Barista ← their own isolated space ├─ Their company and MH credentials ├─ Their branches and points of sale ├─ Their documents, recipients, and products └─ Their API keys ← your system issues on their behalf with them └─ Customer: Ferretería El Clavo ← another space, isolated tooIsolation. Each customer is its own organization: its control numbers, its documents, and its (encrypted) credentials belong to it alone. A customer’s key sees nothing of yours or of your other customers, and your keys don’t issue on anyone’s behalf. Your customer can disconnect whenever they want: their data remains theirs.
The full flow
Section titled “The full flow”-
Enable one of your keys for Plataforma. In the dashboard: Clients → API access. Only the keys you enable there can manage customers. API base:
https://app.openfactura.co/cloud/plataforma. -
Create the customer. What you already know about them arrives prefilled in their onboarding.
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]" }}'Their space exists from that moment (
organizationId): you can configure it before the customer arrives (from the dashboard, Customers → the customer → Their account) and create their keys and webhooks. In production, it issues once the customer activates their account. -
Send them their onboarding link. Single use; it expires in 72 h (1 to 168 with
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… }With the link, your customer creates their user and activates their account: they become the owner, review what you configured, and complete whatever is missing (their Hacienda credentials, if you didn’t upload them). If they already use Open Factura with their company, they can connect that one instead. If we ask them to confirm their email when creating their user, the email link brings them back to their onboarding page to finish.
-
Find out when they’re ready. Subscribe a webhook to
cliente.listo: it arrives once when the customer can issue in test and again when they can in production, at any subscribed webhook (created with a test key, a production key, or in the dashboard). With the CLI:openfactura webhooks add <url> --eventos cliente.listo. You can also queryGET /clientes/:id:preparacion(conectado,pruebas,produccion) andfalta(what is still missing). -
Create their API key. It works only in their space. Store it in your customer’s system.
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_…" } (shown this one time only) -
Issue from your customer’s system with the usual API and their key. Open Factura validates the document, signs it, transmits it to Hacienda, and returns the stamp, the PDF, and the JSON. In production, if the recipient has an email address, they receive it with the PDF (with your customer’s logo) and the official JSON: see Branding and email.
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": { … } }'
Branches
Section titled “Branches”Each customer registers its establishments and points of sale (/api/v1/establecimientos,
/api/v1/puntos-venta, with its key). Each document states who issues it with puntoVentaId, and
each point of sale keeps its own numbering. A customer with three stores issues from all three with a
single integration.
Multi-tenant webhooks
Section titled “Multi-tenant webhooks”Your webhooks also receive the events of all your customers (dte.procesado, dte.rechazado,
dte.contingencia, dte.invalidado…) with cliente in datos so you know whose it is. Your
customer still receives their own, without cliente. Like any webhook, one created with a test key
only receives test events (Environments).
Should a customer’s system receive only its own events? Create the webhook in their space:
POST /clientes/:id/webhooks (or in the dashboard, New webhook → For whom?). That webhook isn’t
tied to an environment (ambiente: null): it receives your customer’s test and production events,
even if you create it with a test key. Use the body’s ambiente to tell them apart.
{ "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 carries { id, externalId, nombre, organizationId, preparacion }.
With your AI agent (MCP)
Section titled “With your AI agent (MCP)”With a key enabled for Plataforma, the MCP adds these tools:
| Tool | What it does |
|---|---|
plataforma_clientes_listar |
Your customers, their status, and what’s missing |
plataforma_cliente_crear |
Adds a customer (with prefilled data) |
plataforma_cliente_enlace |
Their onboarding link |
plataforma_cliente_clave_crear |
An API key in their space |
“Add Casa Barista, NIT 0614-290786-102-3, and give me their onboarding link.”
White label
Section titled “White label”With the Platform plan your customers see your brand, not Open Factura’s. You choose the name, logo and color. Below is exactly what carries your brand and what doesn’t.
Set it up in the dashboard (Marca → White label for your customers) or through the API
(/api/v1/ext/marca/plataforma*, with emisor:write; reading needs 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": "Your Brand", "color": "#3b82f6", "correoSoporte": "[email protected]", "activa": true }'| Field | Rules |
|---|---|
nombre |
2 to 40 characters, Latin letters, numbers and . , ' & ( ) + ! ? - only, no links. Imitations of Open Factura or Hacienda are rejected (letters from other alphabets, digits for letters, separators). |
slug |
Lowercase letters, numbers and hyphens (3 to 32). Some are reserved. Unique: 409 slug_en_uso if another platform has it. |
color |
#rrggbb, with enough contrast on a dark background. |
| Logo | PUT /plataforma/logo with { "base64": "…" }: PNG or JPG, up to 200 KB and 2000 px. No SVG. |
| Support | correoSoporte and whatsappSoporte: email and phone only. |
What your customer sees
Section titled “What your customer sees”Carries your brand:
- Onboarding. The onboarding link carries your logo, name and color, with no mention of Open Factura.
- Dashboard. On your domain the dashboard shows your name, logo, color, title and favicon, and only their business features (issuer, documents, customers, products, WhatsApp). No plans, API keys, webhooks or developer tools.
- Emails. Account emails (confirm email, reset password) and document emails go out under your name and support.
- PDFs. The PDF carries your customer’s logo and, in its metadata, your name as producer.
- WhatsApp bot. The bot’s text speaks under your name and support.
Doesn’t (yet):
- The WhatsApp number. It is shared: the profile name still says Open Factura and the
wa.melink uses that number. A dedicated number per platform will come later. - The email sender address, unless you have a neutral sender or your own sending domain. Otherwise the display name is yours but the address keeps Open Factura’s domain.
- The dashboard code. Anyone reading the page source (view-source) can find Open Factura strings in the JavaScript.
- The CNAME target. Your domain’s DNS shows Open Factura’s fallback host, unless you use a neutral subdomain.
- GitHub sign-in. It is disabled on brand hosts.
Neutral or own senders and neutral subdomains are set up by us: write to us and we enable them. They are not self-serve yet.
What a brand host answers
Section titled “What a brand host answers”On a brand’s domain only what a customer’s dashboard needs is served: the dashboard, onboarding,
sign-in and the /api/v1 routes of their business (issuer, documents, customers, products, events,
catalogs, WhatsApp, email and certification), always with the browser session: a request carrying
Authorization there gets 404. Everything else, including openapi.json, keys, webhooks, plans,
plataforma and ext/marca/plataforma*, gets a neutral 404 No encontrado. Your API keys and
integration keep using app.openfactura.co.
Only people whose companies are all your customers can sign in on that host. A new account with no companies is tied to the platform where it signed up.
In brand mode your customer doesn’t see the Disconnect action: you manage the link from your
dashboard (Clients → Deactivate). Your customer still owns their account and can write to us.
If they reach their plan’s DTE cap, the 429 limite_plan tells them to contact their provider (you).
Plan and lapse
Section titled “Plan and lapse”White label belongs to the Platform plan. If the plan lapses, nothing is deleted: your portal on
a custom domain answers “Portal en pausa” right away, and emails, PDFs and the bot go back to Open
Factura’s brand. When you renew, everything is restored. GET /api/v1/ext/marca/vigente returns
the brand the caller’s account sees (or null), with tieneLogo instead of the logo; the image is
at GET /api/v1/ext/marca/vigente/logo (404 if none).
The company cap depends on your plan (3 on Pro and 25 on Platform, counting your own). The
Clients dashboard shows how many you use; at the cap, creating a client answers
429 limite_plan with the limite in details. If you need more, write to us to raise it.
Custom domain
Section titled “Custom domain”Your portal can live on a subdomain of yours, such as facturas.yourbrand.com. Subdomains only (not
the root domain), up to 3 per platform.
-
Add it. In the dashboard: Marca → Dirección → Dominio propio. Or through the 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.yourbrand.com" }' -
Create the CNAME in your domain’s DNS: the subdomain name pointing to the target the dashboard shows (or
destinoinGET …/dominios). -
Add any TXT records shown (ownership and certificate verification). Each entry in
dnscarries its type, name and value. -
Wait for “Activo”. It can take a few minutes. To skip the wait, press Revisar ahora (
POST …/dominios/:id/revisar). States:pendiente,verificando,activo,error.
Once active, your onboarding links use that domain and your dashboard answers on it. If the plan lapses, the domain stops being served until you renew.
Host rules:
- Subdomains only (
facturas.yourbrand.com), with ASCII letters, numbers and hyphens. No IDN orxn--labels, no ports, paths or wildcards; the top-level domain is letters only. Open Factura domains and services such asworkers.devare not accepted. - Up to 3 domains per platform.
- A domain already claimed by another platform gives
409 dominio_en_uso. If that claim never activated (pendiente,verificandoorerror) and is older than 24 h, you can replace it with yours (so nobody can block a domain that isn’t theirs); anactivoone is never replaced. - A domain that doesn’t become active within 7 days (
pendiente,verificandoorerror) is removed; you can add it again. - Deleting a platform organization that has no customers also removes its domains from the certificate provider.
If your sign-up uses anti-bot verification, let us know so we can enable your domain.
Errors: 400 host_invalido, 409 dominio_en_uso, 409 limite_dominios, 429 limite_excedido
(also when deleting or rechecking domains too often), 502 cloudflare_no_disponible,
503 dominios_no_disponibles (the server doesn’t have them enabled yet).
White label errors
Section titled “White label errors”| Code | When |
|---|---|
400 invalid (invalid data) |
A name, slug, color, support field or logo that breaks the rules. |
400 host_invalido |
The domain breaks the host rules. |
402 plan_requerido |
The account isn’t on the Platform plan or is managed by another platform. |
404 |
The domain or the logo doesn’t exist. |
409 slug_en_uso |
Another platform already uses that slug. |
409 dominio_en_uso |
The host is already claimed (by you, or by another platform with an active or under-24 h claim). |
409 limite_dominios |
You already have 3 domains. |
429 limite_excedido |
Too many attempts per hour (add 5, recheck 20, delete 20). Includes reintentarEn. |
502 cloudflare_no_disponible |
The domain provider didn’t respond. |
503 dominios_no_disponibles |
Custom domains aren’t enabled on the server. |
Reference
Section titled “Reference”Every endpoint, with its fields, responses, and errors, is in the Open Factura Cloud reference (in Spanish). Summary:
Base: https://app.openfactura.co/cloud/plataforma, with Authorization: Bearer <key enabled for Plataforma>. Errors use the usual format.
| Method and route | Description |
|---|---|
POST /clientes |
Creates a pending customer. Body: nombre (2–120), externalId? (unique in your account), datos? telefono. 201. |
GET /clientes |
Lists. Filters: ?estado=pendiente|activo|desactivado, ?externalId=. |
GET /clientes/:id |
One customer: estado, preparacion, falta, enlaceExpira, aceptado, organizationId. |
DELETE /clientes/:id |
Pending: deletes it. Active: deactivates it (their data remains theirs). |
POST /clientes/:id/enlace |
Onboarding link. Optional body { expiraEnHoras: 1–168 }. A new one invalidates the previous one. 409 cliente_no_pendiente if they already connected. |
GET /clientes/:id/empresa |
Their company as registered with Hacienda (NIT, NRC, legal name, activity, environment) and which credentials they uploaded. Never the credentials. |
GET /clientes/:id/uso |
Production DTEs for the month (?periodo=AAAA-MM, i.e. YYYY-MM). |
POST /clientes/:id/claves |
Key in their space: nombre, modo (test|live), scopes, expiraEnDias?. 201. |
GET /clientes/:id/claves |
The keys you created for them (without the secret). |
DELETE /clientes/:id/claves/:clave |
Revokes one of those keys. |
POST /clientes/:id/webhooks |
Webhook in their space: receives only their events (without cliente). Body as in POST /api/v1/webhooks. The secret only appears here. 201. |
GET /clientes/:id/webhooks |
The webhooks you created for them. |
DELETE /clientes/:id/webhooks/:webhook |
Deletes one of those webhooks. |
Specific errors: 402 plan_requerido (Plataforma belongs to the Pro and Platform plans), 403 clave_sin_plataforma (the key isn’t enabled), 403 modo_no_permitido, 409 external_id_repetido,
429 limite_plan (the plan’s company limit).
This feature is exclusive to the managed version and is not part of the open-source code.
For AI assistants: llms.txt ·llms-full.txt ·every page as Markdown by adding .md to its path.