Registrar punto de venta
/api/v1/sucursales/:branchId/puntos-ventaRegistra un punto de venta ante SIAT y conserva sólo su código oficial en Falmus. Antes de llamar al servicio, Falmus reserva el registro local para impedir altas duplicadas durante el procesamiento; nunca expone CUIS ni Token Delegado.
X-API-KeyVer operaciones de Sucursales y puntos de venta Contrato de la operación
Registra un punto de venta ante SIAT y conserva sólo su código oficial en Falmus. Antes de llamar al servicio, Falmus reserva el registro local para impedir altas duplicadas durante el procesamiento; nunca expone CUIS ni Token Delegado.
Autorización y ruta
Requiere únicamente X-API-Key con permiso sucursales.administrar; no usa Bearer, X-Tenant-ID ni Idempotency-Key. branchId es el UUID devuelto al consultar las sucursales y debe pertenecer a la empresa asociada a la clave. El servidor resuelve internamente el código SIAT de sucursal. La integración activa debe corresponder a esa sucursal.
Cuerpo y tipos
nombre (máximo 160 caracteres), descripcion (máximo 300) y tipoSiat son obligatorios. Para los tipos estándar, tipoSiat admite valores de 2 a 6 y sólo requiere esos tres campos.
El tipo 1 es exclusivamente punto de venta comisionista. Además exige nitComisionista numérico de 5 a 15 dígitos, numeroContrato (máximo 120 caracteres), fechaInicio y fechaFin en formato YYYY-MM-DD; la fecha final no puede ser anterior a la inicial. Falmus usa internamente el NIT del comitente, la modalidad, el CUIS y el Token Delegado. No envíes codigoPuntoVenta, CUIS, Token Delegado ni el NIT del comitente.
Respuestas
201 Created confirma el punto de venta con estado activo y codigoPuntoVenta. Si el CUIS fue invalidado por el SIAT, la primera solicitud autenticada regenera automáticamente un CUIS y continúa la operación. 400 indica UUID, campos o contrato inválidos; 401 o 403, una clave API inválida o s...
Ejemplo
Solicitud de ejemplo
{
"nombre": "CLIENTE DE DEMOSTRACIÓN",
"descripcion": "Atención externa",
"tipoSiat": 5,
"nitComisionista": 1017703021,
"numeroContrato": "CON-2026-001",
"fechaInicio": "2026-08-24",
"fechaFin": "2026-12-31"
}Reemplaza el valor por un UUID v4. Conserva la misma clave al reintentar; usa una nueva para otra operación.
Respuesta
Ejemplo de respuesta
application/json{
"message": "punto de venta registrado correctamente",
"data": {
"id": "00000000-0000-4000-8000-000000000022",
"codigoPuntoVenta": 1,
"nombre": "Caja rápida",
"descripcion": "Caja principal",
"tipoSiat": 5,
"tipoSiatDescripcion": "Punto de venta comisionista",
"estado": "activo",
"creadoEn": "2026-08-30T16:10:00-04:00",
"actualizadoEn": "2026-08-30T16:10:00-04:00"
}
}Datos ficticios; los identificadores y valores cambian en cada respuesta.