API Whitelabel: emitir facturas sin enviar correos al cliente

Si estás integrando el API de Factuplan dentro de tu propio producto — un ERP, un POS, una app vertical, un SaaS para un nicho específico — probablemente quieres que la experiencia del cliente final sea 100% tu marca. Sin embargo, por defecto, cuando emites una factura por el endpoint POST /v1/developer/invoices, Factuplan envía un correo automático al cliente con el RIDE adjunto y con su propio logo y branding — tanto en pruebas (ak_test_*) como en producción (ak_live_*).

Si tu integración es whitelabel, ese correo rompe la ilusión. Tu cliente recibe la factura “de Factuplan”, no de tu app. La buena noticia: el API tiene una bandera explícita para apagar ese envío y dejarte a ti el control del correo. Se llama sendEmail y va en el body del request.

El problema: el correo automático no es whitelabel

El Modo A del API (el camino recomendado) hace todo el flujo de un golpe: crea el XML, lo firma con tu certificado P12, lo autoriza ante el SRI, genera el RIDE en PDF y envía el correo al cliente automáticamente.

Ese correo:

• Sale desde un dominio de Factuplan (no del tuyo).
• Trae la plantilla, los colores y el logo de Factuplan.
• Aparece igual en pruebas y en producción — no hay un “modo silencioso” implícito.
• Incluye el RIDE (PDF) y el XML autorizado como adjuntos.

Para un cliente final que está usando tu plataforma “Acme Facturación”, recibir un correo que dice “Factuplan” lo confunde, te pone en una conversación incómoda (“¿y qué es Factuplan?”) y, peor todavía, le entrega a tu cliente un canal directo para descubrir y comparar con tu proveedor de infraestructura. Si vendes whitelabel, eso te puede costar la relación.

La solución: sendEmail: false

El cuerpo del request del endpoint acepta una bandera booleana llamada sendEmail. Por defecto es true. Si la pones en false, Factuplan:

• Sigue creando el XML, firmándolo, autorizándolo ante el SRI y generando el RIDE.
• No envía ningún correo al cliente.
• Te deja a ti el XML y el PDF disponibles para descargar desde los endpoints GET /v1/developer/receipts/{id}/xml y GET /v1/developer/receipts/{id}/pdf.

Es la forma limpia de mantener el flujo automático del SRI sin que tu cliente final vea nada de Factuplan.

Ejemplo mínimo

{
  "customer": {
    "identificationType": "RUC",
    "identification": "0993378150001",
    "legalName": "Empresa Demo S.A.",
    "email": "facturas@empresademo.ec"
  },
  "items": [
    {
      "code": "SERV-001",
      "description": "Servicio de consultoría",
      "quantity": 1,
      "unitPrice": 150.0,
      "taxType": "IVA_RATE",
      "tax": 15
    }
  ],
  "payments": [
    { "method": "20", "amount": 172.5 }
  ],
  "sendEmail": false
}

Fíjate que el campo customer.email puede quedarse — el SRI no lo requiere ni Factuplan tampoco — pero como sendEmail está en false, ese correo nunca se va a usar para notificar. Puedes incluso omitirlo si tu modelo de datos no captura el email del receptor.

Ejemplo completo con cURL

curl https://api.factuplan.com.ec/v1/developer/invoices \
  -X POST \
  -H "X-API-Key: $FACTUPLAN_API_KEY" \
  -H "x-taxpayer-ruc: 0950194407001" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "identificationType": "RUC",
      "identification": "0993378150001",
      "legalName": "Empresa Demo S.A."
    },
    "items": [
      {
        "code": "SERV-001",
        "description": "Servicio de consultoría",
        "quantity": 1,
        "unitPrice": 150.0,
        "taxType": "IVA_RATE",
        "tax": 15
      }
    ],
    "payments": [
      { "method": "20", "amount": 172.5 }
    ],
    "sendEmail": false
  }'

La respuesta es la misma 201 Created que en el flujo normal, con el id del comprobante en estado PROCESSING. Después haces polling a GET /v1/developer/receipts/{id}/status hasta que llegue a AUTHORIZED y descargas tú mismo el RIDE para mandárselo al cliente desde tu propio servicio de correo.

Body completo del endpoint POST /v1/developer/invoices

Para que no tengas que saltar entre pestañas, este es el body completo que acepta el endpoint según la referencia del API. El campo sendEmail está al mismo nivel que customer, items y payments.

{
  "customer": {
    "customerId": "cust_id (opcional)",
    "identificationType": "RUC",
    "identification": "0993378150001",
    "legalName": "Empresa Demo S.A.",
    "email": "facturas@empresademo.ec",
    "address": "Guayaquil, Ecuador",
    "phone": "+593985691039",
    "saveToContacts": true
  },
  "items": [
    {
      "quantity": 1,
      "productId": "prod_id (opcional)",
      "code": "SERV-001",
      "auxiliaryCode": "AUX-001 (opcional)",
      "description": "Servicio de consultoría",
      "unitPrice": 150.0,
      "discount": 0,
      "taxType": "IVA_RATE",
      "tax": 15,
      "saveToProducts": false
    }
  ],
  "emissionPointId": "ep_id (opcional)",
  "establishment": "001 (opcional)",
  "emissionPoint": "001 (opcional)",
  "additionalInfo": { "Vendedor": "Juan Pérez" },
  "sendEmail": true,
  "payments": [
    {
      "method": "20",
      "amount": 172.5,
      "term": 30,
      "timeUnit": "dias"
    }
  ]
}

Campos del customer

Campos de cada item

Campos al nivel raíz

Formas de pago (payments)

Cada entrada lleva el código SRI en method, el amount y, opcionalmente, term + timeUnit. La suma de los amount debe ser exactamente igual al total con impuestos o el SRI rechaza la factura con 400.

Y entonces, ¿cómo le mando el RIDE al cliente?

Una vez que el comprobante pasa a estado AUTHORIZED, descarga el PDF (RIDE) y el XML desde el API y envíalo por tu propio servicio de correo (Resend, Postmark, SES, Mailgun, SendGrid, lo que uses).

1. Espera la autorización

curl https://api.factuplan.com.ec/v1/developer/receipts/$RECEIPT_ID/status \
  -H "X-API-Key: $FACTUPLAN_API_KEY" \
  -H "x-taxpayer-ruc: 0950194407001"

status empieza en PROCESSING y evoluciona a AUTHORIZED → COMPLETED. Si recibes un evento webhook, igual confirma el estado con GET /v1/developer/receipts/{id} antes de disparar el correo.

2. Descarga el RIDE (PDF)

curl https://api.factuplan.com.ec/v1/developer/receipts/$RECEIPT_ID/pdf \
  -H "X-API-Key: $FACTUPLAN_API_KEY" \
  -H "x-taxpayer-ruc: 0950194407001"

Devuelve dos URLs: url (pre-firmada, expira en 5 minutos — ideal para descargarla a tu servidor y adjuntarla al correo) y previewUrl (permanente, ideal para enlazar desde tu panel).

3. Descarga el XML autorizado

curl https://api.factuplan.com.ec/v1/developer/receipts/$RECEIPT_ID/xml \
  -H "X-API-Key: $FACTUPLAN_API_KEY" \
  -H "x-taxpayer-ruc: 0950194407001"

Misma estructura: url pre-firmada de 5 minutos + previewUrl permanente. Adjunta ambos al correo que envías desde tu dominio.

4. Manda el correo desde tu marca

Plantilla HTML con tu logo, tu dominio (facturas@tu-app.com), tu tono, tus enlaces. El cliente final recibe un solo correo y la marca es 100% la tuya. Factuplan queda invisible — exactamente lo que pide un contrato whitelabel.

¿Pruebas o producción? El logo aparece en ambos

Algo que confunde a los integradores nuevos: el correo con logo de Factuplan se manda igual en pruebas que en producción. No hay un “modo silencioso” automático para ak_test_*. Si emites con una API key de pruebas y sendEmail: true, tu cliente de pruebas (o tú mismo en QA) recibe el correo branded de Factuplan.

Por eso, si estás construyendo una integración whitelabel, lo más sano es dejar sendEmail: false desde el primer día, incluso en desarrollo. Así:

• Tu QA ve el flujo exacto que va a ver el cliente en producción.
• Nunca te queda un sendEmail: true “olvidado” cuando promoves a prod.
• Tus pruebas con correos reales pasan por tu propio servicio de correo y descubres ahí los problemas de entregabilidad.

Casos donde sí conviene dejar sendEmail: true

No siempre el envío automático es un problema. Si tu integración:

• Es interna (un ERP de tu empresa) y los receptores ya saben qué es Factuplan.
• Es un MVP y aún no tienes infraestructura de correo propia.
• Apunta a un cliente que prefiere usar el correo tal cual viene, sin personalizar.

…entonces deja sendEmail: true (o sencillamente omite el campo) y deja que Factuplan haga el envío. El esfuerzo de armar plantillas, manejar bounces, autenticar SPF/DKIM y monitorear deliverability no es trivial — si no lo necesitas para diferenciarte, no lo construyas todavía.

La pregunta clave para decidir: ¿el cliente final sabe que existe Factuplan, o crees que sería mejor que no lo supiera? Si la respuesta es la segunda, sendEmail: false es obligatorio.

Otros endpoints relacionados al flujo whitelabel

Si la idea es esconder a Factuplan, conviene revisar también:

• GET /v1/developer/receipts/{id}/pdf — descarga el RIDE para adjuntarlo a tu correo.
• GET /v1/developer/receipts/{id}/xml — descarga el XML autorizado.
• GET /v1/developer/verify/{accessKey} — para verificar contra el SRI sin pasar por la UI de Factuplan.
• POST /v1/developer/sign (Modo C) — si quieres todavía más control: tú generas el XML, Factuplan solo te lo firma y tú te encargas de mandarlo al SRI por tu cuenta. Modo más complejo pero el más whitelabel posible.

Para un comparativo de qué tan flexible es el API de Factuplan frente a otros proveedores ecuatorianos, revisa Factuplan vs Dátil y la lista de los 10 mejores facturadores electrónicos de Ecuador.

Checklist rápido para una integración whitelabel limpia

1. sendEmail: false en cada llamada a POST /v1/developer/invoices.
2. Tu propio servicio de correo configurado (SPF, DKIM, DMARC, dominio dedicado).
3. Plantilla HTML del correo con tu logo y tus enlaces — sin mencionar Factuplan.
4. Webhook o polling a GET /v1/developer/receipts/{id}/status para saber cuándo está AUTHORIZED.
5. Adjuntar siempre el PDF (RIDE) y el XML autorizado al correo. El XML lo necesita el contador del receptor.
6. Plantilla con el botón “Verificar en el SRI” enlazando al portal oficial — refuerza la legitimidad sin depender de Factuplan.
7. Si tu cliente exige también ocultar Factuplan del PDF, abre conversación con el equipo de Factuplan para revisar plantillas personalizadas del RIDE.

¿Estás integrando el API y tienes una duda específica de implementación? Escríbenos a info@factuplan.com.ec o revisa la documentación completa del API REST. Si trabajas en Node.js o TypeScript, también está el SDK oficial que te ahorra cabecear con cURL.