Catálogos SIAT

Consulta códigos oficiales sincronizados para emitir documentos fiscales sin exponer el NIT, ambiente ni credenciales SIAT en cada solicitud.

Comenzar integración Ver primer endpoint

Empezar

Primera consulta

Cuatro pasos desde la integración hasta una respuesta autenticada.

01
Configura SIAT
Registra y valida integración de empresa.
02
Crea una clave API
Concede los permisos catalogos.sincronizar y catalogos.consultar.
03
Sincroniza catálogos
Usa la clave para cargar los códigos oficiales.
04
Consulta
Envía clave mediante X-API-Key.

Seguridad

Autenticación

Cada clave fija empresa, ambiente, sucursal, punto de venta y permisos. No envíes X-Tenant-ID ni el token delegado.

Protege la clave

Úsala sólo desde backend. Nunca la publiques en navegador, aplicación móvil, repositorio o logs.

URL base

Base URL

https://staging-api.falmus.com/api/v1

Cabecera requerida

HTTP

X-API-Key: flm_test_TU_CLAVE

POST/api/v1/catalogos-siat/consultas

Consultar catálogo

Consulta un catálogo o todos los catálogos locales de la empresa. No consume SIAT durante lectura.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
catalogo	string	No	Usa todos u omítelo para paginar el conjunto completo.
page	integer	No	Página desde 0. Valor inicial: 0.
size	integer	No	Resultados por página. Máximo: 100.
filters.codigo	string	No	Coincidencia parcial por código.
filters.descripcion	string	No	Coincidencia parcial sin distinguir mayúsculas.
filters.codigoActividad	string	No	Código exacto de actividad económica.

JSON · cuerpo de solicitud

{
  "catalogo": "todos",
  "page": 0,
  "size": 50,
  "filters": {}
}

Respuesta 200

{
  "data": {
    "content": [
      {
        "codigo": "83131",
        "descripcion": "SERVICIOS DE CONSULTORÍA EN TI",
        "catalogo": "productos_servicios",
        "codigoActividad": "620100"
      }
    ],
    "page": 0,
    "size": 50,
    "totalElements": 1,
    "totalPages": 1,
    "syncedAt": "2026-08-22T10:00:00Z"
  }
}

POST/api/v1/catalogos-siat/sincronizar

Sincronizar catálogos

Descarga todos los catálogos o sólo el catálogo que necesitas para el contexto de la clave.

Permiso adicional

La clave debe incluir catalogos.sincronizar. También determina ambiente, empresa, sucursal y punto de venta.

JSON · cuerpo de solicitud

{
  "catalogo": "productos_servicios"
}

Omite el cuerpo para sincronizar todos los catálogos. Una sincronización específica sólo reemplaza ese catálogo. Las ejecuciones concurrentes se rechazan. Máximo: 5 solicitudes por minuto por clave.

GET/api/v1/catalogos-siat/estado

Estado de catálogos

Muestra disponibilidad y última sincronización del contexto definido por la clave.

cURL

curl 'https://staging-api.falmus.com/api/v1/catalogos-siat/estado' \
  -H 'X-API-Key: flm_test_TU_CLAVE'

Respuesta 200

{
  "data": {
    "syncedAt": "2026-08-22T10:00:00Z",
    "totalRecords": 588,
    "catalogs": [
      "actividades",
      "metodos_pago",
      "productos_servicios"
    ]
  }
}

Referencia

Catálogos disponibles

Envía estos identificadores en snake_case dentro de filters.catalogo. El backend también normaliza camelCase; usa los valores exactos de esta lista.

actividadesactividades_documento_sectorleyendas_facturamensajes_serviciosproductos_servicioseventos_significativosmotivos_anulacionpaises_origentipos_documento_identidadtipos_documento_sectortipos_emisiontipos_habitacionmetodos_pagomonedastipos_punto_ventatipos_facturaunidades_medida

Contrato

Errores

Los errores usan application/problem+json e incluyen traceId para soporte.

Estado	Código	Cuándo ocurre
400	invalid_request	Catálogo o cuerpo inválido.
401	authentication_required	Clave ausente, inválida, vencida o revocada.
404	resource_not_found	Catálogo todavía no sincronizado.
429	rate_limit_exceeded	Límite temporal de solicitudes excedido.
500	internal_error	Fallo no esperado. Reporta traceId.

Reintentos seguros

Reintenta sólo 429 y 5xx con espera exponencial y variación aleatoria. Estas lecturas no requieren Idempotency-Key.