¿Necesito un certificado digital para facturar electrónicamente?

Sí, cada empresa necesita su certificado digital (.p12). MercaloAPI se encarga de firmar automáticamente.

¿Puedo probar la API de facturación antes de pagar?

Sí, todas las cuentas incluyen sandbox y 20 documentos de prueba gratis sin tarjeta de crédito.

¿Cuánto tiempo toma integrar facturación electrónica DIAN?

Con MercaloAPI, la mayoría de desarrolladores integran en 1-3 días gracias a la API REST y SDKs disponibles.

Facturas Electrónicas

Crea, consulta, lista y anula facturas de venta electrónicas validadas ante la DIAN.

POST/v1/invoices

Crea una nueva factura electrónica y la envía a la DIAN para validación.

Campo	Tipo	Req.	Descripción
`companyId`	string	✅	UUID de la empresa emisora
`customer`	object	✅	Datos del adquiriente (NIT, nombre, dirección)
`items`	array	✅	Líneas de la factura con descripción, cantidad, precio e IVA
`notes`	string	—	Notas u observaciones de la factura
`paymentMethod`	string	—	Método de pago (contado, credito)
`dueDate`	string	—	Fecha de vencimiento ISO 8601

curl -X POST https://api.mercalo.co/v1/invoices \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "uuid-empresa",
    "customer": {
      "nit": "901234567",
      "name": "Cliente Ejemplo SAS",
      "email": "cliente@ejemplo.com"
    },
    "items": [{
      "description": "Servicio de desarrollo",
      "quantity": 1,
      "unitPrice": 1500000,
      "taxRate": 19
    }]
  }'

Response (200 OK)

{
  "id": "inv_abc123",
  "cufe": "a1b2c3d4e5f6...",
  "status": "ACCEPTED",
  "total": 1785000,
  "tax": 285000,
  "pdfUrl": "https://api.mercalo.co/v1/invoices/inv_abc123/pdf",
  "xmlUrl": "https://api.mercalo.co/v1/invoices/inv_abc123/xml",
  "createdAt": "2026-03-12T10:30:00Z"
}

GET/v1/invoices/:id

Consulta el detalle y estado de una factura específica.

curl https://api.mercalo.co/v1/invoices/inv_abc123 \
  -H "Authorization: Bearer sk_live_xxx"

Response (200 OK)

{
  "id": "inv_abc123",
  "cufe": "a1b2c3d4...",
  "status": "ACCEPTED",
  "total": 1785000,
  "createdAt": "2026-03-12T10:30:00Z"
}

GET/v1/invoices

Lista las facturas de una empresa con paginación y filtros.

Campo	Tipo	Req.	Descripción
`companyId`	string	✅	UUID de la empresa
`page`	number	—	Número de página (default: 1)
`limit`	number	—	Resultados por página (max: 100)
`status`	string	—	Filtrar por estado (ACCEPTED, REJECTED)

curl "https://api.mercalo.co/v1/invoices?companyId=xxx&page=1&limit=20" \
  -H "Authorization: Bearer sk_live_xxx"

POST/v1/invoices/:id/void

Anula una factura emitida. Requiere nota crédito asociada según normativa DIAN.

curl -X POST https://api.mercalo.co/v1/invoices/inv_abc123/void \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Error en datos del cliente" }'

Errores comunes

Código	Descripción	Solución
`400`	NIT inválido	Verificar dígito de verificación
`401`	API key inválida	Regenerar key en Dashboard
`422`	Certificado vencido	Renovar certificado digital
`422`	Items vacíos	Incluir al menos un item

Autenticación Notas Crédito