Guía de Inicio Rápido

Emite tu primera factura electrónica en menos de 5 minutos.

1

Crea tu cuenta

Regístrate gratis en mercaloapi.com/registro. El plan Free incluye 100 documentos para que pruebes la integración.

# 1. Regístrate en mercaloapi.com/registro
# 2. Ve a Dashboard → API Keys
# 3. Genera tu API key y cópiala — solo se muestra una vez

export MERCALO_KEY="mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
2

Obtén tu API Key

Ve a Dashboard → API Keys y genera tu primera clave — el valor solo se muestra una vez, así que cópialo de inmediato. Mientras tu empresa esté en ambiente de Habilitación, esa misma key llega al set de pruebas de la DIAN, no a producción.

3

Registra una empresa

Registra tu empresa con su NIT y certificado digital .p12.

curl -X POST https://api.mercalo.co/config/companies \
  -H "Authorization: Bearer $MERCALO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nit": "901234567",
    "businessName": "Mi Empresa SAS",
    ...
  }'
4

Emite tu primera factura

Envía una solicitud POST con los datos del cliente y los items.

curl -X POST https://api.mercalo.co/invoice/uuid-empresa \
  -H "Authorization: Bearer $MERCALO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "nit": "800123456",
      "businessName": "Cliente Ejemplo"
    },
    "lines": [{
      "description": "Servicio de software",
      "quantity": 1,
      "priceAmount": 100000
    }]
  }'

Verifica el resultado

La respuesta incluirá el CUFE, el estado de la DIAN, y URLs para PDF y XML firmado.

{
  "id": "inv_abc123",
  "cufe": "a1b2c3d4e5f6...",
  "status": "ACCEPTED",
  "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"
}

Siguiente paso

Configura webhooks para recibir notificaciones cuando la DIAN apruebe o rechace un documento.

Configurar webhooks