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. Recibirás automáticamente acceso al sandbox con 20 documentos de prueba.

# 1. Regístrate en mercaloapi.com/registro
# 2. Ve a Dashboard → API Keys
# 3. Copia tu API key de sandbox

export MERCALO_KEY="sk_test_xxxxxxxxxxxx"
2

Obtén tu API Key

Ve a Dashboard → API Keys y genera tu primera clave. Las claves de sandbox tienen el prefijo sk_test_.

3

Registra una empresa

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

curl -X POST https://api.mercalo.co/v1/companies \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "nit": "901234567",
    "name": "Mi Empresa SAS",
    "certificate": "<base64 del .p12>",
    "certificatePassword": "mi-password"
  }'
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/v1/invoices \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "uuid-empresa",
    "customer": {
      "nit": "800123456",
      "name": "Cliente Ejemplo"
    },
    "items": [{
      "description": "Servicio de software",
      "quantity": 1,
      "unitPrice": 100000,
      "taxRate": 19
    }]
  }'

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