API de facturación electrónica DIAN para tu ERP, tu POS o tu propio software
Envía un JSON y recibe la factura validada por la DIAN con CUFE, PDF y XML. Clientes, notas, documento soporte, nómina, eventos RADIAN, links de cobro y webhooks firmados, todo bajo el NIT de tu empresa, con sandbox gratis y documentación completa en español.
Una factura en una llamada
Con la llave API de tu instancia, un POST crea la factura, la firma con tu certificado y la transmite a la DIAN. Si el cliente ya existe, basta su NIT.
curl -sS -X POST https://<tu-nit>.miplata.co/api/external/invoices \
-H "X-API-Key: TU_LLAVE" -H "Content-Type: application/json" \
-d '{
"customer_nit": "900123456",
"customer_name": "Cliente Ejemplo S.A.S.",
"customer_email": "facturas@cliente.co",
"payment_means_code": "47",
"items": [
{ "description": "Servicio de consultoría", "quantity": 1, "unit_price": 1000000, "tax_percent": 19 }
]
}'
# → 201 { "id": "3f2b8c1e-7a4d-4b9e-9c61-2d5f0a8e4b17", "invoice_number": "FE1234", "cufe": "…", "dian_status": "SENT", "qr_code": "https://catalogo-vpfe.dian.gov.co/…", … }
# dian_status SENT o ya ACCEPTED (QUEUED si la DIAN no responde: miPlata reintenta sola);
# en segundos el webhook invoice.accepted (o GET /invoices/{id} con dian_status ACCEPTED)Qué puedes construir con la API, en una mirada
Seis familias de recursos, un mismo JSON y una misma llave. Cada fila es un caso real que ya corre en producción.
| Quieres… | Llamada | Lo que recibes | Aviso (webhook) |
|---|---|---|---|
| Facturar una venta desde tu sistema | POST /invoices | Factura validada por la DIAN: número, CUFE, PDF y XML | invoice.accepted / invoice.rejected |
| Facturar a un cliente en el exterior | POST /invoices con currency: "USD" (o EUR, GBP…) | Factura de exportación (02) sin IVA, con la TRM del día | invoice.accepted |
| Cobrar una factura o una cotización | POST /invoices/{id}/pay-link | URL de pago (Bre-B, Nequi, Daviplata o PayPal) y QR | invoice.paid |
| Vender desde tu web: cobrar y facturar al pagar | POST /payments/checkouts (pay_and_invoice) | URL de cobro con reserva; factura automática al confirmarse | checkout.paid → checkout.invoiced |
| Registrar un pago en efectivo o transferencia | POST /invoices/{id}/payments | Recibo con referencia única; saldo actualizado | — |
| Anular o ajustar una factura aceptada | POST /invoices con invoice_type 91 / 92 | Nota crédito o débito referenciada al CUFE | credit_note.accepted / debit_note.accepted |
| Corregir una factura rechazada | PUT /invoices/{id} con finalize y send_to_dian | Mismo número, nuevo CUFE, reenvío en la misma llamada | invoice.corrected → invoice.accepted |
| Emitir 500 facturas de un archivo | POST /invoices/bulk | Lote con estado por documento | invoice.* por cada una |
| Comprar a un no obligado a facturar | POST /soporte | Documento soporte (05) validado | invoice.accepted |
| Pagar nómina | POST /payroll | Documento de nómina (102) con CUNE y PDF | invoice.accepted |
| Acusar, aceptar o reclamar una factura recibida | POST /events | Evento RADIAN firmado con tu certificado | — |
| Saber si la DIAN está caída | GET /invoices/{id} o webhook | Estado QUEUED y reintento automático 48 h | invoice.pending_dian → invoice.accepted |
| Dar acceso a un integrador sin tu llave raíz | POST /tokens | Token personal con alcance y vencimiento | — |
Tres flujos que resuelven el 90 % de las integraciones
ERP o contable → DIAN
Tu sistema crea el cliente por NIT (PUT /customers/by-nit), envía la factura (POST /invoices) y guarda el CUFE y el PDF que vuelven en la respuesta o por webhook. Las notas crédito referencian el id (un UUID) y avisan con credit_note.*. Un rechazo se corrige con PUT /invoices/{id}. Idempotency-Key evita duplicados ante un reintento.
Web o app → cobro → factura
Reservas la entrada, el cupo o el producto; creas un checkout pay_and_invoice con la reserva como order_reference; rediriges al comprador; al pagar, miPlata factura y te avisa con checkout.invoiced. Si cancela, DELETE y nota crédito automática si ya había factura.
Marketplace o SaaS → tus clientes
Cada cliente tuyo es una instancia con su NIT, su numeración y su certificado. Tu plataforma integra una vez contra la misma API y pide una llave por cliente. La DIAN ve a cada empresa, no a tu plataforma.
Todo el ciclo del documento, no solo la emisión
Documentos
Factura de venta (01), exportación (02), notas crédito y débito (91/92), documento soporte (05) y su nota de ajuste (95), cotizaciones, emisión masiva por lotes y contingencia tipo 04.
Nómina electrónica
Crear, firmar y transmitir documentos de nómina (102) y ajustes (103), consultar estado y PDF.
Clientes y catálogos
Clientes por NIT con validación del dígito de verificación, departamentos y municipios DANE, tipos de documento, medios de pago.
Cobros
Link de pago por factura con Bre-B, Nequi, Daviplata o PayPal; registro de pagos recibidos fuera de la pasarela; checkouts para tiendas con factura automática al pagar.
Recepción y RADIAN
Eventos de acuse, recibo, aceptación y reclamo sobre facturas de compra identificadas por CUFE.
Webhooks y tokens
Eventos invoice.accepted, invoice.rejected, invoice.paid, credit_note.accepted, checkout.paid, checkout.invoiced y más, firmados con HMAC-SHA256 (X-MiPlata-Signature); tokens personales por integración sin compartir la llave raíz.
API bajo tu propio NIT, no bajo el de un proveedor
Con un proveedor tecnológico, la API transmite a la DIAN bajo el Software ID del proveedor. Con miPlata, tu instancia transmite con tu Software ID y tu certificado: en la DIAN el facturador y el software son tu empresa.
Sandbox y producción
Un solo interruptor en Configuración → Entorno cambia toda la instancia: la DIAN de habilitación y los cobros de prueba. Misma llave, mismas rutas. El sandbox no consume cupo.
Cupo y precio
El plan incluye 1.000 documentos incluidos (12 meses) o 250 documentos incluidos (3 meses). 1 envío a la DIAN en producción = 1 documento; un reintento por caída de la DIAN no cuenta. Recargas de 2.000, 12.500 o 27.000 documentos.
Documentación
Referencia completa en /api-docs, también en texto plano (/api-docs.md), JSON y colección Postman. Ejemplos en curl para cada caso: nacional, extranjero, consumidor final, exportación.
Si vendes en una tienda online, no necesitas la API
Tiendanube y WooCommerce ya tienen conector (Mercado Libre, próximamente): cada pedido pagado se factura solo y cada devolución genera su nota crédito.
Lo que nos preguntan
¿Necesito ser proveedor tecnológico para usar la API?
No. Tu empresa se habilita ante la DIAN con software propio a nombre de su NIT; la API es la de tu propia instancia. No hay un tercero intermedio ni un registro adicional ante la DIAN.
¿La API tiene costo?
Está incluida en el plan con un cupo de documentos: 1.000 documentos incluidos en el Plan 12 Meses y 250 documentos incluidos en el Plan 3 Meses. Sin cargo por llamada. Cuando se agota, compras una recarga (2.000, 12.500 o 27.000 documentos).
¿Hay sandbox?
Sí, gratis e ilimitado. En modo Sandbox la instancia transmite a la DIAN de habilitación (sin validez fiscal) y los cobros usan pasarelas de prueba. Misma llave y mismas rutas que producción.
¿En qué lenguaje están los ejemplos?
curl y JSON en la documentación, utilizable desde cualquier lenguaje. Hay colección Postman y una versión en texto plano pensada para asistentes de código.
¿Cómo me entero de que la DIAN aceptó o rechazó?
Por webhook firmado (invoice.accepted, invoice.rejected, invoice.pending_dian, invoice.contingency_04; las notas crédito con credit_note.*) o consultando GET /invoices/{id}. Los rechazos vienen con el código de regla de la DIAN y su explicación; se corrigen con PUT /invoices/{id} (mismo número, nuevo CUFE).
¿Puedo cobrar la factura desde la API?
Sí. POST /invoices/{id}/pay-link genera un link de pago (Bre-B, Nequi, Daviplata o PayPal); cuando el cliente paga, miPlata deja la factura pagada sola y el webhook invoice.paid te avisa (checkout.paid es solo para los checkouts de POST /payments/checkouts).
Conecta tu sistema a la DIAN en una tarde
Sandbox gratis, documentación en español y soporte por correo. Si prefieres que lo hagamos nosotros, hay paquetes de integración con precio fijo.
Ver la documentación