Verificar NIT
/api/v1/codigos/nitConsulta el estado de un NIT ante SIAT usando la integración activa y el UUID del punto de venta local.
X-API-KeyVer operaciones de Códigos fiscales Contrato de la operación
Consulta el estado de un NIT ante SIAT usando la integración activa y el UUID del punto de venta local.
Autorización y cuerpo
Requiere X-API-Key con permiso codigos.consultar. No usa Bearer, X-Tenant-ID ni Idempotency-Key. puntoVentaId es el UUID obligatorio de un punto y sucursal activos de la empresa de la clave. El backend deriva sucursal, código SIAT y CUIS del punto en el ambiente de la clave. nit debe ser un entero positivo.
El campo anterior codigoPuntoVenta ya no se acepta y no hay punto predeterminado. Consulta [migracion.md](migracion.md). El NIT consultado puede ser el del cliente o proveedor; no sustituye el NIT emisor de la empresa ni cambia el alcance de la clave. Un resultado valido: true tampoco aprueba una solicitud de acceso como proveedor tercero.
Respuestas
200 OK se devuelve incluso cuando el NIT no es válido; revisa valido y mensaje. 400 indica cuerpo o NIT inválidos; 401 y 403, una clave inválida o sin permiso; 404, UUID vacío/ inválido, punto ajeno, inexistente o no activo; 422, una integración SIAT no disponible para la sucursal; 503, indisponibilidad temporal del SIAT.
Si el punto no tiene CUIS vigente, el backend obtiene uno bajo bloqueo por empresa, punto y ambiente antes de consultar el NIT. No utiliza el CUIS de otra sucursal.
No envíes ni recibes Token Delegado, CUIS, certificados o contraseñas.
Ejemplo
Solicitud de ejemplo
{
"puntoVentaId": "{{puntoVentaId}}",
"nit": 123456789
}Respuesta
Ejemplo de respuesta
application/json{
"message": "verificación de NIT obtenida",
"data": {
"valido": true,
"nit": 1020304050,
"mensaje": "NIT válido"
}
}Datos ficticios; los identificadores y valores cambian en cada respuesta.