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. Sin tarjeta de crédito. El plan Free incluye 100 documentos y sandbox incluido para que pruebes la integración sin certificado digital real.

# 1. Regístrate en mercaloapi.com/registro
# 2. Inicia sesión y registra tu empresa desde Dashboard → Empresas
# 3. Genera tu API key en Dashboard → API Keys
#    (marca "Crear como key de sandbox" para probar sin certificado .p12 real)
# 4. Cópiala — si la pierdes, puedes volver a revelarla después desde el Dashboard

export MERCALO_KEY="mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
2

Registra tu empresa

Antes de poder facturar necesitas al menos una empresa (NIT, régimen tributario, responsabilidad fiscal y municipio). Lo más simple es llenar el formulario en Dashboard → Empresas, que te muestra los catálogos para elegir. También puedes hacerlo por API usando el token de tu sesión del dashboard (no tu API key — este endpoint es de gestión, no de facturación):

curl -X POST https://mercaloapi-back-production.up.railway.app/api/v1/config/companies \
  -H "Authorization: Bearer $DASHBOARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nit": "901234567",
    "dv": "4",
    "businessName": "Mi Empresa SAS",
    "typeOrganizationId": 1,
    "typeRegimeId": 1,
    "typeLiabilityId": 1,
    "municipalityId": 1,
    "address": "Calle 123 #45-67"
  }'
3

Obtén tu API Key

Ve a Dashboard → API Keys y genera tu primera clave para esa empresa — marca "Crear como key de sandbox" si quieres probar sin certificado .p12 real (los documentos quedan simulados, no se envían a la DIAN ni consumen créditos). Cópiala de inmediato; si la pierdes, puedes volver a revelarla después desde el mismo Dashboard. Una vez tu empresa pase de Habilitación a Producción, esa misma key sigue funcionando — no hace falta generar una nueva.

4

Emite tu primera factura

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

curl -X POST https://mercaloapi-back-production.up.railway.app/api/v1/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 incluye el CUFE y el estado real de la DIAN (dianStatus: ACCEPTED, REJECTED o CONTINGENCY si la DIAN estaba caída). Guarda el documentId — lo necesitas para descargar el PDF y el XML firmado, que no vienen incluidos en esta respuesta.

{
  "documentId": "b3d7f1a2-4c5e-6f7a-8b9c-0d1e2f3a4b5c",
  "number": "SETP990000045",
  "cufe": "a1b2c3d4e5f6...",
  "trackId": "abc-track-id",
  "dianStatus": "ACCEPTED",
  "dianResponse": { "...": "respuesta cruda de la DIAN" }
}

Descarga el PDF y el XML por separado con ese documentId:

# PDF
curl https://mercaloapi-back-production.up.railway.app/api/v1/documents/uuid-empresa/b3d7f1a2-4c5e-6f7a-8b9c-0d1e2f3a4b5c/pdf \
  -H "Authorization: Bearer $MERCALO_KEY" -o factura.pdf

# XML firmado
curl https://mercaloapi-back-production.up.railway.app/api/v1/documents/uuid-empresa/b3d7f1a2-4c5e-6f7a-8b9c-0d1e2f3a4b5c/xml \
  -H "Authorization: Bearer $MERCALO_KEY" -o factura.xml

Siguiente paso

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

Configurar webhooks