Documentación de la API de Nubicta

URL base

Todas las respuestas son JSON en UTF-8. Las fechas usan el formato AAAA-MM-DD y los valores son números con decimales.

Autenticación

1. En Nubicta entra a Configuración > Credenciales de integración a plataformas digitales (API).
2. Activa Habilitar API, elige los permisos (Solo lectura o Lectura y escritura) y, si quieres, las IPs permitidas separadas por coma.
3. Pulsa Generar nueva llave. La llave se muestra una sola vez: guárdala en un lugar seguro. Al generar otra, la anterior deja de funcionar.

Envía la llave en la cabecera Authorization de cada petición:

Authorization: Bearer TU_LLAVE
Accept: application/json

• Nubicta guarda solo la huella SHA-256 de la llave, nunca la llave en claro.
• Con Solo lectura solo funcionan las peticiones GET.
• Si llenas las IPs permitidas, cualquier otra IP recibe un error 403.
• Límite: 120 peticiones por minuto por llave. Si lo superas recibes un error 429.

Paginación

Los listados devuelven 50 registros por página. Puedes cambiarlo con por_pagina (de 1 a 100) y moverte con page.

{
  "data": [ ... ],
  "pagina": 1,
  "por_pagina": 50,
  "total": 134,
  "paginas": 3
}

Errores

{ "message": "Llave de acceso inválida o revocada." }

Endpoints

GET/terceros

Lista clientes, proveedores y empleados de la empresa, ordenados por nombre.

curl -H "Authorization: Bearer TU_LLAVE" \
  "https://nube.nubicta.online/api/v1/terceros?tipo=cliente&q=ejemplo"

Cada tercero tiene esta forma:

{
  "id": 120,
  "tipo_persona": "natural",
  "tipo_identificacion": "13",
  "identificacion": "1020304050",
  "dv": null,
  "sucursal": 0,
  "nombre": "CLIENTE DE EJEMPLO",
  "nombre_comercial": null,
  "correo": "cliente@correo.com",
  "telefono": "3000000000",
  "direccion": "Calle 1 # 2-3",
  "ciudad": "11001",
  "responsable_iva": false,
  "roles": ["cliente"],
  "dias_credito": 0,
  "activo": true
}

ciudad es el código DANE del municipio (por ejemplo 11001 para Bogotá).

GET/terceros/{id}

Devuelve un tercero con la misma forma del listado.

POST/terceros

Crea un tercero. Requiere permiso de Lectura y escritura. Responde 201 con el tercero creado, o 422 si ya existe uno con la misma identificación.

curl -X POST "https://nube.nubicta.online/api/v1/terceros" \
  -H "Authorization: Bearer TU_LLAVE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"tipo_persona":"natural","tipo_identificacion":"13","identificacion":"1020304050","nombres":"Ana","apellidos":"Gómez","correo":"ana@correo.com","ciudad":"11001"}'

GET/productos

Lista productos y servicios ordenados por código.

{
  "id": 45,
  "codigo": "P001",
  "nombre": "PRODUCTO DE EJEMPLO",
  "tipo": "Producto",
  "referencia": null,
  "codigo_barras": null,
  "unidad": "Unidad",
  "inventariable": true,
  "existencias": 12,
  "iva_incluido": true,
  "precios": [{ "lista_precio_id": 1, "valor": 98000 }],
  "impuestos": [{ "nombre": "IVA 5%", "porcentaje": 5 }],
  "activo": true
}

GET/productos/{id}

Devuelve un producto con la misma forma del listado.

GET/facturas

Lista facturas de venta (FV), notas crédito (NC) y notas débito (ND), de la más reciente a la más antigua.

curl -H "Authorization: Bearer TU_LLAVE" \
  "https://nube.nubicta.online/api/v1/facturas?tipo=FV&desde=2026-10-01&hasta=2026-10-31"

{
  "id": 2301,
  "tipo": "FV",
  "numero": "FV-1-1001",
  "fecha": "2026-10-16",
  "vencimiento": "2026-10-31",
  "cliente": { "identificacion": "1020304050", "nombre": "CLIENTE DE EJEMPLO" },
  "subtotal": 93333.33,
  "descuento": 0,
  "impuestos": 4666.67,
  "retenciones": 0,
  "total": 98000,
  "saldo": 0,
  "cufe": "c1f0...",
  "estado_dian": "Accepted",
  "anulada": false
}

estado_dian puede ser Accepted (aceptado), Rejected (rechazado), Pending (en cola), Draft (sin enviar) o null si el documento no es electrónico.

GET/facturas/{id}

Devuelve el documento con sus ítems:

{
  "id": 2301,
  "numero": "FV-1-1001",
  "...": "los mismos campos del listado",
  "items": [
    { "codigo": "P001", "descripcion": "PRODUCTO DE EJEMPLO", "cantidad": 1, "precio": 93333.33, "descuento": 0, "iva": 5, "total": 98000 }
  ]
}

Buenas prácticas

• Guarda la llave en el servidor de tu plataforma, nunca en el navegador ni en una aplicación móvil.
• Usa una llave de Solo lectura si tu integración solo consulta información.
• Antes de crear un tercero, búscalo con ?identificacion= para no duplicarlo.
• Si sospechas que la llave se filtró, genera una nueva: la anterior queda revocada al instante.

La API es parte del código abierto de Nubicta con licencia MIT y se entrega "tal cual". La información que consultas o creas es de tu empresa; Nubicta no la usa para otros fines.